Programmer Guide/Shell Items/Graph/SET GRAPH

Graph Item
INTRODUCTION	NEW	SET	ATTRIBUTES	MESSAGES	EXAMPLES

A graph consists of eight splitters. It has one X input (which is not always used), a user-defined number of Y inputs and a CURSOR output. Each Y input can be used to display a function (for some functions, in combination with the X input). All splitters in a graph and all functions displayed in a graph use the same X and Y scale settings. Each function is assigned to one splitter in which it should be displayed. More than one function can be displayed in one splitter. The functions displayed in a splitter can even be different but they should be compatible (e.g. it makes no sense to assign a SPECTROGRAM and a WAVEFORM to the same splitter). Each splitter can be set to be visible or hidden.

For all color settings (and palettes) used by a graph, one color can be assigned for the screen and one for the printer. To assign screen colors use the commands as described above. For printer color setup use the same commands a second time with the option /Print.

To minimize screen updates, most setup commands do not directly affect the display. The setup parameters are stored and must be explicitly transferred to the display. For this purpose the option /Apply can be used with any graph-item command.

The formats and values for color and font arguments used in the graph commands are described in detail in the Colors and Color Arguments topic in the General section.

Inputs and plots

Graphs items can display different types of function plots. The function data is passed to the graph via the graph's X and Y inputs. You set up the relationship between the data (a value item, SPU, or GDX file) and the graph's inputs using the following SET graph X and SET graph Y commands.

Connecting graph inputs

Configure a graph's x and y axis for data input.

SET graph X data

The graph item's X command configures a graph's x-axis data input. The exact configuration necessary depends on the type of plot which will be drawn.

SET graph Y index data function splitter params /Realtime

The graph item's Y command configures the graph's y-axis data input. The function parameter specifies which type of plot will be drawn. These plots are described individually in more detail below.

option	description
index	The zero-based input index (0…inputs–1)
data	data parameter. This can be the output of an SPU (spuitem.output) or of a value item (valueitem).
function	One out of XYPLOT, PARAMETER, WATERFALL, SPECTROGRAM and WAVEFORM.
splitter	The number of the graph splitter index (1…8) where the function should be displayed. Note that splitter visibility is set using the SPLITTERS command.
params	The function plot configuration parameters (see the specific plot below).
/Realtime	The real-time option /R causes the function to be re-displayed each time an input is updated. If this option is used, zooming is not possible.

The Y input MUST be defined before the X input on the first call (redefining the Y axis once both x and y inputs have been defined is not a problem). Orienting a graph (e.g. rotating 90 degrees) is achieved with the command SET graph ORIENTATION. Use of the options /Horizontal and /Vertical is no longer supported.

Disconnecting graph inputs

SET graph Y index
SET graph X

Disconnect any inputs previously assigned to the graph's input index.

option	description
index	The index of the input (0…nInputs-1).

Outputs are automatically disconnected if the item owning the output or the graph item itself is deleted.If the connection is synchronized (e.g. the connected SPU item is still running) disconnection is not possible.

Plots

The STx graph item can draw a number of different plot types.

XYPLOT / FUNCTION

SET graph Y index yout XYPLOT splitter color style line width sym [/F=noPlotValue] [/Realtime]

Display a two-dimensional function plot: Y_i = f(X_i). The outputs assigned to the X and Y inputs must be vectors of the same length. The option /F=noplot can be used to suppress plotting all the points where Y_i equals noplot (useful for f0-tracks). If the option /Realtime is used, the function is redisplayed each time an input is updated. Note that zooming is not possible in conjunction with the /Realtime flag. Otherwise, the function is displayed on synchronisation (when the SPU stops). The DASH and DOT line styles only support widths of 0. The keywords XYPLOT and FUNCTION are interchangeable.

option	description
xout	The x data vector (an output of an SPU). This must be the same length as yout.
yout	The y data vector (an output of an SPU). This must be the same length as xout.
colour	The color of the function line (either a color name or an RGB code).
style	The plot style. Either dotted (POINTS), a line (LINES), a solid area (AREA) or no line (NONE). If POINTS is set, then one point is drawn per Y data point. If LINES is set, then a line is drawn between all Y data points. If AREA is set, then the area below the Y data points is filled.
line	The line style (SOLID, DASH or DOT).
width	The width of the function line (0-4 if line is SOLID, 0 if line is DOT or DASH).
sym	The symbol to use at each parameter (NONE, SQUARE, TRIANGLE, CIRCLE, CROSS or DIAMOND).
/F=noPlotValue	Use this option to suppress a particular value (noPlotValue) from the plot

