IDMSerie3 Interface

Version: 3.1
Dispatch interface for DMSerie Object

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

This interface provides access to the plot series objects.

Members:
Kind Name ID Description
IsRecording 1 Change TDataForm.IsRecordingSerie[]
IsFunction 2 Change TSerie.IsFunction
IsEmpty 3 Return TSerie.Empty
ClearSelection 4 Invoke TSerie.ClearBlock()
XColumn 5 Change TSerie.XColumn
YColumn 6 Change TSerie.YColumn
FirstLine 7 Change TSerie.FirstLine
LastLine 8 Change TSerie.LastLine
Select 9 Set serie block (container data range)
XExpression 10 Change TSerie.XExpression
YExpression 11 Change TSerie.YExpression
Text 12 Change TSerie.Text
Container 13 Change TSerie.Container
AddPoint 14 Add and draw point without plot refresh
GetPoint 15 Return X,Y coordinates with all calculations
CopyToClipboard 101 Copies serie object to the clipboard
PasteFromClipboard 102 Paste serie object from the clipboard
CanPaste 103 True if clipboard has serie object
XAxis 104 Change X axis (top or bottom)
YAxis 105 Change Y axis (left or right)
Min 106 Change TSerie.PMin
Max 107 Change TSerie.PMax
IsVisible 108 Control serie visibility
PointVisible 109 Change points visibility
LineVisible 110 Change line visibility
PointType 111 Change points type
PointSize 112 Change point size
LineType 113 Change line type
LineWidth 114 Change line width
Color -501 Change pen color
PointColor 115 Change brush color
Document 116 Returns owner document object
LeaderPosition 201 Changes Leader (point marker) position
LeaderSize 202 Changes Leader (point marker) size
BrushType 203 Changes series brush style
ErrorBarXColumn 204 Changes X error bar column
ErrorBarYColumn 205 Changes Y error bar column
ErrorBarLength 206 Changes relative error bar size (1-point size)
AreaBorder 207 Changes series area border object (axis or another series)
EnableGetPointEvent 208 If true, OnPlotGetPoint event invoked for this series
Delete 209 Deletes series object
Activate 210 Makes series object active, or current
Move 211 Changes position in the list of series
SendToBack 212 Makes series first in the list
BringToFront 213 Makes series last in the list
InvalidateCache 214 Clears series point cache
IsCacheEnabled 215 If true, series uses cache for faster drawing
Interleave 216 Increase interleave to draw series faster
ItemIndex 217 Position of series object in the list
AssignObject 218 Copies all attributes from the given series

Syntax:
property IsRecording: Boolean

Applies to:
DMDocument, DMSerie

For DMDocument, this property indicates whether appropriate data window is in the "recording" state, that is, used for recording data from the measurement system (or for another real-time data streaming). Such window has a thick colored frame. Besides, "recording" data window is not only a visual feedback - it doesn't refresh plot when you set Container.Modified=true, and doesn't refresh Series Manager when you set Container.Modified=false (although worksheet updates its size). This feature should be used to eliminate flickers and significantly increase data streaming rates (and reduce CPU load). In addition, value of this property analyzed in the IDMApplication.RecordPoint() method.

For DMSerie, this property reflects the fact that this series is used to display accumulated data. When it is set to True, a little cross is displayed at the last point. Set IsRecording property to indicate that you are adding points into this series.

Syntax:
property IsFunction: Boolean

Applies to:
DMSerie

If this property is true, the serie is functional, that is, it can display curve given by symbolic expression rather than numeric data. X and Y expressions depend on "cx" parameter, ranged from Min to Max.

In DM2003, when you set IsRecording=True, XExpression automatically initialized with "cx" value, Min and Max are set to the X axis range, number of points, line and point visibility flags also initialized for compatibility with DM2000.

Syntax:
r/o property IsEmpty: Boolean

Applies to:
DMSerie

Read this property to determine whether given serie is empty. Empty series are not displayed. Serie treated as empty if any components of the data range are not defined: for example, X, YColumn is 0 or LastLine is -1.

Use ClearSelection method to make the serie empty.

Syntax:
function ClearSelection: VOID

Applies to:
DMSerie

This procedure simply set XCol=YCol=FirstLine=0, LastLine=-1. Serie become "empty" and not displayed.

