IDMContainer2 Interface

Version: 2.0
Dispatch interface for DMContainer Object

GUID: {673A9FD0-9A0B-11D4-B2A4-FD6847C75367}

Container objects used to store large, dynamically resized arrays of numeric data in the memory. You may not only add, delete or change individual data elements, but also perform complex operations like sorting and table calibration. This interface fully supports disk I/O operations. IDMContainer2 interface may be used as a collection in the "for..each" enumeration cycles.

Members:
Kind Name ID Description
ItemCount 1 Return Items.Count
Items 2 Change Items[I]
Strings 3 Change Items[I].Data
AddItem 4 Add new item initialized with array of numbers
InsertItem 5 Insert new item initialized with array of numbers
DeleteItem 6 Delete Item
Clear 7 Delete all items
Load 8 Load data from file
Save 9 Save data to file
FileName 10 Return FileName
Modified 11 Change Modified flag
Sort 101 Sort selected lines
Calibrate 102 Perform table calibration
KeyColumn 103 Returns calibration (and sorting) key column
Document 104 Returns owner document object
_NewEnum -4 Return Container Items enumerator object

Syntax:
r/o property ItemCount: Long

Applies to:
DMContainer, DMDigitizerContainer, DMLabels, DMListItems, DMStrings

ItemCount property returns number of elements in the Items parameterized property. Items are indexed from 0 to ItemCount-1 as shown in the example.

Example:

for I=0 to MyObject.ItemCount-1
  S=MyObject.Items(I)
next

Syntax:
property Items[Index]: Variant

Applies to:
DMComboBox, DMContainer, DMDigitizerContainer, DMExpressionComboBox, DMIniFile, DMLabels, DMListBox, DMListItems, DMRegistry, DMStrings

For DMINIFile, Items return either collection of INI file sections (if no section was defined in the Open method) OR the collection of names of records in the selected section. Use Value() property to access section contents (or Value) of the selected record. For DMRegistry, Items return the collection of names of the records (values) under the selected registry key.

Items collection filled in the Open method and is read-only. Don't try to change it anyway. Use Value() property to change values.

For DMComboBox, DMExpressionComboBox and DMListBox, Items represent a read/write collection of strings in the appropriate control.

For DMContainer and DMDigitizerContainer, Items is a parameterized property - an array of data items ("for each" cycle still can be performed on the object itself). Each data item is a variant array of double-precision numbers. Notice that for DMDigitizerContainer, you can only read Items. For DMContainer, you may assign either variant array OR just a properly formatted string to the Items() property.

For DMListItems and DMStrings, Items is a parameterized property that returns (or changes) a string selected by Index parameter (0..ItemCount-1).

For DMLabels collection, this is a default, parameterized (0..ItemCount-1) property that returns references to the DMLabel objects.

Syntax:
r/o property Strings[Index]: BSTR

Applies to:
DMContainer, DMDigitizerContainer

While Items() parameterized property always return elements as variant arrays, in some cases it may be preferred to get string representation of data element. However, values will be rounded that may cause precision losses.

Syntax:
function AddItem(Values): VOID

Applies to:
DMContainer, DMDigitizerContainer, DMLabels, DMListItems, DMStrings

AddItem method adds Value(s) element to the end of Items array (parameterized property). Note: for DMDigitizerContainer, this method is not implemented.

For DMLabels collection, it returns reference to the newly created DMLabel object.

Keep in mind that for DMContainer, you should set Modified property manually after you add container items. This will update all associated visual objects.

Examples:

set D=Server.CreateDocument("")
for I=1 to 100
  D.Container.AddItem(I & " " & I^2)
next
D.Container.Modified=true ' false also works

dim i, doc, ar(0,300)
'dim i, doc, ar(0) both commented and uncommented are ok!
set doc=DM2003.CreateDocument("")
for i=0 to 300
  ar(0,i)=i
'  ar(0)=i
'  doc.Container.AddItem(ar)
next
doc.Container.AddItem(ar) ' many lines at once
doc.Worksheet.Refresh

