IDMWorksheet3 Interface

Version: 3.1
Dispatch interface for DMWorksheet Object

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

This interface provides access to the worksheet objects. You may change numerous visual attributes of the worksheet viewer and perform several editing commands on the selected block of cells.

Members:
Kind Name ID Description
ColumnLabels 1 Change column labels
Scroll 2 Scroll to line with number (0..N)
XColumn 3 Change X column
YColumn 4 Change Y column
SelectionTop 5 Change Selection.Top
SelectionBottom 6 Change Selection.Bottom
SelectionLeft 7 Change Selection.Left
SelectionRight 8 Change Selection.Right
CopyToClipboard 9 Invoke TWorksheet.CopyToClipboard()
PasteFromClipboard 10 Invoke TWorksheet.PasteFromClipboard()
Delete 11 Invoke TWorksheet.Delete()
SelectAll 12 Invoke TWorksheet.SelectAll()
Select 13 Select cells
CanPaste 101 True if clipboard has text or TRealData
InPlaceEdit 102 Change worksheet inplace editor mode
Format 103 Change column format
AlignRight 104 Changes TWorksheet.AlignRight property
Font -512 Changes worksheet font
Color -501 Changes worksheet color
FixedColor 105 Changes fixed cells color
BlockColorF 106 Changes selection foreground color
BlockColorB 107 Changes selection background color
Document 108 Returns owner document object
ExpressionColor 201 Changes expression-based cells foreground color
FontColor 202 Changes cell font color
Expression 203 Changes worksheet column expressions
Refresh 204 Updates worksheet when data are changed
RowHeight 205 Changes worksheet rows height
AssignObject 206 Copies attributes from the given worksheet

Syntax:
property ColumnLabels[Index]: BSTR

Applies to:
DMWorksheet

Column labels are displayed in the nonscrolling worksheet area. Unlike data elements, columns are numbered from 1(A) to 26(Z). Column labels in DM2003 are not saved together with data, but can be stored in the MetaBase instead.

Syntax:
function Scroll(Line): VOID

Applies to:
DMWorksheet

Just scrolls worksheet so that required line become visible. Usually it will be at the top of the scrollable area of the worksheet.

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 SelectionTop: Long

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

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

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

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(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 PasteFromClipboard(InsertLines, Overwrite): 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 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 SelectAll: VOID

Applies to:
DMNotes, DMWorksheet

This method selects all data range in the appropriate object.

Syntax:
function Select(Left, Right, Top, Bottom): 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 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 InPlaceEdit: Boolean

Applies to:
DMWorksheet

Syntax:
property Format[Index]: BSTR

Applies to:
DMAxis, DMFloatEdit, DMSpinEdit, DMWorksheet

This property allows you to change numeric format. Possible values are: XX.Yt, where XX - total number of digits, Y - number of digits after decimal point, t - one of the following characters:

Another type of strings used for Date and Time format feature. If format specifier value enclosed in the curly brackets, it is treated as date/time.

Syntax:
property AlignRight: Boolean

Applies to:
DMWorksheet

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

Applies to:
DMWorksheet

Syntax:
property BlockColorF: User_Defined

Applies to:
DMWorksheet

Syntax:
property BlockColorB: User_Defined

Applies to:
DMWorksheet

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

Applies to:
DMWorksheet

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 Expression[Index]: BSTR

Applies to:
DMAxis, DMFitter, DMWorksheet, LMFitter

For DM2003 plot axis, you may transform all series simultaneously if you assign valid expression to this property. See details about expression syntax and allowed arguments and function names.

For DMFitter ActiveX control, Expression property should be defined before you start fitting. There are several possible situations:


For worksheets, this property is index-based and determine column expressions. These expressions may be used to recalculate dynamically the contents of appropriate column. Notice that you can assign expressions to any column, even those that has no data! The syntax and parameter set for column expressions are the same as for plot series.

Example:

Server.CreateDocument Server.InstallPath & "samples\data_1.dat"
Server.ExecuteCommand "ShowWorksheetAction"
Server.ActiveDocument.Worksheet.Expression(3)="a+b"

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

Applies to:
DMWorksheet

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