Graph Objects

In this topic:

Overview

Graph objects are the items displayed in a graph window. These include curves, axes, cursors and the various objects used for annotation. All graph objects possess a number of named properties all of which may be read and some may also be written. Each graph object also has a unique id which is used to identify it.

A knowledge of the inner workings of graph objects will be useful if you wish to customise some of the annotation features provided by the waveform viewer. However, the interface is at a low level with much work carried out by internal scripts. Consequently there is quite a steep learning curve to climb in order to make good use of the features available.

Object Types

The following table lists all the available object types:
Object Name Description
Axis Axes and grids
Crosshair Crosshair part of cursor
CrosshairDimension Object used to dimension cursors. Forms part of cursor. Cannot be displayed on its own
Curve Curve
CurveMarker Marker used to annotate curves
FreeText Free Text annotation object. Displays unboxed text on graph
Graph Graph sheet
LegendBox Box enclosing LegendText objects
LegendText Text objects used in legend boxes and linked to a displayed curve.
TextBox Box enclosing FreeText object

Properties

Properties are the most important aspect of graph objects. Each type of graph object possesses a number of properties which determine characteristics of the object. Some properties are read only and are either never altered or can only be altered indirectly. Other properties can be changed directly using the command SetGraphAnnoProperty. The labels for curves, axes and the various annotation objects are examples of properties that may be edited.

A full list of all object types and their properties is given in Objects and Their Properties .

Graph Object Identifiers - the "ID"

Each instance of a graph object is uniquely identified by an integer value known as its "ID". Valid IDs always have a value of 1 or greater. IDs are returned by a number of functions (see below) and also a number of the objects possess properties whose value is the ID of a related object.

Once the ID of an object has been obtained, its property names can be read and it property values may be read and/or modified.

The following functions return graph object IDs. Note that all functions return object IDs belonging to the currently selected graph only except for GetGraphObjects which can optionally return IDs for objects on a specified graph.
AddGraphCrossHair Add a new cursor to the currently selected graph and return its and its dimension's Ids
GetAllCurves Returns the IDs for all curves
GetAllYAxes Returns the IDs for all Y-axes
GetAxisCurves Returns IDs for all curves attached to specified y-axis
GetCurrentGraph Returns the ID for the currently selected graph sheet
GetCursorCurve Returns information about curve attached to the main cursor including its ID
GetCurveAxis Returns ID of y-axis associated with a curve.
GetDatumCurve Returns information about curve attached to the reference cursor including its ID
GetGraphObjects Returns all objects on a graph, or objects of a specified type
GetSelectedCurves Returns IDs of all selected curves
GetSelectedGraphAnno Returns ID of the selected annotation object
GetSelectedYAxis Returns the ID of the selected Y-axis
GetXAxis Returns the ID of the X-axis

Some of the functions in the above list are technically redundant. For example the value obtained by GetCurveAxis() can also be obtained by reading the value of the 'Y-axis' property of the curve. This can be done with the general purpose GetGraphObjPropValue function.

Symbolic Values

Some properties used for labels may be given symbolic values. Symbolic values consist of a property name enclosed with the '%' character. When the label is actually displayed the property name is replaced with its value.

Symbolic values may also be indirect. Some properties return the id of some other associated object and the value of a property for that object may be referenced with a symbolic value. The ':' character is used to denote indirect symbolic values. For example, this method is used with curve markers. The default value for a curve marker's label is:
%curve:label%
curve is a property of a curve marker that returns the id of the curve that it points to. label is a property of a curve that returns the label assigned to it. So curve:label returns the label of the curve that the curve marker points to.
Other curve properties can be used for this label. For example, curve measurements (as displayed below the legend in the legend panel) can also be accessed via property named "measurements". So the curve marker label:
%curve:label% %curve:measurements%
would display the curve's name followed by its measurements.

Finally the character sequence <n> can be used to denote a new line.

Objects and Their Properties

The following lists all the properties available for all objects. Note that all objects have a 'Type' property that resolves to the object's type name. Also all objects except Graph have a 'Graph' property that returns the ID of the object's parent graph sheet.

Axis

