Programmer Guide/Programming a Toolbox/Toolbox function definition: Difference between revisions
No edit summary |
No edit summary |
||
(12 intermediate revisions by 2 users not shown) | |||
Line 3: | Line 3: | ||
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: | 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: | ||
< | <pre> | ||
[FUNCTION name] | |||
hotkey ; command ; type ; context ; applications | hotkey ; command ; type ; context ; applications | ||
description | description | ||
varname = varvalue</ | varname = varvalue | ||
</pre> | |||
The parameters must be interpreted as follows: | The parameters must be interpreted as follows: | ||
Line 19: | Line 21: | ||
|- | |- | ||
|<code>command</code> | |<code>command</code> | ||
|The command to call when the Toolbox function is called. This | |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. | ||
|- | |- | ||
|<code>type</code> | |<code>type</code> | ||
|The type of command call (<code>MACRO</code> | |The type of command call (<code>APPLICATION</code><nowiki>|</nowiki><code>CLASS</code><nowiki>|</nowiki><code>MACRO</code>). An <code>APPLICATION</code> call means a new application is started. A <code>CLASS</code> call means the class is instantiated. The class must inherit from <code>tbmgr</code>. A <code>MACRO</code> call means the command call is made in the application shell. | ||
|- | |- | ||
|<code>context</code> | |<code>context</code> | ||
Line 37: | Line 39: | ||
|} | |} | ||
Note that you do not end a <code>FUNCTION</code> section with the <code>EXIT</code> command! Please note also, that variable assignment uses neither a colon nor a semi-colon!====Toolbox contexts==== | Note that you do not end a <code>FUNCTION</code> section with the <code>EXIT</code> command! Please note also, that variable assignment uses neither a colon nor a semi-colon! | ||
====Toolbox contexts==== | |||
The following Toolbox contexts are defined in {{STX}}: | The following Toolbox contexts are defined in {{STX}}: | ||
Line 63: | Line 67: | ||
|Spectrogram & Parameters Viewer Sectioner and Spectrum Viewer | |Spectrogram & Parameters Viewer Sectioner and Spectrum Viewer | ||
|} | |} | ||
======SPECTRUM variables and objects====== | ======SPECTRUM variables and objects====== | ||
Line 121: | Line 119: | ||
|Spectrogram & Parameters Viewer | |Spectrogram & Parameters Viewer | ||
|} | |} | ||
======PARAMETER variables and objects====== | ======PARAMETER variables and objects====== | ||
Line 146: | Line 142: | ||
|- | |- | ||
|<code>#defs</code> | |<code>#defs</code> | ||
|The configuration table: every parameter function is described in one line in the format '<code>Type Name Unit Ref Graph Index Line IFun</code>'. | |The configuration table: every parameter function is described in one line in the format '<code>Type Name Unit Ref Graph Index Line IFun</code>'. | ||
|- | |- | ||
|<code>Type</code> | |<code>Type</code> | ||
Line 171: | Line 167: | ||
|IFun | |IFun | ||
|The line color index (not zero<nowiki>-</nowiki>based). | |The line color index (not zero<nowiki>-</nowiki>based). | ||
|- | |- | ||
|<code>#fpos</code> | |<code>#fpos</code> | ||
Line 193: | Line 186: | ||
|The position of the second time cursor. Cursor 1 always has a lower xpos value than cursor 2. | |The position of the second time cursor. Cursor 1 always has a lower xpos value than cursor 2. | ||
|} | |} | ||
=====WAVEFORM===== | =====WAVEFORM===== | ||
Line 211: | Line 202: | ||
|Waveform & Segmentation Viewer | |Waveform & Segmentation Viewer | ||
|} | |} | ||
======WAVEFORM variables and objects====== | ======WAVEFORM variables and objects====== | ||
Line 241: | Line 230: | ||
|The index of the first selected entry. | |The index of the first selected entry. | ||
|} | |} | ||
=====DATASET===== | =====DATASET===== | ||
Line 259: | Line 246: | ||
|Workspace | |Workspace | ||
|} | |} | ||
======DATASET variables and objects====== | ======DATASET variables and objects====== |
Latest revision as of 15:40, 5 August 2019
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
.