SET graph X xout

Assign the X input vector. The X input vector must be the same length as the Y input vector. The Y input vector must be set before calling this command.

PARAMETER

SET graph Y index yout PARAMETER splitter nfrm color style line width  sym [/F=noplot /Realtime]

Display the Y data as a function of time (frame index). The connected output can be a numeric value or a vector. Each value written to Y is appended to the time track. The options /F and /Realtime have the same meaning as for XYPLOT. Note, however, that zooming does not work for the parameter plot when the real-time flag is used. This function is used to display parameter time tracks in (frame-by-frame) analysis applications. The DASH and DOT line styles only support widths of 0.

option	description
yout	The parameter values (one number per frame).
nfrm	The number of frames (parameter values). If real-time mode is specified (/R), this is the number of frames per screen.
color	The line color (color name or rgb code).
style	The plot style (POINTS, LINES, AREA,STEPS).
line	The line style (SOLID, DASH, DOT).
width	The line width (0…4 – SOLID, 0 – DASH and DOT)
sym	The symbol to use at each parameter (NONE, SQUARE, TRIANGLE, CIRCLE, CROSS or DIAMOND).

See Connecting graph inputs for parameters not described here.

No X input connection is necessary. The X (time) scale is defined by the number of frames nfrm specified for the Y data.

WATERFALL

SET graph Y index yout WATERFALL splitter nfrm nspectra lcolor fcolor style width [/Realtime] 
SET graph X xout

The output connected to X contains the frequency values, and the output connected to Ynum contains the magnitude values. Both must be vectors of the same length. The X scale is written only once.

option	description
yout	The waveform samples (a vector or a number).
splitter	The splitter to show the function in.
nfrm	The number of frames.
nspectra	The number of spectra to display.
lcolor	The line color (color name or rgb code).
fcolor	The fill color (color name or rgb code).
style	The line style (SOLID, DASH or DOT).
width	The width of the function line (0-4).

See Connecting graph inputs for parameters not described here.

SPECTROGRAM

SET graph Y

SET graph Y index ydata SPECTROGRAM splitter nframes amin amax palette [ /R ]

The output connected to Y_num contains the values (magnitude, phase,…) to be displayed in colors. The Y vector must be the same length as the X vector. The Y values are converted to colors and either displayed each time the input is updated (if the real-time option /R is specified), or on synchronization (when the SPU stops). The whole spectrogram consists of nfrm spectra. The colours used to display the different amplitudes are defined using the palette parameter.

option	description
ydata	Either an SPU output or a GDX file item providing the magnitude vectors (one spectrum per frame).
nframes	The number of frames (spectra). If the /R option is specified, this parameter determines the number of frames displayed at any one time on screen.
amin, amax	The minimum and maximum magnitudes.
palette	The extended table containing the RGB color values (the color palette). The table must have three integer or number fields R, G and B where each row defines one RGB value (each field entry may be a value from 0 to 255). The maximum number of palette table entries is 256. You can change the palette at any time by calling this function with a new palette table. Mapping of y values to colors, with: i = 0 … nrgb-1; da = (amax – amin) / nrgb y < amin rgb-value[0] y > amax rgb-value[nrgb-1] amin+i.da < y ≤ amin+(i+1).da rgb-value[i]

See Connecting graph inputs for parameters not described here.

SET graph X

SET graph X xdata

The data output connected to X supplies the frequency values. The X vector must be the same length as the Y vector. The X scale is written only once. Note that the frequency scale is displayed on the y axis (time is displayed on the x axis).

option	description
xdata	The frequency vector (only set once).

Zooming in a spectrogram

You can zoom into a spectrogram graph on three axes: time (x), frequency (y) and amplitude (z). Zooming is done using the scale commands XSCALE, YSCALE and ZSCALE.

WAVEFORM

SET graph Y index yout WAVEFORM splitter nsmp color style scroll [ /R ]