Syntax:
property XColumn: Long

Applies to:
DMSerie, DMWorksheet

For DMSerie, XColumn is a part of the serie's data range. It must be greater than 1; for functional series, however, it is not used and may be zero.

For DMWorksheet, this property determines what column is treated as "X". Unlike in spreadsheet processors, many operations in DM2003 require a range of lines and position of X and/or Y columns. As well as with UI, you can set these values programmatically.

Syntax:
property YColumn: Long

Applies to:
DMSerie, DMWorksheet

For DMSerie, YColumn is a part of the serie's data range. It must be greater than 1; for functional series, however, it is not used and may be zero.

For DMWorksheet, this property determines what column is treated as "Y". Unlike in spreadsheet processors, many operations in DM2003 require a range of lines and position of X and/or Y columns. As well as with UI, you can set these values programmatically.

Syntax:
property FirstLine: Long

Applies to:
DMSerie

This property determines index of the first data element in the DMContainer object associated with given serie. If FirstLine is less than 0 or greater than LastLine, data range of the serie is invalid and serie is not displayed.

For functional series, LastLine-FirstLine residual determines the number of intervals.

Syntax:
property LastLine: Long

Applies to:
DMSerie

This property determines index of the last data element in the DMContainer object associated with given serie. If LastLine is less than 0 or less than FirstLine, data range of the serie is invalid and serie is not displayed.

For functional series, LastLine-FirstLine residual determines the number of intervals.

Syntax:
function Select(XCol, YCol, First, Last): 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:
property XExpression: BSTR

Applies to:
DMSerie

Expressions allows you to transform your data "on-fly", and are of the most prominent features of DM2003 graphic engine. Besides, expressions are used in so-called "functional", or parameterized, series. See details about expression syntax and allowed arguments and function names.

Syntax:
property YExpression: BSTR

Applies to:
DMSerie

Expressions allows you to transform your data "on-fly", and are of the most prominent features of DM2003 graphic engine. Besides, expressions are used in so-called "functional", or parameterized, series. See details about expression syntax and allowed arguments and function names.

Syntax:
property Text: BSTR

Applies to:
B740X, DMComboBox, DMExpressionComboBox, DMFloatEdit, DMLabel, DMListBox, DMListItems, DMNotes, DMSerie, DMSpinEdit, DMStrings, E712X, HP4191X

For DMForms ActiveX controls (DMComboBox, DMExpressionComboBox, DMListBox, DMFloatEdit, DMSpinEdit) this property changes the text in the appropriate control.

For collection objects (DMListItems, DMStrings), this property represents the contents of the collection as a single block of text. Lines are separated by standard CRLF characters.

For DMNotes, this property also operates with the editor's data as a whole.

For DMSerie and DMLabel objects, Text is just a label.

For device driver ActiveX controls (HP4191X, B740X and E712X) this property should be used to read and write data from/to the device.

Syntax:
property Container: IDispatch

Applies to:
DMDigitizer, DMDocument, DMSerie

For DMDocument and DMSerie objects, Container property returns reference to the associated DMContainer object. Notice that for DMSerie object, this property is read/write, that is, you can assign to it container of any document.

For DMDigitizer, this property returns reference to the DMDigitizerContainer object, which is used only to store points coordinates.

Syntax:
function AddPoint: VOID

Applies to:
DMSerie

Syntax:
function GetPoint(Index, X, Y): VOID

Applies to:
DMSerie

Syntax:
function CopyToClipboard: 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 PasteFromClipboard(DataOnly): 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:
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:
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:
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 Min: Double

Applies to:
DMAxis, DMFloatEdit, DMSerie, DMSpinEdit

For DMAxis, Min define minimal value of the axis range. Note: if you want to fix axis range you have to clear AutoScale flag. Also keep in mind that in DM2003 Min may be greater than Max.

For DMSerie, this property allows you to change minimal limit of the parameter ("cx") for parameterized (or functional) series.

For DMSpinEdit and DMFloatEdit ActiveX controls, it defines minimal possible value of the Value property.

Syntax:
property Max: Double

Applies to:
DMAxis, DMFloatEdit, DMSerie, DMSpinEdit

For DMAxis, Max defines maximal value of the axis range. Note: if you want to fix axis range you have to clear AutoScale flag. Also keep in mind that in DM2003 Min may be greater than Max.

