Toolbox function definition
A Toolbox function definition defines the interface between the STx Toolbox management routines and the macro where the data processing takes place. If you want to program a Toolbox function for STx, you must first define the function in the Toolbox function format:
[FUNCTION name] hotkey ; command ; type ; context ; applications description varname = varvalue
The parameters must be interpreted as follows:
name
|
The name of the function. This appears in the Toolbox list in the S_TOOLS-STx GUI. |
hotkey
|
The default hotkey to associate with this function or an asterisk if no hotkey should be used. |
command
|
The command to call when the Toolbox function is called. This may be a macro function, a class name or an application name. The class or macro must be defined in the same file as the function definition. |
type
|
The type of command call (APPLICATION|CLASS|MACRO). An APPLICATION call means a new application is started. A CLASS call means the class is instantiated. The class must inherit from tbmgr. A MACRO call means the command call is made in the application shell.
|
context
|
The blank separated list of contexts in which this function will be available (an asterisk means that the function is available in all contexts). |
applications
|
The blank separated list of application names in which this function should be available (an asterisk means that the function is available in all applications). |
description
|
The description to be displayed in the Toolbox function list. |
varname = varvalue
|
Variable definitions: assign the variable varname the value varvalue. These variables can be loaded and saved between function calls and edited in the Toolbox GUI.
|
Note that you do not end a FUNCTION section with the EXIT command! Please note also, that variable assignment uses neither a colon nor a semi-colon!
Contents
Toolbox contexts
The following Toolbox contexts are defined in STx:
SPECTRUM PARAMETER WAVEFORM DATASET
The Toolbox management routines allow Toolbox functions to interact with STx in these contexts. The data available to you when the Toolbox function is called is dependant on the context. Therefore you must program your Toolbox implementation to take the context into account.
SPECTRUM
The Toolbox context SPECTRUM.
| Data: | A table of spectra. |
| Call type: | MACRO |
| Used in: | Spectrogram & Parameters Viewer Sectioner and Spectrum Viewer |
SPECTRUM variables and objects
The following variables and objects are available in the Toolbox SPECTRUM context:
#aset
|
The source signal audio-set reference. |
#aseg
|
The source signal segment for current analysis. |
#ach
|
The source signal's channel. |
#wave
|
The wave item containing the section of the source signal used to calculate the spectra. |
#data
|
The table containing all spectra (one column per analysis method). |
#defs
|
The configuration table: every analysis method is described in one line in the format 'method unit ref'. The variables #methodX, #unitX and #refX (where X is the #defs row index) are assigned the method, unit and ref respectively. See below for details.
|
#methodX
|
The transformation or analysis method (FFT, WAVE = Wavelet, CEPST, LPC, IRRTH, FFTP = FFT-Phase or WAVEP). |
#unitX
|
The value unit (dB or radPi). |
#refX
|
The reference value (only if necessary, e.g. for dB). |
The return value is ignored for this context (i.e. any changes are not displayed). The frequency scale of the spectra is assumed to be an equidistant scale over the whole bandwidth (i.e. 0 -> samplingRate / 2).
PARAMETER
The Toolbox context PARAMETER.
| Data: | A table of parameters in time. |
| Call type: | MACRO |
| Used in: | Spectrogram & Parameters Viewer |
PARAMETER variables and objects
The following variables and objects are available in the Toolbox PARAMETER context:
#aset
|
The source signal audio-set reference. |
#aseg
|
The source signal segment for current analysis. |
#ach
|
The source signal's channel. |
#wave
|
The wave item containing the signal between the time cursors. |
#data
|
The table containing all parameters (one column per function). |
#defs
|
The configuration table: every parameter function is described in one line in the format 'Type Name Unit Ref Graph Index Line IFun'.
|
Type
|
The parameter type. |
Name
|
The parameter name. |
Unit
|
The parameter unit. |
Ref
|
The reference value. |
| Graph | The id of the graph item containing this parameter |
| Index | The parameter index (zero-based). |
| Line | The line this parameter is on (top down). |
| IFun | The line color index (not zero-based). |
#fpos
|
The index of the first selected entry. |
#fnum
|
The number of selected entries. |
#lfrm
|
The analysis frame length in samples. |
#sfrm
|
The analysis frame distance in samples. |
#cpos1
|
The position of the first time cursor in the format 'frameindex xpos ypos'. The values are also assigned to local variables (e.g. for cursor 1 the variables #c1i, #c1x and #c1y are available).
|
#cpos2
|
The position of the second time cursor. Cursor 1 always has a lower xpos value than cursor 2. |
WAVEFORM
The Toolbox context WAVEFORM.
| Data: | Signal and metasegment information. |
| Call type: | MACRO |
| Used in: | Waveform & Segmentation Viewer |
WAVEFORM variables and objects
The following variables and objects are available in the Toolbox WAVEFORM context:
#aset
|
The source signal audio-set reference. |
#aseg
|
The source signal segment for current analysis. |
#ach
|
The source signal's channel. |
#wave
|
The wave item containing the signal between the time cursors. |
#graph
|
The name of the currently active graph item. |
#mslist
|
A list of the currently selected metasegments' ids. |
#fpos
|
The index of the first selected entry. |
DATASET
The Toolbox context DATASET.
| Data: | References to DataSet elements. |
| Call type: | MACRO and APPLICATION
|
| Used in: | Workspace |
DATASET variables and objects
The following variables and objects are available in the Toolbox DATASET context:
#type
|
The DataSet context (element, segment, aseglist, parameter, aparlist, set or signal).
|
#sref
|
The XML reference for the selected set. |
#stag
|
The XML tag for the selected set. |
If #type is segment, aseglist, parameter, aparlist or set then the following variables are defined:
#etab
|
A table with the XML positions of the selected elements in the set. |
#etag
|
The DataSet tag of all the selected elements or * if they have different tags.
|
If #type is signal then the following variables are defined:
#etag
|
A table with the indices of the selected sequence signals. |
Please note that the table #etab should be deleted at the end of the function. You can use the BXMLDOC function RESETPOS for this.
An XML position is a value returned by the command POSITION.
