IDMPlot3 Interface

Version: 3.1
Dispatch interface for DMPlot Object

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

Use this interface to obtain access to the DM2003 graphics engine. Methods and properties of IDMPlot3 allows you to manipulate axes, labels and series objects, as well as perform editing operations, control selection area and reaction on the mouse events.

Although IDMPlot3 looks like usual collection of series objects, accessible through Series() array, it has one specific feature, namely CurrentSerie. It was found to be very convenient to perform operations on a single serie object at a time. This is because plot serie itself is a complex object, in contradistinction from characters in the text editor or strings in regular collections.

Members:
Kind Name ID Description
SerieCount 1 Return Series.Count
SerieIndex 2 Change Plot.SerieIndex
CurrentSerie 3 Return Serie object for current serie
XAxis 4 Return Axis object for X axis
YAxis 5 Return Axis object for Y axis
SelectionTop 6 Change Plot.SelectionTop
SelectionBottom 7 Change Plot.SelectionBottom
SelectionLeft 8 Change Plot.SelectionLeft
SelectionRight 9 Change Plot.SelectionRight
CopyToClipboard 10 Invoke TPlot.CopyToClipboard()
Delete 11 Invoke TPlot.Delete()
Select 12 Set plot selection
AddSerie 13 Create new plot serie
Series 14 Return Serie object for selected serie
SwapSeries 101 Swap order of two plot series
DeleteSerie 102 Delete plot serie
XAxis2 103 Return Axis object for X axis 2
YAxis2 104 Return Axis object for Y axis 2
Color -501 Change plot color
MouseMode 105 Change TPlot.MouseMode
SelectionVisible 106 Change TPlot.SelectionVisible
CanUndoZoom 107 True if undo zoom is possible
UndoZoom 108 Undoes last zoom operation
Save 109 Save plot page to disk file as metafile
Print 110 Print plot page
Document 111 Returns owner document object
_NewEnum -4 Return Series enumerator object
Labels 112 Return Labels collection
CanPaste 113 True if clipboard has serie or/and label objects
PasteFromClipboard 114 Paste serie or/and label objects
MarginTop 201 Distance in pixels between plot axes frame and top
MarginBottom 202 Distance in pixels between plot axes frame and bottom
MarginLeft 203 Distance in pixels between plot axes frame and left
MarginRight 204 Distance in pixels between plot axes frame and right
AutoSizeMargins 205 If true, Plot Margins calculated automatically
AutoScaleLabels 206 If true, labels can participate in axis autoscaling
ClipPoints 207 If true, data points are clipped by axes frame
AreaSeries 208 If true, area stack is mixed with series
Refresh 209 Updates plot when data are changed
SetMargins 210 Set all 4 plot margins and clear AutoMargins mode
Picture 211 Returns plot image as EMF

Syntax:
r/o property SerieCount: Long

Applies to:
DMPlot

Returns number of series in Series array.

Syntax:
property SerieIndex: Long

Applies to:
DMPlot

Like one of document windows is active, one of plot series is current. Current serie displayed in serie toolbar and most of UI operations act on the current serie. This property allows you to change index of current serie programmatically (series are indexed from 0 to SerieCount-1).

Syntax:
r/o property CurrentSerie: IDispatch

Applies to:
DMPlot

This property returns current serie object; it is equal to Series[SerieIndex]. Note that CurrentSerie may be nil if SerieIndex<0 or SerieCount=0.

Syntax:
r/o property XAxis: IDispatch

Applies to:
DMLabel, DMPlot, DMSerie

For DMPlot, XAxis returns reference to the DMAxis object that represents bottom plot axis.

For DMSerie and DMLabel, XAxis property returns reference to the DMAxis object and allows you to change horizontal axis associated with given label or series (which is used to introduce coordinate system for rendering series points or label object).

Example:

dim Plt
set Plt=Server.ActiveDocument.Plot
Plt.CurrentSerie.XAxis=Plt.XAxis2
Plt.Labels(0).XAxis=Plt.XAxis2

Syntax:
r/o property YAxis: IDispatch

Applies to:
DMLabel, DMPlot, DMSerie

For DMPlot, YAxis returns reference to the DMAxis object that represents left plot axis.

