STX Wiki - User contributions [en]

Programmer Guide/Command Reference/EVAL/interp

2025-10-28T14:22:47Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
;Usage 1:<code>interp(<var>x</var>, <var>n</var>, <var>type</var> {, <var>mv</var>})</code>
:Create an interpolated copy of the vector <var>x</var> with length <var>n</var>.
:;<var>x</var>:vector to be interpolated, <var>x[i] = f(i)</var>
:;<var>n</var>:length of the interpolated output vector; the interpolated vector can be shorter or longer than the original
:;<var>type</var>:the type of interpolation to perform
::''type''='''0''': linear interpolation
::''type''='''1''': cubic spline interpolation
:;<var>mv</var>:the value to use for ''missing values''. If ''mv'' is given, then interpolation is stopped when <code>''x''[i] = ''mv''</code>. This means that the sections without missing values are individually interpolated. If ''mv'' is not supplied, the whole vector ''x'' is interpolated.
::'''note''': The missing value handling is implemented only for linear interpolation (''type''='''0''')
;Result:The interpolated vector ''y'' with length ''n''.
;Usage 2:<code>interp(<var>x</var>, <var>y</var>, <var>xp</var> {, <var>type=1</var>})</code>
:Get interpolated values of function <var>y=f(x)</var> at the position(s) <var>xp</var>.
:;<var>x</var>:x value vector
:;<var>y</var>:y value vector, ''y[i]'' = f(''x[i]'')
:;<var>xp</var>:position(s) for interpolation (number, vector or matrix)
:;<var>type</var>:the type of interpolation to perform
::''type''='''0''': linear interpolation
::''type''='''1''': cubic spline interpolation
;Result:The interpolated values ''yp'' (same type as ''xp'').
;See also: [[../rpolyreg|rpolyreg]], [[../qinterp|qinterp]], [[../map2map|map2map]]

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

Programmer Guide/Command Reference/EVAL/interp

2025-10-28T14:22:27Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
;Usage 1:<code>interp(<var>x</var>, <var>n</var>, <var>type</var> {, <var>mv</var>})</code>
:Create an interpolated copy of the vector <var>x</var> with length <var>n</var>.
:;<var>x</var>:vector to be interpolated, x[i] = f(i)
:;<var>n</var>:length of the interpolated output vector; the interpolated vector can be shorter or longer than the original
:;<var>type</var>:the type of interpolation to perform
::''type''='''0''': linear interpolation
::''type''='''1''': cubic spline interpolation
:;<var>mv</var>:the value to use for ''missing values''. If ''mv'' is given, then interpolation is stopped when <code>''x''[i] = ''mv''</code>. This means that the sections without missing values are individually interpolated. If ''mv'' is not supplied, the whole vector ''x'' is interpolated.
::'''note''': The missing value handling is implemented only for linear interpolation (''type''='''0''')
;Result:The interpolated vector ''y'' with length ''n''.
;Usage 2:<code>interp(<var>x</var>, <var>y</var>, <var>xp</var> {, <var>type=1</var>})</code>
:Get interpolated values of function <var>y=f(x)</var> at the position(s) <var>xp</var>.
:;<var>x</var>:x value vector
:;<var>y</var>:y value vector, ''y[i]'' = f(''x[i]'')
:;<var>xp</var>:position(s) for interpolation (number, vector or matrix)
:;<var>type</var>:the type of interpolation to perform
::''type''='''0''': linear interpolation
::''type''='''1''': cubic spline interpolation
;Result:The interpolated values ''yp'' (same type as ''xp'').
;See also: [[../rpolyreg|rpolyreg]], [[../qinterp|qinterp]], [[../map2map|map2map]]

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

Programmer Guide/Command Reference/EVAL/interp

2025-10-28T14:00:33Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
;Usage 1:<code>interp(<var>x</var>, <var>n</var>, <var>type</var> {, <var>mv</var>})</code>
:Create an interpolated copy of the vector <var>x</var> with length <var>n</var>.
:;<var>x</var>:vector to be interpolated
:;<var>n</var>:length of the interpolated output vector; the interpolated vector can be shorter or longer than the original
:;<var>type</var>:the type of interpolation to perform
::''type''='''0''': linear interpolation
::''type''='''1''': cubic spline interpolation
:;<var>mv</var>:the value to use for ''missing values''. If ''mv'' is given, then interpolation is stopped when <code>''x''[i] = ''mv''</code>. This means that the sections without missing values are individually interpolated. If ''mv'' is not supplied, the whole vector ''x'' is interpolated.
::'''note''': The missing value handling is implemented only for linear interpolation (''type''='''0''')
;Result:The interpolated vector ''y'' with length ''n''.
;Usage 2:<code>interp(<var>x</var>, <var>y</var>, <var>xp</var> {, <var>type=1</var>})</code>
:Get interpolated values of function <var>y=f(x)</var> at the position(s) <var>xp</var>.
:;<var>x</var>:x value vector
:;<var>y</var>:y value vector, ''y[i]'' = f(''x[i]'')
:;<var>xp</var>:position(s) for interpolation (number, vector or matrix)
:;<var>type</var>:the type of interpolation to perform
::''type''='''0''': linear interpolation
::''type''='''1''': cubic spline interpolation
;Result:The interpolated values ''yp'' (same type as ''xp'').
;See also: [[../rpolyreg|rpolyreg]], [[../qinterp|qinterp]], [[../map2map|map2map]]

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

Programmer Guide/Command Reference/EVAL/interp

2025-10-28T13:54:50Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
Create an interpolated copy of the vector <var>x</var>.
;Usage 1:<code>interp(<var>x</var>, <var>n</var>, <var>type</var> {, <var>mv</var>})</code>
:;<var>x</var>:vector to be interpolated
:;<var>n</var>:length of the interpolated output vector; the interpolated vector can be shorter or longer than the original
:;<var>type</var>:the type of interpolation to perform
::''type''='''0''': linear interpolation
::''type''='''1''': cubic spline interpolation
:;<var>mv</var>:the value to use for ''missing values''. If ''mv'' is given, then interpolation is stopped when <code>''x''[i] = ''mv''</code>. This means that the sections without missing values are individually interpolated. If ''mv'' is not supplied, the whole vector ''x'' is interpolated.
::'''note''': The missing value handling is implemented only for linear interpolation (''type''='''0''')
;Result:The interpolated vector ''y'' with length ''n''.
;Usage 2:<code>interp(<var>x</var>, <var>y</var>, <var>xp</var> {, <var>type=1</var>})</code>
:;<var>x</var>:x value vector
:;<var>y</var>:y value vector, ''y[i]'' = f(''x[i]'')
:;<var>xp</var>:position(s) for interpolation (number, vector or matrix)
:;<var>type</var>:the type of interpolation to perform
::''type''='''0''': linear interpolation
::''type''='''1''': cubic spline interpolation
;Result:The interpolated values ''yp'' (same type as ''xp'').
;See also: [[../rpolyreg|rpolyreg]], [[../qinterp|qinterp]], [[../map2map|map2map]]

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

Programmer Guide/Command Reference/EVAL/corrfun

2023-09-01T08:39:08Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
Compute the autocorrelation or cross-correlation function.
;Usage:
:{|class="keinrahmen"
|<code>corrfun(''x''vector {, ''n'' {, ''scale'' {, cyclic}}})</code>
| ... autocorrelation of ''x''
|-
|<code>corrfun(''x''vector, ''y''vector {, ''n'' {, ''scale'' {, cylic}}})</code>
| ... cross correlation of ''x'' and ''y''
|}
:;''x'', ''y'': data vectors
:;''n'': the number of lags; 0 < n < <code>ncol(''x'')</code> (default=<code>ncol(''x'')/2</code>)
:;''scale'': specifies the scaling of the function:
::{|class="keinrahmen"
|''scale=0''
| ... no scaling (default)
|-
|''scale=1''
| ... "biased", each lag ''i'' is scaled by the length of ''x'' (<code>1/ncol(''x'')</code>)
|-
|''scale=2''
| ... "unbiased", each lag ''i'' is scaled by the number of correlated elements (<code>1/(ncol(''x'')-''i'')</code>)
|}
:;''cyclic'': normal or cyclic indexing
::{|class="keinrahmen"
|''cyclic=0''
| ... normal (default); (<code>acf[i]=sum(x[t]*y[t+i], t=0..ncol(x)-1-i)<code>)
|-
|''cyclic!=0''
| ... cyclic; (<code>acf[i]=sum(x[t]*y[(t+i)%ncol(x)], t=0..ncol(x)-1)<code>)
|}

;Result: The autocorrelation function of the data vector ''x'' or the cross correlation function of the vectors ''x'' and ''y''. The result is a scalar (if ''n''=1) or a vector with ''n'' elements.
;See also: [[../corr|corr]]

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

Programmer Guide/Command Reference/EVAL/corrfun

2023-09-01T08:37:56Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
Compute the autocorrelation or cross-correlation function.
;Usage:
:{|class="keinrahmen"
|<code>corrfun(''x''vector {, ''n'' {, ''scale'' {, cyclic}}})</code>
| ... autocorrelation of ''x''
|-
|<code>corrfun(''x''vector, ''y''vector {, ''n'' {, ''scale'' {, cylic}}})</code>
| ... cross correlation of ''x'' and ''y''
|}
:;''x'', ''y'': data vectors
:;''n'': the number of lags; 0 < n < <code>ncol(''x'')</code> (default=<code>ncol(''x'')/2</code>)
:;''scale'': specifies the scaling of the function:
::{|class="keinrahmen"
|''scale=0''
| ... no scaling (default)
|-
|''scale=1''
| ... "biased", each lag ''i'' is scaled by the length of ''x'' (<code>1/ncol(''x'')</code>)
|-
|''scale=2''
| ... "unbiased", each lag ''i'' is scaled by the number of correlated elements (<code>1/(ncol(''x'')-''i'')</code>)
|}
:;''cyclic'': normal or cyclic indexing
::{|class="keinrahmen"
|''cyclic=0''
| ... normal (default); (<code>acf[i]=sum(x[t]*y[(t+i)%ncol(x)], t=0..ncol(x)-1-i)<code>)
|-
|''cyclic!=0''
| ... cyclic; (<code>acf[i]=sum(x[t]*y[(t+i)%ncol(x)], t=0..ncol(x)-1)<code>)
|}

;Result: The autocorrelation function of the data vector ''x'' or the cross correlation function of the vectors ''x'' and ''y''. The result is a scalar (if ''n''=1) or a vector with ''n'' elements.
;See also: [[../corr|corr]]

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

Programmer Guide/Command Reference/EVAL/corrfun

2023-09-01T08:37:13Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
Compute the autocorrelation or cross-correlation function.
;Usage:
:{|class="keinrahmen"
|<code>corrfun(''x''vector {, ''n'' {, ''scale'' {, cyclic}}})</code>
| ... autocorrelation of ''x''
|-
|<code>corrfun(''x''vector, ''y''vector {, ''n'' {, ''scale'' {, cylic}}})</code>
| ... cross correlation of ''x'' and ''y''
|}
:;''x'', ''y'': data vectors
:;''n'': the number of lags; 0 < n < <code>ncol(''x'')</code> (default=<code>ncol(''x'')/2</code>)
:;''scale'': specifies the scaling of the function:
::{|class="keinrahmen"
|''scale=0''
| ... no scaling (default)
|-
|''scale=1''
| ... "biased", each lag ''i'' is scaled by the length of ''x'' (<code>1/ncol(''x'')</code>)
|-
|''scale=2''
| ... "unbiased", each lag ''i'' is scaled by the number of correlated elements (<code>1/(ncol(''x'')-''i'')</code>)
|}
:;''cyclic'': normal or cyclic indexing
::{|class="keinrahmen"
|''cyclic=0''
| ... normal (default); (<code>acf[i]=sum(x[t]*y[(t+i)%ncol(x)], t=0..ncol(x)-1-i)<code>)
|-
|''cyclic!=0''
| ... cyclic; (<code>acf[i]=sum(x[t]*y[(t+i)%ncol(x)], t=0..ncol(x)-1)<code>)
|}

;Result: The autocorrelation of the data vector ''x'' or the cross correlation function of the vectors ''x'' and ''y''. The result is a scalar (if ''n''=1) or a vector with ''n'' elements.
;See also: [[../corr|corr]]

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

Programmer Guide/Command Reference/EVAL/corrfun

2023-09-01T08:33:09Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
Compute the autocorrelation or cross-correlation function.
;Usage:
:{|class="keinrahmen"
|<code>corrfun(''x''vector {, ''n'' {, ''scale'' {, cyclic}}})</code>
| ... autocorrelation of ''x''
|-
|<code>corrfun(''x''vector, ''y''vector {, ''n'' {, ''scale'' {, cylic}}})</code>
| ... cross correlation of ''x'' and ''y''
|}
:;''x'', ''y'': data vectors
:;''n'': the number of lags; 0 < n < <code>ncol(''x'')</code> (default=<code>ncol(''x'')/2</code>)
:;''scale'': specifies the scaling of the function:
::{|class="keinrahmen"
|''scale=0''
| ... no scaling (default)
|-
|''scale=1''
| ... "biased", each lag ''i'' is scaled by the length of ''x'' (<code>1/ncol(''x'')</code>)
|-
|''scale=2''
| ... "unbiased", each lag ''i'' is scaled by the number of correlated elements (<code>1/(ncol(''x'')-''i'')</code>)
|}
:;''cyclic'': normal or cyclic indexing
::{|class="keinrahmen"
|''cyclic=0''
| ... normal correlation (default)
|-
|''cyclic!=0''
| ... cyclic correlation (<code>x[t]*y[(t+i)%ncol(x)]<code>)
|}

;Result: The autocorrelation of the data vector ''x'' or the cross correlation function of the vectors ''x'' and ''y''. The result is a scalar (if ''n''=1) or a vector with ''n'' elements.
;See also: [[../corr|corr]]

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

Programmer Guide/Command Reference/EVAL/corrfun

2023-09-01T08:31:42Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
Compute the autocorrelation or cross-correlation function.
;Usage:
:{|class="keinrahmen"
|<code>corrfun(''x''vector {, ''n'' {, ''scale'' {, cyclic}}})</code>
| ... autocorrelation of ''x''
|-
|<code>corrfun(''x''vector, ''y''vector {, ''n'' {, ''scale'' {, cylic}}})</code>
| ... cross correlation of ''x'' and ''y''
|}
:;''x'', ''y'': data vectors
:;''n'': the number of lags; 0 < n < <code>ncol(''x'')</code> (default=<code>ncol(''x'')/2</code>)
:;''scale'': specifies the scaling of the function:
::{|class="keinrahmen"
|''scale=0''
| ... no scaling (default)
|-
|''scale=1''
| ... "biased", each lag ''i'' is scaled by the length of ''x'' (<code>1/ncol(''x'')</code>)
|-
|''scale=2''
| ... "unbiased", each lag ''i'' is scaled by the number of correlated elements (<code>1/(ncol(''x'')-''i'')</code>)
|}
::{|class="keinrahmen"
|''cyclic=0''
| ... normal correlation (default)
|-
|''cyclic!=0''
| ... cyclic correlation (<code>x[t]*y[(t+i)%ncol(x)]<code>)
|}

;Result: The autocorrelation of the data vector ''x'' or the cross correlation function of the vectors ''x'' and ''y''. The result is a scalar (if ''n''=1) or a vector with ''n'' elements.
;See also: [[../corr|corr]]

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

Programmer Guide/Command Reference/EVAL/corrfun

2023-09-01T08:30:31Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
Compute the autocorrelation or cross-correlation function.
;Usage:
:{|class="keinrahmen"
|<code>corrfun(''x''vector {, ''n'' {, ''scale'' {, cyclic}}})</code>
| ... autocorrelation of ''x''
|-
|<code>corrfun(''x''vector, ''y''vector {, ''n'' {, ''scale'' {, cylic}}})</code>
| ... cross correlation of ''x'' and ''y''
|}
:;''x'', ''y'': data vectors
:;''n'': the number of lags; 0 < n < <code>ncol(''x'')</code> (default=<code>ncol(''x'')/2</code>)
:;''scale'': specifies the scaling of the function:
::{|class="keinrahmen"
|''scale=0''
| ... no scaling (default)
|-
|''scale=1''
| ... "biased", each lag ''i'' is scaled by the length of ''x'' (<code>1/ncol(''x'')</code>)
|-
|''scale=2''
| ... "unbiased", each lag ''i'' is scaled by the number of correlated elements (<code>1/(ncol(''x'')-''i'')</code>)
|}
::{|class="keinrahmen"
|''cyclic=0''
| ... normal correlation (default)
|-
|''cyclic!=0''
| ... cyclic correlation (<code>a[i]*b[(i+lag)%ncol(a)]<code>)
|}

;Result: The autocorrelation of the data vector ''x'' or the cross correlation function of the vectors ''x'' and ''y''. The result is a scalar (if ''n''=1) or a vector with ''n'' elements.
;See also: [[../corr|corr]]

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

Programmer Guide/Macro Library/BDataSet

2023-08-28T13:50:26Z

Toni: /* OpenAutoAFile */

{{DISPLAYTITLE:{{SUBPAGENAME}} - Project Document and Project Management}}
:'''File''': BDataSet.STX, linked to library STX.LIB
:'''Parent class''': [[Programmer Guide/Macro Library/BXMLDoc|BXMLDoc]]
:'''See also''': [[Programmer_Guide/Macro_Library/BXMLDoc|BSTXIni]], [[Programmer_Guide/Macro_Library/DataSetCmd|DataSetCmd]]

This class implements the '''project document'''. The project document is the global database available to all {{STx}} applications and scripts and contains all data and links of the current project. The content of the project document is stored in a [[Programmer_Guide/Shell_Items/File|XML file item]] The programmer must not create or destroy the project object because these functions are performed by the application startup and cleanup macros.

: Never ever call the member functions <code>CONSTRUCT</code>, <code>DESTRUCT</code> or <code>CLOSE</code>!

At application startup a <code>BDataSet</code> instance is created and linked to the global project document which is created and managed by the {{STx}} master shell. The name of this instance is stored in the shell variable <var>BDATASET</var>. This object must be used to access the project document.

The class <code>BDataSet</code> is derived from the class <code>[[Programmer_Guide/Macro_Library/BXMLDoc|BXMLDoc]]</code>. Beware of using the base class functions, since they do not update the <code>BDataSet</code> member variables! No static commands are implemented by this class; a call to the macro <code>BDataSet</code> (e.g. <code>bdataset save</code>) will do nothing, returning an empty string.

'''Important note''': A shell or a script should only access or change the content of the project document, while it is attached (locked). This is very important, because the project document can be (and is often) accessed by all running shells (e.g. {{STx}} applications or scripts). A code section accessing the project content should start with <code>$bdataset attach</code> and end with <code>$bdataset detach</code>.

;Example for using attach/detach:

<pre>
// first attach call - lock project document and save current xml-position (pos1)
$bdataset attach
...
// second attach call - save xml-position (pos2)
$bdataset attach
...
// first detach call - restore xml-position pos2, project document remains locked!
$bdataset detach
...
// second detach call - restore xml-position pos1 and unlock project document,
// if the project document was changed by the code between first attach and second detach,
// the message "DATASETCHANGED" is sent to all running shells
$bdataset detach
</pre>

==Project File Management==

===Validate===
;Usage: <code>$bdataset validate <var>showmsg</var></code>
:;<var>showmsg</var>: if set to <code>1</code> a message is displayed also if no invalid elements were detected; default: no message if no invalid elements were found
;Result: number of invalid elements (<code>0</code> for none)
;Description: This function checks all elements (sound files, segments, ...) of the project for validity. If invalid elements are detected, they can be displayed and the user is asked if they should be deleted or not.

===Save===
;Usage: <code>$bdataset save [ <var>path=* ; auto=0 ; pbh=* ]</var></code>
:;<var>path</var>: project file path; if not specified or '''*''', the last load/save path is used
:;<var>auto</var>: if set to '''1''' the user is '''not''' prompted with a yes/no dialog as to whether they want to save or not.
:;<var>pbh</var>: a progress dialog handle (see [[Programmer_Guide/Macro_Library/ProgressBox|macro ProgressBox]]); use '''*''' if no progress box should be displayed
;Result: '''0''' for success or a non-zero error code
;Description: This function saves the current project to the specified or last assigned project file. During the load process all necessary element validations and path conversions are performed. If the project is in mode '''linked''' also the segment metadata files of all linked sound files are updated.

===Load===
;Usage: <code>$bdataset load [ <var>filepath</var> ]</code>
;<var>filepath</var>: the path of the project file to be loaded; if not specified the last assigned path is used
;Result: '''0''' for success or a non-zero error code
;Description: This function loads the specified or last assigned project file. During the load process all necessary path conversions, additional load operations of linked files and element validations are performed. The progress of the load process is display in a popup progress dialog.

==Project Properties==

===IsNewFile===
;Usage: <code>$bdataset isnewfile</code>
;Result: '''1''' if the project file is new (not named and not saved) and '''0''' otherwise.

===GetPath===
;Usage: <code>$bdataset getpath</code>
;Result: the full path of the project file or an empty string

===SetLink===
;Usage: <code>$bdataset setlink <var>mode</var></code>
:;<var>mode</var>: '''0''' (or '''no''') to set project to '''not linked''' and '''1''' (or '''yes''') to set it to '''linked'''
;Result: '''0''' if the selected mode was enabled and '''1''' if the function fails.
;Description: This function change the project attribute <code>AFile</code> (attribute of the root-element <code>STXDataSet</code>).
* <code>AFile=Link</code>: The project is in mode '''linked'''. The segment metadata are stored in {{STx}} metadata files, which are xml-files with the same pathname as the sound file and the filetype '''stxsm'''. The segment metadata files of sound file linked to the project are loaded/saved automatically, when the project is loaded/saved. The project file contains only links to the sound files of the project.
* <code>AFile</code> is not assigned: The project is in mode '''not linked'''. All data of the project, including segment metadata, are stored in the project file. A project in this mode may contain multiple links to one sound file (e.g. to manage different segmentations of the same signal).

===IsLinked===
;Usage: <code>$bdataset islinked</code>
;Result: '''1''' if the project is set to '''linked''' and '''0''' otherwise

===SetRelativity===
;Usage: <code>$bdataset setrelativity <var>mode</var></code>
:;<var>mode</var>: '''0''' (or '''no''') to disable the relative path feature and '''1''' (or '''yes''') to enable it
;Result: '''0''' if the selected mode was enabled and '''1''' if the function has failed.
;Description: This function can be used to enable/disable the relative path option. If the relative path option is enabled, for sound file which are in the same directory as the project file or in subdirectories the relative path is saved in the project. This feature is useful if the project should be copied to other places. The relativity state is saved in the attribute <code>ARelative</code> of the root element of the project. If this attribute has the value <code>yes</code>, relative sound file pathes are used, otherwise (<code>ARelative</code>) equals <code>no</code> or is not set) absolute pathes are used.

===IsRelative===
;Usage: <code>$bdataset isrelative</code>
;Result: '''1''' if the project is set to '''relative sound file pathes''' and '''0''' otherwise

==Audio Set Functions==

===AddASet===
;Usage:
:;<code>$bdataset addaset <var>tag ; targetset ; id ; srate ; channels ; update</var></code>
:;<var>tag</var>: the type off the new audio set; this can be ...
::* the name of an existing sound file to be added to the project
::* the keyword '''AFile''' or '''*''' to create (via dialog) a new soundfile and add it to the project
::* the keyword '''ASequence''' or '''Sequence''' to add a new sequence to the project
:;<var>targetset</var>: the set (folder) where the new audio set should be located; if set to '''*''', the target is selected via a dialog
:;<var>id</var>: the unique id of the new audio set; if set to '''*''' an unique id is choosen automatically
:;<var>srate</var>: the sampling rate in Hz for a new soundfile or a sequence
:;<var>channels</var>: the number of channels for a new soundfile or a sequence
:;<var>update</var>: if set to '''1''' (or '''yes''') the function <code>DataSetCmd RefreshAll</code> is called to refresh the project GUI
;Result: if successful, the the reference (iref) of the added audio set if returned, otherwise an empty string
;Description: This function adds an audio set (sound file or sequence) to the project.

===AFileIsLinked===
;Usage: <code>$bdataset afileislinked <var>path</var></code>
:;<var>path</var>: the path of the sound file to be tested
;Result: '''1''' if the sound file <var>path</var> is already linked to the project and '''0''' otherwise.
;Description: This function tests if a sound file is already linked to the project or not. The check is performed only if the project is set to '''linked'''. For '''not linked''' projects the functions returns always '''0'''.

===SelectASet===
;Usage: <code>$bdataset selectaset <var>aset ; type</var></code>
:;<var>aset</var>: the reference (iref or position) of an audio set or of an element inside an audio set (e.g. a segment)
:;<var>type</var>: assumed type of the audio set: '''AFile''', '''Soundfile''', '''ASequence''', '''Sequence''' or '''*''' (default) if type is unknown
;Result: '''0''' if the audio set is selected and a non-zero error code otherwise
;Description: This function selects the specified audio set. If the function was sussessful, the following member variables of the object <code>$bdataset</code> are assigned:
::*<code>&asetPos</code>: xml position of the audio set element
::*<code>&asetTag</code>: xml tag of the audio set element (AFile or ASequence)
::*<code>&asetID</code>: xml element id (value of attribute ID)
::*<code>&asetSR</code>: sampling rate in Hz (value of attribute SR)
::*<code>&asetCH</code>: number of channels (value of attribute CH)
::*<code>&asetFile</code>: sound file path (only if tag equals AFile)

===GetASetInfo===
;Usage: <code>$bdataset getasetinfo [ <var>aset ; type</var> ]</code>
:;<var>aset</var>: the reference (iref or position) of an audio set or of an element inside an audio set (e.g. a segment)
:;<var>type</var>: assumed type of the audio set: '''AFile''', '''Soundfile''', '''ASequence''', '''Sequence''' or '''*''' (default) if type is unknown
;Result: an empty string for error or the available attributes of the selected audio set:
::* for sound files: <code>Soundfile ; <var>id</var> ; <var>sr</var> ; <var>ch</var> ; <var>filepath</var></code>
::* for sequences: <code>Sequence ; <var>id</var> ; <var>sr</var> ; <var>ch</var></code>
;Description: This function retrieves information about the selected audio set. If arguments are specified, they are passed to the function <code>SelectASet</code> to select the audio set, before the audio set information is returned.