For DMSerie, this property allows you to change maximal limit of the parameter ("cx") for parameterized (or functional) series.

For DMSpinEdit and DMFloatEdit ActiveX controls, it defines maximal possible value of the Value property.

Syntax:
property IsVisible: Boolean

Applies to:
CoCPortLib2, CPortLibX2, DMAxis, DMClientSocket, DMComboBox, DMComPort, DMComTerminal, DMDigitizer, DMExpressionComboBox, DMFloatEdit, DMIEEE488Port, DMLabel, DMListBox, DMSerie, DMSpinEdit

IsVisible property determines whether appropriate object is visible on the screen. Note that for ActiveX controls embedded in the HTML page, you can also change Object.style.visibility property. Some controls like DMClientSocket, DMIEEE488Port and DMComPort are invisible by design and don't implement this property.

Syntax:
property PointVisible: Boolean

Applies to:
DMSerie

Syntax:
property LineVisible: Boolean

Applies to:
DMSerie

Syntax:
property PointType: User_Defined

Applies to:
DMSerie

This property determines point shape. Possible values listed in the PlotPointType enumeration.

Syntax:
property PointSize: Long

Applies to:
DMSerie

Syntax:
property LineType: User_Defined

Applies to:
DMLabel, DMSerie

This property determines line type. Possible values listed in the PlotLineType enumeration.

Syntax:
property LineWidth: Long

Applies to:
DMAxis, DMLabel, DMSerie

LineWidth property determines the width of object's line or contour.

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 PointColor: User_Defined

Applies to:
DMSerie

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:
property LeaderPosition: Long

Applies to:
DMSerie

LeaderPosition property allows you to change position of plot series leader - a small cross that marks some point and may be moved to another point without plot repaint. This feature is affected by IsRecording property: when it turns ON, Leader position moved to the last series point for compatibility with previous versions.

Syntax:
property LeaderSize: Long

Applies to:
DMSerie

This property allows to specify series leader size. Default value of 2 means that leader is 2 times bigger than point.

Syntax:
property BrushType: User_Defined

Applies to:
DMLabel, DMSerie

BrushType property allows you to set fill pattern for label backgrounds and series areas. Possible values of this property are listed in the BrushStyles Enumeration.

Syntax:
property ErrorBarXColumn: Long

Applies to:
DMSerie

ErrorBarXColumn property define column in the reference container for data series which is used as X error bar. Unlike data XColumn, error bar column is not required to be continious, so that you can define errors only for several points in the dataset. Also notice that zero values of error are just ignored.

Syntax:
property ErrorBarYColumn: Long

Applies to:
DMSerie

ErrorBarYColumn property define column in the reference container for data series which is used as Y error bar. Unlike data YColumn, error bar column is not required to be continious, so that you can define errors only for several points in the dataset. Also notice that zero values of error are just ignored.

Syntax:
property ErrorBarLength: Double

Applies to:
DMSerie

Property ErrorBarLength determines X and/or Y point error bar length relative to point size.

Syntax:
property AreaBorder: IDispatch

Applies to:
DMSerie