For DMSerie and DMLabel, YAxis property returns reference to the DMAxis object and allows you to change vertical axis associated with given label or series (which is used to introduce coordinate system for rendering series points or label object).

Example:

dim Plt
set Plt=Server.ActiveDocument.Plot
Plt.CurrentSerie.YAxis=Plt.YAxis2
Plt.Labels(0).YAxis=Plt.YAxis2

Syntax:
property SelectionTop: Double

Applies to:
DMPlot, DMWorksheet

For DMPlot, this property is a double-precision coordinate of the top of the plot selection area.

For DMWorksheet, this property is an integer position of the top line in the selected block of cells, or the vertical position of the selected cell.

Syntax:
property SelectionBottom: Double

Applies to:
DMPlot, DMWorksheet

For DMPlot, this property is a double-precision coordinate of the bottom of the plot selection area.

For DMWorksheet, this property is an integer position of the bottom line in the selected block of cells, or the vertical position of the selected cell.

Syntax:
property SelectionLeft: Double

Applies to:
DMPlot, DMWorksheet

For DMPlot, this property is a double-precision coordinate of the left of the plot selection area.

For DMWorksheet, this property is an integer position of the left column in the selected block of cells, or the horizontal position of the selected cell. Note that columns are counted from 1!

Syntax:
property SelectionRight: Double

Applies to:
DMPlot, DMWorksheet

For DMPlot, this property is a double-precision coordinate of the right of the plot selection area.

For DMWorksheet, this property is an integer position of the right column in the selected block of cells, or the horizontal position of the selected cell. Note that columns are counted from 1!

Syntax:
function CopyToClipboard(Mode, UseTabs): VOID

Applies to:
DMLabel, DMNotes, DMPlot, DMSerie, DMWorksheet

For DMNotes, this method copies selected text on the clipboard as in any text editor.

For DMPlot, CopyToClipboard has a parameters. Mode parameter determine what data will be copied; possible values listed in the PlotCopyModes enumeration. UseTabs parameter defines what character will be used as separator between values: some programs can correctly paste values only if they are separated by tabstop character. Keep in mind that CopyToClipboard acts only on the data in the current plot serie, and only points whose coordinates are within the selection area are copied. If plot selection is not visible, all points or data elements are copied.

For both DMSerie and DMLabel, properties of the object are copied in the special binary format.

For DMWorksheet, it copies selected worksheet cells to the clipboard as a simple text block. UseTabs parameter also defines what character will be used as separator between values. It also puts selection data range as a serie object.

You can use system Clipboard Viewer utility to investigate what data formats are used at every case.

Syntax:
function Delete: VOID

Applies to:
DMIniFile, DMLabel, DMNotes, DMPlot, DMRegistry, DMSerie, DMWorksheet

For DMRegistry and DMINIFile, Delete method deletes selected Value (or INI file section). Name parameter is either name or index in the Items collection. If object was opened in the Read-Only mode, Delete call will have no effect.

For DMNotes, DMPlot and DMWorksheet objects Delete method has no parameters and should be used to delete selected data range in the appropriate objects: selected text, worksheet cells or "selected" points (points whose coordinates belong to selected plot area) in the current plot serie. Note that for DMPlot, if selection is not visible, all points from the current plot serie will be deleted.

For DMSerie and DMLabel, this method just deletes the object. It acts as the appropriate method of owner collection (DMPlot or DMLabels).

Syntax:
function Select(X1, X2, Y1, Y2): VOID

Applies to:
DMLabel, DMNotes, DMPlot, DMSerie, DMWorksheet

For DMNotes object, this method should be used to select text in the editor. SelStart and SelEnd parameters are first and last character positions.

For DMPlot object, Select() changes numeric (double precision) coordinates of the plot selection area. This area may be visualized using SelectionVisible property and affects on some plot editing commands.

For DMWorksheet, this method defines integer coordinates of the worksheet selection. Left and Right ranges are (1..26), Top and Bottom are (0..Container.ItemCount-1).

For DMSerie, Select() has almost the same meaning as for DMWorksheet. Columns are ranged from 1 to 26, lines - from 0 to Container.ItemCount-1. However, XCol and YCol must represent valid data, that is, all items in the selected data range must have appropriate number of columns.

