SET GRAPH

From STX Wiki
Jump to navigationJump to search
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: Yi = f(Xi). 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 Yi 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 Ynum 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.
Retrieved from "https://mediawiki.kfs.oeaw.ac.at/stx/docs/wiki/index.php?title=Programmer_Guide/Shell_Items/Graph/SET_GRAPH&oldid=10669"

Navigation menu

Personal tools