===OpenAutoAFile===
;Usage: <code>$bdataset openautoafile <var>mode ; srate ; channels ; code</var> ]</code>
:;<var>mode</var>:
::* '''0''' → replace the last created autofile
::* '''1''' → get last created autofile, file is replaced if <var>srate</var> or <var>channels</var> are different
::* '''2''' → create and add a new autofile
:;<var>srate</var>: sampling rate in Hz
:;<var>channels</var>: number of signal channels
:;<var>code</var> sample code (see [[Programmer_Guide/Command_Reference/LOAD#LOAD_SOUNDFILE|command LOAD SOUNDFILE]])
;Result: '<var>iref ; created</var>' with:
::* <var>iref</var>: the audio set reference of the autofile
::* <var>created</var>: '''1''' if a new sound file was created and '''0''' if an existing sound file was opened
;Description: This function creates/opens an temporary sound file and adds it to the project. Temporary sound files (autofiles) can be used to save results of signal processing/modification operations. All autofiles are deleted when the project is closed.

===RemoveTmpSet===
;Usage: <code>$bdataset removetmpset <var>del</var> ]</code>
:;<var>del</var>: '''0''' to copy the tmp-set and '''1''' to delete the tmp-set and all temporary sound files
;Result: an empty string if the tmp-set was deleted and the name of an xml file item containing the tmp-set elements otherwise
;Description: This function removes the tmp-set, this is the set element (folder) containing all temporary audio sets (autofiles), from the project. If the argument <var>del</var> is set to '''1''', the temporary sound files are deleted and the tmp-set is removed from the project. Otherwise, the tmp-set is copied to a new xml file item, which is returned to the caller, and than it is removed from the project, but the temporary sound files are not deleted.

===RestoreTmpSet===
;Usage: <code>$bdataset restoretmpset <var>xmlfile</var> ]</code>
:;<var>xmlfile</var>: a xml file item containing the tmp-set to be restored; normally created with <code>$bdataset removetmpset 0</code>
;Result: none (void)
;Description: This function add the tmp-set contained in xml file item passed to the function to the project.

==Audio Segment Functions==

===SelectASeg===
;Usage: :<code>$bdataset selectaseg <var>aset; aseg</var></code>
:;<var>aset</var>: audio set reference (position or iref)
:;<var>aseg</var>: audio segment reference or id
;Result: '''0''' for success or a non-zero error code
;Description: Selects the segment <var>aseg</var> of the audio set <var>aset</var>. This function calls <code>SelectASet</code> first to select the audio set. If the function succeeds, the current element of the xml project file is the selected segment.

===EvalSegment===
;Usage: :<code>$bdataset evalsegment <var>aset; aseg; fmt</var></code>
:;<var>aset</var>: audio set reference (position or iref)
:;<var>asegid</var>: audio segment reference, id or expression
:;<var>fmt</var>select output format and time unit (see result)
;Result:
::* empty string on error
::* <var>fmt</var>='''samples''' → '<var>beginsample endsample numberofsamples' (boundaries in samples, separated by blanks)
::* <var>fmt</var>='''seconds''' → '<var>begintime endtime duration' (time values in seconds, separated by blanks)
::* <var>fmt</var>='''segment''' → '<var>segmentexpression' (a valid segment expression for the specified segment)
;Description: This function returns the boundaries of the specified segment or the segment expression in the selected format.
;See also: [[Programmer_Guide/Command_Reference/SEGMENT|command SEGMENT]]

===SetSegment===
;Usage:
:<code>$bdataset setsegment <var>aset; asegid; asegexpr; attrname=attrvalue; ...</var></code>
:<code>$bdataset setsegment <var>aset; asegid; asegexpr; attrtable</var></code>
:;<var>aset</var>: audio set reference (position or iref)
:;<var>asegid</var>: audio segment id
:;<var>attrname=valuename</var>: name and value segment attribute; multiple attribute assignments can be specified separated by semi-colons
:;<var>attrtable</var>: a simple table containing von attribute assignment (name=value) per line; Warning: This table is deleted after processing!
;Result: '''0''' for success or a non-zero error code
::* for positive error codes (>0) see [[Programmer_Guide/Command_Reference/EMSG|command EMSG]]
::* -4 → invalid segment id <var>asegid</var> (for new segment)
::* -3 → bad segment expression <var>asegexpr</var>
::* -2 → bad segment address (<var>aset</var> and/or <var>asegid</var>)
::* -1 → cannot add segment to database (e.g. due to a duplicate name <var>asegid</var>)
;Description: This functions creates a new segment <var>asegid</var> with the boundaries specified by <var>asegexpr</var> and assignes the specified attributes. If the segment with id <var>asegid</var> already exists, only the boundaries and attributes are updated.
:* To leave the boundaries of an existing segment (attributes P and L) untouched, set <var>asegexpr</var> to '''*'''.
:* To remove an attribute, leave the attribute value empty (<code><var>attrname</var>=</code>).
:* Error and warning messages are written to the {{STx}} log-window.

===GetSegment===
;Usage: <code>$bdataset getsegment <var>aset; aseg; attr1; ...</var></code>
:;<var>aset</var>: audio set reference (position or iref)
:;<var>aseg</var>: audio segment reference or id
:;<var>attr1</var>, <var>attr2</var>, ... : keyword or name of requested attribute(s)
;Result: The function returns the values of the requested attributes or an empty string on error. If more than one value is requested, the returned attribute values are separated by semi-colons.
;Description: This functions retrieves attributes (properties) of the specified segment. The table below shows the possible values and keywords for the attribute argument(s).

{|class="einrahmen"
! attrX !! return value !! comment
|-
| <code>id</code> or <code>name</code> || segment id || attribute ID
|-
| <code>iref</code> || segment reference (iref) ||
|-
| <code>segment [<var>unit</var>]</code> || segment expression || attributes P and L
|-
| <code>position [<var>unit</var>]</code> or <code>begin [<var>unit</var>]</code> || begin of segment || attribute P
|-
| <code>end [<var>unit</var>]</code> || end of segment || attribute P and L
|-
| <code>length [<var>unit</var>]</code> || segment length || attribute L
|-
| <code>channel [<var>unit</var>]</code> || channel assigned to segment || attribute CH
|-
| <var>attrname</var> || value of attribute <var>attrname</var> || attribute names are case sensitive!
|}

Note: The optional argument <var>unit</var> specifies the unit for time values. It can be '''samples''' (default), '''seconds''', '''milliseconds''' (or '''ms''') or '''hms'''

===FindSegment===
;Usage:
:<code>$bdataset findsegment first; <var>aset ; asegid ; range ; attrexpr1 ; ... </var></code>
:<code>$bdataset findsegment next; <var>asegpos ; asegid ; range ; attrexpr1 ; ... </var></code>
;Result: position <var>asegpos</var> of first / next matching segment or empty string
;Description: The find <code>first/next</code> function can be used to process audio segments in an interation loop. If a call to <code>next</code> fails (no more matching segments found), the position <var>asegpos</var> passed to function is cleared automatically. If an iteration loop is leaved before the last segment was processed, the <code>reset</code> variant must be called to clear the last saved position.

;Usage: <code>$bdataset findsegment all|directory; <var>aset ; asegid ; range ; attrexpr1 ; ... </var></code>
;Result: For <code>all</code> a simple table containing the xml positions of all found segments is returned. For <code>directory</code> the function returns an extended table containing the id, begin, length and channel assignment (fields: ID, P, L and CH). If the function fails or no matching elements were found, it returns an empty string.

;Usage: <code>$bdataset findsegment reset; <var>table|asegpos ; delete=0</var></code>
;Result: none (void)
;Description: This function variant clears the position <var>asegpos</var> or the segments positions stored in <var>table</var>. If <var>delete</var> is set to '''1''' also the segments themselves are deleted. It must be called to reset the segment position if an iteration loop is left early and to reset positions of segments found by the <code>all</code> variant.

;Arguments:
:;<var>aset</var>: audio set reference (iref or position)
:;<var>asegid</var>: segment name (wildcard)
:;<var>asegpos</var>: segment element position
:;<var>range</var>: segment expression defining the search range (* = whole audio set)
:;<var>attrexpr</var>: an attribute compare expression (see [[Programmer_Guide/Shell_Items/File/SET_FILE#XML:_FIND|SET xmlfileitem FIND]])
:;<var>table</var>: a simple table with segment element positions (returned by <code>ALL</code>)
:;<var>delete</var>: '''1''' if element(s) should be deleted on RESET, '''0''' otherwise

===DialogSelectSegment===
;Usage: <code>$bdataset dialogselectsegment <var>title ; aset ; mode ; output</var></code>
:;<var>title</var>: dialog capture, empty string to use default title
:;<var>aset</var>: audio set reference (iref)
:;<var>mode</var>: selection mode; '''single''' for one segment, '''multiple''' for multiple segments
:;<var>output</var>: return value(s); '''positioon''' = xml position of segment(s), '''iref''' xml reference (iref) of segment(s), '''id''' segment id
;Result:
::* empty string if failed/canceled
::* if <var>mode</var> = '''single''' → the specified return value as string
::* if <var>mode</var> = '''multiple''' → a simple table with one entry for each selected segment holding the specified output value as string
;Description: This function displayes a dialog with a segment list of the specified audio set, where the user can select segment(s).

===DialogEditSegment===
;Usage: <code>$bdataset dialogeditsegment <var>aset ; aseg ; segment ; channel ; title</var></code>
:;<var>aset</var>: audio set reference (iref)
:;<var>aseg</var>: segment reference, segment id or * (for new segments)
:;<var>segment</var>: segment expression specifying both boundaries of segment or *
:;<var>channel</var>: channel of segment or 0 for all channels
:;<var>title</var>: dialog capture, empty string to use default title
;Result: empty string if failed/canceled or id of changed/created segment
;Description: This function implements a complex dialog to create new segments and to edit properties/attributes of segments.

===CreateWave===
;Usage: <code>$bdataset createwave <var>aset ; aseg ; channels=* ; mode=single</var></code>
:;<var>aset</var>: audio set reference (iref or position)
:;<var>aseg</var>: specifies the segment (begin and end) to be addressed by the created wave item
::* a segment reference (iref or position), a segment id or a segment expression
::* the character '''*''' can be used to address the signal of the whole sound file
::* the expression '''*'''<var>length</var> can be used to create a wave item that appends a signal of duration <var>length</var> to a sound file
:;<var>channels</var>: defines which channels of the audio set should be addressed by the created wave item
::* '''*''' or '''0''' for all channels
::* use keyword '''channels''' (or '''ch''') to retrieve channel value from the attribute '''CH''' of the segment element
::* specify a channel number (1, 2, ..) or a list of blank separated channel numbers (e.g. '''1 3 4''')
:;<var>mode</var>: this argument is only used, if the specified audio set is a sequence (ASequence)
::* set <var>mode</var> to '''single''' if the signal is processed sequential
::* is the signal is accessed in a random way, set <var>mode</var> to '''multiple'''
;Return: the created wave item (item id) or an empty string if the function fails
;Description: This function creates a wave item which can be used to read, write or append a signal from/to an audio set of the current project. A wave item created by this function must be deleted by calling the member function <code>DeleteWave</code>. All wave items created by this member, are automatically deleted by the {{STx}} application management functions, when the shell exits.

===CreateWaveEx===
This function takes the same arguments and performs the same function as <code>CreateWave</code>. Only the result is different.
;Result: the created wave item or a numeric error code

===DeleteWave===
;Usage: <code>$bdataset deletewave <var>waveitem</var></code>
:;<var>waveitem</var>: id of waveitem to be deleted
;Result: no result (void)
;Description: This function deletes the wave item and performs all necessary cleanup operations (e.g. delete assoziated items, close used soundfiles, etc.). Use this function only to delete wave items created with <code>CreateWave/CreateWaveEx</code>.

==Uncommon Functions and Functions for internal use only==

The following functions are not often used and not so important for user script programming. If you want to know more about these functions look at the comments in the source file '''BDataSet.stx'''

* <code>GetBaseDirecory(read: #filepath)</code>: used by member <code>Save</code> to verify the project file path

* <code>BackupSave</code>: create a backup copy of the current project if backups are enabled; this function is called by the members <code>Save/Load</code>
* <code>BackupEmpty</code>: empty backup directory - delete all backups
* <code>BackupLoad</code>: display a list of available backups including options to restore selected backups

* <code>ImportXML(read: #filepath; #set=*; #id=*)</code>: import the content of a xml file into the project (e.g. merge projects)
* <code>ImportSD0(read: afileref=*)</code>: import segment metadata of the specified (selected) audio set; try all versions (stxsm/sd0/st5); this function is used to load segment metadata of linked projects
* <code>ExportSD0(read: afileref=* [xmlfile])</code>: export segment metadata of the specified (selected) audio set; this function is used to save segment metadata of linked projects

* <code>SetSetting(read: #id; version; value)</code>: set the value of project setting '#id' in the STXDataSet/Settings element
* <code>GetSetting(read: #id; version)</code>: get the valud of project setting '#id' from STXDataSet/Settings element

* <code>GetWaveInfo(read: waveitem)</code>: retrieve all information associated to a wave item (created with member CreateWave)

* <code>MakeChannelList(read: nch|aset; withall)</code>: initialize a channel-list variable for dialogs (combobox)

* <code>GetReservedAttributes</code>: returns a blank seperated list of all reserved attribute names
* <code>IsReservedAttribute(read: attrname)</code>: returns 1 if the argument attrname is the name a reserved attribute and 0 otherwise
* <code>GetAttributes(read: type table autoexclude excludelist)</code>: returns a list of all attributes assigned to elements of the specified; the whole project is scanned
* <code>DialogGetAttributes(read: type vlist)</code>: implements a dialog to select visible attributes of the selected element type (e.g. sets, segments, ...); returns a blank separated list of visible attributes

* <code>GetTemplateForCurrentTag</code>: get the template assigned to the current element (or its parent if possible)

* <code>AttrListView</code>: a special handler for attribute editors (controls a dialog via msg. handling and callback); used by some standard dialogs of the GUI

Programmer Guide/Command Reference/EVAL/rpoly

2023-05-15T08:41:13Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
Evaluate polynom with real coefficients.
;Usage: <code>rpoly(<var>a</var>, <var>x</var>)</code>:
:;<var>a</var>: a vector containing the polynom coefficients
:;<var>x</var>: a scalar, vector or matrix
;Result: The result ''y'' has the same type as ''x''.
::<code>''y''[i,j] = ''a''[0] + ''a''[1]*''x''[i,j] + ''a''[2]*''x''[i,j]^2 + ... + ''a''[m]*''x''[i,j]^m</code>
::<code>with: m = polynom order = ncol(''a'')-1</code>
;See also: [[../rpolyreg|rpolyreg]], [[../interp|interp]]

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

Programmer Guide/Command Reference/EVAL/rpoly

2023-05-15T08:40:35Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
Evaluate polynom with real coefficients.
;Usage: <code>rpoly(<var>a</var>, <var>x</var>)</code>:
:;<var>a</var>: a vector containing the polynom coefficients
:;<var>x</var>: a vector or a number
;Result: The result ''y'' has the same type as ''x''.
::<code>''y''[i,j] = ''a''[0] + ''a''[1]*''x''[i,j] + ''a''[2]*''x''[i,j]^2 + ... + ''a''[m]*''x''[i,j]^m</code>
::<code>with: m = polynom order = ncol(''a'')-1</code>
;See also: [[../rpolyreg|rpolyreg]], [[../interp|interp]]

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

Programmer Guide/Command Reference/EVAL/rpoly

2023-05-15T08:39:57Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
Evaluate polynom with real coefficients.
;Usage: <code>rpoly(<var>a</var>, <var>x</var>)</code>:
:;<var>a</var>: a vector containing the polynom coefficients
:;<var>x</var>: a scalar, vector or number
;Result: The result ''y'' has the same type as ''x''.
::<code>''y''[i,j] = ''a''[0] + ''a''[1]*''x''[i,j] + ''a''[2]*''x''[i,j]^2 + ... + ''a''[m]*''x''[i,j]^m</code>
::<code>with: m = polynom order = ncol(''a'')-1</code>
;See also: [[../rpolyreg|rpolyreg]], [[../interp|interp]]

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

User Guide/Waveform and Segmentation Viewer

2020-11-25T08:29:02Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{V1}}
The {{Viewer1}} plots the waveform of the selected signal and is most often used to segment sound files. In {{STX}} 5.0.0, basic signal editing capabilities were added.

The [[User_Guide/SPExL/Transcription_Script|Transcription Script]] is a more recent alternative for segmentation.

[[File:v1_overview.png]]

==Overview Graph==

{{/Overview_Graph}}

==Segment Line Graphs==

{{/Segment_Line_Graphs}}

==Zoom Graphs==

{{/Zoom_Graphs}}

==Control Dialog==

{{/Control_Dialog}}

The following unsorted topics are currently available:

==Waveform and Segmentation Viewer Dialogs==

{{/Waveform_and_Segmentation_Viewer_Dialogs|}}

==Zooming==

{{/Zooming}}

==Playback==

{{/Playback}}

==Pre-Configured Profiles==

{{/Pre-Configured_Profiles}}

==General Settings Dialog==

{{/General_Settings_Dialog}}

==Segment Markers Dialog==

{{/Segment_Markers_Dialog}}

==Profile Settings Dialog==

{{/Profile_Settings_Dialog_(Waveform_and_Segmentation_Viewer)}}

==Segments Dialog==

{{/Segments_Dialog}}

==Cue-Points Dialog==

{{/Cue-Points_Dialog}}

[[User_Guide/Waveform_and_Segmentation_Viewer/Waveform_and_Segmentation_Viewer_Hotkeys|Hotkeys]]

User Guide/Recorder

2020-11-24T11:54:51Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{Recorder}}
{{TODO}}
The Recorder application can be used to record signals from the available MME analog and digital inputs on your system, saving these signals to wave files. Whilst recording, you can set tags, which you can later convert to segments. You can also tag and segment in the graph once recording is finished.

[[File:recorder.png]]

Note that once you saved the signal, further playback and segmentation must be carried out in the [[User_Guide/Workspace|Workspace]] and Viewers (e.g. the [[User_Guide/Waveform_and_Segmentation_Viewer/Waveform_and_Segmentation_Viewer|Waveform and segmentation viewer]]). The {{STX}} Recorder PPM bars only work under Windows XP and under those Windows versions where it works like under Windows XP. If you are running Windows 2000, you will not be able to show the PPM bars and record at the same time. The Real-Time Analyser will also not display correctly while recording. We are working on removing this automatically.

'''Contents'''

[[User_Guide/Recorder/Setup_Dialog|Setup Dialog]]

[[User_Guide/Recorder/Tagging|Tagging]]

[[User_Guide/Copy_or_Print_Dialog|Copy/Print Dialog]]

Programmer Guide/Command Reference/EVAL/avr

2020-01-29T07:59:23Z

Toni:

{{DISPLAYTITLE:avr (alias: avg)}}
The arithmetic mean function is implemented in two versions.
----
;Usage 1: <code>avr(<var>x</var>)</code>
:;<var>x</var>: a scalar, vector or matrix
;Result 1: The result is the arithmetic mean of all elements of <var>x</var>
----
;Usage 2: <code>avr(<var>x</var>, <var>flag</var>)</code>
:;<var>x</var>: a matrix
:;<var>flag</var>: compute mean of the column vectors (''flag''=0) or the row vectors (''flag''≠0) is requsted; ''flag'' must be a scalar
;Result 2:
:*if ''flag''=0: the result ''r'' is the vector of the column means
:::<code>''r''[''i''] = eval avr( ''x''[*,''i''], 0) // ''i'' = 0 .. ncol(''x'')-1</code>
:*otherwise: the result ''r'' is the vector of the row means
:::<code>''r''[''i''] = eval avr( ''x''[''i'',*], 1) // ''i'' = 0 .. nrow(''x'')-1</code>
----
;See also: [[../median|median]], [[../var|var]], [[../dev|dev]], [[../corr|corr]], [[../sum|sum]], [[../hist|hist]],

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

Programmer Guide/Command Reference/CHECKIT

2019-01-31T10:57:24Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
var := CHECKIT arg [option]
with <code>option</code> being either empty, in which case the type of the shell item or of the sourcecode item <var>arg</var> will be returned, or one out of the following keywords:

{|class="einrahmen"
!option!!description!!result on success!!result on failure
|-
|<code>/Trace</code>
|returns a semicolon seperated list of the call stack at the current line; <var>arg</var> can be the number of levels (including current level) or the name of a macro where the traceback should stop
| <var>shellid; macro:line; macro:line; ...</var>
|-
|<code>/Executable</code>
|check if <var>arg</var> is executable, i.e., if it is a command, instance, macro, or class
| <code>1</code> if <var>arg</var> is executable
| <code>0</code> otherwise
|-
|<code>/Item</code>
| get type of the shell item <var>arg</var>
| type of the shell item (cf. [[Programmer_Guide/Shell_Items|shell item types]]) if <var>arg</var> is a shell item
| empty string otherwise
|-
|<code>/Code</code>
| get type of the source code <var>arg</var>
| <code>macro</code>, <code>class</code>, or <code>spu</code> if <var>arg</var> is a source code macro, class, or SPU.
| empty string otherwise
|-
|<code>/Visible</code>
| check if <var>arg</var> is a visible source code
| 1 if it is
| 0 if it is not
|-
| <code>/File</code>
| get full sourcefile path of source code <var>arg</var>
| full path if <var>arg</var> is a source code
| empty string otherwise
|-
| <code>/Style</code>
| get style of sourcecode <var>arg</var>
| <code>local</code>, <code>main</code>, <code>shell</code>, <code>sys</code>, <code>msgHandler</code>, or <code>global</code> if <var>arg</var> is a source code of the respective type.

Note: <code>global</code> is the default codestyle if none is specified in the code header
| empty string otherwise
|-
| no option at all
| get type of shell item or source code <var>arg</var>
| item type (cf. [[Programmer_Guide/Shell_Items|shell item types]]) or code type (<code>macro</code>, <code>class</code>, or <code>spu</code>) if <var>arg</var> is a shell item, or a source code
| empty string otherwise
|}

Programmer Guide/Command Reference/CHECKIT

2019-01-31T10:56:10Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
var := CHECKIT arg [option]
with <code>option</code> being either empty, in which case the type of the shell item or of the sourcecode item <var>arg</var> will be returned, or one out of the following keywords:

{|class="einrahmen"
!option!!description!!result on success!!result on failure
|-
|<code>/Trace</code>
|returns a semicolon seperated list of the call stack at the current line; <var>arg</var> can be the number of levels (including current level) or the name of a macro where the traceback shold stop
| <var>shellid; macro:line; macro:line; ...</var>
|-
|<code>/Executable</code>
|check if <var>arg</var> is executable, i.e., if it is a command, instance, macro, or class
| <code>1</code> if <var>arg</var> is executable
| <code>0</code> otherwise
|-
|<code>/Item</code>
| get type of the shell item <var>arg</var>
| type of the shell item (cf. [[Programmer_Guide/Shell_Items|shell item types]]) if <var>arg</var> is a shell item
| empty string otherwise
|-
|<code>/Code</code>
| get type of the source code <var>arg</var>
| <code>macro</code>, <code>class</code>, or <code>spu</code> if <var>arg</var> is a source code macro, class, or SPU.
| empty string otherwise
|-
|<code>/Visible</code>
| check if <var>arg</var> is a visible source code
| 1 if it is
| 0 if it is not
|-
| <code>/File</code>
| get full sourcefile path of source code <var>arg</var>
| full path if <var>arg</var> is a source code
| empty string otherwise
|-
| <code>/Style</code>
| get style of sourcecode <var>arg</var>
| <code>local</code>, <code>main</code>, <code>shell</code>, <code>sys</code>, <code>msgHandler</code>, or <code>global</code> if <var>arg</var> is a source code of the respective type.

Note: <code>global</code> is the default codestyle if none is specified in the code header
| empty string otherwise
|-
| no option at all
| get type of shell item or source code <var>arg</var>
| item type (cf. [[Programmer_Guide/Shell_Items|shell item types]]) or code type (<code>macro</code>, <code>class</code>, or <code>spu</code>) if <var>arg</var> is a shell item, or a source code
| empty string otherwise
|}

Programmer Guide/Command Reference/CHECKIT

2019-01-31T10:54:47Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
var := CHECKIT arg [option]
with <code>option</code> being either empty, in which case the type of the shell item or of the sourcecode item <var>arg</var> will be returned, or one out of the following keywords:

{|class="einrahmen"
!option!!description!!result on success!!result on failure
|-
|<code>/Trace</code>
|returns a semicolon seperated list of the call stack at the current line; <var>arg</var> can be a number of levels (including current level) or the name a macro to break the traceback
| <var>shellid; macro:line; macro:line; ...</var>
|-
|<code>/Executable</code>
|check if <var>arg</var> is executable, i.e., if it is a command, instance, macro, or class
| <code>1</code> if <var>arg</var> is executable
| <code>0</code> otherwise
|-
|<code>/Item</code>
| get type of the shell item <var>arg</var>
| type of the shell item (cf. [[Programmer_Guide/Shell_Items|shell item types]]) if <var>arg</var> is a shell item
| empty string otherwise
|-
|<code>/Code</code>
| get type of the source code <var>arg</var>
| <code>macro</code>, <code>class</code>, or <code>spu</code> if <var>arg</var> is a source code macro, class, or SPU.
| empty string otherwise
|-
|<code>/Visible</code>
| check if <var>arg</var> is a visible source code
| 1 if it is
| 0 if it is not
|-
| <code>/File</code>
| get full sourcefile path of source code <var>arg</var>
| full path if <var>arg</var> is a source code
| empty string otherwise
|-
| <code>/Style</code>
| get style of sourcecode <var>arg</var>
| <code>local</code>, <code>main</code>, <code>shell</code>, <code>sys</code>, <code>msgHandler</code>, or <code>global</code> if <var>arg</var> is a source code of the respective type.

Note: <code>global</code> is the default codestyle if none is specified in the code header
| empty string otherwise
|-
| no option at all
| get type of shell item or source code <var>arg</var>
| item type (cf. [[Programmer_Guide/Shell_Items|shell item types]]) or code type (<code>macro</code>, <code>class</code>, or <code>spu</code>) if <var>arg</var> is a shell item, or a source code
| empty string otherwise
|}

Programmer Guide/Shell Items/Table/SET TABLE

2019-01-30T09:30:52Z

Toni: /* {{anchor|FIND|Finding table entries}} */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{Table_Item_Template}}
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. Note also that you cannot set 'all' entries, if only tagged entries are currently visible.
|}

// initialize the first field of the first 10 entries with the value 0.
$#extTable 0 0 0 /N=10

== Retrieving a table entry ==

You can retrieve a table entry using the following syntax: <code>$#table[$#index]</code>. If the table has columns defined, you can use the syntax <samp>$#table[$#index,$#columnid]</samp>.

== 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>[[Programmer_Guide/Shell_Items/Table/NEW_TABLE|NEW TABLE]]</code> command. The table must be in configuration mode (see <code>[[#Setting_the_table_mode|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/Introducing_Table_Items#The_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 from 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 show format to format each entry string. This is the default.
;<code>/Write</code>: Use the write format to format each entry string.

SET <var>table</var> CLIPBOARD /Args arg1 arg2 ... [ /Show|Write ]

Copy the content of the arguments to the clipboard. Each argument <code>argI</code> can be a string (string is copied) or a table item (content of table is copied). The option <code>/Show|Write</code> specifies the output format used for the table items (as described above). The content of the table item <var>table</var> is only copied, if it is specified as argument.

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:

::conjunction: <code>AND</code> or <code>&&</code>
::disjunction: <code>OR</code> or <code>||</code>
::exclusive disjunction: <code>XOR</code> or <code>^^</code>

;<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/Introducing_Table_Items#The_Show_Format|show format]] (used to display tables in the GUI) using the [[Programmer_Guide/Shell_Items/Table/SET_TABLE#Configuring_a_table_field|<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 [[#Setting_the_table_mode|<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 ==

The use of '''lock/unlock''' is only important, if a table item is (or may be) used by more than one thread. In {{STX}} shells, spu items and display item are running in their own thread.

SET <var>table</var> LOCK [/Save]
Lock the table item. The execution of the calling shell is stopped, until the item can be locked. If locked, only the shell which locked it has access to the item until it is explicitly unlocked with the command <code>UNLOCK</code>. Always beware of deadlocks.

SET <var>table</var> LOCK <var>timeout</var> [Save]
Try to lock the table item, but wait only the specified time. This command returns '''0''' (success) if the lock request was successful within the timeout, and a non-zero error code if not. If the caller already ''holds'' the lock, the command will fail immediately. This makes sense because, since the caller is the owner, it cannot release it whilst its waiting. The argument <var>timeout</var> specifies the maximum lock-timeout in milliseconds and must be a number greater than zero.

:* If the table is locked with the option '''/Save''', the tag state of each entry, the current order and the mode is saved on <code>lock</code> and restored with the <code>unlock</code> command. In this case in the critical section entries can only be modified, but not created or deleted.

SET <var>table</var> UNLOCK
Unlock the table item. '''Note''': It's very important that for each successful <code>LOCK</code>, an <code>UNLOCK</code> is called!

See <code>lock_example.sts</code> in the script examples directory for an example.

== 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/Introducing_Table_Items#The_Show_Format|show format]], <code>1</code>…[[Programmer_Guide/Shell_Items/Table/Introducing_Table_Items#The_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/Command Reference/NEW

2019-01-21T14:03:19Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{Programmer Guide}}
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>.

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 following is applicable to all <code>NEW</code> commands:

*The argument <var>itemname</var> can be set to '<code>*</code>' if the item should automatically be given a unique name (e.g. <code>NEW FILE * /File</code>).
*The name of a new item is always stored in the variable <code>#NEW</code> if the command was successfully completed, otherwise <code>#NEW</code> is set to '<code>*</code>'.
*An item must be deleted (<code>DELETE name</code>) before another <code>NEW</code> command using the same name can be successfully executed.
*<code>NEW</code> commands can be used in inline statements with the syntax <code>#item = $(NEW itemx paramx)</code>. The variable <code>#item</code> is assigned the value of <code>#NEW</code>. Therefore if the command fails, both are assigned the value <code>*</code>.

;<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 .
;<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 protected 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 <code>[[Programmer_Guide/Command_Reference/DELETE|DELETE]]</code> command. Note: This option is case-sensitive.
;<code>/u</code>: If specified, the created item is 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>: Use this option, to create a reference to an already existing shell item (also if owned by another shell). For more details read the section about [[Programmer_Guide/Shell_Items|shell items]]

The following example creates a new table with an automatic name and assigns the name to a local variable or exits if the table was not created.

NEW TABLE *
if '$#new' == '*' then
butil msgbox msg ; Failed to create table
exit
end
#t := $#new$#t * 'my first entry' // append entry to table

You can also use your own name, rather than an automatically generated one. In this case, the code would look like this.

NEW TABLE myTable
if '$#new' == '*' then
butil msgbox msg ; Failed to create table
exit
end
myTable * 'my first entry' // append entry to table

Alternatively, with the inline syntax:

#t := $(NEW TABLE *)
if '$#t' == '*' then
butil msgbox msg ; Failed to create table
exit
end
$#t * 'my first entry' // append entry to table

All instances created with the NEW command should be deleted when no longer needed using the <code>[[Programmer_Guide/Command_Reference/DELETE|DELETE]]</code> command.

Programmer Guide/Shell Items/Wave/WAVE Item Attributes

2018-11-22T13:28:23Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{Wave Item}}

;<var>!BEGIN</var>

:The <code>WAVE</code> item attribute !BEGIN returns the start address in samples.

;<var>!CHANNELS</var>

:The <code>WAVE</code> item attribute <code>!CHANNELS</code> returns the number of signal channels.

;<var>!DEVICE</var>

:The <code>WAVE</code> item attribute <code>!DEVICE</code> returns the type of device attached to wave item or an empty string if no device is attached. Possible values are:

:<code>PLAY</code>|<code>RECORD</code>

;<var>!INCAPS</var>

:The <code>WAVE</code> item attribute <code>!INCAPS</code> returns the capabilities of the selected input device in the following format:

:<code>devicename ; MME|ASIO|* maxch|* minsr|* maxsr|* anysr{0|1}; sr1 .. srN; fmt1 .. fmtN;</code>

;<var>!INDEVICE</var>

:The <code>WAVE</code> item attribute <code>!INDEVICE</code> returns the id of the input wave device referenced by the mandatory second parameter <var>index</var>.

:E.g.:

:<code>$#wave[!indevice,$#wave[!indevices]-1]</code> // returns the id of the last available input device.

;<var>!INDEVICES</var>

:The <code>WAVE</code> item attribute <code>!INDEVICES</code> returns the number of installed wave recording devices.

;<var>!INSELECTED</var>

:The <code>WAVE</code> item attribute <code>!INSELECTED</code> returns the index of the wave device selected for recording functions.

;<var>!LENGTH</var>

:The <code>WAVE</code> item attribute <code>!LENGTH</code> returns the length of the signal in samples.

;<var>!OUTCAPS</var>

:The <code>WAVE</code> item attribute <code>!OUTCAPS</code> returns the capabilities of the selected output device in the following format:

:<code>devicename ; MME|ASIO|* maxch|* minsr|* maxsr|* anysr{0|1}; sr1 .. srN; fmt1 .. fmtN;</code>

;<var>!OUTDEVICE</var>

:The <code>WAVE</code> item attribute <code>!OUTDEVICE</code> returns the id of the output wave device referenced by the mandatory second parameter <var>index</var>.

:E.g.:

<pre>
$#wave[!outdevice,0] // returns the id of the first playback device
</pre>
;<var>!OUTDEVICES</var>

:The <code>WAVE</code> item attribute <code>!OUTDEVICES</code> returns the number of installed wave playback devices.

;<var>!OUTSELECTED</var>

:The <code>WAVE</code> item attribute <code>!OUTSELECTED</code> returns the index of the wave device selected for playback functions.

;<var>!PLAYGAIN</var>

:The <code>WAVE</code> item attribute <code>!PLAYGAIN</code> returns the linear gain value currently being used for playback. If a second parameter, <var>NewGainValue</var>, is specified, then the playback gain value is changed. If playback is in progress, the new gain value is first used when the current buffer has been played.

:Examples:

<pre>
#linearGainValue := $#wave[!PlayGain] // retrieve gain value
#linearGainValue := $#wave[!PlayGain, $(num $#linearGainValue + 1)] // increase the gain value by one.
</pre>
;<var>!PLAYSRATE</var>

:The <code>WAVE</code> item attribute <code>!PLAYGAIN</code> returns the sampling rate used for playback. If a second parameter, <var>NewPlaybackSRate</var>, is specified, then the playback sampling rate is set to this new value. See the script <code>playsrate.sts</code> for an example.

;<var>!POSITION</var>

:The <code>WAVE</code> item attribute <code>!POSITION</code> returns access position in samples of the attached device. The signal between <code>!BEGIN</code> and this position has already been processed. This value is empty if the wave item is not being played.

;<var>!PROGRESS</var>

:The <code>WAVE</code> item attribute <code>!PROGRESS</code> returns the amount of the signal which has been progressed as a percentage of its length.

;<var>!SIGNAL[,channel[,offset[,length]]]</var>
:The <code>WAVE</code> item attribute <code>!SIGNAL</code> returns the signal as a vector of samples in a shell table.
:You can also specify the channel, offset and length (e.g. <samp>$#wave[!signal,1]</samp>).

;<var>!SRATE</var>

:The <code>WAVE</code> item attribute <code>!SRATE</code> returns the sampling rate in Hz.

;<var>!TYPE</var>

:The <code>WAVE</code> item attribute <code>!TYPE</code> returns the type of the wave item or an empty string if no signal is addressed by wave item. The type is one of the following values:

:<code>STREAM</code>|<code>SEQUENCE</code>|<code>WAVE</code>|<code>ADC</code>|<code>DAC</code>

:For virtual wave items, the type of real wave item is returned.

;<var>!MODE</var>

:The <code>WAVE</code> item attribute <code>!MODE</code> returns <code>WRITE</code> if signal can be written to (stored in) the wave and <code>READ</code> if the signal can only be read but not changed

Programmer Guide/Shell Items/Dialog/SET DIALOG

2018-11-13T15:08:03Z

Toni: /* Setting the attributes of a control */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{Dialog Item}}
Use the [[Programmer_Guide/Shell_Items/Dialog/NEW_DIALOG|<code>NEW DIALOG</code>]] command for creating a [[Programmer_Guide/Shell_Items/Dialog|<code>DIALOG</code> shell item]]. Then apply the <code>SET <var>dialog</var></code> commands described here.

== Data Exchange==

SET <var>dialog</var> [ <var>ctrlId</var> ] /Read|Write
<var>dialog</var> [ <var>ctrlId</var> ] /Read|Write

Exchange data between the dialog controls and their respective variables.

{|class="keinrahmen"
| <var>ctrlId</var>
| colspan="2" | The optional id of an existing control. If specified, the exchange only takes place for this control. Otherwise, all data for all controls is exchanged.
|-
| rowspan="3" | <code>/Read</code> or <code>/Write</code>
| colspan="2" | The direction of data exchange (as seen from the shell).
|-
| <code>/Read</code> || reads the data out of the control into the shell variable.
|-
| <code>/Write</code> || sets the values of the controls.
|}

If you want to read or write only a subset of connected dialog controls, you may do so by using the command
SET <var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>fg</var> <var>bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ]
See [[Programmer_Guide/Shell_Items/Dialog/SET_DIALOG#Setting_the_attributes_of_a_control|Setting the attributes of a control]] on this page.

== Dialog Window Control ==

Set the display and/or dialog window mode, style position and/or size, and configure the dialog. If the option <code>/Read</code> (dialog → shell) or <code>/Write</code> (shell → dialog) is specified, a data exchange between the dialog controls and the variables and items bound to the controls is performed. The <var>mode</var> command has different functions for displays with only a dialog and for displays containing a dialog and graphs.

=== Dialog only ===

SET <var>dialog</var> <var>mode</var> [<var>style</var> <var>xpos</var> <var>ypos</var> <var>width</var> <var>height</var>] [/Centered /Foreground /Dialog /View /Layout|layout]

The dialog is enabled (window is created) and the command is forwarded to the display.

=== Dialog and graphs ===

SET <var>dialog</var> <var>mode</var> [/Read|Write]

The dialog window mode is set. Other arguments/options are ignored if specified.

=== Options ===

{|class="keinrahmen"
| <var>mode</var>
| The dialog window mode, one out of <code>NOWINDOW</code>, <code>HIDDEN</code>. <code>VISIBLE</code>, <code>ENABLED</code> and <code>*</code>). If <code>NOWINDOW</code> is used, the dialog window is destroyed and the dialog must be reconfigured (i.e. controls must be created etc).
|-
| <var>style</var>
| The window style (<code>MINIMIZE</code>, <code>MAXIMIZE</code> or <code>RESTORE</code>).
|-
| <var>xpos</var>
|The x-axis position in pixels of the upper left corner of the dialog relative to the desktop origin.
|-
| <var>ypos</var>
| The y-axis position in pixels of the upper left corner of the dialog relative to the desktop origin.
|-
| <var>width</var>
| The width of the dialog in pixels.
|-
| <var>height</var>
| The height of the dialog in pixels.
|-
| <code>/Centered</code>
| Center the display to the screen in which the mouse is currently. <var>xpos</var>, <var>ypos</var>, <var>width</var> and <var>height</var> are ignored.
|-
| <code>/Foreground</code>
| Send the window to the front (make the window the topmost window).
|-
| <code>/Dialog=<var>pos</var></code>
| Set dialog position inside the display (relative to graphs); changing the position is only possible if the dialog is non-floating. The following values for <var>pos</var> are allowed: <code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code>
|-
| <code>/View=<var>view</var></code>
| Set window view mode to <var>view</var> ('<code>WINDOW</code>' is a normal window, or '<code>FULLSCREEN</code>' = display takes up whole screen (for displays of type 'frame' only) or '<code>ALWAYSONTOP</code>' = the display remains on top, even when other windows are activated).
|-
| <code>/Layout</code> or <code>/layout</code>
| Recalculate the dialog window size, including (<code>/Layout</code> - note the upper-case "L") or ignoring (<code>/layout</code> - note the lower-case "l") hidden controls (this is one of our very few case-sensitive option letters).
|}

== Dialog Window Configuration==

=== <code>TITLE</code> ===

SET <var>dialog</var> TITLE <var>title</var>

Set the caption of the display owning the <var>dialog</var> to <var>title</var>. The caption can be an empty string. Note that it is advisable to surround the string <var>title</var> in quotes, since otherwise, only the first word of the string is interpreted as the title (the rest being additional arguments, which are ignored).

Code example:
SET $#dlg TITLE 'Der Wiener Schnitzel mit de Lavignetten und de Sauerkraut'

=== <code>LAYOUT</code> ===

SET <var>dialog</var> LAYOUT <var>font</var> <var>left</var> <var>top</var> <var>right</var> <var>bottom</var>

Set the dialog margins and the default font. The default font will be used for all ''newly'' created controls (the existing ones will keep their respective font). The unit for specifying margins is characters, just like the control position and size. So, if you specify a margin of <var>n</var>, it will be roughly as wide as a string of <var>n</var> characters would be ("roughly", because with proportional fonts, the single characters are of different widths). Note that each control may be assigned an individual font, thereby overriding this default font (see <code>SET dialog index controltype</code> below).

{|class="keinrahmen"
| <var>font</var>
| The default font (see Fonts and Font Arguments for details).
|-
| <var>left</var>, <var>right</var>
| The margin on the left/right side (in characters).
|-
| <var>top</var>, <var>bottom</var>
| The margin on the top/bottom (in characters).
|}

== Dialog Context Menus ==

It is possible to attach a set of context menus to each dialog. The displaying of the context menu is controlled by the programmer (normally by processing the messages <code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages|CMSTAT]]</code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages| and ]]<code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages|CMITEM]]</code> in a message handler). Context menus are identified by an id string (specified in the <code>ADDPOPUP /X</code> command) or a zero-based index (in the same order as the <code>ADDPOPUP</code> commands). Note: If the option /X is not supplied in a command, the menu handling command is forwarded to the display and used for popup-menu handling. For a detailed description of menu item formats and menu item index computation see command <code>[[Programmer_Guide/Shell_Items/Display/SET_DISPLAY#ADDPOPUP|SET display ADDPOPUP]]</code>.

=== <code>ADDPOPUP</code> ===

SET <var>dialog</var> ADDPOPUP /X <var>id</var> <var>item1</var> <var>item2</var> … <var>itemn</var>
SET <var>dialog</var> ADDPOPUP /X <var>id</var> <var>tableitem</var> /Table

Add a context menu to the dialog.

{|class="keinrahmen"
| <var>id</var>
| The id of the context menu in the dialog (a dialog can have more than one context menu). This is not shown in the menu itself.
|-
| <var>itemn</var>
| The menu items.
|-
| <var>tableItem</var>
| A table
|}

=== <code>SETPOPUP</code> ===

SET <var>dialog</var> SETPOPUP /X <var>index1</var> [ … <var>indexn</var> ] [ /Enable|Disable ] [ /Check|Uncheck ]

Activate or deactivate and/or set or clear the check state of menu items <var>index1</var> to <var>indexn</var>. The items may be located in different menus.

=== <code>DELPOPUP</code> ===

SET <var>dialog</var> DELPOPUP /X
SET <var>dialog</var> DELETEPOPUP /X

Delete all context menus. Note that you can replace an existing popup by just calling <code>ADDPOPUP</code> again with the same index.

=== <code>CONTEXTMENU</code> ===

SET <var>dialog</var> CONTEXTMENU <var>menuId</var>

Show the contextmenu with index or id <var>menuId</var>. This command is usually called in response to a <code>CMSTAT</code> message.

== Editing cells in a <code>LISTVIEW</code> ==

SET <var>dialogItem</var> <var>listviewIndex</var> STARTEDIT <var>col</var> <var>row</var>

Sets the dialog focus to the specified cell and enters edit mode. If the user presses ESC, Return or Enter, the control leaves edit mode. <var>col</var> and <var>row</var> are zero-based indices addressing the field and entry. See the example script <code>editabletable.sts</code> for a complete example.

== Dialog Control Configuration ==

=== Setting the attributes of a control ===

SET <var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>fg</var> <var>bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ]
<var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>fg</var> <var>bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ]

