|
|
In this Topic Hide
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.
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 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.
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.
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% |
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% |
Finally the character sequence <n> can be used to denote a new line.
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 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 |
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 |
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:
|
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 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:
|
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 |
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:
|
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 | |||||||||||||||||||||
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 |
| 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:
|
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 | |||||||||
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:
| 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 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:
| 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 |
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 |
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.
|