Axis objects represent both x and y graph axes.
Name Description Read Only?
Type Type of object - always 'Axis' Yes
Graph ID of parent graph Yes
AxisType 'X', 'Y' or 'Dig' Yes
Label Label used to annotate axis. (Actual displayed text is \textlangle label\textrangle / \textlangle unit\textrangle). Default = %DefaultLabel% No
Name Axis name. ('Y1', 'Y2' etc.). Empty for X and Dig axes Yes
Unit Physical units of axis. (E.g. 'V', 'A' etc.). Default = %DefaultUnit% No
Min Minimum limit of axis No
Max Maximum limit of axis No
AutoLimit 'On' or 'Off' determines whether axis limits are adjusted automatically according to attached curves No
Grad Grading of axis: "Log" or "Lin". No
Delta Value that determines the minor grid line spacing No
VertOrder Vertical order. Arbitrary string used to specify vertical display order No
DefaultLabel Label property is given default value of %DefaultLabel% which resolves to the value of this property. Yes
DefaultUnit Unit property is given default value of %DefaultUnit% which resolves to the value of this property. Yes

Crosshair

Object used to display cursor. Each graph cursor consists of a Crosshair and two CrosshairDimensions.
Name Description Read Only?
COM1 Common reference value. Only meaningful with X-Y plots such as Nyquist plots. Shows the value of the common reference to X and Y. This is frequency in a Nyquist plot Yes
Dimensions Comma delimited string providing the dimension objects attached to this cursor Yes
Graph ID of parent graph Yes
ID ID of this object Yes
Point 1 = Main cursor. 2 = Reference cursor Yes
Type Type of object - always 'Crosshair' Yes
XDimension The ID for the CrosshairDimension object that displays the X dimension and positions Yes
YDimension The ID for the CrosshairDimension object that displays the Y dimension and positions Yes
Curve ID of attached curve No
Division Division index of attached curve. See page for details on multi-division vectors No
Frozen 'On' or 'Off'. If 'On' the user will not be able to move the cursor with the mouse No
Hidden Cursor is hidden No
Label Cursor label displayed at base No
LineStyle Style of line used for crosshair. Comma delimited string of numbers representing mark-space values. E.g. '1,1' defines short evenly spaced dots, '3,1,1,1' defines a dotdash style No
OldStepMethod 'On' or 'Off'. Selects method of choosing the position of the cursor when stepped to a new curve using the TAB key. No
Style Style of crosshair. Possible values: 'Crosshair' or 'Cursor'. 'Crosshair' means the object is displayed as a crosshair with a width and height that extends to cover the whole grid. 'Cursor' means that the object is a small bitmap representing a cross. No
X1 X data value of crosshair position No
Y1 Y data value of crosshair position. The value can be written but this can only affects nonmonotonic curves where there are multiple y crossings at a given x value. No

CrosshairDimension

Object used to display the dimensions and positions of cursors. There are two types, namely horizontal and vertical.
Name Description Read Only?
Curve1 ID of curve attached to crosshair 1 Yes
Curve2 ID of curve attached to crosshair 2 Yes
Graph ID of parent graph Yes
ID ID of this object Yes
Type Type of object - always 'CrosshairDimension' Yes
Vertical 0 = Horizontal dimension, 1 = Vertical dimension Yes
XDiff = X2-X1 Yes
YDiff = Y2-Y1 Yes
Crosshair1 ID of crosshair 1 No
Crosshair2 ID of crosshair 2 No
Extent Value used to define space occupied by dimension as a proportion of font size. For horizontal dimensions this is the vertical space as a proportion of font height and for vertical dimensions this is horizontal space as a proprtion of average font width No
Font Font used to display labels. Can either be the name of a font object or a font spec as returned by GetFontSpec. No
Hidden Dimension is hidden No
Label1 Label positioned to depict value of first crosshair. Default = %x1% for horizontal types, %y1% for vertical. No
Label2 Label positioned to depict value of second crosshair. Default = %x2% for horizontal types, %y2% for vertical. No
Label3 Label positioned to depict the separation between crosshairs. Default = %XDiff% for horizontal types, %YDiff% for vertical. No
Position Value defines display order of dimension. For vertical dimensions this defines the order left to right and for horizontal dimensions this defines the order bottom to top No
Style Controls display of dimension labels. Possible values:
Internal Show difference only (label3) - internal position
External Show difference only (label3) - external position
Auto Show difference only (label3), position chosen automatically
P2P1 Show absolute labels (label1 and label2)
P2P1Auto Show all labels. Difference position chosen automatically
None No controls selected
No
VerticalText If set to 1, text is displayed vertically No
X1 For horizontal types, holds the value of the x data position of the first crosshair and is readonly. For vertical types holds the x view coordinate location of the object on the screen and is writeable No
Y1 For vertical types, holds the value of the y data position of the first crosshair and is readonly. For horizontal types holds the x view coordinate location of the object on the screen and is writeable No
X2 For horizontal types, holds the value of the x data position of the second crosshair and is readonly. For vertical types holds the view coordinate location of the object on the screen and is writeable No
Y2 For vertical types, holds the value of the y data position of the second crosshair and is readonly. For horizontal types holds the x view co-ordinate location of the object on the screen and is writeable No