Set mode and attributes of a control.

;/N=<var>count</var>: apply settings to ''all'' controls in a range <var>index</var> to <code><var>index</var>+count-1</code>
;/Read, /Write: request data being transferred from the dialog to the connected shell variable/item (Read), or from the connected shell variable/item to the dialog control (Write) - for a description, see the [[Programmer_Guide/Shell_Items/Dialog/SET_DIALOG#Data_Exchange|Data Exchange]] section on this page. This data exchange will take place for the addressed control(s) only (as opposed to <code>SET dialog mode</code> which transfers data to/from ''all'' controls of the dialog).

{|class="keinrahmen"
| <var>index</var>
| The index of the (first) control.
|-
| <var>count</var>
| The number of controls (>= 1, default = 1).
|-
| <var>mode</var>
| The control mode (<code>*</code>, <code>HIDDEN</code>, <code>VISIBLE</code>, <code>ENABLED</code> or <code>TITLE</code>).

The <var>mode</var> <code>TITLE</code> is defined for compatibility to earlier versions only. It has the same meaning as <code>*</code> (do not change mode, just set attributes).
|-
| <var>title</var>
| The control caption.
|-
| <var>font</var>
| The control font. See Fonts and Font Arguments for details.
|-
| <var>fg</var>, <var>bg</var>
|The foreground (<var>fg</var>) and background (<var>bg</var>) color. You may use either a color keyword or an RGB value for each of <var>fg</var> and <var>bg</var>.
|}

The color and font specifications are described in the appendix. Note that color settings are applied to controls of type <code>static</code>, and to the caption of controls with a separate caption, window only.

SET <var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>row</var> <var>col</var> <var>width</var> <var>height</var> ] [ /Read|Write ] /Layout | /layout | /Setposition

Set mode, caption, font, position and size of a control
;/Layout: update position/size of the control and recompute dialog window layout
;/layout: update position/size of the control and recompute dialog window layout, ignore hidden controls
;/Setposition: update position/size of the control but do not recompute dialog window layout

{|class="keinrahmen"
| <var>row, col</var>
| new control position (use -1 or * if a value should not be changed)
|-
| <var>width, height</var>
| new control size (use -1 or * if a value should not be changed)
|}

=== <code>FOCUS</code> ===

SET <var>dialog</var> FOCUS
SET <var>dialog</var> <var>index</var> FOCUS

Give a particular control the input focus. All keyboard input is then directed to the control. This command can be used in setup or input dialogs to set the focus to the default input field after creating and displaying the dialog. If no index is specified or if its value is less than zero, the focus is set to the dialog window itself.

=== <code>INPUT</code> ===

SET <var>dialog</var> <var>index</var> INPUT <var>output</var>

Connect dialog control with a data output.

{|class="keinrahmen"
| <var>output</var>
| an SPU output or a value object
|}

=== <code>BITMAP</code> ===

SET dialog index BITMAP <var>buttonId</var>|<var>bitmapFile</var> [ <var>tooltipText</var> ][ /B ]

Assign a bitmap to a button or a static control. The assigned bitmap is displayed in its original size and colors in the center of the control. If no bitmap is specified, any existing assignment is removed. Bitmaps can be read from bitmap files (*.BMP) or from the {{STX}} resource file. To identify a resource the name (or index) of a bitmap resource (no option) or a toolbar button (option <code>/B</code>) can be used.

{| class="keinrahmen"
| valign="top" | <var>index</var>
| The 'button' or 'static' dialog control index.
|-
| valign="top" | <var>buttonId</var>
| The bitmap id or toolbar button id. See the "Bitmaps for Dialog Controls, Icons, Toolbar Buttons" topic in <GD> for a list of available b
|-
| valign="top" | <var>bitmapFile</var>
| The name of a bitmap file.
|-
| valign="top" | <var>tooltipText</var>
| If specified, this string will be displayed as a tooltip when the mouse hovers over the button. This parameter overrides any string associated with the bitmap (/b) in the resource file.
|-
| valign="top" | <code>/B</code>
| If the option <code>/B</code> is specified, the <var>buttonId</var> references a toolbar button (rather than a bitmap resource). [[Programmer_Guide/General_Descriptions/Bitmaps_for_Dialog_Controls,_Icons,_Toolbar_Buttons|Bitmaps for Dialog Controls, Icons, Toolbar Buttons]] shows all images available in {{STX}}.
|}

The <code>SET dialog index BITMAP</code> command only works once a dialog has been created, i.e. after <code>domodaldialog begin</code>.

== Dialog Control Creation ==

You can create a control in a dialog using the <code>SET dialog index controlType</code> commands defined below. All dialog controls must be created before the dialog is displayed for the first time. You can show and hide dialog controls once the dialog has been created with the <code>SET dialog mode</code> command. See [[Programmer_Guide/Shell_Items/Dialog/Dialog_Controls|Dialog Controls]] for a list of available controls and their individual creation syntax.

The number of controls per dialog is limited to 255 due to the MFC implementation.

Programmer Guide/Shell Items/Dialog/SET DIALOG

2018-11-13T15:06:38Z

Toni: /* Setting the attributes of a control */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{Dialog Item}}
Use the [[Programmer_Guide/Shell_Items/Dialog/NEW_DIALOG|<code>NEW DIALOG</code>]] command for creating a [[Programmer_Guide/Shell_Items/Dialog|<code>DIALOG</code> shell item]]. Then apply the <code>SET <var>dialog</var></code> commands described here.

== Data Exchange==

SET <var>dialog</var> [ <var>ctrlId</var> ] /Read|Write
<var>dialog</var> [ <var>ctrlId</var> ] /Read|Write

Exchange data between the dialog controls and their respective variables.

{|class="keinrahmen"
| <var>ctrlId</var>
| colspan="2" | The optional id of an existing control. If specified, the exchange only takes place for this control. Otherwise, all data for all controls is exchanged.
|-
| rowspan="3" | <code>/Read</code> or <code>/Write</code>
| colspan="2" | The direction of data exchange (as seen from the shell).
|-
| <code>/Read</code> || reads the data out of the control into the shell variable.
|-
| <code>/Write</code> || sets the values of the controls.
|}

If you want to read or write only a subset of connected dialog controls, you may do so by using the command
SET <var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>fg</var> <var>bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ]
See [[Programmer_Guide/Shell_Items/Dialog/SET_DIALOG#Setting_the_attributes_of_a_control|Setting the attributes of a control]] on this page.

== Dialog Window Control ==

Set the display and/or dialog window mode, style position and/or size, and configure the dialog. If the option <code>/Read</code> (dialog → shell) or <code>/Write</code> (shell → dialog) is specified, a data exchange between the dialog controls and the variables and items bound to the controls is performed. The <var>mode</var> command has different functions for displays with only a dialog and for displays containing a dialog and graphs.

=== Dialog only ===

SET <var>dialog</var> <var>mode</var> [<var>style</var> <var>xpos</var> <var>ypos</var> <var>width</var> <var>height</var>] [/Centered /Foreground /Dialog /View /Layout|layout]

The dialog is enabled (window is created) and the command is forwarded to the display.

=== Dialog and graphs ===

SET <var>dialog</var> <var>mode</var> [/Read|Write]

The dialog window mode is set. Other arguments/options are ignored if specified.

=== Options ===

{|class="keinrahmen"
| <var>mode</var>
| The dialog window mode, one out of <code>NOWINDOW</code>, <code>HIDDEN</code>. <code>VISIBLE</code>, <code>ENABLED</code> and <code>*</code>). If <code>NOWINDOW</code> is used, the dialog window is destroyed and the dialog must be reconfigured (i.e. controls must be created etc).
|-
| <var>style</var>
| The window style (<code>MINIMIZE</code>, <code>MAXIMIZE</code> or <code>RESTORE</code>).
|-
| <var>xpos</var>
|The x-axis position in pixels of the upper left corner of the dialog relative to the desktop origin.
|-
| <var>ypos</var>
| The y-axis position in pixels of the upper left corner of the dialog relative to the desktop origin.
|-
| <var>width</var>
| The width of the dialog in pixels.
|-
| <var>height</var>
| The height of the dialog in pixels.
|-
| <code>/Centered</code>
| Center the display to the screen in which the mouse is currently. <var>xpos</var>, <var>ypos</var>, <var>width</var> and <var>height</var> are ignored.
|-
| <code>/Foreground</code>
| Send the window to the front (make the window the topmost window).
|-
| <code>/Dialog=<var>pos</var></code>
| Set dialog position inside the display (relative to graphs); changing the position is only possible if the dialog is non-floating. The following values for <var>pos</var> are allowed: <code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code>
|-
| <code>/View=<var>view</var></code>
| Set window view mode to <var>view</var> ('<code>WINDOW</code>' is a normal window, or '<code>FULLSCREEN</code>' = display takes up whole screen (for displays of type 'frame' only) or '<code>ALWAYSONTOP</code>' = the display remains on top, even when other windows are activated).
|-
| <code>/Layout</code> or <code>/layout</code>
| Recalculate the dialog window size, including (<code>/Layout</code> - note the upper-case "L") or ignoring (<code>/layout</code> - note the lower-case "l") hidden controls (this is one of our very few case-sensitive option letters).
|}

== Dialog Window Configuration==

=== <code>TITLE</code> ===

SET <var>dialog</var> TITLE <var>title</var>

Set the caption of the display owning the <var>dialog</var> to <var>title</var>. The caption can be an empty string. Note that it is advisable to surround the string <var>title</var> in quotes, since otherwise, only the first word of the string is interpreted as the title (the rest being additional arguments, which are ignored).

Code example:
SET $#dlg TITLE 'Der Wiener Schnitzel mit de Lavignetten und de Sauerkraut'

=== <code>LAYOUT</code> ===

SET <var>dialog</var> LAYOUT <var>font</var> <var>left</var> <var>top</var> <var>right</var> <var>bottom</var>

Set the dialog margins and the default font. The default font will be used for all ''newly'' created controls (the existing ones will keep their respective font). The unit for specifying margins is characters, just like the control position and size. So, if you specify a margin of <var>n</var>, it will be roughly as wide as a string of <var>n</var> characters would be ("roughly", because with proportional fonts, the single characters are of different widths). Note that each control may be assigned an individual font, thereby overriding this default font (see <code>SET dialog index controltype</code> below).

{|class="keinrahmen"
| <var>font</var>
| The default font (see Fonts and Font Arguments for details).
|-
| <var>left</var>, <var>right</var>
| The margin on the left/right side (in characters).
|-
| <var>top</var>, <var>bottom</var>
| The margin on the top/bottom (in characters).
|}

== Dialog Context Menus ==

It is possible to attach a set of context menus to each dialog. The displaying of the context menu is controlled by the programmer (normally by processing the messages <code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages|CMSTAT]]</code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages| and ]]<code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages|CMITEM]]</code> in a message handler). Context menus are identified by an id string (specified in the <code>ADDPOPUP /X</code> command) or a zero-based index (in the same order as the <code>ADDPOPUP</code> commands). Note: If the option /X is not supplied in a command, the menu handling command is forwarded to the display and used for popup-menu handling. For a detailed description of menu item formats and menu item index computation see command <code>[[Programmer_Guide/Shell_Items/Display/SET_DISPLAY#ADDPOPUP|SET display ADDPOPUP]]</code>.

=== <code>ADDPOPUP</code> ===

SET <var>dialog</var> ADDPOPUP /X <var>id</var> <var>item1</var> <var>item2</var> … <var>itemn</var>
SET <var>dialog</var> ADDPOPUP /X <var>id</var> <var>tableitem</var> /Table

Add a context menu to the dialog.

{|class="keinrahmen"
| <var>id</var>
| The id of the context menu in the dialog (a dialog can have more than one context menu). This is not shown in the menu itself.
|-
| <var>itemn</var>
| The menu items.
|-
| <var>tableItem</var>
| A table
|}

=== <code>SETPOPUP</code> ===

SET <var>dialog</var> SETPOPUP /X <var>index1</var> [ … <var>indexn</var> ] [ /Enable|Disable ] [ /Check|Uncheck ]

Activate or deactivate and/or set or clear the check state of menu items <var>index1</var> to <var>indexn</var>. The items may be located in different menus.

=== <code>DELPOPUP</code> ===

SET <var>dialog</var> DELPOPUP /X
SET <var>dialog</var> DELETEPOPUP /X

Delete all context menus. Note that you can replace an existing popup by just calling <code>ADDPOPUP</code> again with the same index.

=== <code>CONTEXTMENU</code> ===

SET <var>dialog</var> CONTEXTMENU <var>menuId</var>

Show the contextmenu with index or id <var>menuId</var>. This command is usually called in response to a <code>CMSTAT</code> message.

== Editing cells in a <code>LISTVIEW</code> ==

SET <var>dialogItem</var> <var>listviewIndex</var> STARTEDIT <var>col</var> <var>row</var>

Sets the dialog focus to the specified cell and enters edit mode. If the user presses ESC, Return or Enter, the control leaves edit mode. <var>col</var> and <var>row</var> are zero-based indices addressing the field and entry. See the example script <code>editabletable.sts</code> for a complete example.

== Dialog Control Configuration ==

=== Setting the attributes of a control ===

SET <var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>fg</var> <var>bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ]
<var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>fg</var> <var>bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ]

Set mode and attributes of a control.

;/N=<var>count</var>: apply settings to ''all'' controls in a range <var>index</var> to <code><var>index</var>+count-1</code>
;/Read, /Write: request data being transferred from the dialog to the connected shell variable/item (Read), or from the connected shell variable/item to the dialog control (Write) - for a description, see the [[Programmer_Guide/Shell_Items/Dialog/SET_DIALOG#Data_Exchange|Data Exchange]] section on this page. This data exchange will take place for the addressed control(s) only (as opposed to <code>SET dialog mode</code> which transfers data to/from ''all'' controls of the dialog).

{|class="keinrahmen"
| <var>index</var>
| The index of the (first) control.
|-
| <var>count</var>
| The number of controls (>= 1, default = 1).
|-
| <var>mode</var>
| The control mode (<code>*</code>, <code>HIDDEN</code>, <code>VISIBLE</code>, <code>ENABLED</code> or <code>TITLE</code>).

The <var>mode</var> <code>TITLE</code> is defined for compatibility to earlier versions only. It has the same meaning as <code>*</code> (do not change mode, just set attributes).
|-
| <var>title</var>
| The control caption.
|-
| <var>font</var>
| The control font. See Fonts and Font Arguments for details.
|-
| <var>fg</var>, <var>bg</var>
|The foreground (<var>fg</var>) and background (<var>bg</var>) color. You may use either a color keyword or an RGB value for each of <var>fg</var> and <var>bg</var>.
|}

The color and font specifications are described in the appendix. Note that color settings are applied to controls of type <code>static</code>, and to the caption of controls with a separate caption, window only.

SET <var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>row</var> <var>col</var> <var>width</var> <var>height</var> ] [ /Read|Write ] /Layout | /layout | /Setposition

Set mode, caption, font, position and size of a control
;/Layout: update control and recompute dialog window layout
;/layout: update control and recompute dialog window layout, ignore hidden controls
;Setposition: update control but do not recompute dialog window layout

{|class="keinrahmen"
| <var>row, col</var>
| new control position (use -1 or * if a value should not be changed)
|-
| <var>width, height</var>
| new control size (use -1 or * if a value should not be changed)
|}

=== <code>FOCUS</code> ===

SET <var>dialog</var> FOCUS
SET <var>dialog</var> <var>index</var> FOCUS

Give a particular control the input focus. All keyboard input is then directed to the control. This command can be used in setup or input dialogs to set the focus to the default input field after creating and displaying the dialog. If no index is specified or if its value is less than zero, the focus is set to the dialog window itself.

=== <code>INPUT</code> ===

SET <var>dialog</var> <var>index</var> INPUT <var>output</var>

Connect dialog control with a data output.

{|class="keinrahmen"
| <var>output</var>
| an SPU output or a value object
|}

=== <code>BITMAP</code> ===

SET dialog index BITMAP <var>buttonId</var>|<var>bitmapFile</var> [ <var>tooltipText</var> ][ /B ]

Assign a bitmap to a button or a static control. The assigned bitmap is displayed in its original size and colors in the center of the control. If no bitmap is specified, any existing assignment is removed. Bitmaps can be read from bitmap files (*.BMP) or from the {{STX}} resource file. To identify a resource the name (or index) of a bitmap resource (no option) or a toolbar button (option <code>/B</code>) can be used.

{| class="keinrahmen"
| valign="top" | <var>index</var>
| The 'button' or 'static' dialog control index.
|-
| valign="top" | <var>buttonId</var>
| The bitmap id or toolbar button id. See the "Bitmaps for Dialog Controls, Icons, Toolbar Buttons" topic in <GD> for a list of available b
|-
| valign="top" | <var>bitmapFile</var>
| The name of a bitmap file.
|-
| valign="top" | <var>tooltipText</var>
| If specified, this string will be displayed as a tooltip when the mouse hovers over the button. This parameter overrides any string associated with the bitmap (/b) in the resource file.
|-
| valign="top" | <code>/B</code>
| If the option <code>/B</code> is specified, the <var>buttonId</var> references a toolbar button (rather than a bitmap resource). [[Programmer_Guide/General_Descriptions/Bitmaps_for_Dialog_Controls,_Icons,_Toolbar_Buttons|Bitmaps for Dialog Controls, Icons, Toolbar Buttons]] shows all images available in {{STX}}.
|}

The <code>SET dialog index BITMAP</code> command only works once a dialog has been created, i.e. after <code>domodaldialog begin</code>.

== Dialog Control Creation ==

You can create a control in a dialog using the <code>SET dialog index controlType</code> commands defined below. All dialog controls must be created before the dialog is displayed for the first time. You can show and hide dialog controls once the dialog has been created with the <code>SET dialog mode</code> command. See [[Programmer_Guide/Shell_Items/Dialog/Dialog_Controls|Dialog Controls]] for a list of available controls and their individual creation syntax.

The number of controls per dialog is limited to 255 due to the MFC implementation.

Programmer Guide/Shell Items/Dialog/SET DIALOG

2018-11-13T15:05:44Z

Toni: /* Setting the attributes of a control */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{Dialog Item}}
Use the [[Programmer_Guide/Shell_Items/Dialog/NEW_DIALOG|<code>NEW DIALOG</code>]] command for creating a [[Programmer_Guide/Shell_Items/Dialog|<code>DIALOG</code> shell item]]. Then apply the <code>SET <var>dialog</var></code> commands described here.

== Data Exchange==

SET <var>dialog</var> [ <var>ctrlId</var> ] /Read|Write
<var>dialog</var> [ <var>ctrlId</var> ] /Read|Write

Exchange data between the dialog controls and their respective variables.

{|class="keinrahmen"
| <var>ctrlId</var>
| colspan="2" | The optional id of an existing control. If specified, the exchange only takes place for this control. Otherwise, all data for all controls is exchanged.
|-
| rowspan="3" | <code>/Read</code> or <code>/Write</code>
| colspan="2" | The direction of data exchange (as seen from the shell).
|-
| <code>/Read</code> || reads the data out of the control into the shell variable.
|-
| <code>/Write</code> || sets the values of the controls.
|}

If you want to read or write only a subset of connected dialog controls, you may do so by using the command
SET <var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>fg</var> <var>bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ]
See [[Programmer_Guide/Shell_Items/Dialog/SET_DIALOG#Setting_the_attributes_of_a_control|Setting the attributes of a control]] on this page.

== Dialog Window Control ==

Set the display and/or dialog window mode, style position and/or size, and configure the dialog. If the option <code>/Read</code> (dialog → shell) or <code>/Write</code> (shell → dialog) is specified, a data exchange between the dialog controls and the variables and items bound to the controls is performed. The <var>mode</var> command has different functions for displays with only a dialog and for displays containing a dialog and graphs.

=== Dialog only ===

SET <var>dialog</var> <var>mode</var> [<var>style</var> <var>xpos</var> <var>ypos</var> <var>width</var> <var>height</var>] [/Centered /Foreground /Dialog /View /Layout|layout]

The dialog is enabled (window is created) and the command is forwarded to the display.

=== Dialog and graphs ===

SET <var>dialog</var> <var>mode</var> [/Read|Write]

The dialog window mode is set. Other arguments/options are ignored if specified.

=== Options ===

{|class="keinrahmen"
| <var>mode</var>
| The dialog window mode, one out of <code>NOWINDOW</code>, <code>HIDDEN</code>. <code>VISIBLE</code>, <code>ENABLED</code> and <code>*</code>). If <code>NOWINDOW</code> is used, the dialog window is destroyed and the dialog must be reconfigured (i.e. controls must be created etc).
|-
| <var>style</var>
| The window style (<code>MINIMIZE</code>, <code>MAXIMIZE</code> or <code>RESTORE</code>).
|-
| <var>xpos</var>
|The x-axis position in pixels of the upper left corner of the dialog relative to the desktop origin.
|-
| <var>ypos</var>
| The y-axis position in pixels of the upper left corner of the dialog relative to the desktop origin.
|-
| <var>width</var>
| The width of the dialog in pixels.
|-
| <var>height</var>
| The height of the dialog in pixels.
|-
| <code>/Centered</code>
| Center the display to the screen in which the mouse is currently. <var>xpos</var>, <var>ypos</var>, <var>width</var> and <var>height</var> are ignored.
|-
| <code>/Foreground</code>
| Send the window to the front (make the window the topmost window).
|-
| <code>/Dialog=<var>pos</var></code>
| Set dialog position inside the display (relative to graphs); changing the position is only possible if the dialog is non-floating. The following values for <var>pos</var> are allowed: <code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code>
|-
| <code>/View=<var>view</var></code>
| Set window view mode to <var>view</var> ('<code>WINDOW</code>' is a normal window, or '<code>FULLSCREEN</code>' = display takes up whole screen (for displays of type 'frame' only) or '<code>ALWAYSONTOP</code>' = the display remains on top, even when other windows are activated).
|-
| <code>/Layout</code> or <code>/layout</code>
| Recalculate the dialog window size, including (<code>/Layout</code> - note the upper-case "L") or ignoring (<code>/layout</code> - note the lower-case "l") hidden controls (this is one of our very few case-sensitive option letters).
|}

== Dialog Window Configuration==

=== <code>TITLE</code> ===

SET <var>dialog</var> TITLE <var>title</var>

Set the caption of the display owning the <var>dialog</var> to <var>title</var>. The caption can be an empty string. Note that it is advisable to surround the string <var>title</var> in quotes, since otherwise, only the first word of the string is interpreted as the title (the rest being additional arguments, which are ignored).

Code example:
SET $#dlg TITLE 'Der Wiener Schnitzel mit de Lavignetten und de Sauerkraut'

=== <code>LAYOUT</code> ===

SET <var>dialog</var> LAYOUT <var>font</var> <var>left</var> <var>top</var> <var>right</var> <var>bottom</var>

Set the dialog margins and the default font. The default font will be used for all ''newly'' created controls (the existing ones will keep their respective font). The unit for specifying margins is characters, just like the control position and size. So, if you specify a margin of <var>n</var>, it will be roughly as wide as a string of <var>n</var> characters would be ("roughly", because with proportional fonts, the single characters are of different widths). Note that each control may be assigned an individual font, thereby overriding this default font (see <code>SET dialog index controltype</code> below).

{|class="keinrahmen"
| <var>font</var>
| The default font (see Fonts and Font Arguments for details).
|-
| <var>left</var>, <var>right</var>
| The margin on the left/right side (in characters).
|-
| <var>top</var>, <var>bottom</var>
| The margin on the top/bottom (in characters).
|}

== Dialog Context Menus ==

It is possible to attach a set of context menus to each dialog. The displaying of the context menu is controlled by the programmer (normally by processing the messages <code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages|CMSTAT]]</code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages| and ]]<code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages|CMITEM]]</code> in a message handler). Context menus are identified by an id string (specified in the <code>ADDPOPUP /X</code> command) or a zero-based index (in the same order as the <code>ADDPOPUP</code> commands). Note: If the option /X is not supplied in a command, the menu handling command is forwarded to the display and used for popup-menu handling. For a detailed description of menu item formats and menu item index computation see command <code>[[Programmer_Guide/Shell_Items/Display/SET_DISPLAY#ADDPOPUP|SET display ADDPOPUP]]</code>.

=== <code>ADDPOPUP</code> ===

SET <var>dialog</var> ADDPOPUP /X <var>id</var> <var>item1</var> <var>item2</var> … <var>itemn</var>
SET <var>dialog</var> ADDPOPUP /X <var>id</var> <var>tableitem</var> /Table

Add a context menu to the dialog.

{|class="keinrahmen"
| <var>id</var>
| The id of the context menu in the dialog (a dialog can have more than one context menu). This is not shown in the menu itself.
|-
| <var>itemn</var>
| The menu items.
|-
| <var>tableItem</var>
| A table
|}

=== <code>SETPOPUP</code> ===

SET <var>dialog</var> SETPOPUP /X <var>index1</var> [ … <var>indexn</var> ] [ /Enable|Disable ] [ /Check|Uncheck ]

Activate or deactivate and/or set or clear the check state of menu items <var>index1</var> to <var>indexn</var>. The items may be located in different menus.

=== <code>DELPOPUP</code> ===

SET <var>dialog</var> DELPOPUP /X
SET <var>dialog</var> DELETEPOPUP /X

Delete all context menus. Note that you can replace an existing popup by just calling <code>ADDPOPUP</code> again with the same index.

=== <code>CONTEXTMENU</code> ===

SET <var>dialog</var> CONTEXTMENU <var>menuId</var>

Show the contextmenu with index or id <var>menuId</var>. This command is usually called in response to a <code>CMSTAT</code> message.

== Editing cells in a <code>LISTVIEW</code> ==

SET <var>dialogItem</var> <var>listviewIndex</var> STARTEDIT <var>col</var> <var>row</var>

Sets the dialog focus to the specified cell and enters edit mode. If the user presses ESC, Return or Enter, the control leaves edit mode. <var>col</var> and <var>row</var> are zero-based indices addressing the field and entry. See the example script <code>editabletable.sts</code> for a complete example.

== Dialog Control Configuration ==

=== Setting the attributes of a control ===

SET <var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>fg</var> <var>bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ]
<var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>fg</var> <var>bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ]

Set mode and attributes of a control.

;/N=<var>count</var>: apply settings to ''all'' controls in a range <var>index</var> to <code><var>index</var>+count-1</code>
;/Read, /Write: request data being transferred from the dialog to the connected shell variable/item (Read), or from the connected shell variable/item to the dialog control (Write) - for a description, see the [[Programmer_Guide/Shell_Items/Dialog/SET_DIALOG#Data_Exchange|Data Exchange]] section on this page. This data exchange will take place for the addressed control(s) only (as opposed to <code>SET dialog mode</code> which transfers data to/from ''all'' controls of the dialog).

{|class="keinrahmen"
| <var>index</var>
| The index of the (first) control.
|-
| <var>count</var>
| The number of controls (>= 1, default = 1).
|-
| <var>mode</var>
| The control mode (<code>*</code>, <code>HIDDEN</code>, <code>VISIBLE</code>, <code>ENABLED</code> or <code>TITLE</code>).

The <var>mode</var> <code>TITLE</code> is defined for compatibility to earlier versions only. It has the same meaning as <code>*</code> (do not change mode, just set attributes).
|-
| <var>title</var>
| The control caption.
|-
| <var>font</var>
| The control font. See Fonts and Font Arguments for details.
|-
| <var>fg</var>, <var>bg</var>
|The foreground (<var>fg</var>) and background (<var>bg</var>) color. You may use either a color keyword or an RGB value for each of <var>fg</var> and <var>bg</var>.
|}

The color and font specifications are described in the appendix. Note that color settings are applied to controls of type <code>static</code>, and to the caption of controls with a separate caption, window only.

SET <var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>row</var> <var>col</var> <var>width</var> <var>height</var> ] [ /Read|Write ] /Layout | /layout | /Setposition

This command can be used to update the caption, font, position and size of a control
;/Layout: update control and recompute dialog window layout
;/layout: update control and recompute dialog window layout, ignore hidden controls
;Setposition: update control but do not recompute dialog window layout

{|class="keinrahmen"
| <var>row, col</var>
| new control position (use -1 or * if a value should not be changed)
|-
| <var>width, height</var>
| new control size (use -1 or * if a value should not be changed)
|}

=== <code>FOCUS</code> ===

SET <var>dialog</var> FOCUS
SET <var>dialog</var> <var>index</var> FOCUS

Give a particular control the input focus. All keyboard input is then directed to the control. This command can be used in setup or input dialogs to set the focus to the default input field after creating and displaying the dialog. If no index is specified or if its value is less than zero, the focus is set to the dialog window itself.

=== <code>INPUT</code> ===

SET <var>dialog</var> <var>index</var> INPUT <var>output</var>

Connect dialog control with a data output.

{|class="keinrahmen"
| <var>output</var>
| an SPU output or a value object
|}

=== <code>BITMAP</code> ===

SET dialog index BITMAP <var>buttonId</var>|<var>bitmapFile</var> [ <var>tooltipText</var> ][ /B ]

Assign a bitmap to a button or a static control. The assigned bitmap is displayed in its original size and colors in the center of the control. If no bitmap is specified, any existing assignment is removed. Bitmaps can be read from bitmap files (*.BMP) or from the {{STX}} resource file. To identify a resource the name (or index) of a bitmap resource (no option) or a toolbar button (option <code>/B</code>) can be used.

{| class="keinrahmen"
| valign="top" | <var>index</var>
| The 'button' or 'static' dialog control index.
|-
| valign="top" | <var>buttonId</var>
| The bitmap id or toolbar button id. See the "Bitmaps for Dialog Controls, Icons, Toolbar Buttons" topic in <GD> for a list of available b
|-
| valign="top" | <var>bitmapFile</var>
| The name of a bitmap file.
|-
| valign="top" | <var>tooltipText</var>
| If specified, this string will be displayed as a tooltip when the mouse hovers over the button. This parameter overrides any string associated with the bitmap (/b) in the resource file.
|-
| valign="top" | <code>/B</code>
| If the option <code>/B</code> is specified, the <var>buttonId</var> references a toolbar button (rather than a bitmap resource). [[Programmer_Guide/General_Descriptions/Bitmaps_for_Dialog_Controls,_Icons,_Toolbar_Buttons|Bitmaps for Dialog Controls, Icons, Toolbar Buttons]] shows all images available in {{STX}}.
|}

The <code>SET dialog index BITMAP</code> command only works once a dialog has been created, i.e. after <code>domodaldialog begin</code>.

== Dialog Control Creation ==

You can create a control in a dialog using the <code>SET dialog index controlType</code> commands defined below. All dialog controls must be created before the dialog is displayed for the first time. You can show and hide dialog controls once the dialog has been created with the <code>SET dialog mode</code> command. See [[Programmer_Guide/Shell_Items/Dialog/Dialog_Controls|Dialog Controls]] for a list of available controls and their individual creation syntax.

The number of controls per dialog is limited to 255 due to the MFC implementation.

Programmer Guide/Shell Items/Dialog/SET DIALOG

2018-11-13T15:05:09Z

Toni: /* Setting the attributes of a control */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{Dialog Item}}
Use the [[Programmer_Guide/Shell_Items/Dialog/NEW_DIALOG|<code>NEW DIALOG</code>]] command for creating a [[Programmer_Guide/Shell_Items/Dialog|<code>DIALOG</code> shell item]]. Then apply the <code>SET <var>dialog</var></code> commands described here.

