TPlot

A set of components, located in plot.pas unit, is a 2D graphic engine and should be used in technical and scientific graphical applications to display arrays of numbers and/or symbolic expressions. These components were specially optimized for fast visualization, analysis and processing of huge data arrays (10⁶ points and more!). It should be noticed that unlike presentation toolkits like ChartFX or TeeChart shipped with Delphi, at present TPlot component has comparatively limited formatting capabilities and probably not suitable for real-time (oscilloscopic) applications (see picture below).

Key features of DM2000 graphic engine include:

• Fully customizable plot with X/Y axes and unlimited number of series
• TContainer components are used to store data instead of internal arrays
• Expression parser for "on-fly" mathematical curve transformations
• Visual data editor with clipboard support (data or metafiles)
• Printing capabilities, plus export to metafiles
• Unique visual curve translation tool
• Add points without plot refresh (required for data acquisition)

Methods and properties of TPlot component are briefly described below:

public members

function GetDataPoint(D: TData; CX,CY: integer; const XExpr,YExpr: string; var X,Y: extended): boolean

Used to calculate point coordinates from data element D. CX,CY - column numbers, XExpr,YExpr - serie expressions. You need this method to manually display points.

procedure SetDataPoint(D: TData; CX,CY: integer; X,Y: extended)

Override this method for custom data elements support. Used only by visual point editor and translation.

procedure DrawLine(X1,Y1,X2,Y2: extended)
procedure DrawPoint(X,Y: extended; T: TPointType; S: integer)
procedure PaintPoint(X,Y: integer; T: TPointType; S: integer; C: TCanvas)

Drawing methods. Should be called from OnPaint event handler or if you want to add points without full plot refresh. First two methods operate with real coordinates, PaintPoint() requires integer point coordinates. Use Canvas methods to draw lines with   integer coordinates.

function RealToIntCoords(X, Y: extended; var iX,iY: integer): boolean
function IntToRealCoords(X,Y:integer; var rX,rY: extended): boolean

Convert between integer and real coordinates. Returned value define whether conversion is possible (that is, all coordinates are within plot area). Note that RealToIntCoords() return TRUE if real coordinates are out of range, but IntToRealCoords() returns TRUE if coordinates are ok.

procedure CopyToClipboard(Mode: TPlotCopyMode; UseTabs: boolean)
procedure Delete

These methods support block data editing. CopyToClipboard() can copy X,Y coordinates of selected points, all item's data or whole plot page depending on Mode parameter. Like in TWorksheet, this method copy points in two formats: text and TRealData (only for Mode=pcmItems). Both methods process points within selection area (if it is visible), or all points from current serie.

procedure Print(W,H: integer)

Prints plot. W,H - width and height of printed image area. You should also set top left corner position and margins before printing. See DM2000 source for example code.

procedure UndoZoom
r/o property CanUnZoom: boolean

Restore coordinates changed by built-in (with mouse) Zoom. Available only when undo possible (if CanUnZoom=true). If you change axes coordinates via Min/Max properties, UnZoom will not work. Currently unzoom buffer remembers only one level.

r/o property ClickedAt: TClickedAt

Analyze this property in OnClick event handler to determine what part of plot area was clicked. Also may be checked in OnMouseDown/OnMouseUp handlers (this property set in TPlot.MouseDown method).

r/o property Parser: TMathParser

Provide access to TMathParser object used for evaluating serie and axis X,Y expressions. You may add new parameters or change predefined ones. Click this link for more information about parser expression syntax and predefined functions and parameters.

Note that apart from default set of functions and parameters TPlot object adds 4 special parameters that may be used in serie and axis expressions: cx,cy - point coordinates, num - relative point number (index in serie block), absnum - point index in container.

procedure SaveToFile(FileName: string)
procedure SaveToMetafile(WMF: TMetafile)

You can save plot image into metafile object or directly to disk metafile.

property SelectionVisible: boolean
property SelectionTop: extended
property SelectionBottom: extended
property SelectionLeft: extended
property SelectionRight: extended

Read and change coordinates of plot selection. Note that selection may be invisible for user, but all operations that use selection still work.

published members

property Pen: TPen
property Brush: TBrush

Preset these drawing tools at design-time and use them in OnPaint event handler

property BorderStyle: TBorderStyle
property Transparent: boolean

Plot may have or have no border, and be transparent. Change these properties in Object Inspector and see results.

property MouseMode: TPlotMouseMode

This property controls mouse behavior. Select one of following constants to turn on appropriate mode: pmNone, pmAutoZoom, pmZoom, pmRuler, pmUnZoom, pmSelect, pmPointClick, pmPointEdit, pmPointDelete, pmTranslate. Compile plotdemo.dpr example program and see how it works for more information about mouse modes.

There's one important limitation: you cannot use visual editing tools (namely point editor and translation) if axes or series expressions are not empty. Otherwise you have to calculate inverse functions defined in the form of expressions. This is not too easy and not implemented in current version.

Also keep in mind that translation, like "block" clipboard operations, works only with current serie.

property XAxis: TAxis
property YAxis: TAxis

References to TAxis objects. Use these properties to get access to various axes properties: coordinates, title, ticks, labels, etc. Note that axes positions are calculated automatically - you cannot set integer axes coordinates.

property Series: TSeries

References to TSerie objects. Plot have a collection of unlimited number of series. Every serie, in turn, may reference TContainer component with data or be "functional" serie - in this case YExpression calculated instead of displaying data from container. Use TSerie objects to set curve attributes.

property SerieIndex: integer
r/o property ThisSerie: TSerie

In some cases you may prefer sequential access to series collection. These two properties supports "current" serie in the same manner as TForm.ActiveMDIChild property. Note that ThisSerie may be nil.

property OnHint: TPlotHintEvent

OnHint event occurs when TPlot component needs to display status information. You may display this information in the status line of your application.

property OnError: TPlotHintEvent

This event should be used to display error information. Like for previous event, display this information in the status line rather then in messageboxes because this event may occur under unpredictable circumstances - for example, if you add points with incorrect coordinates.

property OnSelectionChange: TNotifyEvent

OnSelectionChange event fired from TPlot.MouseUp() method when user finishes selection in pmSelect or pmTranslate modes.

property OnPointClick: TPointClickEvent

OnPointClick event occurs when user clicks point. It is called from TPlot.MouseDown() method if MouseMode property is set to pmPointClick, pmPointEdit or pmPointDelete.

For more information about these objects, see library demonstration samples, DM2000 source code and description of IDMPlot, IDMAxis and IDMSerie interfaces.