STX Wiki - User contributions [en]

Programmer Guide/Command Reference/EVAL/f0sp

2022-11-10T10:26:04Z

Admin:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{EVALFunctionTemplate}}
A simple f0 estimation from a log. spectrum.
;Usage:<code>f0sp(<var>sp</var>, <var>df</var>, <var>fmin</var>, <var>fmax</var>, <var>nc</var>)</code>
:;<var>sp</var>:log. spectrum
:;<var>df</var>:frequency resolution in Hz
:;<var>fmin</var>:minimum range for component search
:;<var>fmax</var>:maximum range for component search
:;<var>nc</var>:number of f0 components
;Result: f0 in Hz. Set to 0 if detection fails.
;Description:
# find all spectral peaks in the selected frequency range
# select the nc highest peaks
# find the smallest frequency difference of the selected peak (use lowest peak frequency as start value)
# use this difference to compuet harmonic mean of selected peaks

[[../#Functions|<function list>]]

User Guide/Waveform and Segmentation Viewer/Segments Dialog

2015-12-18T11:29:29Z

Admin:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{V1}}
The segments dialog is displayed on the right side of the [[User Guide/Waveform Plot and Segmentation/Control Dialog|control dialog]].

[[File:viewer_dialog_segments.png]]

It consists of a fixed part (the segment definition and the buttons) and a user defined part (the segment attributes). The controls for the attributes (in the example: Typ, Speaker, TR1, TR2) are defined in the associated audio segment template.

;ID:The ID (name) of the selected / new segment.
;Auto:Copy the next automatic segment name into field ID. The name format can be configured with the automatic segment names dialog.
;Seg.:Position and length (task expression) of the selected / new segment.
;Crs.:Use the position of the current cursor(s) to update the Seg. field.
;Ch.:Channel attribute value of the selected / new segment.
;Clear:Reset all segment attributes to default / empty values.
;Save:Save segment attributes. If a marker is selected, the segment is updated, otherwise a new segment is created.
;Edit:Save segment attributes and display the segment properties dialog (without dialog-template).
;Typ, Speaker, TR1, TR2:Controls containing the user defined attributes of the selected / new segment. The controls for the attributes (in the example: Typ, Speaker, TR1, TR2) are defined in the associated audio segment template. The fields ID, Seg., Ch. and the attribute fields are updated automatically when a segment marker is selected.

User Guide/Waveform and Segmentation Viewer/Segments Dialog

2015-12-18T11:28:44Z

Admin:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{V1}}

The segments dialog is displayed on the right side of the [[User Guide/Waveform Plot and Segmentation/Control Dialog|control dialog]].

[[File:viewer_dialog_segments.png]]

It consists of a fixed part (the segment definition and the buttons) and a user defined part (the segment attributes). The controls for the attributes (in the example: Typ, Speaker, TR1, TR2) are defined in the associated audio segment template.

ID

The ID (name) of the selected / new segment.

Auto

Copy the next automatic segment name into field ID. The name format can be configured with the automatic segment names dialog.

Seg.

Position and length (task expression) of the selected / new segment.

Crs.

Use the position of the current cursor(s) to update the Seg. field.

Ch.

Channel attribute value of the selected / new segment.

Clear

Reset all segment attributes to default / empty values.

Save

Save segment attributes. If a marker is selected, the segment is updated, otherwise a new segment is created.

Edit

Save segment attributes and display the segment properties dialog (without dialog-template).

Typ, Speaker, TR1, TR2

Controls containing the user defined attributes of the selected / new segment. The controls for the attributes (in the example: Typ, Speaker, TR1, TR2) are defined in the associated audio segment template.

The fields ID, Seg., Ch. and the attribute fields are updated automatically when a segment marker is selected.

User Guide/Waveform and Segmentation Viewer/Segments Dialog

2015-12-18T11:27:14Z

Admin:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{UG_V1}}

The segments dialog is displayed on the right side of the [[User Guide/Waveform Plot and Segmentation/Control Dialog|control dialog]].

[[File:viewer_dialog_segments.png]]

It consists of a fixed part (the segment definition and the buttons) and a user defined part (the segment attributes). The controls for the attributes (in the example: Typ, Speaker, TR1, TR2) are defined in the associated audio segment template.

ID

The ID (name) of the selected / new segment.

Auto

Copy the next automatic segment name into field ID. The name format can be configured with the automatic segment names dialog.

Seg.

Position and length (task expression) of the selected / new segment.

Crs.

Use the position of the current cursor(s) to update the Seg. field.

Ch.

Channel attribute value of the selected / new segment.

Clear

Reset all segment attributes to default / empty values.

Save

Save segment attributes. If a marker is selected, the segment is updated, otherwise a new segment is created.

Edit

Save segment attributes and display the segment properties dialog (without dialog-template).

Typ, Speaker, TR1, TR2

Controls containing the user defined attributes of the selected / new segment. The controls for the attributes (in the example: Typ, Speaker, TR1, TR2) are defined in the associated audio segment template.

The fields ID, Seg., Ch. and the attribute fields are updated automatically when a segment marker is selected.

Programmer Guide/Macro Library/XPlot

2014-05-20T13:26:00Z

Admin:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}

{{TOC limit|4}}

==XPlot : CObjEx==

A general class for plotting multiple graphs.

===XPlot Construction===

Initialize a new XPlot-instance to display 1 or more graphs. Returns the new object or an empty string. Information and error messages are written to the <code>BSCRIPT CON</code> console.

=====Usage:=====

<code>XPlot <var>rows</var>=1 ; <var>columns</var>=1 ; <var>title</var> ; <var>profile</var> ; <var>window</var> ; <var>owner</var></code>

=====Parameters:=====

;<var>rows</var>

:The number of rows (default=<code>1</code>).

;<var>columns</var>

:The number of columns for each row (inrow0 inrow1 ...). The default is one column per row.

;<var>title</var>

:The display window title.

;<var>profile</var>

:The name of the graphics profile to use. A graphics profile is also known as a colour scheme.

;<var>window</var>

:The window position and size (in the format '<code>x y width height</code>').

;<var>owner</var>

:The id of an existing display item which should own this new window. See <code>NEW DISPLAY</code> for details.

=====Result:=====

A new <code>XPlot</code> object if successful or an empty string.

=====Examples:=====

The simplest way to create an <code>XPlot</code> instance with one graph is as follows:

<pre>
#xplot := xplot
if '$#xplot[?]' != 'instance' em -1 ; Failed to create the xplot instance
</pre>

===XPlot Member Functions===

The <code>XPLOT</code> class has the following member functions. See CObjEx Member Functions for a list of functions implemented in the parent class.

====AddPlot====

The <code>XPLOT</code> function <code>AddPlot</code> is identical to the <code>PLOT</code> function, except that it adds to an existing graph (in addition to or on top of the original plot). If no graph exists at the specified <var>adr</var>, then the call is passed to <code>Plot</code>. It supports the following plot types: <code>XYPLOT</code>, <code>FUNCTION</code> and <code>PARAMETER</code>. The parameters are identical to the <code>[[#Plot|PLOT]]</code> function.

====Dialog====

The function <code>Dialog</code> can be used to show and hide a dialog in the <code>XPlot</code> display.

=====Usage:=====

<code><var>inst</var> Dialog <var>cmd</var> ; <var>args</var></code>

=====Parameters:=====

;<var>cmd</var>

:See below for details.

;<var>args</var>

:See below for details.

=====Result:=====

The ID of the current or new dialog item or an empty string.

====New====

Creates a new dialog item (deleting the old one first).

=====Usage:=====

<code><var>inst</var> Dialog New</code>

======Delete======

Removes the dialog from the display and deletes the dialog item.

=====Usage:=====

<code><var>inst</var> Dialog Delete</code>

======Msg======

Posts a message to the macro message queue. The format of the message is:

<code>MENU</code> <var>dialogItem</var> <var>msgId</var> <var>msgPar</var>

Note that when the display is closed, this function is called to post the message <code>MENU dialogItem CLOSE</code> to the dialog item.

=====Usage:=====

<code><var>inst</var> Dialog Msg ; <var>pos</var> ; <var>msgid</var> <var>msgpar</var></code>

=====Parameters:=====

;<var>pos</var>

:Sets the position of the dialog within the display. The following values are supported:

:<code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code>

;<var>msgid</var>

:The message ID.

;<var>msgpar</var>

:The message parameters.

======On|Enabled======

Show the dialog and set it's position.

=====Usage:=====

<code><var>inst</var> Dialog On; <var>pos</var></code>

<code><var>inst</var> Dialog Enabled; <var>pos</var></code>

=====Parameters:=====

;<var>pos</var>

:Sets the position of the dialog within the display. The following values are supported:

:<code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code>

======Off|Hidden======

Show the dialog and set it's position.

=====Usage:=====

<code><var>inst</var> Dialog Off ; <var>pos</var></code>

<code><var>inst</var> Dialog Hidden ; <var>pos</var></code>

=====Parameters:=====

;<var>pos</var>

:Sets the position of the dialog within the display. The following values are supported:

:<code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code>

====Display====

Returns the ID of the display object associated with this <code>XPLOT</code> instance.

=====Usage:=====

<code><var>inst</var> display</code>

=====Result:=====

Returns the display object of the <code>XPLOT</code> instance.

====End====

Enters the message loop, waits until the user closes the plot display and then destroys itself.

====Get====

Retrieve an attribute from a specific graph.

=====Usage:=====

<code><var>xplot</var> Get <var>adr</var> ; <var>attribute</var></code>

=====Parameters:=====

;<var>adr</var>

:The address of the display splitter (see member function <code>Graph</code> for detail).

;<var>attribute</var>

:The id of the requested attribute. The following values are supported:

:<code>CURSORPOSITION</code> - Returns the current cursor positions in the following format: <code>i1 x1 y1 i2 x2 y2</code>

:Note that <code>x1 <= x2</code>

:<code>YDATA</code> - Returns the y data item.

:<code>XDATA</code> - Returns the x data item.

:<code>RANGE</code> - Returns the x axis and y axis range in the following format: <code>xmin xmax ymin ymax</code>

:<code>TYPE</code> - Returns the plot type (see <code>Plot</code> for a list of available plot types).

====GetFColors====

The <code>GetFColors</code> function returns a blank separated list of the function colors defined in the selected graphics profile.

=====Usage:=====

<code><var>xplot</var> GetFColors</code>

=====Result:=====

Returns a blank separated list of color keywords.

====Graph====

Returns the requested attribute <var>attr</var> of the graph identified by <var>adr</var>.

=====Usage:=====

<code><var>xplot</var> Graph <var>adr</var> [; <var>attr</var>=GRAPH ]</code>

=====Parameters:=====

;<var>adr</var>

:The id of a graph item, an <code>[[Programmer Guide/Class Library/XGraph : CObjEx|XGRAPH]]</code> instance or the '<code>row column</code>' address of a splitter in the display. Note that the <code>row</code> and <code>column</code> indices are zero-based.

;<var>attr</var>

:The attribute to returned. The following values are allowed:

:<code>INSTANCE</code> - Return the id of the <code>XGRAPH</code> instance associated with <var>adr</var>.

:<code>GRAPH</code> - Return the id of the graph object associated with <var>adr</var>. This is the default attribute.

:<code>ROW</code> - Return the row index of the splitter associated with <var>adr</var>.

:<code>COLUMN</code> - Return the column index of the splitter associated with <var>adr</var>.

=====Result:=====

Return values are selected by the argument <var>attr</var>. See the description of <var>attr</var> for details. If the address argument <var>adr</var> do not refer to a graph, <code>XGRAPH</code> or splitter of the display, an empty string is returned.

=====Examples:=====

Get the graph item id for the top left graph.

<pre>
#graph := $#xplot graph 0 0
</pre>
====Legend====

Display a graph legend. Use <code>$#xplot LEGEND $#graph</code> to clear the legend.

=====Usage:=====

<code><var>xplot</var> Legend <var>graph</var> ; <var>unit</var> ; <var>x</var> ; <var>y</var> ; <var>w</var> ; <var>h</var> ; <var>color</var> ; <var>info</var> ; <var>text1</var> ; <var>text2</var> ; <var>textX</var></code>

=====Parameters:=====

;<var>graph</var>

:The graph address (e.g. row and column index. See [[#Plot|PLOT]] for detail).

;<var>unit</var>

:The unit for size and position values. The following values are supported:

:<code>real</code> - The real x/y values.

:<code>%</code> or <code>percent</code> - The percent of the graph's plot area.

;<var>x, y</var>

:The position of the upper right corner of the first legend line.

;<var>w, h</var>

:The width and height of one legend line.

;<var>color</var>

:The legend text color.

;<var>info</var>

:This flag selects the line attributes to be displayed. The following values are supported:

:<code>color</code> - The color.

:<code>all</code> - The color, style, width and symbol.

;<var>textX</var>

:The text for the legend for function X. If no text is supplied, the legend line is removed.This parameter can be either a string, or a simple table.

=====Result:=====

void

====Plot====

The <code>XPlot</code> function <code>Plot</code> can be used to plot a function in a graph. Currently, {{STX}} supports waveform , x/y (aka function and more specifically parameter), spectrogram and waterfall plots.

======XYPLOT======

Plot an x/y function graph.

=====Usage:=====

<code><var>xplot</var> Plot <var>adr</var> ; XYPLOT ; <var>y</var> ; <var>x</var> ; <var>title</var> ; <var>xr</var> ; <var>xu</var> ; <var>xt</var> ; <var>yr</var> ; <var>yu</var> ; <var>yt</var> ; <var>fstyles</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

;<var>adr</var>

:The address of the display splitter (see the member function [[#Graph|GRAPH]] for details).

;<var>y</var>

:The y axis data (a vector or an array).

;<var>x</var>

:The data to be used for the x axis. This can be one of the following:

:A data vector with <code>y[!nrow]</code> values and 1 column.

:<code>*</code> - An asterisk. This is the default and means that the x axis uses the values <code>0</code> through to <code>y[!nrow]-1</code>.

:A blank separated list of values ('x1 x2' -> x[i] = x1+(x2-x1)/(y[!nrow]-1), i = 0..<code>y[!nrow]-1</code>).

;<var>title</var>

:The title to be displayed in this plot.

;<var>xr</var>

:The x axis display range. This can be one of the following values:

:<code>*</code> - An asterisk - an automatic scale is generated.

:<code>xmin xmax</code> - Two numerical values - the minimum and maximum values.

;<var>xu</var>

:The text describing the x axis unit (e.g. <code>seconds</code>). The default is an empty string.

:The <code>WAVEFORM</code> plot only allows the following values: <code>SAMPLES</code>|<code>MS</code>|<code>S</code>. The default is <code>S</code>.

;<var>xt</var>

:The title to be used for the x axis. The default is an empty string.

;<var>yr</var>

:The y axis display range. This can be one of the following:

:<code>*</code> - An asterisk - an automatic scale is generated.

:<code>ymin ymax</code> - Two numerical values - the minimum and maximum values.

;<var>yu</var>

:The text describing the y axis unit (e.g. <code>dB</code>).

;<var>yt</var>

:The title to be used for the y axis. The default is an empty string.

;<var>fstyles</var>

:An <code>fstyle</code> argument (see <code>fstyle</code> for details) or a zero-based function line index as specified in a color scheme (see Color Schemes in the User Guide).

;<var>xlabtab, ylabtab, zlabtab</var>

:Extended tables containing the scale, grid and label definitions. For a description of the table format, please see the scale definition table for details.

=====Result:=====

Return <code>0</code> if successful.

=====Examples:=====

Plot a simple x/y function.

<pre>
#xplot := XPLOT 1 ; 1 ; XPLOT ; Default ; 0 0 400 400
$#xplot plot 0 ; XYPLOT; $(eval fill(10, 0, 1)) ; * ; xyplot ; * ; ; x-axis ; * ; ; y-axis
</pre>
======FUNCTION======

Plot a function graph. Note that this is identical to an <code>XYPLOT</code>.

=====Usage:=====

<code><var>xplot</var> Plot <var>adr</var> ; FUNCTION ; <var>y ; x ; title ; xr ; xu ; xt ; yr ; yu ; yt ; fstyles</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

See <code>XYPLOT</code> for parameter descriptions.

=====Result:=====

Return <code>0</code> if successful.

======parameter======

Plot a parameter graph. A parameter graph differs from a function graph because a parameter plot can have missing values - it does not necessarily have values for every point on the x axis.

=====Usage:=====

<code><var>xplot</var> Plot <var>adr</var> ; parameter ; <var>y ; title ; xr ; xu ; xt ; yr ; yu ; yt ; fstyles</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

See the <code>xyplot</code> for parameter details.

=====Result:=====

Return <code>0</code> if successful.

======spectrogram======

Plot a spectrogram graph.

=====Usage:=====

<code><var>xplot</var> plot <var>adr</var> ; spectrogram ; <var>d</var> ; <var>y</var> ; <var>title</var> ; <var>xr</var> ; <var>xu</var> ; <var>xt</var> ; <var>yr</var> ; <var>yu</var> ; <var>yt</var> ; <var>zr</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

;<var>d</var>

:A data array containing one spectrum or function line per <var>y</var> row. Note that this parameter is specific to the <code>SPECTROGRAM</code> and <code>WATERFALL</code> plots.

;<var>y</var>

:The y-scale data (frequency). This can be one of the following:

:1) <code>vData</code> - A data vector with <code>y[!ncol]</code> values and 1 column.

:2) * - An asterisk: <code>y[i] = i</code>, <code>i = 0..d[!ncol]-1</code>. This is the default.

:3) <code>y1 y2</code> - Two blank separated values: <code>y[i] = y1+i*(y2-y1)/(d[!ncol]-1)</code>, <code>i = 0..d[!ncol]-1</code>.

;<var>zr</var>

:The z scale is a color scale. The following values are supported:

:<code>*</code> - An asterisk. The range is automatically generated.

:<code>zmin zmax</code> - Two numerical values specifying the minimum and maximum z axis values.

:<code>zdown</code> - A numerical value. The maximum z value is chosen automatically and the minimum value is calculated as follows: <code>zmax-zdown</code>.

For all other parameters, see <code>xyplot</code> for descriptions.

======WATERFALL======

Plot a waterfall graph.

=====Usage:=====

<code><var>xplot</var> PLOT <var>adr</var> ; WATERFALL ; <var>d</var> ; <var>x</var> ; <var>title</var> ; <var>xr</var> ; <var>xu</var> ; <var>xt</var> ; <var>yr</var> ; <var>yu</var> ; <var>yt</var> ; <var>zr</var> ; <var>zu</var> ; <var>zt</var> ; <var>xw</var> ; <var>yw</var> ; <var>n</var> ; <var>xlabtab</var> ; <var>ylabtab</var> ; <var>zlabtab</var></code>

=====Parameters:=====

;<var>d</var>

:The data array (one spectrum or function-line / row).

;<var>zr</var>

:The z axis display range. The following values are supported:

:<code>*</code> - An asterisk. The range is automatically generated.

:<code>zmin zmax</code> - Two numerical values specifying the minimum and maximum z axis values.

;<var>zu</var>

:The text describing the z axis unit (e.g. <code>s</code>).

;<var>zt</var>

:The title to be used for the z axis. The default is an empty string.

;<var>xw</var>

:The relative width of the x scale. A value between <code>-1</code> and <code>1</code>. The default is <code>0.8</code>.

;<var>yw</var>

:The relative width of the y scale. A value between <code>-1</code> and <code>1</code>. The default is <code>0.8</code>.

;<var>n</var>

:The number of lines to be plotted. The default is <code>150</code>.

For all other parameters, see <code>XYPLOT</code> for descriptions.

======WAVEFORM======

Plot a waveform graph. Note that the displayed wave item is automatically attached to the graph. This means, no explicit call to <code>SetWave</code> is necessary.

=====Usage:=====

<code><var>xplot</var> PLOT <var>adr</var> ; WAVEFORM ; <var>wave</var> ; <var>title</var> ; <var>xu</var> ; <var>xt</var> ; <var>ymax</var> ; <var>yr</var> ; <var>yt</var> ; <var>fill</var></code>

=====Parameters:=====

;<var>wave</var>

:A wave item id or an <code>XWAVE</code> instance

;<var>xu</var>

:The unit to use on the x axis. The following values: <code>SAMPLES</code>|<code>MS</code>|<code>S</code>. The default is <code>S</code>.

;<var>ymax</var>

:The maximum waveform amplitude. This can be a value between 0 and ...

;<var>yr</var>

:The y axis display range. This can be any positive number. The default is <code>1</code>.

;<var>fill</var>

:<code>1</code> if the waveform envelope should be filled or <code>0</code>.

For all other parameters, see <code>XYPLOT</code> for descriptions.

======TEXTBOX======

Plot a graph containing text.

=====Usage:=====

<code><var>xplot</var> PLOT <var>adr</var> ; TEXTBOX ; <var>title</var> ; <var>color</var> ; <var>halign</var> ; <var>valign</var> ; <var>text</var></code>

=====Parameters:=====

;<var>title</var>

:The graph title.

;<var>color</var>

:The text color. This can be an of the {{STX}} color arguments.

;<var>halign</var>

:The horizontal text alignment. This can be one of the following values: <code>CENTER</code>|<code>LEFT</code>|<code>RIGHT</code>

;<var>valign</var>

:The vertical text alignment. This can be one of the following values: <code>CENTER</code>|<code>TOP</code>|<code>BOTTOM</code>

;<var>text</var>

:The text to be displayed. This can be a simple table with an entry per line of text or a semi-colon separated list of text lines.

For all other parameters, see <code>XYPLOT</code> for descriptions.

======fstyle======

The <var>fstyle</var> argument passed to the <code>XPlot</code> functions <code>Plot</code> and <code>AddPlot</code> has the following syntax and components:

<code><var>linestyle</var><code>:</code><var>linecol</var><code>:</code><var>printcol</var><code>:</code><var>linewidth</var><code>:</code><var>drawstyle</var><code>:</code><var>drawsym</var><code>:</code><var>ymiss</var></code>

;<var>linestyle</var>

:Determines whether the function line is solid (<code>SOLID</code>), dotted (<code>DOT</code>) or dashed (<code>DASH</code>). The default value is taken from the <code>XPLOT</code> color profile.

;<var>linecol</var>

:The colour to use for the function line on screen. This can be any {{STX}} colour keyword or RGB value. The default value is taken from the <code>XPLOT</code> color profile.

;<var>printcol</var>

:The colour to use for the function line when printing. See <var>linecol</var> for details. The default value is taken from the <code>XPLOT</code> color profile.

;<var>linewidth</var>

:The width of the function line. Possible values are <code>0</code> through to <code>4</code> for lines with the <code>SOLID</code> <var>linestyle</var> and <code>0</code> or <code>1</code> for lines with the <code>DOT</code> or <code>DASH</code> <var>linestyle</var>. The default value is taken from the <code>XPLOT</code> color profile.

;<var>drawstyle</var>

:The style to use to draw the function. Each function point can be plotted separately (<code>POINTS</code>), a line can be drawn between each function point (<code>LINES</code>), the area below the function can be filled with the <var>linecol</var> (<code>AREA</code>), the function points can be joined by steps (<code>STEPS</code> - note that this is only available for the <code>PARAMETER</code> plot) or no points are plotted (<code>NONE</code> - this is best used when a drawing symbol (<var>drawsym</var>) is defined). The default style is <code>LINES</code>.

;<var>drawsym</var>

:The symbol to draw at each point. This can be used in conjunction with a drawing style (see <var>drawstyle</var>). The following keywords are supported:

:<code>NONE</code>|<code>SQUARE</code>|<code>TRIANGLE|CIRCLE|CROSS|DIAMOND</code>

:The default style is <code>NONE</code>.

;<var>ymiss</var>

:The value to use for missing y values. If <var>ymiss</var> is not specified (empty) all values are displayed, otherwise all points where <code>y=</code><var>ymiss</var> are not displayed. If <var>ymiss</var> is not empty and is not a number then <var>ymiss</var> is set to <code>0</code>. If no <var>ymiss</var> is defined, no <var>ymiss</var> is used (this is the default).

====Redraw====

Redraw the selected graph. This is currently only implemented for the <code>FUNCTION</code> (<code>XYPLOT</code>) and <code>PARAMETER</code> plots.

=====Usage:=====

<code><var>xplot</var> REDRAW <var>adr</var></code>

=====Parameters:=====

;<var>adr</var>

:The address of the display splitter (see member function <code>Graph</code> for details).

=====Result:=====

Return 0 if successful.

====ScaleOctave====

Generate a logarithmic scale table for use with the <code>Plot</code> or <code>AddPlot</code> functions. This function can also be called statically.

=====Usage:=====

<code><var>xplot</var> ScaleOctave <var>df</var> <var>count</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code>xplot ScaleOctave <var>df</var> <var>count</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code><var>xplot</var> ScaleOctave <var>vector</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code>xplot ScaleOctave <var>vector</var> ; <var>fmax</var> ; <var>fmin</var></code>

=====Parameters:=====

;<var>df</var>

:The frequency resolution in Hz.

;<var>count</var>

:The number of frequency points.

;<var>fmax</var>

:The maximum frequency to be displayed.

;<var>fmin</var>

:The minimum frequency to be displayed.

;<var>vector</var>

:The scale range as a data vector.

=====Result:=====

The following string is returned:

<code>xmin xmax xlabTab xdata</code>

Where <code>xmin</code> and <code>xmax</code> are is the minimum and maximum of the logarithmic scale, <code>xlabTab</code> is the scale definition table which you can then pass to a <code>Plot</code> function and <code>xdata</code> is the logarithmic frequency values vector. See the scale definition table description in the Command Reference for details of the table syntax.

=====Examples:=====

Create a scale definition table for a logarithmic frequency axis with 2000 points at 10 Hz intervals and a maximum frequency of 10000 Hz.

<pre>
readstr '$(xplot scaleOctave 10 2000; 10000)' #xmin #xmax #xlab #x
</pre>
=====Notes:=====

See also ScaleSteps.

====ScaleLog10====

Generate a logarithmic scale table for use with the <code>Plot</code> or <code>AddPlot</code> functions. This function can also be called statically.

=====Usage:=====

<code><var>xplot</var> ScaleLog10 <var>df</var> <var>count</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code>xplot ScaleLog10 <var>df</var> <var>count</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code><var>xplot</var> ScaleLog10 <var>vector</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code>xplot ScaleLog10 <var>vector</var> ; <var>fmax</var> ; <var>fmin</var></code>

=====Parameters:=====

;<var>df</var>

:The frequency resolution in Hz.

;<var>count</var>

:The number of frequency points.

;<var>fmax</var>

:The maximum frequency to be displayed.

;<var>fmin</var>

:The minimum frequency to be displayed.

;<var>vector</var>

:The scale range as a data vector.

=====Result:=====

The following string is returned:

<code>xmin xmax xlabTab xdata</code>

Where <code>xmin</code> and <code>xmax</code> are is the minimum and maximum of the logarithmic scale, <code>xlabTab</code> is the scale definition table which you can then pass to a <code>Plot</code> function and <code>xdata</code> is the logarithmic frequency values vector. See the scale definition table description in the Command Reference for details of the table syntax.

=====Notes:=====

See also <code>ScaleSteps</code> and <code>ScaleOctave</code>.

====ScaleSteps====

Generate a linear scale table for use with the <code>Plot</code> or <code>AddPlot</code> functions. This function can also be called statically, e.g. '<code>xplot ScaleSteps -70 -10 ; 10 ; 5 ; 5 ; 1 ; 1</code>'.

=====Usage:=====

<code><var>inst</var> ScaleSteps <var>min</var> <var>max</var> ; <var>labelDist</var> ; <var>majorGridDist</var> ; <var>majorTickDist</var> ; <var>minorGridDist</var> ; <var>minorTickDist</var></code>

<code>xplot ScaleSteps <var>min</var> <var>max</var> ; <var>labelDist</var>; <var>majorGridDist</var>; <var>majorTickDist</var> ; <var>minorGridDist</var> ; <var>minorTickDist</var></code>

<code><var>inst</var> ScaleSteps <var>vector</var> ; <var>labelDist</var>; <var>majorGridDist</var>; <var>majorTickDist</var> ; <var>minorGridDist</var> ; <var>minorTickDist</var></code>

<code>xplot ScaleSteps <var>vector</var> ; <var>labelDist</var>; <var>majorGridDist</var>; <var>majorTickDist</var> ; <var>minorGridDist</var> ; <var>minorTickDist</var></code>

=====Parameters:=====

;<var>min, max</var>

:The scale range.

;<var>vector</var>

:The scale range as a data vector.

;<var>labelDist</var>

:The label distance in scale units.

;<var>majorGridDist</var>

:The distance of the major grid lines in scale units.

;<var>majorTickDist</var>

:The distance between major ticks in scale units.

;<var>minorGridDist</var>

:The distance of the minor grid lines in scale units.

;<var>minorTickDist</var>

:The distance between minor ticks in scale units.

=====Result:=====

The following string is returned:

<code>min max labTab</code>

Where <code>min</code> and <code>max</code> are is the computed or corrected scale range and <code>labTab</code> is the scale definition table which you can then pass to a <code>Plot</code> function. See the scale definition table description in the Command Reference for details of the table syntax.

=====Examples:=====

Calculate the linear scale, grid and labels for an amplitude axis between -70 and -10 dB with labels every 10 dB, major grid lines and ticks every 5dB and minor grid lines and ticks every dB.

<pre>
readstr '$($#xplot ScaleSteps -70 -10 ; 10 ; 5 ; 5 ; 1 ; 1)' #ymin #ymax #ylab
</pre>
=====Notes:=====

See also <code>ScaleOctave</code> and <code>ScaleLog10</code>.

====Set====

The <code>Set</code> function sets the cursor mode and text attributes.

=====Usage:=====

<code><var>xplot</var> Set [ <var>graph</var>|* ; ] <var>attr</var> <var>args</var></code>

=====Parameters:=====

;<var>xgraph</var>

:An xgraph instance on which to call the <code>Set</code> command. If no graph is specified or an asterisk, then the <code>Set</code> command is carried out on all graphs.

;<var>attr</var>

:One of the following values:

:<code>cursormode</code> - turn cursors on and off and change the way they look.

:<code>xunit</code> - the name of the x-axis unit

:<code>yunit</code> - the name of the y-axis unit

:<code>xtext</code> - the description of the x-axis

:<code>ytext</code> - the description of the y-axis

:<code>title</code> - the graph's title

;<var>args</var>

:The value of <var>args</var> depends on <var>attr</var>.

:If <var>attr</var> is <code>cursormode</code>, then <var>args</var> is as follows:

:<code>mode|* type|* line|*</code>

:Where mode is one of the following values:

:<code>on</code> - show the cursor

:<code>off</code> - hide the cursor

:Where <var>type</var> is one of the following values:

:<code>cross</code>|<code>crosshair</code>|<code>vbarcross</code>|<code>harmonic</code>

:And <code>line</code> is one of the following values:

:<code>off</code> |<code>on</code>

:If <var>attr</var> is not <code>cursormode</code>, then <var>args</var> is used as the text, unit or title.

=====Result:=====

No return value.

====SetCallback====

The callback function is called by the message handlers to process popup and context menu messages and hotkeys which are not used by <code>XPLOT</code> or <code>XGRAPH</code>. The following commands are used to call the callback function:

If called from an <code>XGRAPH</code> message handler:

<code>cbfunction xgraphinstance irow icol msgid msgpar</code>

If called from the <code>XPLOT</code> message handler:

<code>cbfunction xplotinstance * * msgid msgpar</code>

=====Usage:=====

<code><var>xplot</var> SetCallback [ <var>cbfunction</var> ]</code>

=====Parameters:=====

;<var>cbfunction</var>

:The name of the callback function or an empty string to remove a previous association.

=====Result:=====

No return value.

====SetWave====

Attach a signal to one graph or all graphs (see <var>adr</var>). If a wave item is attached to a graph, it can not be deleted before it is detached or the graph or <code>XPLOT</code> instance is deleted.

=====Usage:=====

<code><var>xplot</var> SetWave [ <var>waveitem</var> ]</code>

<code><var>xplot</var> SetWave <var>adr</var> ; [ <var>waveitem</var> ]</code>

=====Parameters:=====

;<var>adr</var>

:The address of the display splitter (see member function Graph for details). If this parameter is omitted, then the wave item is set for all graphs.

;<var>waveitem</var>

:A wave item id or an <code>[[Programmer Guide/Class Library/XWave : CObjEx|XWAVE]]</code> instance (or empty to remove attachment).

=====Result:=====

Return <code>0</code> if successful.

Note that wave items can only be attached to graphs of type <code>FUNCTION</code>, <code>XYPLOT</code>, <code>PARAMETER</code>, <code>SPECTROGRAM</code> and <code>WAVEFORM</code>.====XPlot Hotkeys====

The following hotkeys are implemented in the <code>XPLOT</code> class:

{|
|-
|C
|Turn the cursors on and off.
|-
|S
|Change to the next cursor style.
|-
|B
|Turn cursor binding on and off.
|-
|Ctrl+N
|Bind the cursor to the next function.
|-
|Ctrl+P
|Bind the cursor to the previous function.
|-
|R
|Turn the cursor rubberline on and off.
|-
|T
|Turn the title on and off.
|-
|X
|Change to the next x<nowiki>-</nowiki>scale mode.
|-
|Y
|Change to the next y<nowiki>-</nowiki>scale mode.
|-
|Z
|Change to the next z<nowiki>-</nowiki>scale mode.
|-
|Space
|Open the setup dialog.
|-
|P
|Play the attached wave (between the cursors).
|-
|Q
|Play the attached wave (the whole signal).
|-
|ESC
|Stop playback.
|-
|Ins
|Show the selected metasegment's settings in a dialog or, if no metasegment is selected, show a dialog to create a new metasegment.
|-
|Del
|Delete the selected metasegments.
|-
|Ctrl+Left Click
|Move the legend to the clicked position.
|-
|Shift+Left Click
|Create a metasegment at the clicked position (show the 'Insert Metasegment' dialog).
|}

====XPlot Examples====

=====Simple XPLOT Example=====

The following example demonstrates simple <code>[[Programmer Guide/Class Library/XPlot : CObjEx|XPLOT]]</code> usage.

<pre>
[macro xplot_example_1]
//
// create display (and graph)
//
#xplot := xplot 2 ; 1 ; xplot ; default ; 100 100 800 800
if '$#xplot[?]' != 'instance' em -1 ; xplot creation failed ($emsg)
//
// plot graphs (including data generation)
//
#nValues := 100
$#xplot Plot 0 0 ; XYPLOT ; $(eval fill($#nValues,1,1)) ; * ; Graph Title ; * ; x unit ; x title ; * ; y unit ; y title ; solid:green::1
$#xplot Plot 1 0 ; SPECTROGRAM ; $(eval rand(1,100,100)) ; * ; Graph Title ; * ; x unit ; x title ; * ; y unit ; y title ; solid:green::1
//
// clean up
//
// the clean up takes place automatically
// when the plot window is closed
exit
</pre>
=====Plot rows of a matrix using XPLOT=====

The following example demonstrates how to plot the rows of a matrix using the <code>[[Programmer Guide/Class Library/XPlot : CObjEx|XPLOT]]</code> class.

<pre>
//{{3.9 6473}{2009.01.29 16.44.04} - automatically created version information - do not change or delete this line}

[macro xplot_example_2]

//
// This row demonstrates how to plot each row of a matrix
//
// C.G. 29.1.2009
//

//
// create display (and graph)
//

#xplot := xplot 1 ; 1 ; xplot ; default ; 100 100 800 800
if '$#xplot[?]' != 'instance' em -1 ; xplot creation failed ($emsg)

//
// create a matrix and fill it with some meaningless data
//

#mat := new table * /Parameter * number:X:100
if '$#mat[?]' != table em -1 ; cannot create table ($emsg)

for #i := 0 to $#i < 10 step #i := int $#i + 1
$#mat[$#i,*] := eval fill( 100, $#i+1, $#i+1 )
end

//
// plot each row of the matrix
//

for #i := int 0 to $#i < $#mat[!nrow] step #i := int $#i + 1
#x := eval $#mat[$#i,*]
$#xplot AddPlot 0 0 ; XYPLOT ; $#x ; * ; row-by-row plot ; * ; x unit ; x title ; * ; y unit ; y title ; solid:green::1
end

exit 1 int 0
</pre>

=====Advanced XPLOT Example=====

This example not only demonstrates the use of the <code>XPLOT</code> class, but also signal processing using the <code>EVAL</code> function.

<pre>
//=================================================================================================
//
// DSP Examples
//
// last update: Nov 17, 2007 (AN)
// {{STX}} version: {{STX}} 3.8 Beta
//
// The examples in this file demonstrates how to ...
// ... use the EVAL command for signal processing
// ... use the class XWAVE to read a signal frame by frame
// ... display spectrograms, waveforms and functions in XPLOT graphs
// ... enable XPLOT to play signals
// ... use the XPLOT callback function to implement simple user controls
// ... set and get cursor attritbutes and positions of XPLOT graphs
// ... add a legend to a XPLOT graph
// ... use BUTIL MSGBOX for simple dialogs
// ... use the CON object (class BScript) to display log. messages
// ... use the CON object to save numeric tables to textfiles
// ... simulate item messages using the message queue macro MSGQUEUE
// ... implement and call local subroutines
//
//=================================================================================================

//-------------------------------------------------------------------------------------------------
//
// DSPExAvrSpectrum Create a plot containing the average spectra of all segments selected
// in the DataSet view.
//
//-------------------------------------------------------------------------------------------------
[Macro DSPExAvrSpectrum #lfrm=100ms';'#sfrm=50%';'#wtyp=hamming';'#ascale=dB';'#fscale=Hz';'#amax=1';'#aref=1';'#]
// arguments: #lfrm frame length, absolute time expression
// #sfrm frame shift, relative time expression
// #wtyp window type, {Hanning, Hamming, ...)
// #fscale spectrogram frequency scale unit (Hz, kHz, Bark, Mel, ERB)
// #amax calibration factor or CALSET to use a calibration set
// #aref reference amplitude, ignored if #amax equals CALSET

// set mode to macro name (see macro DSPExCallback)
DSPExMode := set '$#mac'

// get segments selected in the DataSet view
#segments := dspexlib getsegments

// create the result table (one spectrum per row)
#asp := new table * * num:x:$#segments[] /p

// segment analysis loop
#nok := 0 // number of computed average spectra
for #i := 0 to $#i < $#segments[] step #i := int $#i+1

// get next segment from segment list
readtab $#segments $#i #aset';'#aseg';'#ach';'#
con log process segment "set=$#aset, id=$#aseg, ch=$#ach" ($(int $#i+1) of $#segments[])

// create the wave object and initialize frame settings (mode "centered")
// usage: XWAVE setref ; segmentid ; channel ; mode ; framelength ; frameshift ; ampmax ; ampref
if $(#wave := xwave '$#aset;$#aseg;$#ach;1;$#lfrm;$#sfrm;$#amax;$#aref')[?] != instance then
butil 'msgbox msg; create wave object for segment "$#aset/$#aseg,$#ach" failed; Error!'
continue
// set / check sampling rate
else if '$#srate' == '' then
#srate := $($#wave srate)
else if $($#wave srate) != $#srate then
butil 'msgbox msg; segment "$#aset/$#aseg,$#ach" - sampling rate mismatch; Error!'
$#wave destroy // delete wave object
continue
end

// compute the average spectrum
if $(#tmp := dspexlib averagespectrum $#wave ; $#wtyp ; $#ascale)[?] != table then
butil 'msgbox msg; compute average spectrum of segment "$#aset/$#aseg,$#ach" failed; Error!'
$#wave destroy // delete wave object
continue
end

$#asp[*,$#nok] := $#tmp // save the spectrum
delete $#tmp // delete temp. buffer
#legend := '$#legend $($#wave title);' // add segment to legend string
$#wave destroy // delete wave object
#nok := int $#nok+1 // increment result vector counter

end

// exit if no results are computed
if $#nok < 1 exit

// compute frequency scale vector, unit and frequency resolution
readstr '$(dspexlib frequencyscale $#srate ; $#asp[!nrow] ; $#fscale)' #frq #funit #df

// create and configure the plot object
// usage: XPLOT rows ; cols0 cols1 .. ; windowtitle ; graphicprofile ; wx wy wwidth wheight
#plot := xplot 1; 1; Average Spectrum; Rainbow; 0 0 1024 800

// plot all spectra and display the legend
#title := format 'lfrm=%s, sfrm=%s, wtyp=%s, df=%.3fHz' '$#lfrm' '$#sfrm' '$#wtyp' $#df
readstr '$(dspexlib amplitudescale $#ascale)' #ytext #yunit
// usage: xplot PLOT row col; FUNCTION; ydata; xdata; title; xrange; xunit; xtext; yrange; yunit; yrange
$#plot plot 0; function; $#asp; $#frq; $#title; ; $#funit; frequency; ; $#yunit ; $#ytext
$#plot legend 0; %; 50; 95; 45; 5; black; color; $#legend
$#plot set cursormode on crosshair // set cursor mode and style
$#plot setcallback dspexcallback // assign callback function

// wait until plot window is closed
$#plot end // the xplot object is destroyed automatically when the window is closed

// finished - cleanup and and exit
delete $#asp $#frq $#segments // delete data items
showLogOnExit := 0 // close the bscript log-window automatically
exit

//-------------------------------------------------------------------------------------------------
//
// DSPExSpectrogram Plot a spectrogram of all segments selected in the DataSet view.
// For each segment one spectrogram window is displayed. The window
// must be closed before the next segment is analysed.
//
//-------------------------------------------------------------------------------------------------
[Macro DSPExSpectrogram #lfrm=40ms';'#sfrm=10%';'#wtyp=hamming';'#arange=50';'#fscale=Hz';'#amax=1';'#aref=1';'#]
// arguments: #lfrm frame length, absolute time expression
// #sfrm frame shift, relative time expression
// #wtyp window type, {Hanning, Hamming)
// #arange spectrogram display range in dB (max .. max-range)
// #fscale spectrogram frequency scale unit (Hz, kHz, Bark, Mel, ERB)
// #amax calibration factor or CALSET to use a calibration set
// #aref reference amplitude, ignored if #amax equals CALSET

// set mode variable to macro name (see macro DSPExCallback)
DSPExMode := set '$#mac'

// get segments selected in the DataSet view
#segments := dspexlib getsegments

// segment analysis loop
for #i := 0 to $#i < $#segments[] && '$DSPExMode' != '' step #i := int $#i+1

// get next segment from segment list
readtab $#segments $#i #aset';'#aseg';'#ach';'#

// create the wave object and initialize frame settings (mode "centered")
if $(#wave := xwave '$#aset;$#aseg;$#ach;1;$#lfrm;$#sfrm;$#amax;$#aref')[?] != instance then
butil 'msgbox msg; create wave object for segment "$#aset ; $#aseg ; $#ach" failed; Error!'
continue
end

// compute the spectrogram
if $(#asp := dspexlib spectrogram $#wave ; $#wtyp ; log)[?] != table then
butil 'msgbox msg; compute spectrogram of segment "$#aset ; $#aseg ; $#ach" failed; Error!'
$#wave destroy
continue
end

// compute frequency scale vector, unit and frequency resolution
readstr '$(dspexlib frequencyscale $($#wave srate) ; $#asp[!ncol] ; $#fscale)' #frq #funit #df

// create and configure the plot object
#plot := xplot 2; 1 1; $($#wave title) quit = c-q, next = c-n; Rainbow; 0 0 1024 800
$($#plot display) height 3 1 /apply // set height of graphs

// plot spectrogram and waveform
#title := format 'lfrm=%s, sfrm=%s, wtyp=%s, arange=%s, amax=%.1fdB, df=%.3fHz' '$#lfrm' '$#sfrm' '$#wtyp' '$#arange' $(eval max($#asp)) $#df
$#plot plot 0; spectrogram; $#asp; $#frq; $#title; $($#wave tbegin) $($#wave tend); s; time; ; $#funit; frequency; $#arange
$#plot plot 1; waveform; $#wave; ; s; time; $($#wave amax); $($#wave amax); amplitude; 1
$#plot set cursormode on crosshair // set cursor mode and style
$#plot setcallback dspexcallback // assign callback function

// assign wave object to xplot graphs (for playback)
$#plot setwave $#wave

// wait until plot window is closed
$#plot end // the xplot object is destroyed automatically when the window is closed

// cleanup
delete $#asp $#frq // delete data items
$#wave destroy // delete wave object
end

// finished - cleanup and exit
delete $#segments // delete segment table
showLogOnExit := 0 // close the bscript log-window automatically
exit

//-------------------------------------------------------------------------------------------------
//
// DSPExCallback Callback function for XPLOT.
//
// arguments:
// if called from xplotobject message handler -> 'CALLBACK xplotobject * * msgid msgpar'
// if called from xgraphobject message handler -> 'CALLBACK xgraphobject row col msgid msgpar'
//
// Note: This macro uses the shell variable DSPEXMODE to check which macro has installed the
// callback and to set return values.
//
//-------------------------------------------------------------------------------------------------
[Macro DSPExCallback #obj #row #col #msgid #msgpar]

// get xplot-object if called from a xgraph-object
if '$#obj[!class]' == xgraph #obj := $#obj get xplot

// message filter for keystroke messages

// process Control-Q (QUIT) key
if '$#msgid$#msgpar' == keyCQ then

if $(butil msgbox yesno; Quit ?; $DSPExMode) == yes then
// place the display-close message in the message queue to end the xplot message loop
msgqueue 'display $($#obj display) close'
// set mode variable to empty-string if C-Q key was pressed
DSPExMode := ''
end

// process Control-C (COPY) and Control-S (SAVE) keys
else if $(#i := keyword '$#msgid$#msgpar' keyCC keyCS) >= 0 then

// get xgraph-object displayed in row 0 (later used to retrieve data)
#obj := $#obj graph 0; instance

// select the data to be saved and the save format
#todo := butil msgbox userdefined Amp Frq+Amp Cancel;; $DSPExMode - $(word $#i 'Copy to Clipboard' 'Save to CSV-File')
if $#todo == Amp then
#table := eval $($#obj get ydata) // use eval to get a copy of y-data
else if $#todo == Frq+Amp then
if '$DSPExMode' == DSPExAvrSpectrum then
#table := eval vmcol( $($#obj get xdata) , $($#obj get ydata) ) // merge x- and y-data into one table
else
#table := eval vmcol( $($#obj get xdata) , trn($($#obj get ydata)) ) // merge x- and transposed y-data into one table
end
end

// copy / save if table exists
if $#table[?] == table then
// select target
if $#i == 0 then
#file := set clipboard // set target to "clipboard" for all copy_xxx functions
else
#file := butil filedialog save; Select Output File; ; CSV=CSV-File; TXT=Textfile // use filedialog to select the output file
end

// use the CON-object to copy/save table
if '$#file' != '' con savedata text; $#table; $#file; 0; comma; dot
delete $#table
end

// process Control-I (INFO) || Control-M (MAX-MEAN) keys
else if $(#i := keyword '$#msgid$#msgpar' keyCI keyCM) >= 0 then

// get xgraph-object displayed in row 0
#obj := $#obj graph 0;inst

// save original graph title
if '$GraphTitle' == '' GraphTitle := $#obj get title

if $#i == 0 then
// get and display cursor positions
readstr '$($#obj get cursorposition)' #i1 #x1 #y1 #i2 #x2 #y2 #
#text := format 'Index = %d .. %d, X = %g ... %g (%g), Y = %g ... %g (%g)' $#i1 $#i2 $#x1 $#x2 abs($#x1-$#x2) $#y1 $#y2 abs($#y1-$#y2)
else
// set cursor mode (on), style (crosshair), rubberline (off), bind-mode (off), bind-functionindex (0)
$#obj set cursormode on crosshair off off 0
// get x- and y-data
#x := $#obj get xdata
#y := $#obj get ydata
// find index of maximum y value
#imax := eval imax($#y[*,0])
// compute mean of x and y
#xavr := eval avr($#x)
#yavr := eval avr($#y)
// set cursor 1 to maximum and cursor 2 to mean
$#obj set cursorpos 1 $#x[$#imax] $#y[$#imax] deselect
$#obj set cursorpos 2 $#xavr $#yavr deselect
// show maximum and mean in xgraph title
#text := format 'Maximum( %g , %g ), Average( %g , %g )' $#x[$#imax] $#y[$#imax] $#xavr $#yavr
end
// show info in graph title
$#obj set title $GraphTitle -- $#text

end

// note: the return value of the callback function is not used by the xplot/xgraph message handler
exit

//-------------------------------------------------------------------------------------------------
//
// DSPExLib Implements a set of signal processing functions which can be called with
// "DSPLIBEXAMPLE functionname functionarguments". This call style is often
// used to reduce the number of macros of a script or application.
//
// Functions:
//
// DSPEXLIB GETSEGMENTS
// result: a list of all segments selected in the DataSet view stored in a simple
// table (per line: 'setReference ; segmentId ; channelIndex')
// note: this function shows an error message and terminates the caller if no segments
// are selected
//
// DSPEXLIB AVERAGESPECTRUM wave ; wtyp ; atyp
// wave prepared xwave object
// wtyp type of window function: HANNING, HAMMING, KAISER, ...
// atyp type of output spectrum: LOGARITHMIC (=DB), POWER, LINEAR (=AMPLITUDE)
// result: an averaged fft spectrum in the selected format
//
// DSPEXLIB SPECTROGRAM wave ; wtyp ; atyp
// wave prepared xwave object
// wtyp type of window function: HANNING, HAMMING, KAISER, ...
// atyp type of output spectrum: LOGARITHMIC (=DB), POWER, LINEAR (=AMPLITUDE)
// or COMPLEX
// result: a matrix of fft spectra in the selected format, one spectrum per line
//
// DSPEXLIB FREQUENCYSCALE sr ; n ; type
// sr sampling rate in Hz
// n number of spectrum bins (equally spaced in the Hz domain)
// type type of frequency scale: HZ, KHZ, BARK, MEL, ERB
// result: 'frq unit df'; frq is the frequency scale vector, unit is the frequency unit
// name and df is the frequency scale step in Hz
//
// DSPEXLIB AMPLITUDESCALE type
// type type of amplitude scale: LOGARITHMIC (=DB), POWER, LINEAR (=AMPLITUDE)
// result: 'name unit df'; name and unit of amplitude scale
//
//-------------------------------------------------------------------------------------------------
[Macro DSPExLib]

// function call dispatching
readvar #argv #fun #argv /d
goto fun$#fun noFun

noFun:
// function not implemented
// result: empty string

// show an error message and exit
con log '$#mac function "$#fun" not implemented'
exit 1 set ''

//-------------------------------------------------------------------------------------------------
funGetSegments: // in:
// out: segment_list_table
//-------------------------------------------------------------------------------------------------
// retrieve list of selected segments from the DataSet application
#segments := datasetcmd getselected segments
if '$#segments[?]' == table && '$#segments[]' > 0 exit 1 set $#segments
butil msgbox msg ; no segments selected - select and try again; Error!
if '$#segments[?]' == table delete $#segments
exit 2 set '' // terminate this and the calling macro!

//-------------------------------------------------------------------------------------------------
funAverageSpectrum: // in: xwaveobject ; windowtype ; amplitudescale
// out: averagespectrum_vector
//-------------------------------------------------------------------------------------------------
// parse arguments
readvar #argv #wave';'#wtyp';'#atyp';'#

// show init message
con log $#mac $(upper '$#fun') - initializing

// create window
#w := gosub makewindow $($#wave framelength) $#wtyp

// create result table
#spg := new table *

// compute averaged amplitude spectrum
#n := $($#wave framecount)
$#spg := eval cr2len ( fft ( $($#wave read) ?* $#w ) )
for #i := 1 to $#i < $#n step #i := int $#i+1
if $#i%10 == 0 con logext 0; $#mac $(upper '$#fun') - $#i of $#n frames processed
$#spg := eval cr2len ( fft ( $($#wave read) ?* $#w ) ) + $#spg
end
$#spg := eval $#spg / $#n

// convert to selected output spectrum type
if $(#atyp := keyword '$#atyp' dB logarithmic power amplitude linear) < 2 then
$#spg := eval lin2log($#spg , $($#wave aref), 20)
else if $#atyp == 2 then
$#spg := eval $#spg ?^ 2
end

// show end message
con logext 0; $#mac $(upper '$#fun') - finished ($#n spectra computed)

// return averaged spectrum
exit 1 set $#spg

//-------------------------------------------------------------------------------------------------
funSpectrogram: // in: xwaveobject ; windowtype ; amplitudescale
// out: spectrogram_matrix
//-------------------------------------------------------------------------------------------------
// parse arguments
readvar #argv #wave';'#wtyp';'#atyp';'#

// show init message
con log $#mac $(upper '$#fun') - initializing

// create window
#w := gosub makewindow $($#wave framelength) $#wtyp

// check selected output spectrum type
if $(#atyp := keyword '$#wtyp' dB logarithmic power amplitude linear complex) < 5 then
// compute amplitude or power spectra

// create result table (one spectrum per line)
#spg := new table * * num:x:$(int $($#wave fftlength)/2 + 1) /p
// compute amplitude spectra
#n := $($#wave framecount)
for #i := 0 to $#i < $#n step #i := int $#i+1
if $#i%10 == 0 con logext 0; $#mac $(upper '$#fun') - $#i of $#n frames processed
$#spg[$#i,*] := eval cr2len ( fft ( $($#wave read) ?* $#w ) )
end
// convert to selected output spectrum type
if $(#atyp := keyword '$#atyp' dB logarithmic power amplitude linear) < 2 then
$#spg := eval lin2log($#spg , $($#wave aref), 20)
else if $#atyp == 2 then
$#spg := eval $#spg ?^ 2
end

else
// compute complex spectra

// create result table (one spectrum per line)
#spg := new table * * num:x:$(int $($#wave fftlength) + 2) /p
// compute complex spectra
for #i := int $($#wave framecount) to $#i > 0 step #i := int $#i-1
if $#i%50 == 0 con logext 0; $#mac $(upper '$#fun') - $#i of $#n frames processed
$#spg[$#i,*] := eval fft ( $($#wave read) ?* $#w )
end

end

// show end message
con logext 0; $#mac $(upper '$#fun') - finished ($#n spectra computed)

// return spectrogram matrix
exit 1 set $#spg

//-------------------------------------------------------------------------------------------------
funFrequencyScale: // in: samplingrate ; spectrumbins ; frequencyscale
// out: frequencyscale_vector frequencyscale_unit frequency_resolution_Hz
//-------------------------------------------------------------------------------------------------
// parse arguments
readvar #argv #sr';'#n';'#unit';'#
// generate frequency scale equally spaced in Hz
#frq := new table * // dummy table to make frq-scale permanent
$#frq := eval fill($#n, 0, $(#df := eval $#sr / 2 / ($#n - 1)) )
// convert to selected scale
if $(#unit := keyword '$#unit' Hz kHz Bark Mel ERB) < 0 #unit := 0
if $(#unit := word $#unit Hz kHz Bark Mel ERB) == kHz then
$#frq := eval $#frq / 1000
else if $#unit != Hz then
$#frq := eval hz2$#unit($#frq)
end
// return scale settings
exit 1 set '$#frq $#unit $#df'

//-------------------------------------------------------------------------------------------------
funAmplitudeScale: // in: amplitudescale
// out: amplitudescale_text amplitudescale_unit
//-------------------------------------------------------------------------------------------------
// parse arguments
readvar #argv #unit';'#
// get text and unit of amplitude scale
if $(#i := keyword '$#unit' dB logarithmic power amplitude linear) < 2 #i := 0
#unit := word $#i dB dB - - -
#text := word $#i amplitude amplitude power amplitude amplitude
exit 1 set '$#text $#unit'

//
// local subroutines
//

makeWindow:
// GOSUB MAKEWINDOW windowlength windowtype -> windowvector
readvar #argv #wlen #wtyp #
#list := hanning hamming blackman kaiser bartlett taprect nuttall flattop gauss
if $(#wtyp := keyword '$#wtyp' $#list) < 0 #wtyp := 0
exit 1 eval window($#wtyp, $#wlen, 1) * 2 / $#wlen
</pre>

Programmer Guide/Macro Library/XPlot

2014-05-20T13:24:52Z

Admin:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}

{{TOC limit|3}}

==XPlot : CObjEx==

A general class for plotting multiple graphs.

===XPlot Construction===

Initialize a new XPlot-instance to display 1 or more graphs. Returns the new object or an empty string. Information and error messages are written to the <code>BSCRIPT CON</code> console.

=====Usage:=====

<code>XPlot <var>rows</var>=1 ; <var>columns</var>=1 ; <var>title</var> ; <var>profile</var> ; <var>window</var> ; <var>owner</var></code>

=====Parameters:=====

;<var>rows</var>

:The number of rows (default=<code>1</code>).

;<var>columns</var>

:The number of columns for each row (inrow0 inrow1 ...). The default is one column per row.

;<var>title</var>

:The display window title.

;<var>profile</var>

:The name of the graphics profile to use. A graphics profile is also known as a colour scheme.

;<var>window</var>

:The window position and size (in the format '<code>x y width height</code>').

;<var>owner</var>

:The id of an existing display item which should own this new window. See <code>NEW DISPLAY</code> for details.

=====Result:=====

A new <code>XPlot</code> object if successful or an empty string.

=====Examples:=====

The simplest way to create an <code>XPlot</code> instance with one graph is as follows:

<pre>
#xplot := xplot
if '$#xplot[?]' != 'instance' em -1 ; Failed to create the xplot instance
</pre>

===XPlot Member Functions===

The <code>XPLOT</code> class has the following member functions. See CObjEx Member Functions for a list of functions implemented in the parent class.

====AddPlot====

The <code>XPLOT</code> function <code>AddPlot</code> is identical to the <code>PLOT</code> function, except that it adds to an existing graph (in addition to or on top of the original plot). If no graph exists at the specified <var>adr</var>, then the call is passed to <code>Plot</code>. It supports the following plot types: <code>XYPLOT</code>, <code>FUNCTION</code> and <code>PARAMETER</code>. The parameters are identical to the <code>[[#Plot|PLOT]]</code> function.

====Dialog====

The function <code>Dialog</code> can be used to show and hide a dialog in the <code>XPlot</code> display.

=====Usage:=====

<code><var>inst</var> Dialog <var>cmd</var> ; <var>args</var></code>

=====Parameters:=====

;<var>cmd</var>

:See below for details.

;<var>args</var>

:See below for details.

=====Result:=====

The ID of the current or new dialog item or an empty string.

====New====

Creates a new dialog item (deleting the old one first).

=====Usage:=====

<code><var>inst</var> Dialog New</code>

======Delete======

Removes the dialog from the display and deletes the dialog item.

=====Usage:=====

<code><var>inst</var> Dialog Delete</code>

======Msg======

Posts a message to the macro message queue. The format of the message is:

<code>MENU</code> <var>dialogItem</var> <var>msgId</var> <var>msgPar</var>

Note that when the display is closed, this function is called to post the message <code>MENU dialogItem CLOSE</code> to the dialog item.

=====Usage:=====

<code><var>inst</var> Dialog Msg ; <var>pos</var> ; <var>msgid</var> <var>msgpar</var></code>

=====Parameters:=====

;<var>pos</var>

:Sets the position of the dialog within the display. The following values are supported:

:<code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code>

;<var>msgid</var>

:The message ID.

;<var>msgpar</var>

:The message parameters.

======On|Enabled======

Show the dialog and set it's position.

=====Usage:=====

<code><var>inst</var> Dialog On; <var>pos</var></code>

<code><var>inst</var> Dialog Enabled; <var>pos</var></code>

=====Parameters:=====

;<var>pos</var>

:Sets the position of the dialog within the display. The following values are supported:

:<code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code>

======Off|Hidden======

Show the dialog and set it's position.

=====Usage:=====

<code><var>inst</var> Dialog Off ; <var>pos</var></code>

<code><var>inst</var> Dialog Hidden ; <var>pos</var></code>

=====Parameters:=====

;<var>pos</var>

:Sets the position of the dialog within the display. The following values are supported:

:<code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code>

====Display====

Returns the ID of the display object associated with this <code>XPLOT</code> instance.

=====Usage:=====

<code><var>inst</var> display</code>

=====Result:=====

Returns the display object of the <code>XPLOT</code> instance.

====End====

Enters the message loop, waits until the user closes the plot display and then destroys itself.

====Get====

Retrieve an attribute from a specific graph.

=====Usage:=====

<code><var>xplot</var> Get <var>adr</var> ; <var>attribute</var></code>

=====Parameters:=====

;<var>adr</var>

:The address of the display splitter (see member function <code>Graph</code> for detail).

;<var>attribute</var>

:The id of the requested attribute. The following values are supported:

:<code>CURSORPOSITION</code> - Returns the current cursor positions in the following format: <code>i1 x1 y1 i2 x2 y2</code>

:Note that <code>x1 <= x2</code>

:<code>YDATA</code> - Returns the y data item.

:<code>XDATA</code> - Returns the x data item.

:<code>RANGE</code> - Returns the x axis and y axis range in the following format: <code>xmin xmax ymin ymax</code>

:<code>TYPE</code> - Returns the plot type (see <code>Plot</code> for a list of available plot types).

====GetFColors====

The <code>GetFColors</code> function returns a blank separated list of the function colors defined in the selected graphics profile.

=====Usage:=====

<code><var>xplot</var> GetFColors</code>

=====Result:=====

Returns a blank separated list of color keywords.

====Graph====

Returns the requested attribute <var>attr</var> of the graph identified by <var>adr</var>.

=====Usage:=====

<code><var>xplot</var> Graph <var>adr</var> [; <var>attr</var>=GRAPH ]</code>

=====Parameters:=====

;<var>adr</var>

:The id of a graph item, an <code>[[Programmer Guide/Class Library/XGraph : CObjEx|XGRAPH]]</code> instance or the '<code>row column</code>' address of a splitter in the display. Note that the <code>row</code> and <code>column</code> indices are zero-based.

;<var>attr</var>

:The attribute to returned. The following values are allowed:

:<code>INSTANCE</code> - Return the id of the <code>XGRAPH</code> instance associated with <var>adr</var>.

:<code>GRAPH</code> - Return the id of the graph object associated with <var>adr</var>. This is the default attribute.

:<code>ROW</code> - Return the row index of the splitter associated with <var>adr</var>.

:<code>COLUMN</code> - Return the column index of the splitter associated with <var>adr</var>.

=====Result:=====

Return values are selected by the argument <var>attr</var>. See the description of <var>attr</var> for details. If the address argument <var>adr</var> do not refer to a graph, <code>XGRAPH</code> or splitter of the display, an empty string is returned.

=====Examples:=====

Get the graph item id for the top left graph.

<pre>
#graph := $#xplot graph 0 0
</pre>
====Legend====

Display a graph legend. Use <code>$#xplot LEGEND $#graph</code> to clear the legend.

=====Usage:=====

<code><var>xplot</var> Legend <var>graph</var> ; <var>unit</var> ; <var>x</var> ; <var>y</var> ; <var>w</var> ; <var>h</var> ; <var>color</var> ; <var>info</var> ; <var>text1</var> ; <var>text2</var> ; <var>textX</var></code>

=====Parameters:=====

;<var>graph</var>

:The graph address (e.g. row and column index. See [[#Plot|PLOT]] for detail).

;<var>unit</var>

:The unit for size and position values. The following values are supported:

:<code>real</code> - The real x/y values.

:<code>%</code> or <code>percent</code> - The percent of the graph's plot area.

;<var>x, y</var>

:The position of the upper right corner of the first legend line.

;<var>w, h</var>

:The width and height of one legend line.

;<var>color</var>

:The legend text color.

;<var>info</var>

:This flag selects the line attributes to be displayed. The following values are supported:

:<code>color</code> - The color.

:<code>all</code> - The color, style, width and symbol.

;<var>textX</var>

:The text for the legend for function X. If no text is supplied, the legend line is removed.This parameter can be either a string, or a simple table.

=====Result:=====

void

====Plot====

The <code>XPlot</code> function <code>Plot</code> can be used to plot a function in a graph. Currently, {{STX}} supports waveform , x/y (aka function and more specifically parameter), spectrogram and waterfall plots.

======XYPLOT======

Plot an x/y function graph.

=====Usage:=====

<code><var>xplot</var> Plot <var>adr</var> ; XYPLOT ; <var>y</var> ; <var>x</var> ; <var>title</var> ; <var>xr</var> ; <var>xu</var> ; <var>xt</var> ; <var>yr</var> ; <var>yu</var> ; <var>yt</var> ; <var>fstyles</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

;<var>adr</var>

:The address of the display splitter (see the member function [[#Graph|GRAPH]] for details).

;<var>y</var>

:The y axis data (a vector or an array).

;<var>x</var>

:The data to be used for the x axis. This can be one of the following:

:A data vector with <code>y[!nrow]</code> values and 1 column.

:<code>*</code> - An asterisk. This is the default and means that the x axis uses the values <code>0</code> through to <code>y[!nrow]-1</code>.

:A blank separated list of values ('x1 x2' -> x[i] = x1+(x2-x1)/(y[!nrow]-1), i = 0..<code>y[!nrow]-1</code>).

;<var>title</var>

:The title to be displayed in this plot.

;<var>xr</var>

:The x axis display range. This can be one of the following values:

:<code>*</code> - An asterisk - an automatic scale is generated.

:<code>xmin xmax</code> - Two numerical values - the minimum and maximum values.

;<var>xu</var>

:The text describing the x axis unit (e.g. <code>seconds</code>). The default is an empty string.

:The <code>WAVEFORM</code> plot only allows the following values: <code>SAMPLES</code>|<code>MS</code>|<code>S</code>. The default is <code>S</code>.

;<var>xt</var>

:The title to be used for the x axis. The default is an empty string.

;<var>yr</var>

:The y axis display range. This can be one of the following:

:<code>*</code> - An asterisk - an automatic scale is generated.

:<code>ymin ymax</code> - Two numerical values - the minimum and maximum values.

;<var>yu</var>

:The text describing the y axis unit (e.g. <code>dB</code>).

;<var>yt</var>

:The title to be used for the y axis. The default is an empty string.

;<var>fstyles</var>

:An <code>fstyle</code> argument (see <code>fstyle</code> for details) or a zero-based function line index as specified in a color scheme (see Color Schemes in the User Guide).

;<var>xlabtab, ylabtab, zlabtab</var>

:Extended tables containing the scale, grid and label definitions. For a description of the table format, please see the scale definition table for details.

=====Result:=====

Return <code>0</code> if successful.

=====Examples:=====

Plot a simple x/y function.

<pre>
#xplot := XPLOT 1 ; 1 ; XPLOT ; Default ; 0 0 400 400
$#xplot plot 0 ; XYPLOT; $(eval fill(10, 0, 1)) ; * ; xyplot ; * ; ; x-axis ; * ; ; y-axis
</pre>
======FUNCTION======

Plot a function graph. Note that this is identical to an <code>XYPLOT</code>.

=====Usage:=====

<code><var>xplot</var> Plot <var>adr</var> ; FUNCTION ; <var>y ; x ; title ; xr ; xu ; xt ; yr ; yu ; yt ; fstyles</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

See <code>XYPLOT</code> for parameter descriptions.

=====Result:=====

Return <code>0</code> if successful.

======parameter======

Plot a parameter graph. A parameter graph differs from a function graph because a parameter plot can have missing values - it does not necessarily have values for every point on the x axis.

=====Usage:=====

<code><var>xplot</var> Plot <var>adr</var> ; parameter ; <var>y ; title ; xr ; xu ; xt ; yr ; yu ; yt ; fstyles</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

See the <code>xyplot</code> for parameter details.

=====Result:=====

Return <code>0</code> if successful.

======spectrogram======

Plot a spectrogram graph.

=====Usage:=====

<code><var>xplot</var> plot <var>adr</var> ; spectrogram ; <var>d</var> ; <var>y</var> ; <var>title</var> ; <var>xr</var> ; <var>xu</var> ; <var>xt</var> ; <var>yr</var> ; <var>yu</var> ; <var>yt</var> ; <var>zr</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

;<var>d</var>

:A data array containing one spectrum or function line per <var>y</var> row. Note that this parameter is specific to the <code>SPECTROGRAM</code> and <code>WATERFALL</code> plots.

;<var>y</var>

:The y-scale data (frequency). This can be one of the following:

:1) <code>vData</code> - A data vector with <code>y[!ncol]</code> values and 1 column.

:2) * - An asterisk: <code>y[i] = i</code>, <code>i = 0..d[!ncol]-1</code>. This is the default.

:3) <code>y1 y2</code> - Two blank separated values: <code>y[i] = y1+i*(y2-y1)/(d[!ncol]-1)</code>, <code>i = 0..d[!ncol]-1</code>.

;<var>zr</var>

:The z scale is a color scale. The following values are supported:

:<code>*</code> - An asterisk. The range is automatically generated.

:<code>zmin zmax</code> - Two numerical values specifying the minimum and maximum z axis values.

:<code>zdown</code> - A numerical value. The maximum z value is chosen automatically and the minimum value is calculated as follows: <code>zmax-zdown</code>.

For all other parameters, see <code>xyplot</code> for descriptions.

======WATERFALL======

Plot a waterfall graph.

=====Usage:=====

<code><var>xplot</var> PLOT <var>adr</var> ; WATERFALL ; <var>d</var> ; <var>x</var> ; <var>title</var> ; <var>xr</var> ; <var>xu</var> ; <var>xt</var> ; <var>yr</var> ; <var>yu</var> ; <var>yt</var> ; <var>zr</var> ; <var>zu</var> ; <var>zt</var> ; <var>xw</var> ; <var>yw</var> ; <var>n</var> ; <var>xlabtab</var> ; <var>ylabtab</var> ; <var>zlabtab</var></code>

=====Parameters:=====

;<var>d</var>

:The data array (one spectrum or function-line / row).

;<var>zr</var>

:The z axis display range. The following values are supported:

:<code>*</code> - An asterisk. The range is automatically generated.

:<code>zmin zmax</code> - Two numerical values specifying the minimum and maximum z axis values.

;<var>zu</var>

:The text describing the z axis unit (e.g. <code>s</code>).

;<var>zt</var>

:The title to be used for the z axis. The default is an empty string.

;<var>xw</var>

:The relative width of the x scale. A value between <code>-1</code> and <code>1</code>. The default is <code>0.8</code>.

;<var>yw</var>

:The relative width of the y scale. A value between <code>-1</code> and <code>1</code>. The default is <code>0.8</code>.

;<var>n</var>

:The number of lines to be plotted. The default is <code>150</code>.

For all other parameters, see <code>XYPLOT</code> for descriptions.

======WAVEFORM======

Plot a waveform graph. Note that the displayed wave item is automatically attached to the graph. This means, no explicit call to <code>SetWave</code> is necessary.

=====Usage:=====

<code><var>xplot</var> PLOT <var>adr</var> ; WAVEFORM ; <var>wave</var> ; <var>title</var> ; <var>xu</var> ; <var>xt</var> ; <var>ymax</var> ; <var>yr</var> ; <var>yt</var> ; <var>fill</var></code>

=====Parameters:=====

;<var>wave</var>

:A wave item id or an <code>XWAVE</code> instance

;<var>xu</var>

:The unit to use on the x axis. The following values: <code>SAMPLES</code>|<code>MS</code>|<code>S</code>. The default is <code>S</code>.

;<var>ymax</var>

:The maximum waveform amplitude. This can be a value between 0 and ...

;<var>yr</var>

:The y axis display range. This can be any positive number. The default is <code>1</code>.

;<var>fill</var>

:<code>1</code> if the waveform envelope should be filled or <code>0</code>.

For all other parameters, see <code>XYPLOT</code> for descriptions.

======TEXTBOX======

Plot a graph containing text.

=====Usage:=====

<code><var>xplot</var> PLOT <var>adr</var> ; TEXTBOX ; <var>title</var> ; <var>color</var> ; <var>halign</var> ; <var>valign</var> ; <var>text</var></code>

=====Parameters:=====

;<var>title</var>

:The graph title.

;<var>color</var>

:The text color. This can be an of the {{STX}} color arguments.

;<var>halign</var>

:The horizontal text alignment. This can be one of the following values: <code>CENTER</code>|<code>LEFT</code>|<code>RIGHT</code>

;<var>valign</var>

:The vertical text alignment. This can be one of the following values: <code>CENTER</code>|<code>TOP</code>|<code>BOTTOM</code>

;<var>text</var>

:The text to be displayed. This can be a simple table with an entry per line of text or a semi-colon separated list of text lines.

For all other parameters, see <code>XYPLOT</code> for descriptions.

======fstyle======

The <var>fstyle</var> argument passed to the <code>XPlot</code> functions <code>Plot</code> and <code>AddPlot</code> has the following syntax and components:

<code><var>linestyle</var><code>:</code><var>linecol</var><code>:</code><var>printcol</var><code>:</code><var>linewidth</var><code>:</code><var>drawstyle</var><code>:</code><var>drawsym</var><code>:</code><var>ymiss</var></code>

;<var>linestyle</var>

:Determines whether the function line is solid (<code>SOLID</code>), dotted (<code>DOT</code>) or dashed (<code>DASH</code>). The default value is taken from the <code>XPLOT</code> color profile.

;<var>linecol</var>

:The colour to use for the function line on screen. This can be any {{STX}} colour keyword or RGB value. The default value is taken from the <code>XPLOT</code> color profile.

;<var>printcol</var>

:The colour to use for the function line when printing. See <var>linecol</var> for details. The default value is taken from the <code>XPLOT</code> color profile.

;<var>linewidth</var>

:The width of the function line. Possible values are <code>0</code> through to <code>4</code> for lines with the <code>SOLID</code> <var>linestyle</var> and <code>0</code> or <code>1</code> for lines with the <code>DOT</code> or <code>DASH</code> <var>linestyle</var>. The default value is taken from the <code>XPLOT</code> color profile.

;<var>drawstyle</var>

:The style to use to draw the function. Each function point can be plotted separately (<code>POINTS</code>), a line can be drawn between each function point (<code>LINES</code>), the area below the function can be filled with the <var>linecol</var> (<code>AREA</code>), the function points can be joined by steps (<code>STEPS</code> - note that this is only available for the <code>PARAMETER</code> plot) or no points are plotted (<code>NONE</code> - this is best used when a drawing symbol (<var>drawsym</var>) is defined). The default style is <code>LINES</code>.

;<var>drawsym</var>

:The symbol to draw at each point. This can be used in conjunction with a drawing style (see <var>drawstyle</var>). The following keywords are supported:

:<code>NONE</code>|<code>SQUARE</code>|<code>TRIANGLE|CIRCLE|CROSS|DIAMOND</code>

:The default style is <code>NONE</code>.

;<var>ymiss</var>

:The value to use for missing y values. If <var>ymiss</var> is not specified (empty) all values are displayed, otherwise all points where <code>y=</code><var>ymiss</var> are not displayed. If <var>ymiss</var> is not empty and is not a number then <var>ymiss</var> is set to <code>0</code>. If no <var>ymiss</var> is defined, no <var>ymiss</var> is used (this is the default).

====Redraw====

Redraw the selected graph. This is currently only implemented for the <code>FUNCTION</code> (<code>XYPLOT</code>) and <code>PARAMETER</code> plots.

=====Usage:=====

<code><var>xplot</var> REDRAW <var>adr</var></code>

=====Parameters:=====

;<var>adr</var>

:The address of the display splitter (see member function <code>Graph</code> for details).

=====Result:=====

Return 0 if successful.

====ScaleOctave====

Generate a logarithmic scale table for use with the <code>Plot</code> or <code>AddPlot</code> functions. This function can also be called statically.

=====Usage:=====

<code><var>xplot</var> ScaleOctave <var>df</var> <var>count</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code>xplot ScaleOctave <var>df</var> <var>count</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code><var>xplot</var> ScaleOctave <var>vector</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code>xplot ScaleOctave <var>vector</var> ; <var>fmax</var> ; <var>fmin</var></code>

=====Parameters:=====

;<var>df</var>

:The frequency resolution in Hz.

;<var>count</var>

:The number of frequency points.

;<var>fmax</var>

:The maximum frequency to be displayed.

;<var>fmin</var>

:The minimum frequency to be displayed.

;<var>vector</var>

:The scale range as a data vector.

=====Result:=====

The following string is returned:

<code>xmin xmax xlabTab xdata</code>

Where <code>xmin</code> and <code>xmax</code> are is the minimum and maximum of the logarithmic scale, <code>xlabTab</code> is the scale definition table which you can then pass to a <code>Plot</code> function and <code>xdata</code> is the logarithmic frequency values vector. See the scale definition table description in the Command Reference for details of the table syntax.

=====Examples:=====

Create a scale definition table for a logarithmic frequency axis with 2000 points at 10 Hz intervals and a maximum frequency of 10000 Hz.

<pre>
readstr '$(xplot scaleOctave 10 2000; 10000)' #xmin #xmax #xlab #x
</pre>
=====Notes:=====

See also ScaleSteps.

====ScaleLog10====

Generate a logarithmic scale table for use with the <code>Plot</code> or <code>AddPlot</code> functions. This function can also be called statically.

=====Usage:=====

<code><var>xplot</var> ScaleLog10 <var>df</var> <var>count</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code>xplot ScaleLog10 <var>df</var> <var>count</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code><var>xplot</var> ScaleLog10 <var>vector</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code>xplot ScaleLog10 <var>vector</var> ; <var>fmax</var> ; <var>fmin</var></code>

=====Parameters:=====

;<var>df</var>

:The frequency resolution in Hz.

;<var>count</var>

:The number of frequency points.

;<var>fmax</var>

:The maximum frequency to be displayed.

;<var>fmin</var>

:The minimum frequency to be displayed.

;<var>vector</var>

:The scale range as a data vector.

=====Result:=====

The following string is returned:

<code>xmin xmax xlabTab xdata</code>

Where <code>xmin</code> and <code>xmax</code> are is the minimum and maximum of the logarithmic scale, <code>xlabTab</code> is the scale definition table which you can then pass to a <code>Plot</code> function and <code>xdata</code> is the logarithmic frequency values vector. See the scale definition table description in the Command Reference for details of the table syntax.

=====Notes:=====

See also <code>ScaleSteps</code> and <code>ScaleOctave</code>.

====ScaleSteps====

Generate a linear scale table for use with the <code>Plot</code> or <code>AddPlot</code> functions. This function can also be called statically, e.g. '<code>xplot ScaleSteps -70 -10 ; 10 ; 5 ; 5 ; 1 ; 1</code>'.

=====Usage:=====

<code><var>inst</var> ScaleSteps <var>min</var> <var>max</var> ; <var>labelDist</var> ; <var>majorGridDist</var> ; <var>majorTickDist</var> ; <var>minorGridDist</var> ; <var>minorTickDist</var></code>

<code>xplot ScaleSteps <var>min</var> <var>max</var> ; <var>labelDist</var>; <var>majorGridDist</var>; <var>majorTickDist</var> ; <var>minorGridDist</var> ; <var>minorTickDist</var></code>

<code><var>inst</var> ScaleSteps <var>vector</var> ; <var>labelDist</var>; <var>majorGridDist</var>; <var>majorTickDist</var> ; <var>minorGridDist</var> ; <var>minorTickDist</var></code>

<code>xplot ScaleSteps <var>vector</var> ; <var>labelDist</var>; <var>majorGridDist</var>; <var>majorTickDist</var> ; <var>minorGridDist</var> ; <var>minorTickDist</var></code>

=====Parameters:=====

;<var>min, max</var>

:The scale range.

;<var>vector</var>

:The scale range as a data vector.

;<var>labelDist</var>

:The label distance in scale units.

;<var>majorGridDist</var>

:The distance of the major grid lines in scale units.

;<var>majorTickDist</var>

:The distance between major ticks in scale units.

;<var>minorGridDist</var>

:The distance of the minor grid lines in scale units.

;<var>minorTickDist</var>

:The distance between minor ticks in scale units.

=====Result:=====

The following string is returned:

<code>min max labTab</code>

Where <code>min</code> and <code>max</code> are is the computed or corrected scale range and <code>labTab</code> is the scale definition table which you can then pass to a <code>Plot</code> function. See the scale definition table description in the Command Reference for details of the table syntax.

=====Examples:=====

Calculate the linear scale, grid and labels for an amplitude axis between -70 and -10 dB with labels every 10 dB, major grid lines and ticks every 5dB and minor grid lines and ticks every dB.

<pre>
readstr '$($#xplot ScaleSteps -70 -10 ; 10 ; 5 ; 5 ; 1 ; 1)' #ymin #ymax #ylab
</pre>
=====Notes:=====

See also <code>ScaleOctave</code> and <code>ScaleLog10</code>.

====Set====

The <code>Set</code> function sets the cursor mode and text attributes.

=====Usage:=====

<code><var>xplot</var> Set [ <var>graph</var>|* ; ] <var>attr</var> <var>args</var></code>

=====Parameters:=====

;<var>xgraph</var>

:An xgraph instance on which to call the <code>Set</code> command. If no graph is specified or an asterisk, then the <code>Set</code> command is carried out on all graphs.

;<var>attr</var>

:One of the following values:

:<code>cursormode</code> - turn cursors on and off and change the way they look.

:<code>xunit</code> - the name of the x-axis unit

:<code>yunit</code> - the name of the y-axis unit

:<code>xtext</code> - the description of the x-axis

:<code>ytext</code> - the description of the y-axis

:<code>title</code> - the graph's title

;<var>args</var>

:The value of <var>args</var> depends on <var>attr</var>.

:If <var>attr</var> is <code>cursormode</code>, then <var>args</var> is as follows:

:<code>mode|* type|* line|*</code>

:Where mode is one of the following values:

:<code>on</code> - show the cursor

:<code>off</code> - hide the cursor

:Where <var>type</var> is one of the following values:

:<code>cross</code>|<code>crosshair</code>|<code>vbarcross</code>|<code>harmonic</code>

:And <code>line</code> is one of the following values:

:<code>off</code> |<code>on</code>

:If <var>attr</var> is not <code>cursormode</code>, then <var>args</var> is used as the text, unit or title.

=====Result:=====

No return value.

====SetCallback====

The callback function is called by the message handlers to process popup and context menu messages and hotkeys which are not used by <code>XPLOT</code> or <code>XGRAPH</code>. The following commands are used to call the callback function:

If called from an <code>XGRAPH</code> message handler:

<code>cbfunction xgraphinstance irow icol msgid msgpar</code>

If called from the <code>XPLOT</code> message handler:

<code>cbfunction xplotinstance * * msgid msgpar</code>

=====Usage:=====

<code><var>xplot</var> SetCallback [ <var>cbfunction</var> ]</code>

=====Parameters:=====

;<var>cbfunction</var>

:The name of the callback function or an empty string to remove a previous association.

=====Result:=====

No return value.

====SetWave====

Attach a signal to one graph or all graphs (see <var>adr</var>). If a wave item is attached to a graph, it can not be deleted before it is detached or the graph or <code>XPLOT</code> instance is deleted.

=====Usage:=====

<code><var>xplot</var> SetWave [ <var>waveitem</var> ]</code>

<code><var>xplot</var> SetWave <var>adr</var> ; [ <var>waveitem</var> ]</code>

=====Parameters:=====

;<var>adr</var>

:The address of the display splitter (see member function Graph for details). If this parameter is omitted, then the wave item is set for all graphs.

;<var>waveitem</var>

:A wave item id or an <code>[[Programmer Guide/Class Library/XWave : CObjEx|XWAVE]]</code> instance (or empty to remove attachment).

=====Result:=====

Return <code>0</code> if successful.

Note that wave items can only be attached to graphs of type <code>FUNCTION</code>, <code>XYPLOT</code>, <code>PARAMETER</code>, <code>SPECTROGRAM</code> and <code>WAVEFORM</code>.====XPlot Hotkeys====

The following hotkeys are implemented in the <code>XPLOT</code> class:

{|
|-
|C
|Turn the cursors on and off.
|-
|S
|Change to the next cursor style.
|-
|B
|Turn cursor binding on and off.
|-
|Ctrl+N
|Bind the cursor to the next function.
|-
|Ctrl+P
|Bind the cursor to the previous function.
|-
|R
|Turn the cursor rubberline on and off.
|-
|T
|Turn the title on and off.
|-
|X
|Change to the next x<nowiki>-</nowiki>scale mode.
|-
|Y
|Change to the next y<nowiki>-</nowiki>scale mode.
|-
|Z
|Change to the next z<nowiki>-</nowiki>scale mode.
|-
|Space
|Open the setup dialog.
|-
|P
|Play the attached wave (between the cursors).
|-
|Q
|Play the attached wave (the whole signal).
|-
|ESC
|Stop playback.
|-
|Ins
|Show the selected metasegment's settings in a dialog or, if no metasegment is selected, show a dialog to create a new metasegment.
|-
|Del
|Delete the selected metasegments.
|-
|Ctrl+Left Click
|Move the legend to the clicked position.
|-
|Shift+Left Click
|Create a metasegment at the clicked position (show the 'Insert Metasegment' dialog).
|}

====XPlot Examples====

=====Simple XPLOT Example=====

The following example demonstrates simple <code>[[Programmer Guide/Class Library/XPlot : CObjEx|XPLOT]]</code> usage.

<pre>
[macro xplot_example_1]
//
// create display (and graph)
//
#xplot := xplot 2 ; 1 ; xplot ; default ; 100 100 800 800
if '$#xplot[?]' != 'instance' em -1 ; xplot creation failed ($emsg)
//
// plot graphs (including data generation)
//
#nValues := 100
$#xplot Plot 0 0 ; XYPLOT ; $(eval fill($#nValues,1,1)) ; * ; Graph Title ; * ; x unit ; x title ; * ; y unit ; y title ; solid:green::1
$#xplot Plot 1 0 ; SPECTROGRAM ; $(eval rand(1,100,100)) ; * ; Graph Title ; * ; x unit ; x title ; * ; y unit ; y title ; solid:green::1
//
// clean up
//
// the clean up takes place automatically
// when the plot window is closed
exit
</pre>
=====Plot rows of a matrix using XPLOT=====

The following example demonstrates how to plot the rows of a matrix using the <code>[[Programmer Guide/Class Library/XPlot : CObjEx|XPLOT]]</code> class.

<pre>
//{{3.9 6473}{2009.01.29 16.44.04} - automatically created version information - do not change or delete this line}

[macro xplot_example_2]

//
// This row demonstrates how to plot each row of a matrix
//
// C.G. 29.1.2009
//

//
// create display (and graph)
//

#xplot := xplot 1 ; 1 ; xplot ; default ; 100 100 800 800
if '$#xplot[?]' != 'instance' em -1 ; xplot creation failed ($emsg)

//
// create a matrix and fill it with some meaningless data
//

#mat := new table * /Parameter * number:X:100
if '$#mat[?]' != table em -1 ; cannot create table ($emsg)

for #i := 0 to $#i < 10 step #i := int $#i + 1
$#mat[$#i,*] := eval fill( 100, $#i+1, $#i+1 )
end

//
// plot each row of the matrix
//

for #i := int 0 to $#i < $#mat[!nrow] step #i := int $#i + 1
#x := eval $#mat[$#i,*]
$#xplot AddPlot 0 0 ; XYPLOT ; $#x ; * ; row-by-row plot ; * ; x unit ; x title ; * ; y unit ; y title ; solid:green::1
end

exit 1 int 0
</pre>

=====Advanced XPLOT Example=====

This example not only demonstrates the use of the <code>XPLOT</code> class, but also signal processing using the <code>EVAL</code> function.

<pre>
//=================================================================================================
//
// DSP Examples
//
// last update: Nov 17, 2007 (AN)
// {{STX}} version: {{STX}} 3.8 Beta
//
// The examples in this file demonstrates how to ...
// ... use the EVAL command for signal processing
// ... use the class XWAVE to read a signal frame by frame
// ... display spectrograms, waveforms and functions in XPLOT graphs
// ... enable XPLOT to play signals
// ... use the XPLOT callback function to implement simple user controls
// ... set and get cursor attritbutes and positions of XPLOT graphs
// ... add a legend to a XPLOT graph
// ... use BUTIL MSGBOX for simple dialogs
// ... use the CON object (class BScript) to display log. messages
// ... use the CON object to save numeric tables to textfiles
// ... simulate item messages using the message queue macro MSGQUEUE
// ... implement and call local subroutines
//
//=================================================================================================

//-------------------------------------------------------------------------------------------------
//
// DSPExAvrSpectrum Create a plot containing the average spectra of all segments selected
// in the DataSet view.
//
//-------------------------------------------------------------------------------------------------
[Macro DSPExAvrSpectrum #lfrm=100ms';'#sfrm=50%';'#wtyp=hamming';'#ascale=dB';'#fscale=Hz';'#amax=1';'#aref=1';'#]
// arguments: #lfrm frame length, absolute time expression
// #sfrm frame shift, relative time expression
// #wtyp window type, {Hanning, Hamming, ...)
// #fscale spectrogram frequency scale unit (Hz, kHz, Bark, Mel, ERB)
// #amax calibration factor or CALSET to use a calibration set
// #aref reference amplitude, ignored if #amax equals CALSET

// set mode to macro name (see macro DSPExCallback)
DSPExMode := set '$#mac'

// get segments selected in the DataSet view
#segments := dspexlib getsegments

// create the result table (one spectrum per row)
#asp := new table * * num:x:$#segments[] /p

// segment analysis loop
#nok := 0 // number of computed average spectra
for #i := 0 to $#i < $#segments[] step #i := int $#i+1

// get next segment from segment list
readtab $#segments $#i #aset';'#aseg';'#ach';'#
con log process segment "set=$#aset, id=$#aseg, ch=$#ach" ($(int $#i+1) of $#segments[])

// create the wave object and initialize frame settings (mode "centered")
// usage: XWAVE setref ; segmentid ; channel ; mode ; framelength ; frameshift ; ampmax ; ampref
if $(#wave := xwave '$#aset;$#aseg;$#ach;1;$#lfrm;$#sfrm;$#amax;$#aref')[?] != instance then
butil 'msgbox msg; create wave object for segment "$#aset/$#aseg,$#ach" failed; Error!'
continue
// set / check sampling rate
else if '$#srate' == '' then
#srate := $($#wave srate)
else if $($#wave srate) != $#srate then
butil 'msgbox msg; segment "$#aset/$#aseg,$#ach" - sampling rate mismatch; Error!'
$#wave destroy // delete wave object
continue
end

// compute the average spectrum
if $(#tmp := dspexlib averagespectrum $#wave ; $#wtyp ; $#ascale)[?] != table then
butil 'msgbox msg; compute average spectrum of segment "$#aset/$#aseg,$#ach" failed; Error!'
$#wave destroy // delete wave object
continue
end

$#asp[*,$#nok] := $#tmp // save the spectrum
delete $#tmp // delete temp. buffer
#legend := '$#legend $($#wave title);' // add segment to legend string
$#wave destroy // delete wave object
#nok := int $#nok+1 // increment result vector counter

end

// exit if no results are computed
if $#nok < 1 exit

// compute frequency scale vector, unit and frequency resolution
readstr '$(dspexlib frequencyscale $#srate ; $#asp[!nrow] ; $#fscale)' #frq #funit #df

// create and configure the plot object
// usage: XPLOT rows ; cols0 cols1 .. ; windowtitle ; graphicprofile ; wx wy wwidth wheight
#plot := xplot 1; 1; Average Spectrum; Rainbow; 0 0 1024 800

// plot all spectra and display the legend
#title := format 'lfrm=%s, sfrm=%s, wtyp=%s, df=%.3fHz' '$#lfrm' '$#sfrm' '$#wtyp' $#df
readstr '$(dspexlib amplitudescale $#ascale)' #ytext #yunit
// usage: xplot PLOT row col; FUNCTION; ydata; xdata; title; xrange; xunit; xtext; yrange; yunit; yrange
$#plot plot 0; function; $#asp; $#frq; $#title; ; $#funit; frequency; ; $#yunit ; $#ytext
$#plot legend 0; %; 50; 95; 45; 5; black; color; $#legend
$#plot set cursormode on crosshair // set cursor mode and style
$#plot setcallback dspexcallback // assign callback function

// wait until plot window is closed
$#plot end // the xplot object is destroyed automatically when the window is closed

// finished - cleanup and and exit
delete $#asp $#frq $#segments // delete data items
showLogOnExit := 0 // close the bscript log-window automatically
exit

//-------------------------------------------------------------------------------------------------
//
// DSPExSpectrogram Plot a spectrogram of all segments selected in the DataSet view.
// For each segment one spectrogram window is displayed. The window
// must be closed before the next segment is analysed.
//
//-------------------------------------------------------------------------------------------------
[Macro DSPExSpectrogram #lfrm=40ms';'#sfrm=10%';'#wtyp=hamming';'#arange=50';'#fscale=Hz';'#amax=1';'#aref=1';'#]
// arguments: #lfrm frame length, absolute time expression
// #sfrm frame shift, relative time expression
// #wtyp window type, {Hanning, Hamming)
// #arange spectrogram display range in dB (max .. max-range)
// #fscale spectrogram frequency scale unit (Hz, kHz, Bark, Mel, ERB)
// #amax calibration factor or CALSET to use a calibration set
// #aref reference amplitude, ignored if #amax equals CALSET

// set mode variable to macro name (see macro DSPExCallback)
DSPExMode := set '$#mac'

// get segments selected in the DataSet view
#segments := dspexlib getsegments

// segment analysis loop
for #i := 0 to $#i < $#segments[] && '$DSPExMode' != '' step #i := int $#i+1

// get next segment from segment list
readtab $#segments $#i #aset';'#aseg';'#ach';'#

// create the wave object and initialize frame settings (mode "centered")
if $(#wave := xwave '$#aset;$#aseg;$#ach;1;$#lfrm;$#sfrm;$#amax;$#aref')[?] != instance then
butil 'msgbox msg; create wave object for segment "$#aset ; $#aseg ; $#ach" failed; Error!'
continue
end

// compute the spectrogram
if $(#asp := dspexlib spectrogram $#wave ; $#wtyp ; log)[?] != table then
butil 'msgbox msg; compute spectrogram of segment "$#aset ; $#aseg ; $#ach" failed; Error!'
$#wave destroy
continue
end

// compute frequency scale vector, unit and frequency resolution
readstr '$(dspexlib frequencyscale $($#wave srate) ; $#asp[!ncol] ; $#fscale)' #frq #funit #df

// create and configure the plot object
#plot := xplot 2; 1 1; $($#wave title) quit = c-q, next = c-n; Rainbow; 0 0 1024 800
$($#plot display) height 3 1 /apply // set height of graphs

// plot spectrogram and waveform
#title := format 'lfrm=%s, sfrm=%s, wtyp=%s, arange=%s, amax=%.1fdB, df=%.3fHz' '$#lfrm' '$#sfrm' '$#wtyp' '$#arange' $(eval max($#asp)) $#df
$#plot plot 0; spectrogram; $#asp; $#frq; $#title; $($#wave tbegin) $($#wave tend); s; time; ; $#funit; frequency; $#arange
$#plot plot 1; waveform; $#wave; ; s; time; $($#wave amax); $($#wave amax); amplitude; 1
$#plot set cursormode on crosshair // set cursor mode and style
$#plot setcallback dspexcallback // assign callback function

// assign wave object to xplot graphs (for playback)
$#plot setwave $#wave

// wait until plot window is closed
$#plot end // the xplot object is destroyed automatically when the window is closed

// cleanup
delete $#asp $#frq // delete data items
$#wave destroy // delete wave object
end

// finished - cleanup and exit
delete $#segments // delete segment table
showLogOnExit := 0 // close the bscript log-window automatically
exit

//-------------------------------------------------------------------------------------------------
//
// DSPExCallback Callback function for XPLOT.
//
// arguments:
// if called from xplotobject message handler -> 'CALLBACK xplotobject * * msgid msgpar'
// if called from xgraphobject message handler -> 'CALLBACK xgraphobject row col msgid msgpar'
//
// Note: This macro uses the shell variable DSPEXMODE to check which macro has installed the
// callback and to set return values.
//
//-------------------------------------------------------------------------------------------------
[Macro DSPExCallback #obj #row #col #msgid #msgpar]

// get xplot-object if called from a xgraph-object
if '$#obj[!class]' == xgraph #obj := $#obj get xplot

// message filter for keystroke messages

// process Control-Q (QUIT) key
if '$#msgid$#msgpar' == keyCQ then

if $(butil msgbox yesno; Quit ?; $DSPExMode) == yes then
// place the display-close message in the message queue to end the xplot message loop
msgqueue 'display $($#obj display) close'
// set mode variable to empty-string if C-Q key was pressed
DSPExMode := ''
end

// process Control-C (COPY) and Control-S (SAVE) keys
else if $(#i := keyword '$#msgid$#msgpar' keyCC keyCS) >= 0 then

// get xgraph-object displayed in row 0 (later used to retrieve data)
#obj := $#obj graph 0; instance

// select the data to be saved and the save format
#todo := butil msgbox userdefined Amp Frq+Amp Cancel;; $DSPExMode - $(word $#i 'Copy to Clipboard' 'Save to CSV-File')
if $#todo == Amp then
#table := eval $($#obj get ydata) // use eval to get a copy of y-data
else if $#todo == Frq+Amp then
if '$DSPExMode' == DSPExAvrSpectrum then
#table := eval vmcol( $($#obj get xdata) , $($#obj get ydata) ) // merge x- and y-data into one table
else
#table := eval vmcol( $($#obj get xdata) , trn($($#obj get ydata)) ) // merge x- and transposed y-data into one table
end
end

// copy / save if table exists
if $#table[?] == table then
// select target
if $#i == 0 then
#file := set clipboard // set target to "clipboard" for all copy_xxx functions
else
#file := butil filedialog save; Select Output File; ; CSV=CSV-File; TXT=Textfile // use filedialog to select the output file
end

// use the CON-object to copy/save table
if '$#file' != '' con savedata text; $#table; $#file; 0; comma; dot
delete $#table
end

// process Control-I (INFO) || Control-M (MAX-MEAN) keys
else if $(#i := keyword '$#msgid$#msgpar' keyCI keyCM) >= 0 then

// get xgraph-object displayed in row 0
#obj := $#obj graph 0;inst

// save original graph title
if '$GraphTitle' == '' GraphTitle := $#obj get title

if $#i == 0 then
// get and display cursor positions
readstr '$($#obj get cursorposition)' #i1 #x1 #y1 #i2 #x2 #y2 #
#text := format 'Index = %d .. %d, X = %g ... %g (%g), Y = %g ... %g (%g)' $#i1 $#i2 $#x1 $#x2 abs($#x1-$#x2) $#y1 $#y2 abs($#y1-$#y2)
else
// set cursor mode (on), style (crosshair), rubberline (off), bind-mode (off), bind-functionindex (0)
$#obj set cursormode on crosshair off off 0
// get x- and y-data
#x := $#obj get xdata
#y := $#obj get ydata
// find index of maximum y value
#imax := eval imax($#y[*,0])
// compute mean of x and y
#xavr := eval avr($#x)
#yavr := eval avr($#y)
// set cursor 1 to maximum and cursor 2 to mean
$#obj set cursorpos 1 $#x[$#imax] $#y[$#imax] deselect
$#obj set cursorpos 2 $#xavr $#yavr deselect
// show maximum and mean in xgraph title
#text := format 'Maximum( %g , %g ), Average( %g , %g )' $#x[$#imax] $#y[$#imax] $#xavr $#yavr
end
// show info in graph title
$#obj set title $GraphTitle -- $#text

end

// note: the return value of the callback function is not used by the xplot/xgraph message handler
exit

//-------------------------------------------------------------------------------------------------
//
// DSPExLib Implements a set of signal processing functions which can be called with
// "DSPLIBEXAMPLE functionname functionarguments". This call style is often
// used to reduce the number of macros of a script or application.
//
// Functions:
//
// DSPEXLIB GETSEGMENTS
// result: a list of all segments selected in the DataSet view stored in a simple
// table (per line: 'setReference ; segmentId ; channelIndex')
// note: this function shows an error message and terminates the caller if no segments
// are selected
//
// DSPEXLIB AVERAGESPECTRUM wave ; wtyp ; atyp
// wave prepared xwave object
// wtyp type of window function: HANNING, HAMMING, KAISER, ...
// atyp type of output spectrum: LOGARITHMIC (=DB), POWER, LINEAR (=AMPLITUDE)
// result: an averaged fft spectrum in the selected format
//
// DSPEXLIB SPECTROGRAM wave ; wtyp ; atyp
// wave prepared xwave object
// wtyp type of window function: HANNING, HAMMING, KAISER, ...
// atyp type of output spectrum: LOGARITHMIC (=DB), POWER, LINEAR (=AMPLITUDE)
// or COMPLEX
// result: a matrix of fft spectra in the selected format, one spectrum per line
//
// DSPEXLIB FREQUENCYSCALE sr ; n ; type
// sr sampling rate in Hz
// n number of spectrum bins (equally spaced in the Hz domain)
// type type of frequency scale: HZ, KHZ, BARK, MEL, ERB
// result: 'frq unit df'; frq is the frequency scale vector, unit is the frequency unit
// name and df is the frequency scale step in Hz
//
// DSPEXLIB AMPLITUDESCALE type
// type type of amplitude scale: LOGARITHMIC (=DB), POWER, LINEAR (=AMPLITUDE)
// result: 'name unit df'; name and unit of amplitude scale
//
//-------------------------------------------------------------------------------------------------
[Macro DSPExLib]

// function call dispatching
readvar #argv #fun #argv /d
goto fun$#fun noFun

noFun:
// function not implemented
// result: empty string

// show an error message and exit
con log '$#mac function "$#fun" not implemented'
exit 1 set ''

//-------------------------------------------------------------------------------------------------
funGetSegments: // in:
// out: segment_list_table
//-------------------------------------------------------------------------------------------------
// retrieve list of selected segments from the DataSet application
#segments := datasetcmd getselected segments
if '$#segments[?]' == table && '$#segments[]' > 0 exit 1 set $#segments
butil msgbox msg ; no segments selected - select and try again; Error!
if '$#segments[?]' == table delete $#segments
exit 2 set '' // terminate this and the calling macro!

//-------------------------------------------------------------------------------------------------
funAverageSpectrum: // in: xwaveobject ; windowtype ; amplitudescale
// out: averagespectrum_vector
//-------------------------------------------------------------------------------------------------
// parse arguments
readvar #argv #wave';'#wtyp';'#atyp';'#

// show init message
con log $#mac $(upper '$#fun') - initializing

// create window
#w := gosub makewindow $($#wave framelength) $#wtyp

// create result table
#spg := new table *

// compute averaged amplitude spectrum
#n := $($#wave framecount)
$#spg := eval cr2len ( fft ( $($#wave read) ?* $#w ) )
for #i := 1 to $#i < $#n step #i := int $#i+1
if $#i%10 == 0 con logext 0; $#mac $(upper '$#fun') - $#i of $#n frames processed
$#spg := eval cr2len ( fft ( $($#wave read) ?* $#w ) ) + $#spg
end
$#spg := eval $#spg / $#n

// convert to selected output spectrum type
if $(#atyp := keyword '$#atyp' dB logarithmic power amplitude linear) < 2 then
$#spg := eval lin2log($#spg , $($#wave aref), 20)
else if $#atyp == 2 then
$#spg := eval $#spg ?^ 2
end

// show end message
con logext 0; $#mac $(upper '$#fun') - finished ($#n spectra computed)

// return averaged spectrum
exit 1 set $#spg

//-------------------------------------------------------------------------------------------------
funSpectrogram: // in: xwaveobject ; windowtype ; amplitudescale
// out: spectrogram_matrix
//-------------------------------------------------------------------------------------------------
// parse arguments
readvar #argv #wave';'#wtyp';'#atyp';'#

// show init message
con log $#mac $(upper '$#fun') - initializing

// create window
#w := gosub makewindow $($#wave framelength) $#wtyp

// check selected output spectrum type
if $(#atyp := keyword '$#wtyp' dB logarithmic power amplitude linear complex) < 5 then
// compute amplitude or power spectra

// create result table (one spectrum per line)
#spg := new table * * num:x:$(int $($#wave fftlength)/2 + 1) /p
// compute amplitude spectra
#n := $($#wave framecount)
for #i := 0 to $#i < $#n step #i := int $#i+1
if $#i%10 == 0 con logext 0; $#mac $(upper '$#fun') - $#i of $#n frames processed
$#spg[$#i,*] := eval cr2len ( fft ( $($#wave read) ?* $#w ) )
end
// convert to selected output spectrum type
if $(#atyp := keyword '$#atyp' dB logarithmic power amplitude linear) < 2 then
$#spg := eval lin2log($#spg , $($#wave aref), 20)
else if $#atyp == 2 then
$#spg := eval $#spg ?^ 2
end

else
// compute complex spectra

// create result table (one spectrum per line)
#spg := new table * * num:x:$(int $($#wave fftlength) + 2) /p
// compute complex spectra
for #i := int $($#wave framecount) to $#i > 0 step #i := int $#i-1
if $#i%50 == 0 con logext 0; $#mac $(upper '$#fun') - $#i of $#n frames processed
$#spg[$#i,*] := eval fft ( $($#wave read) ?* $#w )
end

end

// show end message
con logext 0; $#mac $(upper '$#fun') - finished ($#n spectra computed)

// return spectrogram matrix
exit 1 set $#spg

//-------------------------------------------------------------------------------------------------
funFrequencyScale: // in: samplingrate ; spectrumbins ; frequencyscale
// out: frequencyscale_vector frequencyscale_unit frequency_resolution_Hz
//-------------------------------------------------------------------------------------------------
// parse arguments
readvar #argv #sr';'#n';'#unit';'#
// generate frequency scale equally spaced in Hz
#frq := new table * // dummy table to make frq-scale permanent
$#frq := eval fill($#n, 0, $(#df := eval $#sr / 2 / ($#n - 1)) )
// convert to selected scale
if $(#unit := keyword '$#unit' Hz kHz Bark Mel ERB) < 0 #unit := 0
if $(#unit := word $#unit Hz kHz Bark Mel ERB) == kHz then
$#frq := eval $#frq / 1000
else if $#unit != Hz then
$#frq := eval hz2$#unit($#frq)
end
// return scale settings
exit 1 set '$#frq $#unit $#df'

//-------------------------------------------------------------------------------------------------
funAmplitudeScale: // in: amplitudescale
// out: amplitudescale_text amplitudescale_unit
//-------------------------------------------------------------------------------------------------
// parse arguments
readvar #argv #unit';'#
// get text and unit of amplitude scale
if $(#i := keyword '$#unit' dB logarithmic power amplitude linear) < 2 #i := 0
#unit := word $#i dB dB - - -
#text := word $#i amplitude amplitude power amplitude amplitude
exit 1 set '$#text $#unit'

//
// local subroutines
//

makeWindow:
// GOSUB MAKEWINDOW windowlength windowtype -> windowvector
readvar #argv #wlen #wtyp #
#list := hanning hamming blackman kaiser bartlett taprect nuttall flattop gauss
if $(#wtyp := keyword '$#wtyp' $#list) < 0 #wtyp := 0
exit 1 eval window($#wtyp, $#wlen, 1) * 2 / $#wlen
</pre>

Programmer Guide/Macro Library/XPlot

2014-05-20T13:20:56Z

Admin:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}

{{TOC limit|3}}

==XPlot : CObjEx==

A general class for plotting multiple graphs.

====XPlot Construction====

Initialize a new XPlot-instance to display 1 or more graphs. Returns the new object or an empty string. Information and error messages are written to the <code>BSCRIPT CON</code> console.

=====Usage:=====

<code>XPlot <var>rows</var>=1 ; <var>columns</var>=1 ; <var>title</var> ; <var>profile</var> ; <var>window</var> ; <var>owner</var></code>

=====Parameters:=====

;<var>rows</var>

:The number of rows (default=<code>1</code>).

;<var>columns</var>

:The number of columns for each row (inrow0 inrow1 ...). The default is one column per row.

;<var>title</var>

:The display window title.

;<var>profile</var>

:The name of the graphics profile to use. A graphics profile is also known as a colour scheme.

;<var>window</var>

:The window position and size (in the format '<code>x y width height</code>').

;<var>owner</var>

:The id of an existing display item which should own this new window. See <code>NEW DISPLAY</code> for details.

=====Result:=====

A new <code>XPlot</code> object if successful or an empty string.

=====Examples:=====

The simplest way to create an <code>XPlot</code> instance with one graph is as follows:

<pre>
#xplot := xplot
if '$#xplot[?]' != 'instance' em -1 ; Failed to create the xplot instance
</pre>
====XPlot Member Functions====

The <code>XPLOT</code> class has the following member functions. See CObjEx Member Functions for a list of functions implemented in the parent class.

=====AddPlot=====

The <code>XPLOT</code> function <code>AddPlot</code> is identical to the <code>PLOT</code> function, except that it adds to an existing graph (in addition to or on top of the original plot). If no graph exists at the specified <var>adr</var>, then the call is passed to <code>Plot</code>. It supports the following plot types: <code>XYPLOT</code>, <code>FUNCTION</code> and <code>PARAMETER</code>. The parameters are identical to the <code>[[#Plot|PLOT]]</code> function.

===Dialog===

The function <code>Dialog</code> can be used to show and hide a dialog in the <code>XPlot</code> display.

=====Usage:=====

<code><var>inst</var> Dialog <var>cmd</var> ; <var>args</var></code>

=====Parameters:=====

;<var>cmd</var>

:See below for details.

;<var>args</var>

:See below for details.

=====Result:=====

The ID of the current or new dialog item or an empty string.

======New======

Creates a new dialog item (deleting the old one first).

=====Usage:=====

<code><var>inst</var> Dialog New</code>

======Delete======

Removes the dialog from the display and deletes the dialog item.

=====Usage:=====

<code><var>inst</var> Dialog Delete</code>

======Msg======

Posts a message to the macro message queue. The format of the message is:

<code>MENU</code> <var>dialogItem</var> <var>msgId</var> <var>msgPar</var>

Note that when the display is closed, this function is called to post the message <code>MENU dialogItem CLOSE</code> to the dialog item.

=====Usage:=====

<code><var>inst</var> Dialog Msg ; <var>pos</var> ; <var>msgid</var> <var>msgpar</var></code>

=====Parameters:=====

;<var>pos</var>

:Sets the position of the dialog within the display. The following values are supported:

:<code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code>

;<var>msgid</var>

:The message ID.

;<var>msgpar</var>

:The message parameters.

======On|Enabled======

Show the dialog and set it's position.

=====Usage:=====

<code><var>inst</var> Dialog On; <var>pos</var></code>

<code><var>inst</var> Dialog Enabled; <var>pos</var></code>

=====Parameters:=====

;<var>pos</var>

:Sets the position of the dialog within the display. The following values are supported:

:<code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code>

======Off|Hidden======

Show the dialog and set it's position.

=====Usage:=====

<code><var>inst</var> Dialog Off ; <var>pos</var></code>

<code><var>inst</var> Dialog Hidden ; <var>pos</var></code>

=====Parameters:=====

;<var>pos</var>

:Sets the position of the dialog within the display. The following values are supported:

:<code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code>

===Display===

Returns the ID of the display object associated with this <code>XPLOT</code> instance.

=====Usage:=====

<code><var>inst</var> display</code>

=====Result:=====

Returns the display object of the <code>XPLOT</code> instance.

===End===

Enters the message loop, waits until the user closes the plot display and then destroys itself.

===Get===

Retrieve an attribute from a specific graph.

=====Usage:=====

<code><var>xplot</var> Get <var>adr</var> ; <var>attribute</var></code>

=====Parameters:=====

;<var>adr</var>

:The address of the display splitter (see member function <code>Graph</code> for detail).

;<var>attribute</var>

:The id of the requested attribute. The following values are supported:

:<code>CURSORPOSITION</code> - Returns the current cursor positions in the following format: <code>i1 x1 y1 i2 x2 y2</code>

:Note that <code>x1 <= x2</code>

:<code>YDATA</code> - Returns the y data item.

:<code>XDATA</code> - Returns the x data item.

:<code>RANGE</code> - Returns the x axis and y axis range in the following format: <code>xmin xmax ymin ymax</code>

:<code>TYPE</code> - Returns the plot type (see <code>Plot</code> for a list of available plot types).

===GetFColors===

The <code>GetFColors</code> function returns a blank separated list of the function colors defined in the selected graphics profile.

=====Usage:=====

<code><var>xplot</var> GetFColors</code>

=====Result:=====

Returns a blank separated list of color keywords.

===Graph===

Returns the requested attribute <var>attr</var> of the graph identified by <var>adr</var>.

=====Usage:=====

<code><var>xplot</var> Graph <var>adr</var> [; <var>attr</var>=GRAPH ]</code>

=====Parameters:=====

;<var>adr</var>

:The id of a graph item, an <code>[[Programmer Guide/Class Library/XGraph : CObjEx|XGRAPH]]</code> instance or the '<code>row column</code>' address of a splitter in the display. Note that the <code>row</code> and <code>column</code> indices are zero-based.

;<var>attr</var>

:The attribute to returned. The following values are allowed:

:<code>INSTANCE</code> - Return the id of the <code>XGRAPH</code> instance associated with <var>adr</var>.

:<code>GRAPH</code> - Return the id of the graph object associated with <var>adr</var>. This is the default attribute.

:<code>ROW</code> - Return the row index of the splitter associated with <var>adr</var>.

:<code>COLUMN</code> - Return the column index of the splitter associated with <var>adr</var>.

=====Result:=====

Return values are selected by the argument <var>attr</var>. See the description of <var>attr</var> for details. If the address argument <var>adr</var> do not refer to a graph, <code>XGRAPH</code> or splitter of the display, an empty string is returned.

=====Examples:=====

Get the graph item id for the top left graph.

<pre>
#graph := $#xplot graph 0 0
</pre>
===Legend===

Display a graph legend. Use <code>$#xplot LEGEND $#graph</code> to clear the legend.

=====Usage:=====

<code><var>xplot</var> Legend <var>graph</var> ; <var>unit</var> ; <var>x</var> ; <var>y</var> ; <var>w</var> ; <var>h</var> ; <var>color</var> ; <var>info</var> ; <var>text1</var> ; <var>text2</var> ; <var>textX</var></code>

=====Parameters:=====

;<var>graph</var>

:The graph address (e.g. row and column index. See [[#Plot|PLOT]] for detail).

;<var>unit</var>

:The unit for size and position values. The following values are supported:

:<code>real</code> - The real x/y values.

:<code>%</code> or <code>percent</code> - The percent of the graph's plot area.

;<var>x, y</var>

:The position of the upper right corner of the first legend line.

;<var>w, h</var>

:The width and height of one legend line.

;<var>color</var>

:The legend text color.

;<var>info</var>

:This flag selects the line attributes to be displayed. The following values are supported:

:<code>color</code> - The color.

:<code>all</code> - The color, style, width and symbol.

;<var>textX</var>

:The text for the legend for function X. If no text is supplied, the legend line is removed.This parameter can be either a string, or a simple table.

=====Result:=====

void

===Plot===

The <code>XPlot</code> function <code>Plot</code> can be used to plot a function in a graph. Currently, {{STX}} supports waveform , x/y (aka function and more specifically parameter), spectrogram and waterfall plots.

======XYPLOT======

Plot an x/y function graph.

=====Usage:=====

<code><var>xplot</var> Plot <var>adr</var> ; XYPLOT ; <var>y</var> ; <var>x</var> ; <var>title</var> ; <var>xr</var> ; <var>xu</var> ; <var>xt</var> ; <var>yr</var> ; <var>yu</var> ; <var>yt</var> ; <var>fstyles</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

;<var>adr</var>

:The address of the display splitter (see the member function [[#Graph|GRAPH]] for details).

;<var>y</var>

:The y axis data (a vector or an array).

;<var>x</var>

:The data to be used for the x axis. This can be one of the following:

:A data vector with <code>y[!nrow]</code> values and 1 column.

:<code>*</code> - An asterisk. This is the default and means that the x axis uses the values <code>0</code> through to <code>y[!nrow]-1</code>.

:A blank separated list of values ('x1 x2' -> x[i] = x1+(x2-x1)/(y[!nrow]-1), i = 0..<code>y[!nrow]-1</code>).

;<var>title</var>

:The title to be displayed in this plot.

;<var>xr</var>

:The x axis display range. This can be one of the following values:

:<code>*</code> - An asterisk - an automatic scale is generated.

:<code>xmin xmax</code> - Two numerical values - the minimum and maximum values.

;<var>xu</var>

:The text describing the x axis unit (e.g. <code>seconds</code>). The default is an empty string.

:The <code>WAVEFORM</code> plot only allows the following values: <code>SAMPLES</code>|<code>MS</code>|<code>S</code>. The default is <code>S</code>.

;<var>xt</var>

:The title to be used for the x axis. The default is an empty string.

;<var>yr</var>

:The y axis display range. This can be one of the following:

:<code>*</code> - An asterisk - an automatic scale is generated.

:<code>ymin ymax</code> - Two numerical values - the minimum and maximum values.

;<var>yu</var>

:The text describing the y axis unit (e.g. <code>dB</code>).

;<var>yt</var>

:The title to be used for the y axis. The default is an empty string.

;<var>fstyles</var>

:An <code>fstyle</code> argument (see <code>fstyle</code> for details) or a zero-based function line index as specified in a color scheme (see Color Schemes in the User Guide).

;<var>xlabtab, ylabtab, zlabtab</var>

:Extended tables containing the scale, grid and label definitions. For a description of the table format, please see the scale definition table for details.

=====Result:=====

Return <code>0</code> if successful.

=====Examples:=====

Plot a simple x/y function.

<pre>
#xplot := XPLOT 1 ; 1 ; XPLOT ; Default ; 0 0 400 400
$#xplot plot 0 ; XYPLOT; $(eval fill(10, 0, 1)) ; * ; xyplot ; * ; ; x-axis ; * ; ; y-axis
</pre>
======FUNCTION======

Plot a function graph. Note that this is identical to an <code>XYPLOT</code>.

=====Usage:=====

<code><var>xplot</var> Plot <var>adr</var> ; FUNCTION ; <var>y ; x ; title ; xr ; xu ; xt ; yr ; yu ; yt ; fstyles</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

See <code>XYPLOT</code> for parameter descriptions.

=====Result:=====

Return <code>0</code> if successful.

======parameter======

Plot a parameter graph. A parameter graph differs from a function graph because a parameter plot can have missing values - it does not necessarily have values for every point on the x axis.

=====Usage:=====

<code><var>xplot</var> Plot <var>adr</var> ; parameter ; <var>y ; title ; xr ; xu ; xt ; yr ; yu ; yt ; fstyles</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

See the <code>xyplot</code> for parameter details.

=====Result:=====

Return <code>0</code> if successful.

======spectrogram======

Plot a spectrogram graph.

=====Usage:=====

<code><var>xplot</var> plot <var>adr</var> ; spectrogram ; <var>d</var> ; <var>y</var> ; <var>title</var> ; <var>xr</var> ; <var>xu</var> ; <var>xt</var> ; <var>yr</var> ; <var>yu</var> ; <var>yt</var> ; <var>zr</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

;<var>d</var>

:A data array containing one spectrum or function line per <var>y</var> row. Note that this parameter is specific to the <code>SPECTROGRAM</code> and <code>WATERFALL</code> plots.

;<var>y</var>

:The y-scale data (frequency). This can be one of the following:

:1) <code>vData</code> - A data vector with <code>y[!ncol]</code> values and 1 column.

:2) * - An asterisk: <code>y[i] = i</code>, <code>i = 0..d[!ncol]-1</code>. This is the default.

:3) <code>y1 y2</code> - Two blank separated values: <code>y[i] = y1+i*(y2-y1)/(d[!ncol]-1)</code>, <code>i = 0..d[!ncol]-1</code>.

;<var>zr</var>

:The z scale is a color scale. The following values are supported:

:<code>*</code> - An asterisk. The range is automatically generated.

:<code>zmin zmax</code> - Two numerical values specifying the minimum and maximum z axis values.

:<code>zdown</code> - A numerical value. The maximum z value is chosen automatically and the minimum value is calculated as follows: <code>zmax-zdown</code>.

For all other parameters, see <code>xyplot</code> for descriptions.

======WATERFALL======

Plot a waterfall graph.

=====Usage:=====

<code><var>xplot</var> PLOT <var>adr</var> ; WATERFALL ; <var>d</var> ; <var>x</var> ; <var>title</var> ; <var>xr</var> ; <var>xu</var> ; <var>xt</var> ; <var>yr</var> ; <var>yu</var> ; <var>yt</var> ; <var>zr</var> ; <var>zu</var> ; <var>zt</var> ; <var>xw</var> ; <var>yw</var> ; <var>n</var> ; <var>xlabtab</var> ; <var>ylabtab</var> ; <var>zlabtab</var></code>

=====Parameters:=====

;<var>d</var>

:The data array (one spectrum or function-line / row).

;<var>zr</var>

:The z axis display range. The following values are supported:

:<code>*</code> - An asterisk. The range is automatically generated.

:<code>zmin zmax</code> - Two numerical values specifying the minimum and maximum z axis values.

;<var>zu</var>

:The text describing the z axis unit (e.g. <code>s</code>).

;<var>zt</var>

:The title to be used for the z axis. The default is an empty string.

;<var>xw</var>

:The relative width of the x scale. A value between <code>-1</code> and <code>1</code>. The default is <code>0.8</code>.

;<var>yw</var>

:The relative width of the y scale. A value between <code>-1</code> and <code>1</code>. The default is <code>0.8</code>.

;<var>n</var>

:The number of lines to be plotted. The default is <code>150</code>.

For all other parameters, see <code>XYPLOT</code> for descriptions.

======WAVEFORM======

Plot a waveform graph. Note that the displayed wave item is automatically attached to the graph. This means, no explicit call to <code>SetWave</code> is necessary.

=====Usage:=====

<code><var>xplot</var> PLOT <var>adr</var> ; WAVEFORM ; <var>wave</var> ; <var>title</var> ; <var>xu</var> ; <var>xt</var> ; <var>ymax</var> ; <var>yr</var> ; <var>yt</var> ; <var>fill</var></code>

=====Parameters:=====

;<var>wave</var>

:A wave item id or an <code>XWAVE</code> instance

;<var>xu</var>

:The unit to use on the x axis. The following values: <code>SAMPLES</code>|<code>MS</code>|<code>S</code>. The default is <code>S</code>.

;<var>ymax</var>

:The maximum waveform amplitude. This can be a value between 0 and ...

;<var>yr</var>

:The y axis display range. This can be any positive number. The default is <code>1</code>.

;<var>fill</var>

:<code>1</code> if the waveform envelope should be filled or <code>0</code>.

For all other parameters, see <code>XYPLOT</code> for descriptions.

======TEXTBOX======

Plot a graph containing text.

=====Usage:=====

<code><var>xplot</var> PLOT <var>adr</var> ; TEXTBOX ; <var>title</var> ; <var>color</var> ; <var>halign</var> ; <var>valign</var> ; <var>text</var></code>

=====Parameters:=====

;<var>title</var>

:The graph title.

;<var>color</var>

:The text color. This can be an of the {{STX}} color arguments.

;<var>halign</var>

:The horizontal text alignment. This can be one of the following values: <code>CENTER</code>|<code>LEFT</code>|<code>RIGHT</code>

;<var>valign</var>

:The vertical text alignment. This can be one of the following values: <code>CENTER</code>|<code>TOP</code>|<code>BOTTOM</code>

;<var>text</var>

:The text to be displayed. This can be a simple table with an entry per line of text or a semi-colon separated list of text lines.

For all other parameters, see <code>XYPLOT</code> for descriptions.

======fstyle======

The <var>fstyle</var> argument passed to the <code>XPlot</code> functions <code>Plot</code> and <code>AddPlot</code> has the following syntax and components:

<code><var>linestyle</var><code>:</code><var>linecol</var><code>:</code><var>printcol</var><code>:</code><var>linewidth</var><code>:</code><var>drawstyle</var><code>:</code><var>drawsym</var><code>:</code><var>ymiss</var></code>

;<var>linestyle</var>

:Determines whether the function line is solid (<code>SOLID</code>), dotted (<code>DOT</code>) or dashed (<code>DASH</code>). The default value is taken from the <code>XPLOT</code> color profile.

;<var>linecol</var>

:The colour to use for the function line on screen. This can be any {{STX}} colour keyword or RGB value. The default value is taken from the <code>XPLOT</code> color profile.

;<var>printcol</var>

:The colour to use for the function line when printing. See <var>linecol</var> for details. The default value is taken from the <code>XPLOT</code> color profile.

;<var>linewidth</var>

:The width of the function line. Possible values are <code>0</code> through to <code>4</code> for lines with the <code>SOLID</code> <var>linestyle</var> and <code>0</code> or <code>1</code> for lines with the <code>DOT</code> or <code>DASH</code> <var>linestyle</var>. The default value is taken from the <code>XPLOT</code> color profile.

;<var>drawstyle</var>

:The style to use to draw the function. Each function point can be plotted separately (<code>POINTS</code>), a line can be drawn between each function point (<code>LINES</code>), the area below the function can be filled with the <var>linecol</var> (<code>AREA</code>), the function points can be joined by steps (<code>STEPS</code> - note that this is only available for the <code>PARAMETER</code> plot) or no points are plotted (<code>NONE</code> - this is best used when a drawing symbol (<var>drawsym</var>) is defined). The default style is <code>LINES</code>.

;<var>drawsym</var>

:The symbol to draw at each point. This can be used in conjunction with a drawing style (see <var>drawstyle</var>). The following keywords are supported:

:<code>NONE</code>|<code>SQUARE</code>|<code>TRIANGLE|CIRCLE|CROSS|DIAMOND</code>

:The default style is <code>NONE</code>.

;<var>ymiss</var>

:The value to use for missing y values. If <var>ymiss</var> is not specified (empty) all values are displayed, otherwise all points where <code>y=</code><var>ymiss</var> are not displayed. If <var>ymiss</var> is not empty and is not a number then <var>ymiss</var> is set to <code>0</code>. If no <var>ymiss</var> is defined, no <var>ymiss</var> is used (this is the default).

===Redraw===

Redraw the selected graph. This is currently only implemented for the <code>FUNCTION</code> (<code>XYPLOT</code>) and <code>PARAMETER</code> plots.

=====Usage:=====

<code><var>xplot</var> REDRAW <var>adr</var></code>

=====Parameters:=====

;<var>adr</var>

:The address of the display splitter (see member function <code>Graph</code> for details).

=====Result:=====

Return 0 if successful.

===ScaleOctave===

Generate a logarithmic scale table for use with the <code>Plot</code> or <code>AddPlot</code> functions. This function can also be called statically.

=====Usage:=====

<code><var>xplot</var> ScaleOctave <var>df</var> <var>count</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code>xplot ScaleOctave <var>df</var> <var>count</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code><var>xplot</var> ScaleOctave <var>vector</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code>xplot ScaleOctave <var>vector</var> ; <var>fmax</var> ; <var>fmin</var></code>

=====Parameters:=====

;<var>df</var>

:The frequency resolution in Hz.

;<var>count</var>

:The number of frequency points.

;<var>fmax</var>

:The maximum frequency to be displayed.

;<var>fmin</var>

:The minimum frequency to be displayed.

;<var>vector</var>

:The scale range as a data vector.

=====Result:=====

The following string is returned:

<code>xmin xmax xlabTab xdata</code>

Where <code>xmin</code> and <code>xmax</code> are is the minimum and maximum of the logarithmic scale, <code>xlabTab</code> is the scale definition table which you can then pass to a <code>Plot</code> function and <code>xdata</code> is the logarithmic frequency values vector. See the scale definition table description in the Command Reference for details of the table syntax.

=====Examples:=====

Create a scale definition table for a logarithmic frequency axis with 2000 points at 10 Hz intervals and a maximum frequency of 10000 Hz.

<pre>
readstr '$(xplot scaleOctave 10 2000; 10000)' #xmin #xmax #xlab #x
</pre>
=====Notes:=====

See also ScaleSteps.

===ScaleLog10===

Generate a logarithmic scale table for use with the <code>Plot</code> or <code>AddPlot</code> functions. This function can also be called statically.

=====Usage:=====

<code><var>xplot</var> ScaleLog10 <var>df</var> <var>count</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code>xplot ScaleLog10 <var>df</var> <var>count</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code><var>xplot</var> ScaleLog10 <var>vector</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code>xplot ScaleLog10 <var>vector</var> ; <var>fmax</var> ; <var>fmin</var></code>

=====Parameters:=====

;<var>df</var>

:The frequency resolution in Hz.

;<var>count</var>

:The number of frequency points.

;<var>fmax</var>

:The maximum frequency to be displayed.

;<var>fmin</var>

:The minimum frequency to be displayed.

;<var>vector</var>

:The scale range as a data vector.

=====Result:=====

The following string is returned:

<code>xmin xmax xlabTab xdata</code>

Where <code>xmin</code> and <code>xmax</code> are is the minimum and maximum of the logarithmic scale, <code>xlabTab</code> is the scale definition table which you can then pass to a <code>Plot</code> function and <code>xdata</code> is the logarithmic frequency values vector. See the scale definition table description in the Command Reference for details of the table syntax.

=====Notes:=====

See also <code>ScaleSteps</code> and <code>ScaleOctave</code>.

===ScaleSteps===

Generate a linear scale table for use with the <code>Plot</code> or <code>AddPlot</code> functions. This function can also be called statically, e.g. '<code>xplot ScaleSteps -70 -10 ; 10 ; 5 ; 5 ; 1 ; 1</code>'.

=====Usage:=====

<code><var>inst</var> ScaleSteps <var>min</var> <var>max</var> ; <var>labelDist</var> ; <var>majorGridDist</var> ; <var>majorTickDist</var> ; <var>minorGridDist</var> ; <var>minorTickDist</var></code>

<code>xplot ScaleSteps <var>min</var> <var>max</var> ; <var>labelDist</var>; <var>majorGridDist</var>; <var>majorTickDist</var> ; <var>minorGridDist</var> ; <var>minorTickDist</var></code>

<code><var>inst</var> ScaleSteps <var>vector</var> ; <var>labelDist</var>; <var>majorGridDist</var>; <var>majorTickDist</var> ; <var>minorGridDist</var> ; <var>minorTickDist</var></code>

<code>xplot ScaleSteps <var>vector</var> ; <var>labelDist</var>; <var>majorGridDist</var>; <var>majorTickDist</var> ; <var>minorGridDist</var> ; <var>minorTickDist</var></code>

=====Parameters:=====

;<var>min, max</var>

:The scale range.

;<var>vector</var>

:The scale range as a data vector.

;<var>labelDist</var>

:The label distance in scale units.

;<var>majorGridDist</var>

:The distance of the major grid lines in scale units.

;<var>majorTickDist</var>

:The distance between major ticks in scale units.

;<var>minorGridDist</var>

:The distance of the minor grid lines in scale units.

;<var>minorTickDist</var>

:The distance between minor ticks in scale units.

=====Result:=====

The following string is returned:

<code>min max labTab</code>

Where <code>min</code> and <code>max</code> are is the computed or corrected scale range and <code>labTab</code> is the scale definition table which you can then pass to a <code>Plot</code> function. See the scale definition table description in the Command Reference for details of the table syntax.

=====Examples:=====

Calculate the linear scale, grid and labels for an amplitude axis between -70 and -10 dB with labels every 10 dB, major grid lines and ticks every 5dB and minor grid lines and ticks every dB.

<pre>
readstr '$($#xplot ScaleSteps -70 -10 ; 10 ; 5 ; 5 ; 1 ; 1)' #ymin #ymax #ylab
</pre>
=====Notes:=====

See also <code>ScaleOctave</code> and <code>ScaleLog10</code>.

===Set===

The <code>Set</code> function sets the cursor mode and text attributes.

=====Usage:=====

<code><var>xplot</var> Set [ <var>graph</var>|* ; ] <var>attr</var> <var>args</var></code>

=====Parameters:=====

;<var>xgraph</var>

:An xgraph instance on which to call the <code>Set</code> command. If no graph is specified or an asterisk, then the <code>Set</code> command is carried out on all graphs.

;<var>attr</var>

:One of the following values:

:<code>cursormode</code> - turn cursors on and off and change the way they look.

:<code>xunit</code> - the name of the x-axis unit

:<code>yunit</code> - the name of the y-axis unit

:<code>xtext</code> - the description of the x-axis

:<code>ytext</code> - the description of the y-axis

:<code>title</code> - the graph's title

;<var>args</var>

:The value of <var>args</var> depends on <var>attr</var>.

:If <var>attr</var> is <code>cursormode</code>, then <var>args</var> is as follows:

:<code>mode|* type|* line|*</code>

:Where mode is one of the following values:

:<code>on</code> - show the cursor

:<code>off</code> - hide the cursor

:Where <var>type</var> is one of the following values:

:<code>cross</code>|<code>crosshair</code>|<code>vbarcross</code>|<code>harmonic</code>

:And <code>line</code> is one of the following values:

:<code>off</code> |<code>on</code>

:If <var>attr</var> is not <code>cursormode</code>, then <var>args</var> is used as the text, unit or title.

=====Result:=====

No return value.

===SetCallback===

The callback function is called by the message handlers to process popup and context menu messages and hotkeys which are not used by <code>XPLOT</code> or <code>XGRAPH</code>. The following commands are used to call the callback function:

If called from an <code>XGRAPH</code> message handler:

<code>cbfunction xgraphinstance irow icol msgid msgpar</code>

If called from the <code>XPLOT</code> message handler:

<code>cbfunction xplotinstance * * msgid msgpar</code>

=====Usage:=====

<code><var>xplot</var> SetCallback [ <var>cbfunction</var> ]</code>

=====Parameters:=====

;<var>cbfunction</var>

:The name of the callback function or an empty string to remove a previous association.

=====Result:=====

No return value.

===SetWave===

Attach a signal to one graph or all graphs (see <var>adr</var>). If a wave item is attached to a graph, it can not be deleted before it is detached or the graph or <code>XPLOT</code> instance is deleted.

=====Usage:=====

<code><var>xplot</var> SetWave [ <var>waveitem</var> ]</code>

<code><var>xplot</var> SetWave <var>adr</var> ; [ <var>waveitem</var> ]</code>

=====Parameters:=====

;<var>adr</var>

:The address of the display splitter (see member function Graph for details). If this parameter is omitted, then the wave item is set for all graphs.

;<var>waveitem</var>

:A wave item id or an <code>[[Programmer Guide/Class Library/XWave : CObjEx|XWAVE]]</code> instance (or empty to remove attachment).

=====Result:=====

Return <code>0</code> if successful.

Note that wave items can only be attached to graphs of type <code>FUNCTION</code>, <code>XYPLOT</code>, <code>PARAMETER</code>, <code>SPECTROGRAM</code> and <code>WAVEFORM</code>.====XPlot Hotkeys====

The following hotkeys are implemented in the <code>XPLOT</code> class:

{|
|-
|C
|Turn the cursors on and off.
|-
|S
|Change to the next cursor style.
|-
|B
|Turn cursor binding on and off.
|-
|Ctrl+N
|Bind the cursor to the next function.
|-
|Ctrl+P
|Bind the cursor to the previous function.
|-
|R
|Turn the cursor rubberline on and off.
|-
|T
|Turn the title on and off.
|-
|X
|Change to the next x<nowiki>-</nowiki>scale mode.
|-
|Y
|Change to the next y<nowiki>-</nowiki>scale mode.
|-
|Z
|Change to the next z<nowiki>-</nowiki>scale mode.
|-
|Space
|Open the setup dialog.
|-
|P
|Play the attached wave (between the cursors).
|-
|Q
|Play the attached wave (the whole signal).
|-
|ESC
|Stop playback.
|-
|Ins
|Show the selected metasegment's settings in a dialog or, if no metasegment is selected, show a dialog to create a new metasegment.
|-
|Del
|Delete the selected metasegments.
|-
|Ctrl+Left Click
|Move the legend to the clicked position.
|-
|Shift+Left Click
|Create a metasegment at the clicked position (show the 'Insert Metasegment' dialog).
|}

====XPlot Examples====

=====Simple XPLOT Example=====

The following example demonstrates simple <code>[[Programmer Guide/Class Library/XPlot : CObjEx|XPLOT]]</code> usage.

<pre>
[macro xplot_example_1]
//
// create display (and graph)
//
#xplot := xplot 2 ; 1 ; xplot ; default ; 100 100 800 800
if '$#xplot[?]' != 'instance' em -1 ; xplot creation failed ($emsg)
//
// plot graphs (including data generation)
//
#nValues := 100
$#xplot Plot 0 0 ; XYPLOT ; $(eval fill($#nValues,1,1)) ; * ; Graph Title ; * ; x unit ; x title ; * ; y unit ; y title ; solid:green::1
$#xplot Plot 1 0 ; SPECTROGRAM ; $(eval rand(1,100,100)) ; * ; Graph Title ; * ; x unit ; x title ; * ; y unit ; y title ; solid:green::1
//
// clean up
//
// the clean up takes place automatically
// when the plot window is closed
exit
</pre>
=====Plot rows of a matrix using XPLOT=====

The following example demonstrates how to plot the rows of a matrix using the <code>[[Programmer Guide/Class Library/XPlot : CObjEx|XPLOT]]</code> class.

<pre>
//{{3.9 6473}{2009.01.29 16.44.04} - automatically created version information - do not change or delete this line}

[macro xplot_example_2]

//
// This row demonstrates how to plot each row of a matrix
//
// C.G. 29.1.2009
//

//
// create display (and graph)
//

#xplot := xplot 1 ; 1 ; xplot ; default ; 100 100 800 800
if '$#xplot[?]' != 'instance' em -1 ; xplot creation failed ($emsg)

//
// create a matrix and fill it with some meaningless data
//

#mat := new table * /Parameter * number:X:100
if '$#mat[?]' != table em -1 ; cannot create table ($emsg)

for #i := 0 to $#i < 10 step #i := int $#i + 1
$#mat[$#i,*] := eval fill( 100, $#i+1, $#i+1 )
end

//
// plot each row of the matrix
//

for #i := int 0 to $#i < $#mat[!nrow] step #i := int $#i + 1
#x := eval $#mat[$#i,*]
$#xplot AddPlot 0 0 ; XYPLOT ; $#x ; * ; row-by-row plot ; * ; x unit ; x title ; * ; y unit ; y title ; solid:green::1
end

exit 1 int 0
</pre>

=====Advanced XPLOT Example=====

This example not only demonstrates the use of the <code>XPLOT</code> class, but also signal processing using the <code>EVAL</code> function.

<pre>
//=================================================================================================
//
// DSP Examples
//
// last update: Nov 17, 2007 (AN)
// {{STX}} version: {{STX}} 3.8 Beta
//
// The examples in this file demonstrates how to ...
// ... use the EVAL command for signal processing
// ... use the class XWAVE to read a signal frame by frame
// ... display spectrograms, waveforms and functions in XPLOT graphs
// ... enable XPLOT to play signals
// ... use the XPLOT callback function to implement simple user controls
// ... set and get cursor attritbutes and positions of XPLOT graphs
// ... add a legend to a XPLOT graph
// ... use BUTIL MSGBOX for simple dialogs
// ... use the CON object (class BScript) to display log. messages
// ... use the CON object to save numeric tables to textfiles
// ... simulate item messages using the message queue macro MSGQUEUE
// ... implement and call local subroutines
//
//=================================================================================================

//-------------------------------------------------------------------------------------------------
//
// DSPExAvrSpectrum Create a plot containing the average spectra of all segments selected
// in the DataSet view.
//
//-------------------------------------------------------------------------------------------------
[Macro DSPExAvrSpectrum #lfrm=100ms';'#sfrm=50%';'#wtyp=hamming';'#ascale=dB';'#fscale=Hz';'#amax=1';'#aref=1';'#]
// arguments: #lfrm frame length, absolute time expression
// #sfrm frame shift, relative time expression
// #wtyp window type, {Hanning, Hamming, ...)
// #fscale spectrogram frequency scale unit (Hz, kHz, Bark, Mel, ERB)
// #amax calibration factor or CALSET to use a calibration set
// #aref reference amplitude, ignored if #amax equals CALSET

// set mode to macro name (see macro DSPExCallback)
DSPExMode := set '$#mac'

// get segments selected in the DataSet view
#segments := dspexlib getsegments

// create the result table (one spectrum per row)
#asp := new table * * num:x:$#segments[] /p

// segment analysis loop
#nok := 0 // number of computed average spectra
for #i := 0 to $#i < $#segments[] step #i := int $#i+1

// get next segment from segment list
readtab $#segments $#i #aset';'#aseg';'#ach';'#
con log process segment "set=$#aset, id=$#aseg, ch=$#ach" ($(int $#i+1) of $#segments[])

// create the wave object and initialize frame settings (mode "centered")
// usage: XWAVE setref ; segmentid ; channel ; mode ; framelength ; frameshift ; ampmax ; ampref
if $(#wave := xwave '$#aset;$#aseg;$#ach;1;$#lfrm;$#sfrm;$#amax;$#aref')[?] != instance then
butil 'msgbox msg; create wave object for segment "$#aset/$#aseg,$#ach" failed; Error!'
continue
// set / check sampling rate
else if '$#srate' == '' then
#srate := $($#wave srate)
else if $($#wave srate) != $#srate then
butil 'msgbox msg; segment "$#aset/$#aseg,$#ach" - sampling rate mismatch; Error!'
$#wave destroy // delete wave object
continue
end

// compute the average spectrum
if $(#tmp := dspexlib averagespectrum $#wave ; $#wtyp ; $#ascale)[?] != table then
butil 'msgbox msg; compute average spectrum of segment "$#aset/$#aseg,$#ach" failed; Error!'
$#wave destroy // delete wave object
continue
end

$#asp[*,$#nok] := $#tmp // save the spectrum
delete $#tmp // delete temp. buffer
#legend := '$#legend $($#wave title);' // add segment to legend string
$#wave destroy // delete wave object
#nok := int $#nok+1 // increment result vector counter

end

// exit if no results are computed
if $#nok < 1 exit

// compute frequency scale vector, unit and frequency resolution
readstr '$(dspexlib frequencyscale $#srate ; $#asp[!nrow] ; $#fscale)' #frq #funit #df

// create and configure the plot object
// usage: XPLOT rows ; cols0 cols1 .. ; windowtitle ; graphicprofile ; wx wy wwidth wheight
#plot := xplot 1; 1; Average Spectrum; Rainbow; 0 0 1024 800

// plot all spectra and display the legend
#title := format 'lfrm=%s, sfrm=%s, wtyp=%s, df=%.3fHz' '$#lfrm' '$#sfrm' '$#wtyp' $#df
readstr '$(dspexlib amplitudescale $#ascale)' #ytext #yunit
// usage: xplot PLOT row col; FUNCTION; ydata; xdata; title; xrange; xunit; xtext; yrange; yunit; yrange
$#plot plot 0; function; $#asp; $#frq; $#title; ; $#funit; frequency; ; $#yunit ; $#ytext
$#plot legend 0; %; 50; 95; 45; 5; black; color; $#legend
$#plot set cursormode on crosshair // set cursor mode and style
$#plot setcallback dspexcallback // assign callback function

// wait until plot window is closed
$#plot end // the xplot object is destroyed automatically when the window is closed

// finished - cleanup and and exit
delete $#asp $#frq $#segments // delete data items
showLogOnExit := 0 // close the bscript log-window automatically
exit

//-------------------------------------------------------------------------------------------------
//
// DSPExSpectrogram Plot a spectrogram of all segments selected in the DataSet view.
// For each segment one spectrogram window is displayed. The window
// must be closed before the next segment is analysed.
//
//-------------------------------------------------------------------------------------------------
[Macro DSPExSpectrogram #lfrm=40ms';'#sfrm=10%';'#wtyp=hamming';'#arange=50';'#fscale=Hz';'#amax=1';'#aref=1';'#]
// arguments: #lfrm frame length, absolute time expression
// #sfrm frame shift, relative time expression
// #wtyp window type, {Hanning, Hamming)
// #arange spectrogram display range in dB (max .. max-range)
// #fscale spectrogram frequency scale unit (Hz, kHz, Bark, Mel, ERB)
// #amax calibration factor or CALSET to use a calibration set
// #aref reference amplitude, ignored if #amax equals CALSET

// set mode variable to macro name (see macro DSPExCallback)
DSPExMode := set '$#mac'

// get segments selected in the DataSet view
#segments := dspexlib getsegments

// segment analysis loop
for #i := 0 to $#i < $#segments[] && '$DSPExMode' != '' step #i := int $#i+1

// get next segment from segment list
readtab $#segments $#i #aset';'#aseg';'#ach';'#

// create the wave object and initialize frame settings (mode "centered")
if $(#wave := xwave '$#aset;$#aseg;$#ach;1;$#lfrm;$#sfrm;$#amax;$#aref')[?] != instance then
butil 'msgbox msg; create wave object for segment "$#aset ; $#aseg ; $#ach" failed; Error!'
continue
end

// compute the spectrogram
if $(#asp := dspexlib spectrogram $#wave ; $#wtyp ; log)[?] != table then
butil 'msgbox msg; compute spectrogram of segment "$#aset ; $#aseg ; $#ach" failed; Error!'
$#wave destroy
continue
end

// compute frequency scale vector, unit and frequency resolution
readstr '$(dspexlib frequencyscale $($#wave srate) ; $#asp[!ncol] ; $#fscale)' #frq #funit #df

// create and configure the plot object
#plot := xplot 2; 1 1; $($#wave title) quit = c-q, next = c-n; Rainbow; 0 0 1024 800
$($#plot display) height 3 1 /apply // set height of graphs

// plot spectrogram and waveform
#title := format 'lfrm=%s, sfrm=%s, wtyp=%s, arange=%s, amax=%.1fdB, df=%.3fHz' '$#lfrm' '$#sfrm' '$#wtyp' '$#arange' $(eval max($#asp)) $#df
$#plot plot 0; spectrogram; $#asp; $#frq; $#title; $($#wave tbegin) $($#wave tend); s; time; ; $#funit; frequency; $#arange
$#plot plot 1; waveform; $#wave; ; s; time; $($#wave amax); $($#wave amax); amplitude; 1
$#plot set cursormode on crosshair // set cursor mode and style
$#plot setcallback dspexcallback // assign callback function

// assign wave object to xplot graphs (for playback)
$#plot setwave $#wave

// wait until plot window is closed
$#plot end // the xplot object is destroyed automatically when the window is closed

// cleanup
delete $#asp $#frq // delete data items
$#wave destroy // delete wave object
end

// finished - cleanup and exit
delete $#segments // delete segment table
showLogOnExit := 0 // close the bscript log-window automatically
exit

//-------------------------------------------------------------------------------------------------
//
// DSPExCallback Callback function for XPLOT.
//
// arguments:
// if called from xplotobject message handler -> 'CALLBACK xplotobject * * msgid msgpar'
// if called from xgraphobject message handler -> 'CALLBACK xgraphobject row col msgid msgpar'
//
// Note: This macro uses the shell variable DSPEXMODE to check which macro has installed the
// callback and to set return values.
//
//-------------------------------------------------------------------------------------------------
[Macro DSPExCallback #obj #row #col #msgid #msgpar]

// get xplot-object if called from a xgraph-object
if '$#obj[!class]' == xgraph #obj := $#obj get xplot

// message filter for keystroke messages

// process Control-Q (QUIT) key
if '$#msgid$#msgpar' == keyCQ then

if $(butil msgbox yesno; Quit ?; $DSPExMode) == yes then
// place the display-close message in the message queue to end the xplot message loop
msgqueue 'display $($#obj display) close'
// set mode variable to empty-string if C-Q key was pressed
DSPExMode := ''
end

// process Control-C (COPY) and Control-S (SAVE) keys
else if $(#i := keyword '$#msgid$#msgpar' keyCC keyCS) >= 0 then

// get xgraph-object displayed in row 0 (later used to retrieve data)
#obj := $#obj graph 0; instance

// select the data to be saved and the save format
#todo := butil msgbox userdefined Amp Frq+Amp Cancel;; $DSPExMode - $(word $#i 'Copy to Clipboard' 'Save to CSV-File')
if $#todo == Amp then
#table := eval $($#obj get ydata) // use eval to get a copy of y-data
else if $#todo == Frq+Amp then
if '$DSPExMode' == DSPExAvrSpectrum then
#table := eval vmcol( $($#obj get xdata) , $($#obj get ydata) ) // merge x- and y-data into one table
else
#table := eval vmcol( $($#obj get xdata) , trn($($#obj get ydata)) ) // merge x- and transposed y-data into one table
end
end

// copy / save if table exists
if $#table[?] == table then
// select target
if $#i == 0 then
#file := set clipboard // set target to "clipboard" for all copy_xxx functions
else
#file := butil filedialog save; Select Output File; ; CSV=CSV-File; TXT=Textfile // use filedialog to select the output file
end

// use the CON-object to copy/save table
if '$#file' != '' con savedata text; $#table; $#file; 0; comma; dot
delete $#table
end

// process Control-I (INFO) || Control-M (MAX-MEAN) keys
else if $(#i := keyword '$#msgid$#msgpar' keyCI keyCM) >= 0 then

// get xgraph-object displayed in row 0
#obj := $#obj graph 0;inst

// save original graph title
if '$GraphTitle' == '' GraphTitle := $#obj get title

if $#i == 0 then
// get and display cursor positions
readstr '$($#obj get cursorposition)' #i1 #x1 #y1 #i2 #x2 #y2 #
#text := format 'Index = %d .. %d, X = %g ... %g (%g), Y = %g ... %g (%g)' $#i1 $#i2 $#x1 $#x2 abs($#x1-$#x2) $#y1 $#y2 abs($#y1-$#y2)
else
// set cursor mode (on), style (crosshair), rubberline (off), bind-mode (off), bind-functionindex (0)
$#obj set cursormode on crosshair off off 0
// get x- and y-data
#x := $#obj get xdata
#y := $#obj get ydata
// find index of maximum y value
#imax := eval imax($#y[*,0])
// compute mean of x and y
#xavr := eval avr($#x)
#yavr := eval avr($#y)
// set cursor 1 to maximum and cursor 2 to mean
$#obj set cursorpos 1 $#x[$#imax] $#y[$#imax] deselect
$#obj set cursorpos 2 $#xavr $#yavr deselect
// show maximum and mean in xgraph title
#text := format 'Maximum( %g , %g ), Average( %g , %g )' $#x[$#imax] $#y[$#imax] $#xavr $#yavr
end
// show info in graph title
$#obj set title $GraphTitle -- $#text

end

// note: the return value of the callback function is not used by the xplot/xgraph message handler
exit

//-------------------------------------------------------------------------------------------------
//
// DSPExLib Implements a set of signal processing functions which can be called with
// "DSPLIBEXAMPLE functionname functionarguments". This call style is often
// used to reduce the number of macros of a script or application.
//
// Functions:
//
// DSPEXLIB GETSEGMENTS
// result: a list of all segments selected in the DataSet view stored in a simple
// table (per line: 'setReference ; segmentId ; channelIndex')
// note: this function shows an error message and terminates the caller if no segments
// are selected
//
// DSPEXLIB AVERAGESPECTRUM wave ; wtyp ; atyp
// wave prepared xwave object
// wtyp type of window function: HANNING, HAMMING, KAISER, ...
// atyp type of output spectrum: LOGARITHMIC (=DB), POWER, LINEAR (=AMPLITUDE)
// result: an averaged fft spectrum in the selected format
//
// DSPEXLIB SPECTROGRAM wave ; wtyp ; atyp
// wave prepared xwave object
// wtyp type of window function: HANNING, HAMMING, KAISER, ...
// atyp type of output spectrum: LOGARITHMIC (=DB), POWER, LINEAR (=AMPLITUDE)
// or COMPLEX
// result: a matrix of fft spectra in the selected format, one spectrum per line
//
// DSPEXLIB FREQUENCYSCALE sr ; n ; type
// sr sampling rate in Hz
// n number of spectrum bins (equally spaced in the Hz domain)
// type type of frequency scale: HZ, KHZ, BARK, MEL, ERB
// result: 'frq unit df'; frq is the frequency scale vector, unit is the frequency unit
// name and df is the frequency scale step in Hz
//
// DSPEXLIB AMPLITUDESCALE type
// type type of amplitude scale: LOGARITHMIC (=DB), POWER, LINEAR (=AMPLITUDE)
// result: 'name unit df'; name and unit of amplitude scale
//
//-------------------------------------------------------------------------------------------------
[Macro DSPExLib]

// function call dispatching
readvar #argv #fun #argv /d
goto fun$#fun noFun

noFun:
// function not implemented
// result: empty string

// show an error message and exit
con log '$#mac function "$#fun" not implemented'
exit 1 set ''

//-------------------------------------------------------------------------------------------------
funGetSegments: // in:
// out: segment_list_table
//-------------------------------------------------------------------------------------------------
// retrieve list of selected segments from the DataSet application
#segments := datasetcmd getselected segments
if '$#segments[?]' == table && '$#segments[]' > 0 exit 1 set $#segments
butil msgbox msg ; no segments selected - select and try again; Error!
if '$#segments[?]' == table delete $#segments
exit 2 set '' // terminate this and the calling macro!

//-------------------------------------------------------------------------------------------------
funAverageSpectrum: // in: xwaveobject ; windowtype ; amplitudescale
// out: averagespectrum_vector
//-------------------------------------------------------------------------------------------------
// parse arguments
readvar #argv #wave';'#wtyp';'#atyp';'#

// show init message
con log $#mac $(upper '$#fun') - initializing

// create window
#w := gosub makewindow $($#wave framelength) $#wtyp

// create result table
#spg := new table *

// compute averaged amplitude spectrum
#n := $($#wave framecount)
$#spg := eval cr2len ( fft ( $($#wave read) ?* $#w ) )
for #i := 1 to $#i < $#n step #i := int $#i+1
if $#i%10 == 0 con logext 0; $#mac $(upper '$#fun') - $#i of $#n frames processed
$#spg := eval cr2len ( fft ( $($#wave read) ?* $#w ) ) + $#spg
end
$#spg := eval $#spg / $#n

// convert to selected output spectrum type
if $(#atyp := keyword '$#atyp' dB logarithmic power amplitude linear) < 2 then
$#spg := eval lin2log($#spg , $($#wave aref), 20)
else if $#atyp == 2 then
$#spg := eval $#spg ?^ 2
end

// show end message
con logext 0; $#mac $(upper '$#fun') - finished ($#n spectra computed)

// return averaged spectrum
exit 1 set $#spg

//-------------------------------------------------------------------------------------------------
funSpectrogram: // in: xwaveobject ; windowtype ; amplitudescale
// out: spectrogram_matrix
//-------------------------------------------------------------------------------------------------
// parse arguments
readvar #argv #wave';'#wtyp';'#atyp';'#

// show init message
con log $#mac $(upper '$#fun') - initializing

// create window
#w := gosub makewindow $($#wave framelength) $#wtyp

// check selected output spectrum type
if $(#atyp := keyword '$#wtyp' dB logarithmic power amplitude linear complex) < 5 then
// compute amplitude or power spectra

// create result table (one spectrum per line)
#spg := new table * * num:x:$(int $($#wave fftlength)/2 + 1) /p
// compute amplitude spectra
#n := $($#wave framecount)
for #i := 0 to $#i < $#n step #i := int $#i+1
if $#i%10 == 0 con logext 0; $#mac $(upper '$#fun') - $#i of $#n frames processed
$#spg[$#i,*] := eval cr2len ( fft ( $($#wave read) ?* $#w ) )
end
// convert to selected output spectrum type
if $(#atyp := keyword '$#atyp' dB logarithmic power amplitude linear) < 2 then
$#spg := eval lin2log($#spg , $($#wave aref), 20)
else if $#atyp == 2 then
$#spg := eval $#spg ?^ 2
end

else
// compute complex spectra

// create result table (one spectrum per line)
#spg := new table * * num:x:$(int $($#wave fftlength) + 2) /p
// compute complex spectra
for #i := int $($#wave framecount) to $#i > 0 step #i := int $#i-1
if $#i%50 == 0 con logext 0; $#mac $(upper '$#fun') - $#i of $#n frames processed
$#spg[$#i,*] := eval fft ( $($#wave read) ?* $#w )
end

end

// show end message
con logext 0; $#mac $(upper '$#fun') - finished ($#n spectra computed)

// return spectrogram matrix
exit 1 set $#spg

//-------------------------------------------------------------------------------------------------
funFrequencyScale: // in: samplingrate ; spectrumbins ; frequencyscale
// out: frequencyscale_vector frequencyscale_unit frequency_resolution_Hz
//-------------------------------------------------------------------------------------------------
// parse arguments
readvar #argv #sr';'#n';'#unit';'#
// generate frequency scale equally spaced in Hz
#frq := new table * // dummy table to make frq-scale permanent
$#frq := eval fill($#n, 0, $(#df := eval $#sr / 2 / ($#n - 1)) )
// convert to selected scale
if $(#unit := keyword '$#unit' Hz kHz Bark Mel ERB) < 0 #unit := 0
if $(#unit := word $#unit Hz kHz Bark Mel ERB) == kHz then
$#frq := eval $#frq / 1000
else if $#unit != Hz then
$#frq := eval hz2$#unit($#frq)
end
// return scale settings
exit 1 set '$#frq $#unit $#df'

//-------------------------------------------------------------------------------------------------
funAmplitudeScale: // in: amplitudescale
// out: amplitudescale_text amplitudescale_unit
//-------------------------------------------------------------------------------------------------
// parse arguments
readvar #argv #unit';'#
// get text and unit of amplitude scale
if $(#i := keyword '$#unit' dB logarithmic power amplitude linear) < 2 #i := 0
#unit := word $#i dB dB - - -
#text := word $#i amplitude amplitude power amplitude amplitude
exit 1 set '$#text $#unit'

//
// local subroutines
//

makeWindow:
// GOSUB MAKEWINDOW windowlength windowtype -> windowvector
readvar #argv #wlen #wtyp #
#list := hanning hamming blackman kaiser bartlett taprect nuttall flattop gauss
if $(#wtyp := keyword '$#wtyp' $#list) < 0 #wtyp := 0
exit 1 eval window($#wtyp, $#wlen, 1) * 2 / $#wlen
</pre>

Programmer Guide/Macro Library/XPlot

2014-05-20T13:16:08Z

Admin:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}

{{TOC limit|3}}

==XPlot : CObjEx==

A general class for plotting multiple graphs.

====XPlot Construction====

Initialize a new XPlot-instance to display 1 or more graphs. Returns the new object or an empty string. Information and error messages are written to the <code>BSCRIPT CON</code> console.

=====Usage:=====

<code>XPlot <var>rows</var>=1 ; <var>columns</var>=1 ; <var>title</var> ; <var>profile</var> ; <var>window</var> ; <var>owner</var></code>

=====Parameters:=====

;<var>rows</var>

:The number of rows (default=<code>1</code>).

;<var>columns</var>

:The number of columns for each row (inrow0 inrow1 ...). The default is one column per row.

;<var>title</var>

:The display window title.

;<var>profile</var>

:The name of the graphics profile to use. A graphics profile is also known as a colour scheme.

;<var>window</var>

:The window position and size (in the format '<code>x y width height</code>').

;<var>owner</var>

:The id of an existing display item which should own this new window. See <code>NEW DISPLAY</code> for details.

=====Result:=====

A new <code>XPlot</code> object if successful or an empty string.

=====Examples:=====

The simplest way to create an <code>XPlot</code> instance with one graph is as follows:

<pre>
#xplot := xplot
if '$#xplot[?]' != 'instance' em -1 ; Failed to create the xplot instance
</pre>
====XPlot Member Functions====

The <code>XPLOT</code> class has the following member functions. See CObjEx Member Functions for a list of functions implemented in the parent class.

=====AddPlot=====

The <code>XPLOT</code> function <code>AddPlot</code> is identical to the <code>PLOT</code> function, except that it adds to an existing graph (in addition to or on top of the original plot). If no graph exists at the specified <var>adr</var>, then the call is passed to <code>Plot</code>.

======XYPLOT======

Add an x/y plot to an existing plot as defined by <var>adr</var>. For example, plot a function over an existing spectrogram. See [[#Plot|PLOT]] for details.

Usage:

<code><var>xplot</var> AddPlot <var>adr</var> ; XYPLOT ; <var>y</var> ; <var>x</var> ; <var>title</var> ; <var>xr</var> ; <var>xu</var> ; <var>xt</var> ; <var>yr</var> ; <var>yu</var> ; <var>yt</var> ; <var>fstyles</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

Parameters:

See [[#Plot|PLOT]] for parameter details.

Result:

Return <code>0</code> if successful.

======FUNCTION======

Add an x/y plot to an existing plot as defined by <var>adr</var>. For example, plot a function over an existing spectrogram.

=====Usage:=====

<code><var>xplot</var> AddPlot <var>adr</var> ; FUNCTION ; <var>y</var> ; <var>x</var> ; <var>title</var> ; <var>xr</var> ; <var>xu</var> ; <var>xt</var> ; <var>yr</var> ; <var>yu</var> ; <var>yt</var> ; <var>fstyles</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

See [[#Plot|PLOT]] for parameter details.

=====Result:=====

Return <code>0</code> if successful.

======PARAMETER======

Plot a parameter function in an existing graph.

=====Usage:=====

<code><var>xplot</var> AddPlot <var>adr</var> ; PARAMETER ; <var>y ; title ; xr ; xu ; xt ; yr ; yu ; yt ; fstyles</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

See the <code>XYPLOT</code> for parameter details.

=====Result:=====

Return <code>0</code> if successful.

===Dialog===

The function <code>Dialog</code> can be used to show and hide a dialog in the <code>XPlot</code> display.

=====Usage:=====

<code><var>inst</var> Dialog <var>cmd</var> ; <var>args</var></code>

=====Parameters:=====

;<var>cmd</var>

:See below for details.

;<var>args</var>

:See below for details.

=====Result:=====

The ID of the current or new dialog item or an empty string.

======New======

Creates a new dialog item (deleting the old one first).

=====Usage:=====

<code><var>inst</var> Dialog New</code>

======Delete======

Removes the dialog from the display and deletes the dialog item.

=====Usage:=====

<code><var>inst</var> Dialog Delete</code>

======Msg======

Posts a message to the macro message queue. The format of the message is:

<code>MENU</code> <var>dialogItem</var> <var>msgId</var> <var>msgPar</var>

Note that when the display is closed, this function is called to post the message <code>MENU dialogItem CLOSE</code> to the dialog item.

=====Usage:=====

<code><var>inst</var> Dialog Msg ; <var>pos</var> ; <var>msgid</var> <var>msgpar</var></code>

=====Parameters:=====

;<var>pos</var>

:Sets the position of the dialog within the display. The following values are supported:

:<code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code>

;<var>msgid</var>

:The message ID.

;<var>msgpar</var>

:The message parameters.

======On|Enabled======

Show the dialog and set it's position.

=====Usage:=====

<code><var>inst</var> Dialog On; <var>pos</var></code>

<code><var>inst</var> Dialog Enabled; <var>pos</var></code>

=====Parameters:=====

;<var>pos</var>

:Sets the position of the dialog within the display. The following values are supported:

:<code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code>

======Off|Hidden======

Show the dialog and set it's position.

=====Usage:=====

<code><var>inst</var> Dialog Off ; <var>pos</var></code>

<code><var>inst</var> Dialog Hidden ; <var>pos</var></code>

=====Parameters:=====

;<var>pos</var>

:Sets the position of the dialog within the display. The following values are supported:

:<code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code>

===Display===

Returns the ID of the display object associated with this <code>XPLOT</code> instance.

=====Usage:=====

<code><var>inst</var> display</code>

=====Result:=====

Returns the display object of the <code>XPLOT</code> instance.

===End===

Enters the message loop, waits until the user closes the plot display and then destroys itself.

===Get===

Retrieve an attribute from a specific graph.

=====Usage:=====

<code><var>xplot</var> Get <var>adr</var> ; <var>attribute</var></code>

=====Parameters:=====

;<var>adr</var>

:The address of the display splitter (see member function <code>Graph</code> for detail).

;<var>attribute</var>

:The id of the requested attribute. The following values are supported:

:<code>CURSORPOSITION</code> - Returns the current cursor positions in the following format: <code>i1 x1 y1 i2 x2 y2</code>

:Note that <code>x1 <= x2</code>

:<code>YDATA</code> - Returns the y data item.

:<code>XDATA</code> - Returns the x data item.

:<code>RANGE</code> - Returns the x axis and y axis range in the following format: <code>xmin xmax ymin ymax</code>

:<code>TYPE</code> - Returns the plot type (see <code>Plot</code> for a list of available plot types).

===GetFColors===

The <code>GetFColors</code> function returns a blank separated list of the function colors defined in the selected graphics profile.

=====Usage:=====

<code><var>xplot</var> GetFColors</code>

=====Result:=====

Returns a blank separated list of color keywords.

===Graph===

Returns the requested attribute <var>attr</var> of the graph identified by <var>adr</var>.

=====Usage:=====

<code><var>xplot</var> Graph <var>adr</var> [; <var>attr</var>=GRAPH ]</code>

=====Parameters:=====

;<var>adr</var>

:The id of a graph item, an <code>[[Programmer Guide/Class Library/XGraph : CObjEx|XGRAPH]]</code> instance or the '<code>row column</code>' address of a splitter in the display. Note that the <code>row</code> and <code>column</code> indices are zero-based.

;<var>attr</var>

:The attribute to returned. The following values are allowed:

:<code>INSTANCE</code> - Return the id of the <code>XGRAPH</code> instance associated with <var>adr</var>.

:<code>GRAPH</code> - Return the id of the graph object associated with <var>adr</var>. This is the default attribute.

:<code>ROW</code> - Return the row index of the splitter associated with <var>adr</var>.

:<code>COLUMN</code> - Return the column index of the splitter associated with <var>adr</var>.

=====Result:=====

Return values are selected by the argument <var>attr</var>. See the description of <var>attr</var> for details. If the address argument <var>adr</var> do not refer to a graph, <code>XGRAPH</code> or splitter of the display, an empty string is returned.

=====Examples:=====

Get the graph item id for the top left graph.

<pre>
#graph := $#xplot graph 0 0
</pre>
===Legend===

Display a graph legend. Use <code>$#xplot LEGEND $#graph</code> to clear the legend.

=====Usage:=====

<code><var>xplot</var> Legend <var>graph</var> ; <var>unit</var> ; <var>x</var> ; <var>y</var> ; <var>w</var> ; <var>h</var> ; <var>color</var> ; <var>info</var> ; <var>text1</var> ; <var>text2</var> ; <var>textX</var></code>

=====Parameters:=====

;<var>graph</var>

:The graph address (e.g. row and column index. See [[#Plot|PLOT]] for detail).

;<var>unit</var>

:The unit for size and position values. The following values are supported:

:<code>real</code> - The real x/y values.

:<code>%</code> or <code>percent</code> - The percent of the graph's plot area.

;<var>x, y</var>

:The position of the upper right corner of the first legend line.

;<var>w, h</var>

:The width and height of one legend line.

;<var>color</var>

:The legend text color.

;<var>info</var>

:This flag selects the line attributes to be displayed. The following values are supported:

:<code>color</code> - The color.

:<code>all</code> - The color, style, width and symbol.

;<var>textX</var>

:The text for the legend for function X. If no text is supplied, the legend line is removed.This parameter can be either a string, or a simple table.

=====Result:=====

void

===Plot===

The <code>XPlot</code> function <code>Plot</code> can be used to plot a function in a graph. Currently, {{STX}} supports waveform , x/y (aka function and more specifically parameter), spectrogram and waterfall plots.

======XYPLOT======

Plot an x/y function graph.

=====Usage:=====

<code><var>xplot</var> Plot <var>adr</var> ; XYPLOT ; <var>y</var> ; <var>x</var> ; <var>title</var> ; <var>xr</var> ; <var>xu</var> ; <var>xt</var> ; <var>yr</var> ; <var>yu</var> ; <var>yt</var> ; <var>fstyles</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

;<var>adr</var>

:The address of the display splitter (see the member function [[#Graph|GRAPH]] for details).

;<var>y</var>

:The y axis data (a vector or an array).

;<var>x</var>

:The data to be used for the x axis. This can be one of the following:

:A data vector with <code>y[!nrow]</code> values and 1 column.

:<code>*</code> - An asterisk. This is the default and means that the x axis uses the values <code>0</code> through to <code>y[!nrow]-1</code>.

:A blank separated list of values ('x1 x2' -> x[i] = x1+(x2-x1)/(y[!nrow]-1), i = 0..<code>y[!nrow]-1</code>).

;<var>title</var>

:The title to be displayed in this plot.

;<var>xr</var>

:The x axis display range. This can be one of the following values:

:<code>*</code> - An asterisk - an automatic scale is generated.

:<code>xmin xmax</code> - Two numerical values - the minimum and maximum values.

;<var>xu</var>

:The text describing the x axis unit (e.g. <code>seconds</code>). The default is an empty string.

:The <code>WAVEFORM</code> plot only allows the following values: <code>SAMPLES</code>|<code>MS</code>|<code>S</code>. The default is <code>S</code>.

;<var>xt</var>

:The title to be used for the x axis. The default is an empty string.

;<var>yr</var>

:The y axis display range. This can be one of the following:

:<code>*</code> - An asterisk - an automatic scale is generated.

:<code>ymin ymax</code> - Two numerical values - the minimum and maximum values.

;<var>yu</var>

:The text describing the y axis unit (e.g. <code>dB</code>).

;<var>yt</var>

:The title to be used for the y axis. The default is an empty string.

;<var>fstyles</var>

:An <code>fstyle</code> argument (see <code>fstyle</code> for details) or a zero-based function line index as specified in a color scheme (see Color Schemes in the User Guide).

;<var>xlabtab, ylabtab, zlabtab</var>

:Extended tables containing the scale, grid and label definitions. For a description of the table format, please see the scale definition table for details.

=====Result:=====

Return <code>0</code> if successful.

=====Examples:=====

Plot a simple x/y function.

<pre>
#xplot := XPLOT 1 ; 1 ; XPLOT ; Default ; 0 0 400 400
$#xplot plot 0 ; XYPLOT; $(eval fill(10, 0, 1)) ; * ; xyplot ; * ; ; x-axis ; * ; ; y-axis
</pre>
======FUNCTION======

Plot a function graph. Note that this is identical to an <code>XYPLOT</code>.

=====Usage:=====

<code><var>xplot</var> Plot <var>adr</var> ; FUNCTION ; <var>y ; x ; title ; xr ; xu ; xt ; yr ; yu ; yt ; fstyles</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

See <code>XYPLOT</code> for parameter descriptions.

=====Result:=====

Return <code>0</code> if successful.

======parameter======

Plot a parameter graph. A parameter graph differs from a function graph because a parameter plot can have missing values - it does not necessarily have values for every point on the x axis.

=====Usage:=====

<code><var>xplot</var> Plot <var>adr</var> ; parameter ; <var>y ; title ; xr ; xu ; xt ; yr ; yu ; yt ; fstyles</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

See the <code>xyplot</code> for parameter details.

=====Result:=====

Return <code>0</code> if successful.

======spectrogram======

Plot a spectrogram graph.

=====Usage:=====

<code><var>xplot</var> plot <var>adr</var> ; spectrogram ; <var>d</var> ; <var>y</var> ; <var>title</var> ; <var>xr</var> ; <var>xu</var> ; <var>xt</var> ; <var>yr</var> ; <var>yu</var> ; <var>yt</var> ; <var>zr</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

;<var>d</var>

:A data array containing one spectrum or function line per <var>y</var> row. Note that this parameter is specific to the <code>SPECTROGRAM</code> and <code>WATERFALL</code> plots.

;<var>y</var>

:The y-scale data (frequency). This can be one of the following:

:1) <code>vData</code> - A data vector with <code>y[!ncol]</code> values and 1 column.

:2) * - An asterisk: <code>y[i] = i</code>, <code>i = 0..d[!ncol]-1</code>. This is the default.

:3) <code>y1 y2</code> - Two blank separated values: <code>y[i] = y1+i*(y2-y1)/(d[!ncol]-1)</code>, <code>i = 0..d[!ncol]-1</code>.

;<var>zr</var>

:The z scale is a color scale. The following values are supported:

:<code>*</code> - An asterisk. The range is automatically generated.

:<code>zmin zmax</code> - Two numerical values specifying the minimum and maximum z axis values.

:<code>zdown</code> - A numerical value. The maximum z value is chosen automatically and the minimum value is calculated as follows: <code>zmax-zdown</code>.

For all other parameters, see <code>xyplot</code> for descriptions.

======WATERFALL======

Plot a waterfall graph.

=====Usage:=====

<code><var>xplot</var> PLOT <var>adr</var> ; WATERFALL ; <var>d</var> ; <var>x</var> ; <var>title</var> ; <var>xr</var> ; <var>xu</var> ; <var>xt</var> ; <var>yr</var> ; <var>yu</var> ; <var>yt</var> ; <var>zr</var> ; <var>zu</var> ; <var>zt</var> ; <var>xw</var> ; <var>yw</var> ; <var>n</var> ; <var>xlabtab</var> ; <var>ylabtab</var> ; <var>zlabtab</var></code>

=====Parameters:=====

;<var>d</var>

:The data array (one spectrum or function-line / row).

;<var>zr</var>

:The z axis display range. The following values are supported:

:<code>*</code> - An asterisk. The range is automatically generated.

:<code>zmin zmax</code> - Two numerical values specifying the minimum and maximum z axis values.

;<var>zu</var>

:The text describing the z axis unit (e.g. <code>s</code>).

;<var>zt</var>

:The title to be used for the z axis. The default is an empty string.

;<var>xw</var>

:The relative width of the x scale. A value between <code>-1</code> and <code>1</code>. The default is <code>0.8</code>.

;<var>yw</var>

:The relative width of the y scale. A value between <code>-1</code> and <code>1</code>. The default is <code>0.8</code>.

;<var>n</var>

:The number of lines to be plotted. The default is <code>150</code>.

For all other parameters, see <code>XYPLOT</code> for descriptions.

======WAVEFORM======

Plot a waveform graph. Note that the displayed wave item is automatically attached to the graph. This means, no explicit call to <code>SetWave</code> is necessary.

=====Usage:=====

<code><var>xplot</var> PLOT <var>adr</var> ; WAVEFORM ; <var>wave</var> ; <var>title</var> ; <var>xu</var> ; <var>xt</var> ; <var>ymax</var> ; <var>yr</var> ; <var>yt</var> ; <var>fill</var></code>

=====Parameters:=====

;<var>wave</var>

:A wave item id or an <code>XWAVE</code> instance

;<var>xu</var>

:The unit to use on the x axis. The following values: <code>SAMPLES</code>|<code>MS</code>|<code>S</code>. The default is <code>S</code>.

;<var>ymax</var>

:The maximum waveform amplitude. This can be a value between 0 and ...

;<var>yr</var>

:The y axis display range. This can be any positive number. The default is <code>1</code>.

;<var>fill</var>

:<code>1</code> if the waveform envelope should be filled or <code>0</code>.

For all other parameters, see <code>XYPLOT</code> for descriptions.

======TEXTBOX======

Plot a graph containing text.

=====Usage:=====

<code><var>xplot</var> PLOT <var>adr</var> ; TEXTBOX ; <var>title</var> ; <var>color</var> ; <var>halign</var> ; <var>valign</var> ; <var>text</var></code>

=====Parameters:=====

;<var>title</var>

:The graph title.

;<var>color</var>

:The text color. This can be an of the {{STX}} color arguments.

;<var>halign</var>

:The horizontal text alignment. This can be one of the following values: <code>CENTER</code>|<code>LEFT</code>|<code>RIGHT</code>

;<var>valign</var>

:The vertical text alignment. This can be one of the following values: <code>CENTER</code>|<code>TOP</code>|<code>BOTTOM</code>

;<var>text</var>

:The text to be displayed. This can be a simple table with an entry per line of text or a semi-colon separated list of text lines.

For all other parameters, see <code>XYPLOT</code> for descriptions.

======fstyle======

The <var>fstyle</var> argument passed to the <code>XPlot</code> functions <code>Plot</code> and <code>AddPlot</code> has the following syntax and components:

<code><var>linestyle</var><code>:</code><var>linecol</var><code>:</code><var>printcol</var><code>:</code><var>linewidth</var><code>:</code><var>drawstyle</var><code>:</code><var>drawsym</var><code>:</code><var>ymiss</var></code>

;<var>linestyle</var>

:Determines whether the function line is solid (<code>SOLID</code>), dotted (<code>DOT</code>) or dashed (<code>DASH</code>). The default value is taken from the <code>XPLOT</code> color profile.

;<var>linecol</var>

:The colour to use for the function line on screen. This can be any {{STX}} colour keyword or RGB value. The default value is taken from the <code>XPLOT</code> color profile.

;<var>printcol</var>

:The colour to use for the function line when printing. See <var>linecol</var> for details. The default value is taken from the <code>XPLOT</code> color profile.

;<var>linewidth</var>

:The width of the function line. Possible values are <code>0</code> through to <code>4</code> for lines with the <code>SOLID</code> <var>linestyle</var> and <code>0</code> or <code>1</code> for lines with the <code>DOT</code> or <code>DASH</code> <var>linestyle</var>. The default value is taken from the <code>XPLOT</code> color profile.

;<var>drawstyle</var>

:The style to use to draw the function. Each function point can be plotted separately (<code>POINTS</code>), a line can be drawn between each function point (<code>LINES</code>), the area below the function can be filled with the <var>linecol</var> (<code>AREA</code>), the function points can be joined by steps (<code>STEPS</code> - note that this is only available for the <code>PARAMETER</code> plot) or no points are plotted (<code>NONE</code> - this is best used when a drawing symbol (<var>drawsym</var>) is defined). The default style is <code>LINES</code>.

;<var>drawsym</var>

:The symbol to draw at each point. This can be used in conjunction with a drawing style (see <var>drawstyle</var>). The following keywords are supported:

:<code>NONE</code>|<code>SQUARE</code>|<code>TRIANGLE|CIRCLE|CROSS|DIAMOND</code>

:The default style is <code>NONE</code>.

;<var>ymiss</var>

:The value to use for missing y values. If <var>ymiss</var> is not specified (empty) all values are displayed, otherwise all points where <code>y=</code><var>ymiss</var> are not displayed. If <var>ymiss</var> is not empty and is not a number then <var>ymiss</var> is set to <code>0</code>. If no <var>ymiss</var> is defined, no <var>ymiss</var> is used (this is the default).

===Redraw===

Redraw the selected graph. This is currently only implemented for the <code>FUNCTION</code> (<code>XYPLOT</code>) and <code>PARAMETER</code> plots.

=====Usage:=====

<code><var>xplot</var> REDRAW <var>adr</var></code>

=====Parameters:=====

;<var>adr</var>

:The address of the display splitter (see member function <code>Graph</code> for details).

=====Result:=====

Return 0 if successful.

===ScaleOctave===

Generate a logarithmic scale table for use with the <code>Plot</code> or <code>AddPlot</code> functions. This function can also be called statically.

=====Usage:=====

<code><var>xplot</var> ScaleOctave <var>df</var> <var>count</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code>xplot ScaleOctave <var>df</var> <var>count</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code><var>xplot</var> ScaleOctave <var>vector</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code>xplot ScaleOctave <var>vector</var> ; <var>fmax</var> ; <var>fmin</var></code>

=====Parameters:=====

;<var>df</var>

:The frequency resolution in Hz.

;<var>count</var>

:The number of frequency points.

;<var>fmax</var>

:The maximum frequency to be displayed.

;<var>fmin</var>

:The minimum frequency to be displayed.

;<var>vector</var>

:The scale range as a data vector.

=====Result:=====

The following string is returned:

<code>xmin xmax xlabTab xdata</code>

Where <code>xmin</code> and <code>xmax</code> are is the minimum and maximum of the logarithmic scale, <code>xlabTab</code> is the scale definition table which you can then pass to a <code>Plot</code> function and <code>xdata</code> is the logarithmic frequency values vector. See the scale definition table description in the Command Reference for details of the table syntax.

=====Examples:=====

Create a scale definition table for a logarithmic frequency axis with 2000 points at 10 Hz intervals and a maximum frequency of 10000 Hz.

<pre>
readstr '$(xplot scaleOctave 10 2000; 10000)' #xmin #xmax #xlab #x
</pre>
=====Notes:=====

See also ScaleSteps.

===ScaleLog10===

Generate a logarithmic scale table for use with the <code>Plot</code> or <code>AddPlot</code> functions. This function can also be called statically.

=====Usage:=====

<code><var>xplot</var> ScaleLog10 <var>df</var> <var>count</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code>xplot ScaleLog10 <var>df</var> <var>count</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code><var>xplot</var> ScaleLog10 <var>vector</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code>xplot ScaleLog10 <var>vector</var> ; <var>fmax</var> ; <var>fmin</var></code>

=====Parameters:=====

;<var>df</var>

:The frequency resolution in Hz.

;<var>count</var>

:The number of frequency points.

;<var>fmax</var>

:The maximum frequency to be displayed.

;<var>fmin</var>

:The minimum frequency to be displayed.

;<var>vector</var>

:The scale range as a data vector.

=====Result:=====

The following string is returned:

<code>xmin xmax xlabTab xdata</code>

Where <code>xmin</code> and <code>xmax</code> are is the minimum and maximum of the logarithmic scale, <code>xlabTab</code> is the scale definition table which you can then pass to a <code>Plot</code> function and <code>xdata</code> is the logarithmic frequency values vector. See the scale definition table description in the Command Reference for details of the table syntax.

=====Notes:=====

See also <code>ScaleSteps</code> and <code>ScaleOctave</code>.

===ScaleSteps===

Generate a linear scale table for use with the <code>Plot</code> or <code>AddPlot</code> functions. This function can also be called statically, e.g. '<code>xplot ScaleSteps -70 -10 ; 10 ; 5 ; 5 ; 1 ; 1</code>'.

=====Usage:=====

<code><var>inst</var> ScaleSteps <var>min</var> <var>max</var> ; <var>labelDist</var> ; <var>majorGridDist</var> ; <var>majorTickDist</var> ; <var>minorGridDist</var> ; <var>minorTickDist</var></code>

<code>xplot ScaleSteps <var>min</var> <var>max</var> ; <var>labelDist</var>; <var>majorGridDist</var>; <var>majorTickDist</var> ; <var>minorGridDist</var> ; <var>minorTickDist</var></code>

<code><var>inst</var> ScaleSteps <var>vector</var> ; <var>labelDist</var>; <var>majorGridDist</var>; <var>majorTickDist</var> ; <var>minorGridDist</var> ; <var>minorTickDist</var></code>

<code>xplot ScaleSteps <var>vector</var> ; <var>labelDist</var>; <var>majorGridDist</var>; <var>majorTickDist</var> ; <var>minorGridDist</var> ; <var>minorTickDist</var></code>

=====Parameters:=====

;<var>min, max</var>

:The scale range.

;<var>vector</var>

:The scale range as a data vector.

;<var>labelDist</var>

:The label distance in scale units.

;<var>majorGridDist</var>

:The distance of the major grid lines in scale units.

;<var>majorTickDist</var>

:The distance between major ticks in scale units.

;<var>minorGridDist</var>

:The distance of the minor grid lines in scale units.

;<var>minorTickDist</var>

:The distance between minor ticks in scale units.

=====Result:=====

The following string is returned:

<code>min max labTab</code>

Where <code>min</code> and <code>max</code> are is the computed or corrected scale range and <code>labTab</code> is the scale definition table which you can then pass to a <code>Plot</code> function. See the scale definition table description in the Command Reference for details of the table syntax.

=====Examples:=====

Calculate the linear scale, grid and labels for an amplitude axis between -70 and -10 dB with labels every 10 dB, major grid lines and ticks every 5dB and minor grid lines and ticks every dB.

<pre>
readstr '$($#xplot ScaleSteps -70 -10 ; 10 ; 5 ; 5 ; 1 ; 1)' #ymin #ymax #ylab
</pre>
=====Notes:=====

See also <code>ScaleOctave</code> and <code>ScaleLog10</code>.

===Set===

The <code>Set</code> function sets the cursor mode and text attributes.

=====Usage:=====

<code><var>xplot</var> Set [ <var>graph</var>|* ; ] <var>attr</var> <var>args</var></code>

=====Parameters:=====

;<var>xgraph</var>

:An xgraph instance on which to call the <code>Set</code> command. If no graph is specified or an asterisk, then the <code>Set</code> command is carried out on all graphs.

;<var>attr</var>

:One of the following values:

:<code>cursormode</code> - turn cursors on and off and change the way they look.

:<code>xunit</code> - the name of the x-axis unit

:<code>yunit</code> - the name of the y-axis unit

:<code>xtext</code> - the description of the x-axis

:<code>ytext</code> - the description of the y-axis

:<code>title</code> - the graph's title

;<var>args</var>

:The value of <var>args</var> depends on <var>attr</var>.

:If <var>attr</var> is <code>cursormode</code>, then <var>args</var> is as follows:

:<code>mode|* type|* line|*</code>

:Where mode is one of the following values:

:<code>on</code> - show the cursor

:<code>off</code> - hide the cursor

:Where <var>type</var> is one of the following values:

:<code>cross</code>|<code>crosshair</code>|<code>vbarcross</code>|<code>harmonic</code>

:And <code>line</code> is one of the following values:

:<code>off</code> |<code>on</code>

:If <var>attr</var> is not <code>cursormode</code>, then <var>args</var> is used as the text, unit or title.

=====Result:=====

No return value.

===SetCallback===

The callback function is called by the message handlers to process popup and context menu messages and hotkeys which are not used by <code>XPLOT</code> or <code>XGRAPH</code>. The following commands are used to call the callback function:

If called from an <code>XGRAPH</code> message handler:

<code>cbfunction xgraphinstance irow icol msgid msgpar</code>

If called from the <code>XPLOT</code> message handler:

<code>cbfunction xplotinstance * * msgid msgpar</code>

=====Usage:=====

<code><var>xplot</var> SetCallback [ <var>cbfunction</var> ]</code>

=====Parameters:=====

;<var>cbfunction</var>

:The name of the callback function or an empty string to remove a previous association.

=====Result:=====

No return value.

===SetWave===

Attach a signal to one graph or all graphs (see <var>adr</var>). If a wave item is attached to a graph, it can not be deleted before it is detached or the graph or <code>XPLOT</code> instance is deleted.

=====Usage:=====

<code><var>xplot</var> SetWave [ <var>waveitem</var> ]</code>

<code><var>xplot</var> SetWave <var>adr</var> ; [ <var>waveitem</var> ]</code>

=====Parameters:=====

;<var>adr</var>

:The address of the display splitter (see member function Graph for details). If this parameter is omitted, then the wave item is set for all graphs.

;<var>waveitem</var>

:A wave item id or an <code>[[Programmer Guide/Class Library/XWave : CObjEx|XWAVE]]</code> instance (or empty to remove attachment).

=====Result:=====

Return <code>0</code> if successful.

Note that wave items can only be attached to graphs of type <code>FUNCTION</code>, <code>XYPLOT</code>, <code>PARAMETER</code>, <code>SPECTROGRAM</code> and <code>WAVEFORM</code>.====XPlot Hotkeys====

The following hotkeys are implemented in the <code>XPLOT</code> class:

{|
|-
|C
|Turn the cursors on and off.
|-
|S
|Change to the next cursor style.
|-
|B
|Turn cursor binding on and off.
|-
|Ctrl+N
|Bind the cursor to the next function.
|-
|Ctrl+P
|Bind the cursor to the previous function.
|-
|R
|Turn the cursor rubberline on and off.
|-
|T
|Turn the title on and off.
|-
|X
|Change to the next x<nowiki>-</nowiki>scale mode.
|-
|Y
|Change to the next y<nowiki>-</nowiki>scale mode.
|-
|Z
|Change to the next z<nowiki>-</nowiki>scale mode.
|-
|Space
|Open the setup dialog.
|-
|P
|Play the attached wave (between the cursors).
|-
|Q
|Play the attached wave (the whole signal).
|-
|ESC
|Stop playback.
|-
|Ins
|Show the selected metasegment's settings in a dialog or, if no metasegment is selected, show a dialog to create a new metasegment.
|-
|Del
|Delete the selected metasegments.
|-
|Ctrl+Left Click
|Move the legend to the clicked position.
|-
|Shift+Left Click
|Create a metasegment at the clicked position (show the 'Insert Metasegment' dialog).
|}

====XPlot Examples====

=====Simple XPLOT Example=====

The following example demonstrates simple <code>[[Programmer Guide/Class Library/XPlot : CObjEx|XPLOT]]</code> usage.

<pre>
[macro xplot_example_1]
//
// create display (and graph)
//
#xplot := xplot 2 ; 1 ; xplot ; default ; 100 100 800 800
if '$#xplot[?]' != 'instance' em -1 ; xplot creation failed ($emsg)
//
// plot graphs (including data generation)
//
#nValues := 100
$#xplot Plot 0 0 ; XYPLOT ; $(eval fill($#nValues,1,1)) ; * ; Graph Title ; * ; x unit ; x title ; * ; y unit ; y title ; solid:green::1
$#xplot Plot 1 0 ; SPECTROGRAM ; $(eval rand(1,100,100)) ; * ; Graph Title ; * ; x unit ; x title ; * ; y unit ; y title ; solid:green::1
//
// clean up
//
// the clean up takes place automatically
// when the plot window is closed
exit
</pre>
=====Plot rows of a matrix using XPLOT=====

The following example demonstrates how to plot the rows of a matrix using the <code>[[Programmer Guide/Class Library/XPlot : CObjEx|XPLOT]]</code> class.

<pre>
//{{3.9 6473}{2009.01.29 16.44.04} - automatically created version information - do not change or delete this line}

[macro xplot_example_2]

//
// This row demonstrates how to plot each row of a matrix
//
// C.G. 29.1.2009
//

//
// create display (and graph)
//

#xplot := xplot 1 ; 1 ; xplot ; default ; 100 100 800 800
if '$#xplot[?]' != 'instance' em -1 ; xplot creation failed ($emsg)

//
// create a matrix and fill it with some meaningless data
//

#mat := new table * /Parameter * number:X:100
if '$#mat[?]' != table em -1 ; cannot create table ($emsg)

for #i := 0 to $#i < 10 step #i := int $#i + 1
$#mat[$#i,*] := eval fill( 100, $#i+1, $#i+1 )
end

//
// plot each row of the matrix
//

for #i := int 0 to $#i < $#mat[!nrow] step #i := int $#i + 1
#x := eval $#mat[$#i,*]
$#xplot AddPlot 0 0 ; XYPLOT ; $#x ; * ; row-by-row plot ; * ; x unit ; x title ; * ; y unit ; y title ; solid:green::1
end

exit 1 int 0
</pre>

=====Advanced XPLOT Example=====

This example not only demonstrates the use of the <code>XPLOT</code> class, but also signal processing using the <code>EVAL</code> function.

<pre>
//=================================================================================================
//
// DSP Examples
//
// last update: Nov 17, 2007 (AN)
// {{STX}} version: {{STX}} 3.8 Beta
//
// The examples in this file demonstrates how to ...
// ... use the EVAL command for signal processing
// ... use the class XWAVE to read a signal frame by frame
// ... display spectrograms, waveforms and functions in XPLOT graphs
// ... enable XPLOT to play signals
// ... use the XPLOT callback function to implement simple user controls
// ... set and get cursor attritbutes and positions of XPLOT graphs
// ... add a legend to a XPLOT graph
// ... use BUTIL MSGBOX for simple dialogs
// ... use the CON object (class BScript) to display log. messages
// ... use the CON object to save numeric tables to textfiles
// ... simulate item messages using the message queue macro MSGQUEUE
// ... implement and call local subroutines
//
//=================================================================================================

//-------------------------------------------------------------------------------------------------
//
// DSPExAvrSpectrum Create a plot containing the average spectra of all segments selected
// in the DataSet view.
//
//-------------------------------------------------------------------------------------------------
[Macro DSPExAvrSpectrum #lfrm=100ms';'#sfrm=50%';'#wtyp=hamming';'#ascale=dB';'#fscale=Hz';'#amax=1';'#aref=1';'#]
// arguments: #lfrm frame length, absolute time expression
// #sfrm frame shift, relative time expression
// #wtyp window type, {Hanning, Hamming, ...)
// #fscale spectrogram frequency scale unit (Hz, kHz, Bark, Mel, ERB)
// #amax calibration factor or CALSET to use a calibration set
// #aref reference amplitude, ignored if #amax equals CALSET

// set mode to macro name (see macro DSPExCallback)
DSPExMode := set '$#mac'

// get segments selected in the DataSet view
#segments := dspexlib getsegments

// create the result table (one spectrum per row)
#asp := new table * * num:x:$#segments[] /p

// segment analysis loop
#nok := 0 // number of computed average spectra
for #i := 0 to $#i < $#segments[] step #i := int $#i+1

// get next segment from segment list
readtab $#segments $#i #aset';'#aseg';'#ach';'#
con log process segment "set=$#aset, id=$#aseg, ch=$#ach" ($(int $#i+1) of $#segments[])

// create the wave object and initialize frame settings (mode "centered")
// usage: XWAVE setref ; segmentid ; channel ; mode ; framelength ; frameshift ; ampmax ; ampref
if $(#wave := xwave '$#aset;$#aseg;$#ach;1;$#lfrm;$#sfrm;$#amax;$#aref')[?] != instance then
butil 'msgbox msg; create wave object for segment "$#aset/$#aseg,$#ach" failed; Error!'
continue
// set / check sampling rate
else if '$#srate' == '' then
#srate := $($#wave srate)
else if $($#wave srate) != $#srate then
butil 'msgbox msg; segment "$#aset/$#aseg,$#ach" - sampling rate mismatch; Error!'
$#wave destroy // delete wave object
continue
end

// compute the average spectrum
if $(#tmp := dspexlib averagespectrum $#wave ; $#wtyp ; $#ascale)[?] != table then
butil 'msgbox msg; compute average spectrum of segment "$#aset/$#aseg,$#ach" failed; Error!'
$#wave destroy // delete wave object
continue
end

$#asp[*,$#nok] := $#tmp // save the spectrum
delete $#tmp // delete temp. buffer
#legend := '$#legend $($#wave title);' // add segment to legend string
$#wave destroy // delete wave object
#nok := int $#nok+1 // increment result vector counter

end

// exit if no results are computed
if $#nok < 1 exit

// compute frequency scale vector, unit and frequency resolution
readstr '$(dspexlib frequencyscale $#srate ; $#asp[!nrow] ; $#fscale)' #frq #funit #df

// create and configure the plot object
// usage: XPLOT rows ; cols0 cols1 .. ; windowtitle ; graphicprofile ; wx wy wwidth wheight
#plot := xplot 1; 1; Average Spectrum; Rainbow; 0 0 1024 800

// plot all spectra and display the legend
#title := format 'lfrm=%s, sfrm=%s, wtyp=%s, df=%.3fHz' '$#lfrm' '$#sfrm' '$#wtyp' $#df
readstr '$(dspexlib amplitudescale $#ascale)' #ytext #yunit
// usage: xplot PLOT row col; FUNCTION; ydata; xdata; title; xrange; xunit; xtext; yrange; yunit; yrange
$#plot plot 0; function; $#asp; $#frq; $#title; ; $#funit; frequency; ; $#yunit ; $#ytext
$#plot legend 0; %; 50; 95; 45; 5; black; color; $#legend
$#plot set cursormode on crosshair // set cursor mode and style
$#plot setcallback dspexcallback // assign callback function

// wait until plot window is closed
$#plot end // the xplot object is destroyed automatically when the window is closed

// finished - cleanup and and exit
delete $#asp $#frq $#segments // delete data items
showLogOnExit := 0 // close the bscript log-window automatically
exit

//-------------------------------------------------------------------------------------------------
//
// DSPExSpectrogram Plot a spectrogram of all segments selected in the DataSet view.
// For each segment one spectrogram window is displayed. The window
// must be closed before the next segment is analysed.
//
//-------------------------------------------------------------------------------------------------
[Macro DSPExSpectrogram #lfrm=40ms';'#sfrm=10%';'#wtyp=hamming';'#arange=50';'#fscale=Hz';'#amax=1';'#aref=1';'#]
// arguments: #lfrm frame length, absolute time expression
// #sfrm frame shift, relative time expression
// #wtyp window type, {Hanning, Hamming)
// #arange spectrogram display range in dB (max .. max-range)
// #fscale spectrogram frequency scale unit (Hz, kHz, Bark, Mel, ERB)
// #amax calibration factor or CALSET to use a calibration set
// #aref reference amplitude, ignored if #amax equals CALSET

// set mode variable to macro name (see macro DSPExCallback)
DSPExMode := set '$#mac'

// get segments selected in the DataSet view
#segments := dspexlib getsegments

// segment analysis loop
for #i := 0 to $#i < $#segments[] && '$DSPExMode' != '' step #i := int $#i+1

// get next segment from segment list
readtab $#segments $#i #aset';'#aseg';'#ach';'#

// create the wave object and initialize frame settings (mode "centered")
if $(#wave := xwave '$#aset;$#aseg;$#ach;1;$#lfrm;$#sfrm;$#amax;$#aref')[?] != instance then
butil 'msgbox msg; create wave object for segment "$#aset ; $#aseg ; $#ach" failed; Error!'
continue
end

// compute the spectrogram
if $(#asp := dspexlib spectrogram $#wave ; $#wtyp ; log)[?] != table then
butil 'msgbox msg; compute spectrogram of segment "$#aset ; $#aseg ; $#ach" failed; Error!'
$#wave destroy
continue
end

// compute frequency scale vector, unit and frequency resolution
readstr '$(dspexlib frequencyscale $($#wave srate) ; $#asp[!ncol] ; $#fscale)' #frq #funit #df

// create and configure the plot object
#plot := xplot 2; 1 1; $($#wave title) quit = c-q, next = c-n; Rainbow; 0 0 1024 800
$($#plot display) height 3 1 /apply // set height of graphs

// plot spectrogram and waveform
#title := format 'lfrm=%s, sfrm=%s, wtyp=%s, arange=%s, amax=%.1fdB, df=%.3fHz' '$#lfrm' '$#sfrm' '$#wtyp' '$#arange' $(eval max($#asp)) $#df
$#plot plot 0; spectrogram; $#asp; $#frq; $#title; $($#wave tbegin) $($#wave tend); s; time; ; $#funit; frequency; $#arange
$#plot plot 1; waveform; $#wave; ; s; time; $($#wave amax); $($#wave amax); amplitude; 1
$#plot set cursormode on crosshair // set cursor mode and style
$#plot setcallback dspexcallback // assign callback function

// assign wave object to xplot graphs (for playback)
$#plot setwave $#wave

// wait until plot window is closed
$#plot end // the xplot object is destroyed automatically when the window is closed

// cleanup
delete $#asp $#frq // delete data items
$#wave destroy // delete wave object
end

// finished - cleanup and exit
delete $#segments // delete segment table
showLogOnExit := 0 // close the bscript log-window automatically
exit

//-------------------------------------------------------------------------------------------------
//
// DSPExCallback Callback function for XPLOT.
//
// arguments:
// if called from xplotobject message handler -> 'CALLBACK xplotobject * * msgid msgpar'
// if called from xgraphobject message handler -> 'CALLBACK xgraphobject row col msgid msgpar'
//
// Note: This macro uses the shell variable DSPEXMODE to check which macro has installed the
// callback and to set return values.
//
//-------------------------------------------------------------------------------------------------
[Macro DSPExCallback #obj #row #col #msgid #msgpar]

// get xplot-object if called from a xgraph-object
if '$#obj[!class]' == xgraph #obj := $#obj get xplot

// message filter for keystroke messages

// process Control-Q (QUIT) key
if '$#msgid$#msgpar' == keyCQ then

if $(butil msgbox yesno; Quit ?; $DSPExMode) == yes then
// place the display-close message in the message queue to end the xplot message loop
msgqueue 'display $($#obj display) close'
// set mode variable to empty-string if C-Q key was pressed
DSPExMode := ''
end

// process Control-C (COPY) and Control-S (SAVE) keys
else if $(#i := keyword '$#msgid$#msgpar' keyCC keyCS) >= 0 then

// get xgraph-object displayed in row 0 (later used to retrieve data)
#obj := $#obj graph 0; instance

// select the data to be saved and the save format
#todo := butil msgbox userdefined Amp Frq+Amp Cancel;; $DSPExMode - $(word $#i 'Copy to Clipboard' 'Save to CSV-File')
if $#todo == Amp then
#table := eval $($#obj get ydata) // use eval to get a copy of y-data
else if $#todo == Frq+Amp then
if '$DSPExMode' == DSPExAvrSpectrum then
#table := eval vmcol( $($#obj get xdata) , $($#obj get ydata) ) // merge x- and y-data into one table
else
#table := eval vmcol( $($#obj get xdata) , trn($($#obj get ydata)) ) // merge x- and transposed y-data into one table
end
end

// copy / save if table exists
if $#table[?] == table then
// select target
if $#i == 0 then
#file := set clipboard // set target to "clipboard" for all copy_xxx functions
else
#file := butil filedialog save; Select Output File; ; CSV=CSV-File; TXT=Textfile // use filedialog to select the output file
end

// use the CON-object to copy/save table
if '$#file' != '' con savedata text; $#table; $#file; 0; comma; dot
delete $#table
end

// process Control-I (INFO) || Control-M (MAX-MEAN) keys
else if $(#i := keyword '$#msgid$#msgpar' keyCI keyCM) >= 0 then

// get xgraph-object displayed in row 0
#obj := $#obj graph 0;inst

// save original graph title
if '$GraphTitle' == '' GraphTitle := $#obj get title

if $#i == 0 then
// get and display cursor positions
readstr '$($#obj get cursorposition)' #i1 #x1 #y1 #i2 #x2 #y2 #
#text := format 'Index = %d .. %d, X = %g ... %g (%g), Y = %g ... %g (%g)' $#i1 $#i2 $#x1 $#x2 abs($#x1-$#x2) $#y1 $#y2 abs($#y1-$#y2)
else
// set cursor mode (on), style (crosshair), rubberline (off), bind-mode (off), bind-functionindex (0)
$#obj set cursormode on crosshair off off 0
// get x- and y-data
#x := $#obj get xdata
#y := $#obj get ydata
// find index of maximum y value
#imax := eval imax($#y[*,0])
// compute mean of x and y
#xavr := eval avr($#x)
#yavr := eval avr($#y)
// set cursor 1 to maximum and cursor 2 to mean
$#obj set cursorpos 1 $#x[$#imax] $#y[$#imax] deselect
$#obj set cursorpos 2 $#xavr $#yavr deselect
// show maximum and mean in xgraph title
#text := format 'Maximum( %g , %g ), Average( %g , %g )' $#x[$#imax] $#y[$#imax] $#xavr $#yavr
end
// show info in graph title
$#obj set title $GraphTitle -- $#text

end

// note: the return value of the callback function is not used by the xplot/xgraph message handler
exit

//-------------------------------------------------------------------------------------------------
//
// DSPExLib Implements a set of signal processing functions which can be called with
// "DSPLIBEXAMPLE functionname functionarguments". This call style is often
// used to reduce the number of macros of a script or application.
//
// Functions:
//
// DSPEXLIB GETSEGMENTS
// result: a list of all segments selected in the DataSet view stored in a simple
// table (per line: 'setReference ; segmentId ; channelIndex')
// note: this function shows an error message and terminates the caller if no segments
// are selected
//
// DSPEXLIB AVERAGESPECTRUM wave ; wtyp ; atyp
// wave prepared xwave object
// wtyp type of window function: HANNING, HAMMING, KAISER, ...
// atyp type of output spectrum: LOGARITHMIC (=DB), POWER, LINEAR (=AMPLITUDE)
// result: an averaged fft spectrum in the selected format
//
// DSPEXLIB SPECTROGRAM wave ; wtyp ; atyp
// wave prepared xwave object
// wtyp type of window function: HANNING, HAMMING, KAISER, ...
// atyp type of output spectrum: LOGARITHMIC (=DB), POWER, LINEAR (=AMPLITUDE)
// or COMPLEX
// result: a matrix of fft spectra in the selected format, one spectrum per line
//
// DSPEXLIB FREQUENCYSCALE sr ; n ; type
// sr sampling rate in Hz
// n number of spectrum bins (equally spaced in the Hz domain)
// type type of frequency scale: HZ, KHZ, BARK, MEL, ERB
// result: 'frq unit df'; frq is the frequency scale vector, unit is the frequency unit
// name and df is the frequency scale step in Hz
//
// DSPEXLIB AMPLITUDESCALE type
// type type of amplitude scale: LOGARITHMIC (=DB), POWER, LINEAR (=AMPLITUDE)
// result: 'name unit df'; name and unit of amplitude scale
//
//-------------------------------------------------------------------------------------------------
[Macro DSPExLib]

// function call dispatching
readvar #argv #fun #argv /d
goto fun$#fun noFun

noFun:
// function not implemented
// result: empty string

// show an error message and exit
con log '$#mac function "$#fun" not implemented'
exit 1 set ''

//-------------------------------------------------------------------------------------------------
funGetSegments: // in:
// out: segment_list_table
//-------------------------------------------------------------------------------------------------
// retrieve list of selected segments from the DataSet application
#segments := datasetcmd getselected segments
if '$#segments[?]' == table && '$#segments[]' > 0 exit 1 set $#segments
butil msgbox msg ; no segments selected - select and try again; Error!
if '$#segments[?]' == table delete $#segments
exit 2 set '' // terminate this and the calling macro!

//-------------------------------------------------------------------------------------------------
funAverageSpectrum: // in: xwaveobject ; windowtype ; amplitudescale
// out: averagespectrum_vector
//-------------------------------------------------------------------------------------------------
// parse arguments
readvar #argv #wave';'#wtyp';'#atyp';'#

// show init message
con log $#mac $(upper '$#fun') - initializing

// create window
#w := gosub makewindow $($#wave framelength) $#wtyp

// create result table
#spg := new table *

// compute averaged amplitude spectrum
#n := $($#wave framecount)
$#spg := eval cr2len ( fft ( $($#wave read) ?* $#w ) )
for #i := 1 to $#i < $#n step #i := int $#i+1
if $#i%10 == 0 con logext 0; $#mac $(upper '$#fun') - $#i of $#n frames processed
$#spg := eval cr2len ( fft ( $($#wave read) ?* $#w ) ) + $#spg
end
$#spg := eval $#spg / $#n

// convert to selected output spectrum type
if $(#atyp := keyword '$#atyp' dB logarithmic power amplitude linear) < 2 then
$#spg := eval lin2log($#spg , $($#wave aref), 20)
else if $#atyp == 2 then
$#spg := eval $#spg ?^ 2
end

// show end message
con logext 0; $#mac $(upper '$#fun') - finished ($#n spectra computed)

// return averaged spectrum
exit 1 set $#spg

//-------------------------------------------------------------------------------------------------
funSpectrogram: // in: xwaveobject ; windowtype ; amplitudescale
// out: spectrogram_matrix
//-------------------------------------------------------------------------------------------------
// parse arguments
readvar #argv #wave';'#wtyp';'#atyp';'#

// show init message
con log $#mac $(upper '$#fun') - initializing

// create window
#w := gosub makewindow $($#wave framelength) $#wtyp

// check selected output spectrum type
if $(#atyp := keyword '$#wtyp' dB logarithmic power amplitude linear complex) < 5 then
// compute amplitude or power spectra

// create result table (one spectrum per line)
#spg := new table * * num:x:$(int $($#wave fftlength)/2 + 1) /p
// compute amplitude spectra
#n := $($#wave framecount)
for #i := 0 to $#i < $#n step #i := int $#i+1
if $#i%10 == 0 con logext 0; $#mac $(upper '$#fun') - $#i of $#n frames processed
$#spg[$#i,*] := eval cr2len ( fft ( $($#wave read) ?* $#w ) )
end
// convert to selected output spectrum type
if $(#atyp := keyword '$#atyp' dB logarithmic power amplitude linear) < 2 then
$#spg := eval lin2log($#spg , $($#wave aref), 20)
else if $#atyp == 2 then
$#spg := eval $#spg ?^ 2
end

else
// compute complex spectra

// create result table (one spectrum per line)
#spg := new table * * num:x:$(int $($#wave fftlength) + 2) /p
// compute complex spectra
for #i := int $($#wave framecount) to $#i > 0 step #i := int $#i-1
if $#i%50 == 0 con logext 0; $#mac $(upper '$#fun') - $#i of $#n frames processed
$#spg[$#i,*] := eval fft ( $($#wave read) ?* $#w )
end

end

// show end message
con logext 0; $#mac $(upper '$#fun') - finished ($#n spectra computed)

// return spectrogram matrix
exit 1 set $#spg

//-------------------------------------------------------------------------------------------------
funFrequencyScale: // in: samplingrate ; spectrumbins ; frequencyscale
// out: frequencyscale_vector frequencyscale_unit frequency_resolution_Hz
//-------------------------------------------------------------------------------------------------
// parse arguments
readvar #argv #sr';'#n';'#unit';'#
// generate frequency scale equally spaced in Hz
#frq := new table * // dummy table to make frq-scale permanent
$#frq := eval fill($#n, 0, $(#df := eval $#sr / 2 / ($#n - 1)) )
// convert to selected scale
if $(#unit := keyword '$#unit' Hz kHz Bark Mel ERB) < 0 #unit := 0
if $(#unit := word $#unit Hz kHz Bark Mel ERB) == kHz then
$#frq := eval $#frq / 1000
else if $#unit != Hz then
$#frq := eval hz2$#unit($#frq)
end
// return scale settings
exit 1 set '$#frq $#unit $#df'

//-------------------------------------------------------------------------------------------------
funAmplitudeScale: // in: amplitudescale
// out: amplitudescale_text amplitudescale_unit
//-------------------------------------------------------------------------------------------------
// parse arguments
readvar #argv #unit';'#
// get text and unit of amplitude scale
if $(#i := keyword '$#unit' dB logarithmic power amplitude linear) < 2 #i := 0
#unit := word $#i dB dB - - -
#text := word $#i amplitude amplitude power amplitude amplitude
exit 1 set '$#text $#unit'

//
// local subroutines
//

makeWindow:
// GOSUB MAKEWINDOW windowlength windowtype -> windowvector
readvar #argv #wlen #wtyp #
#list := hanning hamming blackman kaiser bartlett taprect nuttall flattop gauss
if $(#wtyp := keyword '$#wtyp' $#list) < 0 #wtyp := 0
exit 1 eval window($#wtyp, $#wlen, 1) * 2 / $#wlen
</pre>

Programmer Guide/Macro Library/XPlot

2014-05-20T13:03:07Z

Admin:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}

{{TOC limit|3}}

==XPlot : CObjEx==

A general class for plotting multiple graphs.

====XPlot Construction====

Initialize a new XPlot-instance to display 1 or more graphs. Returns the new object or an empty string. Information and error messages are written to the <code>BSCRIPT CON</code> console.

=====Usage:=====

<code>XPlot <var>rows</var>=1 ; <var>columns</var>=1 ; <var>title</var> ; <var>profile</var> ; <var>window</var> ; <var>owner</var></code>

=====Parameters:=====

;<var>rows</var>

:The number of rows (default=<code>1</code>).

;<var>columns</var>

:The number of columns for each row (inrow0 inrow1 ...). The default is one column per row.

;<var>title</var>

:The display window title.

;<var>profile</var>

:The name of the graphics profile to use. A graphics profile is also known as a colour scheme.

;<var>window</var>

:The window position and size (in the format '<code>x y width height</code>').

;<var>owner</var>

:The id of an existing display item which should own this new window. See <code>NEW DISPLAY</code> for details.

=====Result:=====

A new <code>XPlot</code> object if successful or an empty string.

=====Examples:=====

The simplest way to create an <code>XPlot</code> instance with one graph is as follows:

<pre>
#xplot := xplot
if '$#xplot[?]' != 'instance' em -1 ; Failed to create the xplot instance
</pre>
====XPlot Member Functions====

The <code>XPLOT</code> class has the following member functions. See CObjEx Member Functions for a list of functions implemented in the parent class.

=====AddPlot=====

The <code>XPLOT</code> function <code>AddPlot</code> is a lot like <code>Plot</code>, but the functions are plotted in an existing graph (in addition to or on top of the original plot). If no graph exists at the specified <var>adr</var>, then the call is passed to <code>Plot</code>.

======XYPLOT======

Add an x/y plot to an existing plot as defined by <var>adr</var>. For example, plot a function over an existing spectrogram.

Usage:

<code><var>xplot</var> AddPlot <var>adr</var> ; XYPLOT ; <var>y</var> ; <var>x</var> ; <var>title</var> ; <var>xr</var> ; <var>xu</var> ; <var>xt</var> ; <var>yr</var> ; <var>yu</var> ; <var>yt</var> ; <var>fstyles</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

Parameters:

See [[#Plot|PLOT]] for parameter details.

Result:

Return <code>0</code> if successful.

======FUNCTION======

Add an x/y plot to an existing plot as defined by <var>adr</var>. For example, plot a function over an existing spectrogram.

=====Usage:=====

<code><var>xplot</var> AddPlot <var>adr</var> ; FUNCTION ; <var>y</var> ; <var>x</var> ; <var>title</var> ; <var>xr</var> ; <var>xu</var> ; <var>xt</var> ; <var>yr</var> ; <var>yu</var> ; <var>yt</var> ; <var>fstyles</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

See [[#Plot|PLOT]] for parameter details.

=====Result:=====

Return <code>0</code> if successful.

======PARAMETER======

Plot a parameter function in an existing graph.

=====Usage:=====

<code><var>xplot</var> AddPlot <var>adr</var> ; PARAMETER ; <var>y ; title ; xr ; xu ; xt ; yr ; yu ; yt ; fstyles</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

See the <code>XYPLOT</code> for parameter details.

=====Result:=====

Return <code>0</code> if successful.

===Dialog===

The function <code>Dialog</code> can be used to show and hide a dialog in the <code>XPlot</code> display.

=====Usage:=====

<code><var>inst</var> Dialog <var>cmd</var> ; <var>args</var></code>

=====Parameters:=====

;<var>cmd</var>

:See below for details.

;<var>args</var>

:See below for details.

=====Result:=====

The ID of the current or new dialog item or an empty string.

======New======

Creates a new dialog item (deleting the old one first).

=====Usage:=====

<code><var>inst</var> Dialog New</code>

======Delete======

Removes the dialog from the display and deletes the dialog item.

=====Usage:=====

<code><var>inst</var> Dialog Delete</code>

======Msg======

Posts a message to the macro message queue. The format of the message is:

<code>MENU</code> <var>dialogItem</var> <var>msgId</var> <var>msgPar</var>

Note that when the display is closed, this function is called to post the message <code>MENU dialogItem CLOSE</code> to the dialog item.

=====Usage:=====

<code><var>inst</var> Dialog Msg ; <var>pos</var> ; <var>msgid</var> <var>msgpar</var></code>

=====Parameters:=====

;<var>pos</var>

:Sets the position of the dialog within the display. The following values are supported:

:<code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code>

;<var>msgid</var>

:The message ID.

;<var>msgpar</var>

:The message parameters.

======On|Enabled======

Show the dialog and set it's position.

=====Usage:=====

<code><var>inst</var> Dialog On; <var>pos</var></code>

<code><var>inst</var> Dialog Enabled; <var>pos</var></code>

=====Parameters:=====

;<var>pos</var>

:Sets the position of the dialog within the display. The following values are supported:

:<code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code>

======Off|Hidden======

Show the dialog and set it's position.

=====Usage:=====

<code><var>inst</var> Dialog Off ; <var>pos</var></code>

<code><var>inst</var> Dialog Hidden ; <var>pos</var></code>

=====Parameters:=====

;<var>pos</var>

:Sets the position of the dialog within the display. The following values are supported:

:<code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code>

===Display===

Returns the ID of the display object associated with this <code>XPLOT</code> instance.

=====Usage:=====

<code><var>inst</var> display</code>

=====Result:=====

Returns the display object of the <code>XPLOT</code> instance.

===End===

Enters the message loop, waits until the user closes the plot display and then destroys itself.

===Get===

Retrieve an attribute from a specific graph.

=====Usage:=====

<code><var>xplot</var> Get <var>adr</var> ; <var>attribute</var></code>

=====Parameters:=====

;<var>adr</var>

:The address of the display splitter (see member function <code>Graph</code> for detail).

;<var>attribute</var>

:The id of the requested attribute. The following values are supported:

:<code>CURSORPOSITION</code> - Returns the current cursor positions in the following format: <code>i1 x1 y1 i2 x2 y2</code>

:Note that <code>x1 <= x2</code>

:<code>YDATA</code> - Returns the y data item.

:<code>XDATA</code> - Returns the x data item.

:<code>RANGE</code> - Returns the x axis and y axis range in the following format: <code>xmin xmax ymin ymax</code>

:<code>TYPE</code> - Returns the plot type (see <code>Plot</code> for a list of available plot types).

===GetFColors===

The <code>GetFColors</code> function returns a blank separated list of the function colors defined in the selected graphics profile.

=====Usage:=====

<code><var>xplot</var> GetFColors</code>

=====Result:=====

Returns a blank separated list of color keywords.

===Graph===

Returns the requested attribute <var>attr</var> of the graph identified by <var>adr</var>.

=====Usage:=====

<code><var>xplot</var> Graph <var>adr</var> [; <var>attr</var>=GRAPH ]</code>

=====Parameters:=====

;<var>adr</var>

:The id of a graph item, an <code>[[Programmer Guide/Class Library/XGraph : CObjEx|XGRAPH]]</code> instance or the '<code>row column</code>' address of a splitter in the display. Note that the <code>row</code> and <code>column</code> indices are zero-based.

;<var>attr</var>

:The attribute to returned. The following values are allowed:

:<code>INSTANCE</code> - Return the id of the <code>XGRAPH</code> instance associated with <var>adr</var>.

:<code>GRAPH</code> - Return the id of the graph object associated with <var>adr</var>. This is the default attribute.

:<code>ROW</code> - Return the row index of the splitter associated with <var>adr</var>.

:<code>COLUMN</code> - Return the column index of the splitter associated with <var>adr</var>.

=====Result:=====

Return values are selected by the argument <var>attr</var>. See the description of <var>attr</var> for details. If the address argument <var>adr</var> do not refer to a graph, <code>XGRAPH</code> or splitter of the display, an empty string is returned.

=====Examples:=====

Get the graph item id for the top left graph.

<pre>
#graph := $#xplot graph 0 0
</pre>
===Legend===

Display a graph legend. Use <code>$#xplot LEGEND $#graph</code> to clear the legend.

=====Usage:=====

<code><var>xplot</var> Legend <var>graph</var> ; <var>unit</var> ; <var>x</var> ; <var>y</var> ; <var>w</var> ; <var>h</var> ; <var>color</var> ; <var>info</var> ; <var>text1</var> ; <var>text2</var> ; <var>textX</var></code>

=====Parameters:=====

;<var>graph</var>

:The graph address (e.g. row and column index. See [[#Plot|PLOT]] for detail).

;<var>unit</var>

:The unit for size and position values. The following values are supported:

:<code>real</code> - The real x/y values.

:<code>%</code> or <code>percent</code> - The percent of the graph's plot area.

;<var>x, y</var>

:The position of the upper right corner of the first legend line.

;<var>w, h</var>

:The width and height of one legend line.

;<var>color</var>

:The legend text color.

;<var>info</var>

:This flag selects the line attributes to be displayed. The following values are supported:

:<code>color</code> - The color.

:<code>all</code> - The color, style, width and symbol.

;<var>textX</var>

:The text for the legend for function X. If no text is supplied, the legend line is removed.This parameter can be either a string, or a simple table.

=====Result:=====

void

===Plot===

The <code>XPlot</code> function <code>Plot</code> can be used to plot a function in a graph. Currently, {{STX}} supports waveform , x/y (aka function and more specifically parameter), spectrogram and waterfall plots.

======XYPLOT======

Plot an x/y function graph.

=====Usage:=====

<code><var>xplot</var> Plot <var>adr</var> ; XYPLOT ; <var>y</var> ; <var>x</var> ; <var>title</var> ; <var>xr</var> ; <var>xu</var> ; <var>xt</var> ; <var>yr</var> ; <var>yu</var> ; <var>yt</var> ; <var>fstyles</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

;<var>adr</var>

:The address of the display splitter (see the member function [[#Graph|GRAPH]] for details).

;<var>y</var>

:The y axis data (a vector or an array).

;<var>x</var>

:The data to be used for the x axis. This can be one of the following:

:A data vector with <code>y[!nrow]</code> values and 1 column.

:<code>*</code> - An asterisk. This is the default and means that the x axis uses the values <code>0</code> through to <code>y[!nrow]-1</code>.

:A blank separated list of values ('x1 x2' -> x[i] = x1+(x2-x1)/(y[!nrow]-1), i = 0..<code>y[!nrow]-1</code>).

;<var>title</var>

:The title to be displayed in this plot.

;<var>xr</var>

:The x axis display range. This can be one of the following values:

:<code>*</code> - An asterisk - an automatic scale is generated.

:<code>xmin xmax</code> - Two numerical values - the minimum and maximum values.

;<var>xu</var>

:The text describing the x axis unit (e.g. <code>seconds</code>). The default is an empty string.

:The <code>WAVEFORM</code> plot only allows the following values: <code>SAMPLES</code>|<code>MS</code>|<code>S</code>. The default is <code>S</code>.

;<var>xt</var>

:The title to be used for the x axis. The default is an empty string.

;<var>yr</var>

:The y axis display range. This can be one of the following:

:<code>*</code> - An asterisk - an automatic scale is generated.

:<code>ymin ymax</code> - Two numerical values - the minimum and maximum values.

;<var>yu</var>

:The text describing the y axis unit (e.g. <code>dB</code>).

;<var>yt</var>

:The title to be used for the y axis. The default is an empty string.

;<var>fstyles</var>

:An <code>fstyle</code> argument (see <code>fstyle</code> for details) or a zero-based function line index as specified in a color scheme (see Color Schemes in the User Guide).

;<var>xlabtab, ylabtab, zlabtab</var>

:Extended tables containing the scale, grid and label definitions. For a description of the table format, please see the scale definition table for details.

=====Result:=====

Return <code>0</code> if successful.

=====Examples:=====

Plot a simple x/y function.

<pre>
#xplot := XPLOT 1 ; 1 ; XPLOT ; Default ; 0 0 400 400
$#xplot plot 0 ; XYPLOT; $(eval fill(10, 0, 1)) ; * ; xyplot ; * ; ; x-axis ; * ; ; y-axis
</pre>
======FUNCTION======

Plot a function graph. Note that this is identical to an <code>XYPLOT</code>.

=====Usage:=====

<code><var>xplot</var> Plot <var>adr</var> ; FUNCTION ; <var>y ; x ; title ; xr ; xu ; xt ; yr ; yu ; yt ; fstyles</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

See <code>XYPLOT</code> for parameter descriptions.

=====Result:=====

Return <code>0</code> if successful.

======parameter======

Plot a parameter graph. A parameter graph differs from a function graph because a parameter plot can have missing values - it does not necessarily have values for every point on the x axis.

=====Usage:=====

<code><var>xplot</var> Plot <var>adr</var> ; parameter ; <var>y ; title ; xr ; xu ; xt ; yr ; yu ; yt ; fstyles</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

See the <code>xyplot</code> for parameter details.

=====Result:=====

Return <code>0</code> if successful.

======spectrogram======

Plot a spectrogram graph.

=====Usage:=====

<code><var>xplot</var> plot <var>adr</var> ; spectrogram ; <var>d</var> ; <var>y</var> ; <var>title</var> ; <var>xr</var> ; <var>xu</var> ; <var>xt</var> ; <var>yr</var> ; <var>yu</var> ; <var>yt</var> ; <var>zr</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

;<var>d</var>

:A data array containing one spectrum or function line per <var>y</var> row. Note that this parameter is specific to the <code>SPECTROGRAM</code> and <code>WATERFALL</code> plots.

;<var>y</var>

:The y-scale data (frequency). This can be one of the following:

:1) <code>vData</code> - A data vector with <code>y[!ncol]</code> values and 1 column.

:2) * - An asterisk: <code>y[i] = i</code>, <code>i = 0..d[!ncol]-1</code>. This is the default.

:3) <code>y1 y2</code> - Two blank separated values: <code>y[i] = y1+i*(y2-y1)/(d[!ncol]-1)</code>, <code>i = 0..d[!ncol]-1</code>.

;<var>zr</var>

:The z scale is a color scale. The following values are supported:

:<code>*</code> - An asterisk. The range is automatically generated.

:<code>zmin zmax</code> - Two numerical values specifying the minimum and maximum z axis values.

:<code>zdown</code> - A numerical value. The maximum z value is chosen automatically and the minimum value is calculated as follows: <code>zmax-zdown</code>.

For all other parameters, see <code>xyplot</code> for descriptions.

======WATERFALL======

Plot a waterfall graph.

=====Usage:=====

<code><var>xplot</var> PLOT <var>adr</var> ; WATERFALL ; <var>d</var> ; <var>x</var> ; <var>title</var> ; <var>xr</var> ; <var>xu</var> ; <var>xt</var> ; <var>yr</var> ; <var>yu</var> ; <var>yt</var> ; <var>zr</var> ; <var>zu</var> ; <var>zt</var> ; <var>xw</var> ; <var>yw</var> ; <var>n</var> ; <var>xlabtab</var> ; <var>ylabtab</var> ; <var>zlabtab</var></code>

=====Parameters:=====

;<var>d</var>

:The data array (one spectrum or function-line / row).

;<var>zr</var>

:The z axis display range. The following values are supported:

:<code>*</code> - An asterisk. The range is automatically generated.

:<code>zmin zmax</code> - Two numerical values specifying the minimum and maximum z axis values.

;<var>zu</var>

:The text describing the z axis unit (e.g. <code>s</code>).

;<var>zt</var>

:The title to be used for the z axis. The default is an empty string.

;<var>xw</var>

:The relative width of the x scale. A value between <code>-1</code> and <code>1</code>. The default is <code>0.8</code>.

;<var>yw</var>

:The relative width of the y scale. A value between <code>-1</code> and <code>1</code>. The default is <code>0.8</code>.

;<var>n</var>

:The number of lines to be plotted. The default is <code>150</code>.

For all other parameters, see <code>XYPLOT</code> for descriptions.

======WAVEFORM======

Plot a waveform graph. Note that the displayed wave item is automatically attached to the graph. This means, no explicit call to <code>SetWave</code> is necessary.

=====Usage:=====

<code><var>xplot</var> PLOT <var>adr</var> ; WAVEFORM ; <var>wave</var> ; <var>title</var> ; <var>xu</var> ; <var>xt</var> ; <var>ymax</var> ; <var>yr</var> ; <var>yt</var> ; <var>fill</var></code>

=====Parameters:=====

;<var>wave</var>

:A wave item id or an <code>XWAVE</code> instance

;<var>xu</var>

:The unit to use on the x axis. The following values: <code>SAMPLES</code>|<code>MS</code>|<code>S</code>. The default is <code>S</code>.

;<var>ymax</var>

:The maximum waveform amplitude. This can be a value between 0 and ...

;<var>yr</var>

:The y axis display range. This can be any positive number. The default is <code>1</code>.

;<var>fill</var>

:<code>1</code> if the waveform envelope should be filled or <code>0</code>.

For all other parameters, see <code>XYPLOT</code> for descriptions.

======TEXTBOX======

Plot a graph containing text.

=====Usage:=====

<code><var>xplot</var> PLOT <var>adr</var> ; TEXTBOX ; <var>title</var> ; <var>color</var> ; <var>halign</var> ; <var>valign</var> ; <var>text</var></code>

=====Parameters:=====

;<var>title</var>

:The graph title.

;<var>color</var>

:The text color. This can be an of the {{STX}} color arguments.

;<var>halign</var>

:The horizontal text alignment. This can be one of the following values: <code>CENTER</code>|<code>LEFT</code>|<code>RIGHT</code>

;<var>valign</var>

:The vertical text alignment. This can be one of the following values: <code>CENTER</code>|<code>TOP</code>|<code>BOTTOM</code>

;<var>text</var>

:The text to be displayed. This can be a simple table with an entry per line of text or a semi-colon separated list of text lines.

For all other parameters, see <code>XYPLOT</code> for descriptions.

======fstyle======

The <var>fstyle</var> argument passed to the <code>XPlot</code> functions <code>Plot</code> and <code>AddPlot</code> has the following syntax and components:

<code><var>linestyle</var><code>:</code><var>linecol</var><code>:</code><var>printcol</var><code>:</code><var>linewidth</var><code>:</code><var>drawstyle</var><code>:</code><var>drawsym</var><code>:</code><var>ymiss</var></code>

;<var>linestyle</var>

:Determines whether the function line is solid (<code>SOLID</code>), dotted (<code>DOT</code>) or dashed (<code>DASH</code>). The default value is taken from the <code>XPLOT</code> color profile.

;<var>linecol</var>

:The colour to use for the function line on screen. This can be any {{STX}} colour keyword or RGB value. The default value is taken from the <code>XPLOT</code> color profile.

;<var>printcol</var>

:The colour to use for the function line when printing. See <var>linecol</var> for details. The default value is taken from the <code>XPLOT</code> color profile.

;<var>linewidth</var>

:The width of the function line. Possible values are <code>0</code> through to <code>4</code> for lines with the <code>SOLID</code> <var>linestyle</var> and <code>0</code> or <code>1</code> for lines with the <code>DOT</code> or <code>DASH</code> <var>linestyle</var>. The default value is taken from the <code>XPLOT</code> color profile.

;<var>drawstyle</var>

:The style to use to draw the function. Each function point can be plotted separately (<code>POINTS</code>), a line can be drawn between each function point (<code>LINES</code>), the area below the function can be filled with the <var>linecol</var> (<code>AREA</code>), the function points can be joined by steps (<code>STEPS</code> - note that this is only available for the <code>PARAMETER</code> plot) or no points are plotted (<code>NONE</code> - this is best used when a drawing symbol (<var>drawsym</var>) is defined). The default style is <code>LINES</code>.

;<var>drawsym</var>

:The symbol to draw at each point. This can be used in conjunction with a drawing style (see <var>drawstyle</var>). The following keywords are supported:

:<code>NONE</code>|<code>SQUARE</code>|<code>TRIANGLE|CIRCLE|CROSS|DIAMOND</code>

:The default style is <code>NONE</code>.

;<var>ymiss</var>

:The value to use for missing y values. If <var>ymiss</var> is not specified (empty) all values are displayed, otherwise all points where <code>y=</code><var>ymiss</var> are not displayed. If <var>ymiss</var> is not empty and is not a number then <var>ymiss</var> is set to <code>0</code>. If no <var>ymiss</var> is defined, no <var>ymiss</var> is used (this is the default).

===Redraw===

Redraw the selected graph. This is currently only implemented for the <code>FUNCTION</code> (<code>XYPLOT</code>) and <code>PARAMETER</code> plots.

=====Usage:=====

<code><var>xplot</var> REDRAW <var>adr</var></code>

=====Parameters:=====

;<var>adr</var>

:The address of the display splitter (see member function <code>Graph</code> for details).

=====Result:=====

Return 0 if successful.

===ScaleOctave===

Generate a logarithmic scale table for use with the <code>Plot</code> or <code>AddPlot</code> functions. This function can also be called statically.

=====Usage:=====

<code><var>xplot</var> ScaleOctave <var>df</var> <var>count</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code>xplot ScaleOctave <var>df</var> <var>count</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code><var>xplot</var> ScaleOctave <var>vector</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code>xplot ScaleOctave <var>vector</var> ; <var>fmax</var> ; <var>fmin</var></code>

=====Parameters:=====

;<var>df</var>

:The frequency resolution in Hz.

;<var>count</var>

:The number of frequency points.

;<var>fmax</var>

:The maximum frequency to be displayed.

;<var>fmin</var>

:The minimum frequency to be displayed.

;<var>vector</var>

:The scale range as a data vector.

=====Result:=====

The following string is returned:

<code>xmin xmax xlabTab xdata</code>

Where <code>xmin</code> and <code>xmax</code> are is the minimum and maximum of the logarithmic scale, <code>xlabTab</code> is the scale definition table which you can then pass to a <code>Plot</code> function and <code>xdata</code> is the logarithmic frequency values vector. See the scale definition table description in the Command Reference for details of the table syntax.

=====Examples:=====

Create a scale definition table for a logarithmic frequency axis with 2000 points at 10 Hz intervals and a maximum frequency of 10000 Hz.

<pre>
readstr '$(xplot scaleOctave 10 2000; 10000)' #xmin #xmax #xlab #x
</pre>
=====Notes:=====

See also ScaleSteps.

===ScaleLog10===

Generate a logarithmic scale table for use with the <code>Plot</code> or <code>AddPlot</code> functions. This function can also be called statically.

=====Usage:=====

<code><var>xplot</var> ScaleLog10 <var>df</var> <var>count</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code>xplot ScaleLog10 <var>df</var> <var>count</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code><var>xplot</var> ScaleLog10 <var>vector</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code>xplot ScaleLog10 <var>vector</var> ; <var>fmax</var> ; <var>fmin</var></code>

=====Parameters:=====

;<var>df</var>

:The frequency resolution in Hz.

;<var>count</var>

:The number of frequency points.

;<var>fmax</var>

:The maximum frequency to be displayed.

;<var>fmin</var>

:The minimum frequency to be displayed.

;<var>vector</var>

:The scale range as a data vector.

=====Result:=====

The following string is returned:

<code>xmin xmax xlabTab xdata</code>

Where <code>xmin</code> and <code>xmax</code> are is the minimum and maximum of the logarithmic scale, <code>xlabTab</code> is the scale definition table which you can then pass to a <code>Plot</code> function and <code>xdata</code> is the logarithmic frequency values vector. See the scale definition table description in the Command Reference for details of the table syntax.

=====Notes:=====

See also <code>ScaleSteps</code> and <code>ScaleOctave</code>.

===ScaleSteps===

Generate a linear scale table for use with the <code>Plot</code> or <code>AddPlot</code> functions. This function can also be called statically, e.g. '<code>xplot ScaleSteps -70 -10 ; 10 ; 5 ; 5 ; 1 ; 1</code>'.

=====Usage:=====

<code><var>inst</var> ScaleSteps <var>min</var> <var>max</var> ; <var>labelDist</var> ; <var>majorGridDist</var> ; <var>majorTickDist</var> ; <var>minorGridDist</var> ; <var>minorTickDist</var></code>

<code>xplot ScaleSteps <var>min</var> <var>max</var> ; <var>labelDist</var>; <var>majorGridDist</var>; <var>majorTickDist</var> ; <var>minorGridDist</var> ; <var>minorTickDist</var></code>

<code><var>inst</var> ScaleSteps <var>vector</var> ; <var>labelDist</var>; <var>majorGridDist</var>; <var>majorTickDist</var> ; <var>minorGridDist</var> ; <var>minorTickDist</var></code>

<code>xplot ScaleSteps <var>vector</var> ; <var>labelDist</var>; <var>majorGridDist</var>; <var>majorTickDist</var> ; <var>minorGridDist</var> ; <var>minorTickDist</var></code>

=====Parameters:=====

;<var>min, max</var>

:The scale range.

;<var>vector</var>

:The scale range as a data vector.

;<var>labelDist</var>

:The label distance in scale units.

;<var>majorGridDist</var>

:The distance of the major grid lines in scale units.

;<var>majorTickDist</var>

:The distance between major ticks in scale units.

;<var>minorGridDist</var>

:The distance of the minor grid lines in scale units.

;<var>minorTickDist</var>

:The distance between minor ticks in scale units.

=====Result:=====

The following string is returned:

<code>min max labTab</code>

Where <code>min</code> and <code>max</code> are is the computed or corrected scale range and <code>labTab</code> is the scale definition table which you can then pass to a <code>Plot</code> function. See the scale definition table description in the Command Reference for details of the table syntax.

=====Examples:=====

Calculate the linear scale, grid and labels for an amplitude axis between -70 and -10 dB with labels every 10 dB, major grid lines and ticks every 5dB and minor grid lines and ticks every dB.

<pre>
readstr '$($#xplot ScaleSteps -70 -10 ; 10 ; 5 ; 5 ; 1 ; 1)' #ymin #ymax #ylab
</pre>
=====Notes:=====

See also <code>ScaleOctave</code> and <code>ScaleLog10</code>.

===Set===

The <code>Set</code> function sets the cursor mode and text attributes.

=====Usage:=====

<code><var>xplot</var> Set [ <var>graph</var>|* ; ] <var>attr</var> <var>args</var></code>

=====Parameters:=====

;<var>xgraph</var>

:An xgraph instance on which to call the <code>Set</code> command. If no graph is specified or an asterisk, then the <code>Set</code> command is carried out on all graphs.

;<var>attr</var>

:One of the following values:

:<code>cursormode</code> - turn cursors on and off and change the way they look.

:<code>xunit</code> - the name of the x-axis unit

:<code>yunit</code> - the name of the y-axis unit

:<code>xtext</code> - the description of the x-axis

:<code>ytext</code> - the description of the y-axis

:<code>title</code> - the graph's title

;<var>args</var>

:The value of <var>args</var> depends on <var>attr</var>.

:If <var>attr</var> is <code>cursormode</code>, then <var>args</var> is as follows:

:<code>mode|* type|* line|*</code>

:Where mode is one of the following values:

:<code>on</code> - show the cursor

:<code>off</code> - hide the cursor

:Where <var>type</var> is one of the following values:

:<code>cross</code>|<code>crosshair</code>|<code>vbarcross</code>|<code>harmonic</code>

:And <code>line</code> is one of the following values:

:<code>off</code> |<code>on</code>

:If <var>attr</var> is not <code>cursormode</code>, then <var>args</var> is used as the text, unit or title.

=====Result:=====

No return value.

===SetCallback===

The callback function is called by the message handlers to process popup and context menu messages and hotkeys which are not used by <code>XPLOT</code> or <code>XGRAPH</code>. The following commands are used to call the callback function:

If called from an <code>XGRAPH</code> message handler:

<code>cbfunction xgraphinstance irow icol msgid msgpar</code>

If called from the <code>XPLOT</code> message handler:

<code>cbfunction xplotinstance * * msgid msgpar</code>

=====Usage:=====

<code><var>xplot</var> SetCallback [ <var>cbfunction</var> ]</code>

=====Parameters:=====

;<var>cbfunction</var>

:The name of the callback function or an empty string to remove a previous association.

=====Result:=====

No return value.

===SetWave===

Attach a signal to one graph or all graphs (see <var>adr</var>). If a wave item is attached to a graph, it can not be deleted before it is detached or the graph or <code>XPLOT</code> instance is deleted.

=====Usage:=====

<code><var>xplot</var> SetWave [ <var>waveitem</var> ]</code>

<code><var>xplot</var> SetWave <var>adr</var> ; [ <var>waveitem</var> ]</code>

=====Parameters:=====

;<var>adr</var>

:The address of the display splitter (see member function Graph for details). If this parameter is omitted, then the wave item is set for all graphs.

;<var>waveitem</var>

:A wave item id or an <code>[[Programmer Guide/Class Library/XWave : CObjEx|XWAVE]]</code> instance (or empty to remove attachment).

=====Result:=====

Return <code>0</code> if successful.

Note that wave items can only be attached to graphs of type <code>FUNCTION</code>, <code>XYPLOT</code>, <code>PARAMETER</code>, <code>SPECTROGRAM</code> and <code>WAVEFORM</code>.====XPlot Hotkeys====

The following hotkeys are implemented in the <code>XPLOT</code> class:

{|
|-
|C
|Turn the cursors on and off.
|-
|S
|Change to the next cursor style.
|-
|B
|Turn cursor binding on and off.
|-
|Ctrl+N
|Bind the cursor to the next function.
|-
|Ctrl+P
|Bind the cursor to the previous function.
|-
|R
|Turn the cursor rubberline on and off.
|-
|T
|Turn the title on and off.
|-
|X
|Change to the next x<nowiki>-</nowiki>scale mode.
|-
|Y
|Change to the next y<nowiki>-</nowiki>scale mode.
|-
|Z
|Change to the next z<nowiki>-</nowiki>scale mode.
|-
|Space
|Open the setup dialog.
|-
|P
|Play the attached wave (between the cursors).
|-
|Q
|Play the attached wave (the whole signal).
|-
|ESC
|Stop playback.
|-
|Ins
|Show the selected metasegment's settings in a dialog or, if no metasegment is selected, show a dialog to create a new metasegment.
|-
|Del
|Delete the selected metasegments.
|-
|Ctrl+Left Click
|Move the legend to the clicked position.
|-
|Shift+Left Click
|Create a metasegment at the clicked position (show the 'Insert Metasegment' dialog).
|}

====XPlot Examples====

=====Simple XPLOT Example=====

The following example demonstrates simple <code>[[Programmer Guide/Class Library/XPlot : CObjEx|XPLOT]]</code> usage.

<pre>
[macro xplot_example_1]
//
// create display (and graph)
//
#xplot := xplot 2 ; 1 ; xplot ; default ; 100 100 800 800
if '$#xplot[?]' != 'instance' em -1 ; xplot creation failed ($emsg)
//
// plot graphs (including data generation)
//
#nValues := 100
$#xplot Plot 0 0 ; XYPLOT ; $(eval fill($#nValues,1,1)) ; * ; Graph Title ; * ; x unit ; x title ; * ; y unit ; y title ; solid:green::1
$#xplot Plot 1 0 ; SPECTROGRAM ; $(eval rand(1,100,100)) ; * ; Graph Title ; * ; x unit ; x title ; * ; y unit ; y title ; solid:green::1
//
// clean up
//
// the clean up takes place automatically
// when the plot window is closed
exit
</pre>
=====Plot rows of a matrix using XPLOT=====

The following example demonstrates how to plot the rows of a matrix using the <code>[[Programmer Guide/Class Library/XPlot : CObjEx|XPLOT]]</code> class.

<pre>
//{{3.9 6473}{2009.01.29 16.44.04} - automatically created version information - do not change or delete this line}

[macro xplot_example_2]

//
// This row demonstrates how to plot each row of a matrix
//
// C.G. 29.1.2009
//

//
// create display (and graph)
//

#xplot := xplot 1 ; 1 ; xplot ; default ; 100 100 800 800
if '$#xplot[?]' != 'instance' em -1 ; xplot creation failed ($emsg)

//
// create a matrix and fill it with some meaningless data
//

#mat := new table * /Parameter * number:X:100
if '$#mat[?]' != table em -1 ; cannot create table ($emsg)

for #i := 0 to $#i < 10 step #i := int $#i + 1
$#mat[$#i,*] := eval fill( 100, $#i+1, $#i+1 )
end

//
// plot each row of the matrix
//

for #i := int 0 to $#i < $#mat[!nrow] step #i := int $#i + 1
#x := eval $#mat[$#i,*]
$#xplot AddPlot 0 0 ; XYPLOT ; $#x ; * ; row-by-row plot ; * ; x unit ; x title ; * ; y unit ; y title ; solid:green::1
end

exit 1 int 0
</pre>

=====Advanced XPLOT Example=====

This example not only demonstrates the use of the <code>XPLOT</code> class, but also signal processing using the <code>EVAL</code> function.

<pre>
//=================================================================================================
//
// DSP Examples
//
// last update: Nov 17, 2007 (AN)
// {{STX}} version: {{STX}} 3.8 Beta
//
// The examples in this file demonstrates how to ...
// ... use the EVAL command for signal processing
// ... use the class XWAVE to read a signal frame by frame
// ... display spectrograms, waveforms and functions in XPLOT graphs
// ... enable XPLOT to play signals
// ... use the XPLOT callback function to implement simple user controls
// ... set and get cursor attritbutes and positions of XPLOT graphs
// ... add a legend to a XPLOT graph
// ... use BUTIL MSGBOX for simple dialogs
// ... use the CON object (class BScript) to display log. messages
// ... use the CON object to save numeric tables to textfiles
// ... simulate item messages using the message queue macro MSGQUEUE
// ... implement and call local subroutines
//
//=================================================================================================

//-------------------------------------------------------------------------------------------------
//
// DSPExAvrSpectrum Create a plot containing the average spectra of all segments selected
// in the DataSet view.
//
//-------------------------------------------------------------------------------------------------
[Macro DSPExAvrSpectrum #lfrm=100ms';'#sfrm=50%';'#wtyp=hamming';'#ascale=dB';'#fscale=Hz';'#amax=1';'#aref=1';'#]
// arguments: #lfrm frame length, absolute time expression
// #sfrm frame shift, relative time expression
// #wtyp window type, {Hanning, Hamming, ...)
// #fscale spectrogram frequency scale unit (Hz, kHz, Bark, Mel, ERB)
// #amax calibration factor or CALSET to use a calibration set
// #aref reference amplitude, ignored if #amax equals CALSET

// set mode to macro name (see macro DSPExCallback)
DSPExMode := set '$#mac'

// get segments selected in the DataSet view
#segments := dspexlib getsegments

// create the result table (one spectrum per row)
#asp := new table * * num:x:$#segments[] /p

// segment analysis loop
#nok := 0 // number of computed average spectra
for #i := 0 to $#i < $#segments[] step #i := int $#i+1

// get next segment from segment list
readtab $#segments $#i #aset';'#aseg';'#ach';'#
con log process segment "set=$#aset, id=$#aseg, ch=$#ach" ($(int $#i+1) of $#segments[])

// create the wave object and initialize frame settings (mode "centered")
// usage: XWAVE setref ; segmentid ; channel ; mode ; framelength ; frameshift ; ampmax ; ampref
if $(#wave := xwave '$#aset;$#aseg;$#ach;1;$#lfrm;$#sfrm;$#amax;$#aref')[?] != instance then
butil 'msgbox msg; create wave object for segment "$#aset/$#aseg,$#ach" failed; Error!'
continue
// set / check sampling rate
else if '$#srate' == '' then
#srate := $($#wave srate)
else if $($#wave srate) != $#srate then
butil 'msgbox msg; segment "$#aset/$#aseg,$#ach" - sampling rate mismatch; Error!'
$#wave destroy // delete wave object
continue
end

// compute the average spectrum
if $(#tmp := dspexlib averagespectrum $#wave ; $#wtyp ; $#ascale)[?] != table then
butil 'msgbox msg; compute average spectrum of segment "$#aset/$#aseg,$#ach" failed; Error!'
$#wave destroy // delete wave object
continue
end

$#asp[*,$#nok] := $#tmp // save the spectrum
delete $#tmp // delete temp. buffer
#legend := '$#legend $($#wave title);' // add segment to legend string
$#wave destroy // delete wave object
#nok := int $#nok+1 // increment result vector counter

end

// exit if no results are computed
if $#nok < 1 exit

// compute frequency scale vector, unit and frequency resolution
readstr '$(dspexlib frequencyscale $#srate ; $#asp[!nrow] ; $#fscale)' #frq #funit #df

// create and configure the plot object
// usage: XPLOT rows ; cols0 cols1 .. ; windowtitle ; graphicprofile ; wx wy wwidth wheight
#plot := xplot 1; 1; Average Spectrum; Rainbow; 0 0 1024 800

// plot all spectra and display the legend
#title := format 'lfrm=%s, sfrm=%s, wtyp=%s, df=%.3fHz' '$#lfrm' '$#sfrm' '$#wtyp' $#df
readstr '$(dspexlib amplitudescale $#ascale)' #ytext #yunit
// usage: xplot PLOT row col; FUNCTION; ydata; xdata; title; xrange; xunit; xtext; yrange; yunit; yrange
$#plot plot 0; function; $#asp; $#frq; $#title; ; $#funit; frequency; ; $#yunit ; $#ytext
$#plot legend 0; %; 50; 95; 45; 5; black; color; $#legend
$#plot set cursormode on crosshair // set cursor mode and style
$#plot setcallback dspexcallback // assign callback function

// wait until plot window is closed
$#plot end // the xplot object is destroyed automatically when the window is closed

// finished - cleanup and and exit
delete $#asp $#frq $#segments // delete data items
showLogOnExit := 0 // close the bscript log-window automatically
exit

//-------------------------------------------------------------------------------------------------
//
// DSPExSpectrogram Plot a spectrogram of all segments selected in the DataSet view.
// For each segment one spectrogram window is displayed. The window
// must be closed before the next segment is analysed.
//
//-------------------------------------------------------------------------------------------------
[Macro DSPExSpectrogram #lfrm=40ms';'#sfrm=10%';'#wtyp=hamming';'#arange=50';'#fscale=Hz';'#amax=1';'#aref=1';'#]
// arguments: #lfrm frame length, absolute time expression
// #sfrm frame shift, relative time expression
// #wtyp window type, {Hanning, Hamming)
// #arange spectrogram display range in dB (max .. max-range)
// #fscale spectrogram frequency scale unit (Hz, kHz, Bark, Mel, ERB)
// #amax calibration factor or CALSET to use a calibration set
// #aref reference amplitude, ignored if #amax equals CALSET

// set mode variable to macro name (see macro DSPExCallback)
DSPExMode := set '$#mac'

// get segments selected in the DataSet view
#segments := dspexlib getsegments

// segment analysis loop
for #i := 0 to $#i < $#segments[] && '$DSPExMode' != '' step #i := int $#i+1

// get next segment from segment list
readtab $#segments $#i #aset';'#aseg';'#ach';'#

// create the wave object and initialize frame settings (mode "centered")
if $(#wave := xwave '$#aset;$#aseg;$#ach;1;$#lfrm;$#sfrm;$#amax;$#aref')[?] != instance then
butil 'msgbox msg; create wave object for segment "$#aset ; $#aseg ; $#ach" failed; Error!'
continue
end

// compute the spectrogram
if $(#asp := dspexlib spectrogram $#wave ; $#wtyp ; log)[?] != table then
butil 'msgbox msg; compute spectrogram of segment "$#aset ; $#aseg ; $#ach" failed; Error!'
$#wave destroy
continue
end

// compute frequency scale vector, unit and frequency resolution
readstr '$(dspexlib frequencyscale $($#wave srate) ; $#asp[!ncol] ; $#fscale)' #frq #funit #df

// create and configure the plot object
#plot := xplot 2; 1 1; $($#wave title) quit = c-q, next = c-n; Rainbow; 0 0 1024 800
$($#plot display) height 3 1 /apply // set height of graphs

// plot spectrogram and waveform
#title := format 'lfrm=%s, sfrm=%s, wtyp=%s, arange=%s, amax=%.1fdB, df=%.3fHz' '$#lfrm' '$#sfrm' '$#wtyp' '$#arange' $(eval max($#asp)) $#df
$#plot plot 0; spectrogram; $#asp; $#frq; $#title; $($#wave tbegin) $($#wave tend); s; time; ; $#funit; frequency; $#arange
$#plot plot 1; waveform; $#wave; ; s; time; $($#wave amax); $($#wave amax); amplitude; 1
$#plot set cursormode on crosshair // set cursor mode and style
$#plot setcallback dspexcallback // assign callback function

// assign wave object to xplot graphs (for playback)
$#plot setwave $#wave

// wait until plot window is closed
$#plot end // the xplot object is destroyed automatically when the window is closed

// cleanup
delete $#asp $#frq // delete data items
$#wave destroy // delete wave object
end

// finished - cleanup and exit
delete $#segments // delete segment table
showLogOnExit := 0 // close the bscript log-window automatically
exit

//-------------------------------------------------------------------------------------------------
//
// DSPExCallback Callback function for XPLOT.
//
// arguments:
// if called from xplotobject message handler -> 'CALLBACK xplotobject * * msgid msgpar'
// if called from xgraphobject message handler -> 'CALLBACK xgraphobject row col msgid msgpar'
//
// Note: This macro uses the shell variable DSPEXMODE to check which macro has installed the
// callback and to set return values.
//
//-------------------------------------------------------------------------------------------------
[Macro DSPExCallback #obj #row #col #msgid #msgpar]

// get xplot-object if called from a xgraph-object
if '$#obj[!class]' == xgraph #obj := $#obj get xplot

// message filter for keystroke messages

// process Control-Q (QUIT) key
if '$#msgid$#msgpar' == keyCQ then

if $(butil msgbox yesno; Quit ?; $DSPExMode) == yes then
// place the display-close message in the message queue to end the xplot message loop
msgqueue 'display $($#obj display) close'
// set mode variable to empty-string if C-Q key was pressed
DSPExMode := ''
end

// process Control-C (COPY) and Control-S (SAVE) keys
else if $(#i := keyword '$#msgid$#msgpar' keyCC keyCS) >= 0 then

// get xgraph-object displayed in row 0 (later used to retrieve data)
#obj := $#obj graph 0; instance

// select the data to be saved and the save format
#todo := butil msgbox userdefined Amp Frq+Amp Cancel;; $DSPExMode - $(word $#i 'Copy to Clipboard' 'Save to CSV-File')
if $#todo == Amp then
#table := eval $($#obj get ydata) // use eval to get a copy of y-data
else if $#todo == Frq+Amp then
if '$DSPExMode' == DSPExAvrSpectrum then
#table := eval vmcol( $($#obj get xdata) , $($#obj get ydata) ) // merge x- and y-data into one table
else
#table := eval vmcol( $($#obj get xdata) , trn($($#obj get ydata)) ) // merge x- and transposed y-data into one table
end
end

// copy / save if table exists
if $#table[?] == table then
// select target
if $#i == 0 then
#file := set clipboard // set target to "clipboard" for all copy_xxx functions
else
#file := butil filedialog save; Select Output File; ; CSV=CSV-File; TXT=Textfile // use filedialog to select the output file
end

// use the CON-object to copy/save table
if '$#file' != '' con savedata text; $#table; $#file; 0; comma; dot
delete $#table
end

// process Control-I (INFO) || Control-M (MAX-MEAN) keys
else if $(#i := keyword '$#msgid$#msgpar' keyCI keyCM) >= 0 then

// get xgraph-object displayed in row 0
#obj := $#obj graph 0;inst

// save original graph title
if '$GraphTitle' == '' GraphTitle := $#obj get title

if $#i == 0 then
// get and display cursor positions
readstr '$($#obj get cursorposition)' #i1 #x1 #y1 #i2 #x2 #y2 #
#text := format 'Index = %d .. %d, X = %g ... %g (%g), Y = %g ... %g (%g)' $#i1 $#i2 $#x1 $#x2 abs($#x1-$#x2) $#y1 $#y2 abs($#y1-$#y2)
else
// set cursor mode (on), style (crosshair), rubberline (off), bind-mode (off), bind-functionindex (0)
$#obj set cursormode on crosshair off off 0
// get x- and y-data
#x := $#obj get xdata
#y := $#obj get ydata
// find index of maximum y value
#imax := eval imax($#y[*,0])
// compute mean of x and y
#xavr := eval avr($#x)
#yavr := eval avr($#y)
// set cursor 1 to maximum and cursor 2 to mean
$#obj set cursorpos 1 $#x[$#imax] $#y[$#imax] deselect
$#obj set cursorpos 2 $#xavr $#yavr deselect
// show maximum and mean in xgraph title
#text := format 'Maximum( %g , %g ), Average( %g , %g )' $#x[$#imax] $#y[$#imax] $#xavr $#yavr
end
// show info in graph title
$#obj set title $GraphTitle -- $#text

end

// note: the return value of the callback function is not used by the xplot/xgraph message handler
exit

//-------------------------------------------------------------------------------------------------
//
// DSPExLib Implements a set of signal processing functions which can be called with
// "DSPLIBEXAMPLE functionname functionarguments". This call style is often
// used to reduce the number of macros of a script or application.
//
// Functions:
//
// DSPEXLIB GETSEGMENTS
// result: a list of all segments selected in the DataSet view stored in a simple
// table (per line: 'setReference ; segmentId ; channelIndex')
// note: this function shows an error message and terminates the caller if no segments
// are selected
//
// DSPEXLIB AVERAGESPECTRUM wave ; wtyp ; atyp
// wave prepared xwave object
// wtyp type of window function: HANNING, HAMMING, KAISER, ...
// atyp type of output spectrum: LOGARITHMIC (=DB), POWER, LINEAR (=AMPLITUDE)
// result: an averaged fft spectrum in the selected format
//
// DSPEXLIB SPECTROGRAM wave ; wtyp ; atyp
// wave prepared xwave object
// wtyp type of window function: HANNING, HAMMING, KAISER, ...
// atyp type of output spectrum: LOGARITHMIC (=DB), POWER, LINEAR (=AMPLITUDE)
// or COMPLEX
// result: a matrix of fft spectra in the selected format, one spectrum per line
//
// DSPEXLIB FREQUENCYSCALE sr ; n ; type
// sr sampling rate in Hz
// n number of spectrum bins (equally spaced in the Hz domain)
// type type of frequency scale: HZ, KHZ, BARK, MEL, ERB
// result: 'frq unit df'; frq is the frequency scale vector, unit is the frequency unit
// name and df is the frequency scale step in Hz
//
// DSPEXLIB AMPLITUDESCALE type
// type type of amplitude scale: LOGARITHMIC (=DB), POWER, LINEAR (=AMPLITUDE)
// result: 'name unit df'; name and unit of amplitude scale
//
//-------------------------------------------------------------------------------------------------
[Macro DSPExLib]

// function call dispatching
readvar #argv #fun #argv /d
goto fun$#fun noFun

noFun:
// function not implemented
// result: empty string

// show an error message and exit
con log '$#mac function "$#fun" not implemented'
exit 1 set ''

//-------------------------------------------------------------------------------------------------
funGetSegments: // in:
// out: segment_list_table
//-------------------------------------------------------------------------------------------------
// retrieve list of selected segments from the DataSet application
#segments := datasetcmd getselected segments
if '$#segments[?]' == table && '$#segments[]' > 0 exit 1 set $#segments
butil msgbox msg ; no segments selected - select and try again; Error!
if '$#segments[?]' == table delete $#segments
exit 2 set '' // terminate this and the calling macro!

//-------------------------------------------------------------------------------------------------
funAverageSpectrum: // in: xwaveobject ; windowtype ; amplitudescale
// out: averagespectrum_vector
//-------------------------------------------------------------------------------------------------
// parse arguments
readvar #argv #wave';'#wtyp';'#atyp';'#

// show init message
con log $#mac $(upper '$#fun') - initializing

// create window
#w := gosub makewindow $($#wave framelength) $#wtyp

// create result table
#spg := new table *

// compute averaged amplitude spectrum
#n := $($#wave framecount)
$#spg := eval cr2len ( fft ( $($#wave read) ?* $#w ) )
for #i := 1 to $#i < $#n step #i := int $#i+1
if $#i%10 == 0 con logext 0; $#mac $(upper '$#fun') - $#i of $#n frames processed
$#spg := eval cr2len ( fft ( $($#wave read) ?* $#w ) ) + $#spg
end
$#spg := eval $#spg / $#n

// convert to selected output spectrum type
if $(#atyp := keyword '$#atyp' dB logarithmic power amplitude linear) < 2 then
$#spg := eval lin2log($#spg , $($#wave aref), 20)
else if $#atyp == 2 then
$#spg := eval $#spg ?^ 2
end

// show end message
con logext 0; $#mac $(upper '$#fun') - finished ($#n spectra computed)

// return averaged spectrum
exit 1 set $#spg

//-------------------------------------------------------------------------------------------------
funSpectrogram: // in: xwaveobject ; windowtype ; amplitudescale
// out: spectrogram_matrix
//-------------------------------------------------------------------------------------------------
// parse arguments
readvar #argv #wave';'#wtyp';'#atyp';'#

// show init message
con log $#mac $(upper '$#fun') - initializing

// create window
#w := gosub makewindow $($#wave framelength) $#wtyp

// check selected output spectrum type
if $(#atyp := keyword '$#wtyp' dB logarithmic power amplitude linear complex) < 5 then
// compute amplitude or power spectra

// create result table (one spectrum per line)
#spg := new table * * num:x:$(int $($#wave fftlength)/2 + 1) /p
// compute amplitude spectra
#n := $($#wave framecount)
for #i := 0 to $#i < $#n step #i := int $#i+1
if $#i%10 == 0 con logext 0; $#mac $(upper '$#fun') - $#i of $#n frames processed
$#spg[$#i,*] := eval cr2len ( fft ( $($#wave read) ?* $#w ) )
end
// convert to selected output spectrum type
if $(#atyp := keyword '$#atyp' dB logarithmic power amplitude linear) < 2 then
$#spg := eval lin2log($#spg , $($#wave aref), 20)
else if $#atyp == 2 then
$#spg := eval $#spg ?^ 2
end

else
// compute complex spectra

// create result table (one spectrum per line)
#spg := new table * * num:x:$(int $($#wave fftlength) + 2) /p
// compute complex spectra
for #i := int $($#wave framecount) to $#i > 0 step #i := int $#i-1
if $#i%50 == 0 con logext 0; $#mac $(upper '$#fun') - $#i of $#n frames processed
$#spg[$#i,*] := eval fft ( $($#wave read) ?* $#w )
end

end

// show end message
con logext 0; $#mac $(upper '$#fun') - finished ($#n spectra computed)

// return spectrogram matrix
exit 1 set $#spg

//-------------------------------------------------------------------------------------------------
funFrequencyScale: // in: samplingrate ; spectrumbins ; frequencyscale
// out: frequencyscale_vector frequencyscale_unit frequency_resolution_Hz
//-------------------------------------------------------------------------------------------------
// parse arguments
readvar #argv #sr';'#n';'#unit';'#
// generate frequency scale equally spaced in Hz
#frq := new table * // dummy table to make frq-scale permanent
$#frq := eval fill($#n, 0, $(#df := eval $#sr / 2 / ($#n - 1)) )
// convert to selected scale
if $(#unit := keyword '$#unit' Hz kHz Bark Mel ERB) < 0 #unit := 0
if $(#unit := word $#unit Hz kHz Bark Mel ERB) == kHz then
$#frq := eval $#frq / 1000
else if $#unit != Hz then
$#frq := eval hz2$#unit($#frq)
end
// return scale settings
exit 1 set '$#frq $#unit $#df'

//-------------------------------------------------------------------------------------------------
funAmplitudeScale: // in: amplitudescale
// out: amplitudescale_text amplitudescale_unit
//-------------------------------------------------------------------------------------------------
// parse arguments
readvar #argv #unit';'#
// get text and unit of amplitude scale
if $(#i := keyword '$#unit' dB logarithmic power amplitude linear) < 2 #i := 0
#unit := word $#i dB dB - - -
#text := word $#i amplitude amplitude power amplitude amplitude
exit 1 set '$#text $#unit'

//
// local subroutines
//

makeWindow:
// GOSUB MAKEWINDOW windowlength windowtype -> windowvector
readvar #argv #wlen #wtyp #
#list := hanning hamming blackman kaiser bartlett taprect nuttall flattop gauss
if $(#wtyp := keyword '$#wtyp' $#list) < 0 #wtyp := 0
exit 1 eval window($#wtyp, $#wlen, 1) * 2 / $#wlen
</pre>

Programmer Guide/Macro Library/XPlot

2014-05-20T12:31:45Z

Admin:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}

{{TOC limit|3}}

==XPlot : CObjEx==

A general class for plotting multiple graphs.

====XPlot Construction====

Initialize a new XPlot-instance to display 1 or more graphs. Returns the new object or an empty string. Information and error messages are written to the <code>BSCRIPT CON</code> console.

=====Usage:=====

<code>XPlot <var>rows</var>=1 ; <var>columns</var>=1 ; <var>title</var> ; <var>profile</var> ; <var>window</var> ; <var>owner</var></code>

=====Parameters:=====

;<var>rows</var>

:The number of rows (default=<code>1</code>).

;<var>columns</var>

:The number of columns for each row (inrow0 inrow1 ...). The default is one column per row.

;<var>title</var>

:The display window title.

;<var>profile</var>

:The name of the graphics profile to use. A graphics profile is also known as a colour scheme.

;<var>window</var>

:The window position and size (in the format '<code>x y width height</code>').

;<var>owner</var>

:The id of an existing display item which should own this new window. See <code>NEW DISPLAY</code> for details.

=====Result:=====

A new <code>XPlot</code> object if successful or an empty string.

=====Examples:=====

The simplest way to create an <code>XPlot</code> instance with one graph is as follows:

<pre>
#xplot := xplot
if '$#xplot[?]' != 'instance' em -1 ; Failed to create the xplot instance
</pre>
====XPlot Member Functions====

The <code>XPLOT</code> class has the following member functions. See CObjEx Member Functions for a list of functions implemented in the parent class.

===AddPlot===

The <code>XPLOT</code> function <code>AddPlot</code> is a lot like <code>Plot</code>, but the functions are plotted in an existing graph (in addition to or on top of the original plot). If no graph exists at the specified <var>adr</var>, then the call is passed to <code>Plot</code>.

======XYPLOT======

Add an x/y plot to an existing plot as defined by <var>adr</var>. For example, plot a function over an existing spectrogram.

=====Usage:=====

<code><var>xplot</var> AddPlot <var>adr</var> ; XYPLOT ; <var>y</var> ; <var>x</var> ; <var>title</var> ; <var>xr</var> ; <var>xu</var> ; <var>xt</var> ; <var>yr</var> ; <var>yu</var> ; <var>yt</var> ; <var>fstyles</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

See [[#Plot|PLOT]] for parameter details.

=====Result:=====

Return <code>0</code> if successful.

======FUNCTION======

Add an x/y plot to an existing plot as defined by <var>adr</var>. For example, plot a function over an existing spectrogram.

=====Usage:=====

<code><var>xplot</var> AddPlot <var>adr</var> ; FUNCTION ; <var>y</var> ; <var>x</var> ; <var>title</var> ; <var>xr</var> ; <var>xu</var> ; <var>xt</var> ; <var>yr</var> ; <var>yu</var> ; <var>yt</var> ; <var>fstyles</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

See [[#Plot|PLOT]] for parameter details.

=====Result:=====

Return <code>0</code> if successful.

======PARAMETER======

Plot a parameter function in an existing graph.

=====Usage:=====

<code><var>xplot</var> AddPlot <var>adr</var> ; PARAMETER ; <var>y ; title ; xr ; xu ; xt ; yr ; yu ; yt ; fstyles</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

See the <code>XYPLOT</code> for parameter details.

=====Result:=====

Return <code>0</code> if successful.

===Dialog===

The function <code>Dialog</code> can be used to show and hide a dialog in the <code>XPlot</code> display.

=====Usage:=====

<code><var>inst</var> Dialog <var>cmd</var> ; <var>args</var></code>

=====Parameters:=====

;<var>cmd</var>

:See below for details.

;<var>args</var>

:See below for details.

=====Result:=====

The ID of the current or new dialog item or an empty string.

======New======

Creates a new dialog item (deleting the old one first).

=====Usage:=====

<code><var>inst</var> Dialog New</code>

======Delete======

Removes the dialog from the display and deletes the dialog item.

=====Usage:=====

<code><var>inst</var> Dialog Delete</code>

======Msg======

Posts a message to the macro message queue. The format of the message is:

<code>MENU</code> <var>dialogItem</var> <var>msgId</var> <var>msgPar</var>

Note that when the display is closed, this function is called to post the message <code>MENU dialogItem CLOSE</code> to the dialog item.

=====Usage:=====

<code><var>inst</var> Dialog Msg ; <var>pos</var> ; <var>msgid</var> <var>msgpar</var></code>

=====Parameters:=====

;<var>pos</var>

:Sets the position of the dialog within the display. The following values are supported:

:<code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code>

;<var>msgid</var>

:The message ID.

;<var>msgpar</var>

:The message parameters.

======On|Enabled======

Show the dialog and set it's position.

=====Usage:=====

<code><var>inst</var> Dialog On; <var>pos</var></code>

<code><var>inst</var> Dialog Enabled; <var>pos</var></code>

=====Parameters:=====

;<var>pos</var>

:Sets the position of the dialog within the display. The following values are supported:

:<code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code>

======Off|Hidden======

Show the dialog and set it's position.

=====Usage:=====

<code><var>inst</var> Dialog Off ; <var>pos</var></code>

<code><var>inst</var> Dialog Hidden ; <var>pos</var></code>

=====Parameters:=====

;<var>pos</var>

:Sets the position of the dialog within the display. The following values are supported:

:<code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code>

===Display===

Returns the ID of the display object associated with this <code>XPLOT</code> instance.

=====Usage:=====

<code><var>inst</var> display</code>

=====Result:=====

Returns the display object of the <code>XPLOT</code> instance.

===End===

Enters the message loop, waits until the user closes the plot display and then destroys itself.

===Get===

Retrieve an attribute from a specific graph.

=====Usage:=====

<code><var>xplot</var> Get <var>adr</var> ; <var>attribute</var></code>

=====Parameters:=====

;<var>adr</var>

:The address of the display splitter (see member function <code>Graph</code> for detail).

;<var>attribute</var>

:The id of the requested attribute. The following values are supported:

:<code>CURSORPOSITION</code> - Returns the current cursor positions in the following format: <code>i1 x1 y1 i2 x2 y2</code>

:Note that <code>x1 <= x2</code>

:<code>YDATA</code> - Returns the y data item.

:<code>XDATA</code> - Returns the x data item.

:<code>RANGE</code> - Returns the x axis and y axis range in the following format: <code>xmin xmax ymin ymax</code>

:<code>TYPE</code> - Returns the plot type (see <code>Plot</code> for a list of available plot types).

===GetFColors===

The <code>GetFColors</code> function returns a blank separated list of the function colors defined in the selected graphics profile.

=====Usage:=====

<code><var>xplot</var> GetFColors</code>

=====Result:=====

Returns a blank separated list of color keywords.

===Graph===

Returns the requested attribute <var>attr</var> of the graph identified by <var>adr</var>.

=====Usage:=====

<code><var>xplot</var> Graph <var>adr</var> [; <var>attr</var>=GRAPH ]</code>

=====Parameters:=====

;<var>adr</var>

:The id of a graph item, an <code>[[Programmer Guide/Class Library/XGraph : CObjEx|XGRAPH]]</code> instance or the '<code>row column</code>' address of a splitter in the display. Note that the <code>row</code> and <code>column</code> indices are zero-based.

;<var>attr</var>

:The attribute to returned. The following values are allowed:

:<code>INSTANCE</code> - Return the id of the <code>XGRAPH</code> instance associated with <var>adr</var>.

:<code>GRAPH</code> - Return the id of the graph object associated with <var>adr</var>. This is the default attribute.

:<code>ROW</code> - Return the row index of the splitter associated with <var>adr</var>.

:<code>COLUMN</code> - Return the column index of the splitter associated with <var>adr</var>.

=====Result:=====

Return values are selected by the argument <var>attr</var>. See the description of <var>attr</var> for details. If the address argument <var>adr</var> do not refer to a graph, <code>XGRAPH</code> or splitter of the display, an empty string is returned.

=====Examples:=====

Get the graph item id for the top left graph.

<pre>
#graph := $#xplot graph 0 0
</pre>
===Legend===

Display a graph legend. Use <code>$#xplot LEGEND $#graph</code> to clear the legend.

=====Usage:=====

<code><var>xplot</var> Legend <var>graph</var> ; <var>unit</var> ; <var>x</var> ; <var>y</var> ; <var>w</var> ; <var>h</var> ; <var>color</var> ; <var>info</var> ; <var>text1</var> ; <var>text2</var> ; <var>textX</var></code>

=====Parameters:=====

;<var>graph</var>

:The graph address (e.g. row and column index. See [[#Plot|PLOT]] for detail).

;<var>unit</var>

:The unit for size and position values. The following values are supported:

:<code>real</code> - The real x/y values.

:<code>%</code> or <code>percent</code> - The percent of the graph's plot area.

;<var>x, y</var>

:The position of the upper right corner of the first legend line.

;<var>w, h</var>

:The width and height of one legend line.

;<var>color</var>

:The legend text color.

;<var>info</var>

:This flag selects the line attributes to be displayed. The following values are supported:

:<code>color</code> - The color.

:<code>all</code> - The color, style, width and symbol.

;<var>textX</var>

:The text for the legend for function X. If no text is supplied, the legend line is removed.This parameter can be either a string, or a simple table.

=====Result:=====

void

===Plot===

The <code>XPlot</code> function <code>Plot</code> can be used to plot a function in a graph. Currently, {{STX}} supports waveform , x/y (aka function and more specifically parameter), spectrogram and waterfall plots.

======XYPLOT======

Plot an x/y function graph.

=====Usage:=====

<code><var>xplot</var> Plot <var>adr</var> ; XYPLOT ; <var>y</var> ; <var>x</var> ; <var>title</var> ; <var>xr</var> ; <var>xu</var> ; <var>xt</var> ; <var>yr</var> ; <var>yu</var> ; <var>yt</var> ; <var>fstyles</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

;<var>adr</var>

:The address of the display splitter (see the member function Graph for details).

;<var>y</var>

:The y axis data (a vector or an array).

;<var>x</var>

:The data to be used for the x axis. This can be one of the following:

:A data vector with <code>y[!nrow]</code> values and 1 column.

:<code>*</code> - An asterisk. This is the default and means that the x axis uses the values <code>0</code> through to <code>y[!nrow]-1</code>.

:A blank separated list of values ('x1 x2' -> x[i] = x1+(x2-x1)/(y[!nrow]-1), i = 0..<code>y[!nrow]-1</code>).

;<var>title</var>

:The title to be displayed in this plot.

;<var>xr</var>

:The x axis display range. This can be one of the following values:

:<code>*</code> - An asterisk - an automatic scale is generated.

:<code>xmin xmax</code> - Two numerical values - the minimum and maximum values.

;<var>xu</var>

:The text describing the x axis unit (e.g. <code>seconds</code>). The default is an empty string.

:The <code>WAVEFORM</code> plot only allows the following values: <code>SAMPLES</code>|<code>MS</code>|<code>S</code>. The default is <code>S</code>.

;<var>xt</var>

:The title to be used for the x axis. The default is an empty string.

;<var>yr</var>

:The y axis display range. This can be one of the following:

:<code>*</code> - An asterisk - an automatic scale is generated.

:<code>ymin ymax</code> - Two numerical values - the minimum and maximum values.

;<var>yu</var>

:The text describing the y axis unit (e.g. <code>dB</code>).

;<var>yt</var>

:The title to be used for the y axis. The default is an empty string.

;<var>fstyles</var>

:An <code>fstyle</code> argument (see <code>fstyle</code> for details) or a zero-based function line index as specified in a color scheme (see Color Schemes in the User Guide).

;<var>xlabtab, ylabtab, zlabtab</var>

:Extended tables containing the scale, grid and label definitions. For a description of the table format, please see the scale definition table for details.

=====Result:=====

Return <code>0</code> if successful.

=====Examples:=====

Plot a simple x/y function.

<pre>
#xplot := XPLOT 1 ; 1 ; XPLOT ; Default ; 0 0 400 400
$#xplot plot 0 ; XYPLOT; $(eval fill(10, 0, 1)) ; * ; xyplot ; * ; ; x-axis ; * ; ; y-axis
</pre>
======FUNCTION======

Plot a function graph. Note that this is identical to an <code>XYPLOT</code>.

=====Usage:=====

<code><var>xplot</var> Plot <var>adr</var> ; FUNCTION ; <var>y ; x ; title ; xr ; xu ; xt ; yr ; yu ; yt ; fstyles</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

See <code>XYPLOT</code> for parameter descriptions.

=====Result:=====

Return <code>0</code> if successful.

======parameter======

Plot a parameter graph. A parameter graph differs from a function graph because a parameter plot can have missing values - it does not necessarily have values for every point on the x axis.

=====Usage:=====

<code><var>xplot</var> Plot <var>adr</var> ; parameter ; <var>y ; title ; xr ; xu ; xt ; yr ; yu ; yt ; fstyles</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

See the <code>xyplot</code> for parameter details.

=====Result:=====

Return <code>0</code> if successful.

======spectrogram======

Plot a spectrogram graph.

=====Usage:=====

<code><var>xplot</var> plot <var>adr</var> ; spectrogram ; <var>d</var> ; <var>y</var> ; <var>title</var> ; <var>xr</var> ; <var>xu</var> ; <var>xt</var> ; <var>yr</var> ; <var>yu</var> ; <var>yt</var> ; <var>zr</var> ; <var>xlabtab</var> ; <var>ylabtab</var></code>

=====Parameters:=====

;<var>d</var>

:A data array containing one spectrum or function line per <var>y</var> row. Note that this parameter is specific to the <code>SPECTROGRAM</code> and <code>WATERFALL</code> plots.

;<var>y</var>

:The y-scale data (frequency). This can be one of the following:

:1) <code>vData</code> - A data vector with <code>y[!ncol]</code> values and 1 column.

:2) * - An asterisk: <code>y[i] = i</code>, <code>i = 0..d[!ncol]-1</code>. This is the default.

:3) <code>y1 y2</code> - Two blank separated values: <code>y[i] = y1+i*(y2-y1)/(d[!ncol]-1)</code>, <code>i = 0..d[!ncol]-1</code>.

;<var>zr</var>

:The z scale is a color scale. The following values are supported:

:<code>*</code> - An asterisk. The range is automatically generated.

:<code>zmin zmax</code> - Two numerical values specifying the minimum and maximum z axis values.

:<code>zdown</code> - A numerical value. The maximum z value is chosen automatically and the minimum value is calculated as follows: <code>zmax-zdown</code>.

For all other parameters, see <code>xyplot</code> for descriptions.

======WATERFALL======

Plot a waterfall graph.

=====Usage:=====

<code><var>xplot</var> PLOT <var>adr</var> ; WATERFALL ; <var>d</var> ; <var>x</var> ; <var>title</var> ; <var>xr</var> ; <var>xu</var> ; <var>xt</var> ; <var>yr</var> ; <var>yu</var> ; <var>yt</var> ; <var>zr</var> ; <var>zu</var> ; <var>zt</var> ; <var>xw</var> ; <var>yw</var> ; <var>n</var> ; <var>xlabtab</var> ; <var>ylabtab</var> ; <var>zlabtab</var></code>

=====Parameters:=====

;<var>d</var>

:The data array (one spectrum or function-line / row).

;<var>zr</var>

:The z axis display range. The following values are supported:

:<code>*</code> - An asterisk. The range is automatically generated.

:<code>zmin zmax</code> - Two numerical values specifying the minimum and maximum z axis values.

;<var>zu</var>

:The text describing the z axis unit (e.g. <code>s</code>).

;<var>zt</var>

:The title to be used for the z axis. The default is an empty string.

;<var>xw</var>

:The relative width of the x scale. A value between <code>-1</code> and <code>1</code>. The default is <code>0.8</code>.

;<var>yw</var>

:The relative width of the y scale. A value between <code>-1</code> and <code>1</code>. The default is <code>0.8</code>.

;<var>n</var>

:The number of lines to be plotted. The default is <code>150</code>.

For all other parameters, see <code>XYPLOT</code> for descriptions.

======WAVEFORM======

Plot a waveform graph. Note that the displayed wave item is automatically attached to the graph. This means, no explicit call to <code>SetWave</code> is necessary.

=====Usage:=====

<code><var>xplot</var> PLOT <var>adr</var> ; WAVEFORM ; <var>wave</var> ; <var>title</var> ; <var>xu</var> ; <var>xt</var> ; <var>ymax</var> ; <var>yr</var> ; <var>yt</var> ; <var>fill</var></code>

=====Parameters:=====

;<var>wave</var>

:A wave item id or an <code>XWAVE</code> instance

;<var>xu</var>

:The unit to use on the x axis. The following values: <code>SAMPLES</code>|<code>MS</code>|<code>S</code>. The default is <code>S</code>.

;<var>ymax</var>

:The maximum waveform amplitude. This can be a value between 0 and ...

;<var>yr</var>

:The y axis display range. This can be any positive number. The default is <code>1</code>.

;<var>fill</var>

:<code>1</code> if the waveform envelope should be filled or <code>0</code>.

For all other parameters, see <code>XYPLOT</code> for descriptions.

======TEXTBOX======

Plot a graph containing text.

=====Usage:=====

<code><var>xplot</var> PLOT <var>adr</var> ; TEXTBOX ; <var>title</var> ; <var>color</var> ; <var>halign</var> ; <var>valign</var> ; <var>text</var></code>

=====Parameters:=====

;<var>title</var>

:The graph title.

;<var>color</var>

:The text color. This can be an of the {{STX}} color arguments.

;<var>halign</var>

:The horizontal text alignment. This can be one of the following values: <code>CENTER</code>|<code>LEFT</code>|<code>RIGHT</code>

;<var>valign</var>

:The vertical text alignment. This can be one of the following values: <code>CENTER</code>|<code>TOP</code>|<code>BOTTOM</code>

;<var>text</var>

:The text to be displayed. This can be a simple table with an entry per line of text or a semi-colon separated list of text lines.

For all other parameters, see <code>XYPLOT</code> for descriptions.

======fstyle======

The <var>fstyle</var> argument passed to the <code>XPlot</code> functions <code>Plot</code> and <code>AddPlot</code> has the following syntax and components:

<code><var>linestyle</var><code>:</code><var>linecol</var><code>:</code><var>printcol</var><code>:</code><var>linewidth</var><code>:</code><var>drawstyle</var><code>:</code><var>drawsym</var><code>:</code><var>ymiss</var></code>

;<var>linestyle</var>

:Determines whether the function line is solid (<code>SOLID</code>), dotted (<code>DOT</code>) or dashed (<code>DASH</code>). The default value is taken from the <code>XPLOT</code> color profile.

;<var>linecol</var>

:The colour to use for the function line on screen. This can be any {{STX}} colour keyword or RGB value. The default value is taken from the <code>XPLOT</code> color profile.

;<var>printcol</var>

:The colour to use for the function line when printing. See <var>linecol</var> for details. The default value is taken from the <code>XPLOT</code> color profile.

;<var>linewidth</var>

:The width of the function line. Possible values are <code>0</code> through to <code>4</code> for lines with the <code>SOLID</code> <var>linestyle</var> and <code>0</code> or <code>1</code> for lines with the <code>DOT</code> or <code>DASH</code> <var>linestyle</var>. The default value is taken from the <code>XPLOT</code> color profile.

;<var>drawstyle</var>

:The style to use to draw the function. Each function point can be plotted separately (<code>POINTS</code>), a line can be drawn between each function point (<code>LINES</code>), the area below the function can be filled with the <var>linecol</var> (<code>AREA</code>), the function points can be joined by steps (<code>STEPS</code> - note that this is only available for the <code>PARAMETER</code> plot) or no points are plotted (<code>NONE</code> - this is best used when a drawing symbol (<var>drawsym</var>) is defined). The default style is <code>LINES</code>.

;<var>drawsym</var>

:The symbol to draw at each point. This can be used in conjunction with a drawing style (see <var>drawstyle</var>). The following keywords are supported:

:<code>NONE</code>|<code>SQUARE</code>|<code>TRIANGLE|CIRCLE|CROSS|DIAMOND</code>

:The default style is <code>NONE</code>.

;<var>ymiss</var>

:The value to use for missing y values. If <var>ymiss</var> is not specified (empty) all values are displayed, otherwise all points where <code>y=</code><var>ymiss</var> are not displayed. If <var>ymiss</var> is not empty and is not a number then <var>ymiss</var> is set to <code>0</code>. If no <var>ymiss</var> is defined, no <var>ymiss</var> is used (this is the default).

===Redraw===

Redraw the selected graph. This is currently only implemented for the <code>FUNCTION</code> (<code>XYPLOT</code>) and <code>PARAMETER</code> plots.

=====Usage:=====

<code><var>xplot</var> REDRAW <var>adr</var></code>

=====Parameters:=====

;<var>adr</var>

:The address of the display splitter (see member function <code>Graph</code> for details).

=====Result:=====

Return 0 if successful.

===ScaleOctave===

Generate a logarithmic scale table for use with the <code>Plot</code> or <code>AddPlot</code> functions. This function can also be called statically.

=====Usage:=====

<code><var>xplot</var> ScaleOctave <var>df</var> <var>count</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code>xplot ScaleOctave <var>df</var> <var>count</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code><var>xplot</var> ScaleOctave <var>vector</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code>xplot ScaleOctave <var>vector</var> ; <var>fmax</var> ; <var>fmin</var></code>

=====Parameters:=====

;<var>df</var>

:The frequency resolution in Hz.

;<var>count</var>

:The number of frequency points.

;<var>fmax</var>

:The maximum frequency to be displayed.

;<var>fmin</var>

:The minimum frequency to be displayed.

;<var>vector</var>

:The scale range as a data vector.

=====Result:=====

The following string is returned:

<code>xmin xmax xlabTab xdata</code>

Where <code>xmin</code> and <code>xmax</code> are is the minimum and maximum of the logarithmic scale, <code>xlabTab</code> is the scale definition table which you can then pass to a <code>Plot</code> function and <code>xdata</code> is the logarithmic frequency values vector. See the scale definition table description in the Command Reference for details of the table syntax.

=====Examples:=====

Create a scale definition table for a logarithmic frequency axis with 2000 points at 10 Hz intervals and a maximum frequency of 10000 Hz.

<pre>
readstr '$(xplot scaleOctave 10 2000; 10000)' #xmin #xmax #xlab #x
</pre>
=====Notes:=====

See also ScaleSteps.

===ScaleLog10===

Generate a logarithmic scale table for use with the <code>Plot</code> or <code>AddPlot</code> functions. This function can also be called statically.

=====Usage:=====

<code><var>xplot</var> ScaleLog10 <var>df</var> <var>count</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code>xplot ScaleLog10 <var>df</var> <var>count</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code><var>xplot</var> ScaleLog10 <var>vector</var> ; <var>fmax</var> ; <var>fmin</var></code>

<code>xplot ScaleLog10 <var>vector</var> ; <var>fmax</var> ; <var>fmin</var></code>

=====Parameters:=====

;<var>df</var>

:The frequency resolution in Hz.

;<var>count</var>

:The number of frequency points.

;<var>fmax</var>

:The maximum frequency to be displayed.

;<var>fmin</var>

:The minimum frequency to be displayed.

;<var>vector</var>

:The scale range as a data vector.

=====Result:=====

The following string is returned:

<code>xmin xmax xlabTab xdata</code>

Where <code>xmin</code> and <code>xmax</code> are is the minimum and maximum of the logarithmic scale, <code>xlabTab</code> is the scale definition table which you can then pass to a <code>Plot</code> function and <code>xdata</code> is the logarithmic frequency values vector. See the scale definition table description in the Command Reference for details of the table syntax.

=====Notes:=====

See also <code>ScaleSteps</code> and <code>ScaleOctave</code>.

===ScaleSteps===

Generate a linear scale table for use with the <code>Plot</code> or <code>AddPlot</code> functions. This function can also be called statically, e.g. '<code>xplot ScaleSteps -70 -10 ; 10 ; 5 ; 5 ; 1 ; 1</code>'.

=====Usage:=====

<code><var>inst</var> ScaleSteps <var>min</var> <var>max</var> ; <var>labelDist</var> ; <var>majorGridDist</var> ; <var>majorTickDist</var> ; <var>minorGridDist</var> ; <var>minorTickDist</var></code>

<code>xplot ScaleSteps <var>min</var> <var>max</var> ; <var>labelDist</var>; <var>majorGridDist</var>; <var>majorTickDist</var> ; <var>minorGridDist</var> ; <var>minorTickDist</var></code>

<code><var>inst</var> ScaleSteps <var>vector</var> ; <var>labelDist</var>; <var>majorGridDist</var>; <var>majorTickDist</var> ; <var>minorGridDist</var> ; <var>minorTickDist</var></code>

<code>xplot ScaleSteps <var>vector</var> ; <var>labelDist</var>; <var>majorGridDist</var>; <var>majorTickDist</var> ; <var>minorGridDist</var> ; <var>minorTickDist</var></code>

=====Parameters:=====

;<var>min, max</var>

:The scale range.

;<var>vector</var>

:The scale range as a data vector.

;<var>labelDist</var>

:The label distance in scale units.

;<var>majorGridDist</var>

:The distance of the major grid lines in scale units.

;<var>majorTickDist</var>

:The distance between major ticks in scale units.

;<var>minorGridDist</var>

:The distance of the minor grid lines in scale units.

;<var>minorTickDist</var>

:The distance between minor ticks in scale units.

=====Result:=====

The following string is returned:

<code>min max labTab</code>

Where <code>min</code> and <code>max</code> are is the computed or corrected scale range and <code>labTab</code> is the scale definition table which you can then pass to a <code>Plot</code> function. See the scale definition table description in the Command Reference for details of the table syntax.

=====Examples:=====

Calculate the linear scale, grid and labels for an amplitude axis between -70 and -10 dB with labels every 10 dB, major grid lines and ticks every 5dB and minor grid lines and ticks every dB.

<pre>
readstr '$($#xplot ScaleSteps -70 -10 ; 10 ; 5 ; 5 ; 1 ; 1)' #ymin #ymax #ylab
</pre>
=====Notes:=====

See also <code>ScaleOctave</code> and <code>ScaleLog10</code>.

===Set===

The <code>Set</code> function sets the cursor mode and text attributes.

=====Usage:=====

<code><var>xplot</var> Set [ <var>graph</var>|* ; ] <var>attr</var> <var>args</var></code>

=====Parameters:=====

;<var>xgraph</var>

:An xgraph instance on which to call the <code>Set</code> command. If no graph is specified or an asterisk, then the <code>Set</code> command is carried out on all graphs.

;<var>attr</var>

:One of the following values:

:<code>cursormode</code> - turn cursors on and off and change the way they look.

:<code>xunit</code> - the name of the x-axis unit

:<code>yunit</code> - the name of the y-axis unit

:<code>xtext</code> - the description of the x-axis

:<code>ytext</code> - the description of the y-axis

:<code>title</code> - the graph's title

;<var>args</var>

:The value of <var>args</var> depends on <var>attr</var>.

:If <var>attr</var> is <code>cursormode</code>, then <var>args</var> is as follows:

:<code>mode|* type|* line|*</code>

:Where mode is one of the following values:

:<code>on</code> - show the cursor

:<code>off</code> - hide the cursor

:Where <var>type</var> is one of the following values:

:<code>cross</code>|<code>crosshair</code>|<code>vbarcross</code>|<code>harmonic</code>

:And <code>line</code> is one of the following values:

:<code>off</code> |<code>on</code>

:If <var>attr</var> is not <code>cursormode</code>, then <var>args</var> is used as the text, unit or title.

=====Result:=====

No return value.

===SetCallback===

The callback function is called by the message handlers to process popup and context menu messages and hotkeys which are not used by <code>XPLOT</code> or <code>XGRAPH</code>. The following commands are used to call the callback function:

If called from an <code>XGRAPH</code> message handler:

<code>cbfunction xgraphinstance irow icol msgid msgpar</code>

If called from the <code>XPLOT</code> message handler:

<code>cbfunction xplotinstance * * msgid msgpar</code>

=====Usage:=====

<code><var>xplot</var> SetCallback [ <var>cbfunction</var> ]</code>

=====Parameters:=====

;<var>cbfunction</var>

:The name of the callback function or an empty string to remove a previous association.

=====Result:=====

No return value.

===SetWave===

Attach a signal to one graph or all graphs (see <var>adr</var>). If a wave item is attached to a graph, it can not be deleted before it is detached or the graph or <code>XPLOT</code> instance is deleted.

=====Usage:=====

<code><var>xplot</var> SetWave [ <var>waveitem</var> ]</code>

<code><var>xplot</var> SetWave <var>adr</var> ; [ <var>waveitem</var> ]</code>

=====Parameters:=====

;<var>adr</var>

:The address of the display splitter (see member function Graph for details). If this parameter is omitted, then the wave item is set for all graphs.

;<var>waveitem</var>

:A wave item id or an <code>[[Programmer Guide/Class Library/XWave : CObjEx|XWAVE]]</code> instance (or empty to remove attachment).

=====Result:=====

Return <code>0</code> if successful.

Note that wave items can only be attached to graphs of type <code>FUNCTION</code>, <code>XYPLOT</code>, <code>PARAMETER</code>, <code>SPECTROGRAM</code> and <code>WAVEFORM</code>.====XPlot Hotkeys====

The following hotkeys are implemented in the <code>XPLOT</code> class:

{|
|-
|C
|Turn the cursors on and off.
|-
|S
|Change to the next cursor style.
|-
|B
|Turn cursor binding on and off.
|-
|Ctrl+N
|Bind the cursor to the next function.
|-
|Ctrl+P
|Bind the cursor to the previous function.
|-
|R
|Turn the cursor rubberline on and off.
|-
|T
|Turn the title on and off.
|-
|X
|Change to the next x<nowiki>-</nowiki>scale mode.
|-
|Y
|Change to the next y<nowiki>-</nowiki>scale mode.
|-
|Z
|Change to the next z<nowiki>-</nowiki>scale mode.
|-
|Space
|Open the setup dialog.
|-
|P
|Play the attached wave (between the cursors).
|-
|Q
|Play the attached wave (the whole signal).
|-
|ESC
|Stop playback.
|-
|Ins
|Show the selected metasegment's settings in a dialog or, if no metasegment is selected, show a dialog to create a new metasegment.
|-
|Del
|Delete the selected metasegments.
|-
|Ctrl+Left Click
|Move the legend to the clicked position.
|-
|Shift+Left Click
|Create a metasegment at the clicked position (show the 'Insert Metasegment' dialog).
|}

====XPlot Examples====

=====Simple XPLOT Example=====

The following example demonstrates simple <code>[[Programmer Guide/Class Library/XPlot : CObjEx|XPLOT]]</code> usage.

<pre>
[macro xplot_example_1]
//
// create display (and graph)
//
#xplot := xplot 2 ; 1 ; xplot ; default ; 100 100 800 800
if '$#xplot[?]' != 'instance' em -1 ; xplot creation failed ($emsg)
//
// plot graphs (including data generation)
//
#nValues := 100
$#xplot Plot 0 0 ; XYPLOT ; $(eval fill($#nValues,1,1)) ; * ; Graph Title ; * ; x unit ; x title ; * ; y unit ; y title ; solid:green::1
$#xplot Plot 1 0 ; SPECTROGRAM ; $(eval rand(1,100,100)) ; * ; Graph Title ; * ; x unit ; x title ; * ; y unit ; y title ; solid:green::1
//
// clean up
//
// the clean up takes place automatically
// when the plot window is closed
exit
</pre>
=====Plot rows of a matrix using XPLOT=====

The following example demonstrates how to plot the rows of a matrix using the <code>[[Programmer Guide/Class Library/XPlot : CObjEx|XPLOT]]</code> class.

<pre>
//{{3.9 6473}{2009.01.29 16.44.04} - automatically created version information - do not change or delete this line}

[macro xplot_example_2]

//
// This row demonstrates how to plot each row of a matrix
//
// C.G. 29.1.2009
//

//
// create display (and graph)
//

#xplot := xplot 1 ; 1 ; xplot ; default ; 100 100 800 800
if '$#xplot[?]' != 'instance' em -1 ; xplot creation failed ($emsg)

//
// create a matrix and fill it with some meaningless data
//

#mat := new table * /Parameter * number:X:100
if '$#mat[?]' != table em -1 ; cannot create table ($emsg)

for #i := 0 to $#i < 10 step #i := int $#i + 1
$#mat[$#i,*] := eval fill( 100, $#i+1, $#i+1 )
end

//
// plot each row of the matrix
//

for #i := int 0 to $#i < $#mat[!nrow] step #i := int $#i + 1
#x := eval $#mat[$#i,*]
$#xplot AddPlot 0 0 ; XYPLOT ; $#x ; * ; row-by-row plot ; * ; x unit ; x title ; * ; y unit ; y title ; solid:green::1
end

exit 1 int 0
</pre>

=====Advanced XPLOT Example=====

This example not only demonstrates the use of the <code>XPLOT</code> class, but also signal processing using the <code>EVAL</code> function.

<pre>
//=================================================================================================
//
// DSP Examples
//
// last update: Nov 17, 2007 (AN)
// {{STX}} version: {{STX}} 3.8 Beta
//
// The examples in this file demonstrates how to ...
// ... use the EVAL command for signal processing
// ... use the class XWAVE to read a signal frame by frame
// ... display spectrograms, waveforms and functions in XPLOT graphs
// ... enable XPLOT to play signals
// ... use the XPLOT callback function to implement simple user controls
// ... set and get cursor attritbutes and positions of XPLOT graphs
// ... add a legend to a XPLOT graph
// ... use BUTIL MSGBOX for simple dialogs
// ... use the CON object (class BScript) to display log. messages
// ... use the CON object to save numeric tables to textfiles
// ... simulate item messages using the message queue macro MSGQUEUE
// ... implement and call local subroutines
//
//=================================================================================================

//-------------------------------------------------------------------------------------------------
//
// DSPExAvrSpectrum Create a plot containing the average spectra of all segments selected
// in the DataSet view.
//
//-------------------------------------------------------------------------------------------------
[Macro DSPExAvrSpectrum #lfrm=100ms';'#sfrm=50%';'#wtyp=hamming';'#ascale=dB';'#fscale=Hz';'#amax=1';'#aref=1';'#]
// arguments: #lfrm frame length, absolute time expression
// #sfrm frame shift, relative time expression
// #wtyp window type, {Hanning, Hamming, ...)
// #fscale spectrogram frequency scale unit (Hz, kHz, Bark, Mel, ERB)
// #amax calibration factor or CALSET to use a calibration set
// #aref reference amplitude, ignored if #amax equals CALSET

// set mode to macro name (see macro DSPExCallback)
DSPExMode := set '$#mac'

// get segments selected in the DataSet view
#segments := dspexlib getsegments

// create the result table (one spectrum per row)
#asp := new table * * num:x:$#segments[] /p

// segment analysis loop
#nok := 0 // number of computed average spectra
for #i := 0 to $#i < $#segments[] step #i := int $#i+1

// get next segment from segment list
readtab $#segments $#i #aset';'#aseg';'#ach';'#
con log process segment "set=$#aset, id=$#aseg, ch=$#ach" ($(int $#i+1) of $#segments[])

// create the wave object and initialize frame settings (mode "centered")
// usage: XWAVE setref ; segmentid ; channel ; mode ; framelength ; frameshift ; ampmax ; ampref
if $(#wave := xwave '$#aset;$#aseg;$#ach;1;$#lfrm;$#sfrm;$#amax;$#aref')[?] != instance then
butil 'msgbox msg; create wave object for segment "$#aset/$#aseg,$#ach" failed; Error!'
continue
// set / check sampling rate
else if '$#srate' == '' then
#srate := $($#wave srate)
else if $($#wave srate) != $#srate then
butil 'msgbox msg; segment "$#aset/$#aseg,$#ach" - sampling rate mismatch; Error!'
$#wave destroy // delete wave object
continue
end

// compute the average spectrum
if $(#tmp := dspexlib averagespectrum $#wave ; $#wtyp ; $#ascale)[?] != table then
butil 'msgbox msg; compute average spectrum of segment "$#aset/$#aseg,$#ach" failed; Error!'
$#wave destroy // delete wave object
continue
end

$#asp[*,$#nok] := $#tmp // save the spectrum
delete $#tmp // delete temp. buffer
#legend := '$#legend $($#wave title);' // add segment to legend string
$#wave destroy // delete wave object
#nok := int $#nok+1 // increment result vector counter

end

// exit if no results are computed
if $#nok < 1 exit

// compute frequency scale vector, unit and frequency resolution
readstr '$(dspexlib frequencyscale $#srate ; $#asp[!nrow] ; $#fscale)' #frq #funit #df

// create and configure the plot object
// usage: XPLOT rows ; cols0 cols1 .. ; windowtitle ; graphicprofile ; wx wy wwidth wheight
#plot := xplot 1; 1; Average Spectrum; Rainbow; 0 0 1024 800

// plot all spectra and display the legend
#title := format 'lfrm=%s, sfrm=%s, wtyp=%s, df=%.3fHz' '$#lfrm' '$#sfrm' '$#wtyp' $#df
readstr '$(dspexlib amplitudescale $#ascale)' #ytext #yunit
// usage: xplot PLOT row col; FUNCTION; ydata; xdata; title; xrange; xunit; xtext; yrange; yunit; yrange
$#plot plot 0; function; $#asp; $#frq; $#title; ; $#funit; frequency; ; $#yunit ; $#ytext
$#plot legend 0; %; 50; 95; 45; 5; black; color; $#legend
$#plot set cursormode on crosshair // set cursor mode and style
$#plot setcallback dspexcallback // assign callback function

// wait until plot window is closed
$#plot end // the xplot object is destroyed automatically when the window is closed

// finished - cleanup and and exit
delete $#asp $#frq $#segments // delete data items
showLogOnExit := 0 // close the bscript log-window automatically
exit

//-------------------------------------------------------------------------------------------------
//
// DSPExSpectrogram Plot a spectrogram of all segments selected in the DataSet view.
// For each segment one spectrogram window is displayed. The window
// must be closed before the next segment is analysed.
//
//-------------------------------------------------------------------------------------------------
[Macro DSPExSpectrogram #lfrm=40ms';'#sfrm=10%';'#wtyp=hamming';'#arange=50';'#fscale=Hz';'#amax=1';'#aref=1';'#]
// arguments: #lfrm frame length, absolute time expression
// #sfrm frame shift, relative time expression
// #wtyp window type, {Hanning, Hamming)
// #arange spectrogram display range in dB (max .. max-range)
// #fscale spectrogram frequency scale unit (Hz, kHz, Bark, Mel, ERB)
// #amax calibration factor or CALSET to use a calibration set
// #aref reference amplitude, ignored if #amax equals CALSET

// set mode variable to macro name (see macro DSPExCallback)
DSPExMode := set '$#mac'

// get segments selected in the DataSet view
#segments := dspexlib getsegments

// segment analysis loop
for #i := 0 to $#i < $#segments[] && '$DSPExMode' != '' step #i := int $#i+1

// get next segment from segment list
readtab $#segments $#i #aset';'#aseg';'#ach';'#

// create the wave object and initialize frame settings (mode "centered")
if $(#wave := xwave '$#aset;$#aseg;$#ach;1;$#lfrm;$#sfrm;$#amax;$#aref')[?] != instance then
butil 'msgbox msg; create wave object for segment "$#aset ; $#aseg ; $#ach" failed; Error!'
continue
end

// compute the spectrogram
if $(#asp := dspexlib spectrogram $#wave ; $#wtyp ; log)[?] != table then
butil 'msgbox msg; compute spectrogram of segment "$#aset ; $#aseg ; $#ach" failed; Error!'
$#wave destroy
continue
end

// compute frequency scale vector, unit and frequency resolution
readstr '$(dspexlib frequencyscale $($#wave srate) ; $#asp[!ncol] ; $#fscale)' #frq #funit #df

// create and configure the plot object
#plot := xplot 2; 1 1; $($#wave title) quit = c-q, next = c-n; Rainbow; 0 0 1024 800
$($#plot display) height 3 1 /apply // set height of graphs

// plot spectrogram and waveform
#title := format 'lfrm=%s, sfrm=%s, wtyp=%s, arange=%s, amax=%.1fdB, df=%.3fHz' '$#lfrm' '$#sfrm' '$#wtyp' '$#arange' $(eval max($#asp)) $#df
$#plot plot 0; spectrogram; $#asp; $#frq; $#title; $($#wave tbegin) $($#wave tend); s; time; ; $#funit; frequency; $#arange
$#plot plot 1; waveform; $#wave; ; s; time; $($#wave amax); $($#wave amax); amplitude; 1
$#plot set cursormode on crosshair // set cursor mode and style
$#plot setcallback dspexcallback // assign callback function

// assign wave object to xplot graphs (for playback)
$#plot setwave $#wave

// wait until plot window is closed
$#plot end // the xplot object is destroyed automatically when the window is closed

// cleanup
delete $#asp $#frq // delete data items
$#wave destroy // delete wave object
end

// finished - cleanup and exit
delete $#segments // delete segment table
showLogOnExit := 0 // close the bscript log-window automatically
exit

//-------------------------------------------------------------------------------------------------
//
// DSPExCallback Callback function for XPLOT.
//
// arguments:
// if called from xplotobject message handler -> 'CALLBACK xplotobject * * msgid msgpar'
// if called from xgraphobject message handler -> 'CALLBACK xgraphobject row col msgid msgpar'
//
// Note: This macro uses the shell variable DSPEXMODE to check which macro has installed the
// callback and to set return values.
//
//-------------------------------------------------------------------------------------------------
[Macro DSPExCallback #obj #row #col #msgid #msgpar]

// get xplot-object if called from a xgraph-object
if '$#obj[!class]' == xgraph #obj := $#obj get xplot

// message filter for keystroke messages

// process Control-Q (QUIT) key
if '$#msgid$#msgpar' == keyCQ then

if $(butil msgbox yesno; Quit ?; $DSPExMode) == yes then
// place the display-close message in the message queue to end the xplot message loop
msgqueue 'display $($#obj display) close'
// set mode variable to empty-string if C-Q key was pressed
DSPExMode := ''
end

// process Control-C (COPY) and Control-S (SAVE) keys
else if $(#i := keyword '$#msgid$#msgpar' keyCC keyCS) >= 0 then

// get xgraph-object displayed in row 0 (later used to retrieve data)
#obj := $#obj graph 0; instance

// select the data to be saved and the save format
#todo := butil msgbox userdefined Amp Frq+Amp Cancel;; $DSPExMode - $(word $#i 'Copy to Clipboard' 'Save to CSV-File')
if $#todo == Amp then
#table := eval $($#obj get ydata) // use eval to get a copy of y-data
else if $#todo == Frq+Amp then
if '$DSPExMode' == DSPExAvrSpectrum then
#table := eval vmcol( $($#obj get xdata) , $($#obj get ydata) ) // merge x- and y-data into one table
else
#table := eval vmcol( $($#obj get xdata) , trn($($#obj get ydata)) ) // merge x- and transposed y-data into one table
end
end

// copy / save if table exists
if $#table[?] == table then
// select target
if $#i == 0 then
#file := set clipboard // set target to "clipboard" for all copy_xxx functions
else
#file := butil filedialog save; Select Output File; ; CSV=CSV-File; TXT=Textfile // use filedialog to select the output file
end

// use the CON-object to copy/save table
if '$#file' != '' con savedata text; $#table; $#file; 0; comma; dot
delete $#table
end

// process Control-I (INFO) || Control-M (MAX-MEAN) keys
else if $(#i := keyword '$#msgid$#msgpar' keyCI keyCM) >= 0 then

// get xgraph-object displayed in row 0
#obj := $#obj graph 0;inst

// save original graph title
if '$GraphTitle' == '' GraphTitle := $#obj get title

if $#i == 0 then
// get and display cursor positions
readstr '$($#obj get cursorposition)' #i1 #x1 #y1 #i2 #x2 #y2 #
#text := format 'Index = %d .. %d, X = %g ... %g (%g), Y = %g ... %g (%g)' $#i1 $#i2 $#x1 $#x2 abs($#x1-$#x2) $#y1 $#y2 abs($#y1-$#y2)
else
// set cursor mode (on), style (crosshair), rubberline (off), bind-mode (off), bind-functionindex (0)
$#obj set cursormode on crosshair off off 0
// get x- and y-data
#x := $#obj get xdata
#y := $#obj get ydata
// find index of maximum y value
#imax := eval imax($#y[*,0])
// compute mean of x and y
#xavr := eval avr($#x)
#yavr := eval avr($#y)
// set cursor 1 to maximum and cursor 2 to mean
$#obj set cursorpos 1 $#x[$#imax] $#y[$#imax] deselect
$#obj set cursorpos 2 $#xavr $#yavr deselect
// show maximum and mean in xgraph title
#text := format 'Maximum( %g , %g ), Average( %g , %g )' $#x[$#imax] $#y[$#imax] $#xavr $#yavr
end
// show info in graph title
$#obj set title $GraphTitle -- $#text

end

// note: the return value of the callback function is not used by the xplot/xgraph message handler
exit

//-------------------------------------------------------------------------------------------------
//
// DSPExLib Implements a set of signal processing functions which can be called with
// "DSPLIBEXAMPLE functionname functionarguments". This call style is often
// used to reduce the number of macros of a script or application.
//
// Functions:
//
// DSPEXLIB GETSEGMENTS
// result: a list of all segments selected in the DataSet view stored in a simple
// table (per line: 'setReference ; segmentId ; channelIndex')
// note: this function shows an error message and terminates the caller if no segments
// are selected
//
// DSPEXLIB AVERAGESPECTRUM wave ; wtyp ; atyp
// wave prepared xwave object
// wtyp type of window function: HANNING, HAMMING, KAISER, ...
// atyp type of output spectrum: LOGARITHMIC (=DB), POWER, LINEAR (=AMPLITUDE)
// result: an averaged fft spectrum in the selected format
//
// DSPEXLIB SPECTROGRAM wave ; wtyp ; atyp
// wave prepared xwave object
// wtyp type of window function: HANNING, HAMMING, KAISER, ...
// atyp type of output spectrum: LOGARITHMIC (=DB), POWER, LINEAR (=AMPLITUDE)
// or COMPLEX
// result: a matrix of fft spectra in the selected format, one spectrum per line
//
// DSPEXLIB FREQUENCYSCALE sr ; n ; type
// sr sampling rate in Hz
// n number of spectrum bins (equally spaced in the Hz domain)
// type type of frequency scale: HZ, KHZ, BARK, MEL, ERB
// result: 'frq unit df'; frq is the frequency scale vector, unit is the frequency unit
// name and df is the frequency scale step in Hz
//
// DSPEXLIB AMPLITUDESCALE type
// type type of amplitude scale: LOGARITHMIC (=DB), POWER, LINEAR (=AMPLITUDE)
// result: 'name unit df'; name and unit of amplitude scale
//
//-------------------------------------------------------------------------------------------------
[Macro DSPExLib]

// function call dispatching
readvar #argv #fun #argv /d
goto fun$#fun noFun

noFun:
// function not implemented
// result: empty string

// show an error message and exit
con log '$#mac function "$#fun" not implemented'
exit 1 set ''

//-------------------------------------------------------------------------------------------------
funGetSegments: // in:
// out: segment_list_table
//-------------------------------------------------------------------------------------------------
// retrieve list of selected segments from the DataSet application
#segments := datasetcmd getselected segments
if '$#segments[?]' == table && '$#segments[]' > 0 exit 1 set $#segments
butil msgbox msg ; no segments selected - select and try again; Error!
if '$#segments[?]' == table delete $#segments
exit 2 set '' // terminate this and the calling macro!

//-------------------------------------------------------------------------------------------------
funAverageSpectrum: // in: xwaveobject ; windowtype ; amplitudescale
// out: averagespectrum_vector
//-------------------------------------------------------------------------------------------------
// parse arguments
readvar #argv #wave';'#wtyp';'#atyp';'#

// show init message
con log $#mac $(upper '$#fun') - initializing

// create window
#w := gosub makewindow $($#wave framelength) $#wtyp

// create result table
#spg := new table *

// compute averaged amplitude spectrum
#n := $($#wave framecount)
$#spg := eval cr2len ( fft ( $($#wave read) ?* $#w ) )
for #i := 1 to $#i < $#n step #i := int $#i+1
if $#i%10 == 0 con logext 0; $#mac $(upper '$#fun') - $#i of $#n frames processed
$#spg := eval cr2len ( fft ( $($#wave read) ?* $#w ) ) + $#spg
end
$#spg := eval $#spg / $#n

// convert to selected output spectrum type
if $(#atyp := keyword '$#atyp' dB logarithmic power amplitude linear) < 2 then
$#spg := eval lin2log($#spg , $($#wave aref), 20)
else if $#atyp == 2 then
$#spg := eval $#spg ?^ 2
end

// show end message
con logext 0; $#mac $(upper '$#fun') - finished ($#n spectra computed)

// return averaged spectrum
exit 1 set $#spg

//-------------------------------------------------------------------------------------------------
funSpectrogram: // in: xwaveobject ; windowtype ; amplitudescale
// out: spectrogram_matrix
//-------------------------------------------------------------------------------------------------
// parse arguments
readvar #argv #wave';'#wtyp';'#atyp';'#

// show init message
con log $#mac $(upper '$#fun') - initializing

// create window
#w := gosub makewindow $($#wave framelength) $#wtyp

// check selected output spectrum type
if $(#atyp := keyword '$#wtyp' dB logarithmic power amplitude linear complex) < 5 then
// compute amplitude or power spectra

// create result table (one spectrum per line)
#spg := new table * * num:x:$(int $($#wave fftlength)/2 + 1) /p
// compute amplitude spectra
#n := $($#wave framecount)
for #i := 0 to $#i < $#n step #i := int $#i+1
if $#i%10 == 0 con logext 0; $#mac $(upper '$#fun') - $#i of $#n frames processed
$#spg[$#i,*] := eval cr2len ( fft ( $($#wave read) ?* $#w ) )
end
// convert to selected output spectrum type
if $(#atyp := keyword '$#atyp' dB logarithmic power amplitude linear) < 2 then
$#spg := eval lin2log($#spg , $($#wave aref), 20)
else if $#atyp == 2 then
$#spg := eval $#spg ?^ 2
end

else
// compute complex spectra

// create result table (one spectrum per line)
#spg := new table * * num:x:$(int $($#wave fftlength) + 2) /p
// compute complex spectra
for #i := int $($#wave framecount) to $#i > 0 step #i := int $#i-1
if $#i%50 == 0 con logext 0; $#mac $(upper '$#fun') - $#i of $#n frames processed
$#spg[$#i,*] := eval fft ( $($#wave read) ?* $#w )
end

end

// show end message
con logext 0; $#mac $(upper '$#fun') - finished ($#n spectra computed)

// return spectrogram matrix
exit 1 set $#spg

//-------------------------------------------------------------------------------------------------
funFrequencyScale: // in: samplingrate ; spectrumbins ; frequencyscale
// out: frequencyscale_vector frequencyscale_unit frequency_resolution_Hz
//-------------------------------------------------------------------------------------------------
// parse arguments
readvar #argv #sr';'#n';'#unit';'#
// generate frequency scale equally spaced in Hz
#frq := new table * // dummy table to make frq-scale permanent
$#frq := eval fill($#n, 0, $(#df := eval $#sr / 2 / ($#n - 1)) )
// convert to selected scale
if $(#unit := keyword '$#unit' Hz kHz Bark Mel ERB) < 0 #unit := 0
if $(#unit := word $#unit Hz kHz Bark Mel ERB) == kHz then
$#frq := eval $#frq / 1000
else if $#unit != Hz then
$#frq := eval hz2$#unit($#frq)
end
// return scale settings
exit 1 set '$#frq $#unit $#df'

//-------------------------------------------------------------------------------------------------
funAmplitudeScale: // in: amplitudescale
// out: amplitudescale_text amplitudescale_unit
//-------------------------------------------------------------------------------------------------
// parse arguments
readvar #argv #unit';'#
// get text and unit of amplitude scale
if $(#i := keyword '$#unit' dB logarithmic power amplitude linear) < 2 #i := 0
#unit := word $#i dB dB - - -
#text := word $#i amplitude amplitude power amplitude amplitude
exit 1 set '$#text $#unit'

//
// local subroutines
//

makeWindow:
// GOSUB MAKEWINDOW windowlength windowtype -> windowvector
readvar #argv #wlen #wtyp #
#list := hanning hamming blackman kaiser bartlett taprect nuttall flattop gauss
if $(#wtyp := keyword '$#wtyp' $#list) < 0 #wtyp := 0
exit 1 eval window($#wtyp, $#wlen, 1) * 2 / $#wlen
</pre>

MediaWiki:Common.css

2014-05-20T12:28:33Z

Admin:

/* CSS placed here will be applied to all skins */

/* and, again, using this for *all* our tables... */

table {
border: 0px;
border-collapse: collapse;
}

table tr {
border: 1px solid;
border-color: #000000;
}

table th {
border: 1px solid;
border-color: #000000;
background-color:#FFC8FF;
vertical-align: top;
padding-left: 0.8em;
padding-right: 0.8em;
}

table td {
border: 1px solid;
border-color: #000000;
vertical-align: top;
padding-left: 0.8em;
padding-right: 0.8em;
}

/* C.G. 6.4.2011: einrahmen - einfacher, dünner Rand allüberall (wie von Toni gewünscht) */

table.einrahmen {
border: 0px;
border-collapse: collapse;
}

table.einrahmen tr {
border: 1px solid;
}

table.einrahmen th {
border: 1px solid;
background-color:#FFC8FF;
}

table.einrahmen td {
border: 1px solid;
}

/* C.G. 6.4.2011: keinrahmen - kein Rand */

table.keinrahmen {
border: 0px;
border-style: hidden;
border-collapse: collapse;
}

table.keinrahmen tr {
border: 0px;
}

table.keinrahmen th {
border: 0px;
border-style: hidden;
background-color:#FFC8FF;
}

table.keinrahmen td {
border: 0px;
border-style: hidden;
}

/* C.G. 6.4.2011: zweirahmen - zweifacher, dünner Rand allüberall (wie von Toni gewünscht) */

table.zweirahmen {
border: 1px;
border-collapse: separate;
border-spacing:2px;
border-style:double;
}

table.zweirahmen tr {
border: 1px;
border-style:double;
border-spacing:2px;
}

table.zweirahmen th {
border: 1px;
border-style:double;
background-color:#FFC8FF;
border-spacing:2px;
}

table.zweirahmen td {
border: 1px;
border-style:double;
border-spacing:2px;
}

/* C.G. 6.4.2011: sicherstellen, dass Variablennamen äquidistant gesetzt werden */

var { font-family: Courier, "Courier New", monospace; background-color: #ffc0cb; }

code { font-family: Courier, "Courier New", monospace; background-color: #e0ffff; }
pre { font-family: Courier, "Courier New", monospace; background-color: #e0ffff; }

/* J.W. 20.5.2014: adding TOC limit functionality from default Mediawiki:Common.css */

/*
* Allow limiting of which header levels are shown in a TOC;
* <div class="toclimit-3">, for instance, will limit to
* showing ==headings== and ===headings=== but no further
* (as long as there are no =headings= on the page, which
* there shouldn't be according to the MoS).
* [[Vorlage:TOC limit]]
*/
.toclimit-2 .toclevel-1 ul,
.toclimit-3 .toclevel-2 ul,
.toclimit-4 .toclevel-3 ul,
.toclimit-5 .toclevel-4 ul,
.toclimit-6 .toclevel-5 ul,
.toclimit-7 .toclevel-6 ul {
display: none;
}

Programmer Guide/Shell Items/Table/SET TABLE

2014-05-15T09:24:18Z

Admin: /* {{anchor|FIND|Finding table entries}} */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
The <code>SET <var>table</var>…</code> command is used to modify a table item. The sub-commands documented here are valid for all table types, unless otherwise specified.

== Setting or Adding table entries ==

SET <var>table</var> <var>index</var>|* … [ /Tag | /Untag ]

When using the index of an ''existing'' entry for <var>index</var>, the command will modify the respective entry. When supplying the asterisk, "<code>*</code>", for <var>index</var>, a ''new entry'' will be appended to the end of the table. Finally, when supplying a value for <var>index</var> that is ''greater'' than the number of entries (<var>table</var><code>[]</code>), the table will be padded with an appropriate number of empty entries in order to allow the entry <var>index</var> to be set.

The options <code>/Tag</code> and <code>/Untag</code> may be used for setting or clearing the tag flag.

Remember that with {{STX}} table indexes are always zero-based.

=== Unstructured adding ===

SET <var>table</var> <var>index</var>|* <var>entryValue</var> [ /Tag|Untag ]

This statement is the sole way of adding entries to a simple table. The statement is applicable to extended tables, too. With extended tables, the field separator character may be used to separate fields in the string <var>entryValue</var>, meaning that <var>entryValue</var> will be parsed in the same way as entries are loaded from files.

{|class="keinrahmen"
| <var>index</var>
| The zero-based index of an existing entry to modify the entry's data or a zero-based index greater than the number of existing entries, to add a new entry. If the index is greater than the total number of entries, then all missing entries are created and initialized with default values. An asterisk may be used to append the table with a new entry at the next free index.
|-
| <var>entryValue</var>
| The value to assign to the entry.
|-
| <code>/Tag</code> or <code>/Untag</code>
| tag, or untag, the respective entry
|}

=== Adding structured data to extended tables ===

SET <var>table</var> <var>index</var>|* <var>fieldId1</var> <var>fieldValue1</var> [ … <var>fieldIdn</var> <var>fieldValuen</var> ] [ /Tag|Untag ] [ /N=<var>n</var>|all|tagged ]

The structured variant of setting entries allows to address the fields of an entry. It is thus applicable to extended tables only. Using the option <code>/N</code>, you may even set multiple entries at the same time.

{|class="keinrahmen"
| <var>index</var>
| The zero-based index of an existing entry to modify the entry's data or a zero-based index greater than the number of existing entries, to add a new entry. If the index is greater than the total number of entries, then all missing entries are created and initialized with default values. An asterisk may be used to append the table with a new entry at the next free index.
|-
| <var>fieldId1</var>…
| A valid field id (as defined in the <code>[[User Guide/Workspace/Spectrum Viewer pre-configured profiles|NEW TABLE]]</code> command) or a field index.
|-
| <var>fieldValue1</var>…
| The value to assign to the respective field.
|-
| <code>/Tag</code> or <code>/Untag</code>
| tag, or untag, the respective entry
|-
| <code>/N=<var>n</var></code>
| Repeat this assignment for the next <var>n</var> entries (with <code>/N=<var>n</var></code> and <var>n</var> being an integer higher than, or equal to, 1), or for ''all'' entries from the current one to the last one (with <code>/N=all</code>), or for all tagged entries from the current one to the last one (<code>/N=tagged</code>). Note that the <code>all</code> and <code>tagged</code> variants cannot append new entries to the table.
|}

// initialize the first field of the first 10 entries with the value 0.
$#extTable 0 0 0 /N=10

== Configuring a table field==

The <code>SET table CONFIG</code> command is only applicable to [[Programmer_Guide/Concepts/Extended_table|extended tables]] (after all, [[Programmer_Guide/Concepts/Simple_table|simple tables]] do not have fields).

SET <var>table</var> CONFIG <var>fieldid</var> [ <var>show</var> <var>name</var> <var>scale</var> <var>format</var> <var>mmode</var> <var>mval</var> <var>msym</var> <var>header</var> <var>width</var> <var>align</var> <var>sort</var> <var>editable</var>
[ <var>listtable</var> <var>listfield</var> <var>listonly</var> <var>setdefault</var> <var>setuserdefault</var> <var>multirow</var> ] ]

Configure a table field. Define the display format (list box and list view) and field properties. The field must have been specified in the <code>[[User Guide/Workspace/Spectrum Viewer pre-configured profiles|NEW TABLE]]</code> command. The table must be in configuration mode (see <code>MODE</code>).

{|class="keinrahmen"
| <var>fieldid</var>
| The name or index of the field to be configured / updated.
|-
| <var>show</var>
| Show (<code>1</code> or <code>ON</code>) or hide (<code>0</code> or <code>OFF</code>) the field in listbox and list view controls
|-
| <var>name</var>
| Show both name and value (<code>1</code> or <code>ON</code>) or value only (<code>0</code> or <code>OFF</code>) in list box controls. This is only effective if <var>show</var> is <code>ON</code>.
|-
| <var>scale</var>
| The scaling factor for numeric fields; if a numeric field is accessed in the [[Programmer Guide/Shell Items/Table/Show_Format|show format]], its value is multiplied with scale (used by both listboxes and listviews).
|-
| <var>format</var>
| The [[Programmer Guide/Shell Items/Table/Show_Format|show format]] format string.

For fields of type <code>NAME</code> or <code>STRING</code>, the format must contain a string tag (e.g.: <code>%s</code>, <code>%10.10s</code>) For both numeric field types (<code>INTEGER</code> and <code>NUMBER</code>), the format must contain a float tag (<code>%f</code>, <code>%g</code>). The float tag is necessary for integer values because the scaling factor (<var>scale</var>) is a floating number.

Note that to display an integer (without decimals) you can use the format tag <code>%5.0f</code>. This parameter controls the format for listboxes and listviews dialog controls.
|-
| <var>mmode</var>
| Enable (<code>1</code>|<code>ON</code>) or disable (<code>0</code>|<code>OFF</code>) missing value replacement. Missing value replacement is disabled by default. If enabled, missing values are replaced by <var>msym</var>.
|-
| <var>mval</var>
| The numeric id value of a 'missing value' (e.g. <code>0</code> for f0 data). The default is <code>0</code>. Missing value replacement only works for numerical fields (<code>NUMBER</code> or <code>INTEGER</code>).
|-
| <var>msym</var>
| The replacement symbol (string) for missing values (e.g. <code>UNVOICED</code> for f0 data). The strings <code><empty></code> and <code><blank></code> can be used to replace a missing value with an empty string or a blank character. The default string is the empty string.
|-
| <var>header</var>
| The text to be displayed in the field's column header of a listview control.
|-
| <var>width</var>
| The width (in characters) of the column of a listview control.
|-
| <var>align</var>
| Align field left (<code>0</code>) or right (<code>1</code>) in the column of a listview control; The first column of a listview is always. left-aligned (align is ignored)
|-
| <var>sort</var>
| Enable (<code>1</code>) or disable (<code>0</code>) the sort function of the column header of a listview control.
|-
| <var>editable</var>
| If <var>editable</var> is set to <code>0</code>, the respective field (column) of the table is NOT editable when the table is connected to a <code>ListView</code> item. If <var>editable</var> is set to a number different from <code>0</code>, the respective field (column) of the table IS editable when the table is connected to a <code>ListView</code> item. See the example script <code>editabletable.sts</code> for a complete example.
|-
| <var>listtable</var>
| The name of a table containing all permissible values for this field. If this table (<var>table</var>) is connected to a <code>listview</code> item, and the <var>listtable</var> parameter is specified, the <code>listview</code> displays a combobox in the associated column, and fills the combobox with <var>listtable</var>'s values.
|-
| <var>listfield</var>
| The field id specifying the field in <var>listtable</var> where the values are stored. If <var>listtable</var> is a simple table, <var>listfield</var> must be <code>0</code>.
|-
| <var>listonly</var>
| The <var>listonly</var> parameter specifies whether this <var>table</var>'s field may only use values in the list table (<code>1</code>), or whether any values may be entered (<code>0</code>). If <code>0</code>, then the combobox is editable.
|-
| <var>setdefault</var>
| The <var>setdefault</var> parameter specifies whether invalid or empty data entered whilst editing should be replaced by the default value (<code>1</code>=yes, <code>0</code>=no). The first value in the list table is the default value.
|-
| <var>setuserdefault</var>
| If set to <code>ON</code> or <code>1</code>, the last user-input for this field will be used as the respective default value.
|-
| <var>multirow</var>
| If set to <code>1</code> or <code>ON</code>, the field can display text in multiple rows. If set to <code>0</code> or <code>OFF</code>, text will be displayed in one row. The default is <code>OFF</code>.
|}

A field is defined once, but can be configured as often as needed. If an argument is not supplied or set to '<code>*</code>', the configuration for that parameter is not changed.See the example script <code>editabletable.sts</code> for a detailed example.

== Table-to-table Copy ==

SET <var>table</var> COPY <var>srctable</var> [<var>fieldid</var> … ] [ /Rows /Columns ]

Copy data from the source table <var>srcTable</var> (a parameter table or an extended table) to the target table <var>table</var> (a table of the same kind). If fields (<var>fieldids</var>) are specified, then only these fields are copied. Otherwise all fields of the source table are copied.

If the command is called ''without'' supplying options <code>/Rows</code> or <code>/Columns</code>), then
# the source table must have the ''same format'', i.e. the same fields, as the target table; and
# the source entries will ''overwrite'' the target entries (appending entries if necessary).

If the command is called with either option <code>/Rows</code> or <code>/Columns</code>, the command will ''not'' overwrite existing entries and fields in the target table. Rather than that, the command will ''modify'' the target table, appending source fields (which do not exist in the target table) and entries to the target table. Note that the target table must have enough undefined fields to accommodate the appended fields (i.e. fields created by <code>[[Programmer_Guide/Shell_Items/Table/NEW_TABLE|NEW TABLE]]</code>, but yet undefined).

Note that the <code>COPY</code> command works only with extended and with parameter tables.

;<var>srctable</var>:The table to copy from. This must be an extended or parameter table.
;<var>fieldid</var>: An optional list of field IDs, separated by blank. If specified, only these fields are copied. If omitted, all fields are copied.
;<code>/Rows</code>: If specified, fields from <var>srctable</var> are appended to <var>table</var>. The fields being copied must already be defined in <var>table</var>. Note that the field data type is not checked (i.e. number fields can be copied to string fields of the same name).
;<code>/Columns</code>: If specified, entries from <var>srctable</var> are copied to the ''same'' entries in <var>table</var>, ''overwriting their old value''. Fields not defined in <var>table</var> are automatically defined and configured. For this reason there must be enough undefined fields in <var>table</var>.

== Copying between a Table and a Value Item ==

SET <var>table</var> COPY <var>outputName</var> <var>i</var> <var>j</var> [ /Row|Col ] [ /Write ]

Copy data between a table and a [[Programmer_Guide/Shell_Items/Value|value object]]. If the option <code>/Write</code> is used, the table data is copied to the value item, otherwise (default) the value item data is copied to the table.

;<var>outputName</var>: The name of a value item to copy to or from.
;<var>i</var>: The entry index.
;<var>j</var>: The field index.
;<code>/Row</code>: Copy table fields starting at row <var>i</var> field <var>j</var>. The number of fields copied is determined by the size of the vector. The number of rows copied is determined by the number of vectors (only for array value items). This option is only for array and vector value items.
;<code>/Col</code>: Copy table entries starting at row <var>i</var>, field <var>j</var>. The number of rows copied is determined by the size of the vector. The number of fields copied is determined by the number of vectors (array value items). This option is only for array and vector value items.
;<code>/Write</code>: If the option <code>/Write</code> is specified, the table data is copied to the value item. If omitted, the value item data is copied to the table.

== Copying to and fro the clipboard ==

SET <var>table</var> CLIPBOARD [ /Show|Write ]

Copy the visible entries of a table to the clipboard. The entries can be copied either in:
# [[Programmer_Guide/Shell_Items/Table/Introducing_Table_Items#Show_Format|show-format]], i.e. using listbox display format, when supplying the <code>/Show</code> option (or no option at all, since this is the default); or in
# [[Programmer_Guide/Shell_Items/Table/Introducing_Table_Items#Write_Format|write-format]], i.e. the format normally used when writing to a file. This is done with the <code>/Write</code> option.

;<code>/Show</code>: Use the [[Programmer Guide/Shell Items/Table/Show_Format|show format]] to format each entry string. This is the default.
;<code>/Write</code>: Use the [[Programmer Guide/Shell Items/Table/Write_Format|write format]] to format each entry string.

SET <var>table</var> CLIPBOARD /Read [ /Delete ] [ /Empty ]

Read the last entry from the clipboard. This will work only if the format of the respective clipboard entry is either Unicode (<code>CF_UNICODETEXT</code>) or text (<code>CF_TEXT</code>).
;<code>/Read</code>: Mandatory option.
;<code>/Delete</code>: Delete the table entries before reading from the clipboard.
;<code>/Empty</code>: Empty the clipboard after a successful read.

== Defining a table field ==

SET <var>table</var> DEFINE <var>index</var>|<var>* type name</var> [<var>count offset</var>] [/Auto] [/Undefine]

Note that the table must be in configuration mode (see [[XXX|<code>MODE</code>]]). Define the data type and name of field <var>index</var> (0 .. number of fields - 1). If an asterisk '<code>*</code>' is given instead of <var>index</var>, the first free (undefined) index is used. The argument <var>type</var> is the id of the data type of the field. The argument <var>name</var> is the name to be assigned to the field and must be a valid name string. The parameters <var>count</var> and <var>offset</var> can be used to define multiple fields with one command (<var>count</var> = number of fields, <var>offset</var> = base index). The option /Auto ensures the name is unique by concatenating the string name with an index (first value: 1). Note that once you have configured the table, you need to switch to DATA mode (see [[XXX|<code>MODE</code>]] below).

The <code>SET <var>table</var> DEFINE</code> command is only applicable to [[Programmer_Guide/Concepts/Extended_table|extended tables]], since only they support different types of fields.

;<var>index</var>: The index of the field to be defined or '*' for the next free index.
;<var>type</var>: The type of data to be stored. The following values are supported:
:<code>NAME</code> - Strings which are valid names.
:<code>STRING</code> - Free text.
:<code>INTEGER</code> - Integer numbers.
:<code>NUMBER</code> - Floating point numbers.
;<var>name</var>: The name to assign to the field. Note that this must also be a valid name.
;<var>count</var>: The number of fields to define. Used in conjunction with <var>offset</var> for multiple definitions. Must be >= <code>1</code>.
;<var>offset</var>: The index to start multiple definitions with. Must be >= <code>0</code>.

== Undefining a table field ==

SET <var>table</var> DEFINE <var>index</var>|<var>name</var> [… /Undefine]

Undefine an existing field and delete contents of all field entries. Multiple undefines are possible by using the option <code>/Undefine</code> in conjunction with multiple parameters.

;<var>index|name</var>: The index or name of the field(s) to undefine.

== Renaming a table field ==

SET <var>table</var> DEFINE <var>fieldName</var> <var>newName</var> /Rename

Rename an existing field.

;<var>fieldName</var>: The existing field name.
;<var>newName</var>: The new field name
;<code>/R</code>
:The mandatory option <code>/Rename</code>, specifying that this <code>DEFINE</code> command should rename the field.

An example can be found in the macro file <code>table_redefine.sts</code>.

== Deleting table entries ==

<code>SET <var>table</var> [<var>index</var>] /Delete</code>

Delete all visible entries or the specified entry <var>index</var>.

== {{anchor|FIND|Finding table entries}} ==

The <code>FIND</code> function implements a simple 'database query' interface for tables. To create complex queries, it may be necessary to apply a set of <code>FIND</code>s and possibly combine them with the <code>[[Programmer_Guide/Command_Reference/FIND|FIND]]</code> command. The <code>FIND</code> function only searches tagged entries. Therefore, if you want to search the whole table, you must tag all the entries first. At the end of a query (any number of <code>FIND</code> function calls), the tagged entries are those matching the search criteria.

SET <var>table</var> FIND

Initialize a new find cycle. The tag flag of all entries are set and visibility is set to ALL. This command should be issued before a new query consisting of multiple commands is started. Instead of this command the option /Start can be used with the (first) <code>FIND</code>.

<code>SET <var>table</var> FIND <var>cexpr</var> [<var>loper cexpr</var> ...] [/Start /Invert /Tagged]</code>

Search for all tagged entries matching the criteria defined by the <var>cexpr</var> and <var>loper</var> arguments. The tag flags of all not matching entries are cleared. The logical operators are evaluated strictly from left to right. This means the result of all expressions of the left side of an operator is combined with the result of the expression on the right side. The logical operators <code>AND</code> (=&&), <code>OR</code> (=||) and <code>XOR</code> (=^^) are defined. Note that the field value for simple tables is <code>0</code>.

;<var>cexpr</var>

:The expression defining one search criterion (see Find expressions for details).

;<var>loper</var>

:The logical operator combining two search criteria; logical operators are applied from left to right, bracketing is not possible. The following operators are supported:

:<code>AND</code> - conjunction
<code>&&</code> - conjunction
<code>OR</code> - disjunction
<code>||</code> - disjunction
<code>XOR</code> - exclusive disjunction

:<code>^^</code> - exclusive disjunction

;<var>/Start</var>

:Initialize a new find cycle (this is like a call to <code>FIND</code> without arguments and is applied before query).

;<var>/Invert</var>

:Invert all tag flags (applied after query).

;<var>/Tagged</var>

:Switch to visibility "tagged" (applied after query).

<pre>
// search for entries where key field ends with 'ing'
// and show only tagged entries
$#t find 'key:=I:*ing' /Tagged
</pre>

== {{Anchor|FINDEXPR|Find expressions}} ==
{{:Programmer_Guide/General_Descriptions/Find_Expressions}}

== Regular expressions ==

S_TOOLS<nowiki>-</nowiki>STx supports searches using POSIX regular expression. When using regular expressions, characters which have a special meaning in {{STX}} will need to be escaped using the {{STX}} escape character "<code>`</code>".

{|
|-
|fieldid:cond:regex
|Match the value of a string field (type <code>NAME</code> or <code>STRING</code>).{|
|-
|
|
|
|-
|fieldid
|name or index of a string field (<code>0</code> for simple tables)
|-
|cond
|=RI
|matching regular expression ignoring case
|-
|
|=RR
|matching regular expression respecting case
|-
|
|!RI
|not matching regular expression even if ignoring case
|-
|
|!RR
|not matching regular expression if respecting case.
|-
|regex
|a POSIX regular expression.
|}

The script <code>regular_expressions.sts</code> provides examples of usage.

== Formatting table fields ==

Formatting is only applicable to [[Programmer_Guide/Concepts/Extended_table|extended tables]].

SET <var>table</var> FORMAT <var>format</var> [<var>listdel</var> <var>vardel</var> <var>numfmt </var> <var>intfmt</var>]

Configuration of the write format used to save and load tables from files (see [[XXX|<code>SET file LOAD</code>]] and [[XXX|<code>SET file SAVE</code>]]). You can configure the [[Programmer Guide/Shell Items/Table/Show_Format|show format]] (used to display tables in the GUI) using the [[XXX|<code>CONFIG</code>]] command.

;<var>format</var>
:<code>0</code> - Store all fields even if they are empty. Assigned fields have the format <code>fieldvalue</code> <var>listdel</var> and empty fields have just the <var>listdel</var>. E.g.: <code>10.0 ; 10.1 ; ; 10.3</code>

:<code>1 </code> - Only assigned fields are stored. Every assigned field outputs the following string <code>fieldindex</code> <var>vardel</var> <code>fieldvalue</code> <var>listdel</var>. E.g.: <code>c0=10.0 ; c1=10.1 ; c2= ; c3=10.3</code>

:Note: In order to load a table successfully, it must be loaded using the same format setting as was used to save it.

;<var>listdel</var>
:delimiter string used to separate fields in the output line (for both formats). The special symbol '%t' can be used to specify the tab character. Consecutive white spaces (blanks and tabs) are interpreted as one delimiter. E.g. " 1 2 3" is interpreted as three fields, whereas ":1::2:3"

;<var>vardel</var>
:delimiter string used to separate the <code>fieldindex</code> from the <code>fieldvalue</code> (for format <code>1</code> only)

;<var>numfmt</var>
:Float format string used for all fields of type <code>NUMBER</code>. This can be any valid C string format specifier.

;<var>intfmt</var>

:Integer (!) format string used for all fields of type <code>INTEGER</code>. This can be any valid C string format specifier.

You can set the decimal symbol using the [[XXX|<code>MODE</code>]] command.
<pre>
///////////////////////////////////////////////////////////////////////////////
//
// Macro: load_a_file_into_a_table.sts
// Description: load the contents of a numeric text file into a parameter
// table and displays the table if desired
// Parameters: #fileName the file to load
// #mode 0 silent
// 1 show table
// 2 return table
// Return: 0 on success, non-zero on failure
// Usage: load_a_file_into_a_table [file] ; [show]
// Author: Jonnie White
// History: 2005-03-31 jw created
// 2005-04-27 jw added new mode (return table) and file
// parameter
//
///////////////////////////////////////////////////////////////////////////////
[macro load_a_file_into_a_table]
#fileName := set '$scriptDirectory\input_matrix_small.txt'
#mode := 1
readvar #argv #fileName';'#mode

// create a parameter table with 4 fields
#tableItem := new table * 4 /Parameter number:f:4
if '$#tableItem' == * em -1 ; failed to create a table

// set the write format to blank separated
$#tableItem format 0 ' '

// create the read-only file object associated with fileName
#fileItem := new file * '$#fileName' /Text /Read
if '$#fileItem' == * em -1 ; failed to open the file $#fileName

// load the file into the table
$#fileItem load $#tableItem
if '$rc' > 0 em -1 ; failed to load file $#fileName into table $#tableItem

// show the table
if '$#mode' == 1 showitem $#tableItem

// return table
if '$#mode' == 2 then
delete $#fileItem
exit 1 set '$#tableItem'
else
// clean up
delete $#fileItem $#tableItem
end
exit 1 int 0
</pre>
Note that if you need to save a table containing empty fields, you should *not* use a blank or a tab character as the delimiter. If you do, the empty fields will be omitted on loading the table.

== Locking / Unlocking the table ==

Table items can be locked to prevent access by shells other than the locking shell.

See <code>lock_example.sts</code> in the script examples directory for an example.

=== LOCK ===

<code>SET <var>table</var> LOCK [/Save]</code>

Lock table access. If a table is locked, only the shell which locked it has access to its content. The table must be unlocked after finishing the 'critical' processing section.

During the execution of most table commands, the table is automatically locked temporarily to the shell (by the table command). The table is also locked temporarily to a dialog during update processes. If the table is locked with the option /Save, the tag flags and the current order and mode is saved on lock and restored with the unlock command. In this case in the critical section entries can only be modified, but not created or deleted.

=== TRYLOCK ===

<code>SET <var>table</var> TRYLOCK [ <var>timeout</var> ] [ /S ]</code>

Try to lock the table item <var>table</var>. If no timeout is specified, <code>TRYLOCK</code> returns immediately. If the caller already *holds* the lock, <code>TRYLOCK</code> will fail immediately. This makes sense because, since the caller is the owner, it cannot release it whilst its waiting.

;<var>timeout</var>

:If specified, <code>TRYLOCK</code> will try to get a lock once per millisecond until it is either successful, or <var>timeout</var> milliseconds have elapsed.

;<var>/S</var>

:If specified, errors will generate warning messages rather than error messages. See The Silent Flag for details.

Return Codes:

<code>0</code> - an unlocked table has been successfully locked.
<code>381</code> - Error: if the table could not be locked due to it being locked by someone else.
<code>382</code> - Warning: identical to <code>381</code>, except that this returned when the /S flag is specified.
<code>383</code> - Error: if the table could not be locked due to it being locked by the caller.
<code>384</code> - Warning: identical to <code>383</code>, except that this returned when the /S flag is specified.

Example:

"<code>SET $#table TRYLOCK 5000</code>" will try hard to lock the table. If it does not succeed within 5000ms (i.e., five seconds), it will fail - but it will not fail earlier.

The <code>TRYLOCK</code> command is intended for safe multithreading without race conditions occurring

=== UNLOCK ===

<code>SET <var>table</var> UNLOCK</code>

Unlock table access.

== Setting the table mode ==

This command is only applicable for [[Programmer_Guide/Concepts/Extended_table|extended tables]].

SET <var>table</var> MODE <var>mode</var> [<var>access format decimal</var>]

Set table mode (configuration / data) and general attributes.

;<var>mode</var>

:A flag to switch the table mode to configuration mode (<code>0</code>) or data mode (<code>1</code>); After creating an extended table the table may be in configuration or data mode, depending on the <code>NEW</code> command. See <code>[[User Guide/Workspace/Spectrum Viewer pre-configured profiles|NEW table]]</code> for details.

;<var>access</var>

:This argument is currently meaningless. It is reserved for future database functions and should be set to '<code>0</code>' or '<code>*</code>'.

;<var>format</var>

:Selects the format to be used for file I/O: <code>0</code>…[[Programmer Guide/Shell Items/Table/Show_Format|show format]], <code>1</code>…[[Programmer Guide/Shell Items/Table/Write_Format|write (default) format]].

;<var>decimal</var>

:Sets the character to be used as the decimal symbol. By default, the period '<code>.</code>' is used.

Since {{STX}} 3.7.0, the <code>[[User Guide/Workspace/Spectrum Viewer pre-configured profiles|NEW TABLE]]</code> syntax has been modified to include the field definitions. The table mode is then automatically set to data, and hence this command may in future be pretty much obsolete, except for setting the decimal symbol.

== Showing and hiding table entries ==

SET <var>table</var> /All|Tagged

Make either all table entries visible (<code>/All</code>) or only tagged entries (<code>/Tagged</code>).

Only visible entries can be accessed, deleted or displayed (e.g. in a list box).

== Sorting table entries ==

SET <var>table</var> SORT [/Respect]

Invert entry order (all tables) 

For simple tables:

SET <var>table</var> SORT <var>dir</var> [/Respect]

For extended tables:

SET <var>table</var> SORT <var>fieldid dir</var> […] [/Respect]

Sort table entries. For simple tables only the sort direction (<var>dir</var>: Ascending (0), Descending (1)) can be selected.

For extended tables, one or more fields and the sort direction can be specified. The sort function ignores the visibility setting and sorts all table entries. If the option <code>/Respect</code> is used, strings are sorted respecting their case, otherwise the sort is case-insensitive.

== Tagging table entries ==

SET <var>table</var> /Reset|Invert

Reset (/Reset) or invert (/Invert) tag flags of all entries and set visibility to ALL.

SET <var>table index</var> /Tag|Untag|Invert

Set, clear or invert tag flag of an entry. These options can also be used in all table commands assigning a value.

The command <code>TAGS</code> can be used to save and restore a table's tagged entries.

Programmer Guide/General Descriptions

2014-05-15T06:37:45Z

Admin:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
General Descriptions provides general information about the S_TOOLS-STx macro language and environment.

'''Contents'''

<splist
parent=
sort=asc
sortby=title
showpath=no
liststyle=unordered
kidsonly=yes
>

Programmer Guide/General Descriptions

2014-05-15T06:37:34Z

Admin:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
General Descriptions provides general information about the S_TOOLS-STx macro language and environment.
'''Contents'''

<splist
parent=
sort=asc
sortby=title
showpath=no
liststyle=unordered
kidsonly=yes
>

User Guide/Real Time Analyser

2014-05-14T13:13:58Z

Admin:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
[[File:rtanalyser.png]]

The {{STX}} Real-Time Analyser can analyse mono or stereo input from any available source on the system. Three analysis displays are implemented:

* Spectrum
* Spectrogram
* Waterfall

'''Contents'''

<splist
parent=
sort=asc
sortby=title
showpath=no
liststyle=unordered
kidsonly=yes
>

User Guide/Real Time Analyser

2014-05-14T13:13:35Z

Admin:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}

[[File:rtanalyser.png]]

The {{STX}} Real-Time Analyser can analyse mono or stereo input from any available source on the system. Three analysis displays are implemented:

* Spectrum
* Spectrogram
* Waterfall

'''Contents'''

<splist
parent=
sort=asc
sortby=title
showpath=no
liststyle=unordered
kidsonly=yes
>

Programmer Guide/Command Reference

2011-03-22T16:37:22Z

Admin:

__TOC__The Command Reference documents all the commands available in the S_TOOLS-STx macro language. This is with the notable exception of the shell item commands, which are documented in the chapter Shell Items.

Note that all S_TOOLS-STx commands store their return code in the shell variable <code>rc</code>. See Shell Environment for more details. This is in contrast to all [[User Guide/Workspace/Waveform & Segmentation Viewer pre-configured profiles|MACRO]] commands which store their exit value in the variable <code>result</code>.

== Introductions ==

<splist
parent=Programmer_Guide/Command_Reference_Intro
sort=asc
sortby=title
showpath=no
liststyle=unordered
kidsonly=yes
></splist>

== Commands (alphabetical list) ==
<splist
parent=
sort=asc
sortby=title
showpath=no
liststyle=unordered
kidsonly=yes
></splist>

== Global Options ==

<splist
parent=Programmer_Guide/Command_Reference_Options
sort=asc
sortby=title
showpath=no
liststyle=unordered
kidsonly=yes
></splist>

Programmer Guide/Command Reference

2011-03-22T16:36:21Z

Admin: /* Commands */

The Command Reference documents all the commands available in the S_TOOLS-STx macro language. This is with the notable exception of the shell item commands, which are documented in the chapter Shell Items.

Note that all S_TOOLS-STx commands store their return code in the shell variable <code>rc</code>. See Shell Environment for more details. This is in contrast to all [[User Guide/Workspace/Waveform & Segmentation Viewer pre-configured profiles|MACRO]] commands which store their exit value in the variable <code>result</code>.

== Introductions ==

<splist
parent=Programmer_Guide/Command_Reference_Intro
sort=asc
sortby=title
showpath=no
liststyle=unordered
kidsonly=yes
></splist>

== Commands (alphabetical list) ==
<splist
parent=
sort=asc
sortby=title
showpath=no
liststyle=unordered
kidsonly=yes
></splist>

== Global Options ==

<splist
parent=Programmer_Guide/Command_Reference_Options
sort=asc
sortby=title
showpath=no
liststyle=unordered
kidsonly=yes
></splist>

Programmer Guide/Command Reference

2011-03-22T16:36:10Z

Admin: /* Intro */

The Command Reference documents all the commands available in the S_TOOLS-STx macro language. This is with the notable exception of the shell item commands, which are documented in the chapter Shell Items.

Note that all S_TOOLS-STx commands store their return code in the shell variable <code>rc</code>. See Shell Environment for more details. This is in contrast to all [[User Guide/Workspace/Waveform & Segmentation Viewer pre-configured profiles|MACRO]] commands which store their exit value in the variable <code>result</code>.

== Introductions ==

<splist
parent=Programmer_Guide/Command_Reference_Intro
sort=asc
sortby=title
showpath=no
liststyle=unordered
kidsonly=yes
></splist>

== Commands ==
<splist
parent=
sort=asc
sortby=title
showpath=no
liststyle=unordered
kidsonly=yes
></splist>

== Global Options ==

<splist
parent=Programmer_Guide/Command_Reference_Options
sort=asc
sortby=title
showpath=no
liststyle=unordered
kidsonly=yes
></splist>

Programmer Guide/Command Reference

2011-03-22T16:35:54Z

Admin:

The Command Reference documents all the commands available in the S_TOOLS-STx macro language. This is with the notable exception of the shell item commands, which are documented in the chapter Shell Items.

Note that all S_TOOLS-STx commands store their return code in the shell variable <code>rc</code>. See Shell Environment for more details. This is in contrast to all [[User Guide/Workspace/Waveform & Segmentation Viewer pre-configured profiles|MACRO]] commands which store their exit value in the variable <code>result</code>.

== Intro ==

<splist
parent=Programmer_Guide/Command_Reference_Intro
sort=asc
sortby=title
showpath=no
liststyle=unordered
kidsonly=yes
></splist>

== Commands ==
<splist
parent=
sort=asc
sortby=title
showpath=no
liststyle=unordered
kidsonly=yes
></splist>

== Global Options ==

<splist
parent=Programmer_Guide/Command_Reference_Options
sort=asc
sortby=title
showpath=no
liststyle=unordered
kidsonly=yes
></splist>

Programmer Guide/Command Reference

2011-03-22T16:35:25Z

Admin: /* Options */

The Command Reference documents all the commands available in the S_TOOLS-STx macro language. This is with the notable exception of the shell item commands, which are documented in the chapter Shell Items.

Note that all S_TOOLS-STx commands store their return code in the shell variable <code>rc</code>. See Shell Environment for more details. This is in contrast to all [[User Guide/Workspace/Waveform & Segmentation Viewer pre-configured profiles|MACRO]] commands which store their exit value in the variable <code>result</code>.

== Commands ==
<splist
parent=
sort=asc
sortby=title
showpath=no
liststyle=unordered
kidsonly=yes
></splist>

== Global Options ==

<splist
parent=Programmer_Guide/Command_Reference_Options
sort=asc
sortby=title
showpath=no
liststyle=unordered
kidsonly=yes
></splist>

Programmer Guide/Command Reference Options

2011-03-22T16:34:47Z

Admin: Created page with '<splist parent= sort=asc sortby=title showpath=no liststyle=unordered kidsonly=yes ></splist>'

Programmer Guide/Command Reference/NEW

2011-03-22T16:34:07Z

Admin:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}

NEW <var>itemtype</var> <var>itemname</var> [ [[Programmer_Guide/Command_Reference_Options/Silent|/I]] ] [ /U|/u ] [ /G ] [ /Z ] [ <var>createargs</var> [ <var>createopts</var> ] ]

The <code>NEW</code> command creates a new [[Programmer_Guide/Shell_Items|shell item]] of the type <var>itemtype</var> and named <var>itemname</var>.

;<var>itemtype</var>: The type of the new [[Programmer_Guide/Shell_Items|shell item]]. This must be unique (in the item namespace of a shell).
;<var>itemname</var>: The name of the new [[Programmer_Guide/Shell_Items|shell item]]. If this argument is set to the character '''*''', the name is choosen automatically.
;<var>createargs</var>: Arguments specifying parameters for the initialization of the new item. The format and meaning of these arguments are depending on the type of the new [[Programmer_Guide/Shell_Items|shell item]].
;<code>/I</code>: Enable [[Programmer_Guide/Command_Reference_Options/Silent|silent error reporting]]. If specified, <code>NEW</code> will generate a warning rather than an error if arguments are missing or it is unable create the new item.
;<code>/G</code>: Garbage collection. If specified, a temporary (or local) item created, which is automatically deleted when exiting the macro.
;<code>/U</code>: If specified, the global item protection is enabled. This means all items created before this item (called the protection-master) are proteced from being deleted, until the global item protection is disabled, which is done by deleting the protection-master). Protected items can only be deleted using a special option of the [[Programmer_Guide/Command_Reference/DELETE|delete command]]. Note: This option is case-sensitive.
;<code>/u</code>: If specified, the created item protected from being deleted. , until the global item protection is disabled, which is done by deleting the protection-master). Note: This option is case-sensitive.
;<code>/z</code>

Programmer Guide/Command Reference/NEW

2011-03-22T16:33:03Z

Admin:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}

NEW <var>itemtype</var> <var>itemname</var> [ [[Programmer_Guide/Command_Reference_Options/Silent|/I]] ] [ /U|/u ] [ /G ] [ <var>createargs</var> ] [ <var>createopts</var> ] ]

The <code>NEW</code> command creates a new [[Programmer_Guide/Shell_Items|shell item]] of the type <var>itemtype</var> and named <var>itemname</var>.

;<var>itemtype</var>: The type of the new [[Programmer_Guide/Shell_Items|shell item]]. This must be unique (in the item namespace of a shell).
;<var>itemname</var>: The name of the new [[Programmer_Guide/Shell_Items|shell item]]. If this argument is set to the character '''*''', the name is choosen automatically.
;<var>createargs</var>: Arguments specifying parameters for the initialization of the new item. The format and meaning of these arguments are depending on the type of the new [[Programmer_Guide/Shell_Items|shell item]].
;<code>/I</code>: Enable [[Programmer_Guide/Command_Reference_Options/Silent|silent error reporting]]. If specified, <code>NEW</code> will generate a warning rather than an error if arguments are missing or it is unable create the new item.
;<code>/G</code>: Garbage collection. If specified, a temporary (or local) item created, which is automatically deleted when exiting the macro.
;<code>/U</code>: If specified, the global item protection is enabled. This means all items created before this item (called the protection-master) are proteced from being deleted, until the global item protection is disabled, which is done by deleting the protection-master). Protected items can only be deleted using a special option of the [[Programmer_Guide/Command_Reference/DELETE|delete command]]. Note: This option is case-sensitive.
;<code>/u</code>: If specified, the created item protected from being deleted. , until the global item protection is disabled, which is done by deleting the protection-master). Note: This option is case-sensitive.
;<code>/z</code>

Programmer Guide/Command Reference/DELETE

2011-03-22T16:31:38Z

Admin:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
DELETE [ [[Programmer_Guide/Command_Reference_Options/Variables|/Variables]] ] [/unprotect] [ [[Programmer_Guide/Command_Reference_Options/Silent|/Silent]] ] [ [[Programmer_Guide/Command_Reference_Options/-|/-]] ] <var>itemname1</var> [ <var>itemname2...</var> ]

The <code>DELETE</code> command deletes the specified shell items <var>itemname1</var>, <var>itemname2</var>, and so on. Some types of shell items (e.g. SPU items) cannot be deleted while they are active, causing an error to be emitted. If a display item is deleted, all items contained in the display are removed too (i.e. graphs and dialogs items). If a dialog item contained in a 'dialog only' display item is deleted, the display item is also removed. If a DDE-conversation item (DDEConv) is removed, the conversation is ended before the item is deleted.

;<var>itemname</var>: The name of the shell item to delete.
;<code>/Silent</code>: If specified, <code>DELETE</code> will generate a warning rather than an error if arguments are missing or it is unable delete the arguments.
;<code>/unprotect</code> (case-sensitive!): If specified, <code>DELETE</code> will remove any protection from the respective item before deleting. This is the only way of deleting a [[Programmer_Guide/Protected_item|protected shell item]]. Note that, unlike most other options, the <code>/unprotect</code> option is case-sensitive meaning that you have to use the ''lower-case'' letter '''u'''.
;<code>/Variables</code>: Indicates that the <var>itemname1</var>...<var>itemnamen</var> arguments are variable names. In this case, each itemname is interpreted as the name of a shell item. The respective shell items are deleted, and the variables are then reset to empty.

// create a table item called "hugoItem", and store
// this name in a variable called "#hugo"
#hugo := new table hugoItem

// table item "hugoItem" will be deleted *and* "#hugo" will be cleared
delete /Var #hugo

Programmer Guide/Command Reference Options/Variables

2011-03-22T16:30:44Z

Admin: moved Programmer Guide/Command Reference Intro/Variables to Programmer Guide/Command Reference Options/Variables

Many STx commands expecting the name of an STx item as their arguments support the <code>/Variables</code> option. This option indicates that the arguments to the respective command are the names of STx variables, each containing the name of an STx item to delete. In this case, not only the respective items are being deleted, but also the respective variables are then reset to empty.

Programmer Guide/Command Reference Options/Silent

2011-03-22T16:30:19Z

Admin: moved Programmer Guide/Command Reference Intro/Silent to Programmer Guide/Command Reference Options/Silent

Many STX commands support the <code>/Silent</code> option. Where available, this option leads to exceptional situations being reported as warnings instead of errors.

Notes:
* There are a few commands where, before introducing the ''silent'' option, the <code>/S</code> flag had already been assigned to a different option. In order not to break existing user code, for the respective commands, the ''silent'' flag is indicated by a different letter (e.g. <code>/L</code> for the [[Programmer_Guide/Command_Reference/LOAD|LOAD]] command or <code>/I</code> for the [[Programmer_Guide/Command_Reference/NEW|NEW]]).
* Since version 4.0 the general flag <code>/?</code> can be used to specifiy the ''silent'' option. This general flag was implemeted to simpliy script programming.

Programmer Guide/Command Reference Options/-

2011-03-22T16:29:56Z

Admin: moved Programmer Guide/Command Reference Intro/- to Programmer Guide/Command Reference Options/-

The <code>/-</code> ''end of options'' switch is available for every S_TOOLS-STx command that accepts flags. With the ''end of options'' switch, you indicate that any following arguments should be interpreted as plain arguments, even if they should start with a slash.

For example, the following command will cause an error:
WRITELOG This /command/ will cause an error
The reason is that the slash in front of the string <code>/command/</code> causes the string to be interpreted as the option <code>/C</code>, and there is no such option for the <code>[[Programmer_Guide/Command_Reference/WRITELOG|WRITELOG]]</code> command. (And if there were, the text shown by the respective <code>WRITELOG</code> would be "This will cause an error".)

To make the above example work (and, especially, actually show the string "This /command/ works"), you will have to use the following statement:
WRITELOG /- This /command/ works

Programmer Guide/Command Reference

2011-03-22T16:28:55Z

Admin: /* Commands */

Programmer Guide/Command Reference

2011-03-22T16:28:39Z

Admin:

Programmer Guide/Command Reference

2011-03-22T16:28:25Z

Admin:

Programmer Guide/Command Reference/DELETE

2011-03-22T16:26:03Z

Admin:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
DELETE [ [[Programmer_Guide/Command_Reference_Intro/Variables|/Variables]] ] [/unprotect] [ [[Programmer_Guide/Command_Reference_Intro/Silent|/Silent]] ] [ [[Programmer_Guide/Command_Reference_Intro/-|/-]] ] <var>itemname1</var> [ <var>itemname2...</var> ]

The <code>DELETE</code> command deletes the specified shell items <var>itemname1</var>, <var>itemname2</var>, and so on. Some types of shell items (e.g. SPU items) cannot be deleted while they are active, causing an error to be emitted. If a display item is deleted, all items contained in the display are removed too (i.e. graphs and dialogs items). If a dialog item contained in a 'dialog only' display item is deleted, the display item is also removed. If a DDE-conversation item (DDEConv) is removed, the conversation is ended before the item is deleted.

;<var>itemname</var>: The name of the shell item to delete.
;<code>/Silent</code>: If specified, <code>DELETE</code> will generate a warning rather than an error if arguments are missing or it is unable delete the arguments.
;<code>/unprotect</code> (case-sensitive!): If specified, <code>DELETE</code> will remove any protection from the respective item before deleting. This is the only way of deleting a [[Programmer_Guide/Protected_item|protected shell item]]. Note that, unlike most other options, the <code>/unprotect</code> option is case-sensitive meaning that you have to use the ''lower-case'' letter '''u'''.
;<code>/Variables</code>: Indicates that the <var>itemname1</var>...<var>itemnamen</var> arguments are variable names. In this case, each itemname is interpreted as the name of a shell item. The respective shell items are deleted, and the variables are then reset to empty.

// create a table item called "hugoItem", and store
// this name in a variable called "#hugo"
#hugo := new table hugoItem

// table item "hugoItem" will be deleted *and* "#hugo" will be cleared
delete /Var #hugo

Programmer Guide/Command Reference Options/-

2011-03-22T16:25:27Z

Admin: moved Programmer Guide/Command Reference/- to Programmer Guide/Command Reference Intro/-

Programmer Guide/Command Reference/DELETE

2011-03-22T16:24:36Z

Admin:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
DELETE [ [[Programmer_Guide/Command_Reference_Intro/Variables|/Variables]] ] [/unprotect] [ [[Programmer_Guide/Command_Reference_Intro/Silent|/Silent]] ] [ [[Programmer_Guide/Command_Reference/-|/-]] ] <var>itemname1</var> [ <var>itemname2...</var> ]

The <code>DELETE</code> command deletes the specified shell items <var>itemname1</var>, <var>itemname2</var>, and so on. Some types of shell items (e.g. SPU items) cannot be deleted while they are active, causing an error to be emitted. If a display item is deleted, all items contained in the display are removed too (i.e. graphs and dialogs items). If a dialog item contained in a 'dialog only' display item is deleted, the display item is also removed. If a DDE-conversation item (DDEConv) is removed, the conversation is ended before the item is deleted.

;<var>itemname</var>: The name of the shell item to delete.
;<code>/Silent</code>: If specified, <code>DELETE</code> will generate a warning rather than an error if arguments are missing or it is unable delete the arguments.
;<code>/unprotect</code> (case-sensitive!): If specified, <code>DELETE</code> will remove any protection from the respective item before deleting. This is the only way of deleting a [[Programmer_Guide/Protected_item|protected shell item]]. Note that, unlike most other options, the <code>/unprotect</code> option is case-sensitive meaning that you have to use the ''lower-case'' letter '''u'''.
;<code>/Variables</code>: Indicates that the <var>itemname1</var>...<var>itemnamen</var> arguments are variable names. In this case, each itemname is interpreted as the name of a shell item. The respective shell items are deleted, and the variables are then reset to empty.

// create a table item called "hugoItem", and store
// this name in a variable called "#hugo"
#hugo := new table hugoItem

// table item "hugoItem" will be deleted *and* "#hugo" will be cleared
delete /Var #hugo

Programmer Guide/Command Reference/COND

2011-03-22T16:23:58Z

Admin:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
The <code>COND</code> command performs a conditional assignment.

Generally, the conditional assignment takes the following form:
target := COND condition ? expr1 : expr2

;<code>target</code>: is a normal assignment target, usually the name of an S_TOOLS-STx variable, e.g. <code>#var</code>.
;<code>condition</code>: is a [[Programmer_Guide/Command_Reference_Intro/condition|conditional expression]] like used with the <code>[[User Guide/Workspace/Parameter Processing|IF]]</code> statement and the miscellaneous loop commands, e.g. the string <code>$#a == 7 || $#a == 42</code> (for more examples, see the <code>[[User Guide/Workspace/Parameter Processing|IF]]</code> statement).
:Note that with conditional S_TOOLS-STx expressions there must always be intervening whitespaces between operators and their arguments (unless the argument is quoted). So, both <code>$#a == 7</code> and <code>'$#a'=='7'</code> are valid expression, whereas <code>$#a==7</code> is not.
;<code>expr1</code> and <code>expr2</code>: Both <code>expr1</code> and <code>expr2</code> may be any expressions that may be normally used in an S_TOOLS-STx <code>:=</code> assignment, with the only exception of a <code>COND</code> expression (meaning that conditional assignments must not be nested for the time being). If, at runtime, the conditional expression <code>condition</code> evaluates to truth, the value determined by the first expression, <code>expr1</code>, will be assigned to <code>target</code>. If <code>condition</code> evaluates to falsehood, it will be the second expression, <code>expr2</code>, that gets assigned to target.

You may use any S_TOOLS-STx [[Programmer_Guide/Command_Reference_Intro/condition|conditional expression]] you like for <code>condition</code>. Equally, there is no restriction on <code>expr1</code> and <code>expr2</code>, except that they must not be built up from <code>COND</code> expressions themselves. It is even (and also) possible to use command substitutions (<code>$(...)</code>), nesting them as deeply as one feels inclined to.

=== Notes ===
* The <code>COND</code> command is processed by the loader, and is therefore not available in the command line interface.
* The <code>COND</code> command may not contain a nested <code>COND</code> command.

=== Examples ===
#min := cond $#a < $#b ? $#a : $#b // calculate minimum of #a and #b
#abs := cond $#a < 0 ? num -$#a : $#a // calculate absolute value of #a
#abs := cond $#a < 0 ? eval $#a*(-1) : $#a // an alternative to the above
#absdiff := cond $#a > $#b ? eval $#a-$#b : eval $#b-$#a // absolute difference
#len := cond $(length $#a) > 0 ? length $#a : length $#b // length of #a or, if empty, of #b
See the file <code>conditional_assignment.sts</code> for further working examples.

Programmer Guide/Command Reference/FOR

2011-03-22T16:23:30Z

Admin: /* FOR */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
==FOR==

<code>FOR [ <var>target</var> := <var>init</var> ] TO <var>cond</var> STEP <var>step</var> // commands
END</code>

Excecute the commands in the FOR loop while the condition holds true.

;<var>target</var>

:The incremental counter variable to initialize with the value <var>init</var> (e.g. #i).

;<var>init</var>

:The value with which to initialize the counter variable <var>target</var> (e.g. 0).

;<var>cond</var>

:The condition which should be tested at the start of each loop (e.g. $#i < 10). See the [[Programmer Guide/Command Reference Intro/condition|condition]] topic for the condition syntax.

;<var>step</var>

:The incremental value to add to the counter variable <var>target</var> at the end of each loop. The assignment syntax (e.g. #i := int $#i+1) is allowed.

<pre>
FOR #i := 0 TO $#i < 10 STEP #i := int $#i+1
BUTIL MSGBOX MSG; #i = $#i
END
// an example without initialisation
FOR TO $#x > $#y STEP #i := int $#i + 1
// do something here ...
END
</pre>

Programmer Guide/Command Reference/IF

2011-03-22T16:23:15Z

Admin: /* IF */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
==IF==

There are two forms of the <code>IF</code> syntax. The first allows the conditional execution of one command. The second allows conditional execution of multiple command within a block.

<code>IF <var>condition command</var></code>

<code>IFNOT <var>condition command</var></code>

Conditional execution of a command. For more information on conditions see [[Programmer Guide/Command Reference_Intro/condition|condition]].

<code>IF condition THEN</code>

<code>...</code>

<code>ELSE IF condition THEN</code>

<code>...</code>

<code>ELSE IFNOT condition THEN</code>

<code>...</code>

<code>ELSE</code>

<code>...</code>

<code>END</code>

Conditional execution of command blocks. Only the <code>IF</code> clause is necessary, all others are optional. Both command forms <code>IF</code> and <code>IFNOT</code> can be used. Empty clauses (without commands) are allowed. The last clause must be closed with <code>[[Programmer Guide/Command Reference/END|END]]</code>. For more information on conditions see [[Programmer Guide/Command Reference/condition|condition]].

Programmer Guide/Concepts/Conditional Expressions

2011-03-22T16:22:33Z

Admin: moved Programmer Guide/Command Reference/condition to Programmer Guide/Command Reference Intro/condition

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
All commands using conditions (<code>[[Programmer_Guide/Command_Reference/IF|IF]]</code>, <code>[[Programmer Guide/Command Reference/DO|DO]]</code>, <code>[[Programmer_Guide/Command_Reference/WHILE|WHILE]]</code>) use the same syntax and evaluation rules. A condition consists of one or more comparisons which are joined with logical (binary) operators. Each comparison compares two values and can evaluate to true or false.
<var>condition</var> = <var>comparison</var> [<var>loperator comparison loperator</var> .. <var>comparison loperator</var>]
;<var>comparison</var>: A comparison comprising two expressions separated by a comparison operator. There are two types of comparison supported - see below for comparison operators for details. Both types of comparison can be used within one <code>IF</code> command.
;<var>loperator</var>: A logical operator, which combines the results of two comparisons. Logical operators are evaluated strictly from left to right; bracketing is not possible; it is explicitly ''undefined'' if a part of an expression that is strictly not required for judging on the truth, or falshood, of the whole expression, gets evaluated, or not.

===Logical Operators===

The logical operators supported by S_TOOLS-STx conditional commands are the following:
;<code>AND</code>: returns true if both comparison results are true
;<code>&&</code>: the same as <code>AND</code>
;<code>OR</code>: returns true if either of the comparison results are true
;<code><nowiki>||</nowiki></code>: the same as <code>OR</code>
* Logical operators are evaluated strictly from left to right.
* Bracketing is ''not'' possible.
* It is explicitly undefined if a part of an expression that is strictly not required for judging on the truth, or falshood, of the whole expression, gets evaluated, or not. So you should ''not'' use expressions with side-effects.

===Comparison Operators===

S_TOOLS-STx supports two types of comparison operator:
# Simple comparison operators for numerical expression and case-insensitive string comparisons<code>.</code>
# Pattern matching operators using wild-cards or regular expressions. These pattern matching operators may be applied to strings or, more specifically, to S_TOOLS-STx names.
The general syntax for a comparison is as follows:
<var>expression</var> <var>operator</var> <var>expression</var>

;<var>expression</var> :A numerical expression or a string.
;<var>operator</var>: A comparison operator (see below).

====Simple Comparison====

A simple comparison will be numerical if both arguments are numerical. Otherwise, a case-insensitive string comparison will be performed.

There are the following simple comparison operators:
; <code>==</code> : evaluates to true if both sides are equal.
; <code>!=</code> : evaluates to true if sides are not equal
; <code><</code> : evaluates to true if the left hand side is less than the right hand side
; <code>></code> : evaluates to true if the left hand side is greater than the right hand side
; <code><=</code> : evaluates to true if the left hand side is less than or equal to the right hand side
; <code>>=</code> : evaluates to true if the left hand side is greater than or equal to the right hand side

====Pattern Matching====

The general syntax of a pattern-matching comparison is:
string operator mask
For example:
'the quick brown fox' !SI '*brown*' // search for the word 'brown' in the left hand side string

Note that, instead of a string, the argument to a pattern matching comparison may also be an S_TOOLS-STx name, i.e. a string subject to the syntax restrictions for S_TOOLS-STx names. You can discern the full string comparison operators from the name comparison operators by there second character which is "S" for string comparison (e.g. <code>!SI</code>), and "N" for name comparison (e.g. <code>!NI</code>).

There are two types of pattern matching supported by S_TOOLS-STx conditional commands:
# Wild-card pattern matching
# POSIX regular expression pattern matching

===== Wild-card pattern matching =====

{|
|-
|<code>=SI</code>
|returning true if string matches pattern, ignoring the case
|-
|<code>!SI</code>
|returning true if string does not match pattern, ignoring the case
|-
|<code>=SR</code>
|returning true if the string matches the pattern, respecting the case
|-
|<code>!SR</code>
|returning true if the string does not match the pattern, respecting the case
|-
|<code>=NI</code>
|returning true if name matches pattern, ignoring the case
|-
|<code>!NI</code>
|returning true if name does not match pattern, ignoring the case
|-
|<code>=NR</code>
|returning true if the name matches the pattern, respecting the case
|-
|<code>!NR</code>
|returning true if the name does not match the pattern, respecting the case
|}

===== POSIX regular expression pattern matching =====

{|
|-
|<code>=RSI</code>
|returns true if the string matches the regular expression, ignoring case
|-
|<code>!RSI</code>
|returns true if string does not match the regular expression, ignoring the case
|-
|<code>=RSR</code>
|returns true if the string matches the regular expression, respecting case
|-
|<code>!RSR</code>
|returns true if the string does not match the regular expression, respecting the case
|-
|<code>=RNI</code>
|returns true if the name matches the regular expression, ignoring case
|-
|<code>!RNI</code>
|returns true if name does not match the regular expression, ignoring the case
|-
|<code>=RNR</code>
|returns true if the string matches the regular expression, respecting case
|-
|<code>!RNR</code>
|returns true if the name does not match the regular expression, respecting the case
|}

Regular expressions make heavy use of characters that have a special meaning for S_TOOLS-STx. In order to use such characters, you need to escape them with the S_TOOLS-STx escape character, "<code>`</code>" (back-tick). The S_TOOLS-STx regular expressions are implemented using the [http://laurikari.net/tre/ TRE library].

===Examples===

For an example of regular expression in use, see the example script file <code>regular_expressions.sts</code>.

Programmer Guide/Command Reference Options/Variables

2011-03-22T16:22:19Z

Admin: moved Programmer Guide/Command Reference/Variables to Programmer Guide/Command Reference Intro/Variables

Programmer Guide/Command Reference

2011-03-22T16:21:14Z

Admin:

Programmer Guide/Command Reference

2011-03-22T16:20:53Z

Admin:

Programmer Guide/Command Reference/EVAL

2010-12-03T16:30:53Z

Admin:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
'''Contents'''

<splist
parent=
sort=asc
sortby=title
showpath=no
liststyle=unordered
kidsonly=yes
>

User Guide

2010-12-03T16:27:17Z

Admin: Created page with '{{DISPLAYTITLE:{{SUBPAGENAME}}}} '''Contents''' <splist parent= sort=asc sortby=title showpath=no liststyle=unordered kidsonly=yes >'

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
'''Contents'''

<splist
parent=
sort=asc
sortby=title
showpath=no
liststyle=unordered
kidsonly=yes
>

Main Page

2010-12-03T14:44:43Z

Admin:

STX

[http://mediawiki.kfs.oeaw.ac.at/stx/index.php/User_Guide User Guide]

[http://mediawiki.kfs.oeaw.ac.at/stx/index.php/Programmer_Guide Programmer Guide]

[http://mediawiki.kfs.oeaw.ac.at/sysadmin Sysadmin Wiki]

Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using the wiki software.

== Getting started ==
* [http://www.mediawiki.org/wiki/Manual:Configuration_settings Configuration settings list]
* [http://www.mediawiki.org/wiki/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list]

Main Page

2010-12-03T14:44:32Z

Admin:

STX

[http://mediawiki.kfs.oeaw.ac.at/stx/index.php/User_Guide User Guide]

[http://mediawiki.kfs.oeaw.ac.at/stx/index.php/Programmer_Guide User Guide]

[http://mediawiki.kfs.oeaw.ac.at/sysadmin Sysadmin Wiki]

Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using the wiki software.

== Getting started ==
* [http://www.mediawiki.org/wiki/Manual:Configuration_settings Configuration settings list]
* [http://www.mediawiki.org/wiki/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list]

Main Page

2010-11-25T09:20:35Z

Admin:

STX

[http://mediawiki.kfs.oeaw.ac.at/stx/index.php/User_Guide User Guide]

Programmer Guide

[http://mediawiki.kfs.oeaw.ac.at/sysadmin Sysadmin Wiki]

Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using the wiki software.

== Getting started ==
* [http://www.mediawiki.org/wiki/Manual:Configuration_settings Configuration settings list]
* [http://www.mediawiki.org/wiki/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list]

Programmer Guide

2010-11-25T09:20:33Z

Admin:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
'''Contents'''

<splist
parent=
sort=asc
sortby=title
showpath=no
liststyle=unordered
kidsonly=yes
>

Programmer Guide/Programming a Toolbox

2010-11-18T16:32:19Z

Admin:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
'''Contents'''

<splist
parent=
sort=asc
sortby=title
showpath=no
liststyle=unordered
kidsonly=yes
>

Programmer Guide/Programming a Toolbox/Example Toolbox function

2010-11-18T16:31:59Z

Admin: 1 revision: Initial import

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
==Example Toolbox function==

The function <code>ExportSegmentsToSoundfiles</code> exports the selected segments from the Workspace Detail to individual soundfiles. It is only available in the DataSet context.

<pre>
//{{3.7.0 849}{2005.05.30 15.31.20} - automatically created version information - do not change or delete this line}

/*
This is a Toolbox definition and implementation file. Load this file into the
STx via the Special->Toolbox Function menu.
*/

/*++-------------------------------------------------------------------------//
Function: ExportSegmentsToSoundfiles
Usage: This is a Toolbox function definition and is called
by the Toolbox manager.
Description: The user can select segments in the Workspace Detail and
export them to individual soundfiles (one per segment).
By default, soundfiles are exported to the same directory
as the segment's soundfile is in and sequences are exported
to the working directory.
Author: Jonnie White
History: 2005-06-03 jw Created
2005-09-21 jw Version: 1.0
--*/
[Function ExportSegmentsToSoundfiles]
// Hotkey ; Command ; Type ; Context ; Applications
* ; ExportSegmentsToSoundfiles ; macro ; dataset ; *
// Description
Export the selected segments to individual soundfiles
// Setup Variables
//
// Variable: AddToDataset
// Values: 0|1
// 0 - Do not add files to the dataset
// 1 - Ask the user if they want to add files to the dataset)
AddToDataset = 1
// Variable: PathFlags
// Values: 0|1|2|3
// 0 - The path should be the same as the source file. The
// value of Path is ignored.
// 1 - The value of Path should be used, or if Path is empty,
// the path of the sourcefile should be used.
// 2 - The path should be chosen by the user and used for
// all segements
// 3 - The user should choose a path for each segment.
PathFlags = 0
// Variable: Path
// Values: empty or a valid directory path
Path =
// Variable: FileNameFormat
// Values: String constants and the keywords <soundfile> and <segment> which
// are replaced with the soundfile ID and the segment ID
// respectively.
FileNameFormat = <soundfile>.<segment>

/*++-------------------------------------------------------------------------//
Macro: ExportSegmentsToSoundfiles
Usage: This is a Toolbox function implementation macro for the DataSet
context
Description: This Toolbox function is called in the Dataset context and
exports any selected segments to soundfiles. The user can
choose the file name format for the soundfiles which will be
created.
Author: Jonnie White
History: 2005-06-03 jw Created
--*/
[Macro ExportSegmentsToSoundfiles]
// Parses the arguments depending on the context.
// This must be the first command
$@TBPARSE '$#argv'
// Loads the settings (if any are defined)
$@TBLOADSETUP

// if there are selected segments in the DataSet context table #etab
if '$#etab[?]' == 'table' && '$#etab[]' > 0 && '$#etag' == 'aseg' then
$BDataset Attach // attach the dataset for the duration of this function
// save the position so we can restore it at the end of the function
#origPos := $($BDataset SavePos)
#tFiles := new table * // Add new file paths to this table
while '$#etab[]' > 0 // if the user has selected any segments
$BDataset SelectASeg * ; $#etab[0] // select the segment
if '$result' == 0 then
// get information about the audio set the segment is in
readstr '$($BDataset GetASetInfo)' #';'#ASetId';'#';'#';'#ASetFilePath /Delete
// get information about the id of the segment
readstr '$($BDataset GetSegment $#ASetIRef ; * ; ID)' #ASegId';'# /Delete
// select the output path depending on the user's settings
gosubx _SelectOutputPath
// format the output path depending on the user's settings
#file := $#OutputPath'\'$(gosubx _FormatFileName $#ASetId;$#ASegId).wav
// create a wave item based on this segment and save it to file
#wsrc := $($BDataset CreateWave '$#ASetIRef ; $#ASegId ; *')
if '$#wsrc[?]' == wave then
if '$(bsf 'open $#file;create;~$#wsrc[!srate];~$#wsrc[!channels]')' == 0 then
#wdst := $(new wave * 0_~$#wsrc[!length])
if $rc == 0 then
if $($#wsrc copy $#wdst) == 0 $#tFiles * $#file
delete $#wdst
end
bsf 'close $#file'
else
BUtil 'Msgbox Msg; Failed to create the file $#file ; ToolBox $#mac Error!'
end
$BDataset deletewave $#wsrc
else
BUtil 'Msgbox Msg; Create waveitem failed! ; ToolBox $#mac Error!'
end
end
$#etab 0 /Delete
end
// Give the user the option to add the new soundfiles to the project.
if '$#AddToDataset' > 0 then
readstr '$($BDataset DialogSelectElement Select target set for new soundfiles; single; iref; Set; 1)' #targetSetRef
if '$#read' > 0 then
while $#tFiles[] > 0
$BDataset AddASet '$#tFiles[0];$#targetSetRef;*'
$#tFiles 0 /Delete
end
DatasetCmd RefreshAll
end
end

$BDataset SelectIRef $#origPos
$BDataset SavePos $#origPos
$BDataset Detach
else
BUtil 'MsgBox Msg; Please select at least one segment and try again.; ToolBox $#mac Error!'
end

$@TBSAVESETUP // Save the settings (if any were changed)
exit 1 int $#changed // #changed must be set to 1 if any data was changed (otherwise 0)

// The user can determine what the filename should look like, using
// the keywords <soundfile> and <segment>. This function formats
// the filename.
_FormatFileName:
readvar #argv #soundfile';'#segment
if '$#read' != 2 em -1 ; Not enough argument in $#mac
#name := $#FileNameFormat
readstr '$#name' #before'<soundfile>'#after /Delete
if '$#read' > 0 && '$#before' != '$#name' #name := $#before'$#soundfile'$#after
readstr '$#name' #before'<segment>'#after /Delete
if '$#read' > 0 && '$#before' != '$#name' #name := $#before'$#segment'$#after
exit 1 set '$#name'

// Select the output path based on the user's settings.
_SelectOutputPath:
if '$#PathFlags' == 0 || '$#PathFlags' == 1 then
// User settings path
if '$#PathFlags' == 1 && '$#Path' != '' then
#OutputPath := $(BUtil GetDirectory $#Path)
if '$#OutputPath' != '$#Path' then
#Path := $(Butil DirectoryDialog Please select an existing directory ; $#Path ; Yes ; No ; No)
if '$#Path' != '' then
#OutputPath := $#Path
else
exit 2 // User has failed to select a path, so we will export nothing.
end
end
// Automatic output path
else
if '$#ASetFilePath' != '' then // AFile
readstr '$(FileToolBox Tokenize $#ASetFilePath)' #drive';'#dir';'#name';'#ext /Delete
#OutputPath := '$#drive':'$#dir'
else // ASeq: sequences are stored in the @WORK directory by default
#OutputPath := $@WORK'\'
end
end
else if '$#PathFlags' == 2 || '$#PathFlags' == 3 then
if '$#OutputPath' == '' || '$#PathFlags' == 3 then
#OutputPath := $(butil 'directorydialog Export path for soundfiles; *; No; No; No')
end
end
exit
</pre>

Programmer Guide/Programming a Toolbox/Toolbox function implementation

2010-11-18T16:31:58Z

Admin: 1 revision: Initial import

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
==Toolbox function implementation==

The Toolbox function implementation takes place in a macro:

<pre>
[MACRO tools]readvar #argv #function #argv /Dgoto cmd$#function noCmdnoCmd: exit
cmdFunction1:$@TBPARSE '$#argv' // Parses the arguments depending on the context. This must be the first command$@TBLOADSETUP // Loads the settings (if any are defined)/*... the function code ...*/$@TBSAVESETUP // Save the settings (if any were changed)exit 1 int $#changed // #changed must be set to 1 if any data was changed (otherwise 0)
</pre>
The function <code>@TBPARSE</code> must be the first command in the macro function. <code>@TBPARSE</code> and <code>@TBLOADSETUP</code> convert the calling arguments and the settings into local variables.

====@TBPARSE====

The Toolbox function <code>@TBPARSE</code> creates the following local variables:

{|
|-
|<code>#keyword</code>
|The name of the calling context.
|-
|<code>#function</code>
|The name of the function which was called.
|}

If a failure occurs when parsing, the Toolbox function is exited.

====@TBLOADSETUP====

The Toolbox function <code>@TBLOADSETUP</code> creates local variables for all setup variable definitions in the [[User Guide/Toolbox/Toolbox function definition|function definition]]. Every <code>varname = varvalue</code> entry is converted into a local variable <code>#varname</code> with the value <code>varvalue</code>. Setup variables can be saved using the Toolbox function <code>@TBSAVESETUP</code>. The setup variables are stored in the S_TOOLS-STx INI file.

====@TBSAVESETUP====

The Toolbox function <code>@TBSAVESETUP</code> saves all modified setup variables in the current S_TOOLS-STx INI file.