== Data Exchange==

SET <var>dialog</var> [ <var>ctrlId</var> ] /Read|Write
<var>dialog</var> [ <var>ctrlId</var> ] /Read|Write

Exchange data between the dialog controls and their respective variables.

{|class="keinrahmen"
| <var>ctrlId</var>
| colspan="2" | The optional id of an existing control. If specified, the exchange only takes place for this control. Otherwise, all data for all controls is exchanged.
|-
| rowspan="3" | <code>/Read</code> or <code>/Write</code>
| colspan="2" | The direction of data exchange (as seen from the shell).
|-
| <code>/Read</code> || reads the data out of the control into the shell variable.
|-
| <code>/Write</code> || sets the values of the controls.
|}

If you want to read or write only a subset of connected dialog controls, you may do so by using the command
SET <var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>fg</var> <var>bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ]
See [[Programmer_Guide/Shell_Items/Dialog/SET_DIALOG#Setting_the_attributes_of_a_control|Setting the attributes of a control]] on this page.

== Dialog Window Control ==

Set the display and/or dialog window mode, style position and/or size, and configure the dialog. If the option <code>/Read</code> (dialog → shell) or <code>/Write</code> (shell → dialog) is specified, a data exchange between the dialog controls and the variables and items bound to the controls is performed. The <var>mode</var> command has different functions for displays with only a dialog and for displays containing a dialog and graphs.

=== Dialog only ===

SET <var>dialog</var> <var>mode</var> [<var>style</var> <var>xpos</var> <var>ypos</var> <var>width</var> <var>height</var>] [/Centered /Foreground /Dialog /View /Layout|layout]

The dialog is enabled (window is created) and the command is forwarded to the display.

=== Dialog and graphs ===

SET <var>dialog</var> <var>mode</var> [/Read|Write]

The dialog window mode is set. Other arguments/options are ignored if specified.

=== Options ===

{|class="keinrahmen"
| <var>mode</var>
| The dialog window mode, one out of <code>NOWINDOW</code>, <code>HIDDEN</code>. <code>VISIBLE</code>, <code>ENABLED</code> and <code>*</code>). If <code>NOWINDOW</code> is used, the dialog window is destroyed and the dialog must be reconfigured (i.e. controls must be created etc).
|-
| <var>style</var>
| The window style (<code>MINIMIZE</code>, <code>MAXIMIZE</code> or <code>RESTORE</code>).
|-
| <var>xpos</var>
|The x-axis position in pixels of the upper left corner of the dialog relative to the desktop origin.
|-
| <var>ypos</var>
| The y-axis position in pixels of the upper left corner of the dialog relative to the desktop origin.
|-
| <var>width</var>
| The width of the dialog in pixels.
|-
| <var>height</var>
| The height of the dialog in pixels.
|-
| <code>/Centered</code>
| Center the display to the screen in which the mouse is currently. <var>xpos</var>, <var>ypos</var>, <var>width</var> and <var>height</var> are ignored.
|-
| <code>/Foreground</code>
| Send the window to the front (make the window the topmost window).
|-
| <code>/Dialog=<var>pos</var></code>
| Set dialog position inside the display (relative to graphs); changing the position is only possible if the dialog is non-floating. The following values for <var>pos</var> are allowed: <code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code>
|-
| <code>/View=<var>view</var></code>
| Set window view mode to <var>view</var> ('<code>WINDOW</code>' is a normal window, or '<code>FULLSCREEN</code>' = display takes up whole screen (for displays of type 'frame' only) or '<code>ALWAYSONTOP</code>' = the display remains on top, even when other windows are activated).
|-
| <code>/Layout</code> or <code>/layout</code>
| Recalculate the dialog window size, including (<code>/Layout</code> - note the upper-case "L") or ignoring (<code>/layout</code> - note the lower-case "l") hidden controls (this is one of our very few case-sensitive option letters).
|}

== Dialog Window Configuration==

=== <code>TITLE</code> ===

SET <var>dialog</var> TITLE <var>title</var>

Set the caption of the display owning the <var>dialog</var> to <var>title</var>. The caption can be an empty string. Note that it is advisable to surround the string <var>title</var> in quotes, since otherwise, only the first word of the string is interpreted as the title (the rest being additional arguments, which are ignored).

Code example:
SET $#dlg TITLE 'Der Wiener Schnitzel mit de Lavignetten und de Sauerkraut'

=== <code>LAYOUT</code> ===

SET <var>dialog</var> LAYOUT <var>font</var> <var>left</var> <var>top</var> <var>right</var> <var>bottom</var>

Set the dialog margins and the default font. The default font will be used for all ''newly'' created controls (the existing ones will keep their respective font). The unit for specifying margins is characters, just like the control position and size. So, if you specify a margin of <var>n</var>, it will be roughly as wide as a string of <var>n</var> characters would be ("roughly", because with proportional fonts, the single characters are of different widths). Note that each control may be assigned an individual font, thereby overriding this default font (see <code>SET dialog index controltype</code> below).

{|class="keinrahmen"
| <var>font</var>
| The default font (see Fonts and Font Arguments for details).
|-
| <var>left</var>, <var>right</var>
| The margin on the left/right side (in characters).
|-
| <var>top</var>, <var>bottom</var>
| The margin on the top/bottom (in characters).
|}

== Dialog Context Menus ==

It is possible to attach a set of context menus to each dialog. The displaying of the context menu is controlled by the programmer (normally by processing the messages <code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages|CMSTAT]]</code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages| and ]]<code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages|CMITEM]]</code> in a message handler). Context menus are identified by an id string (specified in the <code>ADDPOPUP /X</code> command) or a zero-based index (in the same order as the <code>ADDPOPUP</code> commands). Note: If the option /X is not supplied in a command, the menu handling command is forwarded to the display and used for popup-menu handling. For a detailed description of menu item formats and menu item index computation see command <code>[[Programmer_Guide/Shell_Items/Display/SET_DISPLAY#ADDPOPUP|SET display ADDPOPUP]]</code>.

=== <code>ADDPOPUP</code> ===

SET <var>dialog</var> ADDPOPUP /X <var>id</var> <var>item1</var> <var>item2</var> … <var>itemn</var>
SET <var>dialog</var> ADDPOPUP /X <var>id</var> <var>tableitem</var> /Table

Add a context menu to the dialog.

{|class="keinrahmen"
| <var>id</var>
| The id of the context menu in the dialog (a dialog can have more than one context menu). This is not shown in the menu itself.
|-
| <var>itemn</var>
| The menu items.
|-
| <var>tableItem</var>
| A table
|}

=== <code>SETPOPUP</code> ===

SET <var>dialog</var> SETPOPUP /X <var>index1</var> [ … <var>indexn</var> ] [ /Enable|Disable ] [ /Check|Uncheck ]

Activate or deactivate and/or set or clear the check state of menu items <var>index1</var> to <var>indexn</var>. The items may be located in different menus.

=== <code>DELPOPUP</code> ===

SET <var>dialog</var> DELPOPUP /X
SET <var>dialog</var> DELETEPOPUP /X

Delete all context menus. Note that you can replace an existing popup by just calling <code>ADDPOPUP</code> again with the same index.

=== <code>CONTEXTMENU</code> ===

SET <var>dialog</var> CONTEXTMENU <var>menuId</var>

Show the contextmenu with index or id <var>menuId</var>. This command is usually called in response to a <code>CMSTAT</code> message.

== Editing cells in a <code>LISTVIEW</code> ==

SET <var>dialogItem</var> <var>listviewIndex</var> STARTEDIT <var>col</var> <var>row</var>

Sets the dialog focus to the specified cell and enters edit mode. If the user presses ESC, Return or Enter, the control leaves edit mode. <var>col</var> and <var>row</var> are zero-based indices addressing the field and entry. See the example script <code>editabletable.sts</code> for a complete example.

== Dialog Control Configuration ==

=== Setting the attributes of a control ===

SET <var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>fg</var> <var>bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ]
<var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>fg</var> <var>bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ]

Set mode and attributes of a control.

;/N=<var>count</var>: apply settings to ''all'' controls in a range <var>index</var> to <code><var>index</var>+count-1</code>
;/Read, /Write: request data being transferred from the dialog to the connected shell variable (Read), or from the connected shell variable to the dialog control (Write) - for a description, see the [[Programmer_Guide/Shell_Items/Dialog/SET_DIALOG#Data_Exchange|Data Exchange]] section on this page. This data exchange will take place for the addressed control(s) only (as opposed to <code>SET dialog mode</code> which transfers data to/from ''all'' controls of the dialog).

{|class="keinrahmen"
| <var>index</var>
| The index of the (first) control.
|-
| <var>count</var>
| The number of controls (>= 1, default = 1).
|-
| <var>mode</var>
| The control mode (<code>*</code>, <code>HIDDEN</code>, <code>VISIBLE</code>, <code>ENABLED</code> or <code>TITLE</code>).

The <var>mode</var> <code>TITLE</code> is defined for compatibility to earlier versions only. It has the same meaning as <code>*</code> (do not change mode, just set attributes).
|-
| <var>title</var>
| The control caption.
|-
| <var>font</var>
| The control font. See Fonts and Font Arguments for details.
|-
| <var>fg</var>, <var>bg</var>
|The foreground (<var>fg</var>) and background (<var>bg</var>) color. You may use either a color keyword or an RGB value for each of <var>fg</var> and <var>bg</var>.
|}

The color and font specifications are described in the appendix. Note that color settings are applied to controls of type <code>static</code>, and to the caption of controls with a separate caption, window only.

SET <var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>row</var> <var>col</var> <var>width</var> <var>height</var> ] [ /Read|Write ] /Layout | /layout | /Setposition

This command can be used to update the caption, font, position and size of a control
;/Layout: update control and recompute dialog window layout
;/layout: update control and recompute dialog window layout, ignore hidden controls
;Setposition: update control but do not recompute dialog window layout

{|class="keinrahmen"
| <var>row, col</var>
| new control position (use -1 or * if a value should not be changed)
|-
| <var>width, height</var>
| new control size (use -1 or * if a value should not be changed)
|}

=== <code>FOCUS</code> ===

SET <var>dialog</var> FOCUS
SET <var>dialog</var> <var>index</var> FOCUS

Give a particular control the input focus. All keyboard input is then directed to the control. This command can be used in setup or input dialogs to set the focus to the default input field after creating and displaying the dialog. If no index is specified or if its value is less than zero, the focus is set to the dialog window itself.

=== <code>INPUT</code> ===

SET <var>dialog</var> <var>index</var> INPUT <var>output</var>

Connect dialog control with a data output.

{|class="keinrahmen"
| <var>output</var>
| an SPU output or a value object
|}

=== <code>BITMAP</code> ===

SET dialog index BITMAP <var>buttonId</var>|<var>bitmapFile</var> [ <var>tooltipText</var> ][ /B ]

Assign a bitmap to a button or a static control. The assigned bitmap is displayed in its original size and colors in the center of the control. If no bitmap is specified, any existing assignment is removed. Bitmaps can be read from bitmap files (*.BMP) or from the {{STX}} resource file. To identify a resource the name (or index) of a bitmap resource (no option) or a toolbar button (option <code>/B</code>) can be used.

{| class="keinrahmen"
| valign="top" | <var>index</var>
| The 'button' or 'static' dialog control index.
|-
| valign="top" | <var>buttonId</var>
| The bitmap id or toolbar button id. See the "Bitmaps for Dialog Controls, Icons, Toolbar Buttons" topic in <GD> for a list of available b
|-
| valign="top" | <var>bitmapFile</var>
| The name of a bitmap file.
|-
| valign="top" | <var>tooltipText</var>
| If specified, this string will be displayed as a tooltip when the mouse hovers over the button. This parameter overrides any string associated with the bitmap (/b) in the resource file.
|-
| valign="top" | <code>/B</code>
| If the option <code>/B</code> is specified, the <var>buttonId</var> references a toolbar button (rather than a bitmap resource). [[Programmer_Guide/General_Descriptions/Bitmaps_for_Dialog_Controls,_Icons,_Toolbar_Buttons|Bitmaps for Dialog Controls, Icons, Toolbar Buttons]] shows all images available in {{STX}}.
|}

The <code>SET dialog index BITMAP</code> command only works once a dialog has been created, i.e. after <code>domodaldialog begin</code>.

== Dialog Control Creation ==

You can create a control in a dialog using the <code>SET dialog index controlType</code> commands defined below. All dialog controls must be created before the dialog is displayed for the first time. You can show and hide dialog controls once the dialog has been created with the <code>SET dialog mode</code> command. See [[Programmer_Guide/Shell_Items/Dialog/Dialog_Controls|Dialog Controls]] for a list of available controls and their individual creation syntax.

The number of controls per dialog is limited to 255 due to the MFC implementation.

Programmer Guide/Shell Items/Dialog/SET DIALOG

2018-11-13T15:04:37Z

Toni: /* Setting the attributes of a control */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{Dialog Item}}
Use the [[Programmer_Guide/Shell_Items/Dialog/NEW_DIALOG|<code>NEW DIALOG</code>]] command for creating a [[Programmer_Guide/Shell_Items/Dialog|<code>DIALOG</code> shell item]]. Then apply the <code>SET <var>dialog</var></code> commands described here.

== Data Exchange==

SET <var>dialog</var> [ <var>ctrlId</var> ] /Read|Write
<var>dialog</var> [ <var>ctrlId</var> ] /Read|Write

Exchange data between the dialog controls and their respective variables.

{|class="keinrahmen"
| <var>ctrlId</var>
| colspan="2" | The optional id of an existing control. If specified, the exchange only takes place for this control. Otherwise, all data for all controls is exchanged.
|-
| rowspan="3" | <code>/Read</code> or <code>/Write</code>
| colspan="2" | The direction of data exchange (as seen from the shell).
|-
| <code>/Read</code> || reads the data out of the control into the shell variable.
|-
| <code>/Write</code> || sets the values of the controls.
|}

If you want to read or write only a subset of connected dialog controls, you may do so by using the command
SET <var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>fg</var> <var>bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ]
See [[Programmer_Guide/Shell_Items/Dialog/SET_DIALOG#Setting_the_attributes_of_a_control|Setting the attributes of a control]] on this page.

== Dialog Window Control ==

Set the display and/or dialog window mode, style position and/or size, and configure the dialog. If the option <code>/Read</code> (dialog → shell) or <code>/Write</code> (shell → dialog) is specified, a data exchange between the dialog controls and the variables and items bound to the controls is performed. The <var>mode</var> command has different functions for displays with only a dialog and for displays containing a dialog and graphs.

=== Dialog only ===

SET <var>dialog</var> <var>mode</var> [<var>style</var> <var>xpos</var> <var>ypos</var> <var>width</var> <var>height</var>] [/Centered /Foreground /Dialog /View /Layout|layout]

The dialog is enabled (window is created) and the command is forwarded to the display.

=== Dialog and graphs ===

SET <var>dialog</var> <var>mode</var> [/Read|Write]

The dialog window mode is set. Other arguments/options are ignored if specified.

=== Options ===

{|class="keinrahmen"
| <var>mode</var>
| The dialog window mode, one out of <code>NOWINDOW</code>, <code>HIDDEN</code>. <code>VISIBLE</code>, <code>ENABLED</code> and <code>*</code>). If <code>NOWINDOW</code> is used, the dialog window is destroyed and the dialog must be reconfigured (i.e. controls must be created etc).
|-
| <var>style</var>
| The window style (<code>MINIMIZE</code>, <code>MAXIMIZE</code> or <code>RESTORE</code>).
|-
| <var>xpos</var>
|The x-axis position in pixels of the upper left corner of the dialog relative to the desktop origin.
|-
| <var>ypos</var>
| The y-axis position in pixels of the upper left corner of the dialog relative to the desktop origin.
|-
| <var>width</var>
| The width of the dialog in pixels.
|-
| <var>height</var>
| The height of the dialog in pixels.
|-
| <code>/Centered</code>
| Center the display to the screen in which the mouse is currently. <var>xpos</var>, <var>ypos</var>, <var>width</var> and <var>height</var> are ignored.
|-
| <code>/Foreground</code>
| Send the window to the front (make the window the topmost window).
|-
| <code>/Dialog=<var>pos</var></code>
| Set dialog position inside the display (relative to graphs); changing the position is only possible if the dialog is non-floating. The following values for <var>pos</var> are allowed: <code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code>
|-
| <code>/View=<var>view</var></code>
| Set window view mode to <var>view</var> ('<code>WINDOW</code>' is a normal window, or '<code>FULLSCREEN</code>' = display takes up whole screen (for displays of type 'frame' only) or '<code>ALWAYSONTOP</code>' = the display remains on top, even when other windows are activated).
|-
| <code>/Layout</code> or <code>/layout</code>
| Recalculate the dialog window size, including (<code>/Layout</code> - note the upper-case "L") or ignoring (<code>/layout</code> - note the lower-case "l") hidden controls (this is one of our very few case-sensitive option letters).
|}

== Dialog Window Configuration==

=== <code>TITLE</code> ===

SET <var>dialog</var> TITLE <var>title</var>

Set the caption of the display owning the <var>dialog</var> to <var>title</var>. The caption can be an empty string. Note that it is advisable to surround the string <var>title</var> in quotes, since otherwise, only the first word of the string is interpreted as the title (the rest being additional arguments, which are ignored).

Code example:
SET $#dlg TITLE 'Der Wiener Schnitzel mit de Lavignetten und de Sauerkraut'

=== <code>LAYOUT</code> ===

SET <var>dialog</var> LAYOUT <var>font</var> <var>left</var> <var>top</var> <var>right</var> <var>bottom</var>

Set the dialog margins and the default font. The default font will be used for all ''newly'' created controls (the existing ones will keep their respective font). The unit for specifying margins is characters, just like the control position and size. So, if you specify a margin of <var>n</var>, it will be roughly as wide as a string of <var>n</var> characters would be ("roughly", because with proportional fonts, the single characters are of different widths). Note that each control may be assigned an individual font, thereby overriding this default font (see <code>SET dialog index controltype</code> below).

{|class="keinrahmen"
| <var>font</var>
| The default font (see Fonts and Font Arguments for details).
|-
| <var>left</var>, <var>right</var>
| The margin on the left/right side (in characters).
|-
| <var>top</var>, <var>bottom</var>
| The margin on the top/bottom (in characters).
|}

== Dialog Context Menus ==

It is possible to attach a set of context menus to each dialog. The displaying of the context menu is controlled by the programmer (normally by processing the messages <code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages|CMSTAT]]</code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages| and ]]<code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages|CMITEM]]</code> in a message handler). Context menus are identified by an id string (specified in the <code>ADDPOPUP /X</code> command) or a zero-based index (in the same order as the <code>ADDPOPUP</code> commands). Note: If the option /X is not supplied in a command, the menu handling command is forwarded to the display and used for popup-menu handling. For a detailed description of menu item formats and menu item index computation see command <code>[[Programmer_Guide/Shell_Items/Display/SET_DISPLAY#ADDPOPUP|SET display ADDPOPUP]]</code>.

=== <code>ADDPOPUP</code> ===

SET <var>dialog</var> ADDPOPUP /X <var>id</var> <var>item1</var> <var>item2</var> … <var>itemn</var>
SET <var>dialog</var> ADDPOPUP /X <var>id</var> <var>tableitem</var> /Table

Add a context menu to the dialog.

{|class="keinrahmen"
| <var>id</var>
| The id of the context menu in the dialog (a dialog can have more than one context menu). This is not shown in the menu itself.
|-
| <var>itemn</var>
| The menu items.
|-
| <var>tableItem</var>
| A table
|}

=== <code>SETPOPUP</code> ===

SET <var>dialog</var> SETPOPUP /X <var>index1</var> [ … <var>indexn</var> ] [ /Enable|Disable ] [ /Check|Uncheck ]

Activate or deactivate and/or set or clear the check state of menu items <var>index1</var> to <var>indexn</var>. The items may be located in different menus.

=== <code>DELPOPUP</code> ===

SET <var>dialog</var> DELPOPUP /X
SET <var>dialog</var> DELETEPOPUP /X

Delete all context menus. Note that you can replace an existing popup by just calling <code>ADDPOPUP</code> again with the same index.

=== <code>CONTEXTMENU</code> ===

SET <var>dialog</var> CONTEXTMENU <var>menuId</var>

Show the contextmenu with index or id <var>menuId</var>. This command is usually called in response to a <code>CMSTAT</code> message.

== Editing cells in a <code>LISTVIEW</code> ==

SET <var>dialogItem</var> <var>listviewIndex</var> STARTEDIT <var>col</var> <var>row</var>

Sets the dialog focus to the specified cell and enters edit mode. If the user presses ESC, Return or Enter, the control leaves edit mode. <var>col</var> and <var>row</var> are zero-based indices addressing the field and entry. See the example script <code>editabletable.sts</code> for a complete example.

== Dialog Control Configuration ==

=== Setting the attributes of a control ===

SET <var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>fg</var> <var>bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ]
<var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>fg</var> <var>bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ]

Set mode and attributes of a control.

;/N=<var>count</var>: apply settings to ''all'' controls in a range <var>index</var> to <code><var>index</var>+count-1</code>
;/Read, /Write: request data being transferred from the dialog to the connected shell variable (Read), or from the connected shell variable to the dialog control (Write) - for a description, see the [[Programmer_Guide/Shell_Items/Dialog/SET_DIALOG#Data_Exchange|Data Exchange]] section on this page. This data exchange will take place for the addressed control(s) only (as opposed to <code>SET dialog mode</code> which transfers data to/from ''all'' controls of the dialog).

The color and font specifications are described in the appendix. Note that color settings are applied to controls of type <code>static</code>, and to the caption of controls with a separate caption, window only.

{|class="keinrahmen"
| <var>index</var>
| The index of the (first) control.
|-
| <var>count</var>
| The number of controls (>= 1, default = 1).
|-
| <var>mode</var>
| The control mode (<code>*</code>, <code>HIDDEN</code>, <code>VISIBLE</code>, <code>ENABLED</code> or <code>TITLE</code>).

The <var>mode</var> <code>TITLE</code> is defined for compatibility to earlier versions only. It has the same meaning as <code>*</code> (do not change mode, just set attributes).
|-
| <var>title</var>
| The control caption.
|-
| <var>font</var>
| The control font. See Fonts and Font Arguments for details.
|-
| <var>fg</var>, <var>bg</var>
|The foreground (<var>fg</var>) and background (<var>bg</var>) color. You may use either a color keyword or an RGB value for each of <var>fg</var> and <var>bg</var>.
|}

SET <var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>row</var> <var>col</var> <var>width</var> <var>height</var> ] [ /Read|Write ] /Layout | /layout | /Setposition

This command can be used to update the caption, font, position and size of a control
;/Layout: update control and recompute dialog window layout
;/layout: update control and recompute dialog window layout, ignore hidden controls
;Setposition: update control but do not recompute dialog window layout

{|class="keinrahmen"
| <var>row, col</var>
| new control position (use -1 or * if a value should not be changed)
|-
| <var>width, height</var>
| new control size (use -1 or * if a value should not be changed)
|}

=== <code>FOCUS</code> ===

SET <var>dialog</var> FOCUS
SET <var>dialog</var> <var>index</var> FOCUS

Give a particular control the input focus. All keyboard input is then directed to the control. This command can be used in setup or input dialogs to set the focus to the default input field after creating and displaying the dialog. If no index is specified or if its value is less than zero, the focus is set to the dialog window itself.

=== <code>INPUT</code> ===

SET <var>dialog</var> <var>index</var> INPUT <var>output</var>

Connect dialog control with a data output.

{|class="keinrahmen"
| <var>output</var>
| an SPU output or a value object
|}

=== <code>BITMAP</code> ===

SET dialog index BITMAP <var>buttonId</var>|<var>bitmapFile</var> [ <var>tooltipText</var> ][ /B ]

Assign a bitmap to a button or a static control. The assigned bitmap is displayed in its original size and colors in the center of the control. If no bitmap is specified, any existing assignment is removed. Bitmaps can be read from bitmap files (*.BMP) or from the {{STX}} resource file. To identify a resource the name (or index) of a bitmap resource (no option) or a toolbar button (option <code>/B</code>) can be used.

{| class="keinrahmen"
| valign="top" | <var>index</var>
| The 'button' or 'static' dialog control index.
|-
| valign="top" | <var>buttonId</var>
| The bitmap id or toolbar button id. See the "Bitmaps for Dialog Controls, Icons, Toolbar Buttons" topic in <GD> for a list of available b
|-
| valign="top" | <var>bitmapFile</var>
| The name of a bitmap file.
|-
| valign="top" | <var>tooltipText</var>
| If specified, this string will be displayed as a tooltip when the mouse hovers over the button. This parameter overrides any string associated with the bitmap (/b) in the resource file.
|-
| valign="top" | <code>/B</code>
| If the option <code>/B</code> is specified, the <var>buttonId</var> references a toolbar button (rather than a bitmap resource). [[Programmer_Guide/General_Descriptions/Bitmaps_for_Dialog_Controls,_Icons,_Toolbar_Buttons|Bitmaps for Dialog Controls, Icons, Toolbar Buttons]] shows all images available in {{STX}}.
|}

The <code>SET dialog index BITMAP</code> command only works once a dialog has been created, i.e. after <code>domodaldialog begin</code>.

== Dialog Control Creation ==

You can create a control in a dialog using the <code>SET dialog index controlType</code> commands defined below. All dialog controls must be created before the dialog is displayed for the first time. You can show and hide dialog controls once the dialog has been created with the <code>SET dialog mode</code> command. See [[Programmer_Guide/Shell_Items/Dialog/Dialog_Controls|Dialog Controls]] for a list of available controls and their individual creation syntax.

The number of controls per dialog is limited to 255 due to the MFC implementation.

Programmer Guide/Shell Items/Dialog/SET DIALOG

2018-11-13T14:58:17Z

Toni: /* Setting the attributes of a control */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{Dialog Item}}
Use the [[Programmer_Guide/Shell_Items/Dialog/NEW_DIALOG|<code>NEW DIALOG</code>]] command for creating a [[Programmer_Guide/Shell_Items/Dialog|<code>DIALOG</code> shell item]]. Then apply the <code>SET <var>dialog</var></code> commands described here.

== Data Exchange==

SET <var>dialog</var> [ <var>ctrlId</var> ] /Read|Write
<var>dialog</var> [ <var>ctrlId</var> ] /Read|Write

Exchange data between the dialog controls and their respective variables.

{|class="keinrahmen"
| <var>ctrlId</var>
| colspan="2" | The optional id of an existing control. If specified, the exchange only takes place for this control. Otherwise, all data for all controls is exchanged.
|-
| rowspan="3" | <code>/Read</code> or <code>/Write</code>
| colspan="2" | The direction of data exchange (as seen from the shell).
|-
| <code>/Read</code> || reads the data out of the control into the shell variable.
|-
| <code>/Write</code> || sets the values of the controls.
|}

If you want to read or write only a subset of connected dialog controls, you may do so by using the command
SET <var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>fg</var> <var>bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ]
See [[Programmer_Guide/Shell_Items/Dialog/SET_DIALOG#Setting_the_attributes_of_a_control|Setting the attributes of a control]] on this page.

== Dialog Window Control ==

Set the display and/or dialog window mode, style position and/or size, and configure the dialog. If the option <code>/Read</code> (dialog → shell) or <code>/Write</code> (shell → dialog) is specified, a data exchange between the dialog controls and the variables and items bound to the controls is performed. The <var>mode</var> command has different functions for displays with only a dialog and for displays containing a dialog and graphs.

=== Dialog only ===

SET <var>dialog</var> <var>mode</var> [<var>style</var> <var>xpos</var> <var>ypos</var> <var>width</var> <var>height</var>] [/Centered /Foreground /Dialog /View /Layout|layout]

The dialog is enabled (window is created) and the command is forwarded to the display.

=== Dialog and graphs ===

SET <var>dialog</var> <var>mode</var> [/Read|Write]

The dialog window mode is set. Other arguments/options are ignored if specified.

=== Options ===

{|class="keinrahmen"
| <var>mode</var>
| The dialog window mode, one out of <code>NOWINDOW</code>, <code>HIDDEN</code>. <code>VISIBLE</code>, <code>ENABLED</code> and <code>*</code>). If <code>NOWINDOW</code> is used, the dialog window is destroyed and the dialog must be reconfigured (i.e. controls must be created etc).
|-
| <var>style</var>
| The window style (<code>MINIMIZE</code>, <code>MAXIMIZE</code> or <code>RESTORE</code>).
|-
| <var>xpos</var>
|The x-axis position in pixels of the upper left corner of the dialog relative to the desktop origin.
|-
| <var>ypos</var>
| The y-axis position in pixels of the upper left corner of the dialog relative to the desktop origin.
|-
| <var>width</var>
| The width of the dialog in pixels.
|-
| <var>height</var>
| The height of the dialog in pixels.
|-
| <code>/Centered</code>
| Center the display to the screen in which the mouse is currently. <var>xpos</var>, <var>ypos</var>, <var>width</var> and <var>height</var> are ignored.
|-
| <code>/Foreground</code>
| Send the window to the front (make the window the topmost window).
|-
| <code>/Dialog=<var>pos</var></code>
| Set dialog position inside the display (relative to graphs); changing the position is only possible if the dialog is non-floating. The following values for <var>pos</var> are allowed: <code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code>
|-
| <code>/View=<var>view</var></code>
| Set window view mode to <var>view</var> ('<code>WINDOW</code>' is a normal window, or '<code>FULLSCREEN</code>' = display takes up whole screen (for displays of type 'frame' only) or '<code>ALWAYSONTOP</code>' = the display remains on top, even when other windows are activated).
|-
| <code>/Layout</code> or <code>/layout</code>
| Recalculate the dialog window size, including (<code>/Layout</code> - note the upper-case "L") or ignoring (<code>/layout</code> - note the lower-case "l") hidden controls (this is one of our very few case-sensitive option letters).
|}

== Dialog Window Configuration==

=== <code>TITLE</code> ===

SET <var>dialog</var> TITLE <var>title</var>

Set the caption of the display owning the <var>dialog</var> to <var>title</var>. The caption can be an empty string. Note that it is advisable to surround the string <var>title</var> in quotes, since otherwise, only the first word of the string is interpreted as the title (the rest being additional arguments, which are ignored).

Code example:
SET $#dlg TITLE 'Der Wiener Schnitzel mit de Lavignetten und de Sauerkraut'

=== <code>LAYOUT</code> ===

SET <var>dialog</var> LAYOUT <var>font</var> <var>left</var> <var>top</var> <var>right</var> <var>bottom</var>

Set the dialog margins and the default font. The default font will be used for all ''newly'' created controls (the existing ones will keep their respective font). The unit for specifying margins is characters, just like the control position and size. So, if you specify a margin of <var>n</var>, it will be roughly as wide as a string of <var>n</var> characters would be ("roughly", because with proportional fonts, the single characters are of different widths). Note that each control may be assigned an individual font, thereby overriding this default font (see <code>SET dialog index controltype</code> below).

{|class="keinrahmen"
| <var>font</var>
| The default font (see Fonts and Font Arguments for details).
|-
| <var>left</var>, <var>right</var>
| The margin on the left/right side (in characters).
|-
| <var>top</var>, <var>bottom</var>
| The margin on the top/bottom (in characters).
|}

== Dialog Context Menus ==

It is possible to attach a set of context menus to each dialog. The displaying of the context menu is controlled by the programmer (normally by processing the messages <code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages|CMSTAT]]</code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages| and ]]<code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages|CMITEM]]</code> in a message handler). Context menus are identified by an id string (specified in the <code>ADDPOPUP /X</code> command) or a zero-based index (in the same order as the <code>ADDPOPUP</code> commands). Note: If the option /X is not supplied in a command, the menu handling command is forwarded to the display and used for popup-menu handling. For a detailed description of menu item formats and menu item index computation see command <code>[[Programmer_Guide/Shell_Items/Display/SET_DISPLAY#ADDPOPUP|SET display ADDPOPUP]]</code>.

=== <code>ADDPOPUP</code> ===

SET <var>dialog</var> ADDPOPUP /X <var>id</var> <var>item1</var> <var>item2</var> … <var>itemn</var>
SET <var>dialog</var> ADDPOPUP /X <var>id</var> <var>tableitem</var> /Table

Add a context menu to the dialog.

{|class="keinrahmen"
| <var>id</var>
| The id of the context menu in the dialog (a dialog can have more than one context menu). This is not shown in the menu itself.
|-
| <var>itemn</var>
| The menu items.
|-
| <var>tableItem</var>
| A table
|}

=== <code>SETPOPUP</code> ===

SET <var>dialog</var> SETPOPUP /X <var>index1</var> [ … <var>indexn</var> ] [ /Enable|Disable ] [ /Check|Uncheck ]

Activate or deactivate and/or set or clear the check state of menu items <var>index1</var> to <var>indexn</var>. The items may be located in different menus.

=== <code>DELPOPUP</code> ===

SET <var>dialog</var> DELPOPUP /X
SET <var>dialog</var> DELETEPOPUP /X

Delete all context menus. Note that you can replace an existing popup by just calling <code>ADDPOPUP</code> again with the same index.

=== <code>CONTEXTMENU</code> ===

SET <var>dialog</var> CONTEXTMENU <var>menuId</var>

Show the contextmenu with index or id <var>menuId</var>. This command is usually called in response to a <code>CMSTAT</code> message.

== Editing cells in a <code>LISTVIEW</code> ==

SET <var>dialogItem</var> <var>listviewIndex</var> STARTEDIT <var>col</var> <var>row</var>

Sets the dialog focus to the specified cell and enters edit mode. If the user presses ESC, Return or Enter, the control leaves edit mode. <var>col</var> and <var>row</var> are zero-based indices addressing the field and entry. See the example script <code>editabletable.sts</code> for a complete example.

== Dialog Control Configuration ==

=== Setting the attributes of a control ===

SET <var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>fg</var> <var>bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ]
<var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>fg</var> <var>bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ]