The waveform envelope is drawn using a min/max plot and optionally filled (style=AREA). Each screen contains nsmp samples of the waveform, and the waveform is scrolled if more than nsmp samples are sent via the input Ynum. The argument scroll can set to OFF (or 0) if scrolling should be avoided. The output connected to Ynum can be a vector (of any length) or a number. If the option /R is used, the function is redisplayed each time an input is updated. Otherwise, the function is displayed on synchronisation (when the SPU stops).

option	description
yout	The waveform samples (a vector or a number).
nsmp	The number of samples per screen.
color	The line color (color name or rgb code).
style	The plot style (LINES, AREA).
scroll	1) or disable scrolling (OFF|0).

See Connecting graph inputs for parameters not described here.

Note that you must apply the settings to the graph (option /A) before synchronizing the inputs if the input data is to be correctly interpreted.

Configuration & Control

Configure the colours and layout of the graph.

AXIS

SET graph AXIS xLabel yLabel labelFont labelColor xTitle yTitle titleFont titleColor xUnit yUnit xBorder yBorder

Configure the X and Y axis. If you are using a WATERFALL graph, you can configure the Z axis with the ZSCALE command.

option	description
xLabel	The position of x labels (OFF, ABOVE. BELOW or BOTH).
yLabel	The position of y labels (OFF, LEFT, RIGHT or BOTH).
labelFont	The label font.
labelColor	The label color.
xTitle	The position of x axis text (OFF, ABOVE, BELOW or BOTH).
yTitle	The position of y axis text (OFF, LEFT, RIGHT or BOTH).
titleFont	The title font.
titleColor	The color for titles.
xUnit, yUnit	Display x and y axis units (OFF or ON) .
xBorder, yBorder	The width of the border at the edge of the window on the x axis and y axis (in pixels). The default is 1.

BGCOLOR

SET graph BGCOLOR text draw

Set background colors for the text and draw regions of a graph.

option	description
text	background color for text regions
draw	background color for draw regions

FRAME

SET graph FRAME xscale yscale scalecolor grid gridcolor xsteps ysteps major minor

Configure the graph's frame, scale and grid. Note if you can use the graph item commands XSCALE, YSCALE and ZSCALE to set the scale, grid and tick values.

xscale	draw x scale (OFF, ABOVE, BELOW or BOTH)
yscale	draw y scale (OFF, LEFT, RIGHT or BOTH)
scalecolor	color for scales
grid	draw grid (OFF, X, Y or BOTH)
gridcolor	color for grid
xsteps, ysteps	number of minor x/y ticks between labels
major, minor	size of major/minor ticks in pixels

Note that the difference between a major and a minor grid is the line style: a major grid is solid, whilst a minor grid is dashed.

ORIENTATION

SET graph ORIENTATION rotation flip

Set the orientation of the graph. By default, the x axis is the horizontal axis and runs from left to right, whilst the y axis is the vertical axis and runs from bottom to top. You can use the ORIENTATION command to rotate the graph and flip the direction in which the axes run. The XSCALE and YSCALE commands can also modify a graph's flip settings.

option	description
rotation	The angle in degrees by which to rotate the graph. Only the values 0, 90, 180 and 270 are supported. An asterisk (*) can be passed to retain the current rotation setting. Rotation is anti-clockwise. The rotation can also be specified thus: 0|1|2|3 where 0 means no rotation, 1 means 90 degree rotation etc.
flip	Determines whether the graph should be flipped on the x and y axis. The following values are supported: 0 do not flip at all (default orientation). 1 flip on the x axis 2 flip on the y axis 3 flip on both the x and y axis. * do not change the current flip setting

Note that you can retrieve the current orientation of a graph using the attribute !ORIENTATION.

OVERVIEW

SET graph OVERVIEW [ mode ]

Switch between overview and view modes. In the overview mode, the whole range of the graph is displayed with the current view displayed as a metasegment. In the view view, only the range of the current view is displayed. Moving the view metasegment whilst in the overview mode will result in a new view, once back in the view mode.

option	description
mode	One of the following values: on or 1 Switch to overview mode. off or 0 Switch to view mode.

If neither is specified, the mode is toggled.

