Programmer Guide/Shell Items/Graph/SET GRAPH: Difference between revisions
(155 intermediate revisions by 3 users not shown) | |||
Line 1: | Line 1: | ||
{{DISPLAYTITLE:{{SUBPAGENAME}}}} | {{DISPLAYTITLE:{{SUBPAGENAME}}}} | ||
{{Graph Item}} | |||
A [[Programmer_Guide/Shell_Items/Graph|graph]] consists of eight splitters. It has one <code>X</code> input (which is not always used), a user-defined number of <code>Y</code> inputs and a <code>CURSOR</code> output. Each <code>Y</code> input can be used to display a function (for some functions, in combination with the <code>X</code> input). All splitters in a graph and all functions displayed in a graph use the same <code>X</code> and <code>Y</code> 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 <code>SPECTROGRAM</code> and a <code>WAVEFORM</code> 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 <code>/Print</code>. | |||
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 <code>/Apply</code> can be used with any graph-item command. | 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 <code>/Apply</code> can be used with any graph-item command. | ||
Line 12: | Line 11: | ||
==Inputs and plots== | ==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 <code>SET graph X</code> and <code>SET graph Y</code> commands. | 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 [[Programmer_Guide/Shell_Items/File/NEW_FILE#GDX_Files|GDX]] file) and the graph's inputs using the following <code>SET graph X</code> and <code>SET graph Y</code> commands. | ||
===Connecting graph inputs=== | ===Connecting graph inputs=== | ||
Line 22: | Line 21: | ||
The graph item's <code>X</code> command configures a graph's x-axis data input. The exact configuration necessary depends on the type of plot which will be drawn. | The graph item's <code>X</code> command configures a graph's x-axis data input. The exact configuration necessary depends on the type of plot which will be drawn. | ||
SET <var>graph</var> Y <var>index data function splitter params</var> / | SET <var>graph</var> Y <var>index</var> <var>data</var> <var>function</var> <var>splitter</var> <var>params</var> /Realtime | ||
The graph item's <code>Y</code> command configures the graph's y-axis data input. The <var>function</var> parameter specifies which type of plot will be drawn. These plots are described individually in more detail below. | The graph item's <code>Y</code> command configures the graph's y-axis data input. The <var>function</var> parameter specifies which type of plot will be drawn. These plots are described individually in more detail below. | ||
Line 39: | Line 38: | ||
|- | |- | ||
| <var>splitter</var> | | <var>splitter</var> | ||
| The number of the graph splitter index (1 | | The number of the graph splitter index (1…8) where the function should be displayed. Note that splitter visibility is set using the <code>SPLITTERS</code> command. | ||
|- | |- | ||
| <var>params</var> | | <var>params</var> | ||
| The function plot configuration parameters (see the specific plot below). | | The function plot configuration parameters (see the specific plot below). | ||
|- | |- | ||
| < | | <code>/Realtime</code> | ||
| The real-time option /R causes the function to be re-displayed each time an input is updated. | | The real-time option <code>/R</code> 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 <code>SET graph ORIENTATION</code>. Use of the options /Horizontal and /Vertical is no longer supported. | 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 [[Shell_Items/Graph/SET_GRAPH#ORIENTATION|<code>SET graph ORIENTATION</code>]]. Use of the options <code>/Horizontal</code> and <code>/Vertical</code> is no longer supported. | ||
=== Disconnecting graph inputs === | === Disconnecting graph inputs === | ||
Line 69: | Line 68: | ||
The {{STX}} graph item can draw a number of different plot types. | The {{STX}} graph item can draw a number of different plot types. | ||
====XYPLOT==== | ====XYPLOT / FUNCTION==== | ||
SET <var>graph</var> Y <var>index yout</var> XYPLOT <var>splitter color style line width sym</var> [/F=noPlotValue] [/Realtime] | SET <var>graph</var> Y <var>index</var> <var>yout</var> XYPLOT <var>splitter</var> <var>color</var> <var>style</var> <var>line</var> <var>width</var> <var>sym</var> [/F=noPlotValue] [/Realtime] | ||
Display a two-dimensional function plot: Y<sub>i</sub> = f(X<sub>i</sub>). The outputs assigned to the X and Y inputs must be vectors of the same length. The option <code>/F=<var>noplot</var></code> can be used to suppress plotting all the points where Y<sub>i</sub> equals <var>noplot</var> (useful for f0-tracks). If the option <code>/Realtime</code> is used, the function is redisplayed each time an input is updated. Otherwise, the function is displayed on synchronisation (when the SPU stops). The <code>DASH</code> and <code>DOT</code> line styles only support widths of <code>0</code>. | Display a two-dimensional function plot: Y<sub>i</sub> = f(X<sub>i</sub>). The outputs assigned to the X and Y inputs must be vectors of the same length. The option <code>/F=<var>noplot</var></code> can be used to suppress plotting all the points where Y<sub>i</sub> equals <var>noplot</var> (useful for f0-tracks). If the option <code>/Realtime</code> is used, the function is redisplayed each time an input is updated. Note that zooming is '''not possible''' in conjunction with the <code>/Realtime</code> flag. Otherwise, the function is displayed on synchronisation (when the SPU stops). The <code>DASH</code> and <code>DOT</code> line styles only support widths of <code>0</code>. The keywords '''XYPLOT''' and '''FUNCTION''' are interchangeable. | ||
{|class="einrahmen" | {|class="einrahmen" | ||
Line 88: | Line 87: | ||
|- | |- | ||
| <var>style</var> | | <var>style</var> | ||
| The plot style. Either dotted (<code>POINTS</code>), a line (<code>LINES</code>), a solid area (<code>AREA</code>) or no line (<code>NONE</code>). | | The plot style. Either dotted (<code>POINTS</code>), a line (<code>LINES</code>), a solid area (<code>AREA</code>) or no line (<code>NONE</code>). 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. | ||
|- | |- | ||
| <var>line</var> | | <var>line</var> | ||
Line 99: | Line 98: | ||
| The symbol to use at each parameter (<code>NONE</code>, <code>SQUARE</code>, <code>TRIANGLE</code>, <code>CIRCLE</code>, <code>CROSS</code> or <code>DIAMOND</code>). | | The symbol to use at each parameter (<code>NONE</code>, <code>SQUARE</code>, <code>TRIANGLE</code>, <code>CIRCLE</code>, <code>CROSS</code> or <code>DIAMOND</code>). | ||
|- | |- | ||
| < | | <code>/F=<var>noPlotValue</var></code> | ||
| Use this option to suppress a particular value (<var>noPlotValue</var>) from the plot | | Use this option to suppress a particular value (<var>noPlotValue</var>) from the plot | ||
|} | |} | ||
Line 109: | Line 108: | ||
====PARAMETER==== | ====PARAMETER==== | ||
SET <var>graph</var> Y <var>index yout</var> PARAMETER <var>splitter nfrm color style line width</var> [/F=noplot /Realtime] | SET <var>graph</var> Y <var>index</var> <var>yout</var> PARAMETER <var>splitter</var> <var>nfrm</var> <var>color</var> <var>style</var> <var>line</var> <var>width</var> <var>sym</var> [/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 / | 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 <code>/F</code> and <code>/Realtime</code> have the same meaning as for <code>[[#XYPLOT / FUNCTION|XYPLOT]]</code>. 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 <code>DASH</code> and <code>DOT</code> line styles only support widths of <code>0</code>. | ||
{|class="einrahmen" | {|class="einrahmen" | ||
Line 132: | Line 131: | ||
|- | |- | ||
| <var>width</var> | | <var>width</var> | ||
| The line width (<code>0</code> | | The line width (<code>0</code>…<code>4</code> – <code>SOLID</code>, <code>0</code> – <code>DASH</code> and <code>DOT</code>) | ||
|- | |||
| <var>sym</var> | |||
| The symbol to use at each parameter (<code>NONE</code>, <code>SQUARE</code>, <code>TRIANGLE</code>, <code>CIRCLE</code>, <code>CROSS</code> or <code>DIAMOND</code>). | |||
|} | |} | ||
Line 141: | Line 143: | ||
====WATERFALL==== | ====WATERFALL==== | ||
SET <var>graph</var> Y <var>index yout</var> WATERFALL <var>splitter nfrm nspectra lcolor fcolor style width</var> [/Realtime] | SET <var>graph</var> Y <var>index</var> <var>yout</var> WATERFALL <var>splitter</var> <var>nfrm</var> <var>nspectra</var> <var>lcolor</var> <var>fcolor</var> <var>style</var> <var>width</var> [/Realtime] | ||
SET <var>graph</var> X <var>xout</var> | SET <var>graph</var> X <var>xout</var> | ||
Line 168: | Line 170: | ||
|- | |- | ||
| <var>style</var> | | <var>style</var> | ||
| The line style (<code>SOLID</code> | | The line style (<code>SOLID</code>, <code>DASH</code> or <code>DOT</code>). | ||
|- | |- | ||
| <var>width</var> | | <var>width</var> | ||
Line 178: | Line 180: | ||
====SPECTROGRAM==== | ====SPECTROGRAM==== | ||
SET <var>graph</var> Y <var>index ydata</var> SPECTROGRAM <var>splitter nframes amin amax palette</var> [ /R ] | ===== <code>SET graph Y</code> ===== | ||
SET <var>graph</var> Y <var>index</var> <var>ydata</var> SPECTROGRAM <var>splitter</var> <var>nframes</var> <var>amin</var> <var>amax</var> <var>palette</var> [ /R ] | |||
The output connected to | The output connected to Y<sub>num</sub> 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 <code>/R</code> is specified), or on synchronization (when the SPU stops). The whole spectrogram consists of <var>nfrm</var> spectra. The colours used to display the different amplitudes are defined using the <var>palette</var> parameter. | ||
{|class="einrahmen" | {|class="einrahmen" | ||
Line 186: | Line 190: | ||
|- | |- | ||
| <var>ydata</var> | | <var>ydata</var> | ||
| Either an SPU output or a GDX file item providing the magnitude vectors ( | | Either an SPU output or a [[Programmer_Guide/Shell_Items/File/NEW_FILE#GDX_Files|GDX]] file item providing the magnitude vectors (one spectrum per frame). | ||
|- | |- | ||
| <var>nframes</var> | | <var>nframes</var> | ||
| 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. | | The number of frames (spectra). If the <code>/R</code> option is specified, this parameter determines the number of frames displayed at any one time on screen. | ||
|- | |- | ||
| <var>amin, amax</var> | | <var>amin</var>, <var>amax</var> | ||
| The minimum and maximum magnitudes. | | The minimum and maximum magnitudes. | ||
|- | |- | ||
| <var>palette</var> | | <var>palette</var> | ||
| 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. | | 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 = (<var>amax</var> – <var>amin</var>) / nrgb | Mapping of y values to colors, with: i = 0 … nrgb-1; da = (<var>amax</var> – <var>amin</var>) / nrgb | ||
{| | {|class="keinrahmen" | ||
|- | |- | ||
|y < amin | |y < amin | ||
Line 213: | Line 217: | ||
See [[#Connecting_graph_inputs|Connecting graph inputs]] for parameters not described here. | See [[#Connecting_graph_inputs|Connecting graph inputs]] for parameters not described here. | ||
===== <code>SET graph X</code> ===== | |||
SET <var>graph</var> X <var>xdata</var> | SET <var>graph</var> X <var>xdata</var> | ||
Line 225: | Line 231: | ||
|} | |} | ||
===== 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 <code>XSCALE</code>, <code>YSCALE</code> and <code>ZSCALE</code>. | You can zoom into a spectrogram graph on three axes: time (x), frequency (y) and amplitude (z). Zooming is done using the scale commands <code>XSCALE</code>, <code>YSCALE</code> and <code>ZSCALE</code>. | ||
Line 231: | Line 237: | ||
====WAVEFORM==== | ====WAVEFORM==== | ||
SET <var>graph</var> Y <var>index yout</var> WAVEFORM <var>splitter nsmp color style scroll</var> [ /R ] | SET <var>graph</var> Y <var>index</var> <var>yout</var> WAVEFORM <var>splitter</var> <var>nsmp</var> <var>color</var> <var>style</var> <var>scroll</var> [ /R ] | ||
The waveform envelope is drawn using a min/max plot and optionally filled (<var>style</var><code>=AREA</code>). Each screen contains <var>nsmp</var> samples of the waveform, and the waveform is scrolled if more than <var>nsmp</var> samples are sent via the input Ynum. The argument <var>scroll</var> can set to <code>OFF</code> (or <code>0</code>) 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). | The waveform envelope is drawn using a min/max plot and optionally filled (<var>style</var><code>=AREA</code>). Each screen contains <var>nsmp</var> samples of the waveform, and the waveform is scrolled if more than <var>nsmp</var> samples are sent via the input Ynum. The argument <var>scroll</var> can set to <code>OFF</code> (or <code>0</code>) 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). | ||
{|class="einrahmen" | |||
!option!!description | |||
|- | |||
| <var>yout</var> | |||
| The waveform samples (a vector or a number). | |||
|- | |||
| <var>nsmp</var> | |||
| The number of samples per screen. | |||
|- | |||
| <var>color</var> | |||
| The line color (color name or rgb code). | |||
|- | |||
| <var>style</var> | |||
| The plot style (<code>LINES</code>, <code>AREA</code>). | |||
|- | |||
| <var>scroll</var> | |||
| Enable scrolling (<code>ON</code>|<code>1</code>) or disable scrolling (<code>OFF</code>|<code>0</code>). | |||
|} | |||
See [[#Connecting_graph_inputs|Connecting graph inputs]] for parameters not described here. | |||
Note that you must apply the settings to the graph (option <code>/A</code>) before synchronizing the inputs if the input data is to be correctly interpreted. | |||
== Configuration & Control == | |||
Configure the colours and layout of the graph. | Configure the colours and layout of the graph. | ||
===AXIS=== | ===AXIS=== | ||
SET graph AXIS <var>xLabel yLabel labelFont labelColor xTitle yTitle titleFont titleColor xUnit yUnit xBorder yBorder</var> | SET graph AXIS <var>xLabel</var> <var>yLabel</var> <var>labelFont</var> <var>labelColor</var> <var>xTitle</var> <var>yTitle</var> <var>titleFont</var> <var>titleColor</var> <var>xUnit</var> <var>yUnit</var> <var>xBorder</var> <var>yBorder</var> | ||
Configure the X and Y axis. If you are using a <code>WATERFALL</code> graph, you can configure the Z axis with the <code>ZSCALE</code> command. | Configure the X and Y axis. If you are using a <code>WATERFALL</code> graph, you can configure the Z axis with the <code>ZSCALE</code> command. | ||
{|class="einrahmen" | |||
!option!!description | |||
|- | |||
| <var>xLabel</var> | |||
| The position of x labels (<code>OFF</code>, <code>ABOVE</code>. <code>BELOW</code> or <code>BOTH</code>). | |||
|- | |||
| <var>yLabel</var> | |||
| The position of y labels (<code>OFF</code>, <code>LEFT</code>, <code>RIGHT</code> or <code>BOTH</code>). | |||
|- | |||
| <var>labelFont</var> | |||
| The label font. | |||
|- | |||
| <var>labelColor</var> | |||
| The label color. | |||
|- | |||
| <var>xTitle</var> | |||
| The position of x axis text (<code>OFF</code>, <code>ABOVE</code>, <code>BELOW</code> or <code>BOTH</code>). | |||
|- | |||
| <var>yTitle</var> | |||
| The position of y axis text (<code>OFF</code>, <code>LEFT</code>, <code>RIGHT</code> or <code>BOTH</code>). | |||
|- | |||
| <var>titleFont</var> | |||
| The title font. | |||
|- | |||
| <var>titleColor</var> | |||
| The color for titles. | |||
|- | |||
| <var>xUnit</var>, <var>yUnit</var> | |||
| Display x and y axis units (<code>OFF</code> or <code>ON</code>) . | |||
|- | |||
| <var>xBorder</var>, <var>yBorder</var> | |||
| The width of the border at the edge of the window on the x axis and y axis (in pixels). The default is <code>1</code>. | |||
|} | |||
===BGCOLOR=== | ===BGCOLOR=== | ||
SET <var>graph</var> BGCOLOR <var>text draw</var> | SET <var>graph</var> BGCOLOR <var>text</var> <var>draw</var> | ||
Set background colors for the text and draw regions of a graph. | Set background colors for the text and draw regions of a graph. | ||
{| | {|class="einrahmen" | ||
!option!!description | |||
|- | |- | ||
|<var>text</var> | |<var>text</var> | ||
|background color for text regions | |background color for text regions | ||
|- | |- | ||
|draw | |<var>draw</var> | ||
|background color for draw regions | |background color for draw regions | ||
|} | |} | ||
===FRAME=== | ===FRAME=== | ||
SET graph FRAME <var>xscale yscale scalecolor grid gridcolor xsteps ysteps major minor</var> | SET graph FRAME <var>xscale</var> <var>yscale</var> <var>scalecolor</var> <var>grid</var> <var>gridcolor</var> <var>xsteps</var> <var>ysteps</var> <var>major</var> <var>minor</var> | ||
Configure the graph's frame, scale and grid. Note if you can use the graph item commands <code>XSCALE</code>, <code>YSCALE</code> and <code>ZSCALE</code> to set the scale, grid and tick values. | Configure the graph's frame, scale and grid. Note if you can use the graph item commands <code>XSCALE</code>, <code>YSCALE</code> and <code>ZSCALE</code> to set the scale, grid and tick values. | ||
Line 337: | Line 332: | ||
{| | {| | ||
|- | |- | ||
| | |xscale | ||
|draw x scale (<code>OFF</code> | |draw x scale (<code>OFF</code>, <code>ABOVE</code>, <code>BELOW</code> or <code>BOTH</code>) | ||
|- | |- | ||
|yscale | |yscale | ||
|draw y scale (<code>OFF</code> | |draw y scale (<code>OFF</code>, <code>LEFT</code>, <code>RIGHT</code> or <code>BOTH</code>) | ||
|- | |- | ||
|scalecolor | |scalecolor | ||
Line 347: | Line 342: | ||
|- | |- | ||
|grid | |grid | ||
|draw grid (<code>OFF</code> | |draw grid (<code>OFF</code>, <code>X</code>, <code>Y</code> or <code>BOTH</code>) | ||
|- | |- | ||
|gridcolor | |gridcolor | ||
|color for grid | |color for grid | ||
|- | |- | ||
|xsteps,ysteps | |xsteps, ysteps | ||
|number of minor x<nowiki> | |number of minor x<nowiki>/</nowiki>y ticks between labels | ||
|- | |- | ||
|major, minor | |major, minor | ||
|size of major | |size of major/minor ticks in pixels | ||
|} | |} | ||
Line 367: | Line 362: | ||
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 <code>ORIENTATION</code> command to rotate the graph and flip the direction in which the axes run. The <code>XSCALE</code> and <code>YSCALE</code> commands can also modify a graph's flip settings. | 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 <code>ORIENTATION</code> command to rotate the graph and flip the direction in which the axes run. The <code>XSCALE</code> and <code>YSCALE</code> commands can also modify a graph's flip settings. | ||
{|class="einrahmen" | |||
!option!!description | |||
|- | |||
| <var>rotation</var> | |||
| The angle in degrees by which to rotate the graph. Only the values <code>0</code>, <code>90</code>, <code>180</code> and <code>270</code> are supported. An asterisk (<code>*</code>) can be passed to retain the current rotation setting. Rotation is anti-clockwise. | |||
: | The rotation can also be specified thus: <code>0</code>|<code>1</code>|<code>2</code>|<code>3</code> where <code>0</code> means no rotation, <code>1</code> means 90 degree rotation etc. | ||
|- | |||
| <var>flip</var> | |||
| Determines whether the graph should be flipped on the x and y axis. The following values are supported: | |||
{|class="keinrahmen" | |||
|- | |||
| <code>0</code> | |||
| do not flip at all (default orientation). | |||
|- | |||
| <code>1</code> | |||
| flip on the x axis | |||
|- | |||
| <code>2</code> | |||
| flip on the y axis | |||
|- | |||
| <code>3</code> | |||
| flip on both the x and y axis. | |||
|- | |||
| <code>*</code> | |||
| do not change the current flip setting | |||
|} | |||
|} | |||
Note that you can retrieve the current orientation of a graph using the attribute <code>[[User Guide/Transcription/SPExL - Transcription Tool|!ORIENTATION]]</code>. | Note that you can retrieve the current orientation of a graph using the attribute <code>[[User Guide/Transcription/SPExL - Transcription Tool|!ORIENTATION]]</code>. | ||
Line 401: | Line 399: | ||
SET <var>graph</var> OVERVIEW [ <var>mode</var> ] | SET <var>graph</var> OVERVIEW [ <var>mode</var> ] | ||
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', 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. | 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. | ||
{|class="einrahmen" | |||
!option!!description | |||
|- | |||
| <var>mode</var> | |||
| One of the following values: | |||
{|class="keinrahmen" | |||
|- | |||
| <code>on</code> or <code>1</code> | |||
| Switch to ''overview'' mode. | |||
|- | |||
| <code>off</code> or <code>0</code> | |||
| Switch to ''view'' mode. | |||
|} | |||
|} | |||
:If neither is specified, the mode is toggled. | :If neither is specified, the mode is toggled. | ||
Line 419: | Line 424: | ||
===SPLITTERS=== | ===SPLITTERS=== | ||
SET <var>graph</var> SPLITTERS <var> | SET <var>graph</var> SPLITTERS <var>splitter<sub>1</sub></var> [<var>splitter<sub>2</sub></var>…] [/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. | 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. | ||
{|class="einrahmen" | |||
!option!!description | |||
|- | |||
| <var>splitter<sub>X</sub></var> | |||
| The index of the splitter to be displayed. This may be any integer from 1 to 8. | |||
|- | |||
| <code>/Merge</code> | |||
| Use the OR operator when setting the splitters. | |||
|} | |||
Example for displaying the first two splitters: | |||
$#graph splitters 1 2 | $#graph splitters 1 2 | ||
Line 437: | Line 444: | ||
===TITLE=== | ===TITLE=== | ||
SET <var>graph</var> TITLE <var>mode font color</var> [<var> | SET <var>graph</var> TITLE <var>mode</var> <var>font</var> <var>color</var> [<var>title<sub>1</sub></var> <var>title<sub>2</sub></var>] [/Settitle] | ||
Configure and/or set graph title. The option /Settitle can be used to set a new graph title without applying other settings. | Configure and/or set graph title. The option <code>/Settitle</code> can be used to set a new graph title without applying other settings. | ||
{|class="einrahmen" | |||
!option!!description | |||
|- | |||
| <var>mode</var> | |||
:<code>ON</code> | | Turn the graph's title on or off. The following values are supported: <code>ON</code> and <code>OFF</code> | ||
|- | |||
| <var>font</var> | |||
| A font argument as specified in Fonts and Font Argument Format. | |||
|- | |||
| <var>color</var> | |||
| A color argument as specified in Colors and Color Arguments. | |||
|- | |||
| <var>title<sub>1</sub></var>, <var>title<sub>2</sub></var> | |||
| The text to be displayed (one or two lines). | |||
|} | |||
=== XSCALE === | === XSCALE === | ||
SET <var>graph</var> XSCALE <var>min max unit text</var> [<var>formatStr</var>|<var>table</var>] [/Invert] [/Log] [/View] | SET <var>graph</var> XSCALE <var>min</var> <var>max</var> <var>unit</var> <var>text</var> [<var>formatStr</var>|<var>table</var>] [/Invert] [/Log] [/View] | ||
SET <var>graph</var> XSCALE [ <var>min</var> <var>max</var> ] /View | SET <var>graph</var> XSCALE [ <var>min</var> <var>max</var> ] /View | ||
Set the x scale range, title and unit string. | Set the x scale range, title and unit string. | ||
{|class="einrahmen" | |||
!option!!description | |||
|- | |||
| <var>min</var>, <var>max</var> | |||
| The minimum and maximum range of values on this scale. | |||
|- | |||
| <var>unit</var> | |||
| The text to be displayed as the unit on scale and in the cursor tooltip windows. | |||
|- | |||
| <var>text</var> | |||
| The title or description. Note that even if this is set here, it must be enabled using the <code>AXIS</code> command. | |||
|- | |||
| <var>formatStr</var> | |||
| A format string which is used to format the range values. See Format Strings and Rules for details. | |||
|- | |||
| <var>table</var> | |||
| An extended table containing alternative scale values. See scale definition table for a description of the table format. | |||
|- | |||
| <code>/Invert</code> | |||
| Invert the scale (x-axis - right to left, y-axis, top to bottom). Note that this is the same as the ORIENTATION command <code>$#graph ORIENTATION * 1</code>. | |||
|- | |||
| <code>/Log</code> | |||
| The scale is logarithmic (base 10). | |||
|- | |||
| <code>/View[=Reset]</code> | |||
| Set the view (section of whole range). | |||
|} | |||
If the option <code>/View</code> is specified, the <var>min</var> and <var>max</var> value are used to display a section of the whole range. If <code>Reset</code> is specified (e.g. <code>/View=Reset</code>), the <var>min</var>/<var>max</var> values are ignored (and can be left out) and the whole range is redisplayed. | |||
=== YSCALE === | === YSCALE === | ||
SET <var>graph</var> YSCALE <var>min max unit text</var> [<var>formatStr</var>|<var>table</var>] [/Invert] | SET <var>graph</var> YSCALE <var>min</var> <var>max</var> <var>unit</var> <var>text</var> [<var>formatStr</var>|<var>table</var>] [/Invert] | ||
SET <var>graph</var> YSCALE [ <var>min</var> <var>max</var> ] /View=[Reset] | SET <var>graph</var> YSCALE [ <var>min</var> <var>max</var> ] /View=[Reset] | ||
Set the y scale range, title | Set the y scale range, title and unit string. | ||
{|class="einrahmen" | |||
!option!!description | |||
|- | |||
| <var>min</var>, <var>max</var> | |||
| The minimum and maximum of scale (range). | |||
|- | |||
| <var>unit</var> | |||
| The text to be displayed as unit on scale and in cursor window. | |||
|- | |||
| <var>text</var> | |||
| The title or description. | |||
|- | |||
| <var>formatStr</var> | |||
| A format string which is used to format the range values. See Format Strings and Rules for details. | |||
|- | |||
| <var>table</var> | |||
| An extended table containing alternative scale values. See scale definition table for a description of the table format. | |||
|- | |||
| <code>/Invert</code> | |||
| Invert the scale (x-axis - right to left, y-axis, top to bottom). Note that this is the same as the ORIENTATION command <code>$#graph ORIENTATION * 2</code>. | |||
|- | |||
| <code>/View[=Reset]</code> | |||
| Set the view (section of whole range). | |||
|} | |||
If the option <code>/View</code> is specified, the <var>min</var> and <var>max</var> value are used to display a section of the whole range. If <code>Reset</code> is specified (e.g. <code>/View=Reset</code>), the <var>min</var>/<var>max</var> values are ignored and the whole range is redisplayed. | |||
=== ZSCALE === | === ZSCALE === | ||
SET <var>graph</var> ZSCALE <var>showScale</var> <var>min</var> <var>max</var> <var>nMinorStep</var> <var>showLabels</var> <var>showUnit</var> <var>unitText</var> <var>showTitle</var> <var>titleText</var> <var>xShrink</var> <var>yShrink</var> [<var>formatStr</var><nowiki>|</nowiki><var>table</var>] [/Invert] | |||
SET <var>graph</var> ZSCALE [ <var>min</var> <var>max</var> ] /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 <var>xShrink</var> and <var>yShrink</var> determine that amount of the available space for the graph is taken up with the x and y axis. | |||
{|class="einrahmen" | |||
!option!!description | |||
{| | |||
|- | |- | ||
|showScale | |showScale | ||
|Set the zscale visiblity (<code>OFF</code> | |Set the zscale visiblity (<code>OFF</code>, <code>LEFT</code>, <code>RIGHT</code> or <code>BOTH</code>). | ||
|- | |- | ||
|min | |min | ||
Line 561: | Line 558: | ||
|- | |- | ||
|showLabels | |showLabels | ||
|Set the label visibility (<code>OFF</code> | |Set the label visibility (<code>OFF</code>, <code>LEFT</code>, <code>RIGHT</code> or <code>BOTH</code>) | ||
|- | |- | ||
|showUnit | |showUnit | ||
|Set the unit visibility (<code>ON</code> | |Set the unit visibility (<code>ON</code> or <code>OFF</code>) | ||
|- | |- | ||
|unitText | |unitText | ||
Line 570: | Line 567: | ||
|- | |- | ||
|showTitle | |showTitle | ||
|Set the title visibility (<code>OFF</code> | |Set the title visibility (<code>OFF</code>, <code>LEFT</code>, <code>RIGHT</code> or <code>BOTH</code>) | ||
|- | |- | ||
|titleText | |titleText | ||
Line 583: | Line 580: | ||
|formatStr | |formatStr | ||
|A format string which is used to format the range values. See Format Strings and Rules for details. | |A format string which is used to format the range values. See Format Strings and Rules for details. | ||
|- | |||
| <code>/Invert</code> | |||
| Use this option to invert the scale. | |||
|- | |||
| <code>/View[=Reset]</code> | |||
| Set the view (section of whole range). | |||
|} | |} | ||
If the option <code>/View</code> is specified, the <var>min</var> and <var>max</var> value are used to display a section of the whole range. If <code>Reset</code> is specified (e.g. <code>/View=Reset</code>), the <var>min</var>/<var>max</var> values are ignored and the whole range is redisplayed. | |||
=== Scale definition table=== | |||
The graph item commands <code>[[#XSCALE|XSCALE]]</code>, <code>[[#YSCALE|YSCALE]]</code> and <code>[[#ZSCALE|ZSCALE]]</code> 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: | |||
The graph item commands <code>XSCALE</code>, <code>YSCALE</code> and <code>ZSCALE</code> 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: | |||
{| | {| | ||
Line 605: | Line 600: | ||
|- | |- | ||
|<code>type</code> | |<code>type</code> | ||
|A string field for the scale type (<code>LABEL</code> | |A string field for the scale type (<code>LABEL</code>, <code>MINORTICK</code>, <code>MAJORTICK</code>, <code>MINORGRID</code> or <code>MAJORGRID</code>). | ||
|- | |- | ||
|<code>label</code> | |<code>label</code> | ||
|A string field for the label text. This is only of used for entries of type <code>LABEL</code>. If the label field is not empty, the label field text is displayed at <code>pos</code>, otherwise the value of <code>pos</code> is displayed at the position <code>pos</code>. | |A string field for the label text. This is only of used for entries of type <code>LABEL</code>. If the label field is not empty, the label field text is displayed at <code>pos</code>, otherwise the value of <code>pos</code> is displayed at the position <code>pos</code>. | ||
|} | |} | ||
==Cursors== | ==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. | {{STX}} graph items support two graphical cursors, which can be used to mark points on a graph. See [[Programmer_Guide/Shell_Items/Graph/Introducing_Graph_Items#Cursors|Cursors]] for an introduction to the concept of cursors. | ||
===CURSORMODE=== | ===CURSORMODE=== | ||
{{/CURSORMODE}} | |||
===PLAYCURSOR=== | ===PLAYCURSOR=== | ||
SET <var>graph</var> PLAYCURSOR <var>mode</var> <var>x</var> <var>y</var> <var>style</var> <var>useY</var> <var>color</var> | |||
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). | 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). | ||
{|class="einrahmen" | |||
!argument!!description | |||
|- | |||
| <var>mode</var> | |||
| The play cursor mode (<code>ON</code> or <code>OFF</code>). | |||
|- | |||
| <var>x</var>, <var>y</var> | |||
| The cursor position. | |||
|- | |||
| <var>style</var> | |||
| The cursor display style (<code>CROSS</code>, <code>CROSSHAIR</code>, <code>HBAR</code>, <code>VBAR</code>, <code>HBARCROSS</code> or <code>VBARCROSS</code>). | |||
|- | |||
| <var>useY</var> | |||
| Selects if y value is used (<code>ON</code>) or ignored (<code>OFF</code>). | |||
|- | |||
| <var>color</var> | |||
| The cursor color. | |||
|} | |||
===CURSORPOS=== | ===CURSORPOS=== | ||
SET <var>graph</var> CURSORPOS <var>cursor x</var> [<var>y</var>] [/Select|Deselect] | |||
Set the position of a cursor and optionally select (/Select) or deselect it (/Deselect). The value <var>y</var> is only needed if the cursor is not function bound. | Set the position of a cursor and optionally select (/Select) or deselect it (/Deselect). The value <var>y</var> 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 <var>y</var> value, it will be set to 0. | ||
{|class="einrahmen" | |||
!argument!!description | |||
|- | |||
| <var>cursor</var> | |||
| The cursor index (<code>1</code> or <code>2</code>). | |||
|- | |||
| <var>x</var>, <var>y</var> | |||
| The new cursor positions. | |||
|- | |||
| <code>/Select</code> | |||
| Set the cursor to the selected state. | |||
|- | |||
| <code>/Deselect</code> | |||
| Set the cursor to a deselected state. | |||
|} | |||
==Context Menus== | ==Context Menus== | ||
Line 732: | Line 665: | ||
===ADDPOPUP=== | ===ADDPOPUP=== | ||
< | SET <var>graph</var> ADDPOPUP <var>item<sub>1</sub></var> <var>item<sub>2</sub></var> … | ||
SET <var>graph</var> ADDPOPUP <var>tableitem</var> /Table | |||
<code> | 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 <code>ADDPOPUP</code> anew. The default entry "Copy/Print…" is automatically appended to the contextmenu. See the command command <code>[[Programmer_Guide/Shell_Items/Dialog/SET_DIALOG#ADDPOPUP|SET display ADDPOPUP]]</code> for details. | ||
When a context menu item is selected by the user, a <code>[[Programmer_Guide/Shell_Items/Dialog/DISPLAY_and_DIALOG_Messages#CMITEM|CMITEM]]</code> message is generated. | |||
When a context menu item is selected by the user, a <code>CMITEM</code> message is generated. | |||
===SETPOPUP=== | ===SETPOPUP=== | ||
SET <var>graph</var> SETPOPUP <var>index1</var> […] [/Enable|Disable /Check|Uncheck] | |||
Active/deactivate and/or set or clear the check status of menu items. | |||
===DELETEPOPUP=== | ===DELETEPOPUP=== | ||
SET <var>graph</var> DELPOPUP | |||
SET <var>graph</var> DELETEPOPUP | |||
Removes the items defined by the user, leaving the default context menu item | Removes the items defined by the user, leaving only the default context menu item "Copy/Print…". | ||
==Print== | ==Print== | ||
SET <var>graph</var> PRINT CLIPBOARD | |||
SET <var>graph</var> PRINT <var>filename</var> | |||
SET <var>graph</var> PRINT PRINTER | |||
Print to | Print or save the graph. Depending on the arguments, the graph will be copied to the clipboard (<code>CLIPBOARD</code>), saved to an image file (when supplying a filename) or actually printed to an actual printing device (<code>PRINTER</code>). 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 <code>/Print</code> and <code>/Screen</code> are used to select the color scheme (see the [[Notes below]]). For file output, the file format is selected by the options <code>/Enhancedmetafile</code> (*.WMF), <code>/Bitmap</code> (*.BMP) or <code>/Gnp</code> (*.PNG). Once started, the operation is performed in the background and a <code>STOP</code> message is sent when the operation is finished. | |||
==Metasegments & Markers== | ==Metasegments & Markers== | ||
Line 774: | Line 699: | ||
===DELETEMARKER=== | ===DELETEMARKER=== | ||
SET <var>graph</var> DELETEMARKER | |||
SET <var>graph</var> DELMARKER | |||
SET <var>graph</var> DELETEMARKER [<var>msid</var>] /X | |||
SET <var>graph</var> DELMARKER [<var>msid</var>] /X | |||
< | |||
Without <var>msid</var> supplied, the command will delete ''all'' segement and label markers from the graph. With the ID of an existing meta segment supplied (<var>msid</var>), only the respective metasegment will be annihilated. | |||
=== MARKERS === | === MARKERS === | ||
SET <var>graph</var> MARKERS <var>mode auto font color msfont mslincol</var> <var>msfillcol mstextcol</var> | SET <var>graph</var> MARKERS <var>mode</var> <var>auto</var> <var>font</var> <var>color</var> <var>msfont</var> <var>mslincol</var> <var>msfillcol</var> <var>mstextcol</var> | ||
Assign settings for markers and metasegments. The settings for metasegments are just default values and can be overwritten when creating a metasegment. | Assign settings for markers and metasegments. The settings for metasegments are just default values and can be overwritten when creating a metasegment. | ||
{|class="einrahmen" | |||
!argument!!description | |||
|- | |||
| <var>mode</var> | |||
| Turn markers <code>ON</code> or <code>OFF</code>. | |||
|- | |||
| <var>auto</var> | |||
| Turn automatic y positioning of markers <code>ON</code> or <code>OFF</code>. | |||
|- | |||
| <var>font</var> | |||
| The marker caption font. | |||
|- | |||
| <var>color</var> | |||
| The marker color. | |||
|- | |||
| <var>msfont</var> | |||
| The metasegment caption font. | |||
|- | |||
| <var>mslinecol</var> | |||
| The metasegment frame color. | |||
|- | |||
| <var>msfillcol</var> | |||
| The background color for filled metasegments. | |||
|- | |||
| <var>mstextcol</var> | |||
| The metasegment caption color. | |||
|} | |||
=== ADDMARKER === | === ADDMARKER === | ||
Line 824: | Line 744: | ||
The graph item's <code>ADDMARKER</code> command adds a marker, segment and or metasegment to a graph. | The graph item's <code>ADDMARKER</code> command adds a marker, segment and or metasegment to a graph. | ||
A marker can display a string and point. | * 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 <code>/I</code> causing error situations to generate warning messages rather than error messages (see [[Programmer_Guide/Command_Reference_Options/Silent#The Silent Flag|The Silent Flag]] for details). | |||
==== Add a marker ==== | |||
SET <var>graph</var> ADDMARKER <var>text</var> <var>x</var> <var>y</var> [ /U|D|M ] [ /L|R|B ] [ /I ] | |||
Parameters not described here are described further below for the other variants of the command. | |||
{|class="einrahmen" | |||
!option!!description | |||
<code> | |- | ||
| <code>U</code>, <code>D</code> or <code>M</code> | |||
| Specifies if the marker should have an arrow head pointing up (<code>U</code>), or down (<code>D</code>), or just be a vertical line (<code>M</code>). If no option is specified, the marker is a cross. | |||
|} | |||
==== Add a segment ==== | |||
SET <var>graph</var> ADDMARKER <var>text</var> <var>x<sub>1</sub></var> <var>x<sub>2</sub></var> <var>y</var> [ /H|V ] [ /L|R ] [ /N ] [ /I ] | |||
If the <code>MARKERS</code> option <code>auto</code> has been enabled, the segment's <var>x</var> position is chosen automatically (<var>y</var> must be specified but is ignored). | If the <code>MARKERS</code> option <code>auto</code> has been enabled, the segment's <var>x</var> position is chosen automatically (<var>y</var> must be specified but is ignored). | ||
{|class="einrahmen" | |||
!argument!!description | |||
|- | |||
| <var>text</var> | |||
| The marker/segment caption. | |||
|- | |||
| <var>x<sub>1</sub></var>, <var>x<sub>2</sub></var> | |||
| The x range of the segment. | |||
|- | |||
| <var>x</var> | |||
| The x position of the marker. | |||
|- | |||
| <var>y</var> | |||
| The y position of the segment-marker line. | |||
|- | |||
| <code>H</code> or <code>V</code> | |||
| Specifies the segment style, with <code>H</code> indicating a horizontal bar and <code>V</code> indicating a vertical bar. | |||
|- | |||
| <code>L</code>, <code>R</code> or <code>B</code> | |||
| If specified, the text is shown to the left (<code>L</code>), right (<code>R</code>) or below (<code>B</code>) the marker. The default is showing the text above the marker. | |||
|- | |||
| <code>L</code> or <code>R</code> | |||
| Specifies the position of the text in relation to the segment, <code>L</code> indicating left aligned text and <code>R</code> indicating right aligned text. The default is centred. | |||
|- | |||
| <code>N</code> | |||
| 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 <var>graph</var> ADDMARKER /X <var>id</var> <var>caption</var> <var>xmin</var> <var>xmax</var> <var>ymin</var> <var>ymax</var> <var>mode</var> <var>style</var> <var>linewidth</var> <var>linecolor</var> <var>fillmode</var> <var>fillcolor</var> <var>halign</var> <var>valign</var> <var>textcolor</var> [ <var>splitters</var> ] [/Update] [/Redraw] [/Select|Deselect] [ /I ] | |||
SET <var>graph</var> ADDMARKER /X <var>tSettings</var> [ /I ] | |||
;<var> | {|class="einrahmen" | ||
!argument!!description | |||
|- | |||
| <var>id</var> | |||
| The id string identifying this metasegment. This should not be a number or numeric expression. | |||
|- | |||
| <var>caption</var> | |||
| The text to be displayed in the metasegment. You can force a line break by including the text '<code>\n</code>' in the string. | |||
|- | |||
| <var>xmin</var>, <var>xmax</var> | |||
| The x range. | |||
|- | |||
| <var>ymin</var>, <var>ymax</var> | |||
| The y range. | |||
|- | |||
| <var>mode</var> | |||
| The mode defines whether a metasegment is only for display (<code>STATIC</code>), can be used like a button (<code>BUTTON</code>), or a button which can be moved (<code>MBUTTON</code>,<code>MHBUTTON</code> or <code>MVBUTTON</code>), or can be moved and resized (<code>WINDOW</code>, <code>HWINDOW</code> or <code>VWINDOW</code>). | |||
|- | |||
| <var>style</var> | |||
| The style specifies whether the metasegment can be displayed without a frame (<code>NONE</code>), as rectangle (<code>BOX</code>) or as two vertical lines connected by a horizontal line (<code>BAR</code>, like: <nowiki>|-|</nowiki>). | |||
|- | |||
| <var>linewidth</var> | |||
| The width of the frame lines (0, 1, 2, 3, etc.). | |||
|- | |||
| <var>linecolor</var> | |||
| The frame colour. | |||
|- | |||
| <var>fillmode</var> | |||
| The metasegment is filled with a background color/picture (<code>FILLED</code>) or not filled (<code>TRANSPARENT</code>). | |||
|- | |||
| <var>fillcolor</var> | |||
| 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. | |||
|- | |||
| <var>halign</var> | |||
| The horizontal text alignment (<code>CENTER</code>, <code>LEFT</code> or <code>RIGHT</code>). | |||
|- | |||
| <var>valign</var> | |||
| The vertical text align (<code>CENTER</code>, <code>TOP</code> or <code>BOTTOM</code>). | |||
|- | |||
| <var>textcolor</var> | |||
| The text caption color. | |||
|- | |||
| <var>splitters</var> | |||
| The index of splitters where the metasegment should be visible (<code>ON</code>) or invisible (<code>OFF</code>); if not specified the metasegment is visible in all splitters. | |||
|- | |||
| <var>tSettings</var> | |||
| An extended table with the following fields: | |||
{| class="keinrahmen" | |||
|- | |||
| 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 <var>tSettings</var> 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: | |||
{|class="einrahmen" | |||
!parameter!!description | |||
|- | |||
| <code>font</code> | |||
| the font to be used for this metasegment (overrides default font set using the <code>MARKERS</code> 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. | |||
|- | |||
| <code>min</code> | |||
| the minimum value. Data type: number | |||
|- | |||
| <code>max</code> | |||
| the maximum value. Data type: number | |||
|- | |||
| <code>mean</code> | |||
| the mean value. Data type: number | |||
|- | |||
| <code>median</code> | |||
| the median value. Data type: number | |||
|- | |||
| <code>iqrmin</code> | |||
| the inter quantal range minimum. Data type: number | |||
|- | |||
| <code>iqrmax</code> | |||
| the inter quantal range maximum. Data type: number | |||
|- | |||
| <code>unit</code> | |||
| the unit. Data type: string | |||
|- | |||
| <code>valueaxis</code> | |||
| the axis (<code>x</code> or <code>y</code>) which the boxandwhisker values are on. Data type: string | |||
|- | |||
| <code>invertSelected</code> | |||
| <code>true</code> if the metasegment should be inverted on selection, <code>false</code> otherwise. The default is <code>true</code>. Data type: string | |||
|- | |||
| <code>modifyKeys</code> | |||
| defines which keys must be pressed to allow metasegment modification (i.e. allow user to move the metasegment). The strings <code>control</code>, <code>shift</code>, <code>controlshift</code> and <code>none</code> 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 (<var>splitterX</var>) and following options: | The metasegment splitter setting are defined by the specified splitter arguments (<var>splitterX</var>) and following options: | ||
{|class="einrahmen" | |||
!option!!description | |||
|- | |||
| <code>/Clear</code> | |||
| The metasegment is only visible in the specified splitters. | |||
|- | |||
| <code>/Merge</code> | |||
| The metasegment is made visible in the specified splitters in addition to those already displayed. | |||
|- | |||
| <code>/Except</code> | |||
| The metasegment is made visible in all splitters except those specified. | |||
|- | |||
| <code>/Toggle</code> | |||
| Toggle the visibility of the metasegment in every splitter. | |||
|- | |||
| <code>/Update</code> | |||
| Change the settings of an existing metasegment. Otherwise create a new one, overwriting the old one if it already existed. | |||
|- | |||
| <code>/Redraw</code> | |||
| Explicitly redraw the metasegment. If this is not specified, then use the command <code>SET graph ADDMARKER /X/R</code> after all chanegs to redraw all metasegments. | |||
|- | |||
| <code>/Select</code> or <code>/Deselect</code> | |||
| Set the selection state of the metasegment. | |||
|} | |||
Adding a normal metasegment to an existing graph: | |||
$#t * parameter id string testid | #t := new table * * /E string:parameter string:string number:number integer:integer | ||
$#t * parameter xmin number 20 | if $#t[?] != table em -1 ; $#mac::error - failed to create table | ||
$#t * parameter xmax number 80 | |||
$#t * parameter ymin number 20 | $#t * parameter id string testid | ||
$#t * parameter ymax number 80 | $#t * parameter xmin number 20 | ||
$#t * parameter caption string this is the text caption | $#t * parameter xmax number 80 | ||
$#t * parameter mode string window | $#t * parameter ymin number 20 | ||
$#t * parameter linewidth integer 1 | $#t * parameter ymax number 80 | ||
$#t * parameter linecol string red | $#t * parameter caption string this is the text caption | ||
$#t * parameter fillmode string filled | $#t * parameter mode string window | ||
$#t * parameter | $#t * parameter style string box | ||
$#t * parameter halign string center | $#t * parameter linewidth integer 1 | ||
$#t * parameter valign string center | $#t * parameter linecol string red | ||
$#t * parameter splitters string 1 2 | $#t * parameter fillmode string filled | ||
$#t | $#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. | Here is an example of a box and whiskers metasegment to an existing graph. | ||
#t := new table * * /E string:parameter string:string number:number | |||
#t := new table * * /E string:parameter string:string number:number | if $#t[?] != table em -1 ; $#mac::error - failed to create table | ||
if $#t[?] != table em -1 ; $#mac::error - failed to create table | |||
$#t * parameter id string testid | |||
$#t * parameter id string testid | $#t * parameter xmin number 20 | ||
$#t * parameter xmin number 20 | $#t * parameter xmax number 80 | ||
$#t * parameter xmax number 80 | $#t * parameter ymin number 20 | ||
$#t * parameter ymin number 20 | $#t * parameter ymax number 80 | ||
$#t * parameter ymax number 80 | $#t * parameter caption string this is the text caption | ||
$#t * parameter caption string this is the text caption | $#t * parameter mode string window | ||
$#t * parameter mode string window | $#t * parameter linewidth integer 2 | ||
$#t * parameter linewidth integer 2 | $#t * parameter linecol string red | ||
$#t * parameter linecol string red | $#t * parameter halign string center | ||
$#t * parameter halign string center | $#t * parameter valign string center | ||
$#t * parameter valign string center | $#t * parameter splitters string 1 2 | ||
$#t * parameter splitters string 1 2 | $#t * parameter valueaxis string x | ||
$#t * parameter valueaxis string x | $#t * parameter style string boxandwhiskers | ||
$#t * parameter style string boxandwhiskers | $#t * parameter min number -20 | ||
$#t * parameter min number -20 | $#t * parameter max number 75 | ||
$#t * parameter max number 75 | $#t * parameter mean number 45 | ||
$#t * parameter mean number 45 | $#t * parameter median number 55 | ||
$#t * parameter median number 55 | $#t * parameter iqrmin number 35 | ||
$#t * parameter iqrmin number 35 | $#t * parameter iqrmax number 65 | ||
$#t * parameter iqrmax number 65 | $#t * parameter unit string dB | ||
$#t * parameter unit string dB | |||
$#g addmarker $#t /Redraw | |||
== Selections == | == 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 <code>SELECTION</code>. | Selections are created, modified and deleted using the graph command <code>SET graph SELECTION</code>, first implemented in {{STX}} 3.10. | ||
===Activating and deactivating selections=== | |||
==== <code>SELECTION ACTIVATE</code> ==== | |||
SET <var>graph</var> SELECTION ACTIVATE <var>id</var> [ ON|OFF ] | |||
Activate the selection identified by <var>id</var>. If <code>OFF</code> is specified, then this command deactivates the selection. | Activate the selection identified by <var>id</var>. If <code>OFF</code> is specified, then this command deactivates the selection. | ||
==== | ==== <code>SELECTION DEACTIVATE</code> ==== | ||
SET <var>graph</var> SELECTION DEACTIVATE <var>id</var> | |||
Deactivate the selection identified by <var>id</var>. | Deactivate the selection identified by <var>id</var>. | ||
=== Creating selections === | |||
==== | ==== <code>SELECTION SET</code> ==== | ||
SET <var>graph</var> SELECTION SET <var>id</var> <var>tSelection</var> | |||
Creates a new selection, or changes the polygon of an existing selection. | Creates a new selection, or changes the polygon of an existing selection. | ||
{|class="einrahmen" | |||
!argument!!description | |||
|- | |||
| <var>id</var> | |||
| The id of the selection. If the selection does not yet exist, it is created. | |||
|- | |||
| <var>tSelection</var> | |||
| A two field parameter table describing the selection's boundary as a vector of x/y coordinates. | |||
|} | |||
=== Deleting selections === | |||
==== | ==== <code>SELECTION DELETE</code> ==== | ||
SET <var>graph</var> SELECTION DELETE <var>cmd</var> [ <var>id</var> ] | |||
The <code>DELETE</code> subcommand can be used to delete one or more selections. | The <code>DELETE</code> subcommand can be used to delete one or more selections. | ||
{|class="einrahmen" | |||
!argument!!description | |||
|- | |||
| <var>cmd</var> | |||
| One of the following keywords: | |||
{| class="keinrahmen" | |||
|- | |||
| <code>ALL</code> | |||
| delete all existing selections | |||
|- | |||
| <code>ACTIVE</code> | |||
| delete the active selection. | |||
|- | |||
| <code>ID</code> | |||
| delete the selection with the specified id. | |||
|} | |||
|- | |||
| <var>id</var> | |||
| The id of the selection to delete (only in conjunction with the <var>cmd</var> <code>ID</code>). | |||
|} | |||
=== Listing existing selections === | |||
==== | ==== <code>SELECTION LIST</code> ==== | ||
SET <var>graph</var> SELECTION LIST <var>tList</var> | |||
The <code>LIST</code> 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. | The <code>LIST</code> 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. | ||
<var>tList</var> | {|class="einrahmen" | ||
!argument!!description | |||
|- | |||
| <var>tList</var> | |||
| An extended table with fields specifying which attributes should be retrieved. | |||
Currently the following field names are supported: | |||
{| class="keinrahmen" | |||
|- | |||
| <code>activated</code> | |||
| 1 if the selection is active. 0 otherwise. | |||
|- | |||
| <code>boundrect</code> | |||
| returns the bounding rectangle in world coordinates (a space separated list: <code>xmin xmax ymin ymax</code>) | |||
|- | |||
| <code>id</code> | |||
| returns the id of the selection | |||
|- | |||
| <code>modified</code> | |||
| 1 if the selection has been modified on screen by the user since the last SELECTION SET command. 0 otherwise. | |||
|- | |||
| <code>splitters</code> | |||
| returns the splitters in which this selection is visible (a bit mask: e.g. 3 = 1st and 2nd splitter, 2 = just the second splitter) | |||
|- | |||
| <code>text</code> | |||
| 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 <code>SETTINGS</code> subcommand. | You can modify the way an existing selection looks and behaves using the <code>SET graph SETTINGS</code> subcommand. | ||
==== | ==== <code>SELECTION SETTINGS</code> ==== | ||
SET <var>graph</var> SELECTION SETTINGS <var>tSettings</var> | |||
Set the default settings for all new selections, modify all selections in one go, or modify an existing selection's settings. | Set the default settings for all new selections, modify all selections in one go, or modify an existing selection's settings. | ||
Line 1,201: | Line 1,114: | ||
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. | 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. | ||
{|class="einrahmen" | |||
!argument!!description | |||
|- | |||
| <var>tSettings</var> | |||
| An extended table with four fields (string:parameter string:string num:number int:integer). Currently the following parameters are supported: | |||
{| class="keinrahmen" | |||
|<code>activecolor</code> | |||
| the color when active | |||
|- | |||
| <code>id</code> | |||
| the id of the selection to set settings for. If no id is specified, all selections will be set. | |||
|- | |||
| <code>inactivecolor</code> | |||
| the color when inactive | |||
|- | |||
| <code>linecolor</code> | |||
| the color used to draw an inactive selection (and text). | |||
|- | |||
| <code>splitters</code> | |||
| a bit mask, specifying in which splitters this selection should be visible (0 for none, 255 for all 8 splitters). | |||
|- | |||
| <code>text</code> | |||
| a string to be displayed in the selection. The character sequence '<code>\n</code>' will force a line break when the text is displayed. | |||
|- | |||
| <code>transparency</code> | |||
| specify a selection's transparency with a value between 0 (opaque) and 100 (transparent). | |||
|} | |||
|} | |||
=== Retrieving a selection === | |||
==== <code>SELECTION GET</code> ==== | |||
SET <var>graph</var> SELECTION GET <var>id</var> <var>tSelection</var> | |||
Retrieves the selection's current polygon. | Retrieves the selection's current polygon. | ||
{|class="einrahmen" | |||
!argument!!description | |||
|- | |||
| <var>id</var> | |||
| The id of the selection. If the selection does not yet exist, it is created. | |||
|- | |||
| <var>tSelection</var> | |||
| A two field parameter table to receive a vector of x/y coordinates. | |||
|} |
Latest revision as of 09:37, 18 October 2019
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.
Contents
- 1 Inputs and plots
- 2 Configuration & Control
- 3 Cursors
- 4 Context Menus
- 5 Print
- 6 Metasegments & Markers
- 7 Selections
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
|
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: | ||||||||||
flip | Determines whether the graph should be flipped on the x and y axis. The following values are supported:
|
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:
|
- 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…".
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:
#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:
|
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:
| ||||||
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:
|
// 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:
|
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. |