Set mode and attributes of a control.

The option <code>/N=<var>count</var></code> may be used to apply settings to ''all'' controls in a range <var>index</var> to <code><var>index</var>+count-1</code>.

The options <code>/Read</code> and <code>/Write</code> request data being transferred from the dialog to the connected shell variable (<code>/Read</code>), or from the connected shell variable to the dialog control (<code>/Write</code>) - for a description, see the [[Programmer_Guide/Shell_Items/Dialog/SET_DIALOG#Data_Exchange|Data Exchange]] section on this page. This data exchange will take place for the addressed control(s) only (as opposed to <code>SET dialog mode</code> which transfers data to/from ''all'' controls of the dialog).

The color and font specifications are described in the appendix. Note that color settings are applied to controls of type <code>static</code>, and to the caption of controls with a separate caption, window only.

{|class="keinrahmen"
| <var>index</var>
| The index of the (first) control.
|-
| <var>count</var>
| The number of controls (>= 1, default = 1).
|-
| <var>mode</var>
| The control mode (<code>*</code>, <code>HIDDEN</code>, <code>VISIBLE</code>, <code>ENABLED</code> or <code>TITLE</code>).

The <var>mode</var> <code>TITLE</code> is defined for compatibility to earlier versions only. It has the same meaning as <code>*</code> (do not change mode, just set attributes).
|-
| <var>title</var>
| The control caption.
|-
| <var>font</var>
| The control font. See Fonts and Font Arguments for details.
|-
| <var>fg</var>, <var>bg</var>
|The foreground (<var>fg</var>) and background (<var>bg</var>) color. You may use either a color keyword or an RGB value for each of <var>fg</var> and <var>bg</var>.
|}

SET <var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>row</var> <var>col</var> <var>width</var> <var>height</var> ] [ /Read|Write ] /Layout | /layout | /Setposition

This command can be used to update the caption, font, position and size of a control
;/Layout: update control and recompute dialog window layout
;/layout: update control and recompute dialog window layout, ignore hidden controls
;Setposition: update control but do not recompute dialog window layout

{|class="keinrahmen"
| <var>row, col</var>
| new control position (use -1 or * if a value should not be changed)
|-
| <var>width, height</var>
| new control size (use -1 or * if a value should not be changed)
|}

=== <code>FOCUS</code> ===

SET <var>dialog</var> FOCUS
SET <var>dialog</var> <var>index</var> FOCUS

Give a particular control the input focus. All keyboard input is then directed to the control. This command can be used in setup or input dialogs to set the focus to the default input field after creating and displaying the dialog. If no index is specified or if its value is less than zero, the focus is set to the dialog window itself.

=== <code>INPUT</code> ===

SET <var>dialog</var> <var>index</var> INPUT <var>output</var>

Connect dialog control with a data output.

{|class="keinrahmen"
| <var>output</var>
| an SPU output or a value object
|}

=== <code>BITMAP</code> ===

SET dialog index BITMAP <var>buttonId</var>|<var>bitmapFile</var> [ <var>tooltipText</var> ][ /B ]

Assign a bitmap to a button or a static control. The assigned bitmap is displayed in its original size and colors in the center of the control. If no bitmap is specified, any existing assignment is removed. Bitmaps can be read from bitmap files (*.BMP) or from the {{STX}} resource file. To identify a resource the name (or index) of a bitmap resource (no option) or a toolbar button (option <code>/B</code>) can be used.

{| class="keinrahmen"
| valign="top" | <var>index</var>
| The 'button' or 'static' dialog control index.
|-
| valign="top" | <var>buttonId</var>
| The bitmap id or toolbar button id. See the "Bitmaps for Dialog Controls, Icons, Toolbar Buttons" topic in <GD> for a list of available b
|-
| valign="top" | <var>bitmapFile</var>
| The name of a bitmap file.
|-
| valign="top" | <var>tooltipText</var>
| If specified, this string will be displayed as a tooltip when the mouse hovers over the button. This parameter overrides any string associated with the bitmap (/b) in the resource file.
|-
| valign="top" | <code>/B</code>
| If the option <code>/B</code> is specified, the <var>buttonId</var> references a toolbar button (rather than a bitmap resource). [[Programmer_Guide/General_Descriptions/Bitmaps_for_Dialog_Controls,_Icons,_Toolbar_Buttons|Bitmaps for Dialog Controls, Icons, Toolbar Buttons]] shows all images available in {{STX}}.
|}

The <code>SET dialog index BITMAP</code> command only works once a dialog has been created, i.e. after <code>domodaldialog begin</code>.

== Dialog Control Creation ==

You can create a control in a dialog using the <code>SET dialog index controlType</code> commands defined below. All dialog controls must be created before the dialog is displayed for the first time. You can show and hide dialog controls once the dialog has been created with the <code>SET dialog mode</code> command. See [[Programmer_Guide/Shell_Items/Dialog/Dialog_Controls|Dialog Controls]] for a list of available controls and their individual creation syntax.

The number of controls per dialog is limited to 255 due to the MFC implementation.

Programmer Guide/Shell Items/Dialog/SET DIALOG

2018-11-13T14:53:27Z

Toni: /* Setting the attributes of a control */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{Dialog Item}}
Use the [[Programmer_Guide/Shell_Items/Dialog/NEW_DIALOG|<code>NEW DIALOG</code>]] command for creating a [[Programmer_Guide/Shell_Items/Dialog|<code>DIALOG</code> shell item]]. Then apply the <code>SET <var>dialog</var></code> commands described here.

== Data Exchange==

SET <var>dialog</var> [ <var>ctrlId</var> ] /Read|Write
<var>dialog</var> [ <var>ctrlId</var> ] /Read|Write

Exchange data between the dialog controls and their respective variables.

{|class="keinrahmen"
| <var>ctrlId</var>
| colspan="2" | The optional id of an existing control. If specified, the exchange only takes place for this control. Otherwise, all data for all controls is exchanged.
|-
| rowspan="3" | <code>/Read</code> or <code>/Write</code>
| colspan="2" | The direction of data exchange (as seen from the shell).
|-
| <code>/Read</code> || reads the data out of the control into the shell variable.
|-
| <code>/Write</code> || sets the values of the controls.
|}

If you want to read or write only a subset of connected dialog controls, you may do so by using the command
SET <var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>fg</var> <var>bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ]
See [[Programmer_Guide/Shell_Items/Dialog/SET_DIALOG#Setting_the_attributes_of_a_control|Setting the attributes of a control]] on this page.

== Dialog Window Control ==

Set the display and/or dialog window mode, style position and/or size, and configure the dialog. If the option <code>/Read</code> (dialog → shell) or <code>/Write</code> (shell → dialog) is specified, a data exchange between the dialog controls and the variables and items bound to the controls is performed. The <var>mode</var> command has different functions for displays with only a dialog and for displays containing a dialog and graphs.

=== Dialog only ===

SET <var>dialog</var> <var>mode</var> [<var>style</var> <var>xpos</var> <var>ypos</var> <var>width</var> <var>height</var>] [/Centered /Foreground /Dialog /View /Layout|layout]

The dialog is enabled (window is created) and the command is forwarded to the display.

=== Dialog and graphs ===

SET <var>dialog</var> <var>mode</var> [/Read|Write]

The dialog window mode is set. Other arguments/options are ignored if specified.

=== Options ===

{|class="keinrahmen"
| <var>mode</var>
| The dialog window mode, one out of <code>NOWINDOW</code>, <code>HIDDEN</code>. <code>VISIBLE</code>, <code>ENABLED</code> and <code>*</code>). If <code>NOWINDOW</code> is used, the dialog window is destroyed and the dialog must be reconfigured (i.e. controls must be created etc).
|-
| <var>style</var>
| The window style (<code>MINIMIZE</code>, <code>MAXIMIZE</code> or <code>RESTORE</code>).
|-
| <var>xpos</var>
|The x-axis position in pixels of the upper left corner of the dialog relative to the desktop origin.
|-
| <var>ypos</var>
| The y-axis position in pixels of the upper left corner of the dialog relative to the desktop origin.
|-
| <var>width</var>
| The width of the dialog in pixels.
|-
| <var>height</var>
| The height of the dialog in pixels.
|-
| <code>/Centered</code>
| Center the display to the screen in which the mouse is currently. <var>xpos</var>, <var>ypos</var>, <var>width</var> and <var>height</var> are ignored.
|-
| <code>/Foreground</code>
| Send the window to the front (make the window the topmost window).
|-
| <code>/Dialog=<var>pos</var></code>
| Set dialog position inside the display (relative to graphs); changing the position is only possible if the dialog is non-floating. The following values for <var>pos</var> are allowed: <code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code>
|-
| <code>/View=<var>view</var></code>
| Set window view mode to <var>view</var> ('<code>WINDOW</code>' is a normal window, or '<code>FULLSCREEN</code>' = display takes up whole screen (for displays of type 'frame' only) or '<code>ALWAYSONTOP</code>' = the display remains on top, even when other windows are activated).
|-
| <code>/Layout</code> or <code>/layout</code>
| Recalculate the dialog window size, including (<code>/Layout</code> - note the upper-case "L") or ignoring (<code>/layout</code> - note the lower-case "l") hidden controls (this is one of our very few case-sensitive option letters).
|}

== Dialog Window Configuration==

=== <code>TITLE</code> ===

SET <var>dialog</var> TITLE <var>title</var>

Set the caption of the display owning the <var>dialog</var> to <var>title</var>. The caption can be an empty string. Note that it is advisable to surround the string <var>title</var> in quotes, since otherwise, only the first word of the string is interpreted as the title (the rest being additional arguments, which are ignored).

Code example:
SET $#dlg TITLE 'Der Wiener Schnitzel mit de Lavignetten und de Sauerkraut'

=== <code>LAYOUT</code> ===

SET <var>dialog</var> LAYOUT <var>font</var> <var>left</var> <var>top</var> <var>right</var> <var>bottom</var>

Set the dialog margins and the default font. The default font will be used for all ''newly'' created controls (the existing ones will keep their respective font). The unit for specifying margins is characters, just like the control position and size. So, if you specify a margin of <var>n</var>, it will be roughly as wide as a string of <var>n</var> characters would be ("roughly", because with proportional fonts, the single characters are of different widths). Note that each control may be assigned an individual font, thereby overriding this default font (see <code>SET dialog index controltype</code> below).

{|class="keinrahmen"
| <var>font</var>
| The default font (see Fonts and Font Arguments for details).
|-
| <var>left</var>, <var>right</var>
| The margin on the left/right side (in characters).
|-
| <var>top</var>, <var>bottom</var>
| The margin on the top/bottom (in characters).
|}

== Dialog Context Menus ==

It is possible to attach a set of context menus to each dialog. The displaying of the context menu is controlled by the programmer (normally by processing the messages <code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages|CMSTAT]]</code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages| and ]]<code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages|CMITEM]]</code> in a message handler). Context menus are identified by an id string (specified in the <code>ADDPOPUP /X</code> command) or a zero-based index (in the same order as the <code>ADDPOPUP</code> commands). Note: If the option /X is not supplied in a command, the menu handling command is forwarded to the display and used for popup-menu handling. For a detailed description of menu item formats and menu item index computation see command <code>[[Programmer_Guide/Shell_Items/Display/SET_DISPLAY#ADDPOPUP|SET display ADDPOPUP]]</code>.

=== <code>ADDPOPUP</code> ===

SET <var>dialog</var> ADDPOPUP /X <var>id</var> <var>item1</var> <var>item2</var> … <var>itemn</var>
SET <var>dialog</var> ADDPOPUP /X <var>id</var> <var>tableitem</var> /Table

Add a context menu to the dialog.

{|class="keinrahmen"
| <var>id</var>
| The id of the context menu in the dialog (a dialog can have more than one context menu). This is not shown in the menu itself.
|-
| <var>itemn</var>
| The menu items.
|-
| <var>tableItem</var>
| A table
|}

=== <code>SETPOPUP</code> ===

SET <var>dialog</var> SETPOPUP /X <var>index1</var> [ … <var>indexn</var> ] [ /Enable|Disable ] [ /Check|Uncheck ]

Activate or deactivate and/or set or clear the check state of menu items <var>index1</var> to <var>indexn</var>. The items may be located in different menus.

=== <code>DELPOPUP</code> ===

SET <var>dialog</var> DELPOPUP /X
SET <var>dialog</var> DELETEPOPUP /X

Delete all context menus. Note that you can replace an existing popup by just calling <code>ADDPOPUP</code> again with the same index.

=== <code>CONTEXTMENU</code> ===

SET <var>dialog</var> CONTEXTMENU <var>menuId</var>

Show the contextmenu with index or id <var>menuId</var>. This command is usually called in response to a <code>CMSTAT</code> message.

== Editing cells in a <code>LISTVIEW</code> ==

SET <var>dialogItem</var> <var>listviewIndex</var> STARTEDIT <var>col</var> <var>row</var>

Sets the dialog focus to the specified cell and enters edit mode. If the user presses ESC, Return or Enter, the control leaves edit mode. <var>col</var> and <var>row</var> are zero-based indices addressing the field and entry. See the example script <code>editabletable.sts</code> for a complete example.

== Dialog Control Configuration ==

=== Setting the attributes of a control ===

SET <var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>fg</var> <var>bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ]
<var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>fg</var> <var>bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ]

Set mode and attributes of a control.

The option <code>/N=<var>count</var></code> may be used to apply settings to ''all'' controls in a range <var>index</var> to <code><var>index</var>+count-1</code>.

The options <code>/Read</code> and <code>/Write</code> request data being transferred from the dialog to the connected shell variable (<code>/Read</code>), or from the connected shell variable to the dialog control (<code>/Write</code>) - for a description, see the [[Programmer_Guide/Shell_Items/Dialog/SET_DIALOG#Data_Exchange|Data Exchange]] section on this page. This data exchange will take place for the addressed control(s) only (as opposed to <code>SET dialog mode</code> which transfers data to/from ''all'' controls of the dialog).

The color and font specifications are described in the appendix. Note that color settings are applied to controls of type <code>static</code>, and to the caption of controls with a separate caption, window only.

{|class="keinrahmen"
| <var>index</var>
| The index of the (first) control.
|-
| <var>count</var>
| The number of controls (>= 1, default = 1).
|-
| <var>mode</var>
| The control mode (<code>*</code>, <code>HIDDEN</code>, <code>VISIBLE</code>, <code>ENABLED</code> or <code>TITLE</code>).

The <var>mode</var> <code>TITLE</code> is defined for compatibility to earlier versions only. It has the same meaning as <code>*</code> (do not change mode, just set attributes).
|-
| <var>title</var>
| The control caption.
|-
| <var>font</var>
| The control font. See Fonts and Font Arguments for details.
|-
| <var>fg</var>, <var>bg</var>
|The foreground (<var>fg</var>) and background (<var>bg</var>) color. You may use either a color keyword or an RGB value for each of <var>fg</var> and <var>bg</var>.
|}

SET <var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>row</var> <var>col</var> <var>width</var> <var>height</var> ] [ /Read|Write ] /Layout | /layout | /Setposition

This command can be used to update the caption, font, position and size of a control
;/Layout: update control and recompute dialog window layout
;/layout: update control and recompute dialog window layout, ignore hidden controls
;Setposition: update control but do not recompute dialog window layout

=== <code>FOCUS</code> ===

SET <var>dialog</var> FOCUS
SET <var>dialog</var> <var>index</var> FOCUS

Give a particular control the input focus. All keyboard input is then directed to the control. This command can be used in setup or input dialogs to set the focus to the default input field after creating and displaying the dialog. If no index is specified or if its value is less than zero, the focus is set to the dialog window itself.

=== <code>INPUT</code> ===

SET <var>dialog</var> <var>index</var> INPUT <var>output</var>

Connect dialog control with a data output.

{|class="keinrahmen"
| <var>output</var>
| an SPU output or a value object
|}

=== <code>BITMAP</code> ===

SET dialog index BITMAP <var>buttonId</var>|<var>bitmapFile</var> [ <var>tooltipText</var> ][ /B ]

Assign a bitmap to a button or a static control. The assigned bitmap is displayed in its original size and colors in the center of the control. If no bitmap is specified, any existing assignment is removed. Bitmaps can be read from bitmap files (*.BMP) or from the {{STX}} resource file. To identify a resource the name (or index) of a bitmap resource (no option) or a toolbar button (option <code>/B</code>) can be used.

{| class="keinrahmen"
| valign="top" | <var>index</var>
| The 'button' or 'static' dialog control index.
|-
| valign="top" | <var>buttonId</var>
| The bitmap id or toolbar button id. See the "Bitmaps for Dialog Controls, Icons, Toolbar Buttons" topic in <GD> for a list of available b
|-
| valign="top" | <var>bitmapFile</var>
| The name of a bitmap file.
|-
| valign="top" | <var>tooltipText</var>
| If specified, this string will be displayed as a tooltip when the mouse hovers over the button. This parameter overrides any string associated with the bitmap (/b) in the resource file.
|-
| valign="top" | <code>/B</code>
| If the option <code>/B</code> is specified, the <var>buttonId</var> references a toolbar button (rather than a bitmap resource). [[Programmer_Guide/General_Descriptions/Bitmaps_for_Dialog_Controls,_Icons,_Toolbar_Buttons|Bitmaps for Dialog Controls, Icons, Toolbar Buttons]] shows all images available in {{STX}}.
|}

The <code>SET dialog index BITMAP</code> command only works once a dialog has been created, i.e. after <code>domodaldialog begin</code>.

== Dialog Control Creation ==

You can create a control in a dialog using the <code>SET dialog index controlType</code> commands defined below. All dialog controls must be created before the dialog is displayed for the first time. You can show and hide dialog controls once the dialog has been created with the <code>SET dialog mode</code> command. See [[Programmer_Guide/Shell_Items/Dialog/Dialog_Controls|Dialog Controls]] for a list of available controls and their individual creation syntax.

The number of controls per dialog is limited to 255 due to the MFC implementation.

Programmer Guide/Shell Items/Dialog/SET DIALOG

2018-11-13T08:13:11Z

Toni: /* Setting the attributes of a control */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{Dialog Item}}
Use the [[Programmer_Guide/Shell_Items/Dialog/NEW_DIALOG|<code>NEW DIALOG</code>]] command for creating a [[Programmer_Guide/Shell_Items/Dialog|<code>DIALOG</code> shell item]]. Then apply the <code>SET <var>dialog</var></code> commands described here.

== Data Exchange==

SET <var>dialog</var> [ <var>ctrlId</var> ] /Read|Write
<var>dialog</var> [ <var>ctrlId</var> ] /Read|Write

Exchange data between the dialog controls and their respective variables.

{|class="keinrahmen"
| <var>ctrlId</var>
| colspan="2" | The optional id of an existing control. If specified, the exchange only takes place for this control. Otherwise, all data for all controls is exchanged.
|-
| rowspan="3" | <code>/Read</code> or <code>/Write</code>
| colspan="2" | The direction of data exchange (as seen from the shell).
|-
| <code>/Read</code> || reads the data out of the control into the shell variable.
|-
| <code>/Write</code> || sets the values of the controls.
|}

If you want to read or write only a subset of connected dialog controls, you may do so by using the command
SET <var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>fg</var> <var>bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ]
See [[Programmer_Guide/Shell_Items/Dialog/SET_DIALOG#Setting_the_attributes_of_a_control|Setting the attributes of a control]] on this page.

== Dialog Window Control ==

Set the display and/or dialog window mode, style position and/or size, and configure the dialog. If the option <code>/Read</code> (dialog → shell) or <code>/Write</code> (shell → dialog) is specified, a data exchange between the dialog controls and the variables and items bound to the controls is performed. The <var>mode</var> command has different functions for displays with only a dialog and for displays containing a dialog and graphs.

=== Dialog only ===

SET <var>dialog</var> <var>mode</var> [<var>style</var> <var>xpos</var> <var>ypos</var> <var>width</var> <var>height</var>] [/Centered /Foreground /Dialog /View /Layout|layout]

The dialog is enabled (window is created) and the command is forwarded to the display.

=== Dialog and graphs ===

SET <var>dialog</var> <var>mode</var> [/Read|Write]

The dialog window mode is set. Other arguments/options are ignored if specified.

=== Options ===

{|class="keinrahmen"
| <var>mode</var>
| The dialog window mode, one out of <code>NOWINDOW</code>, <code>HIDDEN</code>. <code>VISIBLE</code>, <code>ENABLED</code> and <code>*</code>). If <code>NOWINDOW</code> is used, the dialog window is destroyed and the dialog must be reconfigured (i.e. controls must be created etc).
|-
| <var>style</var>
| The window style (<code>MINIMIZE</code>, <code>MAXIMIZE</code> or <code>RESTORE</code>).
|-
| <var>xpos</var>
|The x-axis position in pixels of the upper left corner of the dialog relative to the desktop origin.
|-
| <var>ypos</var>
| The y-axis position in pixels of the upper left corner of the dialog relative to the desktop origin.
|-
| <var>width</var>
| The width of the dialog in pixels.
|-
| <var>height</var>
| The height of the dialog in pixels.
|-
| <code>/Centered</code>
| Center the display to the screen in which the mouse is currently. <var>xpos</var>, <var>ypos</var>, <var>width</var> and <var>height</var> are ignored.
|-
| <code>/Foreground</code>
| Send the window to the front (make the window the topmost window).
|-
| <code>/Dialog=<var>pos</var></code>
| Set dialog position inside the display (relative to graphs); changing the position is only possible if the dialog is non-floating. The following values for <var>pos</var> are allowed: <code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code>
|-
| <code>/View=<var>view</var></code>
| Set window view mode to <var>view</var> ('<code>WINDOW</code>' is a normal window, or '<code>FULLSCREEN</code>' = display takes up whole screen (for displays of type 'frame' only) or '<code>ALWAYSONTOP</code>' = the display remains on top, even when other windows are activated).
|-
| <code>/Layout</code> or <code>/layout</code>
| Recalculate the dialog window size, including (<code>/Layout</code> - note the upper-case "L") or ignoring (<code>/layout</code> - note the lower-case "l") hidden controls (this is one of our very few case-sensitive option letters).
|}

== Dialog Window Configuration==

=== <code>TITLE</code> ===

SET <var>dialog</var> TITLE <var>title</var>

Set the caption of the display owning the <var>dialog</var> to <var>title</var>. The caption can be an empty string. Note that it is advisable to surround the string <var>title</var> in quotes, since otherwise, only the first word of the string is interpreted as the title (the rest being additional arguments, which are ignored).

Code example:
SET $#dlg TITLE 'Der Wiener Schnitzel mit de Lavignetten und de Sauerkraut'

=== <code>LAYOUT</code> ===

SET <var>dialog</var> LAYOUT <var>font</var> <var>left</var> <var>top</var> <var>right</var> <var>bottom</var>

Set the dialog margins and the default font. The default font will be used for all ''newly'' created controls (the existing ones will keep their respective font). The unit for specifying margins is characters, just like the control position and size. So, if you specify a margin of <var>n</var>, it will be roughly as wide as a string of <var>n</var> characters would be ("roughly", because with proportional fonts, the single characters are of different widths). Note that each control may be assigned an individual font, thereby overriding this default font (see <code>SET dialog index controltype</code> below).

{|class="keinrahmen"
| <var>font</var>
| The default font (see Fonts and Font Arguments for details).
|-
| <var>left</var>, <var>right</var>
| The margin on the left/right side (in characters).
|-
| <var>top</var>, <var>bottom</var>
| The margin on the top/bottom (in characters).
|}

== Dialog Context Menus ==

It is possible to attach a set of context menus to each dialog. The displaying of the context menu is controlled by the programmer (normally by processing the messages <code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages|CMSTAT]]</code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages| and ]]<code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages|CMITEM]]</code> in a message handler). Context menus are identified by an id string (specified in the <code>ADDPOPUP /X</code> command) or a zero-based index (in the same order as the <code>ADDPOPUP</code> commands). Note: If the option /X is not supplied in a command, the menu handling command is forwarded to the display and used for popup-menu handling. For a detailed description of menu item formats and menu item index computation see command <code>[[Programmer_Guide/Shell_Items/Display/SET_DISPLAY#ADDPOPUP|SET display ADDPOPUP]]</code>.

=== <code>ADDPOPUP</code> ===

SET <var>dialog</var> ADDPOPUP /X <var>id</var> <var>item1</var> <var>item2</var> … <var>itemn</var>
SET <var>dialog</var> ADDPOPUP /X <var>id</var> <var>tableitem</var> /Table

Add a context menu to the dialog.

{|class="keinrahmen"
| <var>id</var>
| The id of the context menu in the dialog (a dialog can have more than one context menu). This is not shown in the menu itself.
|-
| <var>itemn</var>
| The menu items.
|-
| <var>tableItem</var>
| A table
|}

=== <code>SETPOPUP</code> ===

SET <var>dialog</var> SETPOPUP /X <var>index1</var> [ … <var>indexn</var> ] [ /Enable|Disable ] [ /Check|Uncheck ]

Activate or deactivate and/or set or clear the check state of menu items <var>index1</var> to <var>indexn</var>. The items may be located in different menus.

=== <code>DELPOPUP</code> ===

SET <var>dialog</var> DELPOPUP /X
SET <var>dialog</var> DELETEPOPUP /X

Delete all context menus. Note that you can replace an existing popup by just calling <code>ADDPOPUP</code> again with the same index.

=== <code>CONTEXTMENU</code> ===

SET <var>dialog</var> CONTEXTMENU <var>menuId</var>

Show the contextmenu with index or id <var>menuId</var>. This command is usually called in response to a <code>CMSTAT</code> message.

== Editing cells in a <code>LISTVIEW</code> ==

SET <var>dialogItem</var> <var>listviewIndex</var> STARTEDIT <var>col</var> <var>row</var>

Sets the dialog focus to the specified cell and enters edit mode. If the user presses ESC, Return or Enter, the control leaves edit mode. <var>col</var> and <var>row</var> are zero-based indices addressing the field and entry. See the example script <code>editabletable.sts</code> for a complete example.

== Dialog Control Configuration ==

=== Setting the attributes of a control ===

SET <var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>fg</var> <var>bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ] [/Layout|layout]
<var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>fg</var> <var>bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ] [/Layout|layout]

Set mode and attributes of a control.

The option <code>/N=<var>count</var></code> may be used to apply settings to ''all'' controls in a range <var>index</var> to <code><var>index</var>+count-1</code>.

The options <code>/Read</code> and <code>/Write</code> request data being transferred from the dialog to the connected shell variable (<code>/Read</code>), or from the connected shell variable to the dialog control (<code>/Write</code>) - for a description, see the [[Programmer_Guide/Shell_Items/Dialog/SET_DIALOG#Data_Exchange|Data Exchange]] section on this page. This data exchange will take place for the addressed control(s) only (as opposed to <code>SET dialog mode</code> which transfers data to/from ''all'' controls of the dialog).

The options <code>/Layout</code> or <code>/layout</code> can be used to recompute the position/size of all dialog controls and of the dialog window itself. With the option <code>/layout</code> hidden controls are ignored.

The color and font specifications are described in the appendix. Note that color settings are applied to controls of type <code>static</code>, and to the caption of controls with a separate caption, window only.

{|class="keinrahmen"
| <var>index</var>
| The index of the (first) control.
|-
| <var>count</var>
| The number of controls (>= 1, default = 1).
|-
| <var>mode</var>
| The control mode (<code>*</code>, <code>HIDDEN</code>, <code>VISIBLE</code>, <code>ENABLED</code> or <code>TITLE</code>).

The <var>mode</var> <code>TITLE</code> is defined for compatibility to earlier versions only. It has the same meaning as <code>*</code> (do not change mode, just set attributes).
|-
| <var>title</var>
| The control caption.
|-
| <var>font</var>
| The control font. See Fonts and Font Arguments for details.
|-
| <var>fg</var>, <var>bg</var>
|The foreground (<var>fg</var>) and background (<var>bg</var>) color. You may use either a color keyword or an RGB value for each of <var>fg</var> and <var>bg</var>.
|}

=== <code>FOCUS</code> ===

SET <var>dialog</var> FOCUS
SET <var>dialog</var> <var>index</var> FOCUS

Give a particular control the input focus. All keyboard input is then directed to the control. This command can be used in setup or input dialogs to set the focus to the default input field after creating and displaying the dialog. If no index is specified or if its value is less than zero, the focus is set to the dialog window itself.

=== <code>INPUT</code> ===

SET <var>dialog</var> <var>index</var> INPUT <var>output</var>

Connect dialog control with a data output.

{|class="keinrahmen"
| <var>output</var>
| an SPU output or a value object
|}

=== <code>BITMAP</code> ===

SET dialog index BITMAP <var>buttonId</var>|<var>bitmapFile</var> [ <var>tooltipText</var> ][ /B ]

Assign a bitmap to a button or a static control. The assigned bitmap is displayed in its original size and colors in the center of the control. If no bitmap is specified, any existing assignment is removed. Bitmaps can be read from bitmap files (*.BMP) or from the {{STX}} resource file. To identify a resource the name (or index) of a bitmap resource (no option) or a toolbar button (option <code>/B</code>) can be used.

{| class="keinrahmen"
| valign="top" | <var>index</var>
| The 'button' or 'static' dialog control index.
|-
| valign="top" | <var>buttonId</var>
| The bitmap id or toolbar button id. See the "Bitmaps for Dialog Controls, Icons, Toolbar Buttons" topic in <GD> for a list of available b
|-
| valign="top" | <var>bitmapFile</var>
| The name of a bitmap file.
|-
| valign="top" | <var>tooltipText</var>
| If specified, this string will be displayed as a tooltip when the mouse hovers over the button. This parameter overrides any string associated with the bitmap (/b) in the resource file.
|-
| valign="top" | <code>/B</code>
| If the option <code>/B</code> is specified, the <var>buttonId</var> references a toolbar button (rather than a bitmap resource). [[Programmer_Guide/General_Descriptions/Bitmaps_for_Dialog_Controls,_Icons,_Toolbar_Buttons|Bitmaps for Dialog Controls, Icons, Toolbar Buttons]] shows all images available in {{STX}}.
|}

The <code>SET dialog index BITMAP</code> command only works once a dialog has been created, i.e. after <code>domodaldialog begin</code>.

== Dialog Control Creation ==

You can create a control in a dialog using the <code>SET dialog index controlType</code> commands defined below. All dialog controls must be created before the dialog is displayed for the first time. You can show and hide dialog controls once the dialog has been created with the <code>SET dialog mode</code> command. See [[Programmer_Guide/Shell_Items/Dialog/Dialog_Controls|Dialog Controls]] for a list of available controls and their individual creation syntax.

The number of controls per dialog is limited to 255 due to the MFC implementation.

Programmer Guide/Shell Items/Table/SET TABLE

2018-11-13T07:28:21Z

Toni: /* Copying to and from the clipboard */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{Table_Item_Template}}
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. Note also that you cannot set 'all' entries, if only tagged entries are currently visible.
|}

// initialize the first field of the first 10 entries with the value 0.
$#extTable 0 0 0 /N=10

== Retrieving a table entry ==

You can retrieve a table entry using the following syntax: <code>$#table[$#index]</code>