' text version (JS-compatible)
dim i, doc, str
set doc=DM2003.CreateDocument("")
for i=0 to 300
  str=str & i & vbCrLf
next
doc.Container.AddItem(str)
doc.Worksheet.Refresh

Syntax:
function InsertItem(Position, Values): VOID

Applies to:
DMContainer, DMDigitizerContainer, DMListItems, DMStrings

InsertItem method for collections (DMListItems and DMStrings) inserts Value in the Items array (parameterized property) at the position given by the Index parameter (0..ItemCount-1). To add element to the begin of Items array, you should pass Index=0. For DMContainer, this method inserts Values (variant array or string) in the selected Position of the Items array. For DMDigitizerContainer, this method is not implemented.

Note: for DMContainer, you should set Modified property manually after you insert container items. This will update all associated visual objects.

Example:

dim A(1)
set D=Server.CreateDocument("")
for I=1 to 100
  A(0)=I
  A(1)=I^2
  call D.Container.InsertItem(0, A)
next
D.Container.Modified=true

Syntax:
function DeleteItem(Position): VOID

Applies to:
DMContainer, DMDigitizerContainer, DMLabels, DMListItems, DMStrings

Deletes item in in the appropriate Items array (collection or parameterized property) at the position given by the Index (or Position) parameter (0..ItemCount-1).

Note: for DMContainer, you should set Modified property manually after you delete container items. This will update all associated visual objects.

Syntax:
function Clear: VOID

Applies to:
B740X, DMContainer, DMDigitizer, DMDigitizerContainer, DMLabels, DMListItems, DMNotes, DMStrings, E712X, HP4191X

For DMContainer and DMDigitizerContainer objects, Clear method empties the container and set Modified property to True.

For DMDigitizer, this method clears digitizer picture.

For DMListItems, DMNotes and DMStrings Clear also empties the contents of the appropriate Items (or Lines) arrays.

For HP4191X, B740X and E712X this method initialize appropriate device into some predefined state.

For DMLabels, this method deletes all plot labels.

Syntax:
function Load(FileName): VOID

Applies to:
DMContainer, DMDigitizer, DMDigitizerContainer, DMLabel, DMNotes

Load method allows you to load data from the disk file into the object. For DMContainer, text-type (ASCII) file must contain values separated by commas, tabstops or spaces. For DMDigitizerContainer, however, this method not supported. As of build #415, compressed data format (binary) was added.

DMDigitizer.Load should be used to load picture into the digitizer. DMNotes.Load just loads text into the Notes editor. DMLabel uses Load() member to copy images in various formats (ico, bmp, jpg, gif, png) into the metafile.

For DMContainer, DMLabel and DMNotes objects, this method also can handle HTTP and FTP URLs, so that you can download files located on the Internet/Intranet.

Syntax:
function Save(FileName): VOID

Applies to:
DMContainer, DMDigitizerContainer, DMNotes, DMPlot

Saves object's data to the selected disk file.

For DMContainer, values are separated by spaces, each item take a separate line. Modified property automatically cleared. In the DMDigitizerContainer object this method not implemented. As of build #415, compressed data format (binary) may be used - it depends on CompressDataFiles application option.

DMNotes object just writes editor's text to the disk. DMPlot object saves itself as a metafile picture.

Syntax:
r/o property FileName: BSTR

Applies to:
DMContainer, DMDigitizerContainer, DMNotes

Returns full name of loaded file. Note that Load() and Save() methods implicitly modify this property. If file still not loaded, this property returns empty string.

Example:

MsgBox Server.Notes.FileName
MsgBox Server.ActiveDocument.Container.FileName

Syntax:
property Modified: Boolean

Applies to:
DMContainer, DMDigitizerContainer, DMNotes

This property used to track data modifications.

For DMContainer, when data implicitly modified by some method or you directly set this property, object fires internal event which will correctly update all worksheets and plots referenced this container. It takes a lot of calculations and painting job so don't change this property too frequently.

Notice: when you set Modified=true, and appropriate document window is in "recording" state, plot is not forced to refresh. This feature allows you to refresh worksheet (actually you must set Modified in order to update number of lines in the worksheet!) without repainting whole plot.