For DMLabel, this method allows you programmatically select label object. Notice that Select() has no effect until IDMPlot2.MouseMode<>pmmLabelEdit.

Syntax:
function AddSerie: IDispatch

Applies to:
DMPlot

Adds a new DMSerie object to the end of Series() array and return reference to this object.

Syntax:
r/o property Series[Index]: IDispatch

Applies to:
DMPlot

Read-only array of DMSerie objects. Index parameter ranges from 0 to SerieCount-1. This property gives you "random access" to plot series.

You also may iterate "for each" cycle on DMPlot object as shown in the example below.

Example:

set Plt=Server.ActiveDocument.Plot
for I=0 to Plt.SerieCount-1
  Plt.Series(I).Text="My serie #" & I
next

or

for each Ser in Server.ActiveDocument.Plot
  Ser.Text="My serie"
next

Syntax:
function SwapSeries(Serie1, Serie2): VOID

Applies to:
DMPlot

Exchanges two series objects in the Series() array. Serie1 and Serie2 parameters are indices of appropriate serie objects (ranged from 0 to SerieCount-1).

Syntax:
function DeleteSerie(Serie): VOID

Applies to:
DMPlot

Deletes selected serie object. Serie parameter is a numeric index in the Series() array.

Syntax:
r/o property XAxis2: IDispatch

Applies to:
DMPlot

Syntax:
r/o property YAxis2: IDispatch

Applies to:
DMPlot

Syntax:
property Color: User_Defined

Applies to:
DMAxis, DMComboBox, DMDigitizer, DMExpressionComboBox, DMFloatEdit, DMLabel, DMListBox, DMPlot, DMSerie, DMSpinEdit, DMWorksheet

This property should be used to change color of the selected object.

Syntax:
property MouseMode: User_Defined

Applies to:
DMDigitizer, DMPlot

MouseMode property for DMDigitizer control select one of the following Digitizer modes: Draw axes frame, Add, Delete or Edit points. Only subset of constants listed in PlotMouseModes enumeration is supported.

For DMPlot, all constants except pmmAddPoints are valid. Use this property to set plot reaction on the mouse clicks programmatically.

Syntax:
property SelectionVisible: Boolean

Applies to:
DMPlot

Use this property to show or hide plot selection. Plot selection is a rectangular area, indicated by the special frame. Set MouseMode=pmmSelect to change selection coordinates visually, or use Select() method or change SelectionXXX properties. Plot selection used in many operations on the series data.

Syntax:
function CanUndoZoom: Boolean

Applies to:
DMPlot

This method returns True if UndoZoom operation for given DMPlot object is possible. Use it to monitor controls associated with the "Undo Zoom" command.

Syntax:
function UndoZoom: VOID

Applies to:
DMPlot

UndoZoom method restores plot coordinates changed by mouse zooming operation. Note that only axes associated with current serie are affected.

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:
function Print: VOID

Applies to:
DMPlot

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

Syntax:
r/o property Labels: IDispatch

Applies to:
DMPlot

Labels property provides access to the Labels collection of DMLabel objects. Unlike series, you should manipulate individual plot labels using members of this collection.

Syntax:
function CanPaste: Boolean

Applies to:
DMApplication, DMDigitizer, DMInternalApplication, DMLabel, DMNotes, DMPlot, DMSerie, DMWorksheet

CanPaste method returns True if clipboard has valid data for PasteFromClipboard method. Use it to monitor controls associated with "Paste" command. Notice: for IDMApplication3 interface, this method has a parameter whose value allows to test whether desirable clipboard format is available.

Syntax:
function PasteFromClipboard(Mode): VOID

Applies to:
DMDigitizer, DMLabel, DMNotes, DMPlot, DMSerie, DMWorksheet

For DMDigitizer, this method inserts into the digitizer control the picture from the clipboard.

For DMNotes, PasteFromClipboard operates like in any text editor.

For DMSerie, PasteFromClipboard has a parameter. If DataOnly=True, visual attributes like colors, point size etc. are not assigned. Keep in mind that this method can correctly paste only series copied from the same instance of DM, because it performs search to assign Container.