== 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>[[Programmer_Guide/Shell_Items/Table/NEW_TABLE|NEW TABLE]]</code> command. The table must be in configuration mode (see <code>[[#Setting_the_table_mode|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/Introducing_Table_Items#The_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 from 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 show format to format each entry string. This is the default.
;<code>/Write</code>: Use the write format to format each entry string.

SET <var>table</var> CLIPBOARD /Args arg1 arg2 ... [ /Show|Write ]

Copy the content of the arguments to the clipboard. Each argument <code>argI</code> can be a string (string is copied) or a table item (content of table is copied). The option <code>/Show|Write</code> specifies the output format used for the table items (as described above). The content of the table item <var>table</var> is only copied, if it is specified as argument.

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 [[Programmer_Guide/Shell_Items/Table/SET_TABLE#Configuring_a_table_field|<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 [[#Setting_the_table_mode|<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 ==

The use of '''lock/unlock''' is only important, if a table item is (or may be) used by more than one thread. In {{STX}} shells, spu items and display item are running in their own thread.

SET <var>table</var> LOCK [/Save]
Lock the table item. The execution of the calling shell is stopped, until the item can be locked. If locked, only the shell which locked it has access to the item until it is explicitly unlocked with the command <code>UNLOCK</code>. Always beware of deadlocks.

SET <var>table</var> LOCK <var>timeout</var> [Save]
Try to lock the table item, but wait only the specified time. This command returns '''0''' (success) if the lock request was successful within the timeout, and a non-zero error code if not. If the caller already ''holds'' the lock, the command will fail immediately. This makes sense because, since the caller is the owner, it cannot release it whilst its waiting. The argument <var>timeout</var> specifies the maximum lock-timeout in milliseconds and must be a number greater than zero.

:* If the table is locked with the option '''/Save''', the tag state of each entry, the current order and the mode is saved on <code>lock</code> and restored with the <code>unlock</code> command. In this case in the critical section entries can only be modified, but not created or deleted.

SET <var>table</var> UNLOCK
Unlock the table item. '''Note''': It's very important that for each successful <code>LOCK</code>, an <code>UNLOCK</code> is called!

See <code>lock_example.sts</code> in the script examples directory for an example.

== 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/Introducing_Table_Items#The_Show_Format|show format]], <code>1</code>…[[Programmer_Guide/Shell_Items/Table/Introducing_Table_Items#The_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/Shell Items/Table/SET TABLE

2018-11-13T07:26:41Z

Toni: /* Copying to and from the clipboard */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{Table_Item_Template}}
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. Note also that you cannot set 'all' entries, if only tagged entries are currently visible.
|}

// initialize the first field of the first 10 entries with the value 0.
$#extTable 0 0 0 /N=10

== Retrieving a table entry ==

You can retrieve a table entry using the following syntax: <code>$#table[$#index]</code>

== 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>[[Programmer_Guide/Shell_Items/Table/NEW_TABLE|NEW TABLE]]</code> command. The table must be in configuration mode (see <code>[[#Setting_the_table_mode|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/Introducing_Table_Items#The_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 from 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 show format to format each entry string. This is the default.
;<code>/Write</code>: Use the write format to format each entry string.

SET <var>table</var> CLIPBOARD /Args arg1 arg2 ... [ /Show|Write ]

Copy the content of the arguments to the clipboard. Each argument <code>argI</code> can be a string (string is copied) or a table item (content of table is copied). The option <code>/Show|Write</code> specifies the output format used for the table items (as described above).

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 [[Programmer_Guide/Shell_Items/Table/SET_TABLE#Configuring_a_table_field|<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 [[#Setting_the_table_mode|<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 ==

The use of '''lock/unlock''' is only important, if a table item is (or may be) used by more than one thread. In {{STX}} shells, spu items and display item are running in their own thread.

SET <var>table</var> LOCK [/Save]
Lock the table item. The execution of the calling shell is stopped, until the item can be locked. If locked, only the shell which locked it has access to the item until it is explicitly unlocked with the command <code>UNLOCK</code>. Always beware of deadlocks.

SET <var>table</var> LOCK <var>timeout</var> [Save]
Try to lock the table item, but wait only the specified time. This command returns '''0''' (success) if the lock request was successful within the timeout, and a non-zero error code if not. If the caller already ''holds'' the lock, the command will fail immediately. This makes sense because, since the caller is the owner, it cannot release it whilst its waiting. The argument <var>timeout</var> specifies the maximum lock-timeout in milliseconds and must be a number greater than zero.

:* If the table is locked with the option '''/Save''', the tag state of each entry, the current order and the mode is saved on <code>lock</code> and restored with the <code>unlock</code> command. In this case in the critical section entries can only be modified, but not created or deleted.

SET <var>table</var> UNLOCK
Unlock the table item. '''Note''': It's very important that for each successful <code>LOCK</code>, an <code>UNLOCK</code> is called!

See <code>lock_example.sts</code> in the script examples directory for an example.

== 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/Introducing_Table_Items#The_Show_Format|show format]], <code>1</code>…[[Programmer_Guide/Shell_Items/Table/Introducing_Table_Items#The_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/Shell Items/Table/SET TABLE

2018-11-13T07:25:33Z

Toni: /* Copying to and from the clipboard */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{Table_Item_Template}}
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. Note also that you cannot set 'all' entries, if only tagged entries are currently visible.
|}

// initialize the first field of the first 10 entries with the value 0.
$#extTable 0 0 0 /N=10

== Retrieving a table entry ==

You can retrieve a table entry using the following syntax: <code>$#table[$#index]</code>

== 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>[[Programmer_Guide/Shell_Items/Table/NEW_TABLE|NEW TABLE]]</code> command. The table must be in configuration mode (see <code>[[#Setting_the_table_mode|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/Introducing_Table_Items#The_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 from 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 /Args arg1 arg2 ... [ /Show|Write ]

Copy the content of the arguments to the clipboard. Each argument <code>argI</code> can be a string (string is copied) or a table item (content of table is copied). The option <code>/Show|Write</code> specifies the output format used for the table items (as described above).

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 [[Programmer_Guide/Shell_Items/Table/SET_TABLE#Configuring_a_table_field|<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 [[#Setting_the_table_mode|<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 ==

The use of '''lock/unlock''' is only important, if a table item is (or may be) used by more than one thread. In {{STX}} shells, spu items and display item are running in their own thread.

SET <var>table</var> LOCK [/Save]
Lock the table item. The execution of the calling shell is stopped, until the item can be locked. If locked, only the shell which locked it has access to the item until it is explicitly unlocked with the command <code>UNLOCK</code>. Always beware of deadlocks.

SET <var>table</var> LOCK <var>timeout</var> [Save]
Try to lock the table item, but wait only the specified time. This command returns '''0''' (success) if the lock request was successful within the timeout, and a non-zero error code if not. If the caller already ''holds'' the lock, the command will fail immediately. This makes sense because, since the caller is the owner, it cannot release it whilst its waiting. The argument <var>timeout</var> specifies the maximum lock-timeout in milliseconds and must be a number greater than zero.

:* If the table is locked with the option '''/Save''', the tag state of each entry, the current order and the mode is saved on <code>lock</code> and restored with the <code>unlock</code> command. In this case in the critical section entries can only be modified, but not created or deleted.

SET <var>table</var> UNLOCK
Unlock the table item. '''Note''': It's very important that for each successful <code>LOCK</code>, an <code>UNLOCK</code> is called!

See <code>lock_example.sts</code> in the script examples directory for an example.

== 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/Introducing_Table_Items#The_Show_Format|show format]], <code>1</code>…[[Programmer_Guide/Shell_Items/Table/Introducing_Table_Items#The_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/SPU Reference/AVR

2018-10-16T10:00:17Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
Average input <var>X</var> over evaluation cycles.
==<code>[SPU AVR <var>X TYP T RS</var> OUT <var>Y</var>]</code>==
{|class="einrahmen"
!input !!description !!data type !!value type!!default value
|-
|<var>X</var>||data to be averaged ||number, vector, matrix ||variable
|-
|<var>TYP</var>||averaging method ||number (int.), string||constant
|-
|<var>T</var>||averaging parameter, depends on method ||number or n.c.||<var>TYP</var>=1→variable <var>TYP</var>≠2→constant
|-
|<var>RS</var>||reset flag||number or n.c. ||variable
|-
!output !!description !!data type !!value type!!comment
|-
|<var>Y</var>||averaged input data ||same type as <var>X</var> ||variable
|}

;Description:
The averaging algorithm is defined by the inputs <var>TYP</var> and <var>T</var>. The atom averages the elements <var>X</var>[''i'',''j'']''t'' over evaluation cycles t (''i''=row index, ''j''=column index, ''t''=cycle counter) and stores the averaged value in the element <var>Y</var>[''i'',''j'']''t''.

The cycle counter ''t'' is initialized with 0 and incremented by 1 after each evaluation cycle. The cycle counter is reset, if the input <var>RS</var> is set to a value greater than <code>0</code>. The input <var>RS</var> is checked each time the SPU is started.
:;infinite average:
::<var>TYP</var>=<code>0</code> or <code>linear</code>
::<var>T</var>=<code>0</code>
::<math>Y[i,j]_t =
\begin{cases}
X[i,j]_t & \mbox{if }t=0 \\
\frac{1}{t+1}(t.Y[i,j]_{t-1}+X[i,j]_t) & \mbox{if }t>0
\end{cases}
</math>
:;running average:
::<var>TYP</var>=<code>0</code> or <code>linear</code>
::<var>T</var>><code>0</code>; <var>T</var> is the (integer) number of averaging cycles
::<math>Y[i,j]_t =
\begin{cases}
\frac{1}{t+1}\sum_{z=0}^t X[i,j]_z & \mbox{if }0\leqslant t < T \\
\frac{1}{T}\sum_{z=0}^{T-1}X[i,j]_{t-z} & \mbox{if }t\geqslant T
\end{cases}
</math>
:;exponential average:
::<var>TYP</var>=<code>1</code> or <code>exponential</code>
::<code>0</code><<var>T</var><<code>1</code>; <var>T</var> is the averaging factor
::<math>Y[i,j]_t =
\begin{cases}
X[i,j]_t & \mbox{if }t=0\mbox{ (or }T\mbox{ out of range)}\\
\sqrt{T}.Y[i,j]_{t-1}+(1-\sqrt{T}).X[i,j]_t & \mbox{if }t>0
\end{cases}
</math>
:;minimum:
::<var>TYP</var>=<code>2</code> or <code>minimum</code>
::<var>T</var> is not used
::<math>Y[i,j]_t =
\begin{cases}
X[i,j]_t & \mbox{if }t=0 \\
min(Y[i,j]_{t-1},X[i,j]_t) & \mbox{if }t>0
\end{cases}
</math>
:;maximum:
::<var>TYP</var>=<code>3</code> or <code>maximum</code>
::<var>T</var> is not used
::<math>Y[i,j]_t =
\begin{cases}
X[i,j]_t & \mbox{if }t=0 \\
max(Y[i,j]_{t-1},X[i,j]_t) & \mbox{if }t>0
\end{cases}
</math>

Since {{STx}} version 4.5.0 the following two new average modes are available, which were used to implement the spectral averaging mode <code>power</code> of the applications [[User Guide/Spectrogram and Parameter Viewer|Viewer2]] (sectioner) and [[User Guide/Spectrum Viewer|Viewer3]].

:;power:
::<var>TYP</var>=<code>4</code> or <code>power</code>
::<var>T</var> is not used
::* each input element Xi,j is squared
::* same averaging as for TYP</var>=<code>0</code> is performed
::* square root of each output element Yi,j is taken
:;db-power:
::<var>TYP</var>=<code>5</code> or <code>dbpower</code>
::<var>T</var> is not used
::* each input element Xi,j is converted from dB to squared magnitude (power)
::* same averaging as for TYP</var>=<code>0</code> is performed
::* each output element Yi,j is converted to dB
;See also:
<[[../#Signal Processing Atoms|SP-atoms]]>

Programmer Guide/SPU Reference/AVR

2018-10-16T09:57:11Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
Average input <var>X</var> over evaluation cycles.
==<code>[SPU AVR <var>X TYP T RS</var> OUT <var>Y</var>]</code>==
{|class="einrahmen"
!input !!description !!data type !!value type!!default value
|-
|<var>X</var>||data to be averaged ||number, vector, matrix ||variable
|-
|<var>TYP</var>||averaging method ||number (int.), string||constant
|-
|<var>T</var>||averaging parameter, depends on method ||number or n.c.||<var>TYP</var>=1→variable <var>TYP</var>≠2→constant
|-
|<var>RS</var>||reset flag||number or n.c. ||variable
|-
!output !!description !!data type !!value type!!comment
|-
|<var>Y</var>||averaged input data ||same type as <var>X</var> ||variable
|}

;Description:
The averaging algorithm is defined by the inputs <var>TYP</var> and <var>T</var>. The atom averages the elements <var>X</var>[''i'',''j'']''t'' over evaluation cycles t (''i''=row index, ''j''=column index, ''t''=cycle counter) and stores the averaged value in the element <var>Y</var>[''i'',''j'']''t''.

The cycle counter ''t'' is initialized with 0 and incremented by 1 after each evaluation cycle. The cycle counter is reset, if the input <var>RS</var> is set to a value greater than <code>0</code>. The input <var>RS</var> is checked each time the SPU is started.
:;infinite average:
::<var>TYP</var>=<code>0</code> or <code>linear</code>
::<var>T</var>=<code>0</code>
::<math>Y[i,j]_t =
\begin{cases}
X[i,j]_t & \mbox{if }t=0 \\
\frac{1}{t+1}(t.Y[i,j]_{t-1}+X[i,j]_t) & \mbox{if }t>0
\end{cases}
</math>
:;running average:
::<var>TYP</var>=<code>0</code> or <code>linear</code>
::<var>T</var>><code>0</code>; <var>T</var> is the (integer) number of averaging cycles
::<math>Y[i,j]_t =
\begin{cases}
\frac{1}{t+1}\sum_{z=0}^t X[i,j]_z & \mbox{if }0\leqslant t < T \\
\frac{1}{T}\sum_{z=0}^{T-1}X[i,j]_{t-z} & \mbox{if }t\geqslant T
\end{cases}
</math>
:;exponential average:
::<var>TYP</var>=<code>1</code> or <code>exponential</code>
::<code>0</code><<var>T</var><<code>1</code>; <var>T</var> is the averaging factor
::<math>Y[i,j]_t =
\begin{cases}
X[i,j]_t & \mbox{if }t=0\mbox{ (or }T\mbox{ out of range)}\\
\sqrt{T}.Y[i,j]_{t-1}+(1-\sqrt{T}).X[i,j]_t & \mbox{if }t>0
\end{cases}
</math>
:;minimum:
::<var>TYP</var>=<code>2</code> or <code>minimum</code>
::<var>T</var> is not used
::<math>Y[i,j]_t =
\begin{cases}
X[i,j]_t & \mbox{if }t=0 \\
min(Y[i,j]_{t-1},X[i,j]_t) & \mbox{if }t>0
\end{cases}
</math>
:;maximum:
::<var>TYP</var>=<code>3</code> or <code>maximum</code>
::<var>T</var> is not used
::<math>Y[i,j]_t =
\begin{cases}
X[i,j]_t & \mbox{if }t=0 \\
max(Y[i,j]_{t-1},X[i,j]_t) & \mbox{if }t>0
\end{cases}
</math>

Since {{STx}} version 4.5.0 the following two new average modes are available, which were used to implement the spectral averaging mode <code>power</code> of the applications <code>Viewer2</code> (sectioner) and <code>Viewer3</code>.

:;power:
::<var>TYP</var>=<code>4</code> or <code>power</code>
::<var>T</var> is not used
::* each input element Xi,j is squared
::* same averaging as for TYP</var>=<code>0</code> is performed
::* square root of each output element Yi,j is taken
:;db-power:
::<var>TYP</var>=<code>5</code> or <code>dbpower</code>
::<var>T</var> is not used
::* each input element Xi,j is converted from dB to squared magnitude (power)
::* same averaging as for TYP</var>=<code>0</code> is performed
::* each output element Yi,j is converted to dB
;See also:
<[[../#Signal Processing Atoms|SP-atoms]]>

Programmer Guide/SPU Reference/AVR

2018-10-16T09:56:46Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
Average input <var>X</var> over evaluation cycles.
==<code>[SPU AVR <var>X TYP T RS</var> OUT <var>Y</var>]</code>==
{|class="einrahmen"
!input !!description !!data type !!value type!!default value
|-
|<var>X</var>||data to be averaged ||number, vector, matrix ||variable
|-
|<var>TYP</var>||averaging method ||number (int.), string||constant
|-
|<var>T</var>||averaging parameter, depends on method ||number or n.c.||<var>TYP</var>=1→variable <var>TYP</var>≠2→constant
|-
|<var>RS</var>||reset flag||number or n.c. ||variable
|-
!output !!description !!data type !!value type!!comment
|-
|<var>Y</var>||averaged input data ||same type as <var>X</var> ||variable
|}

;Description:
The averaging algorithm is defined by the inputs <var>TYP</var> and <var>T</var>. The atom averages the elements <var>X</var>[''i'',''j'']''t'' over evaluation cycles t (''i''=row index, ''j''=column index, ''t''=cycle counter) and stores the averaged value in the element <var>Y</var>[''i'',''j'']''t''.

The cycle counter ''t'' is initialized with 0 and incremented by 1 after each evaluation cycle. The cycle counter is reset, if the input <var>RS</var> is set to a value greater than <code>0</code>. The input <var>RS</var> is checked each time the SPU is started.
:;infinite average:
::<var>TYP</var>=<code>0</code> or <code>linear</code>
::<var>T</var>=<code>0</code>
::<math>Y[i,j]_t =
\begin{cases}
X[i,j]_t & \mbox{if }t=0 \\
\frac{1}{t+1}(t.Y[i,j]_{t-1}+X[i,j]_t) & \mbox{if }t>0
\end{cases}
</math>
:;running average:
::<var>TYP</var>=<code>0</code> or <code>linear</code>
::<var>T</var>><code>0</code>; <var>T</var> is the (integer) number of averaging cycles
::<math>Y[i,j]_t =
\begin{cases}
\frac{1}{t+1}\sum_{z=0}^t X[i,j]_z & \mbox{if }0\leqslant t < T \\
\frac{1}{T}\sum_{z=0}^{T-1}X[i,j]_{t-z} & \mbox{if }t\geqslant T
\end{cases}
</math>
:;exponential average:
::<var>TYP</var>=<code>1</code> or <code>exponential</code>
::<code>0</code><<var>T</var><<code>1</code>; <var>T</var> is the averaging factor
::<math>Y[i,j]_t =
\begin{cases}
X[i,j]_t & \mbox{if }t=0\mbox{ (or }T\mbox{ out of range)}\\
\sqrt{T}.Y[i,j]_{t-1}+(1-\sqrt{T}).X[i,j]_t & \mbox{if }t>0
\end{cases}
</math>
:;minimum:
::<var>TYP</var>=<code>2</code> or <code>minimum</code>
::<var>T</var> is not used
::<math>Y[i,j]_t =
\begin{cases}
X[i,j]_t & \mbox{if }t=0 \\
min(Y[i,j]_{t-1},X[i,j]_t) & \mbox{if }t>0
\end{cases}
</math>
:;maximum:
::<var>TYP</var>=<code>3</code> or <code>maximum</code>
::<var>T</var> is not used
::<math>Y[i,j]_t =
\begin{cases}
X[i,j]_t & \mbox{if }t=0 \\
max(Y[i,j]_{t-1},X[i,j]_t) & \mbox{if }t>0
\end{cases}
</math>

Since {{STx}} version 4.5.0 following two new average modes are available, which were used to implement the spectral averaging mode <code>power</code> of the applications <code>Viewer2</code> (sectioner) and <code>Viewer3</code>.

:;power:
::<var>TYP</var>=<code>4</code> or <code>power</code>
::<var>T</var> is not used
::* each input element Xi,j is squared
::* same averaging as for TYP</var>=<code>0</code> is performed
::* square root of each output element Yi,j is taken
:;db-power:
::<var>TYP</var>=<code>5</code> or <code>dbpower</code>
::<var>T</var> is not used
::* each input element Xi,j is converted from dB to squared magnitude (power)
::* same averaging as for TYP</var>=<code>0</code> is performed
::* each output element Yi,j is converted to dB
;See also:
<[[../#Signal Processing Atoms|SP-atoms]]>

Programmer Guide/SPU Reference/AVR

2018-10-16T09:54:13Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
Average input <var>X</var> over evaluation cycles.
==<code>[SPU AVR <var>X TYP T RS</var> OUT <var>Y</var>]</code>==
{|class="einrahmen"
!input !!description !!data type !!value type!!default value
|-
|<var>X</var>||data to be averaged ||number, vector, matrix ||variable
|-
|<var>TYP</var>||averaging method ||number (int.), string||constant
|-
|<var>T</var>||averaging parameter, depends on method ||number or n.c.||<var>TYP</var>=1→variable <var>TYP</var>≠2→constant
|-
|<var>RS</var>||reset flag||number or n.c. ||variable
|-
!output !!description !!data type !!value type!!comment
|-
|<var>Y</var>||averaged input data ||same type as <var>X</var> ||variable
|}

;Description:
The averaging algorithm is defined by the inputs <var>TYP</var> and <var>T</var>. The atom averages the elements <var>X</var>[''i'',''j'']''t'' over evaluation cycles t (''i''=row index, ''j''=column index, ''t''=cycle counter) and stores the averaged value in the element <var>Y</var>[''i'',''j'']''t''.

The cycle counter ''t'' is initialized with 0 and incremented by 1 after each evaluation cycle. The cycle counter is reset, if the input <var>RS</var> is set to a value greater than <code>0</code>. The input <var>RS</var> is checked each time the SPU is started.
:;infinite average:
::<var>TYP</var>=<code>0</code> or <code>linear</code>
::<var>T</var>=<code>0</code>
::<math>Y[i,j]_t =
\begin{cases}
X[i,j]_t & \mbox{if }t=0 \\
\frac{1}{t+1}(t.Y[i,j]_{t-1}+X[i,j]_t) & \mbox{if }t>0
\end{cases}
</math>
:;running average:
::<var>TYP</var>=<code>0</code> or <code>linear</code>
::<var>T</var>><code>0</code>; <var>T</var> is the (integer) number of averaging cycles
::<math>Y[i,j]_t =
\begin{cases}
\frac{1}{t+1}\sum_{z=0}^t X[i,j]_z & \mbox{if }0\leqslant t < T \\
\frac{1}{T}\sum_{z=0}^{T-1}X[i,j]_{t-z} & \mbox{if }t\geqslant T
\end{cases}
</math>
:;exponential average:
::<var>TYP</var>=<code>1</code> or <code>exponential</code>
::<code>0</code><<var>T</var><<code>1</code>; <var>T</var> is the averaging factor
::<math>Y[i,j]_t =
\begin{cases}
X[i,j]_t & \mbox{if }t=0\mbox{ (or }T\mbox{ out of range)}\\
\sqrt{T}.Y[i,j]_{t-1}+(1-\sqrt{T}).X[i,j]_t & \mbox{if }t>0
\end{cases}
</math>
:;minimum:
::<var>TYP</var>=<code>2</code> or <code>minimum</code>
::<var>T</var> is not used
::<math>Y[i,j]_t =
\begin{cases}
X[i,j]_t & \mbox{if }t=0 \\
min(Y[i,j]_{t-1},X[i,j]_t) & \mbox{if }t>0
\end{cases}
</math>
:;maximum:
::<var>TYP</var>=<code>3</code> or <code>maximum</code>
::<var>T</var> is not used
::<math>Y[i,j]_t =
\begin{cases}
X[i,j]_t & \mbox{if }t=0 \\
max(Y[i,j]_{t-1},X[i,j]_t) & \mbox{if }t>0
\end{cases}
</math>
;Additional average modes in {{STx}} version ≥ 4.5.0
:used for spectral averaging in <code>Viewer2</code> (sectioner) and <code>Viewer3</code>
:;power:
::<var>TYP</var>=<code>4</code> or <code>power</code>
::<var>T</var> is not used
::* each input element Xi,j is squared
::* same averaging as for TYP</var>=<code>0</code> is performed
::* square root of each output element Yi,j is taken
:;db-power:
::<var>TYP</var>=<code>5</code> or <code>dbpower</code>
::<var>T</var> is not used
::* each input element Xi,j is converted from dB to squared magnitude (power)
::* same averaging as for TYP</var>=<code>0</code> is performed
::* each output element Yi,j is converted to dB
;See also:
<[[../#Signal Processing Atoms|SP-atoms]]>

Programmer Guide/SPU Reference/AVR

2018-10-16T09:48:54Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
Average input <var>X</var> over evaluation cycles.
==<code>[SPU AVR <var>X TYP T RS</var> OUT <var>Y</var>]</code>==
{|class="einrahmen"
!input !!description !!data type !!value type!!default value
|-
|<var>X</var>||data to be averaged ||number, vector, matrix ||variable
|-
|<var>TYP</var>||averaging method ||number (int.), string||constant
|-
|<var>T</var>||averaging parameter, depends on method ||number or n.c.||<var>TYP</var>=1→variable <var>TYP</var>≠2→constant
|-
|<var>RS</var>||reset flag||number or n.c. ||variable
|-
!output !!description !!data type !!value type!!comment
|-
|<var>Y</var>||averaged input data ||same type as <var>X</var> ||variable
|}

;Description:
The averaging algorithm is defined by the inputs <var>TYP</var> and <var>T</var>. The atom averages the elements <var>X</var>[''i'',''j'']''t'' over evaluation cycles t (''i''=row index, ''j''=column index, ''t''=cycle counter) and stores the averaged value in the element <var>Y</var>[''i'',''j'']''t''.

The cycle counter ''t'' is initialized with 0 and incremented by 1 after each evaluation cycle. The cycle counter is reset, if the input <var>RS</var> is set to a value greater than <code>0</code>. The input <var>RS</var> is checked each time the SPU is started.
:;infinite average:
::<var>TYP</var>=<code>0</code> or <code>linear</code>
::<var>T</var>=<code>0</code>
::<math>Y[i,j]_t =
\begin{cases}
X[i,j]_t & \mbox{if }t=0 \\
\frac{1}{t+1}(t.Y[i,j]_{t-1}+X[i,j]_t) & \mbox{if }t>0
\end{cases}
</math>
:;running average:
::<var>TYP</var>=<code>0</code> or <code>linear</code>
::<var>T</var>><code>0</code>; <var>T</var> is the (integer) number of averaging cycles
::<math>Y[i,j]_t =
\begin{cases}
\frac{1}{t+1}\sum_{z=0}^t X[i,j]_z & \mbox{if }0\leqslant t < T \\
\frac{1}{T}\sum_{z=0}^{T-1}X[i,j]_{t-z} & \mbox{if }t\geqslant T
\end{cases}
</math>
:;exponential average:
::<var>TYP</var>=<code>1</code> or <code>exponential</code>
::<code>0</code><<var>T</var><<code>1</code>; <var>T</var> is the averaging factor
::<math>Y[i,j]_t =
\begin{cases}
X[i,j]_t & \mbox{if }t=0\mbox{ (or }T\mbox{ out of range)}\\
\sqrt{T}.Y[i,j]_{t-1}+(1-\sqrt{T}).X[i,j]_t & \mbox{if }t>0
\end{cases}
</math>
:;minimum:
::<var>TYP</var>=<code>2</code> or <code>minimum</code>
::<var>T</var> is not used
::<math>Y[i,j]_t =
\begin{cases}
X[i,j]_t & \mbox{if }t=0 \\
min(Y[i,j]_{t-1},X[i,j]_t) & \mbox{if }t>0
\end{cases}
</math>
:;maximum:
::<var>TYP</var>=<code>3</code> or <code>maximum</code>
::<var>T</var> is not used
::<math>Y[i,j]_t =
\begin{cases}
X[i,j]_t & \mbox{if }t=0 \\
max(Y[i,j]_{t-1},X[i,j]_t) & \mbox{if }t>0
\end{cases}
</math>
;Additional average modes in {{STx}} version >= 4.5.0
:;power:
::<var>TYP</var>=<code>4</code> or <code>power</code>
::<var>T</var> is not used
::* each input element Xi,j is squared
::* same averaging as for TYP</var>=<code>0</code> is performed
::* square root of each output element Yi,j is taken
:;db-power:
::<var>TYP</var>=<code>5</code> or <code>dbpower</code>
::<var>T</var> is not used
::* each input element Xi,j is converted from dB to squared magnitude (power)
::* same averaging as for TYP</var>=<code>0</code> is performed
::* each output element Yi,j is converted to dB
;See also:
<[[../#Signal Processing Atoms|SP-atoms]]>

Programmer Guide/SPU Reference/AVR

2018-10-16T09:44:29Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
Average input <var>X</var> over evaluation cycles.
==<code>[SPU AVR <var>X TYP T RS</var> OUT <var>Y</var>]</code>==
{|class="einrahmen"
!input !!description !!data type !!value type!!default value
|-
|<var>X</var>||data to be averaged ||number, vector, matrix ||variable
|-
|<var>TYP</var>||averaging method ||number (int.), string||constant
|-
|<var>T</var>||averaging parameter, depends on method ||number or n.c.||<var>TYP</var>=1→variable <var>TYP</var>≠2→constant
|-
|<var>RS</var>||reset flag||number or n.c. ||variable
|-
!output !!description !!data type !!value type!!comment
|-
|<var>Y</var>||averaged input data ||same type as <var>X</var> ||variable
|}

;Description:
The averaging algorithm is defined by the inputs <var>TYP</var> and <var>T</var>. The atom averages the elements <var>X</var>[''i'',''j'']''t'' over evaluation cycles t (''i''=row index, ''j''=column index, ''t''=cycle counter) and stores the averaged value in the element <var>Y</var>[''i'',''j'']''t''.

The cycle counter ''t'' is initialized with 0 and incremented by 1 after each evaluation cycle. The cycle counter is reset, if the input <var>RS</var> is set to a value greater than <code>0</code>. The input <var>RS</var> is checked each time the SPU is started.
:;infinite average:
::<var>TYP</var>=<code>0</code> or <code>linear</code>
::<var>T</var>=<code>0</code>
::<math>Y[i,j]_t =
\begin{cases}
X[i,j]_t & \mbox{if }t=0 \\
\frac{1}{t+1}(t.Y[i,j]_{t-1}+X[i,j]_t) & \mbox{if }t>0
\end{cases}
</math>
:;running average:
::<var>TYP</var>=<code>0</code> or <code>linear</code>
::<var>T</var>><code>0</code>; <var>T</var> is the (integer) number of averaging cycles
::<math>Y[i,j]_t =
\begin{cases}
\frac{1}{t+1}\sum_{z=0}^t X[i,j]_z & \mbox{if }0\leqslant t < T \\
\frac{1}{T}\sum_{z=0}^{T-1}X[i,j]_{t-z} & \mbox{if }t\geqslant T
\end{cases}
</math>
:;exponential average:
::<var>TYP</var>=<code>1</code> or <code>exponential</code>
::<code>0</code><<var>T</var><<code>1</code>; <var>T</var> is the averaging factor
::<math>Y[i,j]_t =
\begin{cases}
X[i,j]_t & \mbox{if }t=0\mbox{ (or }T\mbox{ out of range)}\\
\sqrt{T}.Y[i,j]_{t-1}+(1-\sqrt{T}).X[i,j]_t & \mbox{if }t>0
\end{cases}
</math>
:;minimum:
::<var>TYP</var>=<code>2</code> or <code>minimum</code>
::<var>T</var> is not used
::<math>Y[i,j]_t =
\begin{cases}
X[i,j]_t & \mbox{if }t=0 \\
min(Y[i,j]_{t-1},X[i,j]_t) & \mbox{if }t>0
\end{cases}
</math>
:;maximum:
::<var>TYP</var>=<code>3</code> or <code>maximum</code>
::<var>T</var> is not used
::<math>Y[i,j]_t =
\begin{cases}
X[i,j]_t & \mbox{if }t=0 \\
max(Y[i,j]_{t-1},X[i,j]_t) & \mbox{if }t>0
\end{cases}
</math>
:;power:
::<var>TYP</var>=<code>4</code> or <code>power</code>
::<var>T</var> is not used
::* each input element Xi,j is squared
::* same averaging as for TYP</var>=<code>4</code> is performed
::* square root of each output element Yi,j is taken
;See also:
<[[../#Signal Processing Atoms|SP-atoms]]>

Programmer Guide/SPU Reference/MORLET

2018-10-16T07:42:34Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
====MORLET - wavelet transform====

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

<code>MORLET <var>X</var> <var>SP</var> <var>SR</var> <var>DF</var> <var>FB</var> <var>LB</var> <var>F0</var> <var>ACUT</var> <var>TYP</var> <var>O</var> <var>FMT</var> <var>MAMI</var> <var>MAMX</var> <var>MPV</var></code>

=====Inputs:=====

{|
|-
|X
|input signal; length depends on lowest frequency
|-
|SR
|sampling frequency in Hz
|-
|DF
|frequency resolution in Hz
|-
|FB, LB
|first and last frequency bin of wavelet analysis
|-
|F0, O, ACUT
|wavelet parameters (see function description)
|-
|TYP
|wavelet typ
|-
|FMT
|output format
|-
|SP, MAMI,MAMX, MPV
|phase locking and masking parameters; see atom SPECTRUM
|}

=====Outputs:=====

{|
|-
|<var>WR, WI</var>
|wavelet spectrum output; depends on FMT
|-
|FR
|vector of center frequencies
|-
|BW
|vector or bandwidth frequencies
|-
|TW
|vector of timewidth values
|}

=====Function:=====

This module computes a wavelet analysis using different types of wavelets. In S_TOOLS<nowiki>-</nowiki>STx a scaled wavelet transformation with a bounded integration interval is used:

[[File:1251.png]]

with:

{|
|-
|a
|frequency scaling parameter
|-
|b
|time shift parameter
|-
|S(a)
|amplitude scaling factor
|-
|a
|time window width (input ACUT
|-
|f0
|basic frequency of wavelet function (input F0)
|}

The wavelet function W is defined by the inputs TYP (type of wavelet), ACUT (window width), F0 (basic frequency) and O (order). The available wavelet types and the parameters are described later in this section. The time shift parameter b is always set to the center of the input signal, because the frame shifting is performed outside the module (by the signal I/O functions).

The wavelet transform is computed for a set of discrete frequencies fI, which are defined by the inputs DF, FB (first bin) and LB (last bin):

[[File:1252.png]]

with:

{|
|-
|I
|frequency bin index, FB <= I <= LB
|-
|DF
|frequency resolution in Hz
|}

The scaling factor S(a) is computed for each frequency fI to get the magnitude 1 for a pure sinoid with frequency fI. This scaling is performed to get a 'wavelet spectrum' that is comparable to other spectrum analysis/transformation methods.

For each input signal frame X the wavelet transform of all frequency bins fI is computed:

[[File:1253.png]]

with:

{|
|-
|f0
|basic frequency of wavelet function (see wavelet table below)
|-
|aI
|frequency scaling factor for bin I (= f0/fI)
|-
|tA
|point of analysis, set to the center of the signal vector
|-
|wrI, wiI
|real an imaginary part of H' at bin I;
|}

The values wrI and wiI are converted to different formats (see output format table) and stored in the outputs WR and WI. In addition the center frequencies (fI, output FR), the analysis bandwidths (output BW) and time window widths (output TW) of each bin are computed and stored in outputs.

The length of the input signal X (NX) should be equal to (or greater than) the longest time window. If the signal is shorter zero padding on both sides in performed.

[[File:1254.png]]

The input SP, MAMI, MAMX and MPV are used for the phase computation and are processed in the same way as for the atom [[Programmer Guide/SPU Reference/SPECTRUM - fft spectrum|SPECTRUM]]. Phase locking and masking is also described in this section.

Table 15: Wavelet functions (input TYP) and parameters (inputs F0 and O){|
|-
|TYP
|wavelet W(t)
|F0, O (comments)
|-
|0
|Morlet:[[File:1257.png]]
|f0 = F0
|-
|1
|Generalized Morlet:[[File:1256.png]]
|f0 = F0n = O
|-
|2
|Laplace:[[File:1255.png]]
|f0 = F0
|-
|3
|n<nowiki>-</nowiki>th derivative Gaussian:[[File:1258.png]]
|n = F0 (integer, >=0)[[File:1259.png]]
|-
|4
|Mexican Hat: special case of n<nowiki>-</nowiki>th derivative Gaussian with n equals 2
|f0 = F0
|-
|5
|Goupillaud:[[File:4496.png]]
|f0 = F0
|-
|6
|Morlet II:[[File:4497.png]]
|f0 = F0
|}

Table 16: Output formats (selected by input FMT)
{|
|-
|FMT
|output WR
|output WI
|-
|0, 10
|real part: WRI = wrI
|imaginary part: WII = wiI
|-
|1
|energy: WRI = aI2
|phase: WII = jI
|-
|2
|real part: WRI = wrI
|all zero: WII = 0
|-
|3
|imaginary part: WRI = wiI
|all zero: WII = 0
|-
|4
|amplitude: WRI = aI
|all zero: WII = 0
|-
|5
|phase: WRI = jI
|all zero: WII = 0
|-
|6
|energy: WRI = aI2
|locked phase: WII = j'I
|-
|7
|amplitude (dB): WRI = 20.log10(aI)
|phase: WII = jI
|-
|8
|amplitude (dB): WRI = 20.log10(aI)
|locked phase: WII = j'I
|-
|9
|locked phase: WRI = j'I
|all zero: WII = 0
|}

with:

{|
|-
|I
|bin index (FB, ..., LB)
|-
|wrI, wiI
|real and imaginary part of the wavelet bin I
|-
|aI
|amplitude of wavelet bin I (aI2 = wrI2 + wiI2)
|-
|jI, j'I
|unlocked/locked phase of wavelet bin I (jI = arctan(wiI/wrI))
|}

Programmer Guide/Shell Items/File/FILE Item Attributes

2018-04-10T10:15:04Z

Toni: /* Common file item attributes */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{File Item}}
The following file item attributes can be queried in the format <code>$#fileItem[<var>Attribute</var>]</code>.

== Common file item attributes ==

{|class="einrahmen"
!Attribute
! colspan="2" | Value(s) and Description
|-
| <code>!PATH</code>
| colspan="2" | full path of the file attached to the respective file item
|-
| <code>!UNCPATH</code>
| colspan="2" | full path of the file attached to the respective file item in UNC format
|-
| <code>!DRIVE</code>
| colspan="2" | the drive letter of the file attached to the respective file item (without a colon)
|-
| <code>!DIRECTORY</code>
| colspan="2" | the directory of the file attached to the respective file item (without a trailing backslash)
|-
| <code>!UNCDIRECTORY</code>
| colspan="2" | the directory of the file attached to the respective file item (without a trailing backslash) in UNC format
|-
| <code>!NAME</code>
| colspan="2" | the name of file attached to the respective file item
|-
| <code>!EXTENSION</code>
| colspan="2" | extension part of the filename of the file attached to the respective file item (without a leading "<code>.</code>")
|-
| <code>!FILENAME</code>
| colspan="2" | name and extension of the file
|-
| <code>!CREATED</code>
| <code>yyyy.mm.dd hh.mm.ss</code>
| creation date and time of file attached to the file item
|-
| <code>!MODIFIED</code>
| <code>yyyy.mm.dd hh.mm.ss</code>
| time of last modification of file attached to the file item
|-
| <code>!MTSTAMP</code>
| <code>modmin</code>
| time of last modification in minutes since 1st January 1980
|-
| <code>!ATTRIBUTES</code>
| <code>DIRECTORY|SYSTEM|HIDDEN|NORMAL</code>
| type attributes of file attached to the file item
|-
| <code>!ACCESS</code>
| <code>READ|WRITE|APPEND</code>
| access attributes of file attached to the file item
|-
| <code>!SIZE</code>
| <code>filesize</code>
| size of file attached to the file item in bytes
|-
| <code>!TYPE</code>
| <code>FILE|LIST|TEXT|SECTION|XML</code>
| type of file item (set in NEW command)
|-
| <code>!SHELL</code>
| <code>owner</code>
| shellidid of shell creating the file item (8 hex digits)
|-
| <code>!USERS</code>
| <code>numusers</code>
| number of linked items sharing the file item
|-
| <code>!LASTACCESS</code>
| <code>yyyy.mm.dd hh.mm.ss</code>
| date and time of the last access to the file attached to the file item
|-
| rowspan="2" | <code>!CHANGED</code>
| <code>a number >= 0</code>
| A value of 0 indicates that the file in memory is identical to that on disk. For all files except XML files, a value of 1 indicates that the file has been changed in memory and has not been saved yet. For XML files, the value may be greater than 1, and indicates the number of change operations which have been made since the last time the content was saved to disk.
|-
| assigning <code>1</code> or <code>0</code>
| You may programmatically set, or reset, the value of the !CHANGED attribute by ''assigning'' <code>1</code>, or <code>0</code>, to this attribute:

$#file[!changed] := 1 // set the attribute
$#file[!changed] := 0 // reset the attribute

Warning: this functionality changed in version 3.9.0. Previously, setting the attribute using '1' would ''reset'' the attribute, and using the value '0' was unsupported.
|}

== Binary file items ==

{|class="einrahmen"
|-
! Attribute
! Value(s)
! Description
|-
| rowspan="2" | <code>!BININFO</code>
| rowspan="2" | number of sections
| After a <code>LIST</code> command, <code>!BININFO</code> will return the index of the last section loaded/saved.
|-
| After a <code>LOAD</code> command <code><nowiki>-</nowiki>1</code>, if the file is not a binary file, or the last command failed. 
|}

== GDX file items ==

The GDX file item supports the following attributes in addition to the general file item attributes.

{|class="einrahmen"
!Attribute
! colspan="2" | Value(s) and Description
|-
|<code>!DATA</code>
|The <code>!DATA</code> attribute returns data from the GDX file.
$#gdx[!DATA] // returns all the data
$#gdx[!DATA,index,count] // returns one or more columns
Here the <code>index</code> argument determines the first column, and the <code>count</code> argument determines the number of columns to return.
|-
|<code>!DATATYPE</code>
|The <code>!DATATYPE</code> attribute returns the data type of this GDX file (See [[Programmer Guide/Shell Items/File/NEW FILE|Creating a GDX file]] for details).
|-
|<code>!NCOL</code>
|The <code>!NCOL</code> attribute returns the number of columns.
|-
|<code>!NROW</code>
|The <code>!NROW</code> attribute returns the number of rows.
|-
|<code>!NWRITTEN</code>
|The <code>!NWRITTEN</code> attribute returns the number of columns which have been written (rather than defined).
|}

== XML file items ==

=== General attributes of XML file items ===

{|class="einrahmen"
! Attribute
! Value(s)
! Description
|-
| <code>!XROOT</code>
| <var>root_element_nametag</var>
| name of the root element
|-
| <code>!XPARENT</code>
| <var>parent_element_nametag</var>
| name of the parent element
|-
| <code>!XPARENTPATH</code>
| <var>root_element_name\…\parent_element_name</var>
| full path of the parent element
|-
| <code>!XELEMENTS</code>
| <var>elementcountnumber</var>
| of elements on selected element level
|-
| <code>!XNODETYPE</code>
| <code>ELEMENT|COMMENT|PROC|DOCTYPE</code>
| type of the selected node
|}

=== Attributes of the selected element of an XML file item ===

{|class="einrahmen"
! Attribute
! Argument
! Value(s) and Description
|-
| rowspan="9" | <code>!XALL</code>
|
|-
|  
| a list of all element parts
|-
| <var>tag</var> || element tag name
|-
| <var>empty</var> || 1 if element data is empty, 0 otherwise
|-
| <var>cdata</var> || 1 if element data is a CData-section, 0 otherwise
|-
| <var>childs</var> || number of child elements
|-
| <var>size</var> || size of data section (characters)
|-
| <var>nattr</var> || number of attributes
|-
| <var>attr0</var>,… || name of attribute 0, … (0 to <var>nattr</var>-1)
|-
| <code>!XTAG</code>
|<nowiki>-</nowiki>
|element_tag
|-
| <code>!XATTRIBUTES</code>
|<nowiki>-</nowiki>
|number_of_attributes
|-
| <code>!XATTRIBUTE</code>
|<var>index</var>
|attribute_name name of attribute number <var>index</var>
|-
| <code>!XATTRIBUTE</code>
|<var>name</var>
|attribute_value value of attribute named <var>name</var>
|-
| <code>!XEMPTY</code>
|<nowiki>-</nowiki>
|returns 1 if element is empty (no data) and 0 otherwise
|-
| <code>!XCDATA</code>
|<nowiki>-</nowiki>
|returns 1 if element contains a CData section and 0 otherwise
|-
| <code>!XCHILDS</code> or <code>!XCHILDREN</code>
|<nowiki>-</nowiki>
|returns number of child elements of the selected element
|-
| <code>!XSIZE</code>
|<nowiki>-</nowiki>
|size of data section in characters
|-
| <code>!XDATA</code>
|<nowiki>-</nowiki>
|content of data section
|}

=== Document/element type definition attributes of an XML file item ===

{|class="einrahmen"
!Attribute<nowiki>-</nowiki>Id
!Sub<nowiki>-</nowiki>Id 1
!Sub<nowiki>-</nowiki>Id 2
!Value(s) and Description
|-
|<code>!XDTNAME</code>
|<nowiki>-</nowiki>
|<nowiki>-</nowiki>
|name of document type definition
|-
|<code>!XDTROOT</code>
|<nowiki>-</nowiki>
|<nowiki>-</nowiki>
|tag of root element
|-
|<code>!XDTELEMENTS</code>
|<nowiki>-</nowiki>
|<nowiki>-</nowiki>
|number of defined element types
|-
|<code>!XDTELEMENT</code>
|<var>index</var> or <var>tag</var>
|<nowiki>-</nowiki>
|definition of element type with specified index or tag; the result is
<code>tag parent base nobase data with</code>:
{|
! tag !! element tag
|-
|parent
|parent element tag or <code>*</code>
|-
|base
|base element tag or <code>*</code>
|-
|nobase
|nobase element tag or <code>*</code>
|-
|data
|data type name or <code>*</code>
|}
|-
|<code>!XDTCHILDREN</code>
|<var>tag</var>
|<nowiki>-</nowiki>
|number of children defined for element tag
|-
|<code>!XDTCHILD</code>
|<var>tag</var>
|cindex or ctag
|definition of child cindex or ctag of the element tag. The result is:ctag min maxwith:
{|
! ctag !! tag of child element
|-
|<var>min</var>
|number of minimum occurrences
|-
|<var>max</var>
|number of maximum occurrences or <nowiki>-</nowiki>1 if not defined
|}
|-
|<code>!XDTATTRIBUTES</code>
|<var>tag</var>
|<nowiki>-</nowiki>
|number of attributes defined for element tag
|-
|<code>!XTDATTRIBUTE</code>
|tag
|<var>aindex</var> or <var>aname</var>
|definition of attribute aindex or aname of element tag. The result is:aname req vis val type paramswith:
{|
! aname !! name of attribute
|-
|req
|required flag (0=no, 1=yes)
|-
|vis
|visibility flag (0=hidden, 1=value, 2=name and value)
|-
|val
|default value of * if not set
|-
|type
|attribute value type (<code>INTEGER</code>, <code>NUMBER</code>, <code>STRING</code>, <code>VALUELIST</code>)
|-
|params
|parameters, depends on type{|
|-
|<code>INTEGER</code>
|<code><var>minval</var><nowiki>|</nowiki>* <var>maxval</var><nowiki>|</nowiki>*</code>
|-
|<code>NUMBER</code>
|<code><var>minval</var><nowiki>|</nowiki>* <var>maxval</var><nowiki>|</nowiki>*</code>
|-
|<code>STRING</code>
|unique{0<nowiki>|</nowiki>1} respect{0<nowiki>|</nowiki>1}
|-
|<code>VALUELIST</code>
|<code>value1 value2 …</code>
|}
|-
| <code>!XDTISA</code>
| <var>tag</var>
| none
| returns <code>1</code> if the selected element of the file item is of type <var>tag</var> or is derived from <var>tag</var> and <code>0</code> otherwise
|}

Programmer Guide/Shell Items/File/FILE Item Attributes

2018-04-10T10:12:10Z

Toni: /* Common file item attributes */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{File Item}}
The following file item attributes can be queried in the format <code>$#fileItem[<var>Attribute</var>]</code>.

== Common file item attributes ==

{|class="einrahmen"
!Attribute
! colspan="2" | Value(s) and Description
|-
| <code>!PATH</code>
| colspan="2" | full path of the file attached to the respective file item
|-
| <code>!DRIVE</code>
| colspan="2" | the drive letter of the file attached to the respective file item (without a colon)
|-
| <code>!DIRECTORY</code>
| colspan="2" | the directory of the file attached to the respective file item (without a trailing backslash)
|-
| <code>!NAME</code>
| colspan="2" | the name of file attached to the respective file item
|-
| <code>!EXTENSION</code>
| colspan="2" | extension part of the filename of the file attached to the respective file item (without a leading "<code>.</code>")
|-
| <code>!FILENAME</code>
| colspan="2" | name and extension of the file
|-
| <code>!CREATED</code>
| <code>yyyy.mm.dd hh.mm.ss</code>
| creation date and time of file attached to the file item
|-
| <code>!MODIFIED</code>
| <code>yyyy.mm.dd hh.mm.ss</code>
| time of last modification of file attached to the file item
|-
| <code>!TIMESTAMP</code>
| <code>modmin</code>
| time of last modification in minutes of since 1st January 1980
|-
| <code>!ATTRIBUTES</code>
| <code>DIRECTORY|SYSTEM|HIDDEN|NORMAL</code>
| type attributes of file attached to the file item
|-
| <code>!ACCESS</code>
| <code>READ|WRITE|APPEND</code>
| access attributes of file attached to the file item
|-
| <code>!SIZE</code>
| <code>filesize</code>
| size of file attached to the file item in bytes
|-
| <code>!TYPE</code>
| <code>FILE|LIST|TEXT|SECTION|XML</code>
| type of file item (set in NEW command)
|-
| <code>!SHELL</code>
| <code>owner</code>
| shellidid of shell creating the file item (8 hex digits)
|-
| <code>!USERS</code>
| <code>numusers</code>
| number of linked items sharing the file item
|-
| <code>!LASTACCESS</code>
| <code>yyyy.mm.dd hh.mm.ss</code>
| date and time of the last access to the file attached to the file item
|-
| rowspan="2" | <code>!CHANGED</code>
| <code>a number >= 0</code>
| A value of 0 indicates that the file in memory is identical to that on disk. For all files except XML files, a value of 1 indicates that the file has been changed in memory and has not been saved yet. For XML files, the value may be greater than 1, and indicates the number of change operations which have been made since the last time the content was saved to disk.
|-
| assigning <code>1</code> or <code>0</code>
| You may programmatically set, or reset, the value of the !CHANGED attribute by ''assigning'' <code>1</code>, or <code>0</code>, to this attribute:

$#file[!changed] := 1 // set the attribute
$#file[!changed] := 0 // reset the attribute

Warning: this functionality changed in version 3.9.0. Previously, setting the attribute using '1' would ''reset'' the attribute, and using the value '0' was unsupported.
|}

== Binary file items ==

{|class="einrahmen"
|-
! Attribute
! Value(s)
! Description
|-
| rowspan="2" | <code>!BININFO</code>
| rowspan="2" | number of sections
| After a <code>LIST</code> command, <code>!BININFO</code> will return the index of the last section loaded/saved.
|-
| After a <code>LOAD</code> command <code><nowiki>-</nowiki>1</code>, if the file is not a binary file, or the last command failed. 
|}

== GDX file items ==

The GDX file item supports the following attributes in addition to the general file item attributes.

{|class="einrahmen"
!Attribute
! colspan="2" | Value(s) and Description
|-
|<code>!DATA</code>
|The <code>!DATA</code> attribute returns data from the GDX file.
$#gdx[!DATA] // returns all the data
$#gdx[!DATA,index,count] // returns one or more columns
Here the <code>index</code> argument determines the first column, and the <code>count</code> argument determines the number of columns to return.
|-
|<code>!DATATYPE</code>
|The <code>!DATATYPE</code> attribute returns the data type of this GDX file (See [[Programmer Guide/Shell Items/File/NEW FILE|Creating a GDX file]] for details).
|-
|<code>!NCOL</code>
|The <code>!NCOL</code> attribute returns the number of columns.
|-
|<code>!NROW</code>
|The <code>!NROW</code> attribute returns the number of rows.
|-
|<code>!NWRITTEN</code>
|The <code>!NWRITTEN</code> attribute returns the number of columns which have been written (rather than defined).
|}

== XML file items ==

=== General attributes of XML file items ===

{|class="einrahmen"
! Attribute
! Value(s)
! Description
|-
| <code>!XROOT</code>
| <var>root_element_nametag</var>
| name of the root element
|-
| <code>!XPARENT</code>
| <var>parent_element_nametag</var>
| name of the parent element
|-
| <code>!XPARENTPATH</code>
| <var>root_element_name\…\parent_element_name</var>
| full path of the parent element
|-
| <code>!XELEMENTS</code>
| <var>elementcountnumber</var>
| of elements on selected element level
|-
| <code>!XNODETYPE</code>
| <code>ELEMENT|COMMENT|PROC|DOCTYPE</code>
| type of the selected node
|}

=== Attributes of the selected element of an XML file item ===

{|class="einrahmen"
! Attribute
! Argument
! Value(s) and Description
|-
| rowspan="9" | <code>!XALL</code>
|
|-
|  
| a list of all element parts
|-
| <var>tag</var> || element tag name
|-
| <var>empty</var> || 1 if element data is empty, 0 otherwise
|-
| <var>cdata</var> || 1 if element data is a CData-section, 0 otherwise
|-
| <var>childs</var> || number of child elements
|-
| <var>size</var> || size of data section (characters)
|-
| <var>nattr</var> || number of attributes
|-
| <var>attr0</var>,… || name of attribute 0, … (0 to <var>nattr</var>-1)
|-
| <code>!XTAG</code>
|<nowiki>-</nowiki>
|element_tag
|-
| <code>!XATTRIBUTES</code>
|<nowiki>-</nowiki>
|number_of_attributes
|-
| <code>!XATTRIBUTE</code>
|<var>index</var>
|attribute_name name of attribute number <var>index</var>
|-
| <code>!XATTRIBUTE</code>
|<var>name</var>
|attribute_value value of attribute named <var>name</var>
|-
| <code>!XEMPTY</code>
|<nowiki>-</nowiki>
|returns 1 if element is empty (no data) and 0 otherwise
|-
| <code>!XCDATA</code>
|<nowiki>-</nowiki>
|returns 1 if element contains a CData section and 0 otherwise
|-
| <code>!XCHILDS</code> or <code>!XCHILDREN</code>
|<nowiki>-</nowiki>
|returns number of child elements of the selected element
|-
| <code>!XSIZE</code>
|<nowiki>-</nowiki>
|size of data section in characters
|-
| <code>!XDATA</code>
|<nowiki>-</nowiki>
|content of data section
|}

=== Document/element type definition attributes of an XML file item ===

{|class="einrahmen"
!Attribute<nowiki>-</nowiki>Id
!Sub<nowiki>-</nowiki>Id 1
!Sub<nowiki>-</nowiki>Id 2
!Value(s) and Description
|-
|<code>!XDTNAME</code>
|<nowiki>-</nowiki>
|<nowiki>-</nowiki>
|name of document type definition
|-
|<code>!XDTROOT</code>
|<nowiki>-</nowiki>
|<nowiki>-</nowiki>
|tag of root element
|-
|<code>!XDTELEMENTS</code>
|<nowiki>-</nowiki>
|<nowiki>-</nowiki>
|number of defined element types
|-
|<code>!XDTELEMENT</code>
|<var>index</var> or <var>tag</var>
|<nowiki>-</nowiki>
|definition of element type with specified index or tag; the result is
<code>tag parent base nobase data with</code>:
{|
! tag !! element tag
|-
|parent
|parent element tag or <code>*</code>
|-
|base
|base element tag or <code>*</code>
|-
|nobase
|nobase element tag or <code>*</code>
|-
|data
|data type name or <code>*</code>
|}
|-
|<code>!XDTCHILDREN</code>
|<var>tag</var>
|<nowiki>-</nowiki>
|number of children defined for element tag
|-
|<code>!XDTCHILD</code>
|<var>tag</var>
|cindex or ctag
|definition of child cindex or ctag of the element tag. The result is:ctag min maxwith:
{|
! ctag !! tag of child element
|-
|<var>min</var>
|number of minimum occurrences
|-
|<var>max</var>
|number of maximum occurrences or <nowiki>-</nowiki>1 if not defined
|}
|-
|<code>!XDTATTRIBUTES</code>
|<var>tag</var>
|<nowiki>-</nowiki>
|number of attributes defined for element tag
|-
|<code>!XTDATTRIBUTE</code>
|tag
|<var>aindex</var> or <var>aname</var>
|definition of attribute aindex or aname of element tag. The result is:aname req vis val type paramswith:
{|
! aname !! name of attribute
|-
|req
|required flag (0=no, 1=yes)
|-
|vis
|visibility flag (0=hidden, 1=value, 2=name and value)
|-
|val
|default value of * if not set
|-
|type
|attribute value type (<code>INTEGER</code>, <code>NUMBER</code>, <code>STRING</code>, <code>VALUELIST</code>)
|-
|params
|parameters, depends on type{|
|-
|<code>INTEGER</code>
|<code><var>minval</var><nowiki>|</nowiki>* <var>maxval</var><nowiki>|</nowiki>*</code>
|-
|<code>NUMBER</code>
|<code><var>minval</var><nowiki>|</nowiki>* <var>maxval</var><nowiki>|</nowiki>*</code>
|-
|<code>STRING</code>
|unique{0<nowiki>|</nowiki>1} respect{0<nowiki>|</nowiki>1}
|-
|<code>VALUELIST</code>
|<code>value1 value2 …</code>
|}
|-
| <code>!XDTISA</code>
| <var>tag</var>
| none
| returns <code>1</code> if the selected element of the file item is of type <var>tag</var> or is derived from <var>tag</var> and <code>0</code> otherwise
|}

Programmer Guide/Shell Items/File/FILE Item Attributes

2018-04-06T07:28:36Z

Toni: /* Common file item attributes */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{File Item}}
The following file item attributes can be queried in the format <code>$#fileItem[<var>Attribute</var>]</code>.

== Common file item attributes ==

{|class="einrahmen"
!Attribute
! colspan="2" | Value(s) and Description
|-
| <code>!PATH</code>
| colspan="2" | full path of the file attached to the respective file item
|-
| <code>!DRIVE</code>
| colspan="2" | the drive letter of the file attached to the respective file item (without a colon)
|-
| <code>!DIRECTORY</code>
| colspan="2" | the directory of the file attached to the respective file item (without a trailing backslash)
|-
| <code>!NAME</code>
| colspan="2" | the name of file attached to the respective file item
|-
| <code>!EXTENSION</code>
| colspan="2" | extension part of the filename of the file attached to the respective file item (without a leading "<code>.</code>")
|-
| <code>!FILENAME</code>
| colspan="2" | name and extension of the file
|-
| <code>!CREATED</code>
| <code>yyyy.mm.dd hh.mm.ss</code>
| creation date and time of file attached to the file item
|-
| <code>!MODIFIED</code>
| <code>yyyy.mm.dd hh.mm.ss</code>
| time of last modification of file attached to the file item
|-
| <code>!ATTRIBUTES</code>
| <code>DIRECTORY|SYSTEM|HIDDEN|NORMAL</code>
| type attributes of file attached to the file item
|-
| <code>!ACCESS</code>
| <code>READ|WRITE|APPEND</code>
| access attributes of file attached to the file item
|-
| <code>!SIZE</code>
| <code>filesize</code>
| size of file attached to the file item in bytes
|-
| <code>!TYPE</code>
| <code>FILE|LIST|TEXT|SECTION|XML</code>
| type of file item (set in NEW command)
|-
| <code>!SHELL</code>
| <code>owner</code>
| shellidid of shell creating the file item (8 hex digits)
|-
| <code>!USERS</code>
| <code>numusers</code>
| number of linked items sharing the file item
|-
| <code>!LASTACCESS</code>
| <code>yyyy.mm.dd hh.mm.ss</code>
| date and time of the last access to the file attached to the file item
|-
| rowspan="2" | <code>!CHANGED</code>
| <code>a number >= 0</code>
| A value of 0 indicates that the file in memory is identical to that on disk. For all files except XML files, a value of 1 indicates that the file has been changed in memory and has not been saved yet. For XML files, the value may be greater than 1, and indicates the number of change operations which have been made since the last time the content was saved to disk.
|-
| assigning <code>1</code> or <code>0</code>
| You may programmatically set, or reset, the value of the !CHANGED attribute by ''assigning'' <code>1</code>, or <code>0</code>, to this attribute:

$#file[!changed] := 1 // set the attribute
$#file[!changed] := 0 // reset the attribute

Warning: this functionality changed in version 3.9.0. Previously, setting the attribute using '1' would ''reset'' the attribute, and using the value '0' was unsupported.
|}

== Binary file items ==

{|class="einrahmen"
|-
! Attribute
! Value(s)
! Description
|-
| rowspan="2" | <code>!BININFO</code>
| rowspan="2" | number of sections
| After a <code>LIST</code> command, <code>!BININFO</code> will return the index of the last section loaded/saved.
|-
| After a <code>LOAD</code> command <code><nowiki>-</nowiki>1</code>, if the file is not a binary file, or the last command failed. 
|}

== GDX file items ==

The GDX file item supports the following attributes in addition to the general file item attributes.

{|class="einrahmen"
!Attribute
! colspan="2" | Value(s) and Description
|-
|<code>!DATA</code>
|The <code>!DATA</code> attribute returns data from the GDX file.
$#gdx[!DATA] // returns all the data
$#gdx[!DATA,index,count] // returns one or more columns
Here the <code>index</code> argument determines the first column, and the <code>count</code> argument determines the number of columns to return.
|-
|<code>!DATATYPE</code>
|The <code>!DATATYPE</code> attribute returns the data type of this GDX file (See [[Programmer Guide/Shell Items/File/NEW FILE|Creating a GDX file]] for details).
|-
|<code>!NCOL</code>
|The <code>!NCOL</code> attribute returns the number of columns.
|-
|<code>!NROW</code>
|The <code>!NROW</code> attribute returns the number of rows.
|-
|<code>!NWRITTEN</code>
|The <code>!NWRITTEN</code> attribute returns the number of columns which have been written (rather than defined).
|}

== XML file items ==

=== General attributes of XML file items ===

{|class="einrahmen"
! Attribute
! Value(s)
! Description
|-
| <code>!XROOT</code>
| <var>root_element_nametag</var>
| name of the root element
|-
| <code>!XPARENT</code>
| <var>parent_element_nametag</var>
| name of the parent element
|-
| <code>!XPARENTPATH</code>
| <var>root_element_name\…\parent_element_name</var>
| full path of the parent element
|-
| <code>!XELEMENTS</code>
| <var>elementcountnumber</var>
| of elements on selected element level
|-
| <code>!XNODETYPE</code>
| <code>ELEMENT|COMMENT|PROC|DOCTYPE</code>
| type of the selected node
|}

=== Attributes of the selected element of an XML file item ===

{|class="einrahmen"
! Attribute
! Argument
! Value(s) and Description
|-
| rowspan="9" | <code>!XALL</code>
|
|-
|  
| a list of all element parts
|-
| <var>tag</var> || element tag name
|-
| <var>empty</var> || 1 if element data is empty, 0 otherwise
|-
| <var>cdata</var> || 1 if element data is a CData-section, 0 otherwise
|-
| <var>childs</var> || number of child elements
|-
| <var>size</var> || size of data section (characters)
|-
| <var>nattr</var> || number of attributes
|-
| <var>attr0</var>,… || name of attribute 0, … (0 to <var>nattr</var>-1)
|-
| <code>!XTAG</code>
|<nowiki>-</nowiki>
|element_tag
|-
| <code>!XATTRIBUTES</code>
|<nowiki>-</nowiki>
|number_of_attributes
|-
| <code>!XATTRIBUTE</code>
|<var>index</var>
|attribute_name name of attribute number <var>index</var>
|-
| <code>!XATTRIBUTE</code>
|<var>name</var>
|attribute_value value of attribute named <var>name</var>
|-
| <code>!XEMPTY</code>
|<nowiki>-</nowiki>
|returns 1 if element is empty (no data) and 0 otherwise
|-
| <code>!XCDATA</code>
|<nowiki>-</nowiki>
|returns 1 if element contains a CData section and 0 otherwise
|-
| <code>!XCHILDS</code> or <code>!XCHILDREN</code>
|<nowiki>-</nowiki>
|returns number of child elements of the selected element
|-
| <code>!XSIZE</code>
|<nowiki>-</nowiki>
|size of data section in characters
|-
| <code>!XDATA</code>
|<nowiki>-</nowiki>
|content of data section
|}

=== Document/element type definition attributes of an XML file item ===

{|class="einrahmen"
!Attribute<nowiki>-</nowiki>Id
!Sub<nowiki>-</nowiki>Id 1
!Sub<nowiki>-</nowiki>Id 2
!Value(s) and Description
|-
|<code>!XDTNAME</code>
|<nowiki>-</nowiki>
|<nowiki>-</nowiki>
|name of document type definition
|-
|<code>!XDTROOT</code>
|<nowiki>-</nowiki>
|<nowiki>-</nowiki>
|tag of root element
|-
|<code>!XDTELEMENTS</code>
|<nowiki>-</nowiki>
|<nowiki>-</nowiki>
|number of defined element types
|-
|<code>!XDTELEMENT</code>
|<var>index</var> or <var>tag</var>
|<nowiki>-</nowiki>
|definition of element type with specified index or tag; the result is
<code>tag parent base nobase data with</code>:
{|
! tag !! element tag
|-
|parent
|parent element tag or <code>*</code>
|-
|base
|base element tag or <code>*</code>
|-
|nobase
|nobase element tag or <code>*</code>
|-
|data
|data type name or <code>*</code>
|}
|-
|<code>!XDTCHILDREN</code>
|<var>tag</var>
|<nowiki>-</nowiki>
|number of children defined for element tag
|-
|<code>!XDTCHILD</code>
|<var>tag</var>
|cindex or ctag
|definition of child cindex or ctag of the element tag. The result is:ctag min maxwith:
{|
! ctag !! tag of child element
|-
|<var>min</var>
|number of minimum occurrences
|-
|<var>max</var>
|number of maximum occurrences or <nowiki>-</nowiki>1 if not defined
|}
|-
|<code>!XDTATTRIBUTES</code>
|<var>tag</var>
|<nowiki>-</nowiki>
|number of attributes defined for element tag
|-
|<code>!XTDATTRIBUTE</code>
|tag
|<var>aindex</var> or <var>aname</var>
|definition of attribute aindex or aname of element tag. The result is:aname req vis val type paramswith:
{|
! aname !! name of attribute
|-
|req
|required flag (0=no, 1=yes)
|-
|vis
|visibility flag (0=hidden, 1=value, 2=name and value)
|-
|val
|default value of * if not set
|-
|type
|attribute value type (<code>INTEGER</code>, <code>NUMBER</code>, <code>STRING</code>, <code>VALUELIST</code>)
|-
|params
|parameters, depends on type{|
|-
|<code>INTEGER</code>
|<code><var>minval</var><nowiki>|</nowiki>* <var>maxval</var><nowiki>|</nowiki>*</code>
|-
|<code>NUMBER</code>
|<code><var>minval</var><nowiki>|</nowiki>* <var>maxval</var><nowiki>|</nowiki>*</code>
|-
|<code>STRING</code>
|unique{0<nowiki>|</nowiki>1} respect{0<nowiki>|</nowiki>1}
|-
|<code>VALUELIST</code>
|<code>value1 value2 …</code>
|}
|-
| <code>!XDTISA</code>
| <var>tag</var>
| none
| returns <code>1</code> if the selected element of the file item is of type <var>tag</var> or is derived from <var>tag</var> and <code>0</code> otherwise
|}

Programmer Guide/BScript

2018-03-15T09:18:31Z

Toni: /* File I/O Functions */

{{DISPLAYTITLE:BScript - The runtime environment of Scripts}}
The {{STX}} application implements an environment for the development, debugging and execution of user scripts. It is used by the [[User_Guide/The_Script_Controller|Script Controller]] and the [[User_Guide/STX_Console|Console]] to load a script file and to test, debug or run a macro defined in this file. When the execution of the macro is finished, the script file is unloaded and the runtime environment is deleted.

The term ''script'' is a synonym for an application implemented using one or more [[Programmer_Guide/Introduction#Macros|macros]], [[Programmer_Guide/Introduction#Classes.2C_Instances|classes]] and [[Programmer_Guide/Shell_Items/SPU|SPU]]s. Scripts can be used to implement ...
* applying standard {{STX}} signal processing to multiple signals
* signal processing applications (like the {{Stx}} [[User_Guide/Spectrogram_and_Parameter_Viewer|Spectrogram & Parameters Viewer]])
* complex database operations on the opened {{STx}} project (e.g. using macro [[Programmer_Guide/Macro_Library/DATASETCMD|DataSetCmd]] and classes [[Programmer_Guide/Macro_Library/BDataSet|BDataSet]] and [[Programmer_Guide/Macro_Library/BSTXIni|BSTXIni]]
* a solution for the Towers of Hanoi problem
* in fact, everything you see in {{STX}} can be programmed in the scripting language
* in fact, everything you see in {{Stx}} ''is'' programmed in the scripting language

==Running a Script==
To run a script use the [[User_Guide/The_Script_Controller|Script Controller]] dialog to select/create a file, select the macro and supply arguments or the [[User_Guide/STX_Console|Console command <code>STS ''file''::''macro'' ''arguments'' /Run</code>. In both cases a new instance of the application <code>BScript</code> is started and the script file name, the macro name and the supplied arguments are passed to this instance. Before the execution of the script begins, following initialization steps are performed.

* The specified script file is loaded and it is tested, if the specified macro (called ''scriptmain'') is defined in the loaded file.
* All source files defined in the section ''[[Programmer_Guide/Source_code#Libraries|Libraries]]'' of the script file are loaded.
* The [[#Script environment|script environment]] is initialzed: Some informations about the script are stored in the shell variable space and an instance of the [[Programmer_Guide/Macro_Library/BScript|class BScript]] named CON is created. The member functions of this instance can be used show/hide the console window, to write informations to the console window and for some other purposes.
* The macro ''scriptmain'' is started.
** In the debug mode, the [[User_Guide/Debugger|debugger]] window is shown and the ''break mode'' is entered before the execution of ''scriptmain'' begins.

The user application implemented by ''scriptmain'' is active until this macro is finished, than the control is returned to the BScript application, which performs some cleanup steps:

* All shell items (tables, files, instances, spu's, ...) are deleted in a save way. For instances the destructor member function is called.
* If the variable '''AutoCloseSF''' equals '''1''': All soundfiles opened by the script are closed automatically.
** Note: To manage (create, open, close and select) soundfiles a script should always use the macro [[Programmer_Guide/Macro_Library/BSF|BSF]] instead of the commands [[Programmer_Guide/Command_Reference/LOAD|LOAD]] and [[Programmer_Guide/Command_Reference/UNLOAD|UNLOAD]].

==Script Environment==
All variables and items described here are assigned or created, before the script main macro is called.

These variables '''must not''' be changed:

;<code>ScriptDirectory</code>: the directory of the script file
;<code>ScriptFilePath</code>: the full path of the script file
;<code>ScriptFileName</code>: the name of the script file; only the name without directory and filetype
;<code>ScriptMainName</code>: the name of the script main macro
;<code>ScriptRevision</code>: the {{STX}} revision number used to create the script file; this value is undefined, if the script file was not created with the '''New''' function of the [[User_Guide/The_Script_Controller|Script Controller]] or the line containing this information was changed or removed
;<code>STXRevision</code>: the actual {{STX}} revision number of the running program

These variables can/should be set by the user script before the script main macro exits:

;<code>AutoCloseSF</code>: set this variable <code>1</code> if all sound files opened during the script execution should be closed automatically and to <code>0</code> if not (default: <code>0</code>)
;<code>ShowLogOnExit</code>: set this variable <code>1</code> if the console window should be shown when the script ends, <code>0</code> otherwise (default: <code>1</code>). If the console window shown, the user must close it manually.

Instance items:

;<code>CON</code> - instance of [[Programmer_Guide/Macro_Library/BScript|class BScript]]: this instance implements the console window and a set of useful utility functions.

;<code>'''$'''BSTXIni</code> - instance of [[Programmer_Guide/Macro_Library/BSTXIni|class BSTXIni]]: an interface object to access the workspace data; the name of the instance is stored in the shell variable BSTXIni

;<code>'''$'''BDataSet</code> - instance of [[Programmer_Guide/Macro_Library/BDataSet|class BDataSet]]: an interface object to access the project data; the name of the instance is stored in the shell variable BDataSet

* The items listed above are deleted automatically when the script application exits.
* Both instances $BSTXIni and $BDataSet are accessing global data objects which are (or may be) used by other currently running shells. To gurantee a save access to workspace and project data, the data must be locked to the script (shell) before read and/or write operations.

The following example shows a save way to use the project data. The functions used here are also available for the workspace interface instance.

...
if '$($bdataset attach)' == <nowiki>''</nowiki> then // lock the project-data
// LOCK failed! Its not possible to access the project-data now!
conlog /error 'lock project-data failed!' // write error message to the console window
// do something else but do not use the project-data!
...
else
// LOCK succeeded! Now its save to access project-data!
// use the $BDataSet instance members to access project-data
...
$bdataset detach // unlock project-data,
// this is necessary to make the project-data available to other shells
end
...

==Fuctions Implemented by BScript and CON==
The functions described below are available in the script runtime environment only. They implement some control and output functions for the Console window and some other useful functions.
:'''Note''': All functions described here, except the [[#Special Functions|special functions]] are also available in the command line of the [[User_Guide/STX_Console|Console]].

===Special Functions===
The functions listed below are used to prepare and unprepare the script runtime environment and there should be no necessity to use them in your script:

BSCRIPT LOAD ''filepath'' [ ; ''mainmacro'' ]
BSCRIPT UNLOAD
BSCRIPT VERSIONCHECK ''filepath'' [ ; ''showmsgbox'' ]

A description of these functions is only available in the source file <code>BScript.stx</code>

===Setup Functions===

BSCRIPT GETSETUPPATH [''subset''; ''empty'']
CON getSetupPath [''set''; ''empty'']

Returns the internal reference (iref) of the workspace set containing the script setup elements. This function can be used to save or load script parameters.
Arguments:
:''subset'': The relative reference to a sub-set of the standard setup-set (see example)
:''empty'': If this argument is set to <code>yes</code> or <code>1</code> the selected set or sub-set is emptied (this means all child elements and sets are deleted), otherwise nothing is deleted. This option can be used (carefully) to delete script settings.

'''Example 1''': load current/default script settings
<pre>
...
// lock the workspace before you load the current settings from the workspace
if '$($bstxini attach)' != '' then
// lock okay -> try to load settings from standard script-settings path
#currSetup := $bstxini loadsetelement 'Table; $ScriptMainName; $(con getsetuppath)'
// don't forget to unlock the workspace
$bstxini detach
end
// check if current settings are loaded
if '$#currSetup[?]' != table then
// load default settings from the section [DefaultSettings] of the script source file
// if current settings are not available
#currSetup := sectionfile '$ScriptFilePath ; Load * DefaultSettings'
end
// Th current/default settings are now stored in the simple table $#currSetup and can
// be accessed with the READTAB command or another table access method.
...
</pre>

'''Example 2''': save current script settings
<pre>
...
// lock the workspace before you save the current settings into the workspace
if '$($bstxini attach)' != '' then
// lock okay -> save settings to standard script-settings path
$bstxini SaveSetupElement '$#currSetup; 0 ; Table; $ScriptMainName; $(con getsetuppath)'
$bstxini detach
end
...
</pre>

===Console Window Functions===

CON logOpen
Open the Console window.

CON setTitle [''title'']
Set the caption of the Console window to ''title''. If no caption is specified, the default caption (<code>ScriptFilePath</code> and <code>ScriptMainName</code>) is used.

CON setWindow ''x y w h''
Set the position and size of the Console window.
:''x,y'': The upper left corner position of the window in pixels
:''w,h'': The width and height of the window in pixels.
For more details see macro [[Programmer_Guide/Macro_Library/SETWINDOWPOS|SetWindowPos]].

CON log [''textline'']
CON logText [''textline'']
Write one ''textline'' to the Console window.

CON logExt [''mode''=overwrite ; text]
Extended Console window log-function. The argument ''mode'' can be set to '''overwrite''', to overwrite the last line with ''text'', or to '''append''', to append ''text'' to the last line. This function is e.g. useful to show the progress of a (longer lasting) script process.

CON eLog ''level'' ; [''result''] ; ''textline''
Write the error|exit message ''textline'' to the Console window and execute the return command [[Programmer_Guide/Command_Reference/EXIT|<code>EXIT ''level'' SET <nowiki>'</nowiki>''result''<nowiki>'</nowiki></code>]]. This function is a simple way, to show a text message when returning from a macro.

Example:
con elog 2; 1; the return value of "$#mac" is "1" // show the message and return 1 to the caller of '''$#mac'''

CON cls
CON logClear
Clear the Console window.

CON logClose
Close the Console window.

===File I/O Functions===

CON loadData ''textmode''; ''filepath'' [; ''colsep''=blank; ''header''=0; ''skiplines''=0; ''loadlines''=*]
This function loads numerical data tables or string data tables from the specified text file ''filepath''. The result of the function is a [[Programmer_Guide/Shell_Items/Table/Introducing_Table_Items#Parameter_Table|parameter table item]] or an [[Programmer_Guide/Shell_Items/Table/Introducing_Table_Items#Extended_Table|extended table]] containing the loaded data or an empty string if the function failes.
:<code>''textmode''</code>:
::* '''text''' for numerical text files; use '''textcontinuation''' if the text file may contain [[Programmer_Guide/Source_code#Escape_and_Continuation_Character|continuation lines]]
::* '''string''' for normal text files; '''stringcontinuation''' if the text file may contain [[Programmer_Guide/Source_code#Escape_and_Continuation_Character|continuation lines]]
:<code>''filepath''</code>: the path of the file containing the data to be loaded
:<code>''colsep''</code>: the column seperator: '''blank''', '''tab''', '''comma''' or '''semicolon'''
:<code>''header''</code>: If set to '''yes''' (or '''1'''), the first line of the file is interpreted as header-line, and the value of each header column is used as name for the corresponding table field. Otherwise, no header-line is assumed and the table fields are not named.
:<code>''skiplines''</code>: number of file lines to be skipped (not stored in the table)
:<code>''loadlines''</code>: number of file lines to be loaded; use the character '''*''' (=default) to load the whole file

CON loadData '''binary'''; ''filepath'' [; ''combine''=0; ''sec1'' [''mv1'']; ...]
Load the specified sections (''sec1'', ..) of the [[Programmer_Guide/Shell_Items/File/Introducing_File_Items#Binary_Files|binary file]] ''filepath''. If ''combine'' is set to '''yes''' (or '''1''') the loaded data are combined into one parameter table, otherwise for each section one parameter table is used. The result of this function is a blank seperated list of parameter table items (''combine''=0), one parametr table item (''combine''=1 or only one section was specified) or an empty sting if the function failes. The missing value (mv1, ..) parameter, which can be specified for each section separately, is only necessary if multiple sections are combined into one table. In this the missing value parameters are passed to the function [[Programmer_Guide/Command_Reference/EVAL/interp|eval interp()], which is used to allign all data to the same length.

CON saveData '''text'''|'''ascii'''; ''table''; ''filepath'' [; ''header''=0; ''colsep''=blank; ''decsym''=DOT; ''floatfmt''=%g; ''intfmt''=%g]
Save the parameter or extended table ''table'' into the text file ''filepath''.
:<code>''header''</code>: If set to '''yes''' (or '''1'''), field names of the table are stored in the first line of the text file. Otherwise, no header-line is stored in the file.
:<code>''colsep''</code>: the column seperator: '''blank''', '''tab''', '''comma''' or '''semicolon'''
:<code>''decsym''</code>: the decimal symbol to be used for floating point numbers: '''dot''' or '''comma'''
:<code>''floatfmt''</code>: the format of floating point numbers; any valid float/double C-format string (e.g.: %g, %.2f, ...)
:<code>''intfmt''</code>: the format of integer numbers; any valid float/double C-format string (e.g.: %.0f, ...)

CON saveData '''text'''|'''ascii'''; ''table''; CLIPBOARD [; ''header''=0; ''colsep''=blank; ''decsym''=DOT; ''floatfmt''=%g; ''intfmt''=%g; ''fieldlist'']
Copy the parameter or extended table ''table'' to the clipboard. All arguments have the same meaning as for the file output. In the extra argument ''fieldlist'' a blank seperated list of table field-ids which should be copied ca be specified. If this argument is not supplied, all fields are copied.

For example, the command <code>con savedata text; ''datatable''; clipboard; yes; semicolon; comma</code> can be used to copy the ''datatable'' to the clipboard, from where it can be pasted into a spreadsheet application.

CON saveDataDlg ''table'' [; ''trans''=no; ''title''=Save Table; ''colsep''=blank; ''decsym''=dot; ''header''=no; ''floatfmt''=%g; ''intfmt''=%d]
This function displays a dialog where the arguments of the <code>saveData</code> functions can be entered.

Programmer Guide/BScript

2018-03-15T09:16:36Z

Toni: /* File I/O Functions */

{{DISPLAYTITLE:BScript - The runtime environment of Scripts}}
The {{STX}} application implements an environment for the development, debugging and execution of user scripts. It is used by the [[User_Guide/The_Script_Controller|Script Controller]] and the [[User_Guide/STX_Console|Console]] to load a script file and to test, debug or run a macro defined in this file. When the execution of the macro is finished, the script file is unloaded and the runtime environment is deleted.

The term ''script'' is a synonym for an application implemented using one or more [[Programmer_Guide/Introduction#Macros|macros]], [[Programmer_Guide/Introduction#Classes.2C_Instances|classes]] and [[Programmer_Guide/Shell_Items/SPU|SPU]]s. Scripts can be used to implement ...
* applying standard {{STX}} signal processing to multiple signals
* signal processing applications (like the {{Stx}} [[User_Guide/Spectrogram_and_Parameter_Viewer|Spectrogram & Parameters Viewer]])
* complex database operations on the opened {{STx}} project (e.g. using macro [[Programmer_Guide/Macro_Library/DATASETCMD|DataSetCmd]] and classes [[Programmer_Guide/Macro_Library/BDataSet|BDataSet]] and [[Programmer_Guide/Macro_Library/BSTXIni|BSTXIni]]
* a solution for the Towers of Hanoi problem
* in fact, everything you see in {{STX}} can be programmed in the scripting language
* in fact, everything you see in {{Stx}} ''is'' programmed in the scripting language

==Running a Script==
To run a script use the [[User_Guide/The_Script_Controller|Script Controller]] dialog to select/create a file, select the macro and supply arguments or the [[User_Guide/STX_Console|Console command <code>STS ''file''::''macro'' ''arguments'' /Run</code>. In both cases a new instance of the application <code>BScript</code> is started and the script file name, the macro name and the supplied arguments are passed to this instance. Before the execution of the script begins, following initialization steps are performed.

* The specified script file is loaded and it is tested, if the specified macro (called ''scriptmain'') is defined in the loaded file.
* All source files defined in the section ''[[Programmer_Guide/Source_code#Libraries|Libraries]]'' of the script file are loaded.
* The [[#Script environment|script environment]] is initialzed: Some informations about the script are stored in the shell variable space and an instance of the [[Programmer_Guide/Macro_Library/BScript|class BScript]] named CON is created. The member functions of this instance can be used show/hide the console window, to write informations to the console window and for some other purposes.
* The macro ''scriptmain'' is started.
** In the debug mode, the [[User_Guide/Debugger|debugger]] window is shown and the ''break mode'' is entered before the execution of ''scriptmain'' begins.

The user application implemented by ''scriptmain'' is active until this macro is finished, than the control is returned to the BScript application, which performs some cleanup steps:

* All shell items (tables, files, instances, spu's, ...) are deleted in a save way. For instances the destructor member function is called.
* If the variable '''AutoCloseSF''' equals '''1''': All soundfiles opened by the script are closed automatically.
** Note: To manage (create, open, close and select) soundfiles a script should always use the macro [[Programmer_Guide/Macro_Library/BSF|BSF]] instead of the commands [[Programmer_Guide/Command_Reference/LOAD|LOAD]] and [[Programmer_Guide/Command_Reference/UNLOAD|UNLOAD]].

==Script Environment==
All variables and items described here are assigned or created, before the script main macro is called.

These variables '''must not''' be changed:

;<code>ScriptDirectory</code>: the directory of the script file
;<code>ScriptFilePath</code>: the full path of the script file
;<code>ScriptFileName</code>: the name of the script file; only the name without directory and filetype
;<code>ScriptMainName</code>: the name of the script main macro
;<code>ScriptRevision</code>: the {{STX}} revision number used to create the script file; this value is undefined, if the script file was not created with the '''New''' function of the [[User_Guide/The_Script_Controller|Script Controller]] or the line containing this information was changed or removed
;<code>STXRevision</code>: the actual {{STX}} revision number of the running program

These variables can/should be set by the user script before the script main macro exits:

;<code>AutoCloseSF</code>: set this variable <code>1</code> if all sound files opened during the script execution should be closed automatically and to <code>0</code> if not (default: <code>0</code>)
;<code>ShowLogOnExit</code>: set this variable <code>1</code> if the console window should be shown when the script ends, <code>0</code> otherwise (default: <code>1</code>). If the console window shown, the user must close it manually.

Instance items:

;<code>CON</code> - instance of [[Programmer_Guide/Macro_Library/BScript|class BScript]]: this instance implements the console window and a set of useful utility functions.

;<code>'''$'''BSTXIni</code> - instance of [[Programmer_Guide/Macro_Library/BSTXIni|class BSTXIni]]: an interface object to access the workspace data; the name of the instance is stored in the shell variable BSTXIni

;<code>'''$'''BDataSet</code> - instance of [[Programmer_Guide/Macro_Library/BDataSet|class BDataSet]]: an interface object to access the project data; the name of the instance is stored in the shell variable BDataSet

* The items listed above are deleted automatically when the script application exits.
* Both instances $BSTXIni and $BDataSet are accessing global data objects which are (or may be) used by other currently running shells. To gurantee a save access to workspace and project data, the data must be locked to the script (shell) before read and/or write operations.

The following example shows a save way to use the project data. The functions used here are also available for the workspace interface instance.

...
if '$($bdataset attach)' == <nowiki>''</nowiki> then // lock the project-data
// LOCK failed! Its not possible to access the project-data now!
conlog /error 'lock project-data failed!' // write error message to the console window
// do something else but do not use the project-data!
...
else
// LOCK succeeded! Now its save to access project-data!
// use the $BDataSet instance members to access project-data
...
$bdataset detach // unlock project-data,
// this is necessary to make the project-data available to other shells
end
...

==Fuctions Implemented by BScript and CON==
The functions described below are available in the script runtime environment only. They implement some control and output functions for the Console window and some other useful functions.
:'''Note''': All functions described here, except the [[#Special Functions|special functions]] are also available in the command line of the [[User_Guide/STX_Console|Console]].

===Special Functions===
The functions listed below are used to prepare and unprepare the script runtime environment and there should be no necessity to use them in your script:

BSCRIPT LOAD ''filepath'' [ ; ''mainmacro'' ]
BSCRIPT UNLOAD
BSCRIPT VERSIONCHECK ''filepath'' [ ; ''showmsgbox'' ]

A description of these functions is only available in the source file <code>BScript.stx</code>

===Setup Functions===

BSCRIPT GETSETUPPATH [''subset''; ''empty'']
CON getSetupPath [''set''; ''empty'']

Returns the internal reference (iref) of the workspace set containing the script setup elements. This function can be used to save or load script parameters.
Arguments:
:''subset'': The relative reference to a sub-set of the standard setup-set (see example)
:''empty'': If this argument is set to <code>yes</code> or <code>1</code> the selected set or sub-set is emptied (this means all child elements and sets are deleted), otherwise nothing is deleted. This option can be used (carefully) to delete script settings.

'''Example 1''': load current/default script settings
<pre>
...
// lock the workspace before you load the current settings from the workspace
if '$($bstxini attach)' != '' then
// lock okay -> try to load settings from standard script-settings path
#currSetup := $bstxini loadsetelement 'Table; $ScriptMainName; $(con getsetuppath)'
// don't forget to unlock the workspace
$bstxini detach
end
// check if current settings are loaded
if '$#currSetup[?]' != table then
// load default settings from the section [DefaultSettings] of the script source file
// if current settings are not available
#currSetup := sectionfile '$ScriptFilePath ; Load * DefaultSettings'
end
// Th current/default settings are now stored in the simple table $#currSetup and can
// be accessed with the READTAB command or another table access method.
...
</pre>

'''Example 2''': save current script settings
<pre>
...
// lock the workspace before you save the current settings into the workspace
if '$($bstxini attach)' != '' then
// lock okay -> save settings to standard script-settings path
$bstxini SaveSetupElement '$#currSetup; 0 ; Table; $ScriptMainName; $(con getsetuppath)'
$bstxini detach
end
...
</pre>

===Console Window Functions===

CON logOpen
Open the Console window.

CON setTitle [''title'']
Set the caption of the Console window to ''title''. If no caption is specified, the default caption (<code>ScriptFilePath</code> and <code>ScriptMainName</code>) is used.

CON setWindow ''x y w h''
Set the position and size of the Console window.
:''x,y'': The upper left corner position of the window in pixels
:''w,h'': The width and height of the window in pixels.
For more details see macro [[Programmer_Guide/Macro_Library/SETWINDOWPOS|SetWindowPos]].

CON log [''textline'']
CON logText [''textline'']
Write one ''textline'' to the Console window.

CON logExt [''mode''=overwrite ; text]
Extended Console window log-function. The argument ''mode'' can be set to '''overwrite''', to overwrite the last line with ''text'', or to '''append''', to append ''text'' to the last line. This function is e.g. useful to show the progress of a (longer lasting) script process.

CON eLog ''level'' ; [''result''] ; ''textline''
Write the error|exit message ''textline'' to the Console window and execute the return command [[Programmer_Guide/Command_Reference/EXIT|<code>EXIT ''level'' SET <nowiki>'</nowiki>''result''<nowiki>'</nowiki></code>]]. This function is a simple way, to show a text message when returning from a macro.

Example:
con elog 2; 1; the return value of "$#mac" is "1" // show the message and return 1 to the caller of '''$#mac'''

CON cls
CON logClear
Clear the Console window.

CON logClose
Close the Console window.

===File I/O Functions===

CON loadData ''textmode''; ''filepath'' [; ''colsep''=blank; ''header''=0; ''skiplines''=0; ''loadlines''=*]
This function loads numerical data tables or string data tables from the specified text file ''filepath''. The result of the function is a [[Programmer_Guide/Shell_Items/Table/Introducing_Table_Items#Parameter_Table|parameter table item]] or an [[Programmer_Guide/Shell_Items/Table/Introducing_Table_Items#Extended_Table|extended table]] containing the loaded data or an empty string if the function failes.
:<code>''textmode''</code>: '''text''' for normal text files and '''textcontinuation''' if the text file may contain [[Programmer_Guide/Source_code#Escape_and_Continuation_Character|continuation lines]]
:<code>''filepath''</code>: the path of the file containing the data to be loaded
:<code>''colsep''</code>: the column seperator: '''blank''', '''tab''', '''comma''' or '''semicolon'''
:<code>''header''</code>: If set to '''yes''' (or '''1'''), the first line of the file is interpreted as header-line, and the value of each header column is used as name for the corresponding table field. Otherwise, no header-line is assumed and the table fields are not named.
:<code>''skiplines''</code>: number of file lines to be skipped (not stored in the table)
:<code>''loadlines''</code>: number of file lines to be loaded; use the character '''*''' (=default) to load the whole file

CON loadData '''binary'''; ''filepath'' [; ''combine''=0; ''sec1'' [''mv1'']; ...]
Load the specified sections (''sec1'', ..) of the [[Programmer_Guide/Shell_Items/File/Introducing_File_Items#Binary_Files|binary file]] ''filepath''. If ''combine'' is set to '''yes''' (or '''1''') the loaded data are combined into one parameter table, otherwise for each section one parameter table is used. The result of this function is a blank seperated list of parameter table items (''combine''=0), one parametr table item (''combine''=1 or only one section was specified) or an empty sting if the function failes. The missing value (mv1, ..) parameter, which can be specified for each section separately, is only necessary if multiple sections are combined into one table. In this the missing value parameters are passed to the function [[Programmer_Guide/Command_Reference/EVAL/interp|eval interp()], which is used to allign all data to the same length.

CON saveData '''text'''|'''ascii'''; ''table''; ''filepath'' [; ''header''=0; ''colsep''=blank; ''decsym''=DOT; ''floatfmt''=%g; ''intfmt''=%g]
Save the parameter or extended table ''table'' into the text file ''filepath''.
:<code>''header''</code>: If set to '''yes''' (or '''1'''), field names of the table are stored in the first line of the text file. Otherwise, no header-line is stored in the file.
:<code>''colsep''</code>: the column seperator: '''blank''', '''tab''', '''comma''' or '''semicolon'''
:<code>''decsym''</code>: the decimal symbol to be used for floating point numbers: '''dot''' or '''comma'''
:<code>''floatfmt''</code>: the format of floating point numbers; any valid float/double C-format string (e.g.: %g, %.2f, ...)
:<code>''intfmt''</code>: the format of integer numbers; any valid float/double C-format string (e.g.: %.0f, ...)

CON saveData '''text'''|'''ascii'''; ''table''; CLIPBOARD [; ''header''=0; ''colsep''=blank; ''decsym''=DOT; ''floatfmt''=%g; ''intfmt''=%g; ''fieldlist'']
Copy the parameter or extended table ''table'' to the clipboard. All arguments have the same meaning as for the file output. In the extra argument ''fieldlist'' a blank seperated list of table field-ids which should be copied ca be specified. If this argument is not supplied, all fields are copied.

For example, the command <code>con savedata text; ''datatable''; clipboard; yes; semicolon; comma</code> can be used to copy the ''datatable'' to the clipboard, from where it can be pasted into a spreadsheet application.

CON saveDataDlg ''table'' [; ''trans''=no; ''title''=Save Table; ''colsep''=blank; ''decsym''=dot; ''header''=no; ''floatfmt''=%g; ''intfmt''=%d]
This function displays a dialog where the arguments of the <code>saveData</code> functions can be entered.

Programmer Guide/Macro Library/CONLOG

2018-03-15T08:37:29Z

Toni:

{{DISPLAYTITLE:ConLog - Write messages to the Console and/or the Log-window}}
CONLOG [<var>line1</var> [<var>line2</var> ..]] [ <var>options</var> ]
:Write the specified text-lines (<var>line1</var>, ...) to the [[User_Guide/STX_Console|Console window]] and/or the [[User_Guide/Log_Window|Log-window]]. This function can be used by scripts to write error- and progress-information to the Console. It

{|class="einrahmen"
!argument !!description
|-
|<var>line1</var>, <var>line2</var>, ...
|The text lines to be written to the window(s).
|-
!option !!description !!default
|-
|<code>/Noconsole</code>
|Output only to the Log-window and not to the Console window.
|-
|<code>/Shell</code>
|Write the prefix <code>''appid'':''currtime'' - </code> before each text line. Where ''appid'' is the value of variable <code>AppName</code> and ''currtime'' is the current time (hh.mm.ss).
|-
|<code>/Error</code>
|Write the prefix <code>Error! - </code> before each text line.
|-
|<code>/Warning</code>
|Write the prefix <code>Warning! - </code> before each text line.
|-
|<code>/X</code> <code>/X=</code><var>n
|Exit from <var>n</var> macro levels. If <code>/X</code> (eXit) is supplied without a number, the number of levels <var>n</var> is set to 2 (return to caller).
(see command [[Programmer_Guide/Command_Reference/EXIT|<code>EXIT</code>]] for details)
|-
|<code>/Ton</code>
|Turn timer on. If timer is already active, the elapsed time (since timer was started) is displayed.
|-
|<code>/Toff</code>
|Turn timer off (if active) and display elapsed time (since timer was started).
|-
|<code>/Result</code> <code>Result=</code><var>res</var>
|With this option the result value to be returned with the /X option can be specified. If the value <var>res</var> is not supplied, an empty string (<nowiki>''</nowiki>) is returned.
|-
|<code>/Progress</code>
|If this option is supplied, '''all other options are ignored''' and the text is written to the Console window only. The first line is written with the '''overwrite''' mode, this means the text <var>line1</var> replaces the last output line.
|-
|<code>/File=</code><var>x</var>
|Appends the text lines to the file with path <var>x</var> (opened temporary in text-append mode) or to the fileitem <var>x</var> (if <var>x</var> is the id of a textfileitem)
|-
!RESULT !!description
|-
|''undefined'' || if <code>/X</code> is not supplied
|-
|'<var>res</var>' or <nowiki>''</nowiki> || if <code>/X</code> is supplied; the value is returned to the macro selected by the level <var>n</var> specified with the option <code>/X</code>.
|}

;See also:
[[../LOGWINDOW|LogWindow]], [[../UM|UM and EM]], [[../BUTIL#MsgBox|MsgBox]]

Programmer Guide/Command Reference/EVAL/ydiff

2018-03-09T08:09:39Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
Calculates the differentiation (differnce quotients) of the vector ''y'' = f(''x'').
----
;Usage 1: <code>ydiff(<var>yvector</var> {, <var>dxscalar</var>=1})</code>
;Result 1: The result is the vector ''r'' with <code>nrow(''y'')-1</code>elements.
::<code>''r''[i]=(''y''[i+1]-''y''[i])/dx; with: i=0..nrow(''y'')-2</code>
----
;Usage 2: <code>ydiff(<var>yvector</var>, <var>xvector</var>)</code>
;Result 2: The result is the vector ''r'' with <code>nrow(''y'')-1</code>elements.
::<code>''r''[i]=(''y''[i+1]-''y''[i])/(''x''[i+1]-''x''[i]); with: i=0..nrow(''y'')-2</code>
----
;Usage 3: <code>ydiff(<var>knumber</var>, <var>xvector</var>)</code>
;Result 3: The result is the vector ''r'' with <code>nrow(''y'')-1</code>elements. This version is normally used for signal differentiation (with: 0 ≤ <var>knumber</var> ≤ 1).
::<code>''r''[i]=''x''[i+1]-''k''.''x''[i]; with: i=0..nrow(''y'')-2</code>

;See also: [[../yint|yint]]

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

Programmer Guide/Command Reference/EVAL/ydiff

2018-03-09T08:09:18Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
Calculates the differentiation (differnce quotients) of the vector ''y'' = f(''x'').
----
;Usage 1: <code>ydiff(<var>yvector</var> {, <var>dxscalar</var>=1})</code>
;Result 1: The result is the vector ''r'' with <code>nrow(''y'')-1</code>elements.
::<code>''r''[i]=(''y''[i+1]-''y''[i])/dx; with: i=0..nrow(''y'')-2</code>
----
;Usage 2: <code>ydiff(<var>yvector</var>, <var>xvector</var>)</code>
;Result 2: The result is the vector ''r'' with <code>nrow(''y'')-1</code>elements.
::<code>''r''[i]=(''y''[i+1]-''y''[i])/(''x''[i+1]-''x''[i]); with: i=0..nrow(''y'')-2</code>
----
;Usage 3: <code>ydiff(<var>knumber</var>, <var>xvector</var>)</code>
;Result 3: The result is the vector ''r'' with <code>nrow(''y'')-1</code>elements. This version is normally used for signal differentiation (with: 0 ≤ <var>knumber</var> ≤ 1).
::<code>''r''[i]=''x''[i+1]-''k''.''y''[i]; with: i=0..nrow(''y'')-2</code>

;See also: [[../yint|yint]]

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

Programmer Guide/Command Reference/EVAL/ydiff

2018-03-09T08:08:51Z

Toni:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
Calculates the differentiation (differnce quotients) of the vector ''y'' = f(''x'').
----
;Usage 1: <code>ydiff(<var>yvector</var> {, <var>dxscalar</var>=1})</code>
;Result 1: The result is the vector ''r'' with <code>nrow(''y'')-1</code>elements.
::<code>''r''[i]=(''y''[i+1]-''y''[i])/dx; with: i=0..nrow(''y'')-2</code>
----
;Usage 2: <code>ydiff(<var>yvector</var>, <var>xvector</var>)</code>
;Result 2: The result is the vector ''r'' with <code>nrow(''y'')-1</code>elements.
::<code>''r''[i]=(''y''[i+1]-''y''[i])/(''x''[i+1]-''x''[i]); with: i=0..nrow(''y'')-2</code>
----
;Usage 3: <code>ydiff(<var>knumber</var>, <var>xvector</var>)</code>
;Result 3: The result is the vector ''r'' with <code>nrow(''y'')-1</code>elements. This version is normally used for signal differentiation (with: 0 ≤ <var>knumber</var> &le 1).
::<code>''r''[i]=''x''[i+1]-''k''.''y''[i]; with: i=0..nrow(''y'')-2</code>

;See also: [[../yint|yint]]

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