You can additionally reduce painting if you set Modified=false while Document.IsRecordind=true. In this case, only worksheet size will be updated. This mode can significantly increase the rate of data streaming.

For DMNotes, this property indicates whether editor text is modified or not. For DMDigitizerContainer this property is not implemented.

Syntax:
function Sort(FirstLine, LastLine, KeyColumn, Descend): VOID

Applies to:
DMContainer

Peforms sorting of the selected range of lines of the container. Lines are sorted by the KeyColumn, sort order determined by the Descend boolean parameter.

Syntax:
function Calibrate(Value, Index): Double

Applies to:
DMContainer

Performs table calibration procedure. Container lines must be sorted prior to calibration. Value is the independent variable of the table function defined by the container data, Index (1..26) is the column number of the result.

Example:

dim R, T ' resistance of termometer, temperature
' calibration table layout: R - first column, T - second
' table sorted by first column, in the ascending order
T=Server.Table.Calibrate(R, 2) 

Syntax:
r/o property KeyColumn: Long

Applies to:
DMContainer

This property indicates which column was used as a key column in the Sort() method.

Syntax:
r/o property Document: IDispatch

Applies to:
DMAxis, DMContainer, DMLabel, DMPlot, DMSerie, DMWorksheet

Document property returns DMDocument object which is an owner of the given object. So that, you don't need to cycle through the object collections to determine the object's owner. Keep in mind that in DM, VCL objects may be destroyed while appropriate COM objects still alive since their lifecycle is governed by reference counting mechanism. Such COM objects with killed VCL owner become a "zombie" - they have no actual data, their methods do nothing and properties return empty data.

Examples:

sub TestSerie
dim Serie
  if Server.ActiveDocument is Nothing then
    MsgBox "NULL document"
  else
    set Serie=Server.ActiveDocument.Plot.CurrentSerie
    MsgBox Serie.Document.WindowCaption  
  end if
end sub

sub TestAxis
dim Axis
  set Axis=Server.ActiveDocument.Plot.XAxis2
  MsgBox Axis.Document.WindowCaption
end sub

sub TestContainer
dim Container
  set Container=Server.ActiveDocument.Container
  MsgBox Container.Document.WindowCaption
end sub

sub TestPlot
dim Plot
  set Plot=Server.ActiveDocument.Plot
  MsgBox Plot.Document.WindowCaption
end sub

sub TestWorksheet
dim Worksheet
  set Worksheet=Server.ActiveDocument.Worksheet
  MsgBox Worksheet.Document.WindowCaption
end sub

dim Worksheet1
set Worksheet1=Server.ActiveDocument.Worksheet

sub TestWorksheet1
  MsgBox Worksheet1.Document.WindowCaption
end sub

dim Serie1
set Serie1=Server.ActiveDocument.Plot.CurrentSerie

sub TestSerie1
  if Serie1.Document is Nothing then
    MsgBox "NULL document"
  else
    MsgBox Serie1.Document.WindowCaption  
  end if
end sub

Syntax:
r/o property _NewEnum: Unknown

Applies to:
DMApplication, DMContainer, DMInternalApplication, DMLabels, DMListItems, DMNotes, DMPlot, DMStrings

This property returns so-called Enumerator Object. Do not use it explicitly. It is used internally in the "for each [item] in [object]" cycles. Every object that has this property may be enumerated in such a cycles. This is for your convenience.

Examples:

function EnumDocuments
dim S
  S=""
  for each Doc in Server
    S=S & Doc.WindowCaption & vbCrLf
  next
  EnumDocuments=S  
end function

function EnumNotes
dim S
  S=""
  for each Ss in Server.Notes
    S=S & Ss & vbCrLf
  next
  EnumNotes=S  
end function

function EnumSeries
dim S
  S=""
  for each Ser in Server.ActiveDocument.Plot
    S=S & Ser.Text & vbCrLf
  next
  EnumSeries=S  
end function

function EnumItems
dim S
  S=""
  for each D in Server.ActiveDocument.Container
    S=S & D(0) & vbCrLf
  next
  EnumItems=S  
end function