For DMLabel, this method is just a pair for CopyToClipboard. In addition, Rectangle - type label can paste (and display) metafiles (and bitmaps).

For DMPlot, PasteFromClipboard has Mode parameter that determines what data will be pasted; possible values defined in the PlotCopyModes enumeration. Certainly, only series and labels (or both) may be pasted; new objects are created and initialized by data from the clipboard.

For DMWorksheet, this method also has a parameters. Text in the clipboard must contain lines of values separated by spaces, commas or tabstops. Data is pasted from topleft selected cell. If InsertLines is true, new lines will be added, else existing lines will be modified according to second parameter. If Overwrite mode specified, cell contents are replaced else data from clipboard will be inserted at selected position.

For all objects, this method does nothing if there's no suitable data on the clipboard. Use CanPaste method to determine whether clipboard has appropriate data formats.

Syntax:
property MarginTop: Long

Applies to:
DMPlot

Syntax:
property MarginBottom: Long

Applies to:
DMPlot

Syntax:
property MarginLeft: Long

Applies to:
DMPlot

Syntax:
property MarginRight: Long

Applies to:
DMPlot

Syntax:
property AutoSizeMargins: Boolean

Applies to:
DMPlot

Property AutoSizeMargins determines whether axes positions are calculated programmatically (depend on label size and visibility) or defined manually by MarginXXX properties.

Syntax:
property AutoScaleLabels: Boolean

Applies to:
DMPlot

Syntax:
property ClipPoints: Boolean

Applies to:
DMPlot

Syntax:
property AreaSeries: Boolean

Applies to:
DMPlot

If AreaSeries property is set to True, DMPlot object paints series area (if any) just before appropriate series, so that the area stack is mixed with series. Otherwise, plot paints all areas first, then series.

Syntax:
function Refresh: VOID

Applies to:
DMPlot, DMWorksheet

Updates an object (DMPlot or DMWorksheet). Unlike IDMContainer.Modified property, Refresh does not update all objects that are linked to the container.

Examples:

' refresh plot after data changes
for i=0 to 15
  d=Server.ActiveDocument.Container.Items(i)
  d(1)=d(0)
  Server.ActiveDocument.Container.Items(i)=d
next
Server.ActiveDocument.Plot.Refresh

' refresh worksheet after data changes
set doc=Server.CreateDocument("")
doc.WindowState=0
for i=1 to 15
  d=Array(i, 2*i)
  doc.Container.AddItem(d)
next
doc.Worksheet.Refresh

Syntax:
function SetMargins(Left, Right, Top, Bottom): VOID

Applies to:
DMPlot

Syntax:
r/o property Picture: PTR

Applies to:
DMLabel, DMPlot

This property gives you access to an image displayed by DMPlot and DMLabel objects. It returns reference to the special IPictureDisp interface pointer (IPicture interface also is available). See Microsoft OLE documentation for more details on these interfaces.

Warning! An automation server cannot pass a pointer to the picture object's IPictureDisp implementation across process boundaries (see KB150034). This behavior is by design.

You can use Picture property to programmatically add elements of multimedia on your graphs. For example, imagine that you make a measurement of a signal from the sample, plot this signal and insert an image of the sample from your USB microscope on the plot as a graphical annotation! Also you can make composite plots, or just assign Picture property to the appropriate properties of another ActiveX controls (such as Microsoft Forms Image control).

Examples:

' assign label picture:
set doc=Server.CreateDocument("")
doc.WindowState=1
set lbl=doc.Plot.Labels.AddItem
lbl.LabelKind=pltRectangle
lbl.XMin=doc.Plot.XAxis.Min
lbl.YMin=doc.Plot.YAxis.Min
lbl.XMax=doc.Plot.XAxis.Max/2
lbl.YMax=doc.Plot.YAxis.Max/2
lbl.Picture=doc.Plot.Picture

' clear label picture assigned above:
set Server.ActiveDocument.Plot.Labels(0).Picture=Nothing

' load file using VBScript LoadPicture() function:
wnd.Plot.Labels(0).Picture=LoadPicture("c:\path\1.gif")