You can query which mode the graph is in using the !MODE attribute.

See also XSCALE and YSCALE.

SPLITTERS

SET graph SPLITTERS splitter1 [splitter2…] [/Merge]

Set splitters to be displayed. A graph can contain up to eight splitters. Usually only two are used for, e.g., displaying a stereo signal. If /Merge is specified, the currently displayed splitters remain active, otherwise only the specified splitters are displayed.

option	description
splitterX	The index of the splitter to be displayed. This may be any integer from 1 to 8.
/Merge	Use the OR operator when setting the splitters.

Example for displaying the first two splitters:

$#graph splitters 1 2

TITLE

SET graph TITLE mode font color [title1 title2] [/Settitle]

Configure and/or set graph title. The option /Settitle can be used to set a new graph title without applying other settings.

option	description
mode	Turn the graph's title on or off. The following values are supported: ON and OFF
font	A font argument as specified in Fonts and Font Argument Format.
color	A color argument as specified in Colors and Color Arguments.
title1, title2	The text to be displayed (one or two lines).

XSCALE

SET graph XSCALE min max unit text [formatStr|table] [/Invert] [/Log] [/View]
SET graph XSCALE [ min max ] /View

Set the x scale range, title and unit string.

option	description
min, max	The minimum and maximum range of values on this scale.
unit	The text to be displayed as the unit on scale and in the cursor tooltip windows.
text	The title or description. Note that even if this is set here, it must be enabled using the AXIS command.
formatStr	A format string which is used to format the range values. See Format Strings and Rules for details.
table	An extended table containing alternative scale values. See scale definition table for a description of the table format.
/Invert	Invert the scale (x-axis - right to left, y-axis, top to bottom). Note that this is the same as the ORIENTATION command $#graph ORIENTATION * 1.
/Log	The scale is logarithmic (base 10).
/View[=Reset]	Set the view (section of whole range).

If the option /View is specified, the min and max value are used to display a section of the whole range. If Reset is specified (e.g. /View=Reset), the min/max values are ignored (and can be left out) and the whole range is redisplayed.

YSCALE

SET graph YSCALE min max unit text [formatStr|table] [/Invert]
SET graph YSCALE [ min max ] /View=[Reset]

Set the y scale range, title and unit string.

option	description
min, max	The minimum and maximum of scale (range).
unit	The text to be displayed as unit on scale and in cursor window.
text	The title or description.
formatStr	A format string which is used to format the range values. See Format Strings and Rules for details.
table	An extended table containing alternative scale values. See scale definition table for a description of the table format.
/Invert	Invert the scale (x-axis - right to left, y-axis, top to bottom). Note that this is the same as the ORIENTATION command $#graph ORIENTATION * 2.
/View[=Reset]	Set the view (section of whole range).

If the option /View is specified, the min and max value are used to display a section of the whole range. If Reset is specified (e.g. /View=Reset), the min/max values are ignored and the whole range is redisplayed.

ZSCALE

SET graph ZSCALE showScale min max nMinorStep showLabels showUnit unitText showTitle titleText xShrink yShrink [formatStr|table] [/Invert]
SET graph ZSCALE [ min max ] /View=[Reset]

Set the z scale range, title and unit string. Note that the z scale was introduced with the implementation of the Waterfall graph. The values xShrink and yShrink determine that amount of the available space for the graph is taken up with the x and y axis.

option	description
showScale	Set the zscale visiblity (OFF, LEFT, RIGHT or BOTH).
min	The minimum zscale value
max	The maximum zscale value
nMinorStep	The number of minor tick steps
showLabels	Set the label visibility (OFF, LEFT, RIGHT or BOTH)
showUnit	Set the unit visibility (ON or OFF)
unitText	The text to be displayed as unit on the scale and in the cursor window
showTitle	Set the title visibility (OFF, LEFT, RIGHT or BOTH)
titleText	The title text
xShrink, yShrink	A value between -1 and 1. The shrink value determines how much of the space available for the x and y axis is used.
table	An extended table containing alternative scale values and labels. See scale definition table for a description of the table format.
formatStr	A format string which is used to format the range values. See Format Strings and Rules for details.
/Invert	Use this option to invert the scale.
/View[=Reset]	Set the view (section of whole range).