Curve

Curve objects represent all graph curves.
Name Description Read Only?
Analysis Analysis type used to create curve's data Yes
DefaultLabel This is composed from Name, Suffix and GroupName to form a text string that is the default label for the curve Yes
DisplayType May be:
'analog' curve is regular analog trace
'decimal' bus display showing decimal values
'hex' bus display showing hexadecimal values
'binary' bus display showing binary values
Yes
Division Division index if plotting a multi-division vector. See Multi-division Vectors. Yes
Expression Expression that created this curve Yes
Graph ID of parent graph Yes
GroupName The data group that was current when the curve was created Yes
ID ID of this object Yes
Limits The X an Y limits of the curve in the form [xmin, xmax, ymin, ymax] Yes
Measurements Measurements added to a curve Yes
NumDivisions Number of divisions in curves data. I.e. the number of separate traces in a group of curves. Groups of curves are usually produced by Monte Carlo analyses Yes
ProbeId Name used to uniquely identify fixed probe (i.e. .GRAPH statement) that created this curve. Used to maintain persistence. Empty for randomly plotted curves. Yes
ShortLabel A label composed from Name and Suffix but without group name Yes
Type Type of object - always 'Curve' Yes
XAxis ID of x-axis attached to curve Yes
XExpression Expression that defines X-values Yes
XUnit Physical type of curve's x-data Yes
YAxis ID of y-axis attached to curve Yes
YUnit Physical type of curve's y-data Yes
Frozen If 'true' curve will not be purged. That is it will not be removed to satisfy the persistence setting for a fixed probe No
Label The curve's label. This is the text that appears in the legend panel. This can use a symbolic constant and in fact defaults to %DefaultLabel%. Note that when reading back a symbolic value assigned to this property, the resolved value will be returned No
Name The curve's base name. This is the value passed to the /name switch of the Curve/Plot command or the name of the vector plotted if no /name switch is supplied. No
RGBColour Colour of curve. Can be entered as value returned from GetColourSpec or using format #rrggbb where rr, gg and bb are two digit hex values representing the red, green and blue colour content respectively No
Sequence Integer value that is used to define default colour. The actual colour used may be set globally using options dialog box No
ShowPoints If 'true' data point markers will be displayed No
Suffix This is assigned when the result of a multistep analysis is plotted to give information about the step. E.g. if you stepped a resistor value the suffix would hold the name and value of the resistor at the step. No
Visible If 'false', curve will be hidden, but its legend display will remain No

CurveMarker

An object used to title a curve or mark a feature.

Name Description Read Only?
Division Division index of attached curve Yes
Graph ID of parent graph Yes
ID ID of this object Yes
Type Type of object - always 'CurveMarker' Yes
Curve ID of attached curve No
Font Font for label No
Hidden Not implemented No
Label Label of curve marker. May be a symbolic value. Default is %curve:label% which returns the label of the attached curve No
LabelJustification Text Alignment. May be one of these values:
-1 Automatic
0 Left-Bottom
1 Centre-Bottom
2 Right-Bottom
12 Left-Middle
13 Centre-Middle
14 Right-Middle
8 Left-Top
9 Centre-Top
10 Right-Top
No
SnapToCurve 'On' or 'Off'. If 'On' marker tracks attached curve i.e its y position is determined by the y value of the curve at the marker's x position. If 'Off' marker may be freely located. No
X1 X-data value at arrowhead No
Y1 Y-data value at arrowhead No
X2 X position of label in view units relative to arrowhead No
Y2 Y position of label in view units relative to arrowhead No

FreeText

Free text objects are items of text with no border or background that are not attached to any other object.
Name Description Read Only?
Date Date that the object was created. If the object is on a graph that has been saved to a file then subsequently restored, the date will be the date that the object was originally created. Yes
Graph ID of parent graph Yes
ID ID of this object Yes
Parent ID of parent object. If text is placed freely on the graph, this will be the same as the Graph property. FreeText objects. however are also used in TextBoxes in which case this returns the id for the TextBox Yes
Time Time that the object was created. If the object is on a graph that has been saved to a file then subsequently restored, the time will be the time that the object was originally created. Yes
Type Type of object - always 'FreeText' Yes
Version Product name and version Yes
Font Font for label No
Hidden Not implemented No
Label Text displayed. Symbolic values may be used. E.g. %Time% will display the time the object was created. No
LabelJustification As CurveMarker (see above) except -1 (automatic) not allowed No
X1 X location of object in view units No
Y1 Y location of object in view units No

