IDMLabel2 Interface

Version: 3.1
Dispatch interface for DMLabel Object

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

IDMLabel2 interface provides access to the methods and properties of DMLabel object. You use this interface to change label text and position, read and modify its numerous visual attributes. In addition, you may copy or paste individual objects on the clipboard and programmatically select labels.

Members:
Kind Name ID Description
Text 0 Change label text
IsVisible 1 Control label visibility
LabelKind 2 Change visual label style
XAxis 3 Change X axis (top or bottom)
YAxis 4 Change Y axis (left or right)
XMin 5 Change TPlotLabel.X1 coordinate
XMax 6 Change TPlotLabel.X2 coordinate
YMin 7 Change TPlotLabel.Y1 coordinate
YMax 8 Change TPlotLabel.Y2 coordinate
Font -512 Change label font
LineType 9 Change label pen (line) type
LineWidth 10 Change label pen (line) width
Color -501 Change label pen (line) color
LabelColor 11 Change label background color
Document 12 Returns owner document object
CopyToClipboard 13 Copies label object to the clipboard
PasteFromClipboard 14 Paste label object from the clipboard
CanPaste 15 True if clipboard has label object
Select 16 Selects label (in label edit mode only)
Move 17 Changes label coordinates
FontColor 201 Changes label font color
Transparent 202 If true, label has transparent background
BeforeData 203 If true, label is painted before data series
BrushType 204 Changes label brush style
Alignment 205 Changes label text alignment
PinModeXMin 206 Changes TPlotLabel.PinModeX1
PinModeXMax 207 Changes TPlotLabel.PinModeX2
PinModeYMin 208 Changes TPlotLabel.PinModeY1
PinModeYMax 209 Changes TPlotLabel.PinModeY2
SendToBack 210 Makes the label beneath others
BringToFront 211 Makes the label topmost
Delete 212 Deletes label
AssignObject 213 Copies all attributes from the given label
Load 214 Loads image into square-type label from file
ItemIndex 215 Position of label object in the list of labels
Picture 216 Picture (EMF) for square-type label

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

Applies to:
DMLabel

This property determines label kind. Possible values are listed in the PlotLabelType enumeration.

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 XMin: Double

Applies to:
DMDigitizer, DMLabel

Syntax:
property XMax: Double

Applies to:
DMDigitizer, DMLabel

Syntax:
property YMin: Double

Applies to:
DMDigitizer, DMLabel

Syntax:
property YMax: Double

Applies to:
DMDigitizer, DMLabel

Syntax:
property Font: PTR

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

This property should be used to change font of the selected object. It returns reference to the special IFontDisp interface pointer. See Microsoft OLE documentation for more details.

Example:

 
Server.ActiveDocument.Worksheet.Font.Name
Server.ActiveDocument.Worksheet.Font.Size
Server.ActiveDocument.Worksheet.Font.Bold
Server.ActiveDocument.Worksheet.Font.Italic
Server.ActiveDocument.Worksheet.Font.Underline
Server.ActiveDocument.Worksheet.Font.Strikethrough
Server.ActiveDocument.Worksheet.Font.Weight
Server.ActiveDocument.Worksheet.Font.Charset
Server.ActiveDocument.Worksheet.Font.Color 'absent!

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

Applies to:
DMLabel

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:
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: 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:
function Select: 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 Move(XMin, YMin, XMax, YMax): 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:
property FontColor: User_Defined

Applies to:
DMAxis, DMLabel, DMWorksheet

Use FontColor property to change font color for worksheets, plot axes and labels. Unlike VCL objects, IFont interface has no Color property so it has to be implemented separately.

Syntax:
property Transparent: Boolean

Applies to:
DMLabel

Syntax:
property BeforeData: Boolean

Applies to:
DMLabel

See also IDMPlot3.AreaSeries.

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

Applies to:
DMLabel

Alignment property for labels determines position of label's text block relative to its XMin,YMin coordinate. Possible values of this property are listed in the LabelAlignments Enumeration. Also it defines text position for rectangle - type labels.

Syntax:
property PinModeXMin: User_Defined

Applies to:
DMLabel

This property determine how XMin coordinate is translated into integer plot plane coordinate. When PinMode changed, integer coordinate retained. Possible values of this property are listed in the LabelPinModes Enumeration.

Syntax:
property PinModeXMax: User_Defined

Applies to:
DMLabel

This property determine how XMax coordinate is translated into integer plot plane coordinate. When PinMode changed, integer coordinate retained. Possible values of this property are listed in the LabelPinModes Enumeration.

Syntax:
property PinModeYMin: User_Defined

Applies to:
DMLabel

This property determine how YMin coordinate is translated into integer plot plane coordinate. When PinMode changed, integer coordinate retained. Possible values of this property are listed in the LabelPinModes Enumeration.

Syntax:
property PinModeYMax: User_Defined

Applies to:
DMLabel

This property determine how YMax coordinate is translated into integer plot plane coordinate. When PinMode changed, integer coordinate retained. Possible values of this property are listed in the LabelPinModes Enumeration.

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 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 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

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:
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:
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")