If the option /View is specified, the min and max value are used to display a section of the whole range. If Reset is specified (e.g. /View=Reset), the min/max values are ignored and the whole range is redisplayed.

Scale definition table

The graph item commands XSCALE, YSCALE and ZSCALE can use a scale definition table to define the scale, labels and grid lines. The scale definition table must be an extended table with the following three fields:

pos	A numeric field for the position.
type	A string field for the scale type (LABEL, MINORTICK, MAJORTICK, MINORGRID or MAJORGRID).
label	A string field for the label text. This is only of used for entries of type LABEL. If the label field is not empty, the label field text is displayed at pos, otherwise the value of pos is displayed at the position pos.

Cursors

STx graph items support two graphical cursors, which can be used to mark points on a graph. See Cursors for an introduction to the concept of cursors.

CURSORMODE

Configure the graph cursors' visibility and functionality. One of the options /Graph, /Shell or /Both can be used to define the handling of the special graphic keys (cursor keys and some function keys). See Cursors for a general description of STx cursor functionality.

SET graph CURSORMODE mode style values bound locked rubberline scolor ucolor limit xormode [/Graph|Shell|Both]

argument	description
mode	Set the cursor visibility (OFF, 1, 2 or BOTH). Cursors are off by default.
style	Set the cursor display style (CROSS, CROSSHAIR, HBAR, VBAR, HBARCROSS, VBARCROSS, HARMONIC, YHARMONIC, RANGESELECTION, CROSSCIRCLE or CROSSSQUARE).
values	Turn the cursor tooltip window ON or OFF. The tooltip displays the position of the cursor directly underneath the user's mouse.
bound	Use the index of a function to bind the cursors to a function or -1 to allow unrestricted cursor movement..
locked	Turn cursor locking ON or OFF. If cursors are locked, moving a cursor in one splitter will cause it to move in all other splitters in the graph. If cursors are unlocked, they can be moved independently in all splitters in the graph.
rubberline	Turn the rubber line ON or OFF. A rubber line is a line between the two cursor positions.
scolor	Set the color for selected cursors (see Colors and Color Arguments).
ucolor	Set the color for unselected cursors (see Colors and Color Arguments).
limit	If limit is set to VIEW, cursors which are turned on are restrained to within the current view. If their position moves outside the view (e.g. due to a zoom command), the cursors are repositioned inside the view. If set to RANGE, cursors may be positioned outside of the view (but never outside of the range. The default is VIEW. The attribute !CURSORLIMIT returns the current limit.
xormode	Cursors can be drawn using XOR drawing. This can be useful, if the graph contains many colors, making cursor colour selection difficult. This parameter must be either ON or OFF. The default is ON.
/Graph	The graph handles special cursor keys.
/Shell	The graph sends KEY messages to the shell.
/Both	The graph handles special cursor keys and sends KEY messages.

PLAYCURSOR

SET graph PLAYCURSOR mode x y style useY color

Set position and configuration of the play cursor. The play cursor is a cursor whose position is set by this command and cannot be changed interactively by the user. It is used, for instance, to display the running cursor during signal playback (in this case the position is controlled by a timer).

argument	description
mode	The play cursor mode (ON or OFF).
x, y	The cursor position.
style	The cursor display style (CROSS, CROSSHAIR, HBAR, VBAR, HBARCROSS or VBARCROSS).
useY	Selects if y value is used (ON) or ignored (OFF).
color	The cursor color.

CURSORPOS

SET graph CURSORPOS cursor x [y] [/Select|Deselect]

Set the position of a cursor and optionally select (/Select) or deselect it (/Deselect). The value y is only needed if the cursor is not function bound. Note that if the cursor is not function bound, and you do not set the y value, it will be set to 0.

argument	description
cursor	The cursor index (1 or 2).
x, y	The new cursor positions.
/Select	Set the cursor to the selected state.
/Deselect	Set the cursor to a deselected state.

Context Menus

ADDPOPUP

SET graph ADDPOPUP item1 item2 …
SET graph ADDPOPUP tableitem /Table

Define the context menu items of a graph. One context menu can be added to each graph. If a context menu is already defined, it may be replaced by calling ADDPOPUP anew. The default entry "Copy/Print…" is automatically appended to the contextmenu. See the command command SET display ADDPOPUP for details.

When a context menu item is selected by the user, a CMITEM message is generated.

SETPOPUP

SET graph SETPOPUP index1 […] [/Enable|Disable /Check|Uncheck]

Active/deactivate and/or set or clear the check status of menu items.

DELETEPOPUP

SET graph DELPOPUP
SET graph DELETEPOPUP

Removes the items defined by the user, leaving only the default context menu item "Copy/Print…".

Print

SET graph PRINT CLIPBOARD
SET graph PRINT filename
SET graph PRINT PRINTER

Print or save the graph. Depending on the arguments, the graph will be copied to the clipboard (CLIPBOARD), saved to an image file (when supplying a filename) or actually printed to an actual printing device (PRINTER). In the letter case, the printing device must be capable of image output, meaning that daisywheel printers, teletypes, chain printers and the like are precluded.

The options /Print and /Screen are used to select the color scheme (see the Notes below). For file output, the file format is selected by the options /Enhancedmetafile (*.WMF), /Bitmap (*.BMP) or /Gnp (*.PNG). Once started, the operation is performed in the background and a STOP message is sent when the operation is finished.

Metasegments & Markers

DELETEMARKER

SET graph DELETEMARKER
SET graph DELMARKER
SET graph DELETEMARKER [msid] /X
SET graph DELMARKER [msid] /X

Without msid supplied, the command will delete all segement and label markers from the graph. With the ID of an existing meta segment supplied (msid), only the respective metasegment will be annihilated.

MARKERS

SET graph MARKERS mode auto font color msfont mslincol msfillcol mstextcol

Assign settings for markers and metasegments. The settings for metasegments are just default values and can be overwritten when creating a metasegment.

argument	description
mode	Turn markers ON or OFF.
auto	Turn automatic y positioning of markers ON or OFF.
font	The marker caption font.
color	The marker color.
msfont	The metasegment caption font.
mslinecol	The metasegment frame color.
msfillcol	The background color for filled metasegments.
mstextcol	The metasegment caption color.

ADDMARKER

The graph item's ADDMARKER command adds a marker, segment and or metasegment to a graph.

• A marker can display a string and point.
• A segment can display a line between two points and a string.
• A metasegment can display a line or box and a string, and can be clicked and moved.

All of them support the silent option /I causing error situations to generate warning messages rather than error messages (see The Silent Flag for details).

Add a marker

SET graph ADDMARKER text x y [ /U|D|M ] [ /L|R|B ] [ /I ]

Parameters not described here are described further below for the other variants of the command.

option	description
U, D or M	Specifies if the marker should have an arrow head pointing up (U), or down (D), or just be a vertical line (M). If no option is specified, the marker is a cross.

Add a segment

SET graph ADDMARKER text x1 x2 y [ /H|V ] [ /L|R ] [ /N ] [ /I ]

If the MARKERS option auto has been enabled, the segment's x position is chosen automatically (y must be specified but is ignored).

argument	description
text	The marker/segment caption.
x1, x2	The x range of the segment.
x	The x position of the marker.
y	The y position of the segment-marker line.
H or V	Specifies the segment style, with H indicating a horizontal bar and V indicating a vertical bar.
L, R or B	If specified, the text is shown to the left (L), right (R) or below (B) the marker. The default is showing the text above the marker.
L or R	Specifies the position of the text in relation to the segment, L indicating left aligned text and R indicating right aligned text. The default is centred.
N	If specified, no text is displayed.

Add or update a metasegment

Metasegments are a way to mark regions of graphs. Some of the advantages of metasegments are:

• metasegments be used as interactive "controls": they can be clicked upon and moved, causing messages to be sent to the shell.
• metasegments have many configuration settings and display styles
• metasegments may contain multi-line text

SET graph ADDMARKER /X id caption xmin xmax ymin ymax mode style linewidth linecolor fillmode fillcolor halign valign textcolor [ splitters ] [/Update] [/Redraw] [/Select|Deselect] [ /I ]
SET graph ADDMARKER /X tSettings [ /I ]

argument	description
id	The id string identifying this metasegment. This should not be a number or numeric expression.
caption	The text to be displayed in the metasegment. You can force a line break by including the text '\n' in the string.
xmin, xmax	The x range.
ymin, ymax	The y range.
mode	The mode defines whether a metasegment is only for display (STATIC), can be used like a button (BUTTON), or a button which can be moved (MBUTTON,MHBUTTON or MVBUTTON), or can be moved and resized (WINDOW, HWINDOW or VWINDOW).
style	The style specifies whether the metasegment can be displayed without a frame (NONE), as rectangle (BOX) or as two vertical lines connected by a horizontal line (BAR, like: |-|).
linewidth	The width of the frame lines (0, 1, 2, 3, etc.).
linecolor	The frame colour.
fillmode	The metasegment is filled with a background color/picture (FILLED) or not filled (TRANSPARENT).
fillcolor	The background color, the name of an image file (BMP,GIF,JPG or PNG) containing background picture, or the name of a bitmap (without option) or button resource (with option /Button) containing the background picture.
halign	The horizontal text alignment (CENTER, LEFT or RIGHT).
valign	The vertical text align (CENTER, TOP or BOTTOM).
textcolor	The text caption color.
splitters	The index of splitters where the metasegment should be visible (ON) or invisible (OFF); if not specified the metasegment is visible in all splitters.
tSettings	An extended table with the following fields: parameter string field string string field number number field E.g. you can create this table with the following macro command: #t := new table * * /E string:parameter string:string number:number if $#t[?] != table em -1 ; $#mac::error - failed to create table The table has one entry per parameter. Adding a parameter to the table works like this: $#t * parameter 'xmin' number '20' The parameter tSettings can contain any of the above parameters, but supports a number of newer ones too. With this version you can add a box and whiskers metasegment if you define the style as 'boxandwhiskers'. The following extra parameters are supported: parameter description font the font to be used for this metasegment (overrides default font set using the MARKERS command). The font must be specified using the STx font formatting string: e.g. 'arial:10:b' for a ten point bold arial font. See Fonts and Font Arguments for details. min the minimum value. Data type: number max the maximum value. Data type: number mean the mean value. Data type: number median the median value. Data type: number iqrmin the inter quantal range minimum. Data type: number iqrmax the inter quantal range maximum. Data type: number unit the unit. Data type: string valueaxis the axis (x or y) which the boxandwhisker values are on. Data type: string invertSelected true if the metasegment should be inverted on selection, false otherwise. The default is true. Data type: string modifyKeys defines which keys must be pressed to allow metasegment modification (i.e. allow user to move the metasegment). The strings control, shift, controlshift and none are supported. If this parameter is not specified, the default modify key (control) is used. Data type: string.

The metasegment splitter setting are defined by the specified splitter arguments (splitterX) and following options:

option	description
/Clear	The metasegment is only visible in the specified splitters.
/Merge	The metasegment is made visible in the specified splitters in addition to those already displayed.
/Except	The metasegment is made visible in all splitters except those specified.
/Toggle	Toggle the visibility of the metasegment in every splitter.
/Update	Change the settings of an existing metasegment. Otherwise create a new one, overwriting the old one if it already existed.
/Redraw	Explicitly redraw the metasegment. If this is not specified, then use the command SET graph ADDMARKER /X/R after all chanegs to redraw all metasegments.
/Select or /Deselect	Set the selection state of the metasegment.

Adding a normal metasegment to an existing graph:

#t := new table * * /E string:parameter string:string number:number integer:integer
if $#t[?] != table em -1 ; $#mac::error - failed to create table

$#t * parameter id string testid
$#t * parameter xmin number 20
$#t * parameter xmax number 80
$#t * parameter ymin number 20
$#t * parameter ymax number 80
$#t * parameter caption string this is the text caption
$#t * parameter mode string window
$#t * parameter style string box
$#t * parameter linewidth integer 1
$#t * parameter linecol string red
$#t * parameter fillmode string filled
$#t * parameter fillcolor string green
$#t * parameter halign string center
$#t * parameter valign string center
$#t * parameter splitters string 1 2

$#g addmarker $#t /Redraw

Here is an example of a box and whiskers metasegment to an existing graph.

#t := new table * * /E string:parameter string:string number:number
if $#t[?] != table em -1 ; $#mac::error - failed to create table

$#t * parameter id string testid
$#t * parameter xmin number 20
$#t * parameter xmax number 80
$#t * parameter ymin number 20
$#t * parameter ymax number 80
$#t * parameter caption string this is the text caption
$#t * parameter mode string window
$#t * parameter linewidth integer 2
$#t * parameter linecol string red
$#t * parameter halign string center
$#t * parameter valign string center
$#t * parameter splitters string 1 2
$#t * parameter valueaxis string x
$#t * parameter style string boxandwhiskers
$#t * parameter min number -20
$#t * parameter max number 75
$#t * parameter mean number 45
$#t * parameter median number 55
$#t * parameter iqrmin number 35
$#t * parameter iqrmax number 65
$#t * parameter unit string dB

$#g addmarker $#t /Redraw

Selections

"Selections" can be used to mark polygon areas of a graph. A selection can be moved and redrawn by the user using the mouse.

Selections are created, modified and deleted using the graph command SET graph SELECTION, first implemented in STx 3.10.

Activating and deactivating selections

SELECTION ACTIVATE

SET graph SELECTION ACTIVATE id [ ON|OFF ]

Activate the selection identified by id. If OFF is specified, then this command deactivates the selection.

SELECTION DEACTIVATE

SET graph SELECTION DEACTIVATE id

Deactivate the selection identified by id.

Creating selections

SELECTION SET

SET graph SELECTION SET id tSelection

Creates a new selection, or changes the polygon of an existing selection.

argument	description
id	The id of the selection. If the selection does not yet exist, it is created.
tSelection	A two field parameter table describing the selection's boundary as a vector of x/y coordinates.

Deleting selections

SELECTION DELETE

SET graph SELECTION DELETE cmd [ id ]

The DELETE subcommand can be used to delete one or more selections.

argument	description
cmd	One of the following keywords: ALL delete all existing selections ACTIVE delete the active selection. ID delete the selection with the specified id.
id	The id of the selection to delete (only in conjunction with the cmd ID).

Listing existing selections

SELECTION LIST

SET graph SELECTION LIST tList

The LIST subcommand fills a table with a list of the existing selections in the graph. The exact details which are returned are determined by the table field names.

argument

description

tList

An extended table with fields specifying which attributes should be retrieved. Currently the following field names are supported: activated 1 if the selection is active. 0 otherwise. boundrect returns the bounding rectangle in world coordinates (a space separated list: xmin xmax ymin ymax) id returns the id of the selection modified 1 if the selection has been modified on screen by the user since the last SELECTION SET command. 0 otherwise. splitters returns the splitters in which this selection is visible (a bit mask: e.g. 3 = 1st and 2nd splitter, 2 = just the second splitter) text returns the selection's text

// example
#tList := new table * * /e string:id string:splitters string:boundrect
if '$#tList[?]' != 'table' em -1 ; $#mac::ERROR - failed to create #tList table
$#graph SELECTION LIST $#tList
showitem $#tList ; contents of 'list' table

Modifying default and existing selection settings

You can modify the way an existing selection looks and behaves using the SET graph SETTINGS subcommand.

SELECTION SETTINGS

SET graph SELECTION SETTINGS tSettings

Set the default settings for all new selections, modify all selections in one go, or modify an existing selection's settings.

The settings which can be modified include a selection's color, it's transparency, any text it should display, and which graph splitters it should be visible in.

argument

description

tSettings

An extended table with four fields (string:parameter string:string num:number int:integer). Currently the following parameters are supported: activecolor the color when active id the id of the selection to set settings for. If no id is specified, all selections will be set. inactivecolor the color when inactive linecolor the color used to draw an inactive selection (and text). splitters a bit mask, specifying in which splitters this selection should be visible (0 for none, 255 for all 8 splitters). text a string to be displayed in the selection. The character sequence '\n' will force a line break when the text is displayed. transparency specify a selection's transparency with a value between 0 (opaque) and 100 (transparent).

Retrieving a selection

SELECTION GET

SET graph SELECTION GET id tSelection

Retrieves the selection's current polygon.

argument	description
id	The id of the selection. If the selection does not yet exist, it is created.
tSelection	A two field parameter table to receive a vector of x/y coordinates.