Graph

Name Description Read Only?
FirstCurve ID of the oldest curve on the graph Yes
GroupTitle Title of the data group that was current when the graph was created Yes
ID ID of this object Yes
MainCursor ID of Crosshair object comprising the main cursor. Value = -1 if cursors are not enabled. Yes
RefCursor ID of Crosshair object comprising the reference cursor. Value = -1 if cursors are not enabled. Yes
SourceGroup The data group that was current when the graph was created Yes
Type Type of object - always 'Graph' Yes
CursorStatusDisplay Sets method of displaying cursor positions and dimensions. Possible values:
Graph Display on graph using
CrosshairDimension object
StatusBar Display on status bar
Both Display on graph and status bar
No
Path Path of file to save to. This is the file that will be used by the "File|Save" menu. When saving a graph, this property will be set to the full path name of the file. No
TabTitle The text in the title of the tabbed sheet. This can be symbolic. Default is %SourceGroup% %FirstCurve:Label% No
TitleBar Text to be displayed in the graph window title bar when the graph's sheet is in view. This may be symbolic. Default is %SourceGroup% (%GroupTitle%) No

LegendBox

The LegendBox is used to display labels for every curve on the graph sheet. It consists of a box that is loaded with LegendText objects - one for each curve on the graph. The LegendText objects are automatically loaded when a curve is added to the graph and automatically deleted when a curve is deleted. LegendBox is very similar to the text box and shares the same properties with the following differences and additions:
  1. Type property has the value 'LegendBox'
  2. LegendBox has two additional properties as shown below
Name Description Read Only?
Labels Semicolon delimited string defining text entries in the box. Each entry is usually %DefaultLabel% which resolves to the value of the DefaultLabel property of the LegendText object. Other symbolic values for LegendText properties may also be used No
LegendLabel Text of label that is loaded into box when a curve is added to the graph. This can be symbolic in which case it references properties of the LegendText object that displays the text. The default value is %DefaultLabel% No

LegendText

LegendText objects are used to load legend boxes and cannot be instantiated independently. They are similar to FreeText objects and share the same properties with the following differences and additions:
  1. Type property has the value 'LegendText'
  2. The Label property is set to the value of the legend box's LegendLabel property when it is added to the box.
  3. LegendBox has two additional properties as shown below
Name Description Read Only?
Curve ID of attached curve Yes
DefaultLabel The default value for the label. Actually equivalent to %Curve:Label%\textlangle n\textrangle%Curve:Measurements%. (\textlangle n\textrangle denotes a new line). Yes

TextBox

A TextBox consists of a border with a definable background colour into which a FreeText object may be added. TextBox is also the basis of the LegendBox object.
Name Description Read Only?
Graph ID of parent graph Yes
ID ID of this object Yes
Type Type of object - always 'TextBox' Yes
AutoWidth 'On or 'Off'. If 'On' the width of the box is automatically adjusted according to its contents subject to MaxHeight No
Colour Background colour. Either the name of a colour object or a colour specification. No
Font Font used for text objects added to the box. In practice this only affects the LegendBox object which is based on TextBox. No
FontColour Colour used for text. Either the name of a colour object or a colour specification  
Hidden Not implemented No
Label Text displayed in box No
MaxHeight Maximum physical height in mm of box. This is only used when AutoWidth='On' No
X1 X location of object in view units No
Y1 Y location of object in view units No
X2 Physical width of box in mm. (Ignored if AotoWidth='On') No
Y2 Physical height of box in mm No

Graph Co-ordinate Systems

Three different units of measure are used to define the location and dimensions of an object on a graph sheet. These are 'View units', 'Physical units' and 'Data units'. These are explained as follows:

'Physical Units' relate to the physical size of the displayed object and have units of millimetres. Physical units are only used for dimensions of some annotation objects and are not used for location. When objects are displayed on a screen an assumption is made for the number of pixels per inch. This depends on the display driver but is typically in the range 75 - 100.

'Data Units' relate to the units of the X and Y axes. Typically an object such as curve marker is located using data units so that it always points to the same point on a curve regardless of how the graph is zoomed or scrolled.

'View Units' relate to the current viewable area of the graph. View units use a coordinate system whereby the bottom left of the grid area is co-ordinate (0,0) and the top right corner of the grid is co-ordinate (1,1). View units are used to define the location of objects that need to be at a fixed location on the graph irrespective of zoom magnification.