AreaBorder property used to define object that will be used as a border for series area filling. Another series or axis may serve as a border (as of build #414, line and arrow labels also are valid border objects).

Example:

sub test_ab
dim plt
  set plt=Server.ActiveDocument.Plot
  if plt.CurrentSerie.AreaBorder is Nothing then
    msgbox "Empty!"
  else
    if plt.CurrentSerie.AreaBorder is plt.XAxis then
      msgbox "XAxis title: " & plt.XAxis.Title
      exit sub
    end if
    if plt.CurrentSerie.AreaBorder is plt.YAxis then
      msgbox "YAxis title: " & plt.YAxis.Title
      exit sub
    end if
    if plt.CurrentSerie.AreaBorder is plt.XAxis2 then
      msgbox "XAxis2 title: " & plt.XAxis2.Title
      exit sub
    end if
    if plt.CurrentSerie.AreaBorder is plt.YAxis2 then
      msgbox "YAxis2 title: " & plt.YAxis2.Title
      exit sub
    end if
    ' series!
    msgbox plt.CurrentSerie.AreaBorder.Text
  end if
end sub

Syntax:
property EnableGetPointEvent: Boolean

Applies to:
DMSerie

Set EnableGetPointEvent property if you would like to calculate point coordinates yourself in your code. This method requires IDMApplicationEvents.OnPlotGetPoint event handler. Please keep in mind that comparing to other events, OnPlotGetPoint may be called much more frequently, so that time-consuming code in this event handler may seriously slow down plot painting.

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 Activate: VOID

Applies to:
DMDocument, DMSerie

Only one of MDI child windows may be active, that is, has input focus. For DMDocument, this procedure makes document window active. Note that activation can change index of document in the Documents property.

For DMSerie object, Activate just makes this series active, or current, by changing IDMPlot.SerieIndex property. Of course, its position in the Series array does not change.

Examples:

' DMDocument:
dim Doc
set Doc=Server.Documents(1)
Doc.Activate
' DMSerie:
Server.ActiveDocument.Plot.Series(2).Activate

Syntax:
function Move(Position): VOID

Applies to:
DMLabel, DMSerie

For DMLabel object, Move changes label coordinates. However, for DMSerie objects, this method changes its position in the list of plot series, so that order of series painting also changes.

Syntax:
function SendToBack: VOID

Applies to:
DMLabel, DMLabels, DMSerie

SendToBack method moves given object to the first position in the collection, so it is painted before other objects.

Syntax:
function BringToFront: VOID

Applies to:
DMLabel, DMLabels, DMSerie

BringToFront method moves given object to the last position in the collection, so it is painted after other objects.

Syntax:
function InvalidateCache: VOID

Applies to:
DMSerie

Procedure InvalidateCache clears point coordinates cache. It is called when point coordinates should be recalculated. For cached data series, you must call this procedure after you have changed data in the container. Also keep in mind that this procedure may be used if you generate point coordinates in OnPlotGetPoint event.

Syntax:
property IsCacheEnabled: Boolean

Applies to:
DMSerie

If this property is set to true, DMSerie object will try to cache point coordinates. This is especially useful for series with long expressions, when calculations may take a lot of time. Please notice that axis autoscaling feature does not use cache, so that you should disable it to get the most from point caching!

Syntax:
property Interleave: Long

Applies to:
DMSerie

Syntax:
property ItemIndex: Long

Applies to:
DMComboBox, DMExpressionComboBox, DMLabel, DMListBox, DMSerie

For a list controls in DMForms, this property may be used to change selected item in the list. For DM2003 collection items (series and labels) it represents the index of the item in the appropriate collection. This feature allows much more convienient manipulations with collection items.

Examples:

Doc.Plot.Series(0).ItemIndex=2
  is equal to:
Doc.Plot.Series(0).Move(2)
  and
Doc.Plot.Labels(1).SendToBack   
  is equal to:
Doc.Plot.Labels(1).ItemIndex=0

Syntax:
function AssignObject(Value): VOID

Applies to:
DMAxis, DMLabel, DMSerie, DMWorksheet

AssignObject method allows to quickly copy all properties of axis, series, label or worksheet. In the first 3 cases it is just a wrapper for appropriate VCL method; worksheet copies only those properties that affect visual appearance and may be changed (by user interface or programmatically). It is especially useful when you need to clone separate objects in the data window.

Notice that DMLabel object also can assign DMPlot objects, in this case rectangular label will display plot as a metafile.

Examples:

sub worksheet_assign_test
dim sw, dw
  if Server.DocumentCount=0 then exit sub
  set sw=Server.ActiveDocument
  set dw=Server.CreateDocument("")
  call dw.Worksheet.AssignObject(sw.Worksheet)
  dw.WindowState=0
end sub

sub axis_ser_lbl_assign_test
' note: source window must have series and labels!
dim sw, dw
  if Server.DocumentCount=0 then exit sub
  set sw=Server.ActiveDocument
  set dw=Server.CreateDocument("")
  call dw.Plot.XAxis.AssignObject(sw.Plot.XAxis)
  call dw.Plot.YAxis.AssignObject(sw.Plot.YAxis)
  dw.Plot.Series(0).AssignObject sw.Plot.Series(2)
  dw.Plot.Labels.AddItem.AssignObject sw.Plot.Labels(0)
  dw.WindowState=1
end sub

sub lbl_assign_plot_self
dim doc, lbl
  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.AssignObject doc.Plot
end sub