STX Wiki - User contributions [en]

History of Changes

2026-04-21T08:45:54Z

Jw: /* Downloads */

<div class="noautonum">{{TOC limit|3}}</div>
=5.0=

==Features==

===Compact Workspace Mode===
The Workspace now has a [[User_Guide/Workspace#Modes|compact mode]]. The compact mode is a simplified interface for new users. Although it was designed with linguists in mind, it can be used by anyone.

===webMAUS===
Automatic segmentation using the [https://clarin.phonetik.uni-muenchen.de/BASWebServices/interface webMAUS] REST API. This has been implemented in the toolbox [[User_Guide/Toolbox/runMAUSBasicDlg|<samp>runMAUSBasicDlg</samp>]].

==Bugfixes==

* Correctly handle corrupt Workspace file (generate new one, rather than silently exiting)

==5.0.6==

Released: 30th December 2020

Revision: 10071

* bugfix: No longer dying with "The parameter is incorrect" error

==5.0.4==

Released: 12th November 2019

Revision: 10016

* bugfix: SPExL V1.1.11. Adding new segments respects vertical drawing order.
* bugfix: SPExL V1.1.11. Faster deselection of segments.
* bugfix: Real-time waterfall axis drawing correctly
* bugfix: show/hide sectioner setting now respected.
* bugfix: sectioner height setting now respected.

==5.0.3==

Released: 1st October 2019

Revision: 9967

* feature: Signal.All is now selected by default, if no other segment is selected.
* feature: When exporting profiles, the present working directory is used, rather than always selecting the 'profiles' directory. The profiles directory is only used if the present working directory is the root directory.
* feature: The first sound file in the project is selected by default in the compact mode.
* bugfix: When adding a file per drag and drop, the file is now selected.
* bugfix: enabling a disabled edit box now sets the background color correctly (back to white).
* bugfix: debugger trace window now visible in release version too
* bugfix: [[Programmer_Guide/Command_Reference/SYSINFO|SYSINFO]] command now supports Windows 8.1 and Windows 10 (was returning Windows 8)
* bugfix: SPExL V1.1.10. Playlist listview now processes listsorted message and displays sort order set by clicking a column heading. The sort order was first being displayed when clicking in the control after clicking the column heading.
* bugfix: The 'Start' button should now be activated correctly in the Compact Mode.

==5.0.2==

Released: 19th September 2019

Revision: 9946

* bugfix: The context menu Add Sound File now working from the Audio File list in the Compact Mode.
* feature: The possible number of plots in XPlot was increased from 64 to 128

==5.0.0==

Released: 12th September 2019

Revision: 9935

Initial release.

=4.4=

==Features==
===Transcription Script SPExL 1.1.6===
The transcription script SPExL has been simplified and improved.
* Hotkeys can be defined by the user in the SPExL_SegTrans.hotkeys file
* The number of available 'views' has been reduced to 3:
** wave overview & spg. section (a waveform of the whole file in the top graph, with a section of the file as spectrogram below)
** wave only (a waveform of a section of the file with scrollbar functionality)
** wave and spg. section (a synced waveform and spectrogram of a section of the file with scrollbar functionality)
* Segment selection between graphs and the list are now synchronised. If you select a segment in the graph, it is selected in the list and vice versa.
* Changes made to the project (new segments, edited attributes) are now made directly in the project rather than the user having to explicitly press the 'save segments to project file' button to copy them from SPExL to the Workspace. Note that they are only written to disk, however, if the project is saved (press the 'Save' button).
===Visible Segment Attributes Saved per Project File===
If you choose to display other attributes other than the default attributes in the Workspace Detail View, these settings are now saved in the open project file. When a project file is then opened, the relevant attribute list is loaded and used, rather than the user having to [[User_Guide/Workspace/Detail/Search_for_Element_Attributes|search for them]] again. You can still modify which attributes are displayed using the General Settings [[User_Guide/Workspace/Application_and_Setup_Tree/Options/General_Settings#.22Set.22_Attributes_.26_.22Segment.22_Attributes|'Select "Segment" Attributes' dialog]].
===Global / Profile Sectioner Settings===
The sectioner settings in the {{Viewer2}} analysis application were always global to STx. As of STx 4.4.0, you can choose to save your sectioner settings with your profile. The default is still the 'global' variant. To switch to profile sectioner settings, uncheck the '''use global sectioner settings''' checkbox in the {{Viewer2}} [[User_Guide/Spectrogram_and_Parameter_Viewer/Settings_Dialog|settings dialog]].

==4.4.10==

Released: 17th January 2019

Revision: 9712

* bugfix: playback gain factor - the playback gain is now working also for asio devices (see CSTXASIOEngine::Transfer())
* bugfix: renumbering command did not update detail as expected.
* bugfix: the update version dialogs now display the correct workspace path

==4.4.9==

Released: 25th September 2018

Revision:

* feature: don't ask user where to put sound file if there are no sets in the project.
* feature: dragging and dropping a template onto {{ST}X} copies it to the templates folder.
* feature: added 'Open Containing Folder' context menu for sound files and links. Improved contextualisation of context menu in detail (overview==root/set)
* feature: 'txt2wav' script: Adding decimal symbol and field delimiter to parameters, as well as the ability to specify which extension to use to filter files (was hard-coded to 'txt'). Now this macro can be used to
* feature: bdataset createwave and createwwaveex now take an openmode keyword: auto|create|read|write, which is passed on to bsf open. This means that we can now open files in modes other than 'auto'.
process CSV files.
* bugfix: very long capture text for edit controls with 'text above' could lead to capture static being longer than the edit control and unintentionally overlapping with other controls (e.g. in Transcription Setup dialog).
* bugfix: closing con log window no longer resets PARENT shell variable, unless it is set the the con log window itself.
* bugfix: sound files now opened using the FILE_SHARE_READ dwShareMode. This should mean, that STx no longer prevents other processes from reading the sound files.
* bugfix: viewer opens sound file in read mode, rather than read/write.
* bugfix: the !PATH attribute (MakePath()) now returns the correct path for files in the root of a drive. Bug was introduced in r8998 (STx 4.2.19). This was, for example, was causing sound files in the root directory not to be unloaded, and hence was causing sharing violations.

==4.4.8==

Released: 25th July 2018

Revision: 9500

* feature: Spectrogram & Parameters viewer sectioner window now remembers which function cursor is bound to when being replotted.
* feature: The <samp>downsampling.sts</samp> script now has a <samp>ResampleCLI</samp> macro for automatic resampling of one or more files (see source). The old <samp>ResampleDialog</samp> was renamed to <samp>ResampleDLG</samp>.
* feature: Adding help for "Import_PRAAT_TextGrid" toolbox.
* feature: Adding ability to edit 'Sectioner Settings' from the profile dialog.
* feature: Transcription 1.1.8 - removed segment 'refresh' button, since segments always reflect current project state.
* bugfix: a window that was maximised will now be maximised to the correct monitor. It was always being maximised to monitor 1 on display creation.
* bugfix: the profile version number is now imported with the profile. This means that, for example, the use global profile settings flag is now also set correctly on import.
* bugfix: minor fix of position of two controls which were overlapping with controls beneath
* bugfix: stop playback cursor if wave is stopped by starting playback in another graph. Beforehand, the playback cursor was stopped if it got to the end, or the ESC key was pressed.
* bugfix: Y coordinate vector conversion was inaccurate by 1 pixel (bug introduced in r2536) This affects the XY, parameter, scatter, wave and waterfall functions.

==4.4.6==

Released: 21. March 2018

Revision: 9441

* bugfix: some bugfixes and minor changes in BSeq
* bugfix: BScript: logging of unhandled messages in msg-loop disabled // Conlog: /ton and /toff options implemented (timer on/off + show elapsed time)
* bugfix: Viewer3 settings now being saved (bug introduced in r9318 - STx 4.4.0)
* bugfix CShellFile::Status() - catch CTime exception if file time is illegal (avoid program crash)

==4.4.5==

Released: 19. February 2018

Revision: 9416

* bugfix: in Viewer2 large asegtemplates (with many fields) are now displayed correctly - note: the same problem exists in Viewer1 if the segment dialog part (created by the macro call ""metasegment msdialog") needs more than 90 controls (around 40 segment attributes)
* feature: the bscript.stx function loaddata (con loaddata) can now also load string tables (extenden tables) from csv-files. The file types TEXT/TEXTCONTINUATION (numeric parameter table), STRING/STRINCONTINUATION (extended string table) and BINARY (binary stx-data files) are available. Type ASCII/ASCIICONTINUATION has been removed.
* feature: new feature (bugfix?): CShellTable::Read() - handling of field-separator tab has been changed - empty fields are now possible - warning: may have an effect on existing script/macro code!

==4.4.4==

Released: 26. January 2018

Revision: 9404

* bugfix: combobox entries with underliners retain their underliners now in the workspace detail (reported by Anton Baotic), and in Spexl.

==4.4.3==

Released: 18. December 2017

Revision: 9391

* bugfix: adding missing Transcription hotkey file and retisimo scripts

==4.4.2==

Released: 30. November 2017

Revision: 9377

* bugfix: SPExL Transcription script V1.1.7: the /U ASegTemplate flag is now respected, and, if used, the last entered value for a segment attribute is used as the default for the next new segment.
* bugfix: default profile names no longer have the invalid blank character in them. A check was also added, so new profiles cannot be created with blanks.

==4.4.1==

Released: 23. November 2017

Revision: 9369

* bugfix: if zooming is turned off in {{Viewer2}}, segments are now correctly visible on the Y axis. This bug has existed since at least STx 4.2.

==4.4.0==

Released: 14 November 2017

Revision: 9350

Initial release.

=4.3=

==Features==
====Load or export parameters from super or sub segments====
Parameters from super segments or from sub segments can now be loaded into the selected segment. For example, if you have analysed a word and corrected the parameters, you can use these corrected parameters when viewing phoneme segments within the word. This is achieved by selecting 'super segment data only' setting in the Viewer settings [[User_Guide/Spectrogram_and_Parameter_Viewer/Settings_Dialog#Parameter_IO_Configuration|Parameter IO Configuration]] dialog.

It is possible to select which super/sub segment parameters should be used, filtering by time, attribute or ID.

This feature is also available in the parameter export dialog.

====Parameter setting summary====
A summary of the settings used for parameter analysis is now saved with the parameter in the project file. This information is displayed in the [[User_Guide/Workspace/Detail/Views/Parameter_View|Parameter View]].

====Exact sample positioning in {{Viewer2}}====

You can now select a position in the [[User_Guide/Spectrogram_and_Parameter_Viewer#Waveform_zoom_window|Waveform Zoom window]] in {{Viewer2}} and move the active time cursor to that position using the hotkey '1'. This is useful for exact positioning of the time cursors when segmenting, for example, words.

==4.3.10==

Released: 26. January 2018

Revision: 9407
*bugfix: do not allow user to give a profile a name including blanks.
*bugfix: renaming spectrum profiles (removing blanks)
*bugfix: the correct most recently entered value in a listctrl is now saved (not the last in the list).
*bugfix: passing delete, insert and back keys to static control.
*bugfix: 'spexl*.hotkeys.default' 'retisimo.sts' 'retisimo_*.sts' 'HRTF_II_new.txt' 'downsample.sts' files are now being copied too (bug introduced in r8789)
*bugfix: removing extraneous / from Editing segments help URL
*bugfix: combobox entries with underliners retain their underliners now in the workspace detail (reported by Anton Baotic), and in Spexl.

==4.3.9==

Released: 23. November 2017

Revision: 9363

* bugfix: if zooming is turned off in {{Viewer2}}, segments are now correctly visible on the Y axis. This bug has existed since at least STx 4.2.

==4.3.8==

Released: 14. November 2017

Revision: 9347

* bugfix: zooming and replotting in the xplot class now working
* feature: user is now informed about bugfixes in current release, and/or new major/minor releases. This means that you will be informed of bug fixes for your version of STx, not just for the newest STx.

==4.3.7==

Released: 19. October 2017

Revision: 9328

* bugfix: stx no longer crashing on y zoom (bug introduced in r9293 - STx 4.3.6)
* bugfix: binary_file_example.sts now working
* bugfix: if navigating in file dialog using the keyboard, the edit box is now updated with the selected file.

==4.3.6==

Released 25. September 2017

Revision: 9297

* bugfix: the spectrogram dataset now frees up memory once dataset is drawn
* bugfix: adding specials folder to installer

==4.3.5==

Released: 6. September 2017

Revision: 9286

* bugfix: auto-saving the project file no longer leaks memory
* bugfix: editing segments in the workspace now uses the segment template by default
* bugfix: a backup copy of the project file is now made when saving
* bugfix: lists with one item are now selectable with the keyboard
* bugfix: listview column width now calculated with correct font
* bugfix: default values from aseg templates now written to new segment before editing
* bugfix: correct default value written to segment, even if attribute value starts with a number
* bugfix: combobox entries no longer replacing underlines

==4.3.4==

Released: 3. July 2017

Revision: 9214

====Features====
* feature: the [[Programmer_Guide/Macro_Library/CONLOG|conlog]] command can now log to a file.
====Bug Fixes====
* bugfix: the conlog savedata command no longer fails silently if the file cannot be created.

==4.3.3==

Released: 19. June 2017

Revision: 9185

====Bug Fixes====
* bugfix: segment address in the Transcription script is now rounded to 10th of a millisecond (4 decimal places) rather than 1 millisecond.
* bugfix: saving the project file now resets the automatic save timer.
* bugfix: the Transcription, Import Word List and Reorder Word List should now be working correctly again.
====Features====
* feature: new script: [[User_Guide/Scripts/Anonymize.sts|Anonymize.sts]] - anonymize segments (attributes and signal) - requested by the ARI phonetics group
* feature: adding option to automatically save every minute.

==4.3.2==

Released: 13. June 2017

Revision: 9170

====Bug Fixes====
* bugfix: The segment 'Signal.All' is now created when a new sound file is imported. This bug was introduced in version 4.3.1.
* bugfix: the 'wave-only' view in the Transcription script is now available again.

==4.3.1==

Released: 8. June 2017

Revision: 9165

====Bug Fixes====

* bugfix: clicking SPExL graph whilst editing segment in the segment list now draws the segment in the graph (previously needed an explicit refresh to draw the segment).
* bugfix: the workspace is now saved even if the path contains spaces (bug introduced in r8843)
* bugfix: searching using keyboard in listctrl now working in correct order (not backwards). Bug introduced in r9002.
* bugfix: zooming out in SPExL on the y axis with Ctrl+Subtract is now working correctly. This appears to have been around since at least r4442 (STx 3.9)
* bugfix: y position of cursors is now retained when zooming
* bugfix: Viewers/SPEXL create segments at selected address and not with P=0 and L=0
* bugfix: maximising whilst spectrogram is drawing no longer leaves the spectrogram in unfinished version on screen (set new 'm_bRecalculate' flag to force recalculation/redraw when dataset sync has finished).

==4.3.0==

Released: April 2017

Revision: 9149

=Older Versions=

==4.2==
====4.2.23====
Released: 24 August 2017
Revision: 9264
* BUGFIX: correct font used for calculation of formant dialog column size in {{Viewer2}}

====4.2.22====
Released: 25 January 2017
Revision: 9064
* BUGFIX: The following wildcard string comparison will now match:
<pre>
if '*ha' =SI 'haha' then
// it's a match :-)
end
</pre>
* BUGFIX: Changed behavior of comparisons in FIND-TABLE/XML: if a field/attribute is not defined all "notequal" and "notmatching" operators evaluates to "true" and all others to "false"

====4.2.21====
Released: 9 January 2017
Revision: 9023
* BUGFIX: Edit segment dialog now referencing correct segment attributes (bug introduced in r8852 - STx 4.2.15)

====4.2.20====
Released: 23 December 2016
* FEATURE: STx now informs the user of available update via the About dialog.
* BUGFIX: Removing non-existent files from STX.INI when loading
* BUGFIX: About dialog no long blocking workspace file.

====4.2.19====
Released: 12th December 2016
* BUGFIX: Ctrl+U no longer the same as Ctrl+Shift+U in, e.g., signal view.
* BUGFIX: Generating correct hotkey string for Ctrl+Shift+<key>
* BUGFIX: Switching from long to short list of segments in the workspace should no longer lead to a blank detail.
* BUGFIX: Transcription left cursor right bitmap now correct image
* BUGFIX: Fixed bug in Viewer2 where setting the range did not work under all circumstances.
* BUGFIX: Focus moving with selection for listview key navigation and single selection.
* BUGFIX: Copy attributes in the Workspace overview now includes first value (bug introduced in r8297)
* BUGFIX: Checkbox size increased because some strings were being cut off.
* BUGFIX: Show Find Dialog menu now checked if Show Find Dialog is visible
* BUGFIX: Occasional crash in {{Viewer2}} fixed by removing use of static with CString (r9010,r9012).

====4.2.18====
Released: 27 October 2016

* FEATURE: adding PCM info to edit sound file dialog for editing existing project files too.
* FEATURE/BUGFIX: Improved listview keyboard handling (up/down, page up, page down). Disabled scrolling of listview whilst editing.
* BUGFIX: viewer2 no longer hangs if saved rmsb-data are loaded and displayed with autoscale-option
* BUGFIX: detail sequence view now using Ctrl+Shift+U to move selected entry up and Ctrl+Shift+D to move selected entry down (rather than Ctrl+UP and Ctrl+Down - which conflict with internal listview keyboard handling).
* BUGFIX: bscript log window no longer jumps in front of SPExL window when a dialog is opened.
* FEATURE: releases are now digitally signed by the Österreichische Akademie der Wissenschaften
* NOTE: the pole-zero sectioner in the {{Viewer2}} application is extremely slow for high frame rates. We are working on improving it.

====4.2.17====
Released: 26 September 2016
* BUGFIX: Transcription (SPExL) segment list handling working correctly again (bug introduced in 4.2.16)
* BUGFIX: Moving selected sequence entry up/down with keyboard now uses the hotkeys Ctrl+Shift+U and Ctrl+Shift+D (rather than Ctrl+Up and Ctrl+Down) and now works as expected.

====4.2.16====
Released: 30 August 2016
* Support for Windows XP has been removed.
* FEATURE: the XPLOT member "FORALLGRAPHS" is now a public function.
* FEATURE: the XGRAPH function Zoom -> X-Sync was aded to apply the x-zoom of the current graph across all other graphs.
* BUGFIX: the Automatic Segment Names dialog no longer allows invalid segment names.
* BUGFIX: The palette import/export are working again.
* BUGFIX: The Application and Setup tree now correctly stores it's state.
* BUGFIX: Keyboard focus no longer disappears after pressing enter in the Workspace Detail.
* BUGFIX: The selected entry no longer centers itself after editing.
* BUGFIX: The Transcription script SPExL now plays single selections every time (not every second time).
* BUGFIX: Tabbing through the entries in the Workspace Detail no longer goes backwards instead of forwards.

====4.2.15====
Released: unreleased
* FEATURE: Improved sound file export performance
* BUGFIX: The File->Workspace->Save As workspace menu command is now working (bug introduced in r4092)
* BUGFIX: parameter and function now drawing (invalidating) correctly if being set whilst zoomed in.
* BUGFIX: parameter export dialog no longer needs manual refresh (group box is now transparent - uses WS_EX_TRANSPARENT)

====4.2.14====
Released: 18 January 2016
* Minimising GDI use
* Projects files are now associated with {{STX}}
* BUGFIX: one memory leak fixed
* BUGFIX: all help menus associated with mediawiki online help
====4.2.13====
Released: 22 December 2015
* Default help file now the STx Wiki ([https://www.kfs.oeaw.ac.at/stx/docs/wiki/ https://www.kfs.oeaw.ac.at/stx/docs/wiki/]).
* BUGFIX: Find Segments dialog no longer uses ASet search criteria for ASeg search criteria when ASeg criteria is empty
* BUGFIX: Find Segments dialog can now search for segments within a time range.
* BUGFIX: assigning number values to an integer field using table[,field] := eval $#num1 + $#num2 syntax now works
* BUGFIX: growing table by assigning no longer corrupts heap.
*BUGFIX: force context menu to display within dialog window, even if called directly from shell with 0,0 coordinates.
*BUGFIX: edit segment dialog is now initialised with the segment channel
*BUGFIX: context menu now rebuilt before being displayed to ensure that it reflects current state.

====4.2.12====
Released: 4 December 2015
* Improved spectrogram 'overview' visualisation.

====4.2.11====

Released: 16 November 2015

* Added pole-zero to {{Viewer2}} Sectioner
* Bugfix: pane sizes are no longer reset in {{V2}} when sectioner settings dialog is closed.
* Bugfix: list view control header now correct size and clickable, and entries now selectable with one, rather than two clicks.
* Bugfix: copied attributes are no longer preceded by blank line

====4.2.9====

Released: 16 October 2015

* Bugfix: saving to PNG working again

====4.2.8====

Released: 5 October 2015

* Bugfix: the pole-zero method spectrogram overlay is now working correctly.

====4.2.5====

Released: 30 September 2015

* Feature: the pole-zero method is now available as an overlay in the spectrogram and parameter viewer's spectrogram graph. Note however, that this is not bug free, so please wait for 4.2.6 if you're interested in this feature.

====4.2.4====

Released: 10 September 2015

* Bugfix: added missing Visual C++ 2013 Redistributable Package

====4.2.3====

Released: 26 August 2015

* Metasegment size modification now locks modification mode

====4.2.2====

Released: 15 June 2015

* Viewer print font now legible

====4.2.0====

Released: February 2015

=====Features=====

* The speed of audio playback can now be set in the project interface
* The menu shell item has been given the alias 'DIALOG' and will now be refered to as such in the documentation (r8578)
* Pole-Zero [[Programmer_Guide/SPU_Reference/PZTF|SPAtom]] and [[Programmer Guide/Command Reference/EVAL/pztf|EVAL]] methods are now available and are integrated into the [[User_Guide/Spectrogram_and_Parameter_Viewer/Methods/Polezero|Spectrogram and Parameter viewer]].
* Support for Windows 2000/XP has been removed
* Pole-Zero SPU and EVAL methods
* Multiple bug fixes

==4.0==

===4.0.0===

Released: 2012

==3.9==

3.9.4

Released: 15th October 2009

* BUGFIX: real-time analyser drawing more smoothly

3.9.3

Released: 16th September 2009

* BUGFIX: sequences now being saved.

3.9.2

Released: 30th July 2009

* BUGFIX: segments no longer duplicated in un-linked datasets when importing metadata.
* BUGFIX: user-defined amplitude range working in waveform viewer
* BUGFIX: spectrogram amplitude floor now correct after using settings dialog
* BUGFIX: recorder application now recording

3.9.1

Released: 3rd July 2009

* BUGFIX: cmenu check/uncheck working for consecutive items
* BUGFIX: text files items and the load command can now read files encoded with an "FE FF" byte order mark (encoded in UTF-16BE). The error message "unsupported byte order mark" is returned if a UTF-32BE or UTF-32LE byte order mark is found.Supported encodings specified using a byte order mark: UTF-8, UTF-16LE, UTF-16BE<br /> Other supported encodings:windows-1252
* BUGFIX: wave files with chunks defined after the data chunk now have the correct length.
* BUGFIX: saving dataset faster
* BUGFIX: "load soundfile" options should no longer conflict with each other
* BUGFIX: prevent stack overflow in XML files with many siblings (~ 20000)
* BUGFXI: closing rtanalyser whilst it is running now exits shell correctly (without leaving ghost process).

3.9.0

Released: 15th April 2009

Graphical User Interface

General

S_TOOLS-STx now supports all fonts available on the host system.

Comboboxes in ASegTemplates can now be made editable using the flag <span class="stxmacrocommandoption-character">/E</span>.

You can enable/disable runtime error reporting in the Log Control dialog. It is disabled by default, and should only be enabled if you are having problems with S_TOOLS-STx.

Workspace

The segment list can now be edited in the Workspace.

A summary of existing parameters can now be displayed in the segment list (see the Display and Layout Settings dialog).

The Workspace Detail cells can now display text in multiple lines (see the Display and Layout Settings dialog).

Spectrogram & Parameters Viewer

The Spectrogram & Parameters Viewer can now display a harmonic cursor in the spectrogram graph.

The Spectrogram & Parameters Viewer spectrogram method Wavelet has been extended, and a new Cohen's class distribution method has been implemented.

An amplitude legend is now available in spectrogram plots (via the context menu).

DSP

The band-pass filters now have a window parameter.

Toolbox

The toolbox AutoSeg is available in Spectrogram & Parameters Viewer (if loaded) to automatically segment using peaks, clicks or pauses.

A range of Klatt speech synthesis and resynthesis toolbox functions are available.

The toolbox file 'SegmentImEx.sts' implements toolbox functions to import and export segments in the [http://www.fon.hum.uva.nl/praat/ PRAAT] file format. These functions are available in the Workspace.

Scripts

A script specifically designed for transcription and annotation has been developed and included in the default installation of S_TOOLS-STx. The script can be found in the script directory in the file SPExL.sts. There is also a new entry called transcription in the Workspace script tree, which calls the default segmentation routine. The SPExL macro documentation is still being written.

Macro Language

General

Modal window handling has now been moved to the NEW DISPLAY command. Use the option <span class="stxmacrocommandoption-character">/O=$#ownerDisplay</span> to set the owner (which is behind the new display in the z-order. You may also use the option <span class="stxmacrocommandoption-character">/Modal</span> to specify that the owner should be disabled whilst the new display exists.

The NEW command can create objects which are protected from deletion (option <span class="stxmacrocommandoption-character">/U|u</span>).

The command STXCONSTANTS now supports the keywords BITMAPS and BUTTONS.

The command TRANSLATE can now translate the contents of a variable or table.

The command EXIT -xLevel now returns to the first macro defining the label label "OnExitAll" or to the toplevel macro (1st called macro) (rather than to the first macro where the variable #EXITLEVEL = xLevel).

The new command TOKEN, an extended form of the command WORD, can tokenise a string using the specified delimiter.

The new command TRIM can be used to trim characters from the beginning and end of a string.

The new command QUOTE can quote all special characters in a string.

The new command LINELENGTH, although similar to LENGTH, returns the length of a line including delimiters.

The NAME command can now check XML attributes and S_TOOLS-STx XML IDs for syntactical validity. The NAME command can also return a UNC file name for a file on a mapped drive. This is useful, for example, for making DataSets portable in a network environment.

The new command ARG can be used to retrieve macro arguments.

The IREF command supports the option <span class="stxmacrocommandoption-character">/I</span> to simplify and suppress certain error messages.

The global variable @REPORTRUNTIMEERRORS can be set to 1 to display a dialog every time a error occurs when processing a command. Many commands can now take an option specifying that warnings should be generated, rather than errors (DRIVE, LOAD, UNLOAD, SET file LOAD|SAVE|STATUS|DELETE|RENAME|COPY|POSITION), READ, SEGMENT). If set to specify warnings, they will not cause a runtime error.

The READ command (and its variants READSTR, READTAB and READVAR) have a new option <span class="stxmacrocommandoption-character">/E</span> which can be used to escape characters in the input from being used as separators.

Format strings can now add a new line character (\n), using the tag %n. The standard C format tags %x and %X are now supported.

The KEYWORD command now supports the option <span class="stxmacrocommandoption-character">/F</span> which prevents abbreviations from being found and <span class="stxmacrocommandoption-character">/C</span> to make the comparison case sensitive.

The new commands SYSTEMCALL and SYSTEMCALLX are variants of SYSTEM and SYSTEMX which return warnings rather than errors on failure.

The command TGET can now return elapsed milliseconds, when the new option <span class="stxmacrocommandoption-character">/ms</span> is used.

The NAME command, when used with the new UNC subcommand can convert a file path on a mapped drive to its UNC equivalent. This help keep project files portable when accessed from multiple computers (E.g. when the z drive is mapped to \\server\data, the command "name 'z:\ds.xml' unc" will return "\\server\data\ds.xml".

The READ commands have a new option <span class="stxmacrocommandoption-character">/T</span> which prevents arguments from being trimmed.

The macro WINDOWSIZEDLG can be used to allow a user to set a window's size (width and height in pixels).

SPAtoms

The new SPAtom MIXALL mixes up to eight input arrays/vectors into an output array/vector with gain scaling.

The new SPAtom WLANA performs a general wavelet analysis, and the SPAtom CCANA implement a Cohen Class distribution.

The SPAtoms PVANA and PVSYN no accept a windowing function parameter.

The new SPAtom KLATTSYN can be used to generate synthesised speech.

EVAL command

The EVAL command has the following new subcommands:<br /> formants - a new formant tracking algorithm.<br /> limit, limitlow, limithigh - limits values to within a range of values.<br /> min, max - can receive more than one parameter.<br /> cdot, ctrn, conj - complex dot product, matrix transposition and conjugation.<br /> f0ac - F0 detection using autocorrelation.<br /> The EVAL command now supports numerical (e.g. >=), logical (e.g. &&) and ternary (e.g. eval $#a > $#b ? $#a : $#b).

The Macro Library

The DATASETCMD has a new subcommand AUTOSAVE with which you can turn the DataSet autosave feature on and off.

The GRAPHSETUP macro.

The new CGRAPHSETUP command GRAPHLEGEND displays an amplitude legend in a spectrogram plot.

The new CGRAPHSETUP command GETCOLORPALETTE retrieves the print or screen palette in an extended table.

The new CGRAPHSETUP command GETPROFILELIST returns a simple table with a list of color profiles defined in the settings file (S_TOOLS-STx INI).

===== Classes =====

BXMLDoc class

The SETELEMENT function can now take a table containing attribute/value pairs.

CMenu class

The new CMenu function AddToolBoxMenu adds the standard toolbox menu items to the menu.

XPlot class

When constructing an XPlot instance, an owner window may now be specified.

===== Shell Items =====

Dialog Item

The dialog edit control has a new option '<span class="stxmacrocommandoption-character">/F</span>' which forwards KEY messages to the shell.

There are now four 'types' of edit control and a host of new parameters, which means it can display syntax highlighting, be used as a command line interface, etc.

A listview's cells can now be editable. The option <span class="stxmacrocommandoption-character">/E</span> which must be set for a ListView to be editable. The message CELLEDITED is sent if it is editable and its contents has been changed. If the user cancels editing, the message CELLCANCELLED is sent to the shell. If editing is ended because the user presses <span class="stxhotkey">TAB</span> or <span class="stxhotkey">Shift TAB</span>, the CELLEDITEDTAB or CELLEDITEDBACKTAB messages are sent. You can set the focus to a specific cell and enter editing mode using the new command SET dialogItem listviewIndex STARTEDIT.

The listview now supports the <span class="stxmacrocommandoption-character">/F</span> flag which forwards specific key types to the shell.

The listview supports a new option /R=n, which determines the maximum number of lines of text which can be displayed in the listview.

The new attribute !FOREGROUND returns 1 if the dialog window is in the foreground, 0 if it is not and -1 if the command fails in some way.

The new dialog attribute !EDITING can be used to ascertain if a listview is currently being edited or not.

File Item

The NEW FILE command can now take the option <span class="stxmacrocommandoption-character">/S</span>, to suppress error messages on creation failure.

The new file item command COPY <span class="stxmacrocommandoption-character">/Z</span> can be used to encrypt/decrypt a file, including optional password protection.

The new command TRYLOCK will try to get a lock on the file but will not block the script.

The !CHANGED attribute can now be explicitly set or reset. This functionality is new, in as much as versions previous to 3.9.0 could only reset the attribute. The meaning of assigning '1' to the attribute has changed, since assigning '1' now *sets* the attribute, whilst assigning '0' resets the attribute.

A new file item type - the GDX file item - has been developed, which can be used to create files containing graphic data which are passed directly to a graph item. GDX stands for "graphical data exchange". Currently, the spectrogram is the only plot which supports the GDX file type.

Graph Item

The command ADDMARKER can now be used to add a 'Box and Whiskers' metasegment.

The metasegment font can be specified on an individual basis using the ADDMARKER command.

A metasegment may be told not to change color on selection. This is only available using the "SET graph ADDMARKER table" command with the parameter "invertSelected" set to "true" if the metasegment color should be inverted whilst selected or "false" if not. The default is "true".

The key used to make a metasegment moveable can now be set using a 'modifyKeys' entry in the ADDMARKER table parameter.

A simple marker can now be displayed as a single vertical line (option <span class="stxmacrocommandoption-character">/M</span>).

The command OVERVIEW, which toggles between the 'view' and 'overview' modes, has been documented.

The graph supports a new attribute !CURSORMODE which returns the currently visible cursors, as set using the last CURSORMODE command.

The width of a graph's border can now be set using new AXIS command parameters. The default border width is 1 pixel.

The spectrogram palette can be changed at any time using the "SET graph Y * * SPECTROGRAM" function.

The DATASETLOADED message is now sent when a graph finishes loading data for a particular input.

Instance Item

The new command TRYLOCK will try to get a lock on the instance but will not block the script.

Table Item

A table item connected to a ListView must be configured to be editable using the CONFIG command or the !EDITABLE attribute. The CONFIG command has also been extended to allow for a restrictive set of values to be specified for a table field. If specified, the ListView will display a combobox in this column for each entry. All parameters set using the CONFIG command can now be queried via table field attributes.

The new command TRYLOCK will try to get a lock on the table but will not block the script.

The command NEW TABLE supports a silent error flag.

A table field can now display multirow entries, if the !MULTIROW attribute is set to 1, or the CONFIG command multirow parameter is set to ON.

The last user input for a particular column can now be used as the default for that column using the CONFIG command's setuserdefault parameter.

The DEFINE command can now be used to rename an existing field.

Wave Item

The wave item now supports the new attribute !PLAYSRATE which can be used to return the sampling rate currently used to for playback or set a new sampling rate for playback.

=== Changes ===

Changes in S_TOOLS-STx <CURRENT_VERSION>:

Graphical User Interface

F0 Test, F0Lookup, Amplitude Spectrum Statistics

The F0 Test, F0 Lookup and Amplitude Spectrum Statistics functions in the Spectrogram & Parameters Viewer sectioner have been moved to the toolbox file SpectrumTB.sts.

Macro Language

UNLOAD command

The command UNLOAD MACROCODE, UNLOAD SPUCODE and UNLOAD SOURCECODE take one parameter - the name of a sourcecode file (relative or absolute). The MACROCODE variant used to take a blank separated list of macro names and the SPUCODE version used to take a blank separated list of SPU names.

Display and Dialog DROPFILE message

The DROPFILE message sent to displays and dialogs when files are dropped onto them has been changed. The <span class="stxmacrocommandparameter-character">filePath</span> parameter is not longer a string, but rather the id of a simple table with one absolute path per entry.

Syntax

The string "123 456" is no longer a valid number.

=== Bug Fixes ===

Bug fixes

The waterfall graph now prints correctly.

The BDataSet member function AddASet now selects the new audio set if adding the set succeeds (r5534).

Shell commands using the return value RC now assign the value even if return code equals 0 (indicating success) (r5609).

Spectrogram & Parameters Viewer Sectioner copy to clipboard working again (r5625).

The 'view' graph mode now displays correctly when first drawn (r5643).

The asterisk character * is now officially an invalid hotkey, rather than being one which doesn't work correctly (r5500).

Loading an XML file which an unsupported character encoding now fails rather than asserting (r5614).

The Spectrum viewer can now saving CEPST parameters (r6470).

The color 'GRAY' is now defined as the RGB value 96:96:96, which fixes the bug where cursors were invisible on a 'GRAY' background (r6148).

The "SET graph XSCALE" flag "/I" is now working (r6187).

Using the correct normal/dual/tight phase vocoder pv filters (r5874).

All valid number formats (including mmmE /-eee) can now be used in time-expressions (r5746).

=== Corrections ===

S_TOOLS-STx Version: 3.9

A list of documentation corrections since the last release (3.7).

The macro COBJ has been superseded by the COBJ class and no longer exists.

The command SYSTEM MKDIR and SYSTEM RMDIR were undocumented.

The SPAtom ASEG1 parameters are now in the correct order (<span class="stxmacrocommandparameter-character">TABS</span> and <span class="stxmacrocommandparameter-character">TABM</span> were swapped).

The SPAtom VSPLIT was mistakenly documented as VSPLIT1.

The macro DEBUGTB no longer exists.

The descriptions of the different formulas used by the SPAtom MORLET have been corrected.

The section FILE item command LOAD parameters were not documented as mandatory.

Added description of shell variables SCRIPTFILEPATH, SCRIPTDIRECTORY AND SCRIPTMAINNAME.

The AWEIGHT SPAtom has now been documented.

The WAVEOUT SPAtom has now been documented.

A list of documentation corrections since the last release (3.6.2).

The BUTIL FILEDIALOG no longer has a <span class="stxmacrocommandparameter-character">path</span> parameter.

A list of documentation corrections since the last release (3.6.1).

The SET table FIND <span class="stxmacrocommandparameter-character">cexpr</span> format uses colons, not commas as delimiters.

The SET value OUTPUT commands can take <span class="stxmacrocommandoption-character">/Double</span> options.

The description of the parameters for the NEW TABLE command where field definitions are possible has been corrected.

The SET graph CURSORMODE command now describes the bound and locked parameters correctly.

The VAR arithmetic operators DIV, MUL and SUB are actually called DIVIDE, MULTIPLY and SUBTRACT

The SET graph ZSCALE command parameters were incorrect.

=== Known Bugs ===

S_TOOLS-STx Version: 3.9

These bugs were known to exist at the time of the release and are proving difficult, if not impossible to fix.

Interface

Sometimes 44KB soundfiles are created, which are invalid. This bug has not proved easy to replicate, so if you can replicate it, please contact us ( \n This e-mail address is being protected from spam bots, you need JavaScript enabled to view it ).

Can't delete an entry in the DataSet if it has no ID. It is highly unlikely that you will ever have a DataSet entry with no ID. If this is the case however, you must currently delete it by hand (Close S_TOOLS-STx, open the DataSet in a text editor and either give the offending entry an ID, or remove it). Should you be able to reproduce any action which creates an entry without an ID, please contact us ( \n This e-mail address is being protected from spam bots, you need JavaScript enabled to view it ).

Spectrogram & Parameters Viewer

Interpolation of very short signals is incorrect (Deutsch - 2004-11-10 - since 1.0).

Graphics

Copying a display graphic to the clipboard and pasting into a graphics program does not always achieve the desired results. This bug will not be fixed in the foreseeable future. Some graphics programs paste it properly (IrfanView, Microsoft Word), others don't (PaintShop Pro) - (Jonnie White - 2004-07-14).

Selected cursors is not visible if background is set to GRAY (White - 2004-07-12 - since 1.0).

Macro

The dialog control listbox does not handle displaying huge strings properly. This seems to be a problem with the underlying CListBox control (Becker/White - 2004-12 - since 1.0).

The DCOM command INVOKEMETHOD Evaluate always returns an error when communicating with the R DCOM server even if the command was actually successful (Deutsch/White - 2004 - since 3.6.0).

==3.8==

3.8.3

* BUGFIX: zoom in in viewer3 now working when zooming around active cursor
* BUGFIX: spectragram title display corrected (amin/amax)
* BUGFIX: CDLGMAP now deletes window only if it has created the window during construction

3.8.2

* BUGFIX: dataset path now displayed, even if it has spaces in it.
* BUGFIX: Parameter plot explicitly redrawn when new data is sent. This fixes the bug (reported by Julia Brandstaetter) where Set Zero and Undo were not working properly in Spectrogram and Parameter plot.

3.8.1

* BUGFIX: Warn user that more waveform samples are being sent than expected and refrain from crashing.
* BUGFIX: CDlgMap now always uses the next free dialog index for a new entry. This means that multiple maps can reference the same dialog and still work. The functions fci and nc were removed since they are never used. Display now using second event to synchronise creation and variable initialisation. This fixes the mysterious bug where the window class was only sometimes used.
* BUGFIX: If the polyline function is called with less than two points it no longer asserts, but rather ends gracefully.
* BUGFIX: send keys not processed by dialog on to graph hotkey handlers
* BUGFIX: spectrogram is now being initialised with the correct context menu when formants are displayed in it.
* BUGFIX: giving dialog focus if there are no graphs
* BUGFIX: buttons in dialogs in a graph no longer process normal mneumonics. This means that the graph can process them (for Moosmueller). Buttons can still be activated with return and the space bar and tabbed/arrowed to.
* BUGFIX: preventing race conditions in Attach/Detach. This removes one possible cause of autosave crashing. It does not guarantee, though, there to be no other reasons for autosave to crash.

=Downloads=
The {{STX}} downloads are available here: https://s02kfs1.kfs.oeaw.ac.at/pub/stx

History of Changes

2026-04-21T08:45:37Z

Jw: /* Downloads */

File:Isflogo-480x480.png

2023-02-01T12:29:19Z

Jw:

File:Isf-logo125x125.png

2023-02-01T12:29:09Z

Jw:

File:Isf-logo.png

2023-02-01T12:25:15Z

Jw:

History of Changes

2020-12-30T06:38:05Z

Jw: /* 5.0.6 */

History of Changes

2020-12-30T06:01:35Z

Jw:

<div class="noautonum">{{TOC limit|3}}</div>
=5.0=

==Features==

===Compact Workspace Mode===
The Workspace now has a [[User_Guide/Workspace#Modes|compact mode]]. The compact mode is a simplified interface for new users. Although it was designed with linguists in mind, it can be used by anyone.

===webMAUS===
Automatic segmentation using the [https://clarin.phonetik.uni-muenchen.de/BASWebServices/interface webMAUS] REST API. This has been implemented in the toolbox [[User_Guide/Toolbox/runMAUSBasicDlg|<samp>runMAUSBasicDlg</samp>]].

==Bugfixes==

* Correctly handle corrupt Workspace file (generate new one, rather than silently exiting)

==5.0.6==

Released: 30th December 2020

Revision: 10071

* bugfix: No longer dying with "The parameter is incorrect"

==5.0.4==

Released: 12th November 2019

Revision: 10016

* bugfix: SPExL V1.1.11. Adding new segments respects vertical drawing order.
* bugfix: SPExL V1.1.11. Faster deselection of segments.
* bugfix: Real-time waterfall axis drawing correctly
* bugfix: show/hide sectioner setting now respected.
* bugfix: sectioner height setting now respected.

==5.0.3==

Released: 1st October 2019

Revision: 9967

* feature: Signal.All is now selected by default, if no other segment is selected.
* feature: When exporting profiles, the present working directory is used, rather than always selecting the 'profiles' directory. The profiles directory is only used if the present working directory is the root directory.
* feature: The first sound file in the project is selected by default in the compact mode.
* bugfix: When adding a file per drag and drop, the file is now selected.
* bugfix: enabling a disabled edit box now sets the background color correctly (back to white).
* bugfix: debugger trace window now visible in release version too
* bugfix: [[Programmer_Guide/Command_Reference/SYSINFO|SYSINFO]] command now supports Windows 8.1 and Windows 10 (was returning Windows 8)
* bugfix: SPExL V1.1.10. Playlist listview now processes listsorted message and displays sort order set by clicking a column heading. The sort order was first being displayed when clicking in the control after clicking the column heading.
* bugfix: The 'Start' button should now be activated correctly in the Compact Mode.

==5.0.2==

Released: 19th September 2019

Revision: 9946

* bugfix: The context menu Add Sound File now working from the Audio File list in the Compact Mode.
* feature: The possible number of plots in XPlot was increased from 64 to 128

==5.0.0==

Released: 12th September 2019

Revision: 9935

Initial release.

=4.4=

==Features==
===Transcription Script SPExL 1.1.6===
The transcription script SPExL has been simplified and improved.
* Hotkeys can be defined by the user in the SPExL_SegTrans.hotkeys file
* The number of available 'views' has been reduced to 3:
** wave overview & spg. section (a waveform of the whole file in the top graph, with a section of the file as spectrogram below)
** wave only (a waveform of a section of the file with scrollbar functionality)
** wave and spg. section (a synced waveform and spectrogram of a section of the file with scrollbar functionality)
* Segment selection between graphs and the list are now synchronised. If you select a segment in the graph, it is selected in the list and vice versa.
* Changes made to the project (new segments, edited attributes) are now made directly in the project rather than the user having to explicitly press the 'save segments to project file' button to copy them from SPExL to the Workspace. Note that they are only written to disk, however, if the project is saved (press the 'Save' button).
===Visible Segment Attributes Saved per Project File===
If you choose to display other attributes other than the default attributes in the Workspace Detail View, these settings are now saved in the open project file. When a project file is then opened, the relevant attribute list is loaded and used, rather than the user having to [[User_Guide/Workspace/Detail/Search_for_Element_Attributes|search for them]] again. You can still modify which attributes are displayed using the General Settings [[User_Guide/Workspace/Application_and_Setup_Tree/Options/General_Settings#.22Set.22_Attributes_.26_.22Segment.22_Attributes|'Select "Segment" Attributes' dialog]].
===Global / Profile Sectioner Settings===
The sectioner settings in the {{Viewer2}} analysis application were always global to STx. As of STx 4.4.0, you can choose to save your sectioner settings with your profile. The default is still the 'global' variant. To switch to profile sectioner settings, uncheck the '''use global sectioner settings''' checkbox in the {{Viewer2}} [[User_Guide/Spectrogram_and_Parameter_Viewer/Settings_Dialog|settings dialog]].

==4.4.10==

Released: 17th January 2019

Revision: 9712

* bugfix: playback gain factor - the playback gain is now working also for asio devices (see CSTXASIOEngine::Transfer())
* bugfix: renumbering command did not update detail as expected.
* bugfix: the update version dialogs now display the correct workspace path

==4.4.9==

Released: 25th September 2018

Revision:

* feature: don't ask user where to put sound file if there are no sets in the project.
* feature: dragging and dropping a template onto {{ST}X} copies it to the templates folder.
* feature: added 'Open Containing Folder' context menu for sound files and links. Improved contextualisation of context menu in detail (overview==root/set)
* feature: 'txt2wav' script: Adding decimal symbol and field delimiter to parameters, as well as the ability to specify which extension to use to filter files (was hard-coded to 'txt'). Now this macro can be used to
* feature: bdataset createwave and createwwaveex now take an openmode keyword: auto|create|read|write, which is passed on to bsf open. This means that we can now open files in modes other than 'auto'.
process CSV files.
* bugfix: very long capture text for edit controls with 'text above' could lead to capture static being longer than the edit control and unintentionally overlapping with other controls (e.g. in Transcription Setup dialog).
* bugfix: closing con log window no longer resets PARENT shell variable, unless it is set the the con log window itself.
* bugfix: sound files now opened using the FILE_SHARE_READ dwShareMode. This should mean, that STx no longer prevents other processes from reading the sound files.
* bugfix: viewer opens sound file in read mode, rather than read/write.
* bugfix: the !PATH attribute (MakePath()) now returns the correct path for files in the root of a drive. Bug was introduced in r8998 (STx 4.2.19). This was, for example, was causing sound files in the root directory not to be unloaded, and hence was causing sharing violations.

==4.4.8==

Released: 25th July 2018

Revision: 9500

* feature: Spectrogram & Parameters viewer sectioner window now remembers which function cursor is bound to when being replotted.
* feature: The <samp>downsampling.sts</samp> script now has a <samp>ResampleCLI</samp> macro for automatic resampling of one or more files (see source). The old <samp>ResampleDialog</samp> was renamed to <samp>ResampleDLG</samp>.
* feature: Adding help for "Import_PRAAT_TextGrid" toolbox.
* feature: Adding ability to edit 'Sectioner Settings' from the profile dialog.
* feature: Transcription 1.1.8 - removed segment 'refresh' button, since segments always reflect current project state.
* bugfix: a window that was maximised will now be maximised to the correct monitor. It was always being maximised to monitor 1 on display creation.
* bugfix: the profile version number is now imported with the profile. This means that, for example, the use global profile settings flag is now also set correctly on import.
* bugfix: minor fix of position of two controls which were overlapping with controls beneath
* bugfix: stop playback cursor if wave is stopped by starting playback in another graph. Beforehand, the playback cursor was stopped if it got to the end, or the ESC key was pressed.
* bugfix: Y coordinate vector conversion was inaccurate by 1 pixel (bug introduced in r2536) This affects the XY, parameter, scatter, wave and waterfall functions.

==4.4.6==

Released: 21. March 2018

Revision: 9441

* bugfix: some bugfixes and minor changes in BSeq
* bugfix: BScript: logging of unhandled messages in msg-loop disabled // Conlog: /ton and /toff options implemented (timer on/off + show elapsed time)
* bugfix: Viewer3 settings now being saved (bug introduced in r9318 - STx 4.4.0)
* bugfix CShellFile::Status() - catch CTime exception if file time is illegal (avoid program crash)

==4.4.5==

Released: 19. February 2018

Revision: 9416

* bugfix: in Viewer2 large asegtemplates (with many fields) are now displayed correctly - note: the same problem exists in Viewer1 if the segment dialog part (created by the macro call ""metasegment msdialog") needs more than 90 controls (around 40 segment attributes)
* feature: the bscript.stx function loaddata (con loaddata) can now also load string tables (extenden tables) from csv-files. The file types TEXT/TEXTCONTINUATION (numeric parameter table), STRING/STRINCONTINUATION (extended string table) and BINARY (binary stx-data files) are available. Type ASCII/ASCIICONTINUATION has been removed.
* feature: new feature (bugfix?): CShellTable::Read() - handling of field-separator tab has been changed - empty fields are now possible - warning: may have an effect on existing script/macro code!

==4.4.4==

Released: 26. January 2018

Revision: 9404

* bugfix: combobox entries with underliners retain their underliners now in the workspace detail (reported by Anton Baotic), and in Spexl.

==4.4.3==

Released: 18. December 2017

Revision: 9391

* bugfix: adding missing Transcription hotkey file and retisimo scripts

==4.4.2==

Released: 30. November 2017

Revision: 9377

* bugfix: SPExL Transcription script V1.1.7: the /U ASegTemplate flag is now respected, and, if used, the last entered value for a segment attribute is used as the default for the next new segment.
* bugfix: default profile names no longer have the invalid blank character in them. A check was also added, so new profiles cannot be created with blanks.

==4.4.1==

Released: 23. November 2017

Revision: 9369

* bugfix: if zooming is turned off in {{Viewer2}}, segments are now correctly visible on the Y axis. This bug has existed since at least STx 4.2.

==4.4.0==

Released: 14 November 2017

Revision: 9350

Initial release.

=4.3=

==Features==
====Load or export parameters from super or sub segments====
Parameters from super segments or from sub segments can now be loaded into the selected segment. For example, if you have analysed a word and corrected the parameters, you can use these corrected parameters when viewing phoneme segments within the word. This is achieved by selecting 'super segment data only' setting in the Viewer settings [[User_Guide/Spectrogram_and_Parameter_Viewer/Settings_Dialog#Parameter_IO_Configuration|Parameter IO Configuration]] dialog.

It is possible to select which super/sub segment parameters should be used, filtering by time, attribute or ID.

This feature is also available in the parameter export dialog.

====Parameter setting summary====
A summary of the settings used for parameter analysis is now saved with the parameter in the project file. This information is displayed in the [[User_Guide/Workspace/Detail/Views/Parameter_View|Parameter View]].

====Exact sample positioning in {{Viewer2}}====

You can now select a position in the [[User_Guide/Spectrogram_and_Parameter_Viewer#Waveform_zoom_window|Waveform Zoom window]] in {{Viewer2}} and move the active time cursor to that position using the hotkey '1'. This is useful for exact positioning of the time cursors when segmenting, for example, words.

==4.3.10==

Released: 26. January 2018

Revision: 9407
*bugfix: do not allow user to give a profile a name including blanks.
*bugfix: renaming spectrum profiles (removing blanks)
*bugfix: the correct most recently entered value in a listctrl is now saved (not the last in the list).
*bugfix: passing delete, insert and back keys to static control.
*bugfix: 'spexl*.hotkeys.default' 'retisimo.sts' 'retisimo_*.sts' 'HRTF_II_new.txt' 'downsample.sts' files are now being copied too (bug introduced in r8789)
*bugfix: removing extraneous / from Editing segments help URL
*bugfix: combobox entries with underliners retain their underliners now in the workspace detail (reported by Anton Baotic), and in Spexl.

==4.3.9==

Released: 23. November 2017

Revision: 9363

* bugfix: if zooming is turned off in {{Viewer2}}, segments are now correctly visible on the Y axis. This bug has existed since at least STx 4.2.

==4.3.8==

Released: 14. November 2017

Revision: 9347

* bugfix: zooming and replotting in the xplot class now working
* feature: user is now informed about bugfixes in current release, and/or new major/minor releases. This means that you will be informed of bug fixes for your version of STx, not just for the newest STx.

==4.3.7==

Released: 19. October 2017

Revision: 9328

* bugfix: stx no longer crashing on y zoom (bug introduced in r9293 - STx 4.3.6)
* bugfix: binary_file_example.sts now working
* bugfix: if navigating in file dialog using the keyboard, the edit box is now updated with the selected file.

==4.3.6==

Released 25. September 2017

Revision: 9297

* bugfix: the spectrogram dataset now frees up memory once dataset is drawn
* bugfix: adding specials folder to installer

==4.3.5==

Released: 6. September 2017

Revision: 9286

* bugfix: auto-saving the project file no longer leaks memory
* bugfix: editing segments in the workspace now uses the segment template by default
* bugfix: a backup copy of the project file is now made when saving
* bugfix: lists with one item are now selectable with the keyboard
* bugfix: listview column width now calculated with correct font
* bugfix: default values from aseg templates now written to new segment before editing
* bugfix: correct default value written to segment, even if attribute value starts with a number
* bugfix: combobox entries no longer replacing underlines

==4.3.4==

Released: 3. July 2017

Revision: 9214

====Features====
* feature: the [[Programmer_Guide/Macro_Library/CONLOG|conlog]] command can now log to a file.
====Bug Fixes====
* bugfix: the conlog savedata command no longer fails silently if the file cannot be created.

==4.3.3==

Released: 19. June 2017

Revision: 9185

====Bug Fixes====
* bugfix: segment address in the Transcription script is now rounded to 10th of a millisecond (4 decimal places) rather than 1 millisecond.
* bugfix: saving the project file now resets the automatic save timer.
* bugfix: the Transcription, Import Word List and Reorder Word List should now be working correctly again.
====Features====
* feature: new script: [[User_Guide/Scripts/Anonymize.sts|Anonymize.sts]] - anonymize segments (attributes and signal) - requested by the ARI phonetics group
* feature: adding option to automatically save every minute.

==4.3.2==

Released: 13. June 2017

Revision: 9170

====Bug Fixes====
* bugfix: The segment 'Signal.All' is now created when a new sound file is imported. This bug was introduced in version 4.3.1.
* bugfix: the 'wave-only' view in the Transcription script is now available again.

==4.3.1==

Released: 8. June 2017

Revision: 9165

====Bug Fixes====

* bugfix: clicking SPExL graph whilst editing segment in the segment list now draws the segment in the graph (previously needed an explicit refresh to draw the segment).
* bugfix: the workspace is now saved even if the path contains spaces (bug introduced in r8843)
* bugfix: searching using keyboard in listctrl now working in correct order (not backwards). Bug introduced in r9002.
* bugfix: zooming out in SPExL on the y axis with Ctrl+Subtract is now working correctly. This appears to have been around since at least r4442 (STx 3.9)
* bugfix: y position of cursors is now retained when zooming
* bugfix: Viewers/SPEXL create segments at selected address and not with P=0 and L=0
* bugfix: maximising whilst spectrogram is drawing no longer leaves the spectrogram in unfinished version on screen (set new 'm_bRecalculate' flag to force recalculation/redraw when dataset sync has finished).

==4.3.0==

Released: April 2017

Revision: 9149

=Older Versions=

==4.2==
====4.2.23====
Released: 24 August 2017
Revision: 9264
* BUGFIX: correct font used for calculation of formant dialog column size in {{Viewer2}}

====4.2.22====
Released: 25 January 2017
Revision: 9064
* BUGFIX: The following wildcard string comparison will now match:
<pre>
if '*ha' =SI 'haha' then
// it's a match :-)
end
</pre>
* BUGFIX: Changed behavior of comparisons in FIND-TABLE/XML: if a field/attribute is not defined all "notequal" and "notmatching" operators evaluates to "true" and all others to "false"

====4.2.21====
Released: 9 January 2017
Revision: 9023
* BUGFIX: Edit segment dialog now referencing correct segment attributes (bug introduced in r8852 - STx 4.2.15)

====4.2.20====
Released: 23 December 2016
* FEATURE: STx now informs the user of available update via the About dialog.
* BUGFIX: Removing non-existent files from STX.INI when loading
* BUGFIX: About dialog no long blocking workspace file.

====4.2.19====
Released: 12th December 2016
* BUGFIX: Ctrl+U no longer the same as Ctrl+Shift+U in, e.g., signal view.
* BUGFIX: Generating correct hotkey string for Ctrl+Shift+<key>
* BUGFIX: Switching from long to short list of segments in the workspace should no longer lead to a blank detail.
* BUGFIX: Transcription left cursor right bitmap now correct image
* BUGFIX: Fixed bug in Viewer2 where setting the range did not work under all circumstances.
* BUGFIX: Focus moving with selection for listview key navigation and single selection.
* BUGFIX: Copy attributes in the Workspace overview now includes first value (bug introduced in r8297)
* BUGFIX: Checkbox size increased because some strings were being cut off.
* BUGFIX: Show Find Dialog menu now checked if Show Find Dialog is visible
* BUGFIX: Occasional crash in {{Viewer2}} fixed by removing use of static with CString (r9010,r9012).

====4.2.18====
Released: 27 October 2016

* FEATURE: adding PCM info to edit sound file dialog for editing existing project files too.
* FEATURE/BUGFIX: Improved listview keyboard handling (up/down, page up, page down). Disabled scrolling of listview whilst editing.
* BUGFIX: viewer2 no longer hangs if saved rmsb-data are loaded and displayed with autoscale-option
* BUGFIX: detail sequence view now using Ctrl+Shift+U to move selected entry up and Ctrl+Shift+D to move selected entry down (rather than Ctrl+UP and Ctrl+Down - which conflict with internal listview keyboard handling).
* BUGFIX: bscript log window no longer jumps in front of SPExL window when a dialog is opened.
* FEATURE: releases are now digitally signed by the Österreichische Akademie der Wissenschaften
* NOTE: the pole-zero sectioner in the {{Viewer2}} application is extremely slow for high frame rates. We are working on improving it.

====4.2.17====
Released: 26 September 2016
* BUGFIX: Transcription (SPExL) segment list handling working correctly again (bug introduced in 4.2.16)
* BUGFIX: Moving selected sequence entry up/down with keyboard now uses the hotkeys Ctrl+Shift+U and Ctrl+Shift+D (rather than Ctrl+Up and Ctrl+Down) and now works as expected.

====4.2.16====
Released: 30 August 2016
* Support for Windows XP has been removed.
* FEATURE: the XPLOT member "FORALLGRAPHS" is now a public function.
* FEATURE: the XGRAPH function Zoom -> X-Sync was aded to apply the x-zoom of the current graph across all other graphs.
* BUGFIX: the Automatic Segment Names dialog no longer allows invalid segment names.
* BUGFIX: The palette import/export are working again.
* BUGFIX: The Application and Setup tree now correctly stores it's state.
* BUGFIX: Keyboard focus no longer disappears after pressing enter in the Workspace Detail.
* BUGFIX: The selected entry no longer centers itself after editing.
* BUGFIX: The Transcription script SPExL now plays single selections every time (not every second time).
* BUGFIX: Tabbing through the entries in the Workspace Detail no longer goes backwards instead of forwards.

====4.2.15====
Released: unreleased
* FEATURE: Improved sound file export performance
* BUGFIX: The File->Workspace->Save As workspace menu command is now working (bug introduced in r4092)
* BUGFIX: parameter and function now drawing (invalidating) correctly if being set whilst zoomed in.
* BUGFIX: parameter export dialog no longer needs manual refresh (group box is now transparent - uses WS_EX_TRANSPARENT)

====4.2.14====
Released: 18 January 2016
* Minimising GDI use
* Projects files are now associated with {{STX}}
* BUGFIX: one memory leak fixed
* BUGFIX: all help menus associated with mediawiki online help
====4.2.13====
Released: 22 December 2015
* Default help file now the STx Wiki ([https://www.kfs.oeaw.ac.at/stx/docs/wiki/ https://www.kfs.oeaw.ac.at/stx/docs/wiki/]).
* BUGFIX: Find Segments dialog no longer uses ASet search criteria for ASeg search criteria when ASeg criteria is empty
* BUGFIX: Find Segments dialog can now search for segments within a time range.
* BUGFIX: assigning number values to an integer field using table[,field] := eval $#num1 + $#num2 syntax now works
* BUGFIX: growing table by assigning no longer corrupts heap.
*BUGFIX: force context menu to display within dialog window, even if called directly from shell with 0,0 coordinates.
*BUGFIX: edit segment dialog is now initialised with the segment channel
*BUGFIX: context menu now rebuilt before being displayed to ensure that it reflects current state.

====4.2.12====
Released: 4 December 2015
* Improved spectrogram 'overview' visualisation.

====4.2.11====

Released: 16 November 2015

* Added pole-zero to {{Viewer2}} Sectioner
* Bugfix: pane sizes are no longer reset in {{V2}} when sectioner settings dialog is closed.
* Bugfix: list view control header now correct size and clickable, and entries now selectable with one, rather than two clicks.
* Bugfix: copied attributes are no longer preceded by blank line

====4.2.9====

Released: 16 October 2015

* Bugfix: saving to PNG working again

====4.2.8====

Released: 5 October 2015

* Bugfix: the pole-zero method spectrogram overlay is now working correctly.

====4.2.5====

Released: 30 September 2015

* Feature: the pole-zero method is now available as an overlay in the spectrogram and parameter viewer's spectrogram graph. Note however, that this is not bug free, so please wait for 4.2.6 if you're interested in this feature.

====4.2.4====

Released: 10 September 2015

* Bugfix: added missing Visual C++ 2013 Redistributable Package

====4.2.3====

Released: 26 August 2015

* Metasegment size modification now locks modification mode

====4.2.2====

Released: 15 June 2015

* Viewer print font now legible

====4.2.0====

Released: February 2015

=====Features=====

* The speed of audio playback can now be set in the project interface
* The menu shell item has been given the alias 'DIALOG' and will now be refered to as such in the documentation (r8578)
* Pole-Zero [[Programmer_Guide/SPU_Reference/PZTF|SPAtom]] and [[Programmer Guide/Command Reference/EVAL/pztf|EVAL]] methods are now available and are integrated into the [[User_Guide/Spectrogram_and_Parameter_Viewer/Methods/Polezero|Spectrogram and Parameter viewer]].
* Support for Windows 2000/XP has been removed
* Pole-Zero SPU and EVAL methods
* Multiple bug fixes

==4.0==

===4.0.0===

Released: 2012

==3.9==

3.9.4

Released: 15th October 2009

* BUGFIX: real-time analyser drawing more smoothly

3.9.3

Released: 16th September 2009

* BUGFIX: sequences now being saved.

3.9.2

Released: 30th July 2009

* BUGFIX: segments no longer duplicated in un-linked datasets when importing metadata.
* BUGFIX: user-defined amplitude range working in waveform viewer
* BUGFIX: spectrogram amplitude floor now correct after using settings dialog
* BUGFIX: recorder application now recording

3.9.1

Released: 3rd July 2009

* BUGFIX: cmenu check/uncheck working for consecutive items
* BUGFIX: text files items and the load command can now read files encoded with an "FE FF" byte order mark (encoded in UTF-16BE). The error message "unsupported byte order mark" is returned if a UTF-32BE or UTF-32LE byte order mark is found.Supported encodings specified using a byte order mark: UTF-8, UTF-16LE, UTF-16BE<br /> Other supported encodings:windows-1252
* BUGFIX: wave files with chunks defined after the data chunk now have the correct length.
* BUGFIX: saving dataset faster
* BUGFIX: "load soundfile" options should no longer conflict with each other
* BUGFIX: prevent stack overflow in XML files with many siblings (~ 20000)
* BUGFXI: closing rtanalyser whilst it is running now exits shell correctly (without leaving ghost process).

3.9.0

Released: 15th April 2009

Graphical User Interface

General

S_TOOLS-STx now supports all fonts available on the host system.

Comboboxes in ASegTemplates can now be made editable using the flag <span class="stxmacrocommandoption-character">/E</span>.

You can enable/disable runtime error reporting in the Log Control dialog. It is disabled by default, and should only be enabled if you are having problems with S_TOOLS-STx.

Workspace

The segment list can now be edited in the Workspace.

A summary of existing parameters can now be displayed in the segment list (see the Display and Layout Settings dialog).

The Workspace Detail cells can now display text in multiple lines (see the Display and Layout Settings dialog).

Spectrogram & Parameters Viewer

The Spectrogram & Parameters Viewer can now display a harmonic cursor in the spectrogram graph.

The Spectrogram & Parameters Viewer spectrogram method Wavelet has been extended, and a new Cohen's class distribution method has been implemented.

An amplitude legend is now available in spectrogram plots (via the context menu).

DSP

The band-pass filters now have a window parameter.

Toolbox

The toolbox AutoSeg is available in Spectrogram & Parameters Viewer (if loaded) to automatically segment using peaks, clicks or pauses.

A range of Klatt speech synthesis and resynthesis toolbox functions are available.

The toolbox file 'SegmentImEx.sts' implements toolbox functions to import and export segments in the [http://www.fon.hum.uva.nl/praat/ PRAAT] file format. These functions are available in the Workspace.

Scripts

A script specifically designed for transcription and annotation has been developed and included in the default installation of S_TOOLS-STx. The script can be found in the script directory in the file SPExL.sts. There is also a new entry called transcription in the Workspace script tree, which calls the default segmentation routine. The SPExL macro documentation is still being written.

Macro Language

General

Modal window handling has now been moved to the NEW DISPLAY command. Use the option <span class="stxmacrocommandoption-character">/O=$#ownerDisplay</span> to set the owner (which is behind the new display in the z-order. You may also use the option <span class="stxmacrocommandoption-character">/Modal</span> to specify that the owner should be disabled whilst the new display exists.

The NEW command can create objects which are protected from deletion (option <span class="stxmacrocommandoption-character">/U|u</span>).

The command STXCONSTANTS now supports the keywords BITMAPS and BUTTONS.

The command TRANSLATE can now translate the contents of a variable or table.

The command EXIT -xLevel now returns to the first macro defining the label label "OnExitAll" or to the toplevel macro (1st called macro) (rather than to the first macro where the variable #EXITLEVEL = xLevel).

The new command TOKEN, an extended form of the command WORD, can tokenise a string using the specified delimiter.

The new command TRIM can be used to trim characters from the beginning and end of a string.

The new command QUOTE can quote all special characters in a string.

The new command LINELENGTH, although similar to LENGTH, returns the length of a line including delimiters.

The NAME command can now check XML attributes and S_TOOLS-STx XML IDs for syntactical validity. The NAME command can also return a UNC file name for a file on a mapped drive. This is useful, for example, for making DataSets portable in a network environment.

The new command ARG can be used to retrieve macro arguments.

The IREF command supports the option <span class="stxmacrocommandoption-character">/I</span> to simplify and suppress certain error messages.

The global variable @REPORTRUNTIMEERRORS can be set to 1 to display a dialog every time a error occurs when processing a command. Many commands can now take an option specifying that warnings should be generated, rather than errors (DRIVE, LOAD, UNLOAD, SET file LOAD|SAVE|STATUS|DELETE|RENAME|COPY|POSITION), READ, SEGMENT). If set to specify warnings, they will not cause a runtime error.

The READ command (and its variants READSTR, READTAB and READVAR) have a new option <span class="stxmacrocommandoption-character">/E</span> which can be used to escape characters in the input from being used as separators.

Format strings can now add a new line character (\n), using the tag %n. The standard C format tags %x and %X are now supported.

The KEYWORD command now supports the option <span class="stxmacrocommandoption-character">/F</span> which prevents abbreviations from being found and <span class="stxmacrocommandoption-character">/C</span> to make the comparison case sensitive.

The new commands SYSTEMCALL and SYSTEMCALLX are variants of SYSTEM and SYSTEMX which return warnings rather than errors on failure.

The command TGET can now return elapsed milliseconds, when the new option <span class="stxmacrocommandoption-character">/ms</span> is used.

The NAME command, when used with the new UNC subcommand can convert a file path on a mapped drive to its UNC equivalent. This help keep project files portable when accessed from multiple computers (E.g. when the z drive is mapped to \\server\data, the command "name 'z:\ds.xml' unc" will return "\\server\data\ds.xml".

The READ commands have a new option <span class="stxmacrocommandoption-character">/T</span> which prevents arguments from being trimmed.

The macro WINDOWSIZEDLG can be used to allow a user to set a window's size (width and height in pixels).

SPAtoms

The new SPAtom MIXALL mixes up to eight input arrays/vectors into an output array/vector with gain scaling.

The new SPAtom WLANA performs a general wavelet analysis, and the SPAtom CCANA implement a Cohen Class distribution.

The SPAtoms PVANA and PVSYN no accept a windowing function parameter.

The new SPAtom KLATTSYN can be used to generate synthesised speech.

EVAL command

The EVAL command has the following new subcommands:<br /> formants - a new formant tracking algorithm.<br /> limit, limitlow, limithigh - limits values to within a range of values.<br /> min, max - can receive more than one parameter.<br /> cdot, ctrn, conj - complex dot product, matrix transposition and conjugation.<br /> f0ac - F0 detection using autocorrelation.<br /> The EVAL command now supports numerical (e.g. >=), logical (e.g. &&) and ternary (e.g. eval $#a > $#b ? $#a : $#b).

The Macro Library

The DATASETCMD has a new subcommand AUTOSAVE with which you can turn the DataSet autosave feature on and off.

The GRAPHSETUP macro.

The new CGRAPHSETUP command GRAPHLEGEND displays an amplitude legend in a spectrogram plot.

The new CGRAPHSETUP command GETCOLORPALETTE retrieves the print or screen palette in an extended table.

The new CGRAPHSETUP command GETPROFILELIST returns a simple table with a list of color profiles defined in the settings file (S_TOOLS-STx INI).

===== Classes =====

BXMLDoc class

The SETELEMENT function can now take a table containing attribute/value pairs.

CMenu class

The new CMenu function AddToolBoxMenu adds the standard toolbox menu items to the menu.

XPlot class

When constructing an XPlot instance, an owner window may now be specified.

===== Shell Items =====

Dialog Item

The dialog edit control has a new option '<span class="stxmacrocommandoption-character">/F</span>' which forwards KEY messages to the shell.

There are now four 'types' of edit control and a host of new parameters, which means it can display syntax highlighting, be used as a command line interface, etc.

A listview's cells can now be editable. The option <span class="stxmacrocommandoption-character">/E</span> which must be set for a ListView to be editable. The message CELLEDITED is sent if it is editable and its contents has been changed. If the user cancels editing, the message CELLCANCELLED is sent to the shell. If editing is ended because the user presses <span class="stxhotkey">TAB</span> or <span class="stxhotkey">Shift TAB</span>, the CELLEDITEDTAB or CELLEDITEDBACKTAB messages are sent. You can set the focus to a specific cell and enter editing mode using the new command SET dialogItem listviewIndex STARTEDIT.

The listview now supports the <span class="stxmacrocommandoption-character">/F</span> flag which forwards specific key types to the shell.

The listview supports a new option /R=n, which determines the maximum number of lines of text which can be displayed in the listview.

The new attribute !FOREGROUND returns 1 if the dialog window is in the foreground, 0 if it is not and -1 if the command fails in some way.

The new dialog attribute !EDITING can be used to ascertain if a listview is currently being edited or not.

File Item

The NEW FILE command can now take the option <span class="stxmacrocommandoption-character">/S</span>, to suppress error messages on creation failure.

The new file item command COPY <span class="stxmacrocommandoption-character">/Z</span> can be used to encrypt/decrypt a file, including optional password protection.

The new command TRYLOCK will try to get a lock on the file but will not block the script.

The !CHANGED attribute can now be explicitly set or reset. This functionality is new, in as much as versions previous to 3.9.0 could only reset the attribute. The meaning of assigning '1' to the attribute has changed, since assigning '1' now *sets* the attribute, whilst assigning '0' resets the attribute.

A new file item type - the GDX file item - has been developed, which can be used to create files containing graphic data which are passed directly to a graph item. GDX stands for "graphical data exchange". Currently, the spectrogram is the only plot which supports the GDX file type.

Graph Item

The command ADDMARKER can now be used to add a 'Box and Whiskers' metasegment.

The metasegment font can be specified on an individual basis using the ADDMARKER command.

A metasegment may be told not to change color on selection. This is only available using the "SET graph ADDMARKER table" command with the parameter "invertSelected" set to "true" if the metasegment color should be inverted whilst selected or "false" if not. The default is "true".

The key used to make a metasegment moveable can now be set using a 'modifyKeys' entry in the ADDMARKER table parameter.

A simple marker can now be displayed as a single vertical line (option <span class="stxmacrocommandoption-character">/M</span>).

The command OVERVIEW, which toggles between the 'view' and 'overview' modes, has been documented.

The graph supports a new attribute !CURSORMODE which returns the currently visible cursors, as set using the last CURSORMODE command.

The width of a graph's border can now be set using new AXIS command parameters. The default border width is 1 pixel.

The spectrogram palette can be changed at any time using the "SET graph Y * * SPECTROGRAM" function.

The DATASETLOADED message is now sent when a graph finishes loading data for a particular input.

Instance Item

The new command TRYLOCK will try to get a lock on the instance but will not block the script.

Table Item

A table item connected to a ListView must be configured to be editable using the CONFIG command or the !EDITABLE attribute. The CONFIG command has also been extended to allow for a restrictive set of values to be specified for a table field. If specified, the ListView will display a combobox in this column for each entry. All parameters set using the CONFIG command can now be queried via table field attributes.

The new command TRYLOCK will try to get a lock on the table but will not block the script.

The command NEW TABLE supports a silent error flag.

A table field can now display multirow entries, if the !MULTIROW attribute is set to 1, or the CONFIG command multirow parameter is set to ON.

The last user input for a particular column can now be used as the default for that column using the CONFIG command's setuserdefault parameter.

The DEFINE command can now be used to rename an existing field.

Wave Item

The wave item now supports the new attribute !PLAYSRATE which can be used to return the sampling rate currently used to for playback or set a new sampling rate for playback.

=== Changes ===

Changes in S_TOOLS-STx <CURRENT_VERSION>:

Graphical User Interface

F0 Test, F0Lookup, Amplitude Spectrum Statistics

The F0 Test, F0 Lookup and Amplitude Spectrum Statistics functions in the Spectrogram & Parameters Viewer sectioner have been moved to the toolbox file SpectrumTB.sts.

Macro Language

UNLOAD command

The command UNLOAD MACROCODE, UNLOAD SPUCODE and UNLOAD SOURCECODE take one parameter - the name of a sourcecode file (relative or absolute). The MACROCODE variant used to take a blank separated list of macro names and the SPUCODE version used to take a blank separated list of SPU names.

Display and Dialog DROPFILE message

The DROPFILE message sent to displays and dialogs when files are dropped onto them has been changed. The <span class="stxmacrocommandparameter-character">filePath</span> parameter is not longer a string, but rather the id of a simple table with one absolute path per entry.

Syntax

The string "123 456" is no longer a valid number.

=== Bug Fixes ===

Bug fixes

The waterfall graph now prints correctly.

The BDataSet member function AddASet now selects the new audio set if adding the set succeeds (r5534).

Shell commands using the return value RC now assign the value even if return code equals 0 (indicating success) (r5609).

Spectrogram & Parameters Viewer Sectioner copy to clipboard working again (r5625).

The 'view' graph mode now displays correctly when first drawn (r5643).

The asterisk character * is now officially an invalid hotkey, rather than being one which doesn't work correctly (r5500).

Loading an XML file which an unsupported character encoding now fails rather than asserting (r5614).

The Spectrum viewer can now saving CEPST parameters (r6470).

The color 'GRAY' is now defined as the RGB value 96:96:96, which fixes the bug where cursors were invisible on a 'GRAY' background (r6148).

The "SET graph XSCALE" flag "/I" is now working (r6187).

Using the correct normal/dual/tight phase vocoder pv filters (r5874).

All valid number formats (including mmmE /-eee) can now be used in time-expressions (r5746).

=== Corrections ===

S_TOOLS-STx Version: 3.9

A list of documentation corrections since the last release (3.7).

The macro COBJ has been superseded by the COBJ class and no longer exists.

The command SYSTEM MKDIR and SYSTEM RMDIR were undocumented.

The SPAtom ASEG1 parameters are now in the correct order (<span class="stxmacrocommandparameter-character">TABS</span> and <span class="stxmacrocommandparameter-character">TABM</span> were swapped).

The SPAtom VSPLIT was mistakenly documented as VSPLIT1.

The macro DEBUGTB no longer exists.

The descriptions of the different formulas used by the SPAtom MORLET have been corrected.

The section FILE item command LOAD parameters were not documented as mandatory.

Added description of shell variables SCRIPTFILEPATH, SCRIPTDIRECTORY AND SCRIPTMAINNAME.

The AWEIGHT SPAtom has now been documented.

The WAVEOUT SPAtom has now been documented.

A list of documentation corrections since the last release (3.6.2).

The BUTIL FILEDIALOG no longer has a <span class="stxmacrocommandparameter-character">path</span> parameter.

A list of documentation corrections since the last release (3.6.1).

The SET table FIND <span class="stxmacrocommandparameter-character">cexpr</span> format uses colons, not commas as delimiters.

The SET value OUTPUT commands can take <span class="stxmacrocommandoption-character">/Double</span> options.

The description of the parameters for the NEW TABLE command where field definitions are possible has been corrected.

The SET graph CURSORMODE command now describes the bound and locked parameters correctly.

The VAR arithmetic operators DIV, MUL and SUB are actually called DIVIDE, MULTIPLY and SUBTRACT

The SET graph ZSCALE command parameters were incorrect.

=== Known Bugs ===

S_TOOLS-STx Version: 3.9

These bugs were known to exist at the time of the release and are proving difficult, if not impossible to fix.

Interface

Sometimes 44KB soundfiles are created, which are invalid. This bug has not proved easy to replicate, so if you can replicate it, please contact us ( \n This e-mail address is being protected from spam bots, you need JavaScript enabled to view it ).

Can't delete an entry in the DataSet if it has no ID. It is highly unlikely that you will ever have a DataSet entry with no ID. If this is the case however, you must currently delete it by hand (Close S_TOOLS-STx, open the DataSet in a text editor and either give the offending entry an ID, or remove it). Should you be able to reproduce any action which creates an entry without an ID, please contact us ( \n This e-mail address is being protected from spam bots, you need JavaScript enabled to view it ).

Spectrogram & Parameters Viewer

Interpolation of very short signals is incorrect (Deutsch - 2004-11-10 - since 1.0).

Graphics

Copying a display graphic to the clipboard and pasting into a graphics program does not always achieve the desired results. This bug will not be fixed in the foreseeable future. Some graphics programs paste it properly (IrfanView, Microsoft Word), others don't (PaintShop Pro) - (Jonnie White - 2004-07-14).

Selected cursors is not visible if background is set to GRAY (White - 2004-07-12 - since 1.0).

Macro

The dialog control listbox does not handle displaying huge strings properly. This seems to be a problem with the underlying CListBox control (Becker/White - 2004-12 - since 1.0).

The DCOM command INVOKEMETHOD Evaluate always returns an error when communicating with the R DCOM server even if the command was actually successful (Deutsch/White - 2004 - since 3.6.0).

==3.8==

3.8.3

* BUGFIX: zoom in in viewer3 now working when zooming around active cursor
* BUGFIX: spectragram title display corrected (amin/amax)
* BUGFIX: CDLGMAP now deletes window only if it has created the window during construction

3.8.2

* BUGFIX: dataset path now displayed, even if it has spaces in it.
* BUGFIX: Parameter plot explicitly redrawn when new data is sent. This fixes the bug (reported by Julia Brandstaetter) where Set Zero and Undo were not working properly in Spectrogram and Parameter plot.

3.8.1

* BUGFIX: Warn user that more waveform samples are being sent than expected and refrain from crashing.
* BUGFIX: CDlgMap now always uses the next free dialog index for a new entry. This means that multiple maps can reference the same dialog and still work. The functions fci and nc were removed since they are never used. Display now using second event to synchronise creation and variable initialisation. This fixes the mysterious bug where the window class was only sometimes used.
* BUGFIX: If the polyline function is called with less than two points it no longer asserts, but rather ends gracefully.
* BUGFIX: send keys not processed by dialog on to graph hotkey handlers
* BUGFIX: spectrogram is now being initialised with the correct context menu when formants are displayed in it.
* BUGFIX: giving dialog focus if there are no graphs
* BUGFIX: buttons in dialogs in a graph no longer process normal mneumonics. This means that the graph can process them (for Moosmueller). Buttons can still be activated with return and the space bar and tabbed/arrowed to.
* BUGFIX: preventing race conditions in Attach/Detach. This removes one possible cause of autosave crashing. It does not guarantee, though, there to be no other reasons for autosave to crash.

=Downloads=
The {{STX}} downloads are available here: https://www.kfs.oeaw.ac.at/pub/stx

Template:VERSION

2020-12-30T05:59:42Z

Jw:

5.0.6

Main Page

2020-12-30T05:55:55Z

Jw: /* Download */

== {{STx}} {{VERSION}}==

{{STX}} is a software tool for the analysis, signal processing and annotation of Wave sound files. {{STX}} runs on the Windows operating system. It was originally a port of the S_TOOLS application for dedicated DSP hardware developed at the [https://www.kfs.oeaw.ac.at Acoustics Research Institute] in the 1980s. This documentation is work in progress and by no means complete. If you fail to find something you need, please [[Contact|get in touch]] with the development team.

=== Using {{STx}} ===

* [[User_Guide|User Guide]]
* Introductory Video: [https://kfsmail.kfs.oeaw.ac.at/owncloud/index.php/s/cbMjVjgQLZGjYk8 The Compact Workspace]

=== {{STx}} Programming ===

* [[Programmer_Guide/STx_Guru|Starting with {{STx}} Programming]]
* [[Programmer_Guide|Programmer Guide]]
* [[Programmer_Guide/Quick_Reference|Quick Reference]]

=== About {{STx}} {{VERSION}} ===

* Platform: runs on Windows Vista and higher
* [[History of Changes]]
* [[Known Bugs]]
* [[Feature Requests]]
* [[Contact]]
* [[Running STx under Linux or macOS]]

=== Download ===

[https://s02kfs1.kfs.oeaw.ac.at/pub/stx/stx-5.0.6.10071-freeware.exe STx 5.0.6]

[https://s02kfs1.kfs.oeaw.ac.at/pub/stx/ older releases]

==MediaWiki Links==
* [[STx Documentation Style Guide|Style guide]] for documenting {{STx}} in this wiki.
* Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using the wiki software.
* [http://www.mediawiki.org/wiki/Manual:Configuration_settings Configuration settings list]
* [http://www.mediawiki.org/wiki/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list]
__NOTOC__

User Guide/SPExL/Transcription Script

2020-11-27T11:08:37Z

Jw:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{User Guide}}
{{SPExL}}
{{Hotkeys}}
[[File:stx_ug_spexl_transcription.png|thumb]]

The 'Transcription' script is a tool in {{STX}} specifically written for transcribing sound files. The idea is to make transcribing as simple and efficient as possible. In addition to using the mouse, you can do the transcribing with the keyboard alone. The hotkeys are user-definable.

<div class="noautonum">
{{TOC limit|2}}
</div>

You will find it in the bottom left-hand corner of the [[User_Guide/Workspace|Workspace]] where it is called <code>Transcription</code>.

When starting the Transcription script, you must select the sound file in the Workspace you wish to transcribe. This is unlike the [[User_Guide/Workspace/Application_and_Setup_Tree/Signal_Analysis_and_Display/Profile|analysis profiles]], which analyse a segment. The following dialog will then appear.

[[File:Stx_transcription_startup_dialog.png]]

==Spectrogram / Waveform Views==
You can display either a spectrogram or a waveform of the sound file (or both). There three different combinations available:
===Whole file as waveform, with section as spectrogram===
This view displays a waveform of the whole file and a spectrogram of a section of that file. This means that you can see all the segments in the file in the waveform graph. Navigating around the file in the waveform, you can then view a section of it as a spectrogram (e.g. with the hotkey <kbd>S</kbd>). When starting the transcription script, choose '''wave overview & spg. section'''.

===Section of file as waveform===
This is the fastest view, displaying a section of the sound file as a waveform. The whole of the file is available to scroll through. When starting the transcription script, choose '''wave only'''. The length of signal displayed is specified by the scrollbar '''Length''' value in the start-up dialog. You can then scroll through the sound file using, for example, the hotkeys <kbd>M</kbd> (forwards) and <kbd>N</kbd> (backwards).

===Section of file as synchronised waveform and spectrogram===
This view displays a section of the sound file as both a waveform and a spectrogram. The waveform and spectrogram are time-aligned. The initial length of analysed signal is determined by the '''Length''' value in the start-up dialog. You can zoom in and out of the signal as well as scroll through the whole sound file.

Note that the '''Fixed''' checkbox will mean you can zoom into a signal, but cannot zoom out to display more of the signal than the length specified by 'Length'.

==Dialog Description==

[[file: Spexl_dialog.png]]

===timebar===
The timebar lets you scroll through the sound file. This is useful, if you have a large sound file, and therefore only load part of it at any one time.
* The <samp>|<</samp> button scrolls back to the beginning of the file.
* The <samp><</samp> button scrolls back one step.
* The <samp>></samp> button scrolls forward one step.
* The <samp>>|</samp> button scrolls to the end of the file.
* The <samp>Play</samp> button plays the whole signal currently loaded from disk.
* The <samp>Draw</samp> button redraws the section of the sound file specified by the scroll bar (if <samp>auto</samp> is unchecked).
* The <samp><Seg</samp> and <samp>Seg></samp> buttons scrolls to the previous and next segments outside of the current loaded signal. This can be useful, if you have a long file with few segments in it.
* If the <samp>auto</samp> setting is checked, then moving the scroll bar automatically redraws the graphs. This is the default. If unchecked, you must explicitly press the <samp>Draw</samp> button.

If you are already viewing the entire sound file, the time bar is not very useful. See [[#Scrolling|Scrolling]] for further details.

===spec.===
The <samp>spec.</samp> area of the dialog is only enabled if the spectrogram graph (<samp>wave & spg. section</samp> or <samp>wave overview & spg. section</samp> view) is being used. Choose the 1st or 2nd frame/overlap settings specified in the [[User_Guide/SPExL/Settings#Spectrogram_Display_and_Parameter_Setup|settings dialog]].

===f0/for.===

The F0 and formants can be calculated for the displayed spectrogram. This is not available in the <samp>wave only</samp> view. See [[User_Guide/Transcription_Script#F0_.2F_Formant_Extraction|F0 and Formant Extraction]] for further details.

===main===

Here you can save changes you've made to your segments ([[File:resource_dosave.png]]), revert any changes you have made since you last saved the project file ('Revert'), open the settings dialog ([[File: Resource setup.png]] or exit the transcription script.

===playback===

The playback section of the dialog can be used to play the sound file. The most interesting setting is the ability to repeat the signal when played, which can be useful when transcribing. Alternatively you can repeat the signal forever (or until the ESC key is pressed).

===cursor control===

In addition to moving the cursors around by clicking and dragging in the graph, you can also do it with these buttons. All buttons are also associated with [[#Hotkeys|hotkeys]].

==Scrolling==

Since displaying a long sound file can take a while, it can be useful to load only part of the sound file. This is achieved with scrolling in the <samp>wave only</samp> and <samp>wave & spg. section</samp> [[User_Guide/Transcription_Script#Spectrogram_.2F_Waveform_Views|views]]. The lowest graph displays the section of the sound file which is loaded (purple) and visible (brown).

Note that the <samp>wave overview & spg. section</samp> [[User_Guide/Transcription_Script#Spectrogram_.2F_Waveform_Views|view]] always loads the whole sound file.

==F0 / Formant Extraction==
You can display the F0 and formants in the spectrogram by pressing the [[File: Resource run.png]] button. The settings for extraction are in the [[User Guide/SPExL/Transcription_Script/F0_Formant_Extraction_Settings|F0 / Formant Extraction Settings]] dialog reached by pressing the 'f0/for' button [[File: Resource setup.png]].

==Settings==
There are many settings you can change via the [[User Guide/SPExL/Transcription_Script/Settings|Settings]] dialog reached by the 'main' [[File: Resource setup.png]] button, or the 'settings->setup dialog' context menu.

==Hotkeys==

Many operations are available using hotkeys.

===User Defined Hotkeys===

As of version 1.1, these hotkeys can be changed by the user by modifying the <samp>spexl_segtrans.hotkeys</samp> file. The default hotkeys are defined in the file <samp>spexl_segtrans.hotkeys.default</samp>. These files are in the <samp>profiles</samp> directory in {{STX}} >= 5.0 and in the <samp>scripts</samp> directory in {{STX}} <= 4.4.10.


==Versions==
Note that versions > 1.0 require {{STX}} >= 4.4

===1.1.10===
* bugfix: Playlist listview now processes listsorted message and displays sort order set by clicking a column heading. The sort order was first being displayed when clicking in the control after clicking the column heading.
===1.1.9===
* feature: removed the now unnecessary 'autoDraw' function.
* bugfix: use 'ID' as default attribute for text in segments where no attribute is specified.
===1.1.8===
* feature: removed the now unnecessary 'Refresh' button
===1.1.7===
* bugfix: the /U ASegTemplate flag is now respected, and, if used, the last entered value for a segment attribute is used as the default for the next new segment.
===1.1.5===
* bugfix: segment placement algorithm no longer drawing segments off screen.
* bugfix: moving scrollbar no longer generates an error message in the log window.
Download [https://www.kfs.oeaw.ac.at/pub/stx/spexl/ Transcription script downloads].

User Guide/SPExL/Transcription Script

2020-11-27T05:33:56Z

Jw:

User Guide/Spectrum Viewer

2020-11-27T05:05:21Z

Jw:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{V3}}
[[file:stx_ug_spectrum_viewer.png|thumb]]
The {{Viewer3}} application computes and displays the averaged spectra as defined by the [[User Guide/Spectrum Viewer/Settings|spectrum settings]]. The spectra can be saved in the project.

==Methods==

The {{Viewer3}} implements the following analysis methods:
* [[/Method/Cepstrum_Smoothing/|Cepstrum Smoothing]]
* [[/Method/LPC Transfer Function/|LPC Transfer Function]]
* [[/Method/Wavelet Amplitude Spectrum and Phase/|Wavelet Amplitude Spectrum and Phase]]

==Settings==

You can setup your spectrum analysis in the [[User_Guide/Spectrum_Viewer/Settings|Settings]] dialog, available if you double click a Spectrum Viewer [[User_Guide/Workspace/Application_and_Setup_Tree/Signal_Analysis_and_Display/Profile|profile]] in the [[User Guide/Workspace|Workspace]].

==Pre-Configured Profiles==

*Default
*CEP Spectrum Magnitude
*LPC Spectral Magnitude

==Hotkeys, Context Menu, Copy & Print Dialog==

The available hotkeys are documented [[User Guide/Spectrum_Viewer/Hotkeys|here]]. The context menu is documented [[User Guide/Spectrum Viewer/Context Menu|here]]. The Copy/Print dialog is documented [[User Guide/Copy or Print Dialog|here]].

User Guide/Spectrum Viewer

2020-11-27T05:05:09Z

Jw:

Programmer Guide/Macro Library/XPlot

2020-02-20T09:08:38Z

Jw: /* Plot */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}

{{TOC limit|4}}

==XPlot : CObjEx==

A general class for plotting multiple graphs.

===XPlot Construction===

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

<div class="sourcelabel">Usage:</div>

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

<div class="sourcelabel">Parameters:</div>

;<var>rows</var>

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

;<var>columns</var>

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

;<var>title</var>

:The display window title.

;<var>profile</var>

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

;<var>window</var>

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

;<var>owner</var>

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

<div class="sourcelabel">Result:</div>

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

<div class="sourcelabel">Examples:</div>

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

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

===XPlot Member Functions===

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

====AddPlot====

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

====Dialog====

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

<div class="sourcelabel">Usage:</div>

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

<div class="sourcelabel">Parameters:</div>

;<var>cmd</var>

:The following commands are available: New|Delete|Msg|On|Enabled|Off|Hidden. See below for details.

;<var>args</var>

:See below for details.

<div class="sourcelabel">Result:</div>

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

=====<code>New</code>=====

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

<div class="sourcelabel">Usage:</div>

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

;<var>pos</var>:Sets the position of the dialog within the display. The following values are supported:

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

=====<code>Delete</code>=====

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

<div class="sourcelabel">Usage:</div>

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

=====<code>Msg</code>=====

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

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

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

<div class="sourcelabel">Usage:</div>

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

<div class="sourcelabel">Parameters:</div>

;<var>msgid</var>

:The message ID.

;<var>msgpar</var>

:The message parameters.

=====<code>On|Off|Enabled|Disabled</code>=====

Show the dialog and set it's position.

<div class="sourcelabel">Usage:</div>

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

<div class="sourcelabel">Parameters:</div>
;<var>mode</var>:Turns the dialog on or off and enables or disables it if it is on. The following keywords are supported:
:<code>ON|OFF|ENABLED|DISABLED</code>

;<var>pos</var>:Sets the position of the dialog within the display. The following values are supported:

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

====Display====

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

<div class="sourcelabel">Usage:</div>

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

<div class="sourcelabel">Result:</div>

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

====End====

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

====Get====

Retrieve an attribute from a specific graph.

<div class="sourcelabel">Usage:</div>

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

<div class="sourcelabel">Parameters:</div>

;<var>adr</var>

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

;<var>attribute</var>

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

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

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

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

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

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

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

====GetFColors====

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

<div class="sourcelabel">Usage:</div>

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

<div class="sourcelabel">Result:</div>

Returns a blank separated list of color keywords.

====Graph====

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

<div class="sourcelabel">Usage:</div>

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

<div class="sourcelabel">Parameters:</div>

;<var>adr</var>

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

;<var>attr</var>

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

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

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

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

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

<div class="sourcelabel">Result:</div>

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

<div class="sourcelabel">Examples:</div>

Get the graph item id for the top left graph.

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

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

<div class="sourcelabel">Usage:</div>

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

<div class="sourcelabel">Parameters:</div>

;<var>graph</var>

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

;<var>unit</var>

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

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

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

;<var>x, y</var>

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

;<var>w, h</var>

:The width and height of one legend line.

;<var>color</var>

:The legend text color.

;<var>info</var>

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

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

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

;<var>textX</var>

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

<div class="sourcelabel">Result:</div>

void

====Plot====

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

=====XYPLOT=====

Plot an x/y function graph.

<div class="sourcelabel">Usage:</div>

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

<div class="sourcelabel">Parameters:</div>

;<var>adr</var>

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

;<var>y</var>

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

;<var>x</var>

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

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

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

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

;<var>title</var>

:The title to be displayed in this plot.

;<var>xr</var>

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

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

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

;<var>xu</var>

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

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

;<var>xt</var>

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

;<var>yr</var>

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

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

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

;<var>yu</var>

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

;<var>yt</var>

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

;<var>fstyles</var>

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

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

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

<div class="sourcelabel">Result:</div>

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

<div class="sourcelabel">Examples:</div>

Plot a simple x/y function.

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

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

<div class="sourcelabel">Usage:</div>

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

<div class="sourcelabel">Parameters:</div>

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

<div class="sourcelabel">Result:</div>

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

=====PARAMETER=====

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

<div class="sourcelabel">Usage:</div>

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

<div class="sourcelabel">Parameters:</div>

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

<div class="sourcelabel">Result:</div>

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

=====SPECTROGRAM=====

Plot a spectrogram graph.

<div class="sourcelabel">Usage:</div>

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

<div class="sourcelabel">Parameters:</div>

;<var>d</var>

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

;<var>y</var>

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

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

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

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

;<var>zr</var>

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

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

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

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

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

=====WATERFALL=====

Plot a waterfall graph.

<div class="sourcelabel">Usage:</div>

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

<div class="sourcelabel">Parameters:</div>

;<var>d</var>

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

;<var>zr</var>

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

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

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

;<var>zu</var>

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

;<var>zt</var>

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

;<var>xw</var>

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

;<var>yw</var>

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

;<var>n</var>

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

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

=====WAVEFORM=====

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

<div class="sourcelabel">Usage:</div>

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

<div class="sourcelabel">Parameters:</div>

;<var>wave</var>

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

;<var>xu</var>

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

;<var>ymax</var>

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

;<var>yr</var>

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

;<var>fill</var>

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

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

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

Plot a graph containing text.

<div class="sourcelabel">Usage:</div>

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

<div class="sourcelabel">Parameters:</div>

;<var>title</var>

:The graph title.

;<var>color</var>

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

;<var>halign</var>

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

;<var>valign</var>

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

;<var>text</var>

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

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

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

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

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

;<var>linestyle</var>

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

;<var>linecol</var>

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

;<var>printcol</var>

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

;<var>linewidth</var>

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

;<var>drawstyle</var>

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

;<var>drawsym</var>

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

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

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

;<var>ymiss</var>

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

====Redraw====

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

<div class="sourcelabel">Usage:</div>

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

<div class="sourcelabel">Parameters:</div>

;<var>adr</var>

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

<div class="sourcelabel">Result:</div>

Return 0 if successful.

====ScaleOctave====

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

<div class="sourcelabel">Usage:</div>

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

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

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

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

<div class="sourcelabel">Parameters:</div>

;<var>df</var>

:The frequency resolution in Hz.

;<var>count</var>

:The number of frequency points.

;<var>fmax</var>

:The maximum frequency to be displayed.

;<var>fmin</var>

:The minimum frequency to be displayed.

;<var>vector</var>

:The scale range as a data vector.

<div class="sourcelabel">Result:</div>

The following string is returned:

<code>xmin xmax xlabTab xdata</code>

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

<div class="sourcelabel">Examples:</div>

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

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

See also ScaleSteps.

====ScaleLog10====

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

<div class="sourcelabel">Usage:</div>

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

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

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

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

<div class="sourcelabel">Parameters:</div>

;<var>df</var>

:The frequency resolution in Hz.

;<var>count</var>

:The number of frequency points.

;<var>fmax</var>

:The maximum frequency to be displayed.

;<var>fmin</var>

:The minimum frequency to be displayed.

;<var>vector</var>

:The scale range as a data vector.

<div class="sourcelabel">Result:</div>

The following string is returned:

<code>xmin xmax xlabTab xdata</code>

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

<div class="sourcelabel">Notes:</div>

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

====ScaleSteps====

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

<div class="sourcelabel">Usage:</div>

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

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

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

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

<div class="sourcelabel">Parameters:</div>

;<var>min, max</var>

:The scale range.

;<var>vector</var>

:The scale range as a data vector.

;<var>labelDist</var>

:The label distance in scale units.

;<var>majorGridDist</var>

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

;<var>majorTickDist</var>

:The distance between major ticks in scale units.

;<var>minorGridDist</var>

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

;<var>minorTickDist</var>

:The distance between minor ticks in scale units.

<div class="sourcelabel">Result:</div>

The following string is returned:

<code>min max labTab</code>

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

<div class="sourcelabel">Examples:</div>

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

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

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

====Set====

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

<div class="sourcelabel">Usage:</div>

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

<div class="sourcelabel">Parameters:</div>

;<var>xgraph</var>

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

;<var>attr</var>

:One of the following values:

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

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

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

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

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

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

;<var>args</var>

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

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

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

:Where mode is one of the following values:

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

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

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

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

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

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

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

<div class="sourcelabel">Result:</div>

No return value.

====SetCallback====

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

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

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

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

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

<div class="sourcelabel">Usage:</div>

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

<div class="sourcelabel">Parameters:</div>

;<var>cbfunction</var>

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

<div class="sourcelabel">Result:</div>

No return value.

====SetWave====

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

<div class="sourcelabel">Usage:</div>

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

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

<div class="sourcelabel">Parameters:</div>

;<var>adr</var>

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

;<var>waveitem</var>

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

<div class="sourcelabel">Result:</div>

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

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

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

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

===XPlot Examples===

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

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

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

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

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

[macro xplot_example_2]

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

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

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

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

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

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

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

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

exit 1 int 0
</pre>

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

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

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

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

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

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

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

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

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

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

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

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

end

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

// message filter for keystroke messages

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

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

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

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

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

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

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

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

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

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

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

end

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

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

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

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

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

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

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

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

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

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

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

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

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

// return averaged spectrum
exit 1 set $#spg

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

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

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

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

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

else
// compute complex spectra

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

end

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

// return spectrogram matrix
exit 1 set $#spg

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

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

//
// local subroutines
//

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

Main Page

2019-11-12T08:33:11Z

Jw: /* Download */

== {{STx}} {{VERSION}}==

{{STX}} is a software tool for the analysis, signal processing and annotation of Wave sound files. {{STX}} runs on the Windows operating system. It was originally a port of the S_TOOLS application for dedicated DSP hardware developed at the [https://www.kfs.oeaw.ac.at Acoustics Research Institute] in the 1980s. This documentation is work in progress and by no means complete. If you fail to find something you need, please [[Contact|get in touch]] with the development team.

=== Using {{STx}} ===

* [[User_Guide|User Guide]]
* Introductory Video: [https://kfsmail.kfs.oeaw.ac.at/owncloud/index.php/s/cbMjVjgQLZGjYk8 The Compact Workspace]

=== {{STx}} Programming ===

* [[Programmer_Guide/STx_Guru|Starting with {{STx}} Programming]]
* [[Programmer_Guide|Programmer Guide]]
* [[Programmer_Guide/Quick_Reference|Quick Reference]]

=== About {{STx}} {{VERSION}} ===

* Platform: runs on Windows Vista and higher
* [[History of Changes]]
* [[Known Bugs]]
* [[Feature Requests]]
* [[Contact]]
* [[Running STx under Linux or macOS]]

=== Download ===

[https://www.kfs.oeaw.ac.at/pub/stx/stx-5.0.4.10016-freeware.exe STx 5.0.4]

[https://www.kfs.oeaw.ac.at/pub/stx/ older releases]

==MediaWiki Links==
* [[STx Documentation Style Guide|Style guide]] for documenting {{STx}} in this wiki.
* Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using the wiki software.
* [http://www.mediawiki.org/wiki/Manual:Configuration_settings Configuration settings list]
* [http://www.mediawiki.org/wiki/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list]
__NOTOC__

Template:VERSION

2019-11-12T08:32:53Z

Jw:

5.0.4

History of Changes

2019-11-12T08:32:18Z

Jw: /* 5.0.3 */

<div class="noautonum">{{TOC limit|3}}</div>
=5.0=

==Features==

===Compact Workspace Mode===
The Workspace now has a [[User_Guide/Workspace#Modes|compact mode]]. The compact mode is a simplified interface for new users. Although it was designed with linguists in mind, it can be used by anyone.

===webMAUS===
Automatic segmentation using the [https://clarin.phonetik.uni-muenchen.de/BASWebServices/interface webMAUS] REST API. This has been implemented in the toolbox [[User_Guide/Toolbox/runMAUSBasicDlg|<samp>runMAUSBasicDlg</samp>]].

==Bugfixes==

* Correctly handle corrupt Workspace file (generate new one, rather than silently exiting)

==5.0.4==

Released: 12th November 2019

Revision: 10016

* bugfix: SPExL V1.1.11. Adding new segments respects vertical drawing order.
* bugfix: SPExL V1.1.11. Faster deselection of segments.
* bugfix: Real-time waterfall axis drawing correctly
* bugfix: show/hide sectioner setting now respected.
* bugfix: sectioner height setting now respected.

==5.0.3==

Released: 1st October 2019

Revision: 9967

* feature: Signal.All is now selected by default, if no other segment is selected.
* feature: When exporting profiles, the present working directory is used, rather than always selecting the 'profiles' directory. The profiles directory is only used if the present working directory is the root directory.
* feature: The first sound file in the project is selected by default in the compact mode.
* bugfix: When adding a file per drag and drop, the file is now selected.
* bugfix: enabling a disabled edit box now sets the background color correctly (back to white).
* bugfix: debugger trace window now visible in release version too
* bugfix: [[Programmer_Guide/Command_Reference/SYSINFO|SYSINFO]] command now supports Windows 8.1 and Windows 10 (was returning Windows 8)
* bugfix: SPExL V1.1.10. Playlist listview now processes listsorted message and displays sort order set by clicking a column heading. The sort order was first being displayed when clicking in the control after clicking the column heading.
* bugfix: The 'Start' button should now be activated correctly in the Compact Mode.

==5.0.2==

Released: 19th September 2019

Revision: 9946

* bugfix: The context menu Add Sound File now working from the Audio File list in the Compact Mode.
* feature: The possible number of plots in XPlot was increased from 64 to 128

==5.0.0==

Released: 12th September 2019

Revision: 9935

Initial release.

=4.4=

==Features==
===Transcription Script SPExL 1.1.6===
The transcription script SPExL has been simplified and improved.
* Hotkeys can be defined by the user in the SPExL_SegTrans.hotkeys file
* The number of available 'views' has been reduced to 3:
** wave overview & spg. section (a waveform of the whole file in the top graph, with a section of the file as spectrogram below)
** wave only (a waveform of a section of the file with scrollbar functionality)
** wave and spg. section (a synced waveform and spectrogram of a section of the file with scrollbar functionality)
* Segment selection between graphs and the list are now synchronised. If you select a segment in the graph, it is selected in the list and vice versa.
* Changes made to the project (new segments, edited attributes) are now made directly in the project rather than the user having to explicitly press the 'save segments to project file' button to copy them from SPExL to the Workspace. Note that they are only written to disk, however, if the project is saved (press the 'Save' button).
===Visible Segment Attributes Saved per Project File===
If you choose to display other attributes other than the default attributes in the Workspace Detail View, these settings are now saved in the open project file. When a project file is then opened, the relevant attribute list is loaded and used, rather than the user having to [[User_Guide/Workspace/Detail/Search_for_Element_Attributes|search for them]] again. You can still modify which attributes are displayed using the General Settings [[User_Guide/Workspace/Application_and_Setup_Tree/Options/General_Settings#.22Set.22_Attributes_.26_.22Segment.22_Attributes|'Select "Segment" Attributes' dialog]].
===Global / Profile Sectioner Settings===
The sectioner settings in the {{Viewer2}} analysis application were always global to STx. As of STx 4.4.0, you can choose to save your sectioner settings with your profile. The default is still the 'global' variant. To switch to profile sectioner settings, uncheck the '''use global sectioner settings''' checkbox in the {{Viewer2}} [[User_Guide/Spectrogram_and_Parameter_Viewer/Settings_Dialog|settings dialog]].

==4.4.10==

Released: 17th January 2019

Revision: 9712

* bugfix: playback gain factor - the playback gain is now working also for asio devices (see CSTXASIOEngine::Transfer())
* bugfix: renumbering command did not update detail as expected.
* bugfix: the update version dialogs now display the correct workspace path

==4.4.9==

Released: 25th September 2018

Revision:

* feature: don't ask user where to put sound file if there are no sets in the project.
* feature: dragging and dropping a template onto {{ST}X} copies it to the templates folder.
* feature: added 'Open Containing Folder' context menu for sound files and links. Improved contextualisation of context menu in detail (overview==root/set)
* feature: 'txt2wav' script: Adding decimal symbol and field delimiter to parameters, as well as the ability to specify which extension to use to filter files (was hard-coded to 'txt'). Now this macro can be used to
* feature: bdataset createwave and createwwaveex now take an openmode keyword: auto|create|read|write, which is passed on to bsf open. This means that we can now open files in modes other than 'auto'.
process CSV files.
* bugfix: very long capture text for edit controls with 'text above' could lead to capture static being longer than the edit control and unintentionally overlapping with other controls (e.g. in Transcription Setup dialog).
* bugfix: closing con log window no longer resets PARENT shell variable, unless it is set the the con log window itself.
* bugfix: sound files now opened using the FILE_SHARE_READ dwShareMode. This should mean, that STx no longer prevents other processes from reading the sound files.
* bugfix: viewer opens sound file in read mode, rather than read/write.
* bugfix: the !PATH attribute (MakePath()) now returns the correct path for files in the root of a drive. Bug was introduced in r8998 (STx 4.2.19). This was, for example, was causing sound files in the root directory not to be unloaded, and hence was causing sharing violations.

==4.4.8==

Released: 25th July 2018

Revision: 9500

* feature: Spectrogram & Parameters viewer sectioner window now remembers which function cursor is bound to when being replotted.
* feature: The <samp>downsampling.sts</samp> script now has a <samp>ResampleCLI</samp> macro for automatic resampling of one or more files (see source). The old <samp>ResampleDialog</samp> was renamed to <samp>ResampleDLG</samp>.
* feature: Adding help for "Import_PRAAT_TextGrid" toolbox.
* feature: Adding ability to edit 'Sectioner Settings' from the profile dialog.
* feature: Transcription 1.1.8 - removed segment 'refresh' button, since segments always reflect current project state.
* bugfix: a window that was maximised will now be maximised to the correct monitor. It was always being maximised to monitor 1 on display creation.
* bugfix: the profile version number is now imported with the profile. This means that, for example, the use global profile settings flag is now also set correctly on import.
* bugfix: minor fix of position of two controls which were overlapping with controls beneath
* bugfix: stop playback cursor if wave is stopped by starting playback in another graph. Beforehand, the playback cursor was stopped if it got to the end, or the ESC key was pressed.
* bugfix: Y coordinate vector conversion was inaccurate by 1 pixel (bug introduced in r2536) This affects the XY, parameter, scatter, wave and waterfall functions.

==4.4.6==

Released: 21. March 2018

Revision: 9441

* bugfix: some bugfixes and minor changes in BSeq
* bugfix: BScript: logging of unhandled messages in msg-loop disabled // Conlog: /ton and /toff options implemented (timer on/off + show elapsed time)
* bugfix: Viewer3 settings now being saved (bug introduced in r9318 - STx 4.4.0)
* bugfix CShellFile::Status() - catch CTime exception if file time is illegal (avoid program crash)

==4.4.5==

Released: 19. February 2018

Revision: 9416

* bugfix: in Viewer2 large asegtemplates (with many fields) are now displayed correctly - note: the same problem exists in Viewer1 if the segment dialog part (created by the macro call ""metasegment msdialog") needs more than 90 controls (around 40 segment attributes)
* feature: the bscript.stx function loaddata (con loaddata) can now also load string tables (extenden tables) from csv-files. The file types TEXT/TEXTCONTINUATION (numeric parameter table), STRING/STRINCONTINUATION (extended string table) and BINARY (binary stx-data files) are available. Type ASCII/ASCIICONTINUATION has been removed.
* feature: new feature (bugfix?): CShellTable::Read() - handling of field-separator tab has been changed - empty fields are now possible - warning: may have an effect on existing script/macro code!

==4.4.4==

Released: 26. January 2018

Revision: 9404

* bugfix: combobox entries with underliners retain their underliners now in the workspace detail (reported by Anton Baotic), and in Spexl.

==4.4.3==

Released: 18. December 2017

Revision: 9391

* bugfix: adding missing Transcription hotkey file and retisimo scripts

==4.4.2==

Released: 30. November 2017

Revision: 9377

* bugfix: SPExL Transcription script V1.1.7: the /U ASegTemplate flag is now respected, and, if used, the last entered value for a segment attribute is used as the default for the next new segment.
* bugfix: default profile names no longer have the invalid blank character in them. A check was also added, so new profiles cannot be created with blanks.

==4.4.1==

Released: 23. November 2017

Revision: 9369

* bugfix: if zooming is turned off in {{Viewer2}}, segments are now correctly visible on the Y axis. This bug has existed since at least STx 4.2.

==4.4.0==

Released: 14 November 2017

Revision: 9350

Initial release.

=4.3=

==Features==
====Load or export parameters from super or sub segments====
Parameters from super segments or from sub segments can now be loaded into the selected segment. For example, if you have analysed a word and corrected the parameters, you can use these corrected parameters when viewing phoneme segments within the word. This is achieved by selecting 'super segment data only' setting in the Viewer settings [[User_Guide/Spectrogram_and_Parameter_Viewer/Settings_Dialog#Parameter_IO_Configuration|Parameter IO Configuration]] dialog.

It is possible to select which super/sub segment parameters should be used, filtering by time, attribute or ID.

This feature is also available in the parameter export dialog.

====Parameter setting summary====
A summary of the settings used for parameter analysis is now saved with the parameter in the project file. This information is displayed in the [[User_Guide/Workspace/Detail/Views/Parameter_View|Parameter View]].

====Exact sample positioning in {{Viewer2}}====

You can now select a position in the [[User_Guide/Spectrogram_and_Parameter_Viewer#Waveform_zoom_window|Waveform Zoom window]] in {{Viewer2}} and move the active time cursor to that position using the hotkey '1'. This is useful for exact positioning of the time cursors when segmenting, for example, words.

==4.3.10==

Released: 26. January 2018

Revision: 9407
*bugfix: do not allow user to give a profile a name including blanks.
*bugfix: renaming spectrum profiles (removing blanks)
*bugfix: the correct most recently entered value in a listctrl is now saved (not the last in the list).
*bugfix: passing delete, insert and back keys to static control.
*bugfix: 'spexl*.hotkeys.default' 'retisimo.sts' 'retisimo_*.sts' 'HRTF_II_new.txt' 'downsample.sts' files are now being copied too (bug introduced in r8789)
*bugfix: removing extraneous / from Editing segments help URL
*bugfix: combobox entries with underliners retain their underliners now in the workspace detail (reported by Anton Baotic), and in Spexl.

==4.3.9==

Released: 23. November 2017

Revision: 9363

* bugfix: if zooming is turned off in {{Viewer2}}, segments are now correctly visible on the Y axis. This bug has existed since at least STx 4.2.

==4.3.8==

Released: 14. November 2017

Revision: 9347

* bugfix: zooming and replotting in the xplot class now working
* feature: user is now informed about bugfixes in current release, and/or new major/minor releases. This means that you will be informed of bug fixes for your version of STx, not just for the newest STx.

==4.3.7==

Released: 19. October 2017

Revision: 9328

* bugfix: stx no longer crashing on y zoom (bug introduced in r9293 - STx 4.3.6)
* bugfix: binary_file_example.sts now working
* bugfix: if navigating in file dialog using the keyboard, the edit box is now updated with the selected file.

==4.3.6==

Released 25. September 2017

Revision: 9297

* bugfix: the spectrogram dataset now frees up memory once dataset is drawn
* bugfix: adding specials folder to installer

==4.3.5==

Released: 6. September 2017

Revision: 9286

* bugfix: auto-saving the project file no longer leaks memory
* bugfix: editing segments in the workspace now uses the segment template by default
* bugfix: a backup copy of the project file is now made when saving
* bugfix: lists with one item are now selectable with the keyboard
* bugfix: listview column width now calculated with correct font
* bugfix: default values from aseg templates now written to new segment before editing
* bugfix: correct default value written to segment, even if attribute value starts with a number
* bugfix: combobox entries no longer replacing underlines

==4.3.4==

Released: 3. July 2017

Revision: 9214

====Features====
* feature: the [[Programmer_Guide/Macro_Library/CONLOG|conlog]] command can now log to a file.
====Bug Fixes====
* bugfix: the conlog savedata command no longer fails silently if the file cannot be created.

==4.3.3==

Released: 19. June 2017

Revision: 9185

====Bug Fixes====
* bugfix: segment address in the Transcription script is now rounded to 10th of a millisecond (4 decimal places) rather than 1 millisecond.
* bugfix: saving the project file now resets the automatic save timer.
* bugfix: the Transcription, Import Word List and Reorder Word List should now be working correctly again.
====Features====
* feature: new script: [[User_Guide/Scripts/Anonymize.sts|Anonymize.sts]] - anonymize segments (attributes and signal) - requested by the ARI phonetics group
* feature: adding option to automatically save every minute.

==4.3.2==

Released: 13. June 2017

Revision: 9170

====Bug Fixes====
* bugfix: The segment 'Signal.All' is now created when a new sound file is imported. This bug was introduced in version 4.3.1.
* bugfix: the 'wave-only' view in the Transcription script is now available again.

==4.3.1==

Released: 8. June 2017

Revision: 9165

====Bug Fixes====

* bugfix: clicking SPExL graph whilst editing segment in the segment list now draws the segment in the graph (previously needed an explicit refresh to draw the segment).
* bugfix: the workspace is now saved even if the path contains spaces (bug introduced in r8843)
* bugfix: searching using keyboard in listctrl now working in correct order (not backwards). Bug introduced in r9002.
* bugfix: zooming out in SPExL on the y axis with Ctrl+Subtract is now working correctly. This appears to have been around since at least r4442 (STx 3.9)
* bugfix: y position of cursors is now retained when zooming
* bugfix: Viewers/SPEXL create segments at selected address and not with P=0 and L=0
* bugfix: maximising whilst spectrogram is drawing no longer leaves the spectrogram in unfinished version on screen (set new 'm_bRecalculate' flag to force recalculation/redraw when dataset sync has finished).

==4.3.0==

Released: April 2017

Revision: 9149

=Older Versions=

==4.2==
====4.2.23====
Released: 24 August 2017
Revision: 9264
* BUGFIX: correct font used for calculation of formant dialog column size in {{Viewer2}}

====4.2.22====
Released: 25 January 2017
Revision: 9064
* BUGFIX: The following wildcard string comparison will now match:
<pre>
if '*ha' =SI 'haha' then
// it's a match :-)
end
</pre>
* BUGFIX: Changed behavior of comparisons in FIND-TABLE/XML: if a field/attribute is not defined all "notequal" and "notmatching" operators evaluates to "true" and all others to "false"

====4.2.21====
Released: 9 January 2017
Revision: 9023
* BUGFIX: Edit segment dialog now referencing correct segment attributes (bug introduced in r8852 - STx 4.2.15)

====4.2.20====
Released: 23 December 2016
* FEATURE: STx now informs the user of available update via the About dialog.
* BUGFIX: Removing non-existent files from STX.INI when loading
* BUGFIX: About dialog no long blocking workspace file.

====4.2.19====
Released: 12th December 2016
* BUGFIX: Ctrl+U no longer the same as Ctrl+Shift+U in, e.g., signal view.
* BUGFIX: Generating correct hotkey string for Ctrl+Shift+<key>
* BUGFIX: Switching from long to short list of segments in the workspace should no longer lead to a blank detail.
* BUGFIX: Transcription left cursor right bitmap now correct image
* BUGFIX: Fixed bug in Viewer2 where setting the range did not work under all circumstances.
* BUGFIX: Focus moving with selection for listview key navigation and single selection.
* BUGFIX: Copy attributes in the Workspace overview now includes first value (bug introduced in r8297)
* BUGFIX: Checkbox size increased because some strings were being cut off.
* BUGFIX: Show Find Dialog menu now checked if Show Find Dialog is visible
* BUGFIX: Occasional crash in {{Viewer2}} fixed by removing use of static with CString (r9010,r9012).

====4.2.18====
Released: 27 October 2016

* FEATURE: adding PCM info to edit sound file dialog for editing existing project files too.
* FEATURE/BUGFIX: Improved listview keyboard handling (up/down, page up, page down). Disabled scrolling of listview whilst editing.
* BUGFIX: viewer2 no longer hangs if saved rmsb-data are loaded and displayed with autoscale-option
* BUGFIX: detail sequence view now using Ctrl+Shift+U to move selected entry up and Ctrl+Shift+D to move selected entry down (rather than Ctrl+UP and Ctrl+Down - which conflict with internal listview keyboard handling).
* BUGFIX: bscript log window no longer jumps in front of SPExL window when a dialog is opened.
* FEATURE: releases are now digitally signed by the Österreichische Akademie der Wissenschaften
* NOTE: the pole-zero sectioner in the {{Viewer2}} application is extremely slow for high frame rates. We are working on improving it.

====4.2.17====
Released: 26 September 2016
* BUGFIX: Transcription (SPExL) segment list handling working correctly again (bug introduced in 4.2.16)
* BUGFIX: Moving selected sequence entry up/down with keyboard now uses the hotkeys Ctrl+Shift+U and Ctrl+Shift+D (rather than Ctrl+Up and Ctrl+Down) and now works as expected.

====4.2.16====
Released: 30 August 2016
* Support for Windows XP has been removed.
* FEATURE: the XPLOT member "FORALLGRAPHS" is now a public function.
* FEATURE: the XGRAPH function Zoom -> X-Sync was aded to apply the x-zoom of the current graph across all other graphs.
* BUGFIX: the Automatic Segment Names dialog no longer allows invalid segment names.
* BUGFIX: The palette import/export are working again.
* BUGFIX: The Application and Setup tree now correctly stores it's state.
* BUGFIX: Keyboard focus no longer disappears after pressing enter in the Workspace Detail.
* BUGFIX: The selected entry no longer centers itself after editing.
* BUGFIX: The Transcription script SPExL now plays single selections every time (not every second time).
* BUGFIX: Tabbing through the entries in the Workspace Detail no longer goes backwards instead of forwards.

====4.2.15====
Released: unreleased
* FEATURE: Improved sound file export performance
* BUGFIX: The File->Workspace->Save As workspace menu command is now working (bug introduced in r4092)
* BUGFIX: parameter and function now drawing (invalidating) correctly if being set whilst zoomed in.
* BUGFIX: parameter export dialog no longer needs manual refresh (group box is now transparent - uses WS_EX_TRANSPARENT)

====4.2.14====
Released: 18 January 2016
* Minimising GDI use
* Projects files are now associated with {{STX}}
* BUGFIX: one memory leak fixed
* BUGFIX: all help menus associated with mediawiki online help
====4.2.13====
Released: 22 December 2015
* Default help file now the STx Wiki ([https://www.kfs.oeaw.ac.at/stx/docs/wiki/ https://www.kfs.oeaw.ac.at/stx/docs/wiki/]).
* BUGFIX: Find Segments dialog no longer uses ASet search criteria for ASeg search criteria when ASeg criteria is empty
* BUGFIX: Find Segments dialog can now search for segments within a time range.
* BUGFIX: assigning number values to an integer field using table[,field] := eval $#num1 + $#num2 syntax now works
* BUGFIX: growing table by assigning no longer corrupts heap.
*BUGFIX: force context menu to display within dialog window, even if called directly from shell with 0,0 coordinates.
*BUGFIX: edit segment dialog is now initialised with the segment channel
*BUGFIX: context menu now rebuilt before being displayed to ensure that it reflects current state.

====4.2.12====
Released: 4 December 2015
* Improved spectrogram 'overview' visualisation.

====4.2.11====

Released: 16 November 2015

* Added pole-zero to {{Viewer2}} Sectioner
* Bugfix: pane sizes are no longer reset in {{V2}} when sectioner settings dialog is closed.
* Bugfix: list view control header now correct size and clickable, and entries now selectable with one, rather than two clicks.
* Bugfix: copied attributes are no longer preceded by blank line

====4.2.9====

Released: 16 October 2015

* Bugfix: saving to PNG working again

====4.2.8====

Released: 5 October 2015

* Bugfix: the pole-zero method spectrogram overlay is now working correctly.

====4.2.5====

Released: 30 September 2015

* Feature: the pole-zero method is now available as an overlay in the spectrogram and parameter viewer's spectrogram graph. Note however, that this is not bug free, so please wait for 4.2.6 if you're interested in this feature.

====4.2.4====

Released: 10 September 2015

* Bugfix: added missing Visual C++ 2013 Redistributable Package

====4.2.3====

Released: 26 August 2015

* Metasegment size modification now locks modification mode

====4.2.2====

Released: 15 June 2015

* Viewer print font now legible

====4.2.0====

Released: February 2015

=====Features=====

* The speed of audio playback can now be set in the project interface
* The menu shell item has been given the alias 'DIALOG' and will now be refered to as such in the documentation (r8578)
* Pole-Zero [[Programmer_Guide/SPU_Reference/PZTF|SPAtom]] and [[Programmer Guide/Command Reference/EVAL/pztf|EVAL]] methods are now available and are integrated into the [[User_Guide/Spectrogram_and_Parameter_Viewer/Methods/Polezero|Spectrogram and Parameter viewer]].
* Support for Windows 2000/XP has been removed
* Pole-Zero SPU and EVAL methods
* Multiple bug fixes

==4.0==

===4.0.0===

Released: 2012

==3.9==

3.9.4

Released: 15th October 2009

* BUGFIX: real-time analyser drawing more smoothly

3.9.3

Released: 16th September 2009

* BUGFIX: sequences now being saved.

3.9.2

Released: 30th July 2009

* BUGFIX: segments no longer duplicated in un-linked datasets when importing metadata.
* BUGFIX: user-defined amplitude range working in waveform viewer
* BUGFIX: spectrogram amplitude floor now correct after using settings dialog
* BUGFIX: recorder application now recording

3.9.1

Released: 3rd July 2009

* BUGFIX: cmenu check/uncheck working for consecutive items
* BUGFIX: text files items and the load command can now read files encoded with an "FE FF" byte order mark (encoded in UTF-16BE). The error message "unsupported byte order mark" is returned if a UTF-32BE or UTF-32LE byte order mark is found.Supported encodings specified using a byte order mark: UTF-8, UTF-16LE, UTF-16BE<br /> Other supported encodings:windows-1252
* BUGFIX: wave files with chunks defined after the data chunk now have the correct length.
* BUGFIX: saving dataset faster
* BUGFIX: "load soundfile" options should no longer conflict with each other
* BUGFIX: prevent stack overflow in XML files with many siblings (~ 20000)
* BUGFXI: closing rtanalyser whilst it is running now exits shell correctly (without leaving ghost process).

3.9.0

Released: 15th April 2009

Graphical User Interface

General

S_TOOLS-STx now supports all fonts available on the host system.

Comboboxes in ASegTemplates can now be made editable using the flag <span class="stxmacrocommandoption-character">/E</span>.

You can enable/disable runtime error reporting in the Log Control dialog. It is disabled by default, and should only be enabled if you are having problems with S_TOOLS-STx.

Workspace

The segment list can now be edited in the Workspace.

A summary of existing parameters can now be displayed in the segment list (see the Display and Layout Settings dialog).

The Workspace Detail cells can now display text in multiple lines (see the Display and Layout Settings dialog).

Spectrogram & Parameters Viewer

The Spectrogram & Parameters Viewer can now display a harmonic cursor in the spectrogram graph.

The Spectrogram & Parameters Viewer spectrogram method Wavelet has been extended, and a new Cohen's class distribution method has been implemented.

An amplitude legend is now available in spectrogram plots (via the context menu).

DSP

The band-pass filters now have a window parameter.

Toolbox

The toolbox AutoSeg is available in Spectrogram & Parameters Viewer (if loaded) to automatically segment using peaks, clicks or pauses.

A range of Klatt speech synthesis and resynthesis toolbox functions are available.

The toolbox file 'SegmentImEx.sts' implements toolbox functions to import and export segments in the [http://www.fon.hum.uva.nl/praat/ PRAAT] file format. These functions are available in the Workspace.

Scripts

A script specifically designed for transcription and annotation has been developed and included in the default installation of S_TOOLS-STx. The script can be found in the script directory in the file SPExL.sts. There is also a new entry called transcription in the Workspace script tree, which calls the default segmentation routine. The SPExL macro documentation is still being written.

Macro Language

General

Modal window handling has now been moved to the NEW DISPLAY command. Use the option <span class="stxmacrocommandoption-character">/O=$#ownerDisplay</span> to set the owner (which is behind the new display in the z-order. You may also use the option <span class="stxmacrocommandoption-character">/Modal</span> to specify that the owner should be disabled whilst the new display exists.

The NEW command can create objects which are protected from deletion (option <span class="stxmacrocommandoption-character">/U|u</span>).

The command STXCONSTANTS now supports the keywords BITMAPS and BUTTONS.

The command TRANSLATE can now translate the contents of a variable or table.

The command EXIT -xLevel now returns to the first macro defining the label label "OnExitAll" or to the toplevel macro (1st called macro) (rather than to the first macro where the variable #EXITLEVEL = xLevel).

The new command TOKEN, an extended form of the command WORD, can tokenise a string using the specified delimiter.

The new command TRIM can be used to trim characters from the beginning and end of a string.

The new command QUOTE can quote all special characters in a string.

The new command LINELENGTH, although similar to LENGTH, returns the length of a line including delimiters.

The NAME command can now check XML attributes and S_TOOLS-STx XML IDs for syntactical validity. The NAME command can also return a UNC file name for a file on a mapped drive. This is useful, for example, for making DataSets portable in a network environment.

The new command ARG can be used to retrieve macro arguments.

The IREF command supports the option <span class="stxmacrocommandoption-character">/I</span> to simplify and suppress certain error messages.

The global variable @REPORTRUNTIMEERRORS can be set to 1 to display a dialog every time a error occurs when processing a command. Many commands can now take an option specifying that warnings should be generated, rather than errors (DRIVE, LOAD, UNLOAD, SET file LOAD|SAVE|STATUS|DELETE|RENAME|COPY|POSITION), READ, SEGMENT). If set to specify warnings, they will not cause a runtime error.

The READ command (and its variants READSTR, READTAB and READVAR) have a new option <span class="stxmacrocommandoption-character">/E</span> which can be used to escape characters in the input from being used as separators.

Format strings can now add a new line character (\n), using the tag %n. The standard C format tags %x and %X are now supported.

The KEYWORD command now supports the option <span class="stxmacrocommandoption-character">/F</span> which prevents abbreviations from being found and <span class="stxmacrocommandoption-character">/C</span> to make the comparison case sensitive.

The new commands SYSTEMCALL and SYSTEMCALLX are variants of SYSTEM and SYSTEMX which return warnings rather than errors on failure.

The command TGET can now return elapsed milliseconds, when the new option <span class="stxmacrocommandoption-character">/ms</span> is used.

The NAME command, when used with the new UNC subcommand can convert a file path on a mapped drive to its UNC equivalent. This help keep project files portable when accessed from multiple computers (E.g. when the z drive is mapped to \\server\data, the command "name 'z:\ds.xml' unc" will return "\\server\data\ds.xml".

The READ commands have a new option <span class="stxmacrocommandoption-character">/T</span> which prevents arguments from being trimmed.

The macro WINDOWSIZEDLG can be used to allow a user to set a window's size (width and height in pixels).

SPAtoms

The new SPAtom MIXALL mixes up to eight input arrays/vectors into an output array/vector with gain scaling.

The new SPAtom WLANA performs a general wavelet analysis, and the SPAtom CCANA implement a Cohen Class distribution.

The SPAtoms PVANA and PVSYN no accept a windowing function parameter.

The new SPAtom KLATTSYN can be used to generate synthesised speech.

EVAL command

The EVAL command has the following new subcommands:<br /> formants - a new formant tracking algorithm.<br /> limit, limitlow, limithigh - limits values to within a range of values.<br /> min, max - can receive more than one parameter.<br /> cdot, ctrn, conj - complex dot product, matrix transposition and conjugation.<br /> f0ac - F0 detection using autocorrelation.<br /> The EVAL command now supports numerical (e.g. >=), logical (e.g. &&) and ternary (e.g. eval $#a > $#b ? $#a : $#b).

The Macro Library

The DATASETCMD has a new subcommand AUTOSAVE with which you can turn the DataSet autosave feature on and off.

The GRAPHSETUP macro.

The new CGRAPHSETUP command GRAPHLEGEND displays an amplitude legend in a spectrogram plot.

The new CGRAPHSETUP command GETCOLORPALETTE retrieves the print or screen palette in an extended table.

The new CGRAPHSETUP command GETPROFILELIST returns a simple table with a list of color profiles defined in the settings file (S_TOOLS-STx INI).

===== Classes =====

BXMLDoc class

The SETELEMENT function can now take a table containing attribute/value pairs.

CMenu class

The new CMenu function AddToolBoxMenu adds the standard toolbox menu items to the menu.

XPlot class

When constructing an XPlot instance, an owner window may now be specified.

===== Shell Items =====

Dialog Item

The dialog edit control has a new option '<span class="stxmacrocommandoption-character">/F</span>' which forwards KEY messages to the shell.

There are now four 'types' of edit control and a host of new parameters, which means it can display syntax highlighting, be used as a command line interface, etc.

A listview's cells can now be editable. The option <span class="stxmacrocommandoption-character">/E</span> which must be set for a ListView to be editable. The message CELLEDITED is sent if it is editable and its contents has been changed. If the user cancels editing, the message CELLCANCELLED is sent to the shell. If editing is ended because the user presses <span class="stxhotkey">TAB</span> or <span class="stxhotkey">Shift TAB</span>, the CELLEDITEDTAB or CELLEDITEDBACKTAB messages are sent. You can set the focus to a specific cell and enter editing mode using the new command SET dialogItem listviewIndex STARTEDIT.

The listview now supports the <span class="stxmacrocommandoption-character">/F</span> flag which forwards specific key types to the shell.

The listview supports a new option /R=n, which determines the maximum number of lines of text which can be displayed in the listview.

The new attribute !FOREGROUND returns 1 if the dialog window is in the foreground, 0 if it is not and -1 if the command fails in some way.

The new dialog attribute !EDITING can be used to ascertain if a listview is currently being edited or not.

File Item

The NEW FILE command can now take the option <span class="stxmacrocommandoption-character">/S</span>, to suppress error messages on creation failure.

The new file item command COPY <span class="stxmacrocommandoption-character">/Z</span> can be used to encrypt/decrypt a file, including optional password protection.

The new command TRYLOCK will try to get a lock on the file but will not block the script.

The !CHANGED attribute can now be explicitly set or reset. This functionality is new, in as much as versions previous to 3.9.0 could only reset the attribute. The meaning of assigning '1' to the attribute has changed, since assigning '1' now *sets* the attribute, whilst assigning '0' resets the attribute.

A new file item type - the GDX file item - has been developed, which can be used to create files containing graphic data which are passed directly to a graph item. GDX stands for "graphical data exchange". Currently, the spectrogram is the only plot which supports the GDX file type.

Graph Item

The command ADDMARKER can now be used to add a 'Box and Whiskers' metasegment.

The metasegment font can be specified on an individual basis using the ADDMARKER command.

A metasegment may be told not to change color on selection. This is only available using the "SET graph ADDMARKER table" command with the parameter "invertSelected" set to "true" if the metasegment color should be inverted whilst selected or "false" if not. The default is "true".

The key used to make a metasegment moveable can now be set using a 'modifyKeys' entry in the ADDMARKER table parameter.

A simple marker can now be displayed as a single vertical line (option <span class="stxmacrocommandoption-character">/M</span>).

The command OVERVIEW, which toggles between the 'view' and 'overview' modes, has been documented.

The graph supports a new attribute !CURSORMODE which returns the currently visible cursors, as set using the last CURSORMODE command.

The width of a graph's border can now be set using new AXIS command parameters. The default border width is 1 pixel.

The spectrogram palette can be changed at any time using the "SET graph Y * * SPECTROGRAM" function.

The DATASETLOADED message is now sent when a graph finishes loading data for a particular input.

Instance Item

The new command TRYLOCK will try to get a lock on the instance but will not block the script.

Table Item

A table item connected to a ListView must be configured to be editable using the CONFIG command or the !EDITABLE attribute. The CONFIG command has also been extended to allow for a restrictive set of values to be specified for a table field. If specified, the ListView will display a combobox in this column for each entry. All parameters set using the CONFIG command can now be queried via table field attributes.

The new command TRYLOCK will try to get a lock on the table but will not block the script.

The command NEW TABLE supports a silent error flag.

A table field can now display multirow entries, if the !MULTIROW attribute is set to 1, or the CONFIG command multirow parameter is set to ON.

The last user input for a particular column can now be used as the default for that column using the CONFIG command's setuserdefault parameter.

The DEFINE command can now be used to rename an existing field.

Wave Item

The wave item now supports the new attribute !PLAYSRATE which can be used to return the sampling rate currently used to for playback or set a new sampling rate for playback.

=== Changes ===

Changes in S_TOOLS-STx <CURRENT_VERSION>:

Graphical User Interface

F0 Test, F0Lookup, Amplitude Spectrum Statistics

The F0 Test, F0 Lookup and Amplitude Spectrum Statistics functions in the Spectrogram & Parameters Viewer sectioner have been moved to the toolbox file SpectrumTB.sts.

Macro Language

UNLOAD command

The command UNLOAD MACROCODE, UNLOAD SPUCODE and UNLOAD SOURCECODE take one parameter - the name of a sourcecode file (relative or absolute). The MACROCODE variant used to take a blank separated list of macro names and the SPUCODE version used to take a blank separated list of SPU names.

Display and Dialog DROPFILE message

The DROPFILE message sent to displays and dialogs when files are dropped onto them has been changed. The <span class="stxmacrocommandparameter-character">filePath</span> parameter is not longer a string, but rather the id of a simple table with one absolute path per entry.

Syntax

The string "123 456" is no longer a valid number.

=== Bug Fixes ===

Bug fixes

The waterfall graph now prints correctly.

The BDataSet member function AddASet now selects the new audio set if adding the set succeeds (r5534).

Shell commands using the return value RC now assign the value even if return code equals 0 (indicating success) (r5609).

Spectrogram & Parameters Viewer Sectioner copy to clipboard working again (r5625).

The 'view' graph mode now displays correctly when first drawn (r5643).

The asterisk character * is now officially an invalid hotkey, rather than being one which doesn't work correctly (r5500).

Loading an XML file which an unsupported character encoding now fails rather than asserting (r5614).

The Spectrum viewer can now saving CEPST parameters (r6470).

The color 'GRAY' is now defined as the RGB value 96:96:96, which fixes the bug where cursors were invisible on a 'GRAY' background (r6148).

The "SET graph XSCALE" flag "/I" is now working (r6187).

Using the correct normal/dual/tight phase vocoder pv filters (r5874).

All valid number formats (including mmmE /-eee) can now be used in time-expressions (r5746).

=== Corrections ===

S_TOOLS-STx Version: 3.9

A list of documentation corrections since the last release (3.7).

The macro COBJ has been superseded by the COBJ class and no longer exists.

The command SYSTEM MKDIR and SYSTEM RMDIR were undocumented.

The SPAtom ASEG1 parameters are now in the correct order (<span class="stxmacrocommandparameter-character">TABS</span> and <span class="stxmacrocommandparameter-character">TABM</span> were swapped).

The SPAtom VSPLIT was mistakenly documented as VSPLIT1.

The macro DEBUGTB no longer exists.

The descriptions of the different formulas used by the SPAtom MORLET have been corrected.

The section FILE item command LOAD parameters were not documented as mandatory.

Added description of shell variables SCRIPTFILEPATH, SCRIPTDIRECTORY AND SCRIPTMAINNAME.

The AWEIGHT SPAtom has now been documented.

The WAVEOUT SPAtom has now been documented.

A list of documentation corrections since the last release (3.6.2).

The BUTIL FILEDIALOG no longer has a <span class="stxmacrocommandparameter-character">path</span> parameter.

A list of documentation corrections since the last release (3.6.1).

The SET table FIND <span class="stxmacrocommandparameter-character">cexpr</span> format uses colons, not commas as delimiters.

The SET value OUTPUT commands can take <span class="stxmacrocommandoption-character">/Double</span> options.

The description of the parameters for the NEW TABLE command where field definitions are possible has been corrected.

The SET graph CURSORMODE command now describes the bound and locked parameters correctly.

The VAR arithmetic operators DIV, MUL and SUB are actually called DIVIDE, MULTIPLY and SUBTRACT

The SET graph ZSCALE command parameters were incorrect.

=== Known Bugs ===

S_TOOLS-STx Version: 3.9

These bugs were known to exist at the time of the release and are proving difficult, if not impossible to fix.

Interface

Sometimes 44KB soundfiles are created, which are invalid. This bug has not proved easy to replicate, so if you can replicate it, please contact us ( \n This e-mail address is being protected from spam bots, you need JavaScript enabled to view it ).

Can't delete an entry in the DataSet if it has no ID. It is highly unlikely that you will ever have a DataSet entry with no ID. If this is the case however, you must currently delete it by hand (Close S_TOOLS-STx, open the DataSet in a text editor and either give the offending entry an ID, or remove it). Should you be able to reproduce any action which creates an entry without an ID, please contact us ( \n This e-mail address is being protected from spam bots, you need JavaScript enabled to view it ).

Spectrogram & Parameters Viewer

Interpolation of very short signals is incorrect (Deutsch - 2004-11-10 - since 1.0).

Graphics

Copying a display graphic to the clipboard and pasting into a graphics program does not always achieve the desired results. This bug will not be fixed in the foreseeable future. Some graphics programs paste it properly (IrfanView, Microsoft Word), others don't (PaintShop Pro) - (Jonnie White - 2004-07-14).

Selected cursors is not visible if background is set to GRAY (White - 2004-07-12 - since 1.0).

Macro

The dialog control listbox does not handle displaying huge strings properly. This seems to be a problem with the underlying CListBox control (Becker/White - 2004-12 - since 1.0).

The DCOM command INVOKEMETHOD Evaluate always returns an error when communicating with the R DCOM server even if the command was actually successful (Deutsch/White - 2004 - since 3.6.0).

==3.8==

3.8.3

* BUGFIX: zoom in in viewer3 now working when zooming around active cursor
* BUGFIX: spectragram title display corrected (amin/amax)
* BUGFIX: CDLGMAP now deletes window only if it has created the window during construction

3.8.2

* BUGFIX: dataset path now displayed, even if it has spaces in it.
* BUGFIX: Parameter plot explicitly redrawn when new data is sent. This fixes the bug (reported by Julia Brandstaetter) where Set Zero and Undo were not working properly in Spectrogram and Parameter plot.

3.8.1

* BUGFIX: Warn user that more waveform samples are being sent than expected and refrain from crashing.
* BUGFIX: CDlgMap now always uses the next free dialog index for a new entry. This means that multiple maps can reference the same dialog and still work. The functions fci and nc were removed since they are never used. Display now using second event to synchronise creation and variable initialisation. This fixes the mysterious bug where the window class was only sometimes used.
* BUGFIX: If the polyline function is called with less than two points it no longer asserts, but rather ends gracefully.
* BUGFIX: send keys not processed by dialog on to graph hotkey handlers
* BUGFIX: spectrogram is now being initialised with the correct context menu when formants are displayed in it.
* BUGFIX: giving dialog focus if there are no graphs
* BUGFIX: buttons in dialogs in a graph no longer process normal mneumonics. This means that the graph can process them (for Moosmueller). Buttons can still be activated with return and the space bar and tabbed/arrowed to.
* BUGFIX: preventing race conditions in Attach/Detach. This removes one possible cause of autosave crashing. It does not guarantee, though, there to be no other reasons for autosave to crash.

=Downloads=
The {{STX}} downloads are available here: https://www.kfs.oeaw.ac.at/pub/stx

User Guide/Spectrogram and Parameter Viewer/Settings Dialog

2019-11-11T13:32:44Z

Jw: /* use global sectioner settings */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{V2}}
This is the setup and start dialog for the [[User Guide/Spectrogram and Parameter Viewer|Spectrogram & Parameters Viewer]], also known as ''Analysis'' in the ''Compact'' mode. This application shows a selected set of transformations and parameters of the source signals. It also implements a spectrum sectioner and some segmentation tools.

[[File:v2_settings_dialog.png|thumb]]

==Dialog Layout==

At the top of the dialog window the control buttons and the controls for the source signal selection are located. Below the source signal controls the controls for the application settings are displayed in two groups. On the left side are the settings for the three plot regions zoom, segment lines and overview and on the right side are the general settings and some buttons for sub-dialogs.

==Control Buttons==

[[File:v_dialog_start_cancel_etc.png]]

;Start:Save settings into the profile displayed in the dialog caption, close the dialog and start the application. This button is only displayed if one or more signals are selected in the Overview or Detail window of the Workspace. If multiple signals are selected, for each signal a separate application is started.
;OK:Save settings into the profile displayed in the dialog caption and close the dialog, but do not start the application.
;Cancel:Close the dialog without saving the changes.

Note: The Start button is only displayed if a valid object is selected in the Workspace (e.g. a segment or sound file).====Source Signal====

==Source Signal==

[[File:v_dialog_source_signal_selection.png]]

;Set:Shows the XML-reference (IRef) of the audio-set containing the source signal
;Seg:Contains the ID of the selected segment or the address (task-expression) of the source signal. This field can be edited.
;Chn.:Source signal channel (All, 1, 2, ...). The contents of the combobox depend on the number of channels of the audio-set.

Note: If multiple source signals are selected, only the number of selected signals (on the left side) and the Chn.-selection is displayed, the Set- and Seg-controls are hidden.

==Analysis==

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
The following Spectrogram & Parameters Viewer settings are specific to the signal analysis.

[[File:Stx ug v2 settings analysis.PNG]]

===spectrogram frame===

This group of controls below this text is used to define the frame parameters for the spectrogram analysis.

=====bandwidth/length=====

This button selects the unit of the frame length. To change the unit, press the button. The available settings are length[smpl] (framelength in samples), length[ms] (framelength in milliseconds) and bandw[Hz] (bandwidth in Hertz). The edit field on the right side contains the value of the framelength which must be greater than zero.

=====overlap/shift=====

This button selects the type and unit of the frame shift or overlap. Press the button to change it. The available settings are shift[smpl] (shift in sampled), shift[ms] (shift in milliseconds) and overlap[%] (overlap in percent of the framelength). The edit field on the right side contains the shift/overlap value. Shift values must be greater than zero and lower or equal to the framelength and the overlap value must be in the range 0 to 99 percent.

=====diff. factor=====

Differentiation factor. If greater than zero (and lower or equal 1) differentiation is applied to the signal before analysis.

=====kaiser-bessel(8)=====

This button selects the windowing function which should be applied to the signal. Press the button to change the window function type. The available windows are rectangle, Hanning, Hamming, Blackman-Harris, Kaiser-Bessel (with to different factors) and Bartlett.

===parameter frame===

If checked, separate frame settings for the parameter analysis methods can be defined. Otherwise the same settings as for the spectrogram frame are used. See spectrogram frame (above) for the meaning of frame settings.

====waveform range / 0db====

Waveform amplitude value for full attenuation (range) and zero dB (0dB=). Both values must be greater than zero.

===show in spectrogram: formants / pole-zero ===

If checked, the formant tracks (method: formants) and/or pole-zero tracks (method: pole-zero) are plotted over the spectrogram, rather than in their own graph. The scale and unit settings of the spectrogram are used instead of the formant/pole-zero scale and unit.

==Calibration==

You can set the profile's calibration settings using the [[User_Guide/Spectrogram_and_Parameter_Viewer/Settings/Calibration_parameters|calibration parameters dialog]].

==General==

The following general settings are available:

===batch mode===

If checked, the analysis application is closed automatically when finished. This option can only be used if automatic printout and/or automatic parameter save is enabled.

===Automatic Printout===

If checked, the printout of the waveform plot is started automatically and the application is closed when the printout is finished. The button starts the print settings dialog.

===do not print cursors===

If checked, the cursors are not printed. This option works only for the automatic printout.

===automatic parameter save===

If checked, the computed parameters (but not the spectrogram) are automatically saved. Older versions of same parameter methods computed for the analysed segment are replaced. This checkbox is only enabled if the Parameter Data Management is set to 'COMPUTE always'.

===Automatic Segment Names===

If checked, the id of new segments is assigned automatically. The format of the automatic name depends on the settings of the Automatic Segment Names dialog, which can be opened with this button.

===show sectioner windows===

Enable / disable the sectioner windows. If enabled, the sectioner windows are shown on top of the analysis display.

===automatic sectioner plot===

Enable / disable automatic sectioner update. If enabled, the sectioner windows are updated every time a time scale cursor is selected or moved. Otherwise the user must press the function key F8 to update the sectioner.

===show x grid, show y grid===

Enable/disable the grid on the x/y-scales of the all graphs. This setting is not applied to the sectioner windows, which have their own grid settings.

===x scale position and window===

Selects the position (below or above graph) and window (none, lowest, highest or all) where the x-scale (time) should be displayed.

===title window===

Selects the graph (none, lowest, highest or all), where the analysis title (audio-set, segment and channel) should be displayed.

===show dialog===

Show / hide the analysis application control dialog and select the dialog position (below or above graph windows)

===timescale===

Choose the timescale to use on the x-axis. The clock setting displays the time in hours, minutes, seconds and milliseconds from the beginning of the displayed segment (E.g. 0:01:00.000 which means 1 minute from the beginning of the displayed segment). If layout-defaults is specified, the timescale set in the Display Layout and Format dialog is used.

===enable zoom and autoscale===

If checked, then the [[User Guide/Spectrogram and Parameters/Zooming|zoom and autoscale features]] are turned on.

===enable one-click range selection===

If checked, you can set a new cursor range by clicking anywhere in the graph, dragging and letting go. This can make selecting a cursor range very easy. However, if you prefer to be able to change the cursor range only by selecting a cursor and dragging it, please disable this check box.

===play window===

The size of the window to be played when the [[User_Guide/Spectrogram_and_Parameter_Viewer/Spectrogram_and_Parameter_Viewer_Hotkeys|'play window' hotkey]] is pressed. The signal before, around or after the active cursor is played.

===Color Scheme===

With this button the Color Scheme and Settings dialog is opened to select and/or configure the plot colors, line styles and general graphics settings. The selected color scheme is displayed in the button caption.

===global===
If checked, then the [[User_Guide/Spectrogram_and_Parameter_Viewer/Sectioner/Sectioner_Settings_Dialog|sectioner settings]] are global to STx. If unchecked, then these settings are saved with this profile. This can be specified per profile. Note that if you export a profile, the sectioner settings are only exported if global settings are unchecked.

==Method list==

[[File:v2_settings_method_list.png]]

The method list is where you specify which analysis methods to use in the profile and modify their settings. The Spectrogram & Parameters Viewer currently supports these [[User Guide/Spectrogram and Parameter Viewer/Methods|methods]].

===Methods===

You can analyse the signal with a variety of methods. More details [[User Guide/Spectrogram and Parameter Viewer/Methods|here]].

===Up/Down===

Reposition the graph within the display by moving it up or down.

===Settings===

Open a settings dialog for the selected method (click on the method name in the method list to select it).

===Mode===

Whether a method is used in a profile is determined by its mode: <code>ON</code> or <code>OFF</code>. Double-click a method to toggle its mode.

===Size===

The Size column specifies the size of the method. The size is the method's graph size in relation to the other method graphs. If all methods have a size of 1, then they will all be the same height. If one method has a size of <code>2</code>, it will be double the height of the methods with a size of <code>1</code>.

===Line===

The value in the Line column specifies which function line color (see Color Schemes) to use to draw the method's function. You can change the line value by right-clicking on the method and selecting the context menu item line.

===Segs===

The Segs column indicates if segments will be displayed in the graphs or not. You can turn segments on and off via the context menu item Segments -> On / Off. You can modify how and where segments are drawn by pressing the ''Segs'' button, which opens the [[User Guide/Segment Markers Dialog|Segment Markers Dialog]].

==Parameter Data Management==

Choose whether parameters are computed or loaded on analysis.

*COMPUTE always - computes the parameters on analysis, even if parameters already exist (i.e. old parameters are overwritten).
*LOAD available / COMPUTE missing - loads the parameters if they exist and computes those which are missing.
*LOAD available / DISABLE missing - loads the parameters which exist, and does not draw those parameters which are missing. This setting does not work well with super segments and sub segments, since they will not be loaded if the segment itself has no parameter data.

===Parameter IO Configuration===

If you choose to load existing parameters, you have the choice of loading super or sub segment parameters in addition or instead. A '''super segment''' is a segment which starts before and ends after another segment. A '''sub segment''' is a segment which starts after and ends before another segment. This feature was introduced in {{STX}} 4.3.

====Load====
You can choose to load parameter data from super or sub segments as well as from the segment itself. This is done by selecting one of the following:
{|
|own data only
|parameter data is loaded from the selected segment.
|-
|super segment data only
|parameter data is loaded from the super segment if one is found, otherwise no parameter data is loaded.
|-
|super segment data (preferred) or own data
|parameter data is loaded from the super segment if one is found, otherwise parameter data is loaded from the selected segment.
|-
|sub segment data only
|parameter data is loaded from sub segments, if found, otherwise no parameter data is loaded.
|-
|sub segment data (preferred) or own data
|parameter data is loaded from sub segments if any are found. If no sub segments are found, then the selected segments parameter data is loaded.
|}

====Save====
If you have loaded sub or super parameters, and you choose to save the parameter, you can choose one of the following for saving the loaded super/sub data:
{|
|always overwrite origin data
|the parameter data loaded will always be overwritten, if the user chooses to save the selected parameter (or has automatic parameter saving turned on).
|-
|prompt user
|the user will be prompted to choose whether they wish to save the loaded sub/super parameter data.
|-
|never overwrite origin data
|the loaded super/sub parameter data will never be overwritten.
|}

TODO: allow user to specify if selected segment parameters are saved. Currently it is '''always''' overwritten.

====Select====
Here you can define how super or sub segments get selected.
{|
|timebased (shortest super / longest sub)
|The shortest segment enclosing the selected segment will be chosen as the super segment or the longest sub segment within the selected segment will be chosen as the sub segment.
|-
|timebased + wildcard ID
|In addition to finding either the shortest super segment, or the longest sub segment, the ID of the segment must match the wildcard ID. [[Programmer_Guide/Introduction#Conditional_Expressions|Simple wildcard matching]] using an asterisk for any number of characters and a question mark for on character.
|-
|timebased + find expression
|In addition to finding either the shortest super segment or the longest sub segment, a find expression can be specified, filtering the segments according to their attributes. E.g. you could only consider segments with the attribute <code>Spk:==:m1</code>.
|}

File:V2 settings dialog.png

2019-11-11T13:11:45Z

Jw: Jw uploaded a new version of File:V2 settings dialog.png

Importing PNGs

User Guide/Spectrogram and Parameter Viewer/Sectioner

2019-11-11T13:03:50Z

Jw: /* Hiding and showing the Sectioner windows */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{V2}}
The Sectioner windows are always displayed above all other graphs in the [[User_Guide/Spectrogram_and_Parameter_Viewer|Spectrogram & Parameters Viewer]]. They contain the waveform zoom and the spectrum of the signal around the active time scale cursor. The Sectioner implements a number of different analysis methods, which can be configured in the [[User Guide/Spectrogram and Parameter Viewer/Sectioner Settings Dialog|Settings Dialog]], reached from the Sectioner context menu or the Sectioner menu.

[[File:v2_sectioner_windows.png]]

Sectioner settings may be global to {{STX}} or [[User_Guide/Spectrogram_and_Parameter_Viewer/Settings_Dialog#use_global_sectioner_settings|saved per profile]].

==Automatic Plotting==

By default, the Sectioner is plotted for the signal at the active cursor position in the active method graph. You can turn of automatic plotting in the Sectioner menu. If automatic plotting is turned off, you can explicitly plot a spectrum of the signal at the current cursor position by pressing the hotkey associated with the [[User_Guide/Spectrogram_and_Parameter_Viewer/Spectrogram_and_Parameter_Viewer_Hotkeys|<samp>sectionerPlot</samp>]] command.

==Calibration Data==

You can use the spectrum in the Sectioner to set the calibration data for the current sound file using the context menu entry '[[/Set Calibration Data/]]'.

==Hiding and showing the Sectioner windows==

You can hide or show the Sectioner windows using the hotkey <kbd>Ctrl+Shift+W</kbd> or the 'Toggle Sectioner' command in the Sectioner menu. There are also three different layouts for the Sectioner windows, which you can toggle through using the hotkey <kbd>Ctrl+Shift+N</kbd>.

==Settings==

The sectioner settings are available in the [[/Sectioner Settings Dialog/]].

Programmer Guide/General Descriptions/Shell Environment

2019-10-24T11:18:01Z

Jw: /* STXREVISION, the executing {{STx}} version */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{Shell}}
Variables which do not begin with <code>@</code>, <code>#</code> or <code>&</code> (i.e. all variables beginning with an alphanumeric character) are so-called ''shell environment'' variables. You can use shell variables yourself when programming. The following shell variables have predefined uses:

== <var>APPMODE</var>, the application run-mode ==

The shell variable <code>APPMODE</code> indicates the current mode the application <code>APPMAIN</code> is in. A value of <code>0</code> indicates that <code>APPNAME</code> is inactive or finished; a value of <code>1</code> indicates that <code>APPNAME</code> is currently active..

== <var>APPNAME</var>, the application name ==

The shell variable <code>APPNAME</code> is defined in the registration entry in the configuration files. To start the shell application defined and registered in the configuration files, the macro <code>APPMAIN</code> is used. Before calling the application's main macro (called: RUNappname), <code>APPMAIN</code> assigns the application name to the variable <code>APPNAME</code> and sets the application mode <code>APPMODE</code> to active (<code>1</code>). The variable <code>APPMODE</code> is used by the macro <code>GETMESSAGE</code> to check the application mode. If <code>APPMODE</code> is set to <code>0</code> (e.g. in a message handler) <code>GETMESSAGE</code> stops receiving messages and returns the value <code>* * * *</code>.

Applications started via <code>APPMAIN</code> must never use <code>EXIT 0</code> to terminate the shell. They must return to <code>APPMAIN</code> (using a normal <code>EXIT 1</code> command from the main macro) which performs some clean-up functions before the shell is terminated.

== <var>CSF</var>, the name of the current sound file ==

The name (full path) of the current, i.e. active sound file is assigned to the variable <var>CSF</var> when a <code>LOAD</code> (open) or <code>UNLOAD</code> (close) command is executed. If <var>CSF</var> is not set (i.e. empty), no sound file is active.

== <var>CSFH</var>, properties of the current sound file ==

<var>CSFH</var> = <var>srate</var> <var>channels</var> <var>samples</var> <var>code</var> <var>type</var> <var>mode</var>

The parameters of the current/active sound file are assigned to the variable <code>CSFH</code> when a <code>LOAD</code> (open) or <code>UNLOAD</code> (close) command is executed.

== <var>EMSG</var>, the current error message string ==

If an error occurs, the textual description corresponding to the return code <var>RC</var> is stored in <var>EMSG</var>.

Note that you can use the command [[Programmer_Guide/Command_Reference/EMSG|<code>EMSG</code>]] to retrieve a description of an error code.

== <var>PARENT</var>, the parent window ==

PARENT = windowitemname

The variable <code>PARENT</code> is used by the window-management functions (e.g. in <code>GETMESSAGE</code> or by <code>DOMODALDIALOG</code>) to identify the parent (main) window of an application. In each application the name of the item (of type display or dialog) used as main window should be assigned to this variable (directly after creation). If <var>PARENT</var> is not set, some functions or user interactions will not work correctly (e.g. minimize/restore).

Special processing applied to the main window:

*The main-window item's close message is translated by <code>GETMESSAGE</code> into the message <code>SHELL thisshell EXIT</code>.
*If the application is minimized, the main window is displayed in the taskbar while all other window are set to invisible. On restore, all windows are restored to their last status/position.

== <var>RC</var>, the return code ==

The return code of the last executed command. See [[Programmer_Guide/General_Descriptions/Return_Codes#RC|Command Return Codes]] for details.

== <var>RESULT</var>, the macro result ==

The value returned by the previous macro. See [[Programmer_Guide/General_Descriptions/Return_Codes#RESULT|Macro Results]] for details.

== <var>SCRIPTDIRECTORY</var>, the directory of the running script ==

The shell variable <var>SCRIPTDIRECTORY</var> is available when an {{STX}} script (*.sts) is running. It contains the directory path where the running script file is stored.

== <var>SCRIPTFILEPATH</var>, the filename of the running script ==

The shell variable <var>SCRIPTFILEPATH</var> is available when an {{STX}} script (*.sts) is running. It contains the name of the running script file including the path.

==<var>SCRIPTMAINNAME</var>, the running macro ==

The shell variable <var>SCRIPTMAINNAME</var> is available when an {{STX}} script (*.sts) is running. It contains the name of the running macro.

== <var>SCRIPTREVISION</var>, the creating {{STX}} version number ==

The shell variable <var>SCRIPTREVISION</var> contains the Subversion repository revision number of the {{STX}} version used to create the current script. For scripts created before r751, this variable is set to 0.

== <var>SHELL</var>, the executing and the calling shell ==

The variable <var>SHELL</var> is generated during the startup code execution of the shell called via the command [[Programmer_Guide/Command_Reference/SHELL|<code>SHELL</code>]]. Its format is

<var>thisshellid</var> <var>callershellid</var>

with <var>callershellid</var> being the ID of the calling shell, and <var>thisshellid</var> being the ID of the new shell. The one exception is the master shell (the first one to be started (automatically) during program initialization) which only stores its own id in <var>SHELL</var>.

== <var>STXREVISION</var>, the executing {{STx}} version ==

The shell variable <var>STXREVISION</var> contains the Subversion repository revision number of the running {{STX}} version. This variable is only available in scripts.

== <var>XRC</var>, the system return code ==

The value returned by the operating system when the command [[Programmer_Guide/Command_Reference/SYSTEM|<code>SYSTEM</code>]] has been called.

[[Category:Programmer Guide]][[Category:General Descriptions]]

Programmer Guide/Macro Library/CDlgMap

2019-10-23T08:21:34Z

Jw: /* Parameters: */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{TOC limit|3}}
==CDlgMap : CObj==

A class to help map [[Programmer_Guide/Shell_Items/Dialog|dialog]] control indices to meaningful keywords. If you use lots of controls in your dialogs, then associating them to keywords makes programming and maintenance a lot easier.

'''Constructor'''

Create a new dialog map instance for the dialog-item <var>dlg</var>. Note that this is the same as <code>CObj NEW CDlgMap</code> <var>dlg</var>.

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

<code>CDlgMap <var>dlg</var>|* [ <var>type</var> <var>icon</var> <var>title</var> ]</code>

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

;<var>dlg</var>

:The id of a dialog item or an asterisk if the dialog should be created on construction. If the dialog map creates it's own dialog, it also destroys it on destruction.

See the macro <code>[[Programmer_Guide/Macro_Library/CREATEMENU|CREATEMENU]]</code> for details of the other parameters.

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

Always returns 0.

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

<code>#map := CDlgMap $#dlg</code>

====CDlgMap Member Variables====

The <code>CDlgMap</code> class has the following member variables:

;<var>&dlg</var>:The dialog this class is mapping control ids to names.
;<var>&map</var>:The extended table mapping indices to names.
;<var>&owned</var>: True if the dialog was created by CDlgMap in the constructor.
;<var>&modal</var>: Flag used for begin/end modal dialog

====Member Functions====

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

===BEGIN===

Displays the dialog as a modal dialog.

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

<code><var>mapinst</var> BEGIN [ <var>focuscontrol</var> ; <var>windowpos</var> ]</code>

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

;<var>focusControl</var>

:The control name assigned to the control which should receive keyboard focus.

;<var>windowPos</var>

:The position to display the dialog window. See [[Programmer_Guide/Macro_Library/DOMODALDIALOG#BEGIN|DoModalDialog Begin]] for a description of this parameter.

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

This function uses the macro <code>DoModalDialog</code>.

===CI===

Get the control index mapped to the string <var>controlName</var>. If the name does not exist in the mapping table, then the next free index is mapped to the string <var>controlName</var> and the index is returned. The first index returned by <code>CI</code> is the same as the number of dialog controls (0 for a new dialog).

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

<code><var>dlgmap</var> CI <var>controlName</var></code>

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

;<var>controlName</var>

:The name to map to the control or an empty string to use the control index as the name.

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

The control index mapped to the string <var>controlName</var>.

===CN===

Get the name mapped to the control index <var>cindex</var>.

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

<code><var>dlgmap</var> CN <var>cindex</var></code>

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

;<var>cindex</var>

:The index of the control.

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

The name mapped to the control index <var>cindex</var> or an empty string if the index is not mapped.

===DESTROY===

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

<code><var>dlgmap</var> DESTROY</code>

=====Description:=====

Delete the dialog map object <var>dlgmap</var>. Note that this is the same as calling <code>COBJ DELETE</code> <var>dlgmap</var>.

===DLG===

Returns the dialog map's dialog item.

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

<code><var>mapinst</var> Dlg</code>

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

The dialog map's dialog item.

===END===

End the modal dialog and destroy map. This is the same as <var>mapinst</var> <code>DESTROY</code>. If the dialog item was created in the constructer or a modal dialog loop has been started, the dialog item is also deleted.

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

<code><var>mapinst</var> END</code>

===FCI===

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

<code><var>dlgmap</var> FCI</code>

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

The index of the first (lowest) mapped control.

=====Description:=====

Get the index of the first mapped control. This is actually the next free dialog index at the time of construction and therefore can be greater than 1 even if there are no mapped controls.

===ISCI===

Query whether a control with a specified name or index exists.

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

<code><var>dlgmap</var> ISCI <var>controlName</var>|<var>controlIndex</var></code>

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

;<var>controlName</var>

:The name used to map a control index in a previous <code>ci</code> function call.

;<var>controlIndex</var>

:An index greater or equal to <code>0</code>.

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

The name of the control (<var>controlName</var>) if the control is defined, or an empty string.

===LOOP===

Executes the modal dialog message loop (via DoModalDialog Loop).

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

<code><var>mapinst</var> LOOP <var>okayControl</var> <var>cancelControl</var></code>

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

;<var>okayControl</var>

:Either the index or control name of the dialog control to use as the OK button (when it is pressed, the dialog closes).

;<var>cancelControl</var>

:Either the index or control name of the dialog control to use as the cancel button (when it is pressed, the dialog closes).

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

A message id and parameters :

<code>msgId msgPar</code>

For <code>COMMAND</code> and <code>UPDATE</code> messages, the original <code>msgPar</code> is converted to a control name string if possible (if it has an associated name in the map).

===NC===

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

<code><var>dlgmap</var> NC</code>

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

The number of controls that have been mapped.

=====Description:=====

Get the total number of controls which are mapped.

===SETCI===

Like the CI member function, this function creates a map between a string and an integer id. The result returned, however, can be used directly as the first part of a <code>SET dialog controlIndex</code> command.

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

<code><var>dlgmap</var> SETCI <var>controlName</var></code>

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

;<var>controlName</var>

:The name to map to the control or an empty string to use the control index as the name.

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

Returns the dialog item and control index mapped to the string <var>controlName</var>:

<code>dialogItem controlIndex</code>

===SETHELP===

The <code>CDlgMap</code> function <code>SETHELP</code> associates the dialog with a help topic referenced by an <code>IREF</code>. When used in conjunction with the <code>CDlgMap</code> functions <code>BEGIN</code> and <code>END</code>, the F1 key will call the relevant help topic if pressed whilst the associated dialog is being displayed.

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

<code><var>dlgmap</var> SETHELP <var>iref</var></code>

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

;<var>iref</var>

:The IREF to the relevant help topic. Note that the IREF must be present in the stxconfig.xml file.

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

Returns the dialog item and control index mapped to the string <var>controlName</var>:

<code>dialogItem controlIndex</code>

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

<code>$#dmap sethelp 'Toolbox/AutoSeg/ASeg_Short_Clicks_Segmentation'</code>

====Examples====

<pre>
[Macro cdlgmap_example]
// create map and dialog
#dmap := cdlgmap * dialog * 'CDlgMap Test'
// create controls
$($#dmap setci ok) button 0 0 '&OK' * 8
$($#dmap setci cancel) button 1 0 '&Cancel' * 8
// display dialog and react to user input
$#dmap begin
do forever
$($#dmap dlg) /W
// use the CDlgMap LOOP command, which translates dialog ids
// into control names
readstr '$($#dmap loop ok cancel)' #msgId #ctrlName
$($#dmap dlg) /R
if '$#msgId' == 'command' then
if '$#ctrlName' == 'ok' then
// save settings
break
else if '$#ctrlName' == 'cancel' then
break
end
else if '$#msgId' == 'update' then
// react to update
end
end
// destroy dialog and map
$#dmap end
exit 1 int 0
</pre>

Programmer Guide/Shell Items/Graph/SET GRAPH

2019-10-18T07:37:20Z

Jw: /* Add or update a metasegment */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{Graph Item}}
A [[Programmer_Guide/Shell_Items/Graph|graph]] consists of eight splitters. It has one <code>X</code> input (which is not always used), a user-defined number of <code>Y</code> inputs and a <code>CURSOR</code> output. Each <code>Y</code> input can be used to display a function (for some functions, in combination with the <code>X</code> input). All splitters in a graph and all functions displayed in a graph use the same <code>X</code> and <code>Y</code> scale settings. Each function is assigned to one splitter in which it should be displayed. More than one function can be displayed in one splitter. The functions displayed in a splitter can even be different but they should be compatible (e.g. it makes no sense to assign a <code>SPECTROGRAM</code> and a <code>WAVEFORM</code> to the same splitter). Each splitter can be set to be visible or hidden.

For all color settings (and palettes) used by a graph, one color can be assigned for the screen and one for the printer. To assign screen colors use the commands as described above. For printer color setup use the same commands a second time with the option <code>/Print</code>.

To minimize screen updates, most setup commands do not directly affect the display. The setup parameters are stored and must be explicitly transferred to the display. For this purpose the option <code>/Apply</code> can be used with any graph-item command.

The formats and values for color and font arguments used in the graph commands are described in detail in the Colors and Color Arguments topic in the General section.

==Inputs and plots==

Graphs items can display different types of function plots. The function data is passed to the graph via the graph's X and Y inputs. You set up the relationship between the data (a value item, SPU, or [[Programmer_Guide/Shell_Items/File/NEW_FILE#GDX_Files|GDX]] file) and the graph's inputs using the following <code>SET graph X</code> and <code>SET graph Y</code> commands.

===Connecting graph inputs===

Configure a graph's x and y axis for data input.

SET <var>graph</var> X <var>data</var>

The graph item's <code>X</code> command configures a graph's x-axis data input. The exact configuration necessary depends on the type of plot which will be drawn.

SET <var>graph</var> Y <var>index</var> <var>data</var> <var>function</var> <var>splitter</var> <var>params</var> /Realtime

The graph item's <code>Y</code> command configures the graph's y-axis data input. The <var>function</var> parameter specifies which type of plot will be drawn. These plots are described individually in more detail below.

{|class="einrahmen"
!option!!description
|-
| <var>index</var>
| The zero-based input index (0…inputs–1)
|-
| <var>data</var>
| data parameter. This can be the output of an SPU (spuitem.output) or of a value item (valueitem).
|-
| <var>function</var>
| One out of <code>XYPLOT</code>, <code>PARAMETER</code>, <code>WATERFALL</code>, <code>SPECTROGRAM</code> and <code>WAVEFORM</code>.
|-
| <var>splitter</var>
| The number of the graph splitter index (1…8) where the function should be displayed. Note that splitter visibility is set using the <code>SPLITTERS</code> command.
|-
| <var>params</var>
| The function plot configuration parameters (see the specific plot below).
|-
| <code>/Realtime</code>
| The real-time option <code>/R</code> causes the function to be re-displayed each time an input is updated. If this option is used, zooming is not possible.
|}

The Y input '''MUST''' be defined before the X input on the first call (redefining the Y axis once both x and y inputs have been defined is not a problem). Orienting a graph (e.g. rotating 90 degrees) is achieved with the command [[Shell_Items/Graph/SET_GRAPH#ORIENTATION|<code>SET graph ORIENTATION</code>]]. Use of the options <code>/Horizontal</code> and <code>/Vertical</code> is no longer supported.

=== Disconnecting graph inputs ===

SET <var>graph</var> Y <var>index</var>
SET <var>graph</var> X

Disconnect any inputs previously assigned to the graph's input <var>index</var>.
{|class="einrahmen"
!option!!description
|-
| <var>index</var>
| The index of the input (0…nInputs-1).
|}

Outputs are automatically disconnected if the item owning the output or the graph item itself is deleted.If the connection is synchronized (e.g. the connected SPU item is still running) disconnection is not possible.

===Plots===

The {{STX}} graph item can draw a number of different plot types.

====XYPLOT / FUNCTION====

SET <var>graph</var> Y <var>index</var> <var>yout</var> XYPLOT <var>splitter</var> <var>color</var> <var>style</var> <var>line</var> <var>width</var> <var>sym</var> [/F=noPlotValue] [/Realtime]

Display a two-dimensional function plot: Y<sub>i</sub> = f(X<sub>i</sub>). The outputs assigned to the X and Y inputs must be vectors of the same length. The option <code>/F=<var>noplot</var></code> can be used to suppress plotting all the points where Y<sub>i</sub> equals <var>noplot</var> (useful for f0-tracks). If the option <code>/Realtime</code> is used, the function is redisplayed each time an input is updated. Note that zooming is '''not possible''' in conjunction with the <code>/Realtime</code> flag. Otherwise, the function is displayed on synchronisation (when the SPU stops). The <code>DASH</code> and <code>DOT</code> line styles only support widths of <code>0</code>. The keywords '''XYPLOT''' and '''FUNCTION''' are interchangeable.

{|class="einrahmen"
!option!!description
|-
| <var>xout</var>
| The x data vector (an output of an <code>SPU</code>). This must be the same length as <var>yout</var>.
|-
| <var>yout</var>
| The y data vector (an output of an <code>SPU</code>). This must be the same length as <var>xout</var>.
|-
| <var>colour</var>
| The color of the function line (either a color name or an RGB code).
|-
| <var>style</var>
| The plot style. Either dotted (<code>POINTS</code>), a line (<code>LINES</code>), a solid area (<code>AREA</code>) or no line (<code>NONE</code>). If ''POINTS'' is set, then one point is drawn per Y data point. If ''LINES'' is set, then a line is drawn between all Y data points. If ''AREA'' is set, then the area below the Y data points is filled.
|-
| <var>line</var>
| The line style (<code>SOLID</code>, <code>DASH</code> or <code>DOT</code>).
|-
| <var>width</var>
| The width of the function line (<code>0</code>-<code>4</code> if line is <code>SOLID</code>, <code>0</code> if <var>line</var> is <code>DOT</code> or <code>DASH</code>).
|-
| <var>sym</var>
| The symbol to use at each parameter (<code>NONE</code>, <code>SQUARE</code>, <code>TRIANGLE</code>, <code>CIRCLE</code>, <code>CROSS</code> or <code>DIAMOND</code>).
|-
| <code>/F=<var>noPlotValue</var></code>
| Use this option to suppress a particular value (<var>noPlotValue</var>) from the plot
|}

SET <var>graph</var> X <var>xout</var>

Assign the X input vector. The X input vector must be the same length as the Y input vector. The Y input vector must be set before calling this command.

====PARAMETER====

SET <var>graph</var> Y <var>index</var> <var>yout</var> PARAMETER <var>splitter</var> <var>nfrm</var> <var>color</var> <var>style</var> <var>line</var> <var>width</var> <var>sym</var> [/F=noplot /Realtime]

Display the Y data as a function of time (frame index). The connected output can be a numeric value or a vector. Each value written to Y is appended to the time track. The options <code>/F</code> and <code>/Realtime</code> have the same meaning as for <code>[[#XYPLOT / FUNCTION|XYPLOT]]</code>. Note, however, that zooming does not work for the parameter plot when the real-time flag is used. This function is used to display parameter time tracks in (frame-by-frame) analysis applications. The <code>DASH</code> and <code>DOT</code> line styles only support widths of <code>0</code>.

{|class="einrahmen"
!option!!description
|-
| <var>yout</var>
| The parameter values (one number per frame).
|-
| <var>nfrm</var>
| The number of frames (parameter values). If real-time mode is specified (/R), this is the number of frames per screen.
|-
| <var>color</var>
| The line color (color name or rgb code).
|-
| <var>style</var>
| The plot style (<code>POINTS</code>, <code>LINES</code>, <code>AREA,STEPS</code>).
|-
| <var>line</var>
| The line style (<code>SOLID</code>, <code>DASH</code>, <code>DOT</code>).
|-
| <var>width</var>
| The line width (<code>0</code>…<code>4</code> – <code>SOLID</code>, <code>0</code> – <code>DASH</code> and <code>DOT</code>)
|-
| <var>sym</var>
| The symbol to use at each parameter (<code>NONE</code>, <code>SQUARE</code>, <code>TRIANGLE</code>, <code>CIRCLE</code>, <code>CROSS</code> or <code>DIAMOND</code>).
|}

See [[#Connecting_graph_inputs|Connecting graph inputs]] for parameters not described here.

No X input connection is necessary. The X (time) scale is defined by the number of frames <var>nfrm</var> specified for the Y data.

====WATERFALL====

SET <var>graph</var> Y <var>index</var> <var>yout</var> WATERFALL <var>splitter</var> <var>nfrm</var> <var>nspectra</var> <var>lcolor</var> <var>fcolor</var> <var>style</var> <var>width</var> [/Realtime]
SET <var>graph</var> X <var>xout</var>

The output connected to X contains the frequency values, and the output connected to Ynum contains the magnitude values. Both must be vectors of the same length. The X scale is written only once.

{|class="einrahmen"
!option!!description
|-
| <var>yout</var>
| The waveform samples (a vector or a number).
|-
| <var>splitter</var>
| The splitter to show the function in.
|-
| <var>nfrm</var>
| The number of frames.
|-
| <var>nspectra</var>
| The number of spectra to display.
|-
| <var>lcolor</var>
| The line color (color name or rgb code).
|-
| <var>fcolor</var>
| The fill color (color name or rgb code).
|-
| <var>style</var>
| The line style (<code>SOLID</code>, <code>DASH</code> or <code>DOT</code>).
|-
| <var>width</var>
| The width of the function line (<code>0</code>-<code>4</code>).
|}

See [[#Connecting_graph_inputs|Connecting graph inputs]] for parameters not described here.

====SPECTROGRAM====

===== <code>SET graph Y</code> =====

SET <var>graph</var> Y <var>index</var> <var>ydata</var> SPECTROGRAM <var>splitter</var> <var>nframes</var> <var>amin</var> <var>amax</var> <var>palette</var> [ /R ]

The output connected to Y<sub>num</sub> contains the values (magnitude, phase,…) to be displayed in colors. The Y vector must be the same length as the X vector. The Y values are converted to colors and either displayed each time the input is updated (if the real-time option <code>/R</code> is specified), or on synchronization (when the SPU stops). The whole spectrogram consists of <var>nfrm</var> spectra. The colours used to display the different amplitudes are defined using the <var>palette</var> parameter.

{|class="einrahmen"
!option!!description
|-
| <var>ydata</var>
| Either an SPU output or a [[Programmer_Guide/Shell_Items/File/NEW_FILE#GDX_Files|GDX]] file item providing the magnitude vectors (one spectrum per frame).
|-
| <var>nframes</var>
| The number of frames (spectra). If the <code>/R</code> option is specified, this parameter determines the number of frames displayed at any one time on screen.
|-
| <var>amin</var>, <var>amax</var>
| The minimum and maximum magnitudes.
|-
| <var>palette</var>
| The extended table containing the RGB color values (the color palette). The table must have three integer or number fields ''R'', ''G'' and ''B'' where each row defines one RGB value (each field entry may be a value from 0 to 255). The maximum number of palette table entries is 256. You can change the palette at any time by calling this function with a new palette table.

Mapping of y values to colors, with: i = 0 … nrgb-1; da = (<var>amax</var> – <var>amin</var>) / nrgb

{|class="keinrahmen"
|-
|y < amin
|rgb-value[0]
|-
|y > amax
|rgb-value[nrgb-1]
|-
|amin+i.da < y ≤ <var>amin</var>+(i+1).da
|rgb-value[i]
|}
|}

See [[#Connecting_graph_inputs|Connecting graph inputs]] for parameters not described here.

===== <code>SET graph X</code> =====

SET <var>graph</var> X <var>xdata</var>

The data output connected to X supplies the frequency values. The X vector must be the same length as the Y vector. The X scale is written only once. Note that the frequency scale is displayed on the y axis (time is displayed on the x axis).

{|class="einrahmen"
!option!!description
|-
| <var>xdata</var>
| The frequency vector (only set once).
|}

===== Zooming in a spectrogram =====

You can zoom into a spectrogram graph on three axes: time (x), frequency (y) and amplitude (z). Zooming is done using the scale commands <code>XSCALE</code>, <code>YSCALE</code> and <code>ZSCALE</code>.

====WAVEFORM====

SET <var>graph</var> Y <var>index</var> <var>yout</var> WAVEFORM <var>splitter</var> <var>nsmp</var> <var>color</var> <var>style</var> <var>scroll</var> [ /R ]

The waveform envelope is drawn using a min/max plot and optionally filled (<var>style</var><code>=AREA</code>). Each screen contains <var>nsmp</var> samples of the waveform, and the waveform is scrolled if more than <var>nsmp</var> samples are sent via the input Ynum. The argument <var>scroll</var> can set to <code>OFF</code> (or <code>0</code>) if scrolling should be avoided. The output connected to Ynum can be a vector (of any length) or a number. If the option /R is used, the function is redisplayed each time an input is updated. Otherwise, the function is displayed on synchronisation (when the SPU stops).

{|class="einrahmen"
!option!!description
|-
| <var>yout</var>
| The waveform samples (a vector or a number).
|-
| <var>nsmp</var>
| The number of samples per screen.
|-
| <var>color</var>
| The line color (color name or rgb code).
|-
| <var>style</var>
| The plot style (<code>LINES</code>, <code>AREA</code>).
|-
| <var>scroll</var>
| Enable scrolling (<code>ON</code>|<code>1</code>) or disable scrolling (<code>OFF</code>|<code>0</code>).
|}

See [[#Connecting_graph_inputs|Connecting graph inputs]] for parameters not described here.

Note that you must apply the settings to the graph (option <code>/A</code>) before synchronizing the inputs if the input data is to be correctly interpreted.

== Configuration & Control ==

Configure the colours and layout of the graph.

===AXIS===

SET graph AXIS <var>xLabel</var> <var>yLabel</var> <var>labelFont</var> <var>labelColor</var> <var>xTitle</var> <var>yTitle</var> <var>titleFont</var> <var>titleColor</var> <var>xUnit</var> <var>yUnit</var> <var>xBorder</var> <var>yBorder</var>

Configure the X and Y axis. If you are using a <code>WATERFALL</code> graph, you can configure the Z axis with the <code>ZSCALE</code> command.

{|class="einrahmen"
!option!!description
|-
| <var>xLabel</var>
| The position of x labels (<code>OFF</code>, <code>ABOVE</code>. <code>BELOW</code> or <code>BOTH</code>).
|-
| <var>yLabel</var>
| The position of y labels (<code>OFF</code>, <code>LEFT</code>, <code>RIGHT</code> or <code>BOTH</code>).
|-
| <var>labelFont</var>
| The label font.
|-
| <var>labelColor</var>
| The label color.
|-
| <var>xTitle</var>
| The position of x axis text (<code>OFF</code>, <code>ABOVE</code>, <code>BELOW</code> or <code>BOTH</code>).
|-
| <var>yTitle</var>
| The position of y axis text (<code>OFF</code>, <code>LEFT</code>, <code>RIGHT</code> or <code>BOTH</code>).
|-
| <var>titleFont</var>
| The title font.
|-
| <var>titleColor</var>
| The color for titles.
|-
| <var>xUnit</var>, <var>yUnit</var>
| Display x and y axis units (<code>OFF</code> or <code>ON</code>) .
|-
| <var>xBorder</var>, <var>yBorder</var>
| The width of the border at the edge of the window on the x axis and y axis (in pixels). The default is <code>1</code>.
|}

===BGCOLOR===

SET <var>graph</var> BGCOLOR <var>text</var> <var>draw</var>

Set background colors for the text and draw regions of a graph.

{|class="einrahmen"
!option!!description
|-
|<var>text</var>
|background color for text regions
|-
|<var>draw</var>
|background color for draw regions
|}

===FRAME===

SET graph FRAME <var>xscale</var> <var>yscale</var> <var>scalecolor</var> <var>grid</var> <var>gridcolor</var> <var>xsteps</var> <var>ysteps</var> <var>major</var> <var>minor</var>

Configure the graph's frame, scale and grid. Note if you can use the graph item commands <code>XSCALE</code>, <code>YSCALE</code> and <code>ZSCALE</code> to set the scale, grid and tick values.

{|
|-
|xscale
|draw x scale (<code>OFF</code>, <code>ABOVE</code>, <code>BELOW</code> or <code>BOTH</code>)
|-
|yscale
|draw y scale (<code>OFF</code>, <code>LEFT</code>, <code>RIGHT</code> or <code>BOTH</code>)
|-
|scalecolor
|color for scales
|-
|grid
|draw grid (<code>OFF</code>, <code>X</code>, <code>Y</code> or <code>BOTH</code>)
|-
|gridcolor
|color for grid
|-
|xsteps, ysteps
|number of minor x<nowiki>/</nowiki>y ticks between labels
|-
|major, minor
|size of major/minor ticks in pixels
|}

Note that the difference between a major and a minor grid is the line style: a major grid is solid, whilst a minor grid is dashed.

===ORIENTATION===

SET <var>graph</var> ORIENTATION <var>rotation</var> <var>flip</var>

Set the orientation of the graph. By default, the x axis is the horizontal axis and runs from left to right, whilst the y axis is the vertical axis and runs from bottom to top. You can use the <code>ORIENTATION</code> command to rotate the graph and flip the direction in which the axes run. The <code>XSCALE</code> and <code>YSCALE</code> commands can also modify a graph's flip settings.

{|class="einrahmen"
!option!!description
|-
| <var>rotation</var>
| The angle in degrees by which to rotate the graph. Only the values <code>0</code>, <code>90</code>, <code>180</code> and <code>270</code> are supported. An asterisk (<code>*</code>) can be passed to retain the current rotation setting. Rotation is anti-clockwise.

The rotation can also be specified thus: <code>0</code>|<code>1</code>|<code>2</code>|<code>3</code> where <code>0</code> means no rotation, <code>1</code> means 90 degree rotation etc.

|-
| <var>flip</var>
| Determines whether the graph should be flipped on the x and y axis. The following values are supported:

{|class="keinrahmen"
|-
| <code>0</code>
| do not flip at all (default orientation).
|-
| <code>1</code>
| flip on the x axis
|-
| <code>2</code>
| flip on the y axis
|-
| <code>3</code>
| flip on both the x and y axis.
|-
| <code>*</code>
| do not change the current flip setting
|}
|}

Note that you can retrieve the current orientation of a graph using the attribute <code>[[User Guide/Transcription/SPExL - Transcription Tool|!ORIENTATION]]</code>.

===OVERVIEW===

SET <var>graph</var> OVERVIEW [ <var>mode</var> ]

Switch between ''overview'' and ''view'' modes. In the ''overview'' mode, the whole range of the graph is displayed with the current ''view'' displayed as a metasegment. In the ''view'' view, only the range of the current view is displayed. Moving the view metasegment whilst in the ''overview'' mode will result in a new view, once back in the ''view'' mode.

{|class="einrahmen"
!option!!description
|-
| <var>mode</var>
| One of the following values:
{|class="keinrahmen"
|-
| <code>on</code> or <code>1</code>
| Switch to ''overview'' mode.
|-
| <code>off</code> or <code>0</code>
| Switch to ''view'' mode.
|}
|}

:If neither is specified, the mode is toggled.

You can query which mode the graph is in using the <code>!MODE</code> attribute.

See also XSCALE and YSCALE.

===SPLITTERS===

SET <var>graph</var> SPLITTERS <var>splitter<sub>1</sub></var> [<var>splitter<sub>2</sub></var>…] [/Merge]

Set splitters to be displayed. A graph can contain up to eight splitters. Usually only two are used for, e.g., displaying a stereo signal. If /Merge is specified, the currently displayed splitters remain active, otherwise only the specified splitters are displayed.

{|class="einrahmen"
!option!!description
|-
| <var>splitter<sub>X</sub></var>
| The index of the splitter to be displayed. This may be any integer from 1 to 8.
|-
| <code>/Merge</code>
| Use the OR operator when setting the splitters.
|}

Example for displaying the first two splitters:

$#graph splitters 1 2

===TITLE===

SET <var>graph</var> TITLE <var>mode</var> <var>font</var> <var>color</var> [<var>title<sub>1</sub></var> <var>title<sub>2</sub></var>] [/Settitle]

Configure and/or set graph title. The option <code>/Settitle</code> can be used to set a new graph title without applying other settings.

{|class="einrahmen"
!option!!description
|-
| <var>mode</var>
| Turn the graph's title on or off. The following values are supported: <code>ON</code> and <code>OFF</code>
|-
| <var>font</var>
| A font argument as specified in Fonts and Font Argument Format.
|-
| <var>color</var>
| A color argument as specified in Colors and Color Arguments.
|-
| <var>title<sub>1</sub></var>, <var>title<sub>2</sub></var>
| The text to be displayed (one or two lines).
|}

=== XSCALE ===

SET <var>graph</var> XSCALE <var>min</var> <var>max</var> <var>unit</var> <var>text</var> [<var>formatStr</var>|<var>table</var>] [/Invert] [/Log] [/View]
SET <var>graph</var> XSCALE [ <var>min</var> <var>max</var> ] /View

Set the x scale range, title and unit string.

{|class="einrahmen"
!option!!description
|-
| <var>min</var>, <var>max</var>
| The minimum and maximum range of values on this scale.
|-
| <var>unit</var>
| The text to be displayed as the unit on scale and in the cursor tooltip windows.
|-
| <var>text</var>
| The title or description. Note that even if this is set here, it must be enabled using the <code>AXIS</code> command.
|-
| <var>formatStr</var>
| A format string which is used to format the range values. See Format Strings and Rules for details.
|-
| <var>table</var>
| An extended table containing alternative scale values. See scale definition table for a description of the table format.
|-
| <code>/Invert</code>
| Invert the scale (x-axis - right to left, y-axis, top to bottom). Note that this is the same as the ORIENTATION command <code>$#graph ORIENTATION * 1</code>.
|-
| <code>/Log</code>
| The scale is logarithmic (base 10).
|-
| <code>/View[=Reset]</code>
| Set the view (section of whole range).
|}

If the option <code>/View</code> is specified, the <var>min</var> and <var>max</var> value are used to display a section of the whole range. If <code>Reset</code> is specified (e.g. <code>/View=Reset</code>), the <var>min</var>/<var>max</var> values are ignored (and can be left out) and the whole range is redisplayed.

=== YSCALE ===

SET <var>graph</var> YSCALE <var>min</var> <var>max</var> <var>unit</var> <var>text</var> [<var>formatStr</var>|<var>table</var>] [/Invert]
SET <var>graph</var> YSCALE [ <var>min</var> <var>max</var> ] /View=[Reset]

Set the y scale range, title and unit string.

{|class="einrahmen"
!option!!description
|-
| <var>min</var>, <var>max</var>
| The minimum and maximum of scale (range).
|-
| <var>unit</var>
| The text to be displayed as unit on scale and in cursor window.
|-
| <var>text</var>
| The title or description.
|-
| <var>formatStr</var>
| A format string which is used to format the range values. See Format Strings and Rules for details.
|-
| <var>table</var>
| An extended table containing alternative scale values. See scale definition table for a description of the table format.
|-
| <code>/Invert</code>
| Invert the scale (x-axis - right to left, y-axis, top to bottom). Note that this is the same as the ORIENTATION command <code>$#graph ORIENTATION * 2</code>.
|-
| <code>/View[=Reset]</code>
| Set the view (section of whole range).
|}

If the option <code>/View</code> is specified, the <var>min</var> and <var>max</var> value are used to display a section of the whole range. If <code>Reset</code> is specified (e.g. <code>/View=Reset</code>), the <var>min</var>/<var>max</var> values are ignored and the whole range is redisplayed.

=== ZSCALE ===

SET <var>graph</var> ZSCALE <var>showScale</var> <var>min</var> <var>max</var> <var>nMinorStep</var> <var>showLabels</var> <var>showUnit</var> <var>unitText</var> <var>showTitle</var> <var>titleText</var> <var>xShrink</var> <var>yShrink</var> [<var>formatStr</var><nowiki>|</nowiki><var>table</var>] [/Invert]
SET <var>graph</var> ZSCALE [ <var>min</var> <var>max</var> ] /View=[Reset]

Set the z scale range, title and unit string. Note that the z scale was introduced with the implementation of the Waterfall graph. The values <var>xShrink</var> and <var>yShrink</var> determine that amount of the available space for the graph is taken up with the x and y axis.

{|class="einrahmen"
!option!!description
|-
|showScale
|Set the zscale visiblity (<code>OFF</code>, <code>LEFT</code>, <code>RIGHT</code> or <code>BOTH</code>).
|-
|min
|The minimum zscale value
|-
|max
|The maximum zscale value
|-
|nMinorStep
|The number of minor tick steps
|-
|showLabels
|Set the label visibility (<code>OFF</code>, <code>LEFT</code>, <code>RIGHT</code> or <code>BOTH</code>)
|-
|showUnit
|Set the unit visibility (<code>ON</code> or <code>OFF</code>)
|-
|unitText
|The text to be displayed as unit on the scale and in the cursor window
|-
|showTitle
|Set the title visibility (<code>OFF</code>, <code>LEFT</code>, <code>RIGHT</code> or <code>BOTH</code>)
|-
|titleText
|The title text
|-
|xShrink, yShrink
|A value between <code>-1</code> and <code>1</code>. The shrink value determines how much of the space available for the x and y axis is used.
|-
|table
|An extended table containing alternative scale values and labels. See scale definition table for a description of the table format.
|-
|formatStr
|A format string which is used to format the range values. See Format Strings and Rules for details.
|-
| <code>/Invert</code>
| Use this option to invert the scale.
|-
| <code>/View[=Reset]</code>
| Set the view (section of whole range).
|}

If the option <code>/View</code> is specified, the <var>min</var> and <var>max</var> value are used to display a section of the whole range. If <code>Reset</code> is specified (e.g. <code>/View=Reset</code>), the <var>min</var>/<var>max</var> values are ignored and the whole range is redisplayed.

=== Scale definition table===

The graph item commands <code>[[#XSCALE|XSCALE]]</code>, <code>[[#YSCALE|YSCALE]]</code> and <code>[[#ZSCALE|ZSCALE]]</code> can use a scale definition table to define the scale, labels and grid lines. The scale definition table must be an extended table with the following three fields:

{|
|-
|<code>pos</code>
|A numeric field for the position.
|-
|<code>type</code>
|A string field for the scale type (<code>LABEL</code>, <code>MINORTICK</code>, <code>MAJORTICK</code>, <code>MINORGRID</code> or <code>MAJORGRID</code>).
|-
|<code>label</code>
|A string field for the label text. This is only of used for entries of type <code>LABEL</code>. If the label field is not empty, the label field text is displayed at <code>pos</code>, otherwise the value of <code>pos</code> is displayed at the position <code>pos</code>.
|}

==Cursors==

{{STX}} graph items support two graphical cursors, which can be used to mark points on a graph. See [[Programmer_Guide/Shell_Items/Graph/Introducing_Graph_Items#Cursors|Cursors]] for an introduction to the concept of cursors.

===CURSORMODE===

{{/CURSORMODE}}

===PLAYCURSOR===

SET <var>graph</var> PLAYCURSOR <var>mode</var> <var>x</var> <var>y</var> <var>style</var> <var>useY</var> <var>color</var>

Set position and configuration of the play cursor. The play cursor is a cursor whose position is set by this command and cannot be changed interactively by the user. It is used, for instance, to display the running cursor during signal playback (in this case the position is controlled by a timer).

{|class="einrahmen"
!argument!!description
|-
| <var>mode</var>
| The play cursor mode (<code>ON</code> or <code>OFF</code>).
|-
| <var>x</var>, <var>y</var>
| The cursor position.
|-
| <var>style</var>
| The cursor display style (<code>CROSS</code>, <code>CROSSHAIR</code>, <code>HBAR</code>, <code>VBAR</code>, <code>HBARCROSS</code> or <code>VBARCROSS</code>).
|-
| <var>useY</var>
| Selects if y value is used (<code>ON</code>) or ignored (<code>OFF</code>).
|-
| <var>color</var>
| The cursor color.
|}

===CURSORPOS===

SET <var>graph</var> CURSORPOS <var>cursor x</var> [<var>y</var>] [/Select|Deselect]

Set the position of a cursor and optionally select (/Select) or deselect it (/Deselect). The value <var>y</var> is only needed if the cursor is not function bound. Note that if the cursor is not function bound, and you do not set the <var>y</var> value, it will be set to 0.

{|class="einrahmen"
!argument!!description
|-
| <var>cursor</var>
| The cursor index (<code>1</code> or <code>2</code>).
|-
| <var>x</var>, <var>y</var>
| The new cursor positions.
|-
| <code>/Select</code>
| Set the cursor to the selected state.
|-
| <code>/Deselect</code>
| Set the cursor to a deselected state.
|}

==Context Menus==

===ADDPOPUP===

SET <var>graph</var> ADDPOPUP <var>item<sub>1</sub></var> <var>item<sub>2</sub></var> …
SET <var>graph</var> ADDPOPUP <var>tableitem</var> /Table

Define the context menu items of a graph. One context menu can be added to each graph. If a context menu is already defined, it may be replaced by calling <code>ADDPOPUP</code> anew. The default entry "Copy/Print…" is automatically appended to the contextmenu. See the command command <code>[[Programmer_Guide/Shell_Items/Dialog/SET_DIALOG#ADDPOPUP|SET display ADDPOPUP]]</code> for details.

When a context menu item is selected by the user, a <code>[[Programmer_Guide/Shell_Items/Dialog/DISPLAY_and_DIALOG_Messages#CMITEM|CMITEM]]</code> message is generated.

===SETPOPUP===

SET <var>graph</var> SETPOPUP <var>index1</var> […] [/Enable|Disable /Check|Uncheck]

Active/deactivate and/or set or clear the check status of menu items.

===DELETEPOPUP===

SET <var>graph</var> DELPOPUP
SET <var>graph</var> DELETEPOPUP

Removes the items defined by the user, leaving only the default context menu item "Copy/Print…".

==Print==

SET <var>graph</var> PRINT CLIPBOARD
SET <var>graph</var> PRINT <var>filename</var>
SET <var>graph</var> PRINT PRINTER

Print or save the graph. Depending on the arguments, the graph will be copied to the clipboard (<code>CLIPBOARD</code>), saved to an image file (when supplying a filename) or actually printed to an actual printing device (<code>PRINTER</code>). In the letter case, the printing device must be capable of image output, meaning that daisywheel printers, teletypes, chain printers and the like are precluded.

The options <code>/Print</code> and <code>/Screen</code> are used to select the color scheme (see the [[Notes below]]). For file output, the file format is selected by the options <code>/Enhancedmetafile</code> (*.WMF), <code>/Bitmap</code> (*.BMP) or <code>/Gnp</code> (*.PNG). Once started, the operation is performed in the background and a <code>STOP</code> message is sent when the operation is finished.

==Metasegments & Markers==

===DELETEMARKER===

SET <var>graph</var> DELETEMARKER
SET <var>graph</var> DELMARKER
SET <var>graph</var> DELETEMARKER [<var>msid</var>] /X
SET <var>graph</var> DELMARKER [<var>msid</var>] /X

Without <var>msid</var> supplied, the command will delete ''all'' segement and label markers from the graph. With the ID of an existing meta segment supplied (<var>msid</var>), only the respective metasegment will be annihilated.

=== MARKERS ===

SET <var>graph</var> MARKERS <var>mode</var> <var>auto</var> <var>font</var> <var>color</var> <var>msfont</var> <var>mslincol</var> <var>msfillcol</var> <var>mstextcol</var>

Assign settings for markers and metasegments. The settings for metasegments are just default values and can be overwritten when creating a metasegment.

{|class="einrahmen"
!argument!!description
|-
| <var>mode</var>
| Turn markers <code>ON</code> or <code>OFF</code>.
|-
| <var>auto</var>
| Turn automatic y positioning of markers <code>ON</code> or <code>OFF</code>.
|-
| <var>font</var>
| The marker caption font.
|-
| <var>color</var>
| The marker color.
|-
| <var>msfont</var>
| The metasegment caption font.
|-
| <var>mslinecol</var>
| The metasegment frame color.
|-
| <var>msfillcol</var>
| The background color for filled metasegments.
|-
| <var>mstextcol</var>
| The metasegment caption color.
|}

=== ADDMARKER ===

The graph item's <code>ADDMARKER</code> command adds a marker, segment and or metasegment to a graph.

* A marker can display a string and point.
* A segment can display a line between two points and a string.
* A metasegment can display a line or box and a string, and can be clicked and moved.

All of them support the silent option <code>/I</code> causing error situations to generate warning messages rather than error messages (see [[Programmer_Guide/Command_Reference_Options/Silent#The Silent Flag|The Silent Flag]] for details).

==== Add a marker ====

SET <var>graph</var> ADDMARKER <var>text</var> <var>x</var> <var>y</var> [ /U|D|M ] [ /L|R|B ] [ /I ]

Parameters not described here are described further below for the other variants of the command.

{|class="einrahmen"
!option!!description
|-
| <code>U</code>, <code>D</code> or <code>M</code>
| Specifies if the marker should have an arrow head pointing up (<code>U</code>), or down (<code>D</code>), or just be a vertical line (<code>M</code>). If no option is specified, the marker is a cross.
|}

==== Add a segment ====

SET <var>graph</var> ADDMARKER <var>text</var> <var>x<sub>1</sub></var> <var>x<sub>2</sub></var> <var>y</var> [ /H|V ] [ /L|R ] [ /N ] [ /I ]

If the <code>MARKERS</code> option <code>auto</code> has been enabled, the segment's <var>x</var> position is chosen automatically (<var>y</var> must be specified but is ignored).

{|class="einrahmen"
!argument!!description
|-
| <var>text</var>
| The marker/segment caption.
|-
| <var>x<sub>1</sub></var>, <var>x<sub>2</sub></var>
| The x range of the segment.
|-
| <var>x</var>
| The x position of the marker.
|-
| <var>y</var>
| The y position of the segment-marker line.
|-
| <code>H</code> or <code>V</code>
| Specifies the segment style, with <code>H</code> indicating a horizontal bar and <code>V</code> indicating a vertical bar.
|-
| <code>L</code>, <code>R</code> or <code>B</code>
| If specified, the text is shown to the left (<code>L</code>), right (<code>R</code>) or below (<code>B</code>) the marker. The default is showing the text above the marker.
|-
| <code>L</code> or <code>R</code>
| Specifies the position of the text in relation to the segment, <code>L</code> indicating left aligned text and <code>R</code> indicating right aligned text. The default is centred.
|-
| <code>N</code>
| If specified, ''no'' text is displayed.
|}

==== Add or update a metasegment ====

Metasegments are a way to mark regions of graphs. Some of the advantages of metasegments are:
* metasegments be used as interactive "controls": they can be clicked upon and moved, causing messages to be sent to the shell.
* metasegments have many configuration settings and display styles
* metasegments may contain multi-line text

SET <var>graph</var> ADDMARKER /X <var>id</var> <var>caption</var> <var>xmin</var> <var>xmax</var> <var>ymin</var> <var>ymax</var> <var>mode</var> <var>style</var> <var>linewidth</var> <var>linecolor</var> <var>fillmode</var> <var>fillcolor</var> <var>halign</var> <var>valign</var> <var>textcolor</var> [ <var>splitters</var> ] [/Update] [/Redraw] [/Select|Deselect] [ /I ]
SET <var>graph</var> ADDMARKER /X <var>tSettings</var> [ /I ]

{|class="einrahmen"
!argument!!description
|-
| <var>id</var>
| The id string identifying this metasegment. This should not be a number or numeric expression.
|-
| <var>caption</var>
| The text to be displayed in the metasegment. You can force a line break by including the text '<code>\n</code>' in the string.
|-
| <var>xmin</var>, <var>xmax</var>
| The x range.
|-
| <var>ymin</var>, <var>ymax</var>
| The y range.
|-
| <var>mode</var>
| The mode defines whether a metasegment is only for display (<code>STATIC</code>), can be used like a button (<code>BUTTON</code>), or a button which can be moved (<code>MBUTTON</code>,<code>MHBUTTON</code> or <code>MVBUTTON</code>), or can be moved and resized (<code>WINDOW</code>, <code>HWINDOW</code> or <code>VWINDOW</code>).
|-
| <var>style</var>
| The style specifies whether the metasegment can be displayed without a frame (<code>NONE</code>), as rectangle (<code>BOX</code>) or as two vertical lines connected by a horizontal line (<code>BAR</code>, like: <nowiki>|-|</nowiki>).
|-
| <var>linewidth</var>
| The width of the frame lines (0, 1, 2, 3, etc.).
|-
| <var>linecolor</var>
| The frame colour.
|-
| <var>fillmode</var>
| The metasegment is filled with a background color/picture (<code>FILLED</code>) or not filled (<code>TRANSPARENT</code>).
|-
| <var>fillcolor</var>
| The background color, the name of an image file (BMP,GIF,JPG or PNG) containing background picture, or the name of a bitmap (without option) or button resource (with option /Button) containing the background picture.
|-
| <var>halign</var>
| The horizontal text alignment (<code>CENTER</code>, <code>LEFT</code> or <code>RIGHT</code>).
|-
| <var>valign</var>
| The vertical text align (<code>CENTER</code>, <code>TOP</code> or <code>BOTTOM</code>).
|-
| <var>textcolor</var>
| The text caption color.
|-
| <var>splitters</var>
| The index of splitters where the metasegment should be visible (<code>ON</code>) or invisible (<code>OFF</code>); if not specified the metasegment is visible in all splitters.
|-
| <var>tSettings</var>
| An extended table with the following fields:

{| class="keinrahmen"
|-
| parameter || string field
|-
| string || string field
|-
| number || number field
|}

E.g. you can create this table with the following macro command:

#t := new table * * /E string:parameter string:string number:number
if $#t[?] != table em -1 ; $#mac::error - failed to create table

The table has one entry per parameter. Adding a parameter to the table works like this:

$#t * parameter 'xmin' number '20'

The parameter <var>tSettings</var> can contain any of the above parameters, but supports a number of newer ones too. With this version you can add a box and whiskers metasegment if you define the style as 'boxandwhiskers'. The following extra parameters are supported:

{|class="einrahmen"
!parameter!!description
|-
| <code>font</code>
| the font to be used for this metasegment (overrides default font set using the <code>MARKERS</code> command). The font must be specified using the {{STX}} font formatting string: e.g. 'arial:10:b' for a ten point bold arial font. See Fonts and Font Arguments for details.
|-
| <code>min</code>
| the minimum value. Data type: number
|-
| <code>max</code>
| the maximum value. Data type: number
|-
| <code>mean</code>
| the mean value. Data type: number
|-
| <code>median</code>
| the median value. Data type: number
|-
| <code>iqrmin</code>
| the inter quantal range minimum. Data type: number
|-
| <code>iqrmax</code>
| the inter quantal range maximum. Data type: number
|-
| <code>unit</code>
| the unit. Data type: string
|-
| <code>valueaxis</code>
| the axis (<code>x</code> or <code>y</code>) which the boxandwhisker values are on. Data type: string
|-
| <code>invertSelected</code>
| <code>true</code> if the metasegment should be inverted on selection, <code>false</code> otherwise. The default is <code>true</code>. Data type: string
|-
| <code>modifyKeys</code>
| defines which keys must be pressed to allow metasegment modification (i.e. allow user to move the metasegment). The strings <code>control</code>, <code>shift</code>, <code>controlshift</code> and <code>none</code> are supported. If this parameter is not specified, the default modify key (control) is used. Data type: string.
|}
|}

The metasegment splitter setting are defined by the specified splitter arguments (<var>splitterX</var>) and following options:

{|class="einrahmen"
!option!!description
|-
| <code>/Clear</code>
| The metasegment is only visible in the specified splitters.
|-
| <code>/Merge</code>
| The metasegment is made visible in the specified splitters in addition to those already displayed.
|-
| <code>/Except</code>
| The metasegment is made visible in all splitters except those specified.
|-
| <code>/Toggle</code>
| Toggle the visibility of the metasegment in every splitter.
|-
| <code>/Update</code>
| Change the settings of an existing metasegment. Otherwise create a new one, overwriting the old one if it already existed.
|-
| <code>/Redraw</code>
| Explicitly redraw the metasegment. If this is not specified, then use the command <code>SET graph ADDMARKER /X/R</code> after all chanegs to redraw all metasegments.
|-
| <code>/Select</code> or <code>/Deselect</code>
| Set the selection state of the metasegment.
|}

Adding a normal metasegment to an existing graph:

#t := new table * * /E string:parameter string:string number:number integer:integer
if $#t[?] != table em -1 ; $#mac::error - failed to create table

$#t * parameter id string testid
$#t * parameter xmin number 20
$#t * parameter xmax number 80
$#t * parameter ymin number 20
$#t * parameter ymax number 80
$#t * parameter caption string this is the text caption
$#t * parameter mode string window
$#t * parameter style string box
$#t * parameter linewidth integer 1
$#t * parameter linecol string red
$#t * parameter fillmode string filled
$#t * parameter fillcolor string green
$#t * parameter halign string center
$#t * parameter valign string center
$#t * parameter splitters string 1 2

$#g addmarker $#t /Redraw

Here is an example of a box and whiskers metasegment to an existing graph.

#t := new table * * /E string:parameter string:string number:number
if $#t[?] != table em -1 ; $#mac::error - failed to create table

$#t * parameter id string testid
$#t * parameter xmin number 20
$#t * parameter xmax number 80
$#t * parameter ymin number 20
$#t * parameter ymax number 80
$#t * parameter caption string this is the text caption
$#t * parameter mode string window
$#t * parameter linewidth integer 2
$#t * parameter linecol string red
$#t * parameter halign string center
$#t * parameter valign string center
$#t * parameter splitters string 1 2
$#t * parameter valueaxis string x
$#t * parameter style string boxandwhiskers
$#t * parameter min number -20
$#t * parameter max number 75
$#t * parameter mean number 45
$#t * parameter median number 55
$#t * parameter iqrmin number 35
$#t * parameter iqrmax number 65
$#t * parameter unit string dB

$#g addmarker $#t /Redraw

== Selections ==

"Selections" can be used to mark polygon areas of a graph. A selection can be moved and redrawn by the user using the mouse.

Selections are created, modified and deleted using the graph command <code>SET graph SELECTION</code>, first implemented in {{STX}} 3.10.

===Activating and deactivating selections===

==== <code>SELECTION ACTIVATE</code> ====

SET <var>graph</var> SELECTION ACTIVATE <var>id</var> [ ON|OFF ]

Activate the selection identified by <var>id</var>. If <code>OFF</code> is specified, then this command deactivates the selection.

==== <code>SELECTION DEACTIVATE</code> ====

SET <var>graph</var> SELECTION DEACTIVATE <var>id</var>

Deactivate the selection identified by <var>id</var>.

=== Creating selections ===

==== <code>SELECTION SET</code> ====

SET <var>graph</var> SELECTION SET <var>id</var> <var>tSelection</var>

Creates a new selection, or changes the polygon of an existing selection.

{|class="einrahmen"
!argument!!description
|-
| <var>id</var>
| The id of the selection. If the selection does not yet exist, it is created.
|-
| <var>tSelection</var>
| A two field parameter table describing the selection's boundary as a vector of x/y coordinates.
|}

=== Deleting selections ===

==== <code>SELECTION DELETE</code> ====

SET <var>graph</var> SELECTION DELETE <var>cmd</var> [ <var>id</var> ]

The <code>DELETE</code> subcommand can be used to delete one or more selections.

{|class="einrahmen"
!argument!!description
|-
| <var>cmd</var>
| One of the following keywords:
{| class="keinrahmen"
|-
| <code>ALL</code>
| delete all existing selections
|-
| <code>ACTIVE</code>
| delete the active selection.
|-
| <code>ID</code>
| delete the selection with the specified id.
|}
|-
| <var>id</var>
| The id of the selection to delete (only in conjunction with the <var>cmd</var> <code>ID</code>).
|}

=== Listing existing selections ===

==== <code>SELECTION LIST</code> ====

SET <var>graph</var> SELECTION LIST <var>tList</var>

The <code>LIST</code> subcommand fills a table with a list of the existing selections in the graph. The exact details which are returned are determined by the table field names.

{|class="einrahmen"
!argument!!description
|-
| <var>tList</var>
| An extended table with fields specifying which attributes should be retrieved.
Currently the following field names are supported:
{| class="keinrahmen"
|-
| <code>activated</code>
| 1 if the selection is active. 0 otherwise.
|-
| <code>boundrect</code>
| returns the bounding rectangle in world coordinates (a space separated list: <code>xmin xmax ymin ymax</code>)
|-
| <code>id</code>
| returns the id of the selection
|-
| <code>modified</code>
| 1 if the selection has been modified on screen by the user since the last SELECTION SET command. 0 otherwise.
|-
| <code>splitters</code>
| returns the splitters in which this selection is visible (a bit mask: e.g. 3 = 1st and 2nd splitter, 2 = just the second splitter)
|-
| <code>text</code>
| returns the selection's text
|}
|}

// example
#tList := new table * * /e string:id string:splitters string:boundrect
if '$#tList[?]' != 'table' em -1 ; $#mac::ERROR - failed to create #tList table
$#graph SELECTION LIST $#tList
showitem $#tList ; contents of 'list' table

=== Modifying default and existing selection settings ===

You can modify the way an existing selection looks and behaves using the <code>SET graph SETTINGS</code> subcommand.

==== <code>SELECTION SETTINGS</code> ====

SET <var>graph</var> SELECTION SETTINGS <var>tSettings</var>

Set the default settings for all new selections, modify all selections in one go, or modify an existing selection's settings.

The settings which can be modified include a selection's color, it's transparency, any text it should display, and which graph splitters it should be visible in.

{|class="einrahmen"
!argument!!description
|-
| <var>tSettings</var>
| An extended table with four fields (string:parameter string:string num:number int:integer). Currently the following parameters are supported:
{| class="keinrahmen"
|<code>activecolor</code>
| the color when active
|-
| <code>id</code>
| the id of the selection to set settings for. If no id is specified, all selections will be set.
|-
| <code>inactivecolor</code>
| the color when inactive
|-
| <code>linecolor</code>
| the color used to draw an inactive selection (and text).
|-
| <code>splitters</code>
| a bit mask, specifying in which splitters this selection should be visible (0 for none, 255 for all 8 splitters).
|-
| <code>text</code>
| a string to be displayed in the selection. The character sequence '<code>\n</code>' will force a line break when the text is displayed.
|-
| <code>transparency</code>
| specify a selection's transparency with a value between 0 (opaque) and 100 (transparent).
|}
|}

=== Retrieving a selection ===

==== <code>SELECTION GET</code> ====

SET <var>graph</var> SELECTION GET <var>id</var> <var>tSelection</var>

Retrieves the selection's current polygon.

{|class="einrahmen"
!argument!!description
|-
| <var>id</var>
| The id of the selection. If the selection does not yet exist, it is created.
|-
| <var>tSelection</var>
| A two field parameter table to receive a vector of x/y coordinates.
|}

User Guide/Waveform and Segmentation Viewer/Waveform and Segmentation Viewer Hotkeys

2019-10-15T08:00:28Z

Jw:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{V1}}
{{Hotkeys}}
__TOC__

=={{STX}} >= 5.0==

Hotkeys are now defined in the text file <samp>viewer1.hotkeys</samp> in the <samp>profiles</samp> directory of your {{STX}} installation.

=={{STX}} <= 4.4.10==
{|
|-
|Cursors
|
|-
|Home
|Move active cursor to beginning of the x axis of the active graph
|-
|End
|Move active cursor to end of the x axis of the active graph
|-
|PgUp
|Segment Lines: Move active cursor to first line
|-
|Left, Right
|Move active cursor left / right
|-
|Shift+Left, Shift+Right
|Fast move active cursor left / right
|-
|Up, Down
|Zoom: Move active cursor up / down, only if cursor is not bound to function values. Segment lines: Move active cursor to previous / next line
|-
|Shift+Up, Shift+Down
|Zoom: Fast move active cursor up / down, only if cursor is not bound to function values
|-
|F2
|Activate next cursor of active graph (toggle)
|-
|F3
|Mirror inactive cursor around active cursor position (toggle)
|-
|Ctrl+F3
|Mirror active cursor around inactive cursor position (toggle)
|-
|Ctrl+M
|Move the selected segment marker to the cursor positions. The segment controls and the segment marker are updated, but the new position is not saved in the DataSet.
|-
|B
|Zoom: Bind / unbind zoom cursor (amplitudes) to / from waveform function.
|-
|C
|Change cursor style of active graph (cyclic)
|-
|1, 2
|Zoom: Move first / second segment lines cursor to the (exact) position of active zoom cursor.
|-
|Ctrl+C
|Set a cue<nowiki>-</nowiki>point at the position of the active cursor. The cue-point is added to the cue-point list displayed in the dialog.
|}

{|
|-
|Segments
|
|-
|Del
|Delete the selected segment marker from the graphics and from the DataSet!
|-
|Ins
|Create new segment over the signal bracketed by the cursors of the active graph.
|-
|M
|Move the cursors to selected segment marker.

|-
|W
|Write (changed) position of segment marker to the DataSet
|}

{|
|-
|Navigation
|
|-
|Tab, Shift+TAB
|Active next/previous graph or dialog control.
|-
|Ctrl+TAB
|Toggle focus between dialog and last activated graph
|}

{|
|-
|Playback
|
|-
|P
|Play signal bracketed by cursors
|-
|Ctrl+P
|Play signal of selected segment marker in active graph
|-
|Q
|Play whole signal displayed in active graph
|-
|T
|Toggle play window alignment (before / after)
|-
|ESC
|Stop playback
|-
|SPACE
|Play the signal window. The window length and alignment is defined by the play window settings in the [[User Guide/Waveform Plot and Segmentation/General Settings Dialog|General Settings]] dialog.
|-
|F4
|Increase play window length (double)
|-
|Ctrl+F4
|Decrease play window length (half)
|-
|Ctrl+L
|Toggle audio loop on and off
|}

{|
|-
|Zoom
|
|-
|NUM+
|Zoom in to centering around the active cursor on the x axis
|-
|NUM-
|Zoom out of graph centering around the active cursor on the x axis
|-
|Ctrl+NUM+
|Zoom in to graph centering around the active cursor on the y axis
|-
|Ctrl+NUM-
|Zoom out of graph centering around the active cursor on the y axis
|-
|Ctrl+O
|Reset the zoom (zoom out completely)
|}

{|
|-
|Layout/Update
|
|-
|Ctrl+F
|Hide / show overview (file) window (toggle)
|-
|Ctrl+Z
|Hide / show zoom window (toggle)
|-
|V
|Overview: View bracketed signal in the segment lines Segment lines: View bracketed signal in the zoom. Only if zoom mode is set to "between cursors".
|-
|Z
|Change zoom window layout (cyclic)
|}

{|
|-
|Misc
|
|-
|A
|Start a viewer / analyser application for the bracketed signal. A dialog to select the application and profile is displayed.
|}

User Guide/Segment Markers Dialog

2019-10-08T10:09:19Z

Jw:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{V1}}
{{V2}}
The Segment Markers Dialog controls the way segments are displayed in a particular graph. You can specify the shape and color, as well as the text alignment. You can also split the graph into lines and specify the lines in which segments should be displayed. You can even filter the visible segments based on an attribute and value combination.

Each profile method has its own segment marker settings.

[[File:ws_dialog_segment_markers.png]]

;style
:Selects the style of the graphics object used for the marker.
;line color
:Color used to draw and optional fill the marker object.
;text color, text alignment
:Color and alignment for text displayed in the marker.
;attributes
:List of blank separated segment attributes to be displayed in the marker. At least one attribute name must be entered. Attribute names are case sensitive! The attributes are displayed in the same order they are specified.
;use XML attribute format
:If checked, the attributes are displayed in the format name="value", otherwise only the attribute value is displayed.
;order mode
:Selects the method with which segment markers should be sorted.
;direction
:Selects the order in which segment markers are assigned to the segment lines.
;count: The number of segment lines in the graph. The higher the number, the smaller the segment height.
;first: The first line to use for drawing segments. Usually 1.
;last: The last line to draw segments on. If the same as 'count', then segments will use the full height of the graph. If, e.g., count/2, then only half of the graph's y axis will be used. The 'last' value is only used if 'order mode' is set to begin or ID.
;attr name, attr values
:The field attr name contains the name of the attribute to be used to assign segments to lines. The field attr values contains the list of values in the marker line order. Both fields are only used for the order mode attribute-value.

==Examples==
If you are using the webMAUS interface, then you will receive segments with the attribute 'Tier' and the attribute values 'ORT-MAU', 'KAN-MAU' and 'MAU'. If you would like to draw one Tier per line, then set the 'order mode' to 'attribute-value', the 'attr name' to 'Tier' and the 'attr values' to 'ORT-MAU KAN-MAU MAU'.

User Guide/Segment Markers Dialog

2019-10-08T09:55:24Z

Jw:

Programmer Guide/Macro Library/METASEGMENT

2019-10-08T07:39:28Z

Jw:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
Viewer macro: Implements the segment dialog for viewers and some special metasegment functions.

User Guide

2019-10-04T10:08:30Z

Jw: /* Tutorials */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{User Guide}}
==Organise your sound files==

{{STX}} can play, analyse, annotate and modify wave files. The main application - the [[User_Guide/Workspace|Workspace]] - is where you load your sound files and start your analysis from. Your sound files are organised in a [[User_Guide/Project|project]] file. You can use the [[User_Guide/FindFile|FindFile]] application to search for wave files on disk and import them into {{STX}}.

==Analyse a Signal==

There are a number of applications for analysing signals in {{STX}}.

* [[User_Guide/Real_Time_Analyser|Real-Time Analyser]] - analyse the current sound input as a spectrum, wave or spectrogram graph
* [[User Guide/Waveform and Segmentation Viewer|Waveform and Segmentation Viewer]] - useful for segmenting signals
* [[User Guide/Spectrogram and Parameter Viewer|Spectrogram and Parameter Viewer]] - calculate, edit and extract parameters from the signal. Segmentation is also easy here.
* [[User Guide/Spectrum Viewer|Spectrum Viewer]] - average the spectra of a signal segment.
* [[User Guide/Transcription Script|Transcription]] - an application specifically designed for segmentation and transcription.

==Record a Signal==

The [[User Guide/Recorder|Recorder]] can be used to save an input stream to disk and whilst segmenting it on the fly.

==Command-Line Parameters==

There is a minimal set of [[User Guide/Command-Line Parameters|command line parameters]] which can be passed to {{STX}}.

==Concepts and Terminology==

{{STX}} uses some concepts and terminology which might benefit from some explanation. See [[User Guide/Concepts and Terminology|Concepts and Terminology]].

==Tutorials==

There are a few [[User Guide/Tutorials|tutorials available]].

* [[User_Guide/Tutorials/Analysing_a_sound_file|Analysing a sound file]]
* [[User_Guide/Tutorials/Opening_the_samples.stxpr_project|Opening the sample project]]
* [[User_Guide/Tutorials/Playing_a_sound_file|Play a sound file]]
* [[User_Guide/Tutorials/Running_an_application|Running an application]]
* [[User_Guide/Tutorials/Setting_the_default_application|Setting the default application]]
* [[User_Guide/Tutorials/Zooming_in_a_Viewer|Zooming in a viewer]]

There is also the introductory video about [https://kfsmail.kfs.oeaw.ac.at/owncloud/index.php/s/cbMjVjgQLZGjYk8 the compact workspace].

==Scripts, Toolboxes, Development, and Extending {{STX}}==

{{STX}} comes with a number of [[User Guide/Pre-installed scripts|pre-installed scripts]] - applications written in the {{STX}} scripting language, and loaded and run from a text file. You can write your own {{STX}} scripts, [[User Guide/Toolbox|toolboxes]] and applications. All the functionality that you find in {{STX}} is available to you in the script language. The [[User Guide/The_Script_Controller|script controller]] dialog, the [[User Guide/STX_Console|command line console]], the integrated [[User Guide/Debugger|debugger]] and the [[Programmer Guide]] will help you.

==The Log Window==
The little window up on the left hand corner of the screen is the {{STX}} [[/Log Window/]]. You can start a number of applications from here, change some general {{STX}} settings, and view the log messages.

Main Page

2019-10-04T10:05:52Z

Jw:

== {{STx}} {{VERSION}}==

{{STX}} is a software tool for the analysis, signal processing and annotation of Wave sound files. {{STX}} runs on the Windows operating system. It was originally a port of the S_TOOLS application for dedicated DSP hardware developed at the [https://www.kfs.oeaw.ac.at Acoustics Research Institute] in the 1980s. This documentation is work in progress and by no means complete. If you fail to find something you need, please [[Contact|get in touch]] with the development team.

=== Using {{STx}} ===

* [[User_Guide|User Guide]]
* Introductory Video: [https://kfsmail.kfs.oeaw.ac.at/owncloud/index.php/s/cbMjVjgQLZGjYk8 The Compact Workspace]

=== {{STx}} Programming ===

* [[Programmer_Guide/STx_Guru|Starting with {{STx}} Programming]]
* [[Programmer_Guide|Programmer Guide]]
* [[Programmer_Guide/Quick_Reference|Quick Reference]]

=== About {{STx}} {{VERSION}} ===

* Platform: runs on Windows Vista and higher
* [[History of Changes]]
* [[Known Bugs]]
* [[Feature Requests]]
* [[Contact]]
* [[Running STx under Linux or macOS]]

=== Download ===

[https://www.kfs.oeaw.ac.at/pub/stx/stx-5.0.3.9967-freeware.exe STx 5.0.3]

[https://www.kfs.oeaw.ac.at/pub/stx/ older releases]

==MediaWiki Links==
* [[STx Documentation Style Guide|Style guide]] for documenting {{STx}} in this wiki.
* Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using the wiki software.
* [http://www.mediawiki.org/wiki/Manual:Configuration_settings Configuration settings list]
* [http://www.mediawiki.org/wiki/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list]
__NOTOC__

User Guide/SPExL/Transcription Script

2019-10-01T12:20:56Z

Jw: /* User Defined Hotkeys */

User Guide/Spectrogram and Parameter Viewer/Spectrogram and Parameter Viewer Hotkeys

2019-10-01T12:19:37Z

Jw: /* {{STX}} >= 5.0 */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{V2}}
{{Hotkeys}}
__TOC__

=={{STX}} >= 5.0==

Hotkeys are now defined in the text file <samp>viewer2.hotkeys</samp> in the <samp>profiles</samp> directory of your {{STX}} installation.

=={{STX}} <= 4.4.10==

{|
|-
|colspan=2|'''Cursor'''
|-
|Home
|Move active cursor to beginning of the x axis of the active graph
|-
|End
|Move active cursor to end of the x axis of the active graph
|-
|PgUp, PgDn
|Sectioner Spectrum: Change cursor binding between 1st to 2nd spectrum
|-
|Left, Right
|Move active cursor left / right
|-
|Shift+Left, Shift+Right
|Fast move active cursor left / right
|-
|Up, Down
|Move active cursor up / down, only if cursor is not bound to function values.
|-
|Shift+Up, Shift+Down
|Fast move active cursor up / down, only if cursor is not bound to function values
|-
|F2
|Activate next cursor of active graph (toggle)
|-
|F3
|Mirror inactive cursor around active cursor position (toggle)
|-
|Ctrl+F3
|Mirror active cursor around inactive cursor position (toggle)
|-
|C
|Change cursor style of active graph (cyclic)
|-
|B
|Bind / unbind cursors (y<nowiki>-</nowiki>scale) to / from function displayed in active graph
|-
|L
|Lock/unlock time cursors (toggle)
|-
|M
|Move the cursors to selected segment marker.
|-
|1
|In the [[User_Guide/Spectrogram_and_Parameter_Viewer#Waveform_zoom_window|Waveform zoom window]], pressing 1 will use the position of the selected cursor to adjust the position of the selected cursor in the spectrogram and parameter graphs. This is useful for fine-grained positioning. In all other graphs, 1 will set selected part of parameter function to the value entered in the input field.
|-
|colspan=2|'''Segments'''
|
|-
|Del
|Delete the selected segment marker from the graphics and from the project!
|-
|Ins
|Create a new segment over the signal bracketed by the cursors of the active graph.
|-
|Ctrl+Ins
|Create a new segment over the signal bracketed by the cursors in the active graph and save the parameters in this segment.
|-
|Ctrl+Shift+Ins
|Create a new segment over the signal bracketed by the cursors in the active graph and then select profile to analyse new segment.
|-
|H
|Hide segment markers (if visible) or mark all segments in analysed range (if hidden, without name dialog)
|-
|W
|Write (changed) position of segment marker to the project. This calls the <samp>segmentSaveSelected</samp> command.
|-
|Ctrl+M
|Move the selected segment marker to the cursor positions. The segment controls and the segment marker are updated, but the new position is not saved in the project.
|-
|Z
|Copy the position of the (running) play cursor into the Seg. field of the segment dialog
|-
|colspan=2|'''Navigation'''
|
|-
|Tab, Shift+Tab
|Active next/previous graph or dialog control.
|-
|Ctrl+Tab
|Toggle focus between dialog and last activated graph
|-
|colspan=2|'''Parameters'''
|
|-
|0
|Set selected part of parameter function to zero
|-
|1
|Set selected part of parameter function to the value entered in the input field. This hotkey is available in all graphs except for the [[User_Guide/Spectrogram_and_Parameter_Viewer/Sectioner|Waveform Zoom]]. In the Waveform Zoom window, pressing one will use the position of the selected cursor to adjust the position of the selected cursor in the spectrogram and parameter graphs. This is useful for fine-grained positioning.
|-
|Ctrl+0
|Mask out all parameters between the cursors which have no value in the selected parameter line.
|-
|Ctrl+C
|Copy selected part of parameter function to another compatible parameter function
|-
|D
|Replace selected part of parameter function with the line connecting the cursors (use rubber line for preview)
|-
|E
|Enable edit mode for parameter selected in the parameter list (dialog)
|-
|F
|Start f0<nowiki>-</nowiki>test for the spectrum displayed in the sectioner window
|-
|Ctrl+G
|Exchange selected part of parameter function with an other compatible parameter function
|-
|J
|Join all broken parts inside the selected part of the frequency function to one track (replace gaps with interpolated lines)
|-
|Ctrl+Z
|Undo last parameter edit command, only one undo step is possible
|-
|S
|Show statistics of parameter selected in the parameter list (dialog)
|-
|Ctrl+S
|Save parameter functions in project.
|-
|X
|End parameter edit mode
|-
|Ctrl+X
|Move selected part of parameter function to an other compatible parameter function
|-
|Ctrl+ Num *
|Multiply selected part of parameter function with factor entered in input field
|-
|colspan=2|'''Layout'''
|
|-
|Ctrl+N
|Switch to next sectioner layout (circle)
|-
|Ctrl+W
|Hide/show sectioner windows (toggle)
|-
|Ctrl+T
|Toggle between parameter and segment dialog
|-
|colspan=2|'''Playback'''
|
|-
|Space
|Play signal bracketed by cursors
|-
|Ctrl+P
|Play signal of selected segment marker in active graph
|-
|Q
|Play whole signal displayed in active graph
|-
|P
|Play signal window before / after current cursor. The window length and alignment is defined by the [[../Settings_Dialog#play_window|play window settings]].
|-
|Esc
|Stop playback
|-
|F4
|Increase play window length (double)
|-
|Ctrl+F4
|Decrease play window length (half)
|-
|T
|Toggle play window alignment (before / after)
|-
|Ctrl+L
|Toggle audio loop on and off
|-
|colspan=2|'''Zoom'''
|
|-
|NUM+
|Zoom in to graph centering around the active cursor on the x axis
|-
|NUM-
|Zoom out of graph centering around the active cursor on the x axis
|-
|Ctrl+NUM+
|Zoom in to graph centering around the active cursor on the y axis
|-
|Ctrl+NUM-
|Zoom out of graph centering around the active cursor on the y axis
|-
|V
|Zoom in to the area between the cursors on the x axis.
|-
|Ctrl+V
|Zoom in to the area between the cursors on the y axis.
|-
|Shift+V
|Zoom in to the area between the cursors on both the x and y axes.
|-
|Shift+NUM+
|Increase the floor (spectrogram)
|-
|Shift+NUM-
|Decrease the floor (spectrogram)
|-
|O
|Toggle between zoom and overview modes
|-
|Ctrl+O
|Reset the zoom (zoom out completely)
|-
|colspan=2|'''Misc'''
|
|-
|R
|Set cent reference frequency to the frequency of the active cursor in the sectioner spectrum window
|-
|Ctrl+A
|Turn automatic sectioner update on/off (toggle). This calls the <samp>sectionerPlot</samp> command.
|-
|F8
|Update sectioner windows using signal around position of selected time cursor. Only needed, if automatic update is disabled
|-
|Ctrl+F8
|Compute averaged spectrum of bracketed signal.
|-
|Y
|Enable/disable the "use<nowiki>-</nowiki>Y for range selection" option
|-
|A
|Start a viewer / analyser application for the bracketed signal. A dialog to select the application and profile is displayed.
|}

User Guide/Spectrogram and Parameter Viewer

2019-10-01T12:18:52Z

Jw: /* Stopping playback */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{V2}}
The application {{Viewer2}} implements spectrogram and parameter analysis methods for mono signals. The application window contains the time synchronous plots of the results of the selected analysis methods, the [[User Guide/Spectrogram and Parameter Viewer/Sectioner windows|Sectioner windows]] and the control dialog (see the [[User Guide/Spectrogram and Parameter Viewer/Settings Dialog|settings dialog]]). The computed parameter functions can be edited and saved in the current project. The Sectioner windows (displayed above all other graphs) , contain the waveform and the spectrum of the signal around the active time scale cursor. The [[User Guide/Spectrogram and Parameter Viewer/Sectioner windows|Sectioner]] also implements functions for spectrum averaging, spectrum statistics and fundamental frequency measurement. For the parameter functions, simple graphical edit and statistic functions are implemented and can be controlled via the control dialog (if the control dialog is not visible, activate using the menu General -> Toggle Dialog).

The example below shows the spectrogram with overlaid formant tracks and segment markers, the fundamental frequency track and the waveform of a speech signal. This plot was generated with the default settings of the profile "FFT_Speech".

[[File:v2_profile_fft_speech.png|thumb]]

==Features==

===Methods===

The source signal can be analysed using a multiple of different [[/Methods/|methods]]. The {{Viewer2}} comes with a set of [[/Pre-Configured Profiles/|pre-configured profiles]] to cover the most common configurations. You can create new profiles with your desired combination of analysis methods by copying an existing profile.

===Parameters===

The parameters calculated by the chosen methods are displayed as function lines in the chosen graph. [[/Statistics/]] are available for each parameter. They can be individually viewed and [[/Editing parameters/|edited]] in the [[/Control dialog/|control dialog]] and graph, [[/Saving parameters/|saved]] for later analysis or [[/Copying parameters to the clipboard/|copied to the clipboard]] for exporting to other applications.

===Playback===

You can play the signal displayed in the {{Viewer2}} by either selecting the command from a menu or using a [[/Spectrogram and Parameter Viewer Hotkeys/|hotkey]]. You can play the signal between the cursors with the hotkey P. You can play back the whole signal with the hotkey Q.

====Looping playback====

You can turn looping on and off with the hotkey <kbd>Ctrl+L</kbd>.

====Stopping playback====

You can stop playback with the hotkey <kbd>ESC</kbd>.

===Scale Range Auto-Scaling===

The best scale range for the analysed signal can now be calculated automatically using the auto-scale feature. The following Spectrogram & Parameters Viewer methods support auto-scaling:

* f0 (harmonic grid)
* formants
* frq.-band signal energy
* signal energy (rms)
* spectrogram
* waveform

In addition, the Sectioner and Spectrum Viewer supports auto-scaling too.

You can turn auto-scaling off for a Viewer's profile using the 'enable zoom and autoscaling' checkbox in the [[User Guide/Spectrogram and Parameter Viewer/Settings Dialog|profile's settings dialog]]. Auto-scaling can then be enabled or disabled for each [[User Guide/Spectrogram and Parameter Viewer/Methods|individual method]] in its settings dialog. Sectioner auto-scaling is enabled in the [[User Guide/Spectrogram and Parameter Viewer/Sectioner Settings Dialog|Sectioner settings dialog]].

===Cursors - using the mouse to get detailed information===

There are two [[/Cursors/|cursors]] available in each graph which can be used to mark sections of the signal on which commands should act, e.g. create a new segment, zoom the graph, listen to a section, edit parameters etc. Information pertaining to the signal at the cursors is displayed in the control dialog.

===Zooming in the graphs===

Zooming in the {{Viewer2}} is available on both time, frequency and amplitude axes using [[User Guide/Spectrogram and Parameter Viewer/Spectrogram and Parameter Viewer Hotkeys|hotkeys]] or the context menu. See [[User_Guide/Tutorials/Zooming_in_a_Viewer|Zooming in a Viewer]] for general details about zooming.

===Waveform zoom window===

The top left-hand window - the waveform zoom window - shows a waveform of the signal directly around the active time cursor.

===Sectioner===

The Sectioner graph in the upper right-hand corner displays an amplitude/frequency plot of the signal at the active cursor. The Sectioner also implements functions for spectrum averaging, spectrum statistics and fundamental frequency measurement. See [[User_Guide/Spectrogram_and_Parameter_Viewer/Sectioner|The Sectioner]] for details.

==The Control Dialog==

At the bottom of the display, a dialog displays information about the cursors, segments and parameters. This is called the [[/Control dialog/|control dialog]]. You can create segments, annotate and edit parameters here. The dialog can be shown and hidden via the ''General > Show/Hide Dialog'' menu.

==Hotkeys==

A list of hotkeys available in {{V2}} can be found [[/Spectrogram_and_Parameter_Viewer_Hotkeys/|here]].

==Settings==

All settings are available in the [[/Settings Dialog/]] reached via the context menu for the selected [[/Pre-Configured Profiles/|profile]] in the [[User_Guide/Workspace/Application_and_Setup_Tree/Signal_Analysis_and_Display|Application and Setup Tree]]or via the <samp>General -> Setup / Redraw</samp> menu in {{Viewer2}}.

==Segments==

You can create segments in {{Viewer2}} using the 'Name' function. Select an area of the signal and select name from the context menu. The segment is created in the project. If you would like to move an existing segment, press the <kbd>Ctrl</kbd> key and drag the segment. If you would like to save your changes, press the [[User_Guide/Spectrogram_and_Parameter_Viewer/Spectrogram_and_Parameter_Viewer_Hotkeys|<samp>segmentSaveSelected</samp>]] hotkey

==Menus==

The following menus are available in {{Viewer2}}:
* [[/General_Menu/|General]]
* [[/Sectioner_Menu/|Sectioner]]
* [[/Segments_Menu/|Segments]]
* [[/Editing_parameters|Edit]]
* [[/Toolbox_Menu/|Toolbox/]]
* [[/Help_Menu/|Help]]

==Context Menus==

Many of the functions in the {{Viewer2}} are available via context menus.
* [[/Context Menu of Spectrogram and Parameter Graphs/|Spectrogram and Parameter Graphs]]
* [[/Context Menu of Sectioner Spectrum Graph/|Sectioner Spectrum Graph]]
* [[/Context Menu of Sectioner Waveform Graph/|Sectioner Waveform Graph]]

==Print or Copy to Clipboard==

You can print a copy of the whole display, or of the active graph either by selecting ''Copy/Print'' from the context menu or ''Print'' from the General menu. This opens the [[User_Guide/Copy_or_Print_Dialog|Copy or Print]] dialog. The printer settings can be modified via ''Print Settings'' in the ''General'' menu.

User Guide/SPExL/Transcription Script

2019-10-01T12:16:59Z

Jw: /* Versions */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{User Guide}}
{{SPExL}}
{{Hotkeys}}
[[File:stx_ug_spexl_transcription.png|thumb]]

The 'Transcription' script is a tool in {{STX}} specifically written for transcribing sound files. The idea is to make transcribing as simple and efficient as possible. In addition to using the mouse, you can do the transcribing with the keyboard alone. The hotkeys are user-definable.

<div class="noautonum">
{{TOC limit|2}}
</div>

You will find it in the bottom left-hand corner of the [[User_Guide/Workspace|Workspace]] where it is called <code>Transcription</code>.

When starting the Transcription script, you must select the sound file in the Workspace you wish to transcribe. This is unlike the [[User_Guide/Workspace/Application_and_Setup_Tree/Signal_Analysis_and_Display/Profile|analysis profiles]], which analyse a segment. The following dialog will then appear.

[[File:Stx_transcription_startup_dialog.png]]

==Spectrogram / Waveform Views==
You can display either a spectrogram or a waveform of the sound file (or both). There three different combinations available:
===Whole file as waveform, with section as spectrogram===
This view displays a waveform of the whole file and a spectrogram of a section of that file. This means that you can see all the segments in the file in the waveform graph. Navigating around the file in the waveform, you can then view a section of it as a spectrogram (e.g. with the hotkey <kbd>S</kbd>). When starting the transcription script, choose '''wave overview & spg. section'''.

===Section of file as waveform===
This is the fastest view, displaying a section of the sound file as a waveform. The whole of the file is available to scroll through. When starting the transcription script, choose '''wave only'''. The length of signal displayed is specified by the scrollbar '''Length''' value in the start-up dialog. You can then scroll through the sound file using, for example, the hotkeys <kbd>M</kbd> (forwards) and <kbd>N</kbd> (backwards).

===Section of file as synchronised waveform and spectrogram===
This view displays a section of the sound file as both a waveform and a spectrogram. The waveform and spectrogram are time-aligned. The initial length of analysed signal is determined by the '''Length''' value in the start-up dialog. You can zoom in and out of the signal as well as scroll through the whole sound file.

Note that the '''Fixed''' checkbox will mean you can zoom into a signal, but cannot zoom out to display more of the signal than the length specified by 'Length'.

==Dialog Description==

[[file: Spexl_dialog.png]]

===timebar===
The timebar lets you scroll through the sound file. This is useful, if you have a large sound file, and therefore only load part of it at any one time.
* The <samp>|<</samp> button scrolls back to the beginning of the file.
* The <samp><</samp> button scrolls back one step.
* The <samp>></samp> button scrolls forward one step.
* The <samp>>|</samp> button scrolls to the end of the file.
* The <samp>Play</samp> button plays the whole signal currently loaded from disk.
* The <samp>Draw</samp> button redraws the section of the sound file specified by the scroll bar (if <samp>auto</samp> is unchecked).
* The <samp><Seg</samp> and <samp>Seg></samp> buttons scrolls to the previous and next segments outside of the current loaded signal. This can be useful, if you have a long file with few segments in it.
* If the <samp>auto</samp> setting is checked, then moving the scroll bar automatically redraws the graphs. This is the default. If unchecked, you must explicitly press the <samp>Draw</samp> button.

If you are already viewing the entire sound file, the time bar is not very useful. See [[#Scrolling|Scrolling]] for further details.

===spec.===
The <samp>spec.</samp> area of the dialog is only enabled if the spectrogram graph (<samp>wave & spg. section</samp> or <samp>wave overview & spg. section</samp> view) is being used. Choose the 1st or 2nd frame/overlap settings specified in the [[User_Guide/SPExL/Settings#Spectrogram_Display_and_Parameter_Setup|settings dialog]].

===f0/for.===

The F0 and formants can be calculated for the displayed spectrogram. This is not available in the <samp>wave only</samp> view. See [[User_Guide/Transcription_Script#F0_.2F_Formant_Extraction|F0 and Formant Extraction]] for further details.

===main===

Here you can save changes you've made to your segments ([[File:resource_dosave.png]]), revert any changes you have made since you last saved the project file ('Revert'), open the settings dialog ([[File: Resource setup.png]] or exit the transcription script.

===playback===

The playback section of the dialog can be used to play the sound file. The most interesting setting is the ability to repeat the signal when played, which can be useful when transcribing. Alternatively you can repeat the signal forever (or until the ESC key is pressed).

===cursor control===

In addition to moving the cursors around by clicking and dragging in the graph, you can also do it with these buttons. All buttons are also associated with [[#Hotkeys|hotkeys]].

==Scrolling==

Since displaying a long sound file can take a while, it can be useful to load only part of the sound file. This is achieved with scrolling in the <samp>wave only</samp> and <samp>wave & spg. section</samp> [[User_Guide/Transcription_Script#Spectrogram_.2F_Waveform_Views|views]]. The lowest graph displays the section of the sound file which is loaded (purple) and visible (brown).

Note that the <samp>wave overview & spg. section</samp> [[User_Guide/Transcription_Script#Spectrogram_.2F_Waveform_Views|view]] always loads the whole sound file.

==F0 / Formant Extraction==
You can display the F0 and formants in the spectrogram by pressing the [[File: Resource run.png]] button. The settings for extraction are in the [[User Guide/SPExL/Transcription_Script/F0_Formant_Extraction_Settings|F0 / Formant Extraction Settings]] dialog reached by pressing the 'f0/for' button [[File: Resource setup.png]].

==Settings==
There are many settings you can change via the [[User Guide/SPExL/Transcription_Script/Settings|Settings]] dialog reached by the 'main' [[File: Resource setup.png]] button, or the 'settings->setup dialog' context menu.

==Hotkeys==

Many operations are available using hotkeys.

===User Defined Hotkeys===

As of version 1.1, these hotkeys can be changed by the user by modifying the <samp>spexl_segtrans.hotkeys</samp> file. The default hotkeys are defined in the file <samp>spexl_segtrans.hotkeys.default</samp>. These files are in the <samp>scripts</samp> directory in {{STX}} <= 4.4.10 and in the <samp>profiles</samp> directory in {{STX}} >= 5.0.


==Versions==
Note that versions > 1.0 require {{STX}} >= 4.4

===1.1.10===
* bugfix: Playlist listview now processes listsorted message and displays sort order set by clicking a column heading. The sort order was first being displayed when clicking in the control after clicking the column heading.
===1.1.9===
* feature: removed the now unnecessary 'autoDraw' function.
* bugfix: use 'ID' as default attribute for text in segments where no attribute is specified.
===1.1.8===
* feature: removed the now unnecessary 'Refresh' button
===1.1.7===
* bugfix: the /U ASegTemplate flag is now respected, and, if used, the last entered value for a segment attribute is used as the default for the next new segment.
===1.1.5===
* bugfix: segment placement algorithm no longer drawing segments off screen.
* bugfix: moving scrollbar no longer generates an error message in the log window.
Download [https://www.kfs.oeaw.ac.at/pub/stx/spexl/ Transcription script downloads].

Main Page

2019-10-01T11:41:04Z

Jw: /* Download */

== {{STx}} {{VERSION}}==

{{STX}} is a software tool for the analysis, signal processing and annotation of Wave sound files. {{STX}} runs on the Windows operating system. It was originally a port of the S_TOOLS application for dedicated DSP hardware developed at the [https://www.kfs.oeaw.ac.at Acoustics Research Institute] in the 1980s. This documentation is work in progress and by no means complete. If you fail to find something you need, please [[Contact|get in touch]] with the development team.

=== Using {{STx}} ===

* [[User_Guide|User Guide]]

=== {{STx}} Programming ===

* [[Programmer_Guide/STx_Guru|Starting with {{STx}} Programming]]
* [[Programmer_Guide|Programmer Guide]]
* [[Programmer_Guide/Quick_Reference|Quick Reference]]

=== About {{STx}} {{VERSION}} ===

* Platform: runs on Windows Vista and higher
* [[History of Changes]]
* [[Known Bugs]]
* [[Feature Requests]]
* [[Contact]]
* [[Running STx under Linux or macOS]]

=== Download ===

[https://www.kfs.oeaw.ac.at/pub/stx/stx-5.0.3.9967-freeware.exe STx 5.0.3]

[https://www.kfs.oeaw.ac.at/pub/stx/ older releases]

==MediaWiki Links==
* [[STx Documentation Style Guide|Style guide]] for documenting {{STx}} in this wiki.
* Consult the [http://meta.wikimedia.org/wiki/Help:Contents User's Guide] for information on using the wiki software.
* [http://www.mediawiki.org/wiki/Manual:Configuration_settings Configuration settings list]
* [http://www.mediawiki.org/wiki/Manual:FAQ MediaWiki FAQ]
* [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki release mailing list]
__NOTOC__

Template:VERSION

2019-10-01T11:23:49Z

Jw:

5.0.3

History of Changes

2019-10-01T11:18:56Z

Jw: /* 5.0.2 */

<div class="noautonum">{{TOC limit|3}}</div>
=5.0=

==Features==

===Compact Workspace Mode===
The Workspace now has a [[User_Guide/Workspace#Modes|compact mode]]. The compact mode is a simplified interface for new users. Although it was designed with linguists in mind, it can be used by anyone.

===webMAUS===
Automatic segmentation using the [https://clarin.phonetik.uni-muenchen.de/BASWebServices/interface webMAUS] REST API. This has been implemented in the toolbox [[User_Guide/Toolbox/runMAUSBasicDlg|<samp>runMAUSBasicDlg</samp>]].

==Bugfixes==

* Correctly handle corrupt Workspace file (generate new one, rather than silently exiting)

==5.0.3==

Released: 1st October 2019

Revision: 9967

* feature: Signal.All is now selected by default, if no other segment is selected.
* feature: When exporting profiles, the present working directory is used, rather than always selecting the 'profiles' directory. The profiles directory is only used if the present working directory is the root directory.
* feature: The first sound file in the project is selected by default in the compact mode.
* bugfix: When adding a file per drag and drop, the file is now selected.
* bugfix: enabling a disabled edit box now sets the background color correctly (back to white).
* bugfix: debugger trace window now visible in release version too
* bugfix: [[Programmer_Guide/Command_Reference/SYSINFO|SYSINFO]] command now supports Windows 8.1 and Windows 10 (was returning Windows 8)
* bugfix: SPExL V1.1.10. Playlist listview now processes listsorted message and displays sort order set by clicking a column heading. The sort order was first being displayed when clicking in the control after clicking the column heading.
* bugfix: The 'Start' button should now be activated correctly in the Compact Mode.

==5.0.2==

Released: 19th September 2019

Revision: 9946

* bugfix: The context menu Add Sound File now working from the Audio File list in the Compact Mode.
* feature: The possible number of plots in XPlot was increased from 64 to 128

==5.0.0==

Released: 12th September 2019

Revision: 9935

Initial release.

=4.4=

==Features==
===Transcription Script SPExL 1.1.6===
The transcription script SPExL has been simplified and improved.
* Hotkeys can be defined by the user in the SPExL_SegTrans.hotkeys file
* The number of available 'views' has been reduced to 3:
** wave overview & spg. section (a waveform of the whole file in the top graph, with a section of the file as spectrogram below)
** wave only (a waveform of a section of the file with scrollbar functionality)
** wave and spg. section (a synced waveform and spectrogram of a section of the file with scrollbar functionality)
* Segment selection between graphs and the list are now synchronised. If you select a segment in the graph, it is selected in the list and vice versa.
* Changes made to the project (new segments, edited attributes) are now made directly in the project rather than the user having to explicitly press the 'save segments to project file' button to copy them from SPExL to the Workspace. Note that they are only written to disk, however, if the project is saved (press the 'Save' button).
===Visible Segment Attributes Saved per Project File===
If you choose to display other attributes other than the default attributes in the Workspace Detail View, these settings are now saved in the open project file. When a project file is then opened, the relevant attribute list is loaded and used, rather than the user having to [[User_Guide/Workspace/Detail/Search_for_Element_Attributes|search for them]] again. You can still modify which attributes are displayed using the General Settings [[User_Guide/Workspace/Application_and_Setup_Tree/Options/General_Settings#.22Set.22_Attributes_.26_.22Segment.22_Attributes|'Select "Segment" Attributes' dialog]].
===Global / Profile Sectioner Settings===
The sectioner settings in the {{Viewer2}} analysis application were always global to STx. As of STx 4.4.0, you can choose to save your sectioner settings with your profile. The default is still the 'global' variant. To switch to profile sectioner settings, uncheck the '''use global sectioner settings''' checkbox in the {{Viewer2}} [[User_Guide/Spectrogram_and_Parameter_Viewer/Settings_Dialog|settings dialog]].

==4.4.10==

Released: 17th January 2019

Revision: 9712

* bugfix: playback gain factor - the playback gain is now working also for asio devices (see CSTXASIOEngine::Transfer())
* bugfix: renumbering command did not update detail as expected.
* bugfix: the update version dialogs now display the correct workspace path

==4.4.9==

Released: 25th September 2018

Revision:

* feature: don't ask user where to put sound file if there are no sets in the project.
* feature: dragging and dropping a template onto {{ST}X} copies it to the templates folder.
* feature: added 'Open Containing Folder' context menu for sound files and links. Improved contextualisation of context menu in detail (overview==root/set)
* feature: 'txt2wav' script: Adding decimal symbol and field delimiter to parameters, as well as the ability to specify which extension to use to filter files (was hard-coded to 'txt'). Now this macro can be used to
* feature: bdataset createwave and createwwaveex now take an openmode keyword: auto|create|read|write, which is passed on to bsf open. This means that we can now open files in modes other than 'auto'.
process CSV files.
* bugfix: very long capture text for edit controls with 'text above' could lead to capture static being longer than the edit control and unintentionally overlapping with other controls (e.g. in Transcription Setup dialog).
* bugfix: closing con log window no longer resets PARENT shell variable, unless it is set the the con log window itself.
* bugfix: sound files now opened using the FILE_SHARE_READ dwShareMode. This should mean, that STx no longer prevents other processes from reading the sound files.
* bugfix: viewer opens sound file in read mode, rather than read/write.
* bugfix: the !PATH attribute (MakePath()) now returns the correct path for files in the root of a drive. Bug was introduced in r8998 (STx 4.2.19). This was, for example, was causing sound files in the root directory not to be unloaded, and hence was causing sharing violations.

==4.4.8==

Released: 25th July 2018

Revision: 9500

* feature: Spectrogram & Parameters viewer sectioner window now remembers which function cursor is bound to when being replotted.
* feature: The <samp>downsampling.sts</samp> script now has a <samp>ResampleCLI</samp> macro for automatic resampling of one or more files (see source). The old <samp>ResampleDialog</samp> was renamed to <samp>ResampleDLG</samp>.
* feature: Adding help for "Import_PRAAT_TextGrid" toolbox.
* feature: Adding ability to edit 'Sectioner Settings' from the profile dialog.
* feature: Transcription 1.1.8 - removed segment 'refresh' button, since segments always reflect current project state.
* bugfix: a window that was maximised will now be maximised to the correct monitor. It was always being maximised to monitor 1 on display creation.
* bugfix: the profile version number is now imported with the profile. This means that, for example, the use global profile settings flag is now also set correctly on import.
* bugfix: minor fix of position of two controls which were overlapping with controls beneath
* bugfix: stop playback cursor if wave is stopped by starting playback in another graph. Beforehand, the playback cursor was stopped if it got to the end, or the ESC key was pressed.
* bugfix: Y coordinate vector conversion was inaccurate by 1 pixel (bug introduced in r2536) This affects the XY, parameter, scatter, wave and waterfall functions.

==4.4.6==

Released: 21. March 2018

Revision: 9441

* bugfix: some bugfixes and minor changes in BSeq
* bugfix: BScript: logging of unhandled messages in msg-loop disabled // Conlog: /ton and /toff options implemented (timer on/off + show elapsed time)
* bugfix: Viewer3 settings now being saved (bug introduced in r9318 - STx 4.4.0)
* bugfix CShellFile::Status() - catch CTime exception if file time is illegal (avoid program crash)

==4.4.5==

Released: 19. February 2018

Revision: 9416

* bugfix: in Viewer2 large asegtemplates (with many fields) are now displayed correctly - note: the same problem exists in Viewer1 if the segment dialog part (created by the macro call ""metasegment msdialog") needs more than 90 controls (around 40 segment attributes)
* feature: the bscript.stx function loaddata (con loaddata) can now also load string tables (extenden tables) from csv-files. The file types TEXT/TEXTCONTINUATION (numeric parameter table), STRING/STRINCONTINUATION (extended string table) and BINARY (binary stx-data files) are available. Type ASCII/ASCIICONTINUATION has been removed.
* feature: new feature (bugfix?): CShellTable::Read() - handling of field-separator tab has been changed - empty fields are now possible - warning: may have an effect on existing script/macro code!

==4.4.4==

Released: 26. January 2018

Revision: 9404

* bugfix: combobox entries with underliners retain their underliners now in the workspace detail (reported by Anton Baotic), and in Spexl.

==4.4.3==

Released: 18. December 2017

Revision: 9391

* bugfix: adding missing Transcription hotkey file and retisimo scripts

==4.4.2==

Released: 30. November 2017

Revision: 9377

* bugfix: SPExL Transcription script V1.1.7: the /U ASegTemplate flag is now respected, and, if used, the last entered value for a segment attribute is used as the default for the next new segment.
* bugfix: default profile names no longer have the invalid blank character in them. A check was also added, so new profiles cannot be created with blanks.

==4.4.1==

Released: 23. November 2017

Revision: 9369

* bugfix: if zooming is turned off in {{Viewer2}}, segments are now correctly visible on the Y axis. This bug has existed since at least STx 4.2.

==4.4.0==

Released: 14 November 2017

Revision: 9350

Initial release.

=4.3=

==Features==
====Load or export parameters from super or sub segments====
Parameters from super segments or from sub segments can now be loaded into the selected segment. For example, if you have analysed a word and corrected the parameters, you can use these corrected parameters when viewing phoneme segments within the word. This is achieved by selecting 'super segment data only' setting in the Viewer settings [[User_Guide/Spectrogram_and_Parameter_Viewer/Settings_Dialog#Parameter_IO_Configuration|Parameter IO Configuration]] dialog.

It is possible to select which super/sub segment parameters should be used, filtering by time, attribute or ID.

This feature is also available in the parameter export dialog.

====Parameter setting summary====
A summary of the settings used for parameter analysis is now saved with the parameter in the project file. This information is displayed in the [[User_Guide/Workspace/Detail/Views/Parameter_View|Parameter View]].

====Exact sample positioning in {{Viewer2}}====

You can now select a position in the [[User_Guide/Spectrogram_and_Parameter_Viewer#Waveform_zoom_window|Waveform Zoom window]] in {{Viewer2}} and move the active time cursor to that position using the hotkey '1'. This is useful for exact positioning of the time cursors when segmenting, for example, words.

==4.3.10==

Released: 26. January 2018

Revision: 9407
*bugfix: do not allow user to give a profile a name including blanks.
*bugfix: renaming spectrum profiles (removing blanks)
*bugfix: the correct most recently entered value in a listctrl is now saved (not the last in the list).
*bugfix: passing delete, insert and back keys to static control.
*bugfix: 'spexl*.hotkeys.default' 'retisimo.sts' 'retisimo_*.sts' 'HRTF_II_new.txt' 'downsample.sts' files are now being copied too (bug introduced in r8789)
*bugfix: removing extraneous / from Editing segments help URL
*bugfix: combobox entries with underliners retain their underliners now in the workspace detail (reported by Anton Baotic), and in Spexl.

==4.3.9==

Released: 23. November 2017

Revision: 9363

* bugfix: if zooming is turned off in {{Viewer2}}, segments are now correctly visible on the Y axis. This bug has existed since at least STx 4.2.

==4.3.8==

Released: 14. November 2017

Revision: 9347

* bugfix: zooming and replotting in the xplot class now working
* feature: user is now informed about bugfixes in current release, and/or new major/minor releases. This means that you will be informed of bug fixes for your version of STx, not just for the newest STx.

==4.3.7==

Released: 19. October 2017

Revision: 9328

* bugfix: stx no longer crashing on y zoom (bug introduced in r9293 - STx 4.3.6)
* bugfix: binary_file_example.sts now working
* bugfix: if navigating in file dialog using the keyboard, the edit box is now updated with the selected file.

==4.3.6==

Released 25. September 2017

Revision: 9297

* bugfix: the spectrogram dataset now frees up memory once dataset is drawn
* bugfix: adding specials folder to installer

==4.3.5==

Released: 6. September 2017

Revision: 9286

* bugfix: auto-saving the project file no longer leaks memory
* bugfix: editing segments in the workspace now uses the segment template by default
* bugfix: a backup copy of the project file is now made when saving
* bugfix: lists with one item are now selectable with the keyboard
* bugfix: listview column width now calculated with correct font
* bugfix: default values from aseg templates now written to new segment before editing
* bugfix: correct default value written to segment, even if attribute value starts with a number
* bugfix: combobox entries no longer replacing underlines

==4.3.4==

Released: 3. July 2017

Revision: 9214

====Features====
* feature: the [[Programmer_Guide/Macro_Library/CONLOG|conlog]] command can now log to a file.
====Bug Fixes====
* bugfix: the conlog savedata command no longer fails silently if the file cannot be created.

==4.3.3==

Released: 19. June 2017

Revision: 9185

====Bug Fixes====
* bugfix: segment address in the Transcription script is now rounded to 10th of a millisecond (4 decimal places) rather than 1 millisecond.
* bugfix: saving the project file now resets the automatic save timer.
* bugfix: the Transcription, Import Word List and Reorder Word List should now be working correctly again.
====Features====
* feature: new script: [[User_Guide/Scripts/Anonymize.sts|Anonymize.sts]] - anonymize segments (attributes and signal) - requested by the ARI phonetics group
* feature: adding option to automatically save every minute.

==4.3.2==

Released: 13. June 2017

Revision: 9170

====Bug Fixes====
* bugfix: The segment 'Signal.All' is now created when a new sound file is imported. This bug was introduced in version 4.3.1.
* bugfix: the 'wave-only' view in the Transcription script is now available again.

==4.3.1==

Released: 8. June 2017

Revision: 9165

====Bug Fixes====

* bugfix: clicking SPExL graph whilst editing segment in the segment list now draws the segment in the graph (previously needed an explicit refresh to draw the segment).
* bugfix: the workspace is now saved even if the path contains spaces (bug introduced in r8843)
* bugfix: searching using keyboard in listctrl now working in correct order (not backwards). Bug introduced in r9002.
* bugfix: zooming out in SPExL on the y axis with Ctrl+Subtract is now working correctly. This appears to have been around since at least r4442 (STx 3.9)
* bugfix: y position of cursors is now retained when zooming
* bugfix: Viewers/SPEXL create segments at selected address and not with P=0 and L=0
* bugfix: maximising whilst spectrogram is drawing no longer leaves the spectrogram in unfinished version on screen (set new 'm_bRecalculate' flag to force recalculation/redraw when dataset sync has finished).

==4.3.0==

Released: April 2017

Revision: 9149

=Older Versions=

==4.2==
====4.2.23====
Released: 24 August 2017
Revision: 9264
* BUGFIX: correct font used for calculation of formant dialog column size in {{Viewer2}}

====4.2.22====
Released: 25 January 2017
Revision: 9064
* BUGFIX: The following wildcard string comparison will now match:
<pre>
if '*ha' =SI 'haha' then
// it's a match :-)
end
</pre>
* BUGFIX: Changed behavior of comparisons in FIND-TABLE/XML: if a field/attribute is not defined all "notequal" and "notmatching" operators evaluates to "true" and all others to "false"

====4.2.21====
Released: 9 January 2017
Revision: 9023
* BUGFIX: Edit segment dialog now referencing correct segment attributes (bug introduced in r8852 - STx 4.2.15)

====4.2.20====
Released: 23 December 2016
* FEATURE: STx now informs the user of available update via the About dialog.
* BUGFIX: Removing non-existent files from STX.INI when loading
* BUGFIX: About dialog no long blocking workspace file.

====4.2.19====
Released: 12th December 2016
* BUGFIX: Ctrl+U no longer the same as Ctrl+Shift+U in, e.g., signal view.
* BUGFIX: Generating correct hotkey string for Ctrl+Shift+<key>
* BUGFIX: Switching from long to short list of segments in the workspace should no longer lead to a blank detail.
* BUGFIX: Transcription left cursor right bitmap now correct image
* BUGFIX: Fixed bug in Viewer2 where setting the range did not work under all circumstances.
* BUGFIX: Focus moving with selection for listview key navigation and single selection.
* BUGFIX: Copy attributes in the Workspace overview now includes first value (bug introduced in r8297)
* BUGFIX: Checkbox size increased because some strings were being cut off.
* BUGFIX: Show Find Dialog menu now checked if Show Find Dialog is visible
* BUGFIX: Occasional crash in {{Viewer2}} fixed by removing use of static with CString (r9010,r9012).

====4.2.18====
Released: 27 October 2016

* FEATURE: adding PCM info to edit sound file dialog for editing existing project files too.
* FEATURE/BUGFIX: Improved listview keyboard handling (up/down, page up, page down). Disabled scrolling of listview whilst editing.
* BUGFIX: viewer2 no longer hangs if saved rmsb-data are loaded and displayed with autoscale-option
* BUGFIX: detail sequence view now using Ctrl+Shift+U to move selected entry up and Ctrl+Shift+D to move selected entry down (rather than Ctrl+UP and Ctrl+Down - which conflict with internal listview keyboard handling).
* BUGFIX: bscript log window no longer jumps in front of SPExL window when a dialog is opened.
* FEATURE: releases are now digitally signed by the Österreichische Akademie der Wissenschaften
* NOTE: the pole-zero sectioner in the {{Viewer2}} application is extremely slow for high frame rates. We are working on improving it.

====4.2.17====
Released: 26 September 2016
* BUGFIX: Transcription (SPExL) segment list handling working correctly again (bug introduced in 4.2.16)
* BUGFIX: Moving selected sequence entry up/down with keyboard now uses the hotkeys Ctrl+Shift+U and Ctrl+Shift+D (rather than Ctrl+Up and Ctrl+Down) and now works as expected.

====4.2.16====
Released: 30 August 2016
* Support for Windows XP has been removed.
* FEATURE: the XPLOT member "FORALLGRAPHS" is now a public function.
* FEATURE: the XGRAPH function Zoom -> X-Sync was aded to apply the x-zoom of the current graph across all other graphs.
* BUGFIX: the Automatic Segment Names dialog no longer allows invalid segment names.
* BUGFIX: The palette import/export are working again.
* BUGFIX: The Application and Setup tree now correctly stores it's state.
* BUGFIX: Keyboard focus no longer disappears after pressing enter in the Workspace Detail.
* BUGFIX: The selected entry no longer centers itself after editing.
* BUGFIX: The Transcription script SPExL now plays single selections every time (not every second time).
* BUGFIX: Tabbing through the entries in the Workspace Detail no longer goes backwards instead of forwards.

====4.2.15====
Released: unreleased
* FEATURE: Improved sound file export performance
* BUGFIX: The File->Workspace->Save As workspace menu command is now working (bug introduced in r4092)
* BUGFIX: parameter and function now drawing (invalidating) correctly if being set whilst zoomed in.
* BUGFIX: parameter export dialog no longer needs manual refresh (group box is now transparent - uses WS_EX_TRANSPARENT)

====4.2.14====
Released: 18 January 2016
* Minimising GDI use
* Projects files are now associated with {{STX}}
* BUGFIX: one memory leak fixed
* BUGFIX: all help menus associated with mediawiki online help
====4.2.13====
Released: 22 December 2015
* Default help file now the STx Wiki ([https://www.kfs.oeaw.ac.at/stx/docs/wiki/ https://www.kfs.oeaw.ac.at/stx/docs/wiki/]).
* BUGFIX: Find Segments dialog no longer uses ASet search criteria for ASeg search criteria when ASeg criteria is empty
* BUGFIX: Find Segments dialog can now search for segments within a time range.
* BUGFIX: assigning number values to an integer field using table[,field] := eval $#num1 + $#num2 syntax now works
* BUGFIX: growing table by assigning no longer corrupts heap.
*BUGFIX: force context menu to display within dialog window, even if called directly from shell with 0,0 coordinates.
*BUGFIX: edit segment dialog is now initialised with the segment channel
*BUGFIX: context menu now rebuilt before being displayed to ensure that it reflects current state.

====4.2.12====
Released: 4 December 2015
* Improved spectrogram 'overview' visualisation.

====4.2.11====

Released: 16 November 2015

* Added pole-zero to {{Viewer2}} Sectioner
* Bugfix: pane sizes are no longer reset in {{V2}} when sectioner settings dialog is closed.
* Bugfix: list view control header now correct size and clickable, and entries now selectable with one, rather than two clicks.
* Bugfix: copied attributes are no longer preceded by blank line

====4.2.9====

Released: 16 October 2015

* Bugfix: saving to PNG working again

====4.2.8====

Released: 5 October 2015

* Bugfix: the pole-zero method spectrogram overlay is now working correctly.

====4.2.5====

Released: 30 September 2015

* Feature: the pole-zero method is now available as an overlay in the spectrogram and parameter viewer's spectrogram graph. Note however, that this is not bug free, so please wait for 4.2.6 if you're interested in this feature.

====4.2.4====

Released: 10 September 2015

* Bugfix: added missing Visual C++ 2013 Redistributable Package

====4.2.3====

Released: 26 August 2015

* Metasegment size modification now locks modification mode

====4.2.2====

Released: 15 June 2015

* Viewer print font now legible

====4.2.0====

Released: February 2015

=====Features=====

* The speed of audio playback can now be set in the project interface
* The menu shell item has been given the alias 'DIALOG' and will now be refered to as such in the documentation (r8578)
* Pole-Zero [[Programmer_Guide/SPU_Reference/PZTF|SPAtom]] and [[Programmer Guide/Command Reference/EVAL/pztf|EVAL]] methods are now available and are integrated into the [[User_Guide/Spectrogram_and_Parameter_Viewer/Methods/Polezero|Spectrogram and Parameter viewer]].
* Support for Windows 2000/XP has been removed
* Pole-Zero SPU and EVAL methods
* Multiple bug fixes

==4.0==

===4.0.0===

Released: 2012

==3.9==

3.9.4

Released: 15th October 2009

* BUGFIX: real-time analyser drawing more smoothly

3.9.3

Released: 16th September 2009

* BUGFIX: sequences now being saved.

3.9.2

Released: 30th July 2009

* BUGFIX: segments no longer duplicated in un-linked datasets when importing metadata.
* BUGFIX: user-defined amplitude range working in waveform viewer
* BUGFIX: spectrogram amplitude floor now correct after using settings dialog
* BUGFIX: recorder application now recording

3.9.1

Released: 3rd July 2009

* BUGFIX: cmenu check/uncheck working for consecutive items
* BUGFIX: text files items and the load command can now read files encoded with an "FE FF" byte order mark (encoded in UTF-16BE). The error message "unsupported byte order mark" is returned if a UTF-32BE or UTF-32LE byte order mark is found.Supported encodings specified using a byte order mark: UTF-8, UTF-16LE, UTF-16BE<br /> Other supported encodings:windows-1252
* BUGFIX: wave files with chunks defined after the data chunk now have the correct length.
* BUGFIX: saving dataset faster
* BUGFIX: "load soundfile" options should no longer conflict with each other
* BUGFIX: prevent stack overflow in XML files with many siblings (~ 20000)
* BUGFXI: closing rtanalyser whilst it is running now exits shell correctly (without leaving ghost process).

3.9.0

Released: 15th April 2009

Graphical User Interface

General

S_TOOLS-STx now supports all fonts available on the host system.

Comboboxes in ASegTemplates can now be made editable using the flag <span class="stxmacrocommandoption-character">/E</span>.

You can enable/disable runtime error reporting in the Log Control dialog. It is disabled by default, and should only be enabled if you are having problems with S_TOOLS-STx.

Workspace

The segment list can now be edited in the Workspace.

A summary of existing parameters can now be displayed in the segment list (see the Display and Layout Settings dialog).

The Workspace Detail cells can now display text in multiple lines (see the Display and Layout Settings dialog).

Spectrogram & Parameters Viewer

The Spectrogram & Parameters Viewer can now display a harmonic cursor in the spectrogram graph.

The Spectrogram & Parameters Viewer spectrogram method Wavelet has been extended, and a new Cohen's class distribution method has been implemented.

An amplitude legend is now available in spectrogram plots (via the context menu).

DSP

The band-pass filters now have a window parameter.

Toolbox

The toolbox AutoSeg is available in Spectrogram & Parameters Viewer (if loaded) to automatically segment using peaks, clicks or pauses.

A range of Klatt speech synthesis and resynthesis toolbox functions are available.

The toolbox file 'SegmentImEx.sts' implements toolbox functions to import and export segments in the [http://www.fon.hum.uva.nl/praat/ PRAAT] file format. These functions are available in the Workspace.

Scripts

A script specifically designed for transcription and annotation has been developed and included in the default installation of S_TOOLS-STx. The script can be found in the script directory in the file SPExL.sts. There is also a new entry called transcription in the Workspace script tree, which calls the default segmentation routine. The SPExL macro documentation is still being written.

Macro Language

General

Modal window handling has now been moved to the NEW DISPLAY command. Use the option <span class="stxmacrocommandoption-character">/O=$#ownerDisplay</span> to set the owner (which is behind the new display in the z-order. You may also use the option <span class="stxmacrocommandoption-character">/Modal</span> to specify that the owner should be disabled whilst the new display exists.

The NEW command can create objects which are protected from deletion (option <span class="stxmacrocommandoption-character">/U|u</span>).

The command STXCONSTANTS now supports the keywords BITMAPS and BUTTONS.

The command TRANSLATE can now translate the contents of a variable or table.

The command EXIT -xLevel now returns to the first macro defining the label label "OnExitAll" or to the toplevel macro (1st called macro) (rather than to the first macro where the variable #EXITLEVEL = xLevel).

The new command TOKEN, an extended form of the command WORD, can tokenise a string using the specified delimiter.

The new command TRIM can be used to trim characters from the beginning and end of a string.

The new command QUOTE can quote all special characters in a string.

The new command LINELENGTH, although similar to LENGTH, returns the length of a line including delimiters.

The NAME command can now check XML attributes and S_TOOLS-STx XML IDs for syntactical validity. The NAME command can also return a UNC file name for a file on a mapped drive. This is useful, for example, for making DataSets portable in a network environment.

The new command ARG can be used to retrieve macro arguments.

The IREF command supports the option <span class="stxmacrocommandoption-character">/I</span> to simplify and suppress certain error messages.

The global variable @REPORTRUNTIMEERRORS can be set to 1 to display a dialog every time a error occurs when processing a command. Many commands can now take an option specifying that warnings should be generated, rather than errors (DRIVE, LOAD, UNLOAD, SET file LOAD|SAVE|STATUS|DELETE|RENAME|COPY|POSITION), READ, SEGMENT). If set to specify warnings, they will not cause a runtime error.

The READ command (and its variants READSTR, READTAB and READVAR) have a new option <span class="stxmacrocommandoption-character">/E</span> which can be used to escape characters in the input from being used as separators.

Format strings can now add a new line character (\n), using the tag %n. The standard C format tags %x and %X are now supported.

The KEYWORD command now supports the option <span class="stxmacrocommandoption-character">/F</span> which prevents abbreviations from being found and <span class="stxmacrocommandoption-character">/C</span> to make the comparison case sensitive.

The new commands SYSTEMCALL and SYSTEMCALLX are variants of SYSTEM and SYSTEMX which return warnings rather than errors on failure.

The command TGET can now return elapsed milliseconds, when the new option <span class="stxmacrocommandoption-character">/ms</span> is used.

The NAME command, when used with the new UNC subcommand can convert a file path on a mapped drive to its UNC equivalent. This help keep project files portable when accessed from multiple computers (E.g. when the z drive is mapped to \\server\data, the command "name 'z:\ds.xml' unc" will return "\\server\data\ds.xml".

The READ commands have a new option <span class="stxmacrocommandoption-character">/T</span> which prevents arguments from being trimmed.

The macro WINDOWSIZEDLG can be used to allow a user to set a window's size (width and height in pixels).

SPAtoms

The new SPAtom MIXALL mixes up to eight input arrays/vectors into an output array/vector with gain scaling.

The new SPAtom WLANA performs a general wavelet analysis, and the SPAtom CCANA implement a Cohen Class distribution.

The SPAtoms PVANA and PVSYN no accept a windowing function parameter.

The new SPAtom KLATTSYN can be used to generate synthesised speech.

EVAL command

The EVAL command has the following new subcommands:<br /> formants - a new formant tracking algorithm.<br /> limit, limitlow, limithigh - limits values to within a range of values.<br /> min, max - can receive more than one parameter.<br /> cdot, ctrn, conj - complex dot product, matrix transposition and conjugation.<br /> f0ac - F0 detection using autocorrelation.<br /> The EVAL command now supports numerical (e.g. >=), logical (e.g. &&) and ternary (e.g. eval $#a > $#b ? $#a : $#b).

The Macro Library

The DATASETCMD has a new subcommand AUTOSAVE with which you can turn the DataSet autosave feature on and off.

The GRAPHSETUP macro.

The new CGRAPHSETUP command GRAPHLEGEND displays an amplitude legend in a spectrogram plot.

The new CGRAPHSETUP command GETCOLORPALETTE retrieves the print or screen palette in an extended table.

The new CGRAPHSETUP command GETPROFILELIST returns a simple table with a list of color profiles defined in the settings file (S_TOOLS-STx INI).

===== Classes =====

BXMLDoc class

The SETELEMENT function can now take a table containing attribute/value pairs.

CMenu class

The new CMenu function AddToolBoxMenu adds the standard toolbox menu items to the menu.

XPlot class

When constructing an XPlot instance, an owner window may now be specified.

===== Shell Items =====

Dialog Item

The dialog edit control has a new option '<span class="stxmacrocommandoption-character">/F</span>' which forwards KEY messages to the shell.

There are now four 'types' of edit control and a host of new parameters, which means it can display syntax highlighting, be used as a command line interface, etc.

A listview's cells can now be editable. The option <span class="stxmacrocommandoption-character">/E</span> which must be set for a ListView to be editable. The message CELLEDITED is sent if it is editable and its contents has been changed. If the user cancels editing, the message CELLCANCELLED is sent to the shell. If editing is ended because the user presses <span class="stxhotkey">TAB</span> or <span class="stxhotkey">Shift TAB</span>, the CELLEDITEDTAB or CELLEDITEDBACKTAB messages are sent. You can set the focus to a specific cell and enter editing mode using the new command SET dialogItem listviewIndex STARTEDIT.

The listview now supports the <span class="stxmacrocommandoption-character">/F</span> flag which forwards specific key types to the shell.

The listview supports a new option /R=n, which determines the maximum number of lines of text which can be displayed in the listview.

The new attribute !FOREGROUND returns 1 if the dialog window is in the foreground, 0 if it is not and -1 if the command fails in some way.

The new dialog attribute !EDITING can be used to ascertain if a listview is currently being edited or not.

File Item

The NEW FILE command can now take the option <span class="stxmacrocommandoption-character">/S</span>, to suppress error messages on creation failure.

The new file item command COPY <span class="stxmacrocommandoption-character">/Z</span> can be used to encrypt/decrypt a file, including optional password protection.

The new command TRYLOCK will try to get a lock on the file but will not block the script.

The !CHANGED attribute can now be explicitly set or reset. This functionality is new, in as much as versions previous to 3.9.0 could only reset the attribute. The meaning of assigning '1' to the attribute has changed, since assigning '1' now *sets* the attribute, whilst assigning '0' resets the attribute.

A new file item type - the GDX file item - has been developed, which can be used to create files containing graphic data which are passed directly to a graph item. GDX stands for "graphical data exchange". Currently, the spectrogram is the only plot which supports the GDX file type.

Graph Item

The command ADDMARKER can now be used to add a 'Box and Whiskers' metasegment.

The metasegment font can be specified on an individual basis using the ADDMARKER command.

A metasegment may be told not to change color on selection. This is only available using the "SET graph ADDMARKER table" command with the parameter "invertSelected" set to "true" if the metasegment color should be inverted whilst selected or "false" if not. The default is "true".

The key used to make a metasegment moveable can now be set using a 'modifyKeys' entry in the ADDMARKER table parameter.

A simple marker can now be displayed as a single vertical line (option <span class="stxmacrocommandoption-character">/M</span>).

The command OVERVIEW, which toggles between the 'view' and 'overview' modes, has been documented.

The graph supports a new attribute !CURSORMODE which returns the currently visible cursors, as set using the last CURSORMODE command.

The width of a graph's border can now be set using new AXIS command parameters. The default border width is 1 pixel.

The spectrogram palette can be changed at any time using the "SET graph Y * * SPECTROGRAM" function.

The DATASETLOADED message is now sent when a graph finishes loading data for a particular input.

Instance Item

The new command TRYLOCK will try to get a lock on the instance but will not block the script.

Table Item

A table item connected to a ListView must be configured to be editable using the CONFIG command or the !EDITABLE attribute. The CONFIG command has also been extended to allow for a restrictive set of values to be specified for a table field. If specified, the ListView will display a combobox in this column for each entry. All parameters set using the CONFIG command can now be queried via table field attributes.

The new command TRYLOCK will try to get a lock on the table but will not block the script.

The command NEW TABLE supports a silent error flag.

A table field can now display multirow entries, if the !MULTIROW attribute is set to 1, or the CONFIG command multirow parameter is set to ON.

The last user input for a particular column can now be used as the default for that column using the CONFIG command's setuserdefault parameter.

The DEFINE command can now be used to rename an existing field.

Wave Item

The wave item now supports the new attribute !PLAYSRATE which can be used to return the sampling rate currently used to for playback or set a new sampling rate for playback.

=== Changes ===

Changes in S_TOOLS-STx <CURRENT_VERSION>:

Graphical User Interface

F0 Test, F0Lookup, Amplitude Spectrum Statistics

The F0 Test, F0 Lookup and Amplitude Spectrum Statistics functions in the Spectrogram & Parameters Viewer sectioner have been moved to the toolbox file SpectrumTB.sts.

Macro Language

UNLOAD command

The command UNLOAD MACROCODE, UNLOAD SPUCODE and UNLOAD SOURCECODE take one parameter - the name of a sourcecode file (relative or absolute). The MACROCODE variant used to take a blank separated list of macro names and the SPUCODE version used to take a blank separated list of SPU names.

Display and Dialog DROPFILE message

The DROPFILE message sent to displays and dialogs when files are dropped onto them has been changed. The <span class="stxmacrocommandparameter-character">filePath</span> parameter is not longer a string, but rather the id of a simple table with one absolute path per entry.

Syntax

The string "123 456" is no longer a valid number.

=== Bug Fixes ===

Bug fixes

The waterfall graph now prints correctly.

The BDataSet member function AddASet now selects the new audio set if adding the set succeeds (r5534).

Shell commands using the return value RC now assign the value even if return code equals 0 (indicating success) (r5609).

Spectrogram & Parameters Viewer Sectioner copy to clipboard working again (r5625).

The 'view' graph mode now displays correctly when first drawn (r5643).

The asterisk character * is now officially an invalid hotkey, rather than being one which doesn't work correctly (r5500).

Loading an XML file which an unsupported character encoding now fails rather than asserting (r5614).

The Spectrum viewer can now saving CEPST parameters (r6470).

The color 'GRAY' is now defined as the RGB value 96:96:96, which fixes the bug where cursors were invisible on a 'GRAY' background (r6148).

The "SET graph XSCALE" flag "/I" is now working (r6187).

Using the correct normal/dual/tight phase vocoder pv filters (r5874).

All valid number formats (including mmmE /-eee) can now be used in time-expressions (r5746).

=== Corrections ===

S_TOOLS-STx Version: 3.9

A list of documentation corrections since the last release (3.7).

The macro COBJ has been superseded by the COBJ class and no longer exists.

The command SYSTEM MKDIR and SYSTEM RMDIR were undocumented.

The SPAtom ASEG1 parameters are now in the correct order (<span class="stxmacrocommandparameter-character">TABS</span> and <span class="stxmacrocommandparameter-character">TABM</span> were swapped).

The SPAtom VSPLIT was mistakenly documented as VSPLIT1.

The macro DEBUGTB no longer exists.

The descriptions of the different formulas used by the SPAtom MORLET have been corrected.

The section FILE item command LOAD parameters were not documented as mandatory.

Added description of shell variables SCRIPTFILEPATH, SCRIPTDIRECTORY AND SCRIPTMAINNAME.

The AWEIGHT SPAtom has now been documented.

The WAVEOUT SPAtom has now been documented.

A list of documentation corrections since the last release (3.6.2).

The BUTIL FILEDIALOG no longer has a <span class="stxmacrocommandparameter-character">path</span> parameter.

A list of documentation corrections since the last release (3.6.1).

The SET table FIND <span class="stxmacrocommandparameter-character">cexpr</span> format uses colons, not commas as delimiters.

The SET value OUTPUT commands can take <span class="stxmacrocommandoption-character">/Double</span> options.

The description of the parameters for the NEW TABLE command where field definitions are possible has been corrected.

The SET graph CURSORMODE command now describes the bound and locked parameters correctly.

The VAR arithmetic operators DIV, MUL and SUB are actually called DIVIDE, MULTIPLY and SUBTRACT

The SET graph ZSCALE command parameters were incorrect.

=== Known Bugs ===

S_TOOLS-STx Version: 3.9

These bugs were known to exist at the time of the release and are proving difficult, if not impossible to fix.

Interface

Sometimes 44KB soundfiles are created, which are invalid. This bug has not proved easy to replicate, so if you can replicate it, please contact us ( \n This e-mail address is being protected from spam bots, you need JavaScript enabled to view it ).

Can't delete an entry in the DataSet if it has no ID. It is highly unlikely that you will ever have a DataSet entry with no ID. If this is the case however, you must currently delete it by hand (Close S_TOOLS-STx, open the DataSet in a text editor and either give the offending entry an ID, or remove it). Should you be able to reproduce any action which creates an entry without an ID, please contact us ( \n This e-mail address is being protected from spam bots, you need JavaScript enabled to view it ).

Spectrogram & Parameters Viewer

Interpolation of very short signals is incorrect (Deutsch - 2004-11-10 - since 1.0).

Graphics

Copying a display graphic to the clipboard and pasting into a graphics program does not always achieve the desired results. This bug will not be fixed in the foreseeable future. Some graphics programs paste it properly (IrfanView, Microsoft Word), others don't (PaintShop Pro) - (Jonnie White - 2004-07-14).

Selected cursors is not visible if background is set to GRAY (White - 2004-07-12 - since 1.0).

Macro

The dialog control listbox does not handle displaying huge strings properly. This seems to be a problem with the underlying CListBox control (Becker/White - 2004-12 - since 1.0).

The DCOM command INVOKEMETHOD Evaluate always returns an error when communicating with the R DCOM server even if the command was actually successful (Deutsch/White - 2004 - since 3.6.0).

==3.8==

3.8.3

* BUGFIX: zoom in in viewer3 now working when zooming around active cursor
* BUGFIX: spectragram title display corrected (amin/amax)
* BUGFIX: CDLGMAP now deletes window only if it has created the window during construction

3.8.2

* BUGFIX: dataset path now displayed, even if it has spaces in it.
* BUGFIX: Parameter plot explicitly redrawn when new data is sent. This fixes the bug (reported by Julia Brandstaetter) where Set Zero and Undo were not working properly in Spectrogram and Parameter plot.

3.8.1

* BUGFIX: Warn user that more waveform samples are being sent than expected and refrain from crashing.
* BUGFIX: CDlgMap now always uses the next free dialog index for a new entry. This means that multiple maps can reference the same dialog and still work. The functions fci and nc were removed since they are never used. Display now using second event to synchronise creation and variable initialisation. This fixes the mysterious bug where the window class was only sometimes used.
* BUGFIX: If the polyline function is called with less than two points it no longer asserts, but rather ends gracefully.
* BUGFIX: send keys not processed by dialog on to graph hotkey handlers
* BUGFIX: spectrogram is now being initialised with the correct context menu when formants are displayed in it.
* BUGFIX: giving dialog focus if there are no graphs
* BUGFIX: buttons in dialogs in a graph no longer process normal mneumonics. This means that the graph can process them (for Moosmueller). Buttons can still be activated with return and the space bar and tabbed/arrowed to.
* BUGFIX: preventing race conditions in Attach/Detach. This removes one possible cause of autosave crashing. It does not guarantee, though, there to be no other reasons for autosave to crash.

=Downloads=
The {{STX}} downloads are available here: https://www.kfs.oeaw.ac.at/pub/stx

Programmer Guide/STx Guru

2019-10-01T08:43:49Z

Jw:

{{DISPLAYTITLE:Becoming an {{STx}} Guru}}
The following text is based on an {{STX}} workshop of 2005, which took place in the [http://www.kfs.oeaw.ac.at Acoustics Research Institute (ARI)], and which was described as "our weekly time-wasting meeting" in a colleague's blog. It explains the internal structure and the features of the {{STX}} 3.7 release, and has been carefully adapted to the current {{Stx}} version (4.0) in 2014.

__TOC__

==Whom this is for==

This manual is a general introduction to the programming language that is part of the {{Stx}} environment. Reading this manual will allow you to implement procedural functions and then to proceed to object-oriented classes for a wide range of tasks, with a natural focus on numerical applications, sound processing, and visualization. As a reader of this manual, you should be slightly familiar with programming in general, and it would be great if you were an avid user of {{STx}} (on the other hand, being faintly familiar with starting up {{STX}}, loading sound files, and maybe even starting the spectrogram function should suffice).

This manual is intended for reading from start to end (not necessarily without interruptions). It is not a reference manual (there is such a thing, too: the [[Programmer_Guide/Quick_Reference|{{STx}} Quick Reference]]), meaning that it will abstract from, you might even bluntly say: omit, many a detail in order not to depress the reader with a seemingly abundant amount of material. Instead, a careful selection has been taken on what is, and what is not, necessary for achieving common goals. Of course this selectivity (or, if you prefer, these omissions) try hard not to give any false impressions of what can, and what can't, be done with {{Stx}} (and how). We are well aware that writing such an introductory programmer's (or, as we hope, programmers') manual is a slippery slope, and we hope for the reader's (or, as we hope, the readers') pardon if the depth covering each topic is too shallow, or to deep, or both (we are not quite sure whether the latter is logically possible, but one never knows). We appreciate any comments or criticism, both on this manual and on {{STx}}.

If you want to dig deeper into any specific topic, or if you are looking for information on a specific issue, we recommend having a look either at the online help of {{STX}} (just start {{Stx}} and select the "Help" menu, or press the "F1" key), or, even better, at the [[Programmer_Guide|{{STx}} Programmer Guide]]. Both are a vast and ever-growing collection of deep, sometimes even exhausting wisdom. They are, in fact, the official reference manual.

When new to {{STX}} programming, we recommend first reading this manual (you might skip paragraphs you find particularly uninteresting), probably trying out all the examples by yourself, preferably even modifying and improving them. Afterwards, you will have a basis firm enough for using the [[Programmer_Guide|{{Stx}} Programmer Guide]], or even the [[Programmer_Guide/Quick_Reference|{{STx}} Quick Reference]], as a reference manual. And you will surely have a sound basis for solving all your future programming tasks with {{STx}}, disposing of the need for any other programming languages or environments.

== How to write an {{STX}} Script: The Easy Part ==

This chapter deals with quite a basic fact, answering the first question that may come to your mind: ''How'' can I create and edit a script, and ''what'' need I do to submit it to {{Stx}} for execution?

Well, the first part is easy: Just use a text editor of your choosing. Since Windows does not come equipped with the editor of your choosing, you should probably get it from [http://www.vim.org/download.php www.vim.org], unless, of course, you already did so.

There is a faint convention to use the filename extension ".STS" for {{STx}} scripts, but everything else will really work equally well. So: just start editing. In its simplest case, your script will contain only one macro. The start of the macro is indicated by macro header, and it should end with an <code>EXIT</code> statement:

[macro TowersOfHanoi]
[[Programmer_Guide/Macro_Library/StdLib#UM_and_EM|um]] 'Rapid prototyping of the towers of Hanoi problem. Program logic not yet present.'
exit

There is, of course, [[Programmer_Guide/Source_code|a more formal definition of what an {{Stx}} script is built up from]], but at this stage you should probably not bother with all these other thingies.

After crafting your {{STX}} script, you still have {{Stx}} to notice its presence, and to execute it. The simplest way for working on a script is pushing the large button labelled "Script file" (on the top of the main {{STx}} window, labelled (and called) "Workspace". After pressing this button, a file dialog titled "Select script file" will open, allowing you to, well, select your shiny new script file.

[[File:ws_sc.png]]

To the right of the "Script file" area, there is another area labelled "Macro". If your script file contains more than one macro function, this drop-down thingy will allow you to select which macro to execute.

There is a third field, labelled "Arguments", where you can supply arguments for your macro. And there are two awesome checkboxes labelled "Debug" and "Console", respectively. When checking "Debug", {{STX}} will start your amazing macro program in the [[User_Guide/Debugger|gorgeous {{Stx}} macro debugger]]. When checking "Console", your macro will run in the interactive {{STx}} console (an interactive version of the {{STX}} command interpreter). When checking both, either may happen, or both.

The awesome buttons, fields and checkboxes mentioned here build up what we call the gorgeous Script Controller. You will not find much more information in [[User_Guide/Workspace/Script_Controller|Script Controller]].

''Note'': If you do not see any of the fields mentioned here (bluntly put: if you do not see the Script Controller at all), it is likely that it is not there. In this case, try using the Workspace menu item "Scripts > Show Scripts" to unhide it.

==Constants==

Our {{Stx}} does not strictly discern between string constants and numerical constants. Normally each constant is considered a string, there only being exceptions dependent on the context where the constant occurs. If, for example, a constant occurs as part of a numerical expression, {{STx}} tries to get its numerical value.

Generally, you may, but you need not, put single quotes around constants. With a few exceptions depending on context, this will not change the way {{STX}} handles the constant. So each of the following strings is a valid {{Stx}} constant:

string1
'string1'
-12.34
'-12.34'

Regardless of the presence or absence of single quotes, both the first and the second argument will be considered string constants. Also regardless of the presence or absence of single quotes, both the third and the fourth constant will be considered numerical constants when occurring in a numerical context, or string constants when occurring in a string context.

If a string constant contains whitespace characters, it depends on the context whether {{STX}} considers it ''one'' string constant or ''more than one'' string constant. If you want to make sure that a string constant is considered one constant, you should always put single quotes around the whole affair:

'Hello World'
Hello World

While the first string is always considered one string constant, the second one may, depending on where it is occurring, be considered one string constant denoting the string "Hello World", or two string constants, denoting the strings "Hello" and "World", respectively.

These issues will be dealt with in more detail below. For the moment, the curious reader may have a look at the following assignment statements:

#a := [[Programmer_Guide/Command_Reference/NUM|num]] '5' * '3' // value of #a will be 15
#b := [[Programmer_Guide/Command_Reference/SET|set]] 5 * 3 // value of #a will be "5 * 3"

The first statement is a numerical assignment (denoted by the keyword "<code>[[Programmer_Guide/Command_Reference/NUM|num]]</code>"). Both constants, 5 and 3, will be considered numerical constants, even if surrounded by quote characters. On the other hand, the second statement is a string assignment (denoted by the keyword "<code>[[Programmer_Guide/Command_Reference/SET|set]]</code>"). So the argument will, logically, be interpreted as one string constant, "5 * 3", even though it contains whitespace and lacks any quote character. What happens physically is that all separate words will be concatenated to the one string constant expected, inserting exactly one blank between each pair of words. The following statements show the consequences of this procedure:

#b := [[Programmer_Guide/Command_Reference/SET|set]] 5 * 3 // value of #b will be "5 * 3"
#b := [[Programmer_Guide/Command_Reference/SET|set]] 5 * 3 // value of #b will be "5 * 3", too
#b := [[Programmer_Guide/Command_Reference/SET|set]] '5 * 3' // value of #b will also be "5 * 3"

In the second statement, though the words "5", "*", and "3" are separated by more than one whitespace character, the one string that will be built up from them is "5 * 3" – when concatenating them, they get separated by exactly one space character.

You may influence the way concatenation works by quoting some, or all, of the words to concatenate. Quoting a word will prevent {{STx}} from automatically inserting a blank before and after that word. So, compare the above statements with the statements below:

#b := [[Programmer_Guide/Command_Reference/SET|set]] 5 '*' 3 // #b is "5*3" (no space)
#b := [[Programmer_Guide/Command_Reference/SET|set]] '5' * 3 // #b is "5* 3" (one space)
#b := [[Programmer_Guide/Command_Reference/SET|set]] 5 ' * ' 3 // #b is "5 * 3" (three spaces)

With the first statement, the word in the middle, "*", is quoted. This indicates {{STX}} on concatenation not to insert a space character either before or after this word, resulting in <var>#b</var> being set to "5*3" (no intervening whitespace).

With the second statement, the first word is quoted and will, hence, be concatenated to its right successor (there is no left predecessor) without inserting space. The second and the third word are not quoted and will be concatenated with an additional space in between them. This results in <var>#b</var> being assigned "5* 3" (no whitespace between "5" and "*", one blank between "*" and "3").

With the third statement, concatenation will not add any additional blanks either before or after the word in the middle. The whitespace that is part of the word, i.e. part of the quotation (three blanks before and after the asterisk, each), will be unaltered, though. So what results it <var>#b</var> being assigned the string "5 * 3" (exactly three blanks both before and after the asterisk).

Within a constant, you may alter the meaning of special characters by using the {{Stx}} escape character "`", the backwards single quote, sometimes called back-tick. At the current stage, we can only use this feature for defining a string constant that contains single quote characters themselves:

#a := set 'Rome is a city but `'Rome`' is a four-letter word'
#a := set Rome is a city but `'Rome`' is a four-letter word

Both statements will assign the string "Rome is a city but 'Rome' is a four-letter word" to a variable called <var>#a</var> (although it may not always be easy later to retrieve the value of this variable). We have to leave these issues open for later discussion.

==Variables==

The names of {{STx}} variables start with an optional one-character prefix indicating the scope of this variable (the lack of such a prefix indicating shell-global scope, see below). Besides this prefix, they may consist of letters and digits, although their first actual character must be a letter. Names are not case-sensitive, meaning that e.g. „freq", „Freq", and „FREQ", are names of the same variable.

Our {{STX}} discerns four kinds of scope and, hence, four kinds of variables:

{|
|-
|Scope
|Prefix
|Description
|-
|Global
|<code>@</code>
|Global variables are known to, and may be changed by, every shell instance, both running or yet to start. Global variables are the only kind of variables guaranteed to be persistent over interactive macro calls during one {{Stx}} run.
|-
|Shell
|no prefix
|"Shell-global" variables are global to the running shell. This implies that they are known to, any may be changed by, any macro invoked by a normal macro call. The variable will not, though, be known to other running shells or to shells yet to start. So, in general, shell-global variables will not be persistent through interactive calls to a user-defined macro.N.B.: Do not mix up shell-global variables with item handles that will be dealt with in chapter [[Programmer Guide/STx Guru/Shell Items: An Overview|5]] (page 1). For the time being, suffice it to say that item handles look like shell-global variables, but that they reside in different namespaces and that they behave differently.
|-
|Local
|<code>#</code>
|Local variables are valid only during the runtime of one invocation of a shell macro. On each invocation of a shell macro, a separate namespace containing all its local variables is being created. This namespace is destroyed as soon as the macro finishes. Note that this implies that on invocating a macro recursively, it will find itself starting with a fresh, empty copy of all its local variables, while the calling instance will find its namespace, i.e. its local variables, untouched.
|-
|Member
|<code>&</code>
|When adhering to the object-oriented programming paradigm, you will define classes and instantiate them. Each instance of a class will have its own set of variables called member variables. The introductory chapters will stick to the clean ole' procedural way of programming.
|}

As a rule of thumb, most of the time you will be using local variables whose names start with "<code>#</code>", e.g. variables like <var>#i</var>, <var>#depth</var> or <var>#title</var>.

Variables need neither be declared nor to be explicitly initialized. If you want to introduce a variable, just start using it. Note that a variable is empty, i.e. contains the empty string, when being referred to without having been explicitly set to a value different from the void.

===Typing===

There is really not much about typing in {{STx}}. All variables store strings, like it is the case with most scripting languages. Of course these strings are at liberty only to consist of digits, a comma, and an optional sign character, making them look like numbers, smell like numbers, taste like numbers, and being treated like numbers by numerical {{STX}} functions like addition, multiplication, or even the controversial subtraction.

===Setting Variables===

Setting a variable, i.e. assigning a value to the variable, is done with the "<code>:=</code>" operator. Its general format is

variable := expression

You should ''never'' use this kind of assignment with {{Stx}}, though. Instead, ''always'' use one of the following assignments:

variable := [[Programmer_Guide/Command_Reference/SET|SET]] string_expression // typed string assignment
variable := [[Programmer_Guide/Command_Reference/INT|INT]] numerical_expression // typed integer assignment
variable := [[Programmer_Guide/Command_Reference/NUM|NUM]] numerical_expression // typed numerical assignment
variable := [[Programmer_Guide/Command_Reference/EVAL|EVAL]] amazing_expression // awesome assignment using [[Programmer_Guide/Command_Reference/EVAL|EVAL]]

See the following chapters for the reasons of this recommendation.

====Simple string assignment====

In its simplest form, this "expression" is a simple string constant, just like in the following example:

#adress := 'Reichsratsstrasse 17' // discouraged, see further below - always use [[Programmer_Guide/Command_Reference/SET|SET]]

Or even:

#adress := Reichsratsstrasse 17 // discouraged, see further below - always use [[Programmer_Guide/Command_Reference/SET|SET]]

Although generally valid, either usage is strongly discouraged, because it may lead to often surprising, seldom desired results if or when the string to be assigned starts with the name of a built-in function or a user-defined macro (note that words so far not reserved may become reserved words any time now, and that, when in a large software-building project, you never know how your colleagues call their helper macros today).

====Typed string assignment====

You may indicate your expressed desire for the expression to be a string constant by prefixing it with the type-selector statement "<code>[[Programmer_Guide/Command_Reference/SET|set]]</code>":

#address := [[Programmer_Guide/Command_Reference/SET|set]] Reichsratsstrasse 17 // this is better

or, even better:

#address := [[Programmer_Guide/Command_Reference/SET|set]] 'Reichsratsstrasse 17' // and this is the way to go

In this case, the assignment will even work if one day the {{Stx}} macro language should be added a built-in function "Reichsratsstrasse" (which is, we dare to admit, unlikely) – or if one of your colleagues' macros happens to be likely called.

====Typed numerical assignment====

Although the value assigned is invariably a string, this string may be the result of a numerical computation. You may indicate your desire for it to be so by using one out of the following type-selector statements: "<code>[[Programmer_Guide/Command_Reference/INT|int]]</code>", "<code>[[Programmer_Guide/Command_Reference/NUM|num]]</code>", and "<code>[[Programmer_Guide/Command_Reference/EVAL|eval]]</code>".

The "<code>[[Programmer_Guide/Command_Reference/INT|int]]</code>" type-selector will cause your expression being evaluated as an integer expression. More precisely (more precisely less wrongly), the expression will be evaluated numerically, and the result will be converted to an integer whose textual representation will be the string to be assigned to the destination variable. The calculation itself will be done with the point floating, though (see the below examples for what that means).

The "<code>[[Programmer_Guide/Command_Reference/NUM|num]]</code>" type-selector will cause your expression being evaluated as a numerical expression, provided it is such. The textual representation of the numerical result will be the string to assign to the destination variable.

The "<code>[[Programmer_Guide/Command_Reference/EVAL|eval]]</code>" type-selector is the most powerful of them all. Firstly, it does everything the "<code>[[Programmer_Guide/Command_Reference/NUM|num]]</code>" type-selector does. So, when evaluating a plain numerical expression, it is your free choice whether to use "<code>[[Programmer_Guide/Command_Reference/NUM|num]]</code>" or "<code>[[Programmer_Guide/Command_Reference/EVAL|eval]]</code>" (we might one day choose spontaneously to fade out the "<code>[[Programmer_Guide/Command_Reference/NUM|num]]</code>" type-selector, but do not allow this to bias your choice). But, secondly: The "<code>[[Programmer_Guide/Command_Reference/EVAL|eval]]</code>" type-selector is capable of much, much more: It does vector and matrix operations of the most sophisticated kind, calculates averages, converts units, dances the Fourier transform, and so on. The actual number of functions available to "<code>eval</code>" expressions is more than 70 and counting (see the interactive {{STX}} help topics "[[Programmer_Guide/Command_Reference/EVAL|eval]]").

For an example, compare the following statements:

#a := [[Programmer_Guide/Command_Reference/NUM|num]] 3*3.4 // result is 10.19999999999
#a := [[Programmer_Guide/Command_Reference/INT|int]] 3*3.4 // result is 10 (!)
#a := [[Programmer_Guide/Command_Reference/NUM|num]] 3*int(3.4) // result is 9
#a := [[Programmer_Guide/Command_Reference/INT|int]] 3*int(3.4) // result is 9
#a := [[Programmer_Guide/Command_Reference/NUM|num]] int(3*3.4) // result is 10 (!)
#a := [[Programmer_Guide/Command_Reference/NUM|num]] int(3*int(3.4)) // result is 9

Here the first statement will cause <code>#a</code> to be assigned the result of the floating point multiplication of 3 and 3.4, i.e. about 10.2. In the second statement, the same multiplication will be calculated, and only the result of this calculation, i.e. 10.2 (roughly...), will get truncated to an integer – this integer in turn being 10. Only the third and the fourth statement (both!) will cause the second factor, 3.4, to be broken down to an integer before multiplication. This usage, though, is strictly not a feature of the type selector-based assignment, but of the numerical function (we will come to these later) "int". (Note that since the product of two integers is an integer itself, in the third and fourth statement it does not make any difference whether we use the "num" or the "int" type selector.)

Do not mix up the type selector of the assignment with any built-in type-conversion functions: Whereas the type-selector always immediately follows the assignment operator, "<code>:=</code>", type-conversion functions never do. Furthermore, the arguments of type-conversion functions are always enclosed in brackets, whereas the type selector never uses brackets.

So in the third to sixth example, the type selectors are "<code>num</code>", "<code>int</code>", "<code>num</code>", and again "<code>num</code>", whereas the strings "<code>int(3.4)</code>", "<code>int(3*3.4)</code>", and "<code>int(3*int(3.4))</code>" are calls to the built-in type conversion function, "<code>int</code>". (If this sounds confusing for the moment, you should not worry: In practice, things are much easier, and it is not normally necessary to think these things over).

====Function calls====

Syntactically, every built-in {{STx}} function, every macro, and every method of a user-defined class may be the source of an assignment. If this happens to be the case, the respective function or macro is executed, and its result is assigned to the destination variable. See it for yourself:

#i := [[Programmer_Guide/Command_Reference/WORD|word]] 2 one two three four // #i will be "three"

The built-in "<code>[[Programmer_Guide/Command_Reference/WORD|word]]</code>" function takes an integer index and a list of strings as its arguments. From this list, it selects and returns the string with the respective index. Hence, the expression "<code>word 2 one two three four</code>" will select, and return, the third word, „three". When part of an assignment as in the above example, this very string "three" will be assigned to the respective destination variable, in this case: to the local variable <code>#i</code>.

The same holds true if the source of the assignment is the name of a class method. In this case, the respective method is being called, and its result (which may as well be the empty string) gets assigned to the destination variable.

The issue of function calls will be dealt with in full detail in chapter [[#Calls_to_Macros_and_Built-In_Functions|Calls to {{Stx}} Macros and Built-in Functions]].

===Accessing Variables===

If and when you want to access the value of a variable (bluntly put: to read out its content), you need to put a dollar sign in front of the variable name. What happens internally is that, before actually executing a line from the macro file, {{STX}} replaces all occurrences of variable names that are prefixed by a dollar sign by the content of the respective variables. See for yourself:

#i := [[Programmer_Guide/Command_Reference/INT|int]] 7
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] 'The current value of variable #i is $#i'
#i := [[Programmer_Guide/Command_Reference/INT|int]] $#i + 1 // #i will be set to 8
#heading := [[Programmer_Guide/Command_Reference/SET|set]] 'This is page $#curpage out of $#totpage'

The first line in this example will assign the value 7 to a local variable called <var>#i</var>. This is nothing new; note that we are using the type-selector "<code>[[Programmer_Guide/Command_Reference/INT|int]]</code>" to make sure the assigned value is interpreted as an integer, though in this case this is strictly redundant because 7 cannot help being an integer anyway.

The second line will print out the text "The current value of variable #i is 7". This should not be surprising, for the name of a variable is only replaced by its content if preceded by a dollar sign. Hence, the first occurrence of "#i" – although we know that there is a variable called <var>#i</var> – does not get replaced by that variable's value. The second, though, does, because it is preceded by the dollar sign. {{Stx}} is one reliable piece of software, strictly and indiscriminately following the instructions laid out by its master.

What the third line does is increase the value of the local variable <var>#i</var> by 1. What's more interesting is how it does so. First, {{STx}} replaces all dollar-prefixed variable names by the contents of the respective variables. Hence, {{STX}} will replace the string "$#i" by the current value of <var>#i</var> which, in our example, happens to be 7. This replacement will change the current statement from "#<code>i := [[Programmer_Guide/Command_Reference/INT|int]] $#i + 1</code>" to "<code>#i := [[Programmer_Guide/Command_Reference/INT|int]] 7 + 1</code>". Now this is one fine integer expression that in turn gets evaluated to 8, thereby causing 8 to be the string that is finally assigned to the destination variable.

The fourth and last line demonstrates that substitution also works within string constants, and that it does so even if they are put under quotation marks (in our case, apostrophes). Some macro languages, e.g. the well-known UNIX shells, let certain kinds of quotation marks prevent substitution. Users familiar with such shells should bear in mind that {{Stx}} is a kind of its own. (Note that if you really want to suppress the special meaning of a character like the dollar sign, you may precede it with the {{STx}} escape character "<code>`</code>", the so-called back-tick.)

The aspiring {{STX}} guru may find it instructive to consider the following example (anyone else will find no harm in completely skipping it):

#var := [[Programmer_Guide/Command_Reference/SET|set]] 'one'
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] '#var now containing "$#var"'

#var := [[Programmer_Guide/Command_Reference/SET|set]] 'two'
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] '#var now containing "$#var"'

$#var := [[Programmer_Guide/Command_Reference/SET|set]] 'three' // N.B.: substitution will make this
// "two := set 'three'"
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] '#var still containing "$#var"'

[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] '...but there suddenly is a variable called two'
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] '...and its value is "$two"'

The first line is well familiar. It assigns the string "one" to a local variable called "<code>#var</code>". Consequently, the second line will print exactly the following string:

#var now containing "one"

The third line changes the value of <code>#var</code> to "two", hence the third line will print out the following string:

#var now containing "two"

No surprises yet. But what will the fourth line do? Well, not to be surprised about the answer to this semi-rhetorical question, we must analyze the statement carefully. It reads "<code>$#var := set 'three'</code>" – did you notice that the assignment target is preceded by a dollar sign? Alas, this instructs {{Stx}} to replace the variable name by its content; but the content of variable "<code>#var</code>" is "two." Hence the statement gets, by substitution, altered to "<code>two := set 'three'</code>". This is a perfectly valid assignment statement, only that the target of the assignment is a shell-global variable called "<code>two</code>". So we assign the string "three" to a variable called "<code>two</code>". The next statements only illustrate this fact by printing out the respective values.

===Read Functions===

The {{STx}} [[Programmer_Guide/Command_Reference/READ|<code>read</code> family of functions]] supply a means for parsing the contents of a string or a variable, that is for splitting them into several pieces, and for storing some or all of these pieces into one or more other variables (or even in the same variable). That being said, it should be noticed that everything is much easier than this description implicates. See for yourself:

[[Programmer_Guide/Command_Reference/READ|readstr]] 'one two three four five' #a #b #c /Delete
// #a is now "one", #b is now "two", #c is "three four five"
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] 'now a="$#a", b="$#b", and c="$#c".'

The <code>[[Programmer_Guide/Command_Reference/READ|readstr]]</code> command parses its first argument into (at most) as many blank-separated strings as there are variables. If the number of variables is higher than the number of available words, the remaining variables will either be cleared (if supplying the <code>/Delete</code> option), or they will be left untouched (if omitting the <code>/Delete</code> option). If, on the other hand, the number of variables is lower than the number of available words, the last variable gets all the remaining words. Note that if there is more than one whitespace character between two words, this will not do any harm.

So what the above example does is parse the string "<code>one two three four five</code>" into three substrings (there are three variables supplied, <var>#a</var>, <var>#b</var>, and <var>#c</var>). The first substring will be the first word, "one". The second substring will be the second word, "two". Since there are more words than variables, the third substring will catch all the rest, that is, the string "three four five". It's really simple, isn't it?

There is one additional feature you may, or may not, find convenient. You may as well parse strings that are separated by exactly one character of your choice. If, for some reason, you prefer semicolons over blanks, you might have done the above example as follows:

[[Programmer_Guide/Command_Reference/READ|readstr]] 'one;two;three;four;five' #a ';' #b ';' #c /Delete
// #a is now "one", #b is now "two", #c is "three;four;five"
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] 'now a="$#a", b="$#b", and c="$#c".'

The syntactical difference between those two examples is that the latter explicitly names the separator character between each pair of variables. The difference in semantics is that now there must be exactly one separator character between two words. So this variant of the <code>[[Programmer_Guide/Command_Reference/READ|readstr]]</code> command empowers you to read empty words, two. Consider the following statement (we may abbreviate the <code>/Delete</code> option to <code>/D</code>, if we do not care for the reduced legibility):

[[Programmer_Guide/Command_Reference/READ|readstr]] 'one;;two;three;four;five' #a ';' #b ';' #c /D
// #a is "one", #b is empty, #c is " two;three;four;five"
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] 'now a="$#a", b="$#b", and c="$#c".'

Looking awfully identical, doesn't it? Well, instead of one semicolon, there are now two semicolons between the first two words, "one" and "two". Believe it or not, this is making all the difference in the world: {{STx}} will consider these successive semicolons three separate words, the first being "one", the second one being empty, and the third one being, in general, "two" (in our case where there are only three variables supplied, the third word will get the rest of the string). So, with this example, variable <var>#a</var> will get the string "one", variable <var>#b</var> will be cleared, and variable <var>#c</var> will get the rest, that is the string, "two;three;four;five". Cool, isn't it?

Note that if you omit the <code>/Delete</code> option, target variables corresponding to empty words will not be cleared, that is, they will keep whatever value that had before calling <code>[[Programmer_Guide/Command_Reference/READ|readstr]]</code>. That being said, you can easily foretell the results of the following statements:

b := set 'old value before calling readstr'
[[Programmer_Guide/Command_Reference/READ|readstr]] 'one;;two;three;four;five' #a ';' #b ';' #c
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] 'now a="$#a", b="$#b", and c="$#c".'

As you rightly foretold, the <code>[[Programmer_Guide/Command_Reference/READ|readstr]]</code> command in this example will not change the value of the second variable, <var>#b</var>, since the second word in this string is empty.

Although technically a consequence of the above, it may not immediately be clear that the space character, too, may explicitly named as separating arguments – and that this does cause a difference to the default <code>[[Programmer_Guide/Command_Reference/READ|readstr]]</code> behaviour. Look for yourself (and notice that there are two space characters between the "a" and the "b" in the first string constant):

[[Programmer_Guide/Command_Reference/READ|readstr]] 'a b c' #a #b #c /Delete</code>
// #a is now "a", #b is "b", #c is "c"
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] 'a="$#a", b="$#b", c="$#c"'
[[Programmer_Guide/Command_Reference/READ|readstr]] 'a b c' #a ' ' #b ' ' #c /Delete
// #a is now "a", #b is empty, #c is "b c"
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] 'a="$#a", b="$#b", c="$#c"'

As you already know, there is one important difference between both <code>[[Programmer_Guide/Command_Reference/READ|readstr]]</code> variants: When explicitly naming the separation character, {{STX}} considers consecutive occurrences of the separation character to separate empty strings. When not naming a separation, consecutive occurrences of whitespace are considered one single separator character, thereby causing no empty word to be read. So, in the above example, the first <code>[[Programmer_Guide/Command_Reference/READ|readstr]]</code> command will read "a" into <var>#a</var>, "b" into <var>#b</var>, and "c" into <var>#c</var>, whereas the second <code>[[Programmer_Guide/Command_Reference/READ|readstr]]</code> command will read "a" into <var>#a</var>, the empty word into <var>#b</var>, and the remaining string, "b c", into the last variable, <var>#c</var>.

Of course the string argument supplied to <code>[[Programmer_Guide/Command_Reference/READ|readstr]]</code> may even be the result of variable substitution. Less prosaically put, you might as well supply code like the following:

#three := set 'THREE'
[[Programmer_Guide/Command_Reference/READ|readstr]] 'one two $#three four' #a #b #c #d
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] 'now a="$#a", b="$#b", c="$#c", d="$#d"'

Before executing the command, {{Stx}} will, as usual, look for any variable name prefixed with a dollar sign. If there happens to be any, they will be replaced by the contents of the respective variables. So in the above example, the text "<code>$#three</code>" will get replaced by the contents of variable <var>#three</var>, thereby causing the [[Programmer_Guide/Command_Reference/READ|{{Stx}} <code>readstr</code> command]] to actually be processed to be the following:

[[Programmer_Guide/Command_Reference/READ|readstr]] 'one two THREE four' #a #b #c #d

Only the strong survive the following example (anyone else will find no harm in skipping it).

[[Programmer_Guide/Command_Reference/READ|readstr]] 'x y z' #a #b #c
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] 'now a="$#a", b="$#b", c="$#c"'
[[Programmer_Guide/Command_Reference/READ|readstr]] 'one two three' $#a $#b $#c
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] 'gee, now a="$#a", b="$#b", c="$#c"'
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] 'but mysteriously, x="$x", y="$y", z="$z"'

When listening very carefully, you might hear the above example speak for itself. If not, you will find the key in the third line that contains the second <code>[[Programmer_Guide/Command_Reference/READ|readstr]]</code> command. Did you notice the variables being prefixed by a dollar sign each? Now the dollar sign indicates {{STx}} that variable substitution is desired (and required) before the command is to be processed. So all {{STX}} does is replace the two strings "<code>$#a</code>", "<code>$#b</code>", and "<code>$#c</code>" by the contents of the respective variables. Since, at this stage, their contents are "x", "y", and "z", the command actually to get executed will look as follows:

[[Programmer_Guide/Command_Reference/READ|readstr]] 'one two three' x y z

Now this clearly is a request to parse the string "one two three" into the three shell-global variables "<var>x</var>", "<var>y</var>", and "<var>z</var>".

When reading directly from one variable, you might prefer a variant of <code>[[Programmer_Guide/Command_Reference/READ|readstr]]</code>, the <code>[[Programmer_Guide/Command_Reference/READ|readvar]]</code> command. <code>[[Programmer_Guide/Command_Reference/READ|readvar]]</code> works similar to <code>readstr</code>, as the following example shows:

#var := set 'one two three'
[[Programmer_Guide/Command_Reference/READ|readvar]] #var #a #b #c /Delete

The first argument to <code>[[Programmer_Guide/Command_Reference/READ|readvar]]</code> is one variable to read from. The remaining arguments are the variables where to store the words read. Otherwise that <code>[[Programmer_Guide/Command_Reference/READ|readvar]]</code> reads from a variable as opposed to reading from a literal string, there is no difference between <code>[[Programmer_Guide/Command_Reference/READ|readvar]]</code> and <code>readstr</code>.

You will undoubtedly ask why there is such a thing as a <code>[[Programmer_Guide/Command_Reference/READ|readvar]]</code> command. After all, all that

[[Programmer_Guide/Command_Reference/READ|readvar]] #var #a #b #c

does may as well be done using the following command:

[[Programmer_Guide/Command_Reference/READ|readstr]] '$#var' #a #b #c

You are, of course, right in principle. The difference between the two commands is that the latter depends upon variable substitution which introduces a second step when evaluating and executing the command. Hence, the former is simply faster.

Note that there is a <code>[[Programmer_Guide/Command_Reference/READ|readtable]]</code> function, too. We will come to that much later when dealing with the versatile (both are) {{Stx}} table feature.

===Special Variables===

There are a number of reserved variables that serve special purposes. At this stage, it suffices to give a short overview of the most important special variables.

{|
|-
|Variable
|Description
|-
|<var>rc</var>
|After executing an {{STx}} statement or built-in function (not a user-defined macro!), this variable contains its numerical return code, 0 indicating success, and values different from 0 indicating different kinds of failure. "<var>rc</var>" gets set after each invocation of an {{STX}} statement or built-in function, meaning that an error code will get reset when executing the next statement. If you later need to map a numerical error code to a textual error message (e.g. for presenting it to the user), you may always use the [[Programmer_Guide/Command_Reference/EMSG|EMSG]] command.
|-
|<var>emsg</var>
|This variable contains a textual description of the value of the "<var>rc</var>" variable. It, too, gets reset with each new {{Stx}} statement. If you have saved the value of <var>rc</var> e.g. in a local variable and you later need to map it to a textual error message (e.g. for presenting it to the user), you may always use the [[Programmer_Guide/Command_Reference/EMSG|EMSG]] command. (And don't confuse the <var>emsg</var> variable and the [[Programmer_Guide/Command_Reference/EMSG|EMSG]] command - they are not the same).
|-
|<var>#argc</var>, <var>#argv</var>
|On macro invocation, "<var>argc</var>" contains the number of arguments supplied to the respective macro, while "<var>argv</var>" contains the actual arguments (all of them). See below.
|-
|<var>result</var>
|After returning from a user-defined macro call, the variable "<var>result</var>" contains the value returned by the respective macro, i.e. the value the macro supplied as an argument to the "<code>[[Programmer_Guide/Command_Reference/EXIT|exit]]</code>" call. If the macro was left without returning an argument, "<var>result</var>" is empty (this is not considered an error – honestly, there is not much that is ever considered an error as far as {{STx}} is concerned).
|-
|<var>#read</var>
|After using one of the {{STX}} [[Programmer_Guide/Command_Reference/READ|READ]] commands (<code>read</code>, <code>readstr</code>, <code>readvar</code>, <code>readtab</code>), this variable contains the number of arguments actually read.
|-
|<var>#new</var>
|When allocating an {{Stx}} shell item, its item name will be stored in a variable called "<var>#new</var>". On the issue of shell items, please be patient until chapter [[Programmer_Guide/STx_Guru#Shell_Items:_An_Overview|Shell Items: An Overview]], or divert to the [[Programmer_Guide/Shell_Items|Shell Items]] chapter in the Reference Manual.
|}

In general, even the reserved variable may be target of an assignment (this is sometimes used with the "<var>#argv</var>" variable for implementing default macro arguments). You should not be surprised, though, that assigning a value to either "<var>rc</var>" or "<var>emsg</var>" will not have the desired outcome: Since the assignment statement is built-in {{STx}} statement itself, executing it will reset "<var>rc</var>" to 0 and "<var>emsg</var>" to the empty string, thereby indicating that the assignment statement itself was successful (which it was).

==Control Structures==

===Calls to Macros and Built-In Functions===

You might argue that we have been through that already, but, unfortunately, this is only part true: There is much more to passing an argument to a function than we have explored when calling the built-in "<code>[[Programmer_Guide/Command_Reference/WORD|word]]</code>" function, or the built-in "<code>[[Programmer_Guide/Command_Reference/WRITELOG|writelog]]</code>" command. This chapter tells why and what.

===Macros===

Semantically, an {{STX}} macro is like a procedure or function of any procedural programming language of your choice. Syntactically, a macro starts with a macro definition surrounded by square brackets, e.g. the following line:

[Macro mymacro]

There is no clear end to a macro. Execution continues until the control flow reaches an "<code>exit</code>" statement, until a new macro starts, or until the file comes to an end (whichever happens first).

==== Calling a macro ====

For calling a macro, you simply type the macro name. In the above case, if {{Stx}} encounters a line starting whose first word is the string "<code>mymacro</code>", it will execute the like-named macro. {{STx}} supports recursive macro calls.

There are a few commands providing different, not always cleaner ways of calling a macro, namely the [[Programmer_Guide/Command_Reference/MACRO|MACRO]], the [[Programmer_Guide/Command_Reference/MACROX|MACROX]] and the [[Programmer_Guide/Command_Reference/SHELL|SHELL]] command. Please do not use these commands unless there is very good reason to (there normally isn't).

====Returning From a Macro====

Macro execution will stop when {{STX}} encounters the "<code>[[Programmer_Guide/Command_Reference/EXIT|exit]]</code>" statement. Normally, control flow resumes at the line immediately following the statement that caused the macro to execute. You may supply the following optional arguments to an exit statement:

[[Programmer_Guide/Command_Reference/EXIT|exit]] <var>level</var> <var>result</var>

When calling "<code>[[Programmer_Guide/Command_Reference/EXIT|exit]]</code>" without any arguments or when calling "<code>[[Programmer_Guide/Command_Reference/EXIT|exit]] 1</code>", control flow will, as said above, resume with the next statement after the macro call.

In general, the first argument to "<code>[[Programmer_Guide/Command_Reference/EXIT|exit]]</code>" indicates how many call levels to skip. When calling "<code>[[Programmer_Guide/Command_Reference/EXIT|exit]] 2</code>", control flow will not resume at the line after the statement calling the macro, but at the line after that statement calling whichever macro was in turn calling our macro. When calling "<code>[[Programmer_Guide/Command_Reference/EXIT|exit]] 3</code>", control flow will resume at the line after the statement calling the macro calling the macro calling our macro. When calling "<code>[[Programmer_Guide/Command_Reference/EXIT|exit]] 4</code>", control flow will resume at the line after the statement calling the macro calling the macro calling the macro calling our macro, while on "<code>[[Programmer_Guide/Command_Reference/EXIT|exit]] 5</code>" execution will resume with the line after the statement calling the macro calling the macro calling the macro calling the macro calling our macro, and so on. There is limited use to this feature, and you are at the safe side when, at least in the beginning, always using "<code>[[Programmer_Guide/Command_Reference/EXIT|exit]] 1</code>".

There are two special cases, one when supplying 0 for the exit level, the other when supplying a negative number.

When supplying 0 for the exit level, i.e. when executing <code>[[Programmer_Guide/Command_Reference/EXIT|exit]] 0</code>, the executing shell will be terminated, effectively ending execution of the whole user script (both the running macro and all calling macros).

When supplying a ''negative'' level argument (e.g. <code>[[Programmer_Guide/Command_Reference/EXIT|exit]] -2</code>), {{Stx}} will return from as many macro levels as needed to find a macro level where there is a non-empty local variable <var>#onexitall</var> defined. Since this is a bit complicated and not very clean, you probably should try not to use this feature.

Of more interest than the first is the second argument to "<code>[[Programmer_Guide/Command_Reference/EXIT|exit]]</code>". It is the result of the macro, that is the number or string the macro is to return. Like with assignment operations, this result may, and should, start with a type selector, one out of "<code>[[Programmer_Guide/Command_Reference/SET|set]]</code>", "<code>[[Programmer_Guide/Command_Reference/INT|int]]</code>", "<code>[[Programmer_Guide/Command_Reference/NUM|num]]</code>", and "<code>[[Programmer_Guide/Command_Reference/EVAL|eval]]</code>". Consider the following "<code>exit</code>" statements:

[[Programmer_Guide/Command_Reference/EXIT|exit]] 1 set 'Hallo Welt'
[[Programmer_Guide/Command_Reference/EXIT|exit]] 1 int 5/3
[[Programmer_Guide/Command_Reference/EXIT|exit]] 1 num 3/5

The first statement will exit the running macro and return the friendly string "Hello World". The second statement will exit the running macro and return whichever integer results on dividing 5 by 3. Finally, the third statement will exit the running macro and return the quotient of 3 and 5.

There are several interchangeable ways for the caller to retrieve whatever value the macro has returned. First of all, the result is stored in the reserved shell variable "<code>result</code>", rendering the following code snipped a working example:

greetings // call the "greetings" macro
writelog '$result' // ...and print its results
exit // ...and rest after a long day's work

[Macro greetings]
[[Programmer_Guide/Command_Reference/EXIT|exit]] 1 set 'Hello World'

An even more elegant feature is using command substitution, a concept both known and feared from the UNIX shells:

#var := set '$(greetings)'
writelog '$(greetings)'

The first statement executes the macro "greetings" and assigns its result to a variable called "<code>var</code>". The second statement, too, calls the "greetings" macro, but directly pastes its result into a "<code>writelog</code>" statement.

Though command substitution is the most general way, a macro may be directly called, too – just like any built-in {{STx}} function:

#var := greetings

The latter format greatly improves legibility and is therefore he recommended way of calling a user-defined macro.

====Supplying and Retrieving Arguments====

There are, they say, many ways leading to Rome, and this surely holds true for retrieving and parsing the arguments a user-defined macro has been supplied with. The easiest way is disposing of the problem in the macro definition, i.e. by writing something like this:

[Macro multiply #mand #mor]
#prod := [[Programmer_Guide/Command_Reference/EVAL|eval]] $#mand * $#mor
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] 'multiplying $#mand by $#mor results in $#prod'
[[Programmer_Guide/Command_Reference/EXIT|exit]]

As you may have noticed, the macro name may be followed by one or more variable names. In this case the arguments supplied to the macro are being automatically parsed and stored to the like-named variables. We call this the implicit argument parsing feature. Hence, when calling "<code>multiply 7 9</code>", the starting macro will find its local variable <code>#mand</code> set to 7 and its local variable <code>#mor</code> set to 9. This will cause the above macro to print the message "multiplying 7 by 9 results in 63". If there are fewer arguments than variables, the remaining variables will be empty. If there are more arguments than variables, the whole remaining part of the arguments will be stored to the last variable. When you think it over, this is completely analogous to the <code>readstr</code> and <code>readvar</code> functions already known.

What's also analogous to <code>readstr</code> and <code>readvar</code> is the possibility explicitly to name a separator character of one's choice. See for yourself:

[Macro multiply #mand';'#mor]
#prod := [[Programmer_Guide/Command_Reference/EVAL|eval]] $#mand * $#mor
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] 'multiplying $#mand by $#mor results in $#prod'
[[Programmer_Guide/Command_Reference/EXIT|exit]]

While the first variant of the user-defined macro "multiply" will expect its arguments to be separated by an arbitrary number of whitespace characters, the second version will expect them to be separated by exactly one semicolon. This comes in handy when passing arguments that may contain, or contain, or must contain, or should contain, or would contain were it not for the fact that this is impossible with the default way of argument parsing, whitespace characters.

A further and generally slightly more flexible, though a little more laborious way of parsing one's arguments is using the special variables "<code>#argc</code>" and "<code>#argv</code>". On start-up of a macro, these variables get set to the number of arguments and to the actual argument list, respectively. So the above example may be re-written for explicit argument parsing as follows:

[Macro multiply]
readvar #argv #mand #mor
#prod := [[Programmer_Guide/Command_Reference/EVAL|eval]] $#mand * $#mor
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] 'multiplying $#mand by $#mor results in $#prod'
[[Programmer_Guide/Command_Reference/EXIT|exit]]

Why is this more flexible in general? – Because of the greater versatility of the <code>readvar</code> and <code>readstr</code> commands that even allow parsing argument lists built up from a variable number of arguments. We will come to that with the macro <code>countSTXProgrammers</code> of chapter 4.1.1.3 on page 1.

That being said, we may well continue with a real-world example. Consider e.g. the following macro:

[Macro declare #person #attribute]
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] 'I hereby declare $#person an $#attribute'
[[Programmer_Guide/Command_Reference/EXIT|exit]]

Now, if you would like to declare, say, Toni an {{STX}} hero, you might call the macro as follows:

declare Toni {{Stx}} hero

This will work fine because the first word, "Toni", gets stored to the first variable, <code>#person</code>, and the rest of the arguments, "STX hero", gets stored to the second, and last, variable, <code>#attribute</code>. But what if you want to declare Christian Gottschall an {{STx}} beginner? See for yourself:

declare Christian Gottschall {{STX}} beginner

This will invariably lead to the first word, "Christian", being stored to <code>#person</code>, and the whole rest, "Gottschall {{STx}} beginner", being stored to <code>#attribute</code>, hence causing Christian being declared a (sic!) "Gottschall {{STx}} beginner", which he surely isn't.

You might be tempted to attacking this problem by using quotes, but in fact this is utterly impossible. You will find any conceivable combination (and even most unconceivable combinations) of quotes and escape characters to have a meaning very different from that intended. So the only general solution to this problem is using a different separator character:

[Macro declare #person';'#attribute]
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] 'I hereby declare $#person an $#attribute'
[[Programmer_Guide/Command_Reference/EXIT|exit]]

Or:

[Macro declare]
readvar #argv #person ';' #attribute
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] 'I hereby declare $#person an $#attribute'
[[Programmer_Guide/Command_Reference/EXIT|exit]]

Now you may declare whomever you want whatever you please:

declare Toni ; {{STX}} hero

declare Christian Gottschall ; {{Stx}} beginner

Though looking unusual from the standpoint of several other programming languages, it is good {{STx}} practice to quote the macro arguments, either as a whole, or argument-wise, or even (don't read this loudly!) on a per-word basis:

declare 'Jonnie White ; {{STX}} guru'
declare 'Jonnie White' ; 'STX guru'
declare 'Jonnie' ' White' ; 'STX ' 'guru'

In general, neither form of quotation will do any harm. Remember, though, that, with {{Stx}}, writing several quoted strings will cause them to be implicitly concatenated with any intervening whitespace removed. Hence, although the above examples work as desired (note the quotations of the fourth statement containing space characters), the following won't:

declare 'Jonnie' 'White' ; 'STX' 'guru'

The latter statement will print out the text "I hereby declare JonnieWhite an STXguru": Although there is a whitespace character between each pair of quoted words, the quotations themselves do not contain any blank character, thereby causing the respective words to be concatenated without any intervening space. Compare this with the third statement in the previous example where there is a space character at the beginning of the second, and at the end of the third quoted word. (We've already had a few words on concatenation in chapter on page 1.)

Note that when using the implicit argument parsing feature (or when using <code>readvar</code> with the default separation characters (whitespace), you need to be careful not to let the concatenation feature come in your way. Consider the following macro call:

usermacro 'one' 'two' 'three'

Here, by string concatenation, the two strings "one", "two," and "three" will get concatenated to one single string, "onetwothree". Consequently, the macro will, whatever way of parsing it uses, get only one argument – the string "onetwothree." If you want the macro actually to be called with three arguments, you will need to use one of the following statements:

usermacro one two three
usermacro 'one two three'
usermacro 'one ' 'two ' ' three'

It will work either way, additional whitespace characters never doing any harm.

As a rule of thumb, the easiest thing would be always to quote the whole arguments to a macro call, like is done in the second statement of the above example.

====Combined example====

The following example builds up several things we are at this stage familiar with (and several others we are not). You need not fully understand the macro at this stage, but you might notice several familiar issues.

[Macro countSTXProgrammers]
// read 0 both into #count and #totcount
[[Programmer_Guide/Command_Reference/READ|readstr]] '0 0' #count #totcount // [[#ckremark1|(1)]]

// the "forever" loop will never terminate by itself.
// it will only stop at a "break" statement
[[Programmer_Guide/Command_Reference/FOREVER|forever]] // [[#ckremark2|(2)]]

// read the first person into #person, and the
// remaining persons into #argv
[[Programmer_Guide/Command_Reference/READ|readvar]] #argv #person ';' #argv /Delete // [[#ckremark3|(3)]]

// return both the total number of persons counted and
// the number of {{STx}} persons
[[Programmer_Guide/Command_Reference/IF|if]] '$#read' == 0 then // [[#ckremark4|(4)]]
[[{Programmer_Guide/Command_Reference/EXIT|exit]] 1 set '$#totcount;$#count' // [[#ckremark5|(5)]]
end

#totcount := int $#totcount+1
#index := keyword '$#person' Toni Jonnie Christian // [[#ckremark6|(6)]]

[[Programmer_Guide/Command_Reference/IF|if]] '$#index' >= 0 then
#count := int $#count+1
end

end

The <code>countSTXProgrammers</code> macro gets an arbitrary number of arguments separated by semicolons. Each argument is considered the name of a person. What the macro does, slightly arbitrarily, is count both the total number of persons supplied, and the number of {{STX}} programmers amongst them ({{Stx}} programmers being considered Toni, Jonnie, and Christian only). The most important statements are the following (see the respective numbers commented in the macro source):

;{{anchor|ckremark1|(1)}}: This shows an idiomatic use of the <code>readstr</code> command for initializing multiple variables. Here the string "0 0" is parsed into two variables, <code>#count</code> and <code>#totcount</code>, effectively setting them both to zero. Of course you might as well use the two separate assignment statements "<code>#count := int 0</code>", and "<code>#totcount := int 0</code>".
;{{anchor|ckremark2|(2)}}: The <code>forever</code> keyword starts kind of an eternal loop running until a <code>break</code> statement will be met. Both issues are dealt with in separate chapters ([[#Forever_and_Ever|Forever and Ever]] and [[#Ending_a_Loop_Prematurely:_Break_and_Continue|Ending a Loop Prematurely: Break and Continue]]).
;{{anchor|ckremark3|(3)}}: The <code>readvar</code> statement will be utterly familiar to you. Note, though, that one of the destination variables is the same as the source variable. This is not a problem at all. Parsing will proceed normally, and the assignment will take place only after parsing has finished. So this <code>readvar</code> statement will result in the first word of <var>#argv</var> being parsed into <var>#person</var>. The remaining contents of <var>#argv</var> will, in turn, be parsed to%… <var>#argv</var> itself(!), effectively removing the first word from <var>#argv</var>. So with each pass of the loop, the next "first" name from the list will both be stored in <var>#person</var> and be removed from <var>#argv</var>. Isn't ''that'' cool?
;{{anchor|ckremark4|(4)}}: This line introduces the <code>if</code> command. You need not worry about this command; it will be dealt with properly in chapterc 4.1.3.
;{{anchor|ckremark5|(5)}}: The <code>exit</code> statement will return from the macro, and it will do so – due to the <code>if</code> statement – on the condition that <var>#read</var> is zero which is the case as soon as there are no more names to read. The first argument to the <code>exit</code> statement is 1, indicating that only the current macro is to end (and that execution shall continue with the calling macro). The second argument to the <code>exit</code> statement is the result of the macro, in this case: the string to return (indicated by the string assignment type selector, <code>set</code>). This string is built up from <var>#totcount</var>, a semicolon, and <var>#count</var>, and will hence contain the total number of persons and the number of {{STx}} programmers, separated by a semicolon.
;{{anchor|ckremark6|(6)}}: This statement uses the built-in <code>keyword</code> function to investigate whether the current person is on the list of {{STX}} programmers.

===Statements and Built-in Functions===

Arguments to {{Stx}} statements and to built-in functions differ in several respects from macro calls:

# One quoted string is always considered one argument, even if it contains whitespace characters.
# Hence there is no automatic string concatenation either.
# If (and only if) the statement or the function expects a numerical argument, you may supply a numerical expression instead of a number. This expression will be evaluated before executing the statement, or calling the built-in function, respectively.

The first two issues are easily demonstrated by the following example:

#a := [[Programmer_Guide/Command_Reference/WORD|word]] 2 'a b c' d 'e' f
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] '#a="$#a"' // value of #a is "e"

Both quoted strings will be considered one argument each, and no concatenation will take place. Hence, the built-in <code>[[Programmer_Guide/Command_Reference/WORD|word]]</code> function will return the string "e", "e" being the third argument (index 2).

More surprising is the third issue, but it, too, can be demonstrated by a simple example:

#a := [[Programmer_Guide/Command_Reference/WORD|word]] 1+1 'a b c' d 'e' f
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] '#a="$#a"' // value of #a is "e", too

Since the "[[Programmer_Guide/Command_Reference/WORD|word]]" built-in expects its first argument to be a number, any numerical expression occurring at the respective position will be evaluated before calling "word". Hence, this example will return "e", too, because 1+1 equals 2. Compare this with the following statements:

#a := [[Programmer_Guide/Command_Reference/WORD|word]] 1+1 'a b c' d '2+2' f
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] '#a="$#a"' // value of #a is "2+2"

Here what the third argument of the "[[Programmer_Guide/Command_Reference/WORD|word]]" built-in will return is the string "2+2". This string does not get evaluated, because "[[Programmer_Guide/Command_Reference/WORD|word]]" expects a string argument (and not a numerical argument) at this position.

Note that if the numerical expression is to contain whitespace (or if it cannot be precluded that it does, e.g. when it is built up using variable substitution), you need to quote the whole expression. This quite naturally leads to the following rule of thumb: Always quote numerical expressions that are arguments to a statement or to a built-in function. See the following example:

#i := [[Programmer_Guide/Command_Reference/INT|int]] 3-2
#a := [[Programmer_Guide/Command_Reference/WORD|word]] '$#i+2' a b c d e
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] '#a="$#a"' // value of #a is "d"

First of all, <var>#i</var> gets assigned the difference between 3 and 2, that is 1. String substitution will change the string "<code>$#i+2</code>" to "<code>1+2</code>", "<code>1</code>" being the value of <var>#i</var>. Finally, due to the fact that the "<code>[[Programmer_Guide/Command_Reference/WORD|word]]</code>" function expects its first argument to be numerical, "<code>1+2</code>" will be evaluated as a numerical expression, resulting in 3. So the fourth string argument, "d", will be returned.

===If Conditions are to be Tested===

If conditions are to be tested, the "<code>[[Programmer_Guide/Command_Reference/IF|if]]</code>" statement comes in handy. It actually does so in two flavours:

[[Programmer_Guide/Command_Reference/IF|if]] [[Programmer_Guide/Concepts/Conditional_Expressions|condition]] statement

And:

[[Programmer_Guide/Command_Reference/IF|if]] [[Programmer_Guide/Concepts/Conditional_Expressions|condition]] then

many statements

else

many more statements

end

Before going into more details about what conditions look like, a few simple examples should make things more clear:

[[Programmer_Guide/Command_Reference/IF|if]] '$#a' == <nowiki>''</nowiki> [[[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] 'Variable #a is empty.'

[[Programmer_Guide/Command_Reference/IF|if]] '1+2' != 3 then
// note the use of the {{STx}} escape character, the back-tick,
// for building up a string that contains a quote character
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] Wohllebenstraße, we`'re having a problem.
else
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] All systems nominal.
end

[[Programmer_Guide/Command_Reference/IF|if]] a > c then // character-wise comparison
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] 'Detecting an unusual character set'
else
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] 'Detecting a usual character set'
end

[[Programmer_Guide/Command_Reference/IF|if]] '2+3' != '3+2' writelog 'STX addition is not commutative'

Note that with the first, simple form of the "<code>[[Programmer_Guide/Command_Reference/IF|if]]</code>" command, the statement to be executed in case of the condition being true must not be another "<code>if</code>" command. (In simpler wording: ''Simple [[Programmer_Guide/Command_Reference/IF|if]] statements must not be nested.'') Hence, it is not allowed to construct a statement like the following:

// BAD! NOT ALLOWED! ERRONEOUS! DON'T DO IT!
// COMBINING TWO SIMPLE "IF" STATEMENTS IS FORBIDDEN!

if '$a' == '$b' if '$c' != '$d' writelog a and b are equal, but c and d are not

If two or more "<code>[[Programmer_Guide/Command_Reference/IF|if]]</code>" statements are to be combined, use their complex form instead:

if '$a' == '$b' then
if '$c' != '$d' then
[[Programmer_Guide/Command_Reference/WRITELOG|writelog]] 'a and b are equal, but c and d are not'
end
end

===Conditions, Formally Revisited===

====Simple Comparison====

Conditions basically compare two entities for being equal, or for one of them being less than, or higher than, or not higher than, or not less than, or quite unlike the other. All this is done with the comparison operators "<code>=</code>", "<code><</code>", "<code>></code>", "<code><=</code>", "<code>>=</code>", and "<code>!=</code>". The arguments to these operators may either be strings, in which case a Unicode-based string comparison will take place, or numerical expressions, in which case a numerical comparison will take place. If the argument to a comparison operator looks like a numerical expression, it will be treated as such, even if the programmer did not mean that to happen.

Note that unless the argument to a comparison operator is quoted, it must be separated from the operator by at least one whitespace character. This means that while "<code>'$#a'=='1'</code>" (no whitespace, but quotes) and "<code>$#a == 1</code>" (blanks between the operator and its arguments) are well-formed expressions, "<code>$#a==1</code>" is not. (Yet another reason for always quoting everything, one might feel inclined to say.)

See a number of simple examples:

if '$#a' > '$#b*2' writelog '#a is more than twice as much as #b'

if 'int($#a)' == '$#a' writelog '#a is an integer'

if '$#a' == '0+$#a' then
writelog '#a is a number.'
else
writelog '#a is not a number.'
end

All these examples show that numerical expressions occurring in comparisons will be evaluated. Hence, the first example will compare the value of <code>#a</code> with twice the value of <code>#b</code>. The second example will compare <code>#a</code> with its integer part. If they are the same, we know that <code>#a</code> must store an integer.

The most interesting of these examples is the third one. What it does is check if the variable <code>#a</code> is numeric, i.e. if it contains a number. For understanding how it does so you need to remember that {{STX}} evaluates numerical expressions only. Now, should <code>#a</code> contain a number, say, 42, variable substitution will alter the expression "<code>if '$#a' == '0+$#a'</code>" to "<code>if '42' == '0+42'</code>". Now since "<code>0+42</code>" is a numerical expression (remember that single quotes do not matter), it will, in turn, be evaluated to 42 (0+42 equalling 42). This leads to the final statement "<code>if 42 == 42</code>". Since the number 42 is equal to 42, the condition will come out true, causing the "<code>then</code>" branch to be executed.

If, on the other hand, <code>#a</code> contains a value that is not a number, say, the string "Hello", variable substitution will alter the "<code>if</code>" statement to "<code>if 'Hello' == '0+Hello</code>". Due to "<code>0+Hello</code>" not being a numerical expression, there will be no evaluation, resulting in the string "<code>Hello</code>" to be compared against the string "<code>0+Hello</code>". Since they are not identical, the "<code>else</code>" branch will be executed.

Note that there is one potential pitfall (and note the alliteration, too). Should #a consist of digits separated by whitespace, it will be considered a number (one number) anyway. So e.g. the string "<code>123 440 . 12</code>" will be considered the number "123440.12". This is a feature allowing for separating numbers into groups of digits (e.g. a group of ones, tenths, and hundreds, and a group of thousands, ten-thousands, and hundred-thousands).

====Pattern Matching====

Besides these comparison operators, there are matching operators, too. Matching may be considered a more powerful way of comparing strings that is able not only to find out if two strings are strictly identical, but also to find out whether they are similar in a way yet to be defined. With a matching operation, its first, left-hand side argument must be the string to match. Its second, right-hand side argument must be the ''pattern'' against which to match the string.

===== Wildcard Pattern Matching=====

''Wildcard patterns'' are similar to strings with the exception that they may contain wildcards (hence the name). With {{Stx}}, these wildcards are the asterisk, "*", for matching a string of arbitrary length, and the question mark, "?", for matching exactly one character.

There are the following wildcard matching operators:

; Wildcard string matching:
{| style="margin-left: 1.5em;"
|-
|<code>=SI</code>
|The string argument does match the pattern. Case will be ignored.
|-
|<code>!SI</code>
|The string does not match the pattern, not even regardless of case.
|-
|<code>=SR</code>
|The string argument matches the pattern case-sensitively.
|-
|<code>!SR</code>
|The string argument does not match the pattern when respecting case.
|}

; Wildcard name matching: Name matching is similar to string matching, the difference being that the string to match is expected to be a well-formed {{STX}} name. If this is not the case, the match will fail, even if the pattern would string-match the string. More precisely, matching a non-name string with <code>=N</code> will always return false, whereas matching a non-name string with <code>!N</code> will always succeed, regardless of the pattern used.
{| style="margin-left: 1.5em;"
|-
|<code>=NI</code>
|The name argument matches the pattern ignoring case.
|-
|<code>!NI</code>
|The name argument does not match the pattern, not even regardless of case.
|-
|<code>=NR</code>
|The name argument matches the pattern including case.
|-
|<code>!NR</code>
|The name argument does not match the pattern when respecting case.
|}

Have a glance at the following examples:

if 'hallo' =SI ha* writelog 'OK' // 1
if 'hallo' =SI *ha* writelog 'OK' // 2
if 'hallo' =SI h*o writelog 'OK' // 3
if 'hallx' !NI ha*o writelog 'OK' // 4
if 'test' !SI ha* writelog 'OK' // 5
if 'test' !SI *ha* writelog 'OK' // 6
if 'test' !SI h*o writelog 'OK' // 7
if 'h-o' !NI h*o writelog 'OK' // 8
if 'test' =SI t*t* writelog 'OK' // 9

Each of these comparisons should come out true, hence causing each statement to print the string "OK". Let's have a look at a few of these examples in detail:

The pattern, "<code>ha*</code>", will match any string starting with "<code>ha</code>" – "<code>hallo</code>" does. So "<code>=SI</code>" will guarantee a positive outcome.

The pattern "<code>h*o</code>" will match any string whose first character is an "h" and whose last character is an "o". Now, "<code>hallx</code>" is no such string, but since we are using a negative comparison operator, "<code>!NI</code>", the whole thing comes out true since the pattern does not match. (Using "<code>!NI</code>" instead of "<code>!SI</code>" presupposes the string to be a well-formed {{STx}} name which, by chance, "<code>hallx</code>" is. But compare statement 8.)

The pattern "<code>h*o</code>" normally matches any string starting with "h" and ending with "o". That it does not match in this expression is because the "<code>NI</code>" operator presupposes its argument to be a well-formed {{Stx}} name. Now, "<code>h-o</code>" is no such name because it contains a minus sign, "<code>-</code>". So, the match fails by necessity, hence causing the negative expression "<code>!NI</code>" to become true.

If you are shaken by statement 8 of the previous example, you might want to try out for yourself the following macro:

if 'h-o' !NI h*o writelog 'OK1' // 1
if 'h-o' !SI h*o writelog 'OK2' // 2
if 'h-o' =NI h*o writelog 'OK3' // 3
if 'h-o' =SI h*o writelog 'OK4' // 4

What this will do is print out "OK1" and "OK4", but neither "OK2" nor "OK3". Do you see why?

Well, first of all, the string "<code>h-o</code>" is no valid {{STX}} name due to its containing the minus sign, "<code>-</code>". So every name-based comparison will fail before even considering the pattern argument. So the third comparison, "<code>=NI</code>", will fail though "<code>h-o</code>" is a string starting with "h" and ending with "o". Consequently, the expression inverting that condition (using "<code>!NI</code>" instead of "<code>=NI</code>") will come out true, causing the first comparison to come out true.

With the string-based comparison operators, things are different. Stringly put, the pattern "<code>h*o</code>" does match the string "h-o", that string actually starting with an "h" and ending with an "o". So the positive operator, "<code>=SI</code>", will come out true, while, consequently, its negative form will come out false.

===== Regular-Expression Pattern Matching=====

Aside from the simple wildcard-patterns, {{Stx}} also supports full POSIX regular-expression pattern matching, using the open-source [https://github.com/laurikari/tre/ TRE] library. Here is not the place for introducing POSIX regular-expressions, but if you are familiar with that concept, you will find the following {{STx}} matching operations useful:

; Regular-expression string matching:
{| style="margin-left: 1.5em;"
|-
|<code>=RSI</code>
|The string argument does match the regular expression. Case will be ignored.
|-
|<code>!RSI</code>
|The string does not match the regular expression, not even regardless of case.
|-
|<code>=RSR</code>
|The string argument matches the regular expression case-sensitively.
|-
|<code>!RSR</code>
|The string argument does not match the regular expression when respecting case.
|}

; Regular-expression name matching: This, too, is similar to regular-expression string matching, the difference being that the string to match is expected to be a well-formed {{STX}} name. If this is not the case, the match will fail, even if the regular expression would string-match the string.
{| style="margin-left: 1.5em;"
|-
|<code>=RNI</code>
|The name argument matches the regular expression ''ignoring case''.
|-
|<code>!RNI</code>
|The name argument does not match the regular expression, not even regardless of case.
|-
|<code>=RNR</code>
|The name argument matches the regular expression including case.
|-
|<code>!RNR</code>
|The name argument does not match the regular expression when respecting case.
|}

====Building up Complex Expressions====

You may combine more than one comparison either conjunctively, using the "<code>&&</code>" operator, or disjunctively, using the "<code>||</code>" operator. There is, though, neither precedence nor grouping, meaning that (a) complex expressions will be evaluated strictly from left to right and that (b) you cannot use brackets for grouping sub-expressions. While the former is not strictly an offence once one gets used to it (other programming languages like APL behave very similarly), the latter may sometimes cause some programmer inconvenience. We will try addressing this issue a wee bit later.

Evaluation stops as soon as the outcome is clear, but with {{Stx}}, this is only a performance issue (there is no such thing as built-in functions with side-effects, whereas command substitution, on the other hand, will always be done regardless of where the "<code>$(...)</code>" expression actually occurs).

See the following examples:

if 1 > 2 || 3 > 1 writelog 'condition 1 is true'

if 1 > 2 || 3 > 1 && 0 == 1 writelog 'condition 2 is true'

if '$#a+1' < '$#b*3' || '$#c-7' == '$#d' writelog 'condition 3 is true'

Whereas the first statement should be fairly clear, fully to understand the second statement requires being aware of {{STx}} strictly evaluating from left to right: For {{STX}}, the condition "<code>1 > 2 || 3 > 1 && 0 == 1</code>" will mean the same as, for a human reader, "(1 > 2 or 3 > 1) and 0 == 1" would. The "and" ("<code>&&</code>") does not – as it normally does in logic and mathematics – take precedence over the "or" ("<code>||</code>").

{|
|-
|What you type
|What {{Stx}} does
|-
|<code>$a > $b && $b < $c || $c < $b && $b < $a</code>
|<code>(($a > $b && $b < $c) || $c < $b) && $b < $a</code>
|-
|<code>$a < $b && $a > 0 || $b == -1</code>
|<code>($a < $b && $a > 0) || $b == -1</code>
|-
|<code>$a < $b || $b > $a && $invert == 1</code>
|<code>($a < $b || $b > $a) && $invert == 1</code>
|-
|<code>$a < $b || ( $b > $a && $invert == 1 )</code>
|Syntax error (brackets are not allowed!)
|}

From the theoretical standpoint, the lack of grouping (i.e. brackets) allows for a much faster evaluation. It does, though, sometimes force the programmer either to combine several "<code>if</code>"-statements, or to alter his or her expression – that is why support for bracketing in logical expressions is under active consideration for {{STx}} versions to come. For the time being, here are a few examples on how to rewrite complex expressions:

{|
|-
|What you mean to do
|What you need to do to do what you mean to do
|-
|<code>if ($a > $b && $b < $c) || ($c < $b && $b < $a) then</code><br><code>   statements…</code><br><code>end</code>
|<code>#flag := int 0</code><br><code>if $a > $b && $b < $c #flag := int 1</code><br><code>if $c < $b && $b < $a || $#flag == 1 then</code><br><code> statements…</code><br><code>end</code>
|-
|<code>if $a > 0 || ( $a < 0 && $b == int($b) ) then</code><br><code>   statements…</code><br><code>end</code>
|<code>if $a < 0 && $b == int($b) || $a > 0 then</code><br><code>   statements…</code><br><code>end</code>
|-
|<code>if ($a > $b) && $b < $c) ||</code><br><code>($c < $b && $b < $a) ||</code><br><code>   ($b < $c && $c < $a) ||</code><br><code>   ($b < $a && $a < $c) then</code><br><code>   Statements…</code><br><code>end</code>
|<code>#flag := int 0</code><br><code>if $a > $b && $b < $c #flag := int 1</code><br><code>if $c < $b && $b < $a #flag := int 1</code><br><code>if $b < $c && $c < $a #flag := int 1</code><br><code>if $b < $a && $a < $c || $#flag == 1 then</code><br><code>   statements…</code><br><code>end</code>
|}

====Reference====
* [[Programmer_Guide/Concepts/Conditional_Expressions|Conditional Expressions]] Reference in the {{STX}} Programmers' Guide

===While Loops Loop===

While loops model our everyday concept of repeating a task until it finally has the desired outcome. With {{Stx}}, this is done as follows:

[[Programmer_Guide/Command_Reference/WHILE|while]] [[Programmer_Guide/Concepts/Conditional_Expressions|expression]]

many statements…

end

With this code, {{STx}} will first evaluate the [[Programmer_Guide/Concepts/Conditional_Expressions|expression]] supplied to the "<code>[[Programmer_Guide/Command_Reference/WHILE|while]]</code>" statement. If this expression happens to be true, all statements between the "<code>[[Programmer_Guide/Command_Reference/WHILE|while]]</code>" and the corresponding "<code>[[Programmer_Guide/Command_Reference/END|end]]</code>" statement are being executed once. Afterwards, {{STX}} again evaluates the very same [[Programmer_Guide/Concepts/Conditional_Expressions|expression]]. If it is still true, all the statements between the "<code>[[Programmer_Guide/Command_Reference/WHILE|while]]</code>" and the "<code>[[Programmer_Guide/Command_Reference/END|end]]</code>" statement are being executed once more. Then, again, the [[Programmer_Guide/Concepts/Conditional_Expressions|expression]] is evaluated… and so on, the effect being that all statements between the "<code>[[Programmer_Guide/Command_Reference/WHILE|while]]</code>" and the "<code>[[Programmer_Guide/Command_Reference/END|end]]</code>" statement are being executed "while" (i.e. as long as) the condition happens to be true.

===For Loops to Be Organized===

The "<code>[[Programmer_Guide/Command_Reference/FOR|for]]</code>" statement is a more organized loop statement. Its syntax is the following:

[[Programmer_Guide/Command_Reference/FOR|for]] startcmd to [[Programmer_Guide/Concepts/Conditional_Expressions|whilecondition]] step changecmd
many statements…
end

First of all, "<code>startcmd</code>" – some arbitrary command – gets executed. Next, the expression "<code>[[Programmer_Guide/Concepts/Conditional_Expressions|whilecondition]]</code>" gets evaluated. If it is false, the control flow will continue with the line immediately following the "end" statement. If, on the other hand, it is true, all the statements between "[[Programmer_Guide/Command_Reference/FOR|for]]" and "end" will be executed. Next, the "<code>changecmd</code>" – again, any command of your choice – will be executed. After that, things will start all over, with "condition" being evaluated again.

This is functionally equivalent to the following code snippet:

startcmd
while whilecondition
many statements…
changecmd
end

So the <code>[[Programmer_Guide/Command_Reference/FOR|for]]</code> statement does not introduce any new functionality. What it does, though, is saving space and making this certain kind of loop more readable.

Note that the <code>[[Programmer_Guide/Command_Reference/FOR|for]]</code> statement is modelled after the like-named statement of fashionable programming languages like C, C++, Java, or the author's all-time favourite AWK. From a semantical point of view, the keyword "<code>to</code>" may seem slightly misleading. Suffice it to say that there is a lesser-known (and these days virtually extinct) Klingon dialect where the word "t'o" means the same as the English imperative phrase "do this while" (at least we trust this statement to be hard to disprove).

As an example, counting from 1 to 10, may serve the following "[[Programmer_Guide/Command_Reference/FOR|for]]" loop:

[[Programmer_Guide/Command_Reference/FOR|for]] #a := int 1 to $#a <= 10 step #a := int $#a + 1
writelog 'at this stage, #a=$#a'
end
exit

===Forever and Ever===

People often feel uneasy with the rapid change and the lack of durability in today's fast-paced environment. {{Stx}} addresses these issues with the "<code>[[Programmer_Guide/Command_Reference/FOREVER|forever]]</code>" statement that allows for enduring, long-term code execution. In fact, "<code>[[Programmer_Guide/Command_Reference/FOREVER|forever]]</code>" will start a flow of execution that never ends:

[[Programmer_Guide/Command_Reference/FOREVER|forever]]
eternal statements…
end

This kind of loop will cause the statements between "<code>[[Programmer_Guide/Command_Reference/FOREVER|forever]]</code>" and "<code>end</code>" to be processed for eternity (or until your computer breaks down, whichever happens first).

===Ending a Loop Prematurely: Break and Continue===

If {{STx}} encounters the "<code>[[Programmer_Guide/Command_Reference/BREAK|break]]</code>" statement within the body of a loop, this very loop gets at once terminated. Control flow will resume at the statement immediately following the "<code>end</code>" statement at the end of the loop.

The "<code>[[Programmer_Guide/Command_Reference/CONTINUE|continue]]</code>" statement will have a different effect: Whenever {{STX}} encounters this kind of statement, it will directly pass to the next run of this loop, ignoring any statements between the "<code>[[Programmer_Guide/Command_Reference/BREAK|break]]</code>" statement and the "<code>end</code>" statement at the end of this loop.

Consider the following example:

// print odd numbers less than 20 that are not a multiple of 3

#i := 0
forever
#i := int $#i + 1
if '$#i' >= 20 break

// note that "int" here is an in-place function truncating the
// fractional part off a number
if '$#i/3' == 'int($#i/3)' || '$#i/2' == 'int($#i/2)' continue

writelog '$#i is neither a multiple of 3 nor even'
end
writelog 'Done.'
exit

Though not at all an example in style, the above loop surely demonstrates the use of both the "<code>[[Programmer_Guide/Command_Reference/BREAK|break]]</code>" and the "<code>[[Programmer_Guide/Command_Reference/CONTINUE|continue]]</code>" statement. The basic idea of this loop is to run forever, with each pass increasing <code>#i</code> by one. Immediately after increasing <code>#i</code> is where the "<code>break</code>" statement finds its use: <code>#i</code> is being compared against twenty, and after having reached this upper limit, the whole loop will be terminated. Execution will continue with the first statement after the "end" statement of the respective loop. In our example, this first statement is the call to the built-in "<code>writelog</code>" statement printing out the string "Done."

The next issue demonstrated here is the "<code>continue</code>" statement. After having ensured that <code>#i</code> has not reached its desired upper limit, <code>#i</code> is being checked for being either a multiple of 3, being a multiple of 2, or both. If so happens, {{Stx}} will "continue" the loop, i.e. omit its remaining part (in our case, the "<code>writelog</code>" statement), and continue with its first statement.

Should the loop to be "continued" be a "<code>[[Programmer_Guide/Command_Reference/FOR|for]]</code>" or "<code>[[Programmer_Guide/Command_Reference/WHILE|while]]</code>" loop, the next run of the loop will begin normally, that is with testing the expression supplied to the "<code>[[Programmer_Guide/Command_Reference/FOR|for]]</code>" or "<code>[[Programmer_Guide/Command_Reference/WHILE|while]]</code>" statement. Should it prove false, the loop will terminate. In the case of a "<code>[[Programmer_Guide/Command_Reference/FOR|for]]</code>" loop, its "<code>changecmd</code>" (see above), too, will be executed normally, i.e., before checking the condition.

===Statements Considered Useful: goto, gosub, and gosubx===

Each statement in an {{STx}} script may be labelled. The name of a label may consist of letters, digits, and underscores (though it must not start with a digit). The label must be immediately followed by a colon (that's necessary because otherwise there would be no way to discern between labels and macro calls). Note that labels are local to the macro they are part of. It is hence not possible to jump to a label that is part of a macro different from the executing macro (and it is possible to use labels of the same name in more than one macro).

When using a label, you may at any time divert the flow of control to that label. This is done with the "<code>[[Programmer_Guide/Command_Reference/GOTO|goto]]</code>" command. Though it has come out of fashion recently, the "<code>[[Programmer_Guide/Command_Reference/GOTO|goto]]</code>" command allows for very efficient diversions in the control flow that may be really hard to follow.

Contrary to most other programming languages, {{STX}} allows "<code>[[Programmer_Guide/Command_Reference/GOTO|goto]]</code>" to be supplied not only one, but even two labels. If this is the case, {{Stx}} first tries to go to the first label. Only if there happens to be no such label, {{STx}} falls back to the second label and tries to go there. If the second label is not present either, the "<code>[[Programmer_Guide/Command_Reference/GOTO|goto]]</code>" command will do nothing (it will leave an error code in the variable <code>rc</code>, though, but most programmers do not check for errors anyway).

The following loop will count from 1 to 10 (compare this with the "<code>[[Programmer_Guide/Command_Reference/FOR|for]]</code>" loop of the last example in the previous chapter):

#a := int 0
looping:
if '$#a' >= 10 [[Programmer_Guide/Command_Reference/GOTO|goto]] endloop
#a := int $#a + 1
writelog 'at this stage, a=$#a'
[[Programmer_Guide/Command_Reference/GOTO|goto]] looping
endloop:
writelog 'let it be'
exit

A different issue is the "<code>[[Programmer_Guide/Command_Reference/GOSUB|gosub]]</code>" command. It is very similar to calling a macro: A new execution environment will be created, and control will resume at the label referred to by the "<code>[[Programmer_Guide/Command_Reference/GOSUB|gosub]]</code>" command. When (and if) the control flow reaches an "<code>[[Programmer_Guide/Command_Reference/EXIT|exit]]</code>" command, this execution environment will be destroyed, and control will resume with the line immediately following the "<code>[[Programmer_Guide/Command_Reference/GOSUB|gosub]]</code>" command that caused all that to happen. Summarizing things up, the code called by the "<code>[[Programmer_Guide/Command_Reference/GOSUB|gosub]]</code>" statement will see all variables empty. Furthermore, any changes made during the statements invoked using "<code>[[Programmer_Guide/Command_Reference/GOSUB|gosub]]</code>" will get lost on returning. This is a very powerful feature.

The "<code>[[Programmer_Guide/Command_Reference/GOSUBX|gosubx]]</code>" statement differs from the "<code>[[Programmer_Guide/Command_Reference/GOSUB|gosub]]</code>" command in that no separate execution environment is being created. Hence, the code will see all variables having their current value, and, conversely, any changes in variables done by the called code will remain in effect after returning. This, too, is always a powerful, sometimes a desired feature, and seldom easy to follow.

Compare the effect of the "<code>[[Programmer_Guide/Command_Reference/GOSUB|gosub]]</code>" and the "<code>[[Programmer_Guide/Command_Reference/GOSUBX|gosubx]]</code>" commands in the following example:

#a := 5
[[Programmer_Guide/Command_Reference/GOSUB|gosub]] subroutine
writelog 'a after gosubbing subroutine: $#a (no change!)'
[[Programmer_Guide/Command_Reference/GOSUBX|gosubx]] subroutine
writelog 'a after gosubxing subroutine: $#a (changed!)'
exit

subroutine:
// should #a be unset, numerical evaluation will fail
#a := int $#a + 5
writelog 'value of a in subroutine: $#a'
exit

Note that we do not actually dare to recommend using any of these statements, and that we strongly encourage structured programming (using "<code>[[Programmer_Guide/Command_Reference/FOR|for]]</code>" and "<code>[[Programmer_Guide/Command_Reference/WHILE|while]]</code>" loops and breaking program code into macros). There may, however, be cases where the real programmer finds that he or she can do many interesting things with the help of the statements considered harmful since Dijkstra's famous letter.

==Shell Items: An Overview==

[[Programmer_Guide/Shell_Items|Shell items]] are a kind of their own. Each shell item has a handle – actually kind of an internal name – that is not normally directly known to the programmer. Shell items may be created using the "<code>[[Programmer_Guide/Command_Reference/NEW|new]]</code>" command, and they may – and should – be disposed of properly after use which is done with the "<code>[[Programmer_Guide/Command_Reference/DELETE|delete]]</code>" command. The handle to a shell item is normally stored in an {{STX}} variable.

There are different sorts of shell items, the most important being [[Programmer_Guide/Shell_Items/File|file items]] (representing disk files), [[Programmer_Guide/Shell_Items/Graph|graph items]] (representing graphs visible to the user), [[Programmer_Guide/Shell_Items/Dialog|dialog items]] (representing GUI dialogs, menus, windows, and the like), [[Programmer_Guide/Shell_Items/Table|table items]] (representing in-memory databases, numerical vectors, and matrices), [[Programmer_Guide/Shell_Items/Value|value items]] (providing things as diverse as timers, and fast matrix operations), [[Programmer_Guide/Shell_Items/Wave|wave items]] (for handling soundfiles), and instances of user-defined classes. We will come to each of them later (or at least to most of them).

Beginners occasionally find it difficult to grasp the difference between a variable and a shell item. It is often helpful to remember the following properties:

# Shell items are very complex objects like files or tables that normally consist of many parts (e.g. the rows and columns of a table, or the records of a file) most of which are themselves complex objects.
# Variables, on the other hand, are very simple and dumb things: They store one string each – nothing complex in that.
# Shell items are referred to by their handle, variables by their name.
# You usually store the handle of a shell item in a variable.
# You usually do not access a shell item directly, but by using the variable storing its item handle.
# For using a variable, i.e. accessing its contents, you need the dollar sign ("$"). Opposed to this there is no dollar sign with item handles, because there is no such thing as a simple content of an item.

You may at any time request some action from an existing shell item. For doing so, you use the following command:

set <var>itemhandle</var> actionrequest

Here "<var>itemhandle</var>" is the internal handle of the respective {{Stx}} item, and the exact nature of "<code>actionrequest</code>" depends on what kind of item you are dealing with; you may, e.g., request a table item to add or remove one or more rows, or a file item to write or to read data.

Since requesting some item to do something is such common a task, you may abbreviate it by completely omitting the "<code>set</code>" command. This means that instead of "<code>set itemhandle actionrequest</code>", you may at any time type the following command:

<var>itemhandle</var> actionrequest

So there would actually be no need of even knowing about the "<code>set</code>" command, were it not for the fact that with the {{STx}} online help, you find the actions each kind of item supports under the keyword "<code>set itemtype</code>" (<code>[[Programmer_Guide/Shell_Items/Table/SET_TABLE|set table]]</code>, <code>[[Programmer_Guide/Shell_Items/Dialog/SET_DIALOG|SET DIALOG]]</code>, <code>[[Programmer_Guide/Shell_Items/Graph/SET_GRAPH|SET GRAPH]]</code>, and so on).

Let's have a first simple example on how shell items are normally used:

// create a table whose handle is called "myhandle"
[[Programmer_Guide/Shell_Items/Table/NEW_TABLE|new table]] myhandle

// set third line (first and second line will be created empty)
[[Programmer_Guide/Shell_Items/Table/SET_TABLE|set]] myhandle 2 'third line' // explicitly using "set"

// replace empty first line with a string
[[Programmer_Guide/Shell_Items/Table/SET_TABLE|myhandle]] 0 'first line' // not using "set" works just as well

// now replace the second line, too
[[Programmer_Guide/Shell_Items/Table/SET_TABLE|myhandle]] 1 'second line'

// show the table
[[Programmer_Guide/Macro_Library/StdLib#ShowItem|showitem]] myhandle ; Showing table "myhandle"

// now, just for the fun of it, delete the second row – note that, again,
// either using "set" or omitting it makes no change at all
[[Programmer_Guide/Shell_Items/Table/SET_TABLE|myhandle]] myhandle 1 /Delete

// finally, show the reduced table
[[Programmer_Guide/Macro_Library/StdLib#ShowItem|showitem]] myhandle; Showing table myhandle" after deleting its second row

[[Programmer_Guide/Command_Reference/DELETE|delete]] myhandle // don't forget to delete the item after use

In this example, we create a table item whose handle is the string "<code>myhandle</code>". Any further access to this item is done with this handle. Note that there is no dollar sign when using "<code>myhandle</code>", because "<code>myhandle</code>" is not a variable, but an item handle. If, by mistake, we would use the expression "<code>$myhandle</code>", {{STX}} would replace this expression by the contents of the shell-global variable "<code>myhandle</code>" – an empty string in case of there being no such variable, and surely an undesired result. Bluntly put: Item handles and variables reside in different namespaces, and you may well have like-named variables and item handles (of course this is not at all recommended because it may lead to some degree of confusion.)

All that being said, it is, common practice not to choose a handle of one's own, but to let {{Stx}} do the choosing. In this case, the automatically chosen handle is normally stored in an {{STx}} variable:

// create a table item with a handle of STX's choice (e.g. T#27)
// (the asterisk instructs {{STX}} to choose a handle on its own).
// the handle will be stored in a variable called "#tab"
#tab := [[Programmer_Guide/Shell_Items/Table/NEW_TABLE|new table]] *

// set third line (first and second line will be created empty)
[[Programmer_Guide/Shell_Items/Table/SET_TABLE|$#tab]] 2 'third line'

// replace empty first line with a string
[[Programmer_Guide/Shell_Items/Table/SET_TABLE|$#tab]] 0 'first line'

// now replace the second line, too
[[Programmer_Guide/Shell_Items/Table/SET_TABLE|$#tab]] 1 'second line'

// show the table
[[Programmer_Guide/Macro_Library/StdLib#ShowItem|showitem]] $#tab ; Showing table "#tab"

// now, just for fun, delete the second row
[[Programmer_Guide/Shell_Items/Table/SET_TABLE|$#tab]] 1 /Delete

// finally, show the reduced table
[[Programmer_Guide/Macro_Library/StdLib#ShowItem|showitem]] $#tab ; Showing table "#tab" after deleting second row

// old-style deletion
// [[Programmer_Guide/Command_Reference/DELETE|delete]] $#tab // important: delete after use
// #tab := set <nowiki>''</nowiki> // clean the variable

// new-style deletion - deletes the shell item whose name is stored in a variable,
// ''and'' clears the variable
[[Programmer_Guide/Command_Reference/DELETE|delete]] /Var #tab // no dollar here!

N.B.: Whenever actively allocating a shell item (normally with the "<code>[[Programmer_Guide/Command_Reference/NEW|new]]</code>" command), you should always delete it as soon as you no longer need it. If you don't, your macro(s) will consume an unnecessarily high amount of memory which may, for large macro applications, impair performance. There is no such thing as automatic garbage collection in {{Stx}}.

===Shell Tables in Detail===

There are three kinds of tables: (a) [[Programmer_Guide/Concepts/Simple_table|plain, or simple, tables]], (b) [[Programmer_Guide/Concepts/Parameter_table|parameter tables]], and (c) [[Programmer_Guide/Concepts/Extended_table|extended tables]] (I do not mention [[Programmer_Guide/Concepts/Directory_table|directory tables]] here, and I do not even mention that I do not mention [[Programmer_Guide/Concepts/Directory_table|directory tables]] here). [[Programmer_Guide/Concepts/Simple_table|plain, or simple, tables]] are easiest to handle, and they are most useful for storing lists of strings, each table entry being one such string. [[Programmer_Guide/Concepts/Extended_table|Extended tables]] are such that tables more versatile than them cannot be conceived: [[Programmer_Guide/Concepts/Extended_table|Extended tables]] tables may consist of an arbitrary number of columns each of which may be a string, an {{STx}} name, an integer, or a general number. Access to each column may be done, at the programmer's discretion, either by its index or by its symbolic name. [[Programmer_Guide/Concepts/Parameter_table|Parameter tables]], in turn, are a somewhat reduced variant of extended tables, in that they store numbers only. On the other hand, parameter tables do so most efficiently, both memory-wise and runtime-wise. This makes [[Programmer_Guide/Concepts/Parameter_table|parameter tables]] the preferred means of storing numerical vectors and matrices, and for doing numerical operations of the utmost complicated kinds. The following chapters will deal with each kind of table in detail.

====Plain, or Simple, Tables====

[[Programmer_Guide/Concepts/Simple_table|Plain tables]] are mainly useful for storing lists of strings. As always, these strings may be of arbitrary content, allowing for e.g. logically storing multiple values per row that are, in turn, retrieved by the "<code>readstr</code>" or even the "<code>readtab</code>" command (the [[Programmer_Guide/Command_Reference/READ|READ family of commands]]). Be this as it may, with the availability of the more efficient extended tables for database-like structured data, and of parameter tables for structured numerical data like vectors and matrices, storing structured data in plain tables is no longer recommended.

The "<code>[[Programmer_Guide/Shell_Items/Table/NEW_TABLE|new table]] *</code>" command creates a plain table item. The name of this table item will be stored in the reserved variable "<code>#new</code>". Furthermore, it will be the result of the "<code>[[Programmer_Guide/Shell_Items/Table/NEW_TABLE|new table]] *</code>" command. The asterisk, though strictly instructing {{STX}} to choose an internal name on its own, should be considered a part of the command and should not normally be altered.

Have a look at the following example using simple tables. The macro "<code>tablewrite</code>" will create a table, fill it with a hundred strings, delete every other row, and, finally, save the table to a file. The macro "<code>tableread</code>" will, in turn, re-read the table from the file.

[Macro tablewrite]
// create the table
#tab := [[Programmer_Guide/Shell_Items/Table/NEW_TABLE|new table]] *

// the "[[Programmer_Guide/Macro_Library/StdLib#UM_and_EM|em]]" command will, after displaying its second argument in an error
// dialog, immediately terminate the macro, using its first argument as the
// result of the macro
if '$#tab[?]' != table [[Programmer_Guide/Macro_Library/StdLib#UM_and_EM|em]] '-1 ; Cannot create table'

// fill the table with a hundred strings
for #i := 1 to $#i <= 100 step #i := int $#i+1
$#tab $#i 'This is string $#i out of 100'
end

// now we prove of changing mind and delete every other row
for #i := 98 to $#i >= 0 step #i := int $#i-2
$#tab $#i /Delete
end

// show the contents of the table
[[Programmer_Guide/Macro_Library/StdLib#ShowItem|showitem]] $#tab ; See Our Table

// now save the table as a text file called "table_file.txt".
// the file will be stored in the {{Stx}} script directory (whose path
// is available in the shell-global variable "scriptDirectory")
#fileName := set '$scriptDirectory\table_file.txt'

// create a text file item – we will come to this in a later chapter,
// here it is shown only as kind of cliffhanger
#fileItem := [[Programmer_Guide/Shell_Items/File/NEW_FILE|new file]] * '$#fileName' /Text /Write
if '$#fileItem' == * [[Programmer_Guide/Macro_Library/StdLib#UM_and_EM|em]] '-1 ; failed to open the file $#fileName'

// save the table to the file
[[Programmer_Guide/Shell_Items/File/SET_FILE#Text_Files:_SAVE|$#fileItem save]] $#tab

if '$rc' > 0 [[Programmer_Guide/Macro_Library/StdLib#UM_and_EM|em]] '-1 ; failed to save table to file $#fileName'

// dispose of the file item (not the file on disk!) and the table
[[Programmer_Guide/Command_Reference/DELETE|delete]] $#fileItem $#tab

exit 1 int 0

[Macro tableread]
// create an empty table
#tab := [[Programmer_Guide/Shell_Items/Table/NEW_TABLE|new table]] *
#fileName := set '$scriptDirectory\table_file.txt'

// now, create a file item for reading a text file
#fileItem := [[Programmer_Guide/Shell_Items/File/NEW_FILE|new file]] * '$#fileName' /Text /Read
if '$#fileItem' == * [[Programmer_Guide/Macro_Library/StdLib#UM_and_EM|em]] -1 ; failed to open the file $#fileName

[[Programmer_Guide/Shell_Items/File/SET_FILE#Text_Files:_LOAD|$#fileItem load]] $#tab
if '$rc' > 0 [[Programmer_Guide/Macro_Library/StdLib#UM_and_EM|em]] -1 ; failed to load table from file $#fileName

[[Programmer_Guide/Command_Reference/DELETE|delete]] $#fileItem

// show the loaded table
[[Programmer_Guide/Macro_Library/StdLib#ShowItem|showitem]] $#tab ; See Our Loaded Table

[[Programmer_Guide/Command_Reference/DELETE|delete]] $#tab
exit 1 int 0

The above macro already makes use of file items we need to leave for later discussion. As you can see, using them for saving and loading tables is fairly easy. You might even at this stage start saving and loading tables of your own without having looked up any details about file items.

====Parameter Tables====

[[Programmer_Guide/Concepts/Parameter_table|Parameter tables]] store numerical data only. They are optimized for numerical throughput and, hence, are the means of choice when it comes to modelling vectors and matrices.

Technically, parameter tables are a variant of the extended tables yet to be mentioned. The reason why we deal with parameter tables first is their optimal fitness for vector and matrix arithmetic. Note that extended tables, when they are all numerical, support exactly the same operations as parameter tables – in fact, numerical-only extended tables and parameter tables are completely interchangeable. Nevertheless, parameter tables are more efficient both runtime-wise and memory-wise. So, as a rule of thumb, always use parameter tables whenever doing vector and matrix arithmetic.

There are two ways of creating a parameter table:
# explicitly, by using the [[Programmer_Guide/Shell_Items/Table/NEW_TABLE|NEW TABLE … /Parameter]] command; or
# implicitly, by using the matrix or vector result of a call to [[Programmer_Guide/Command_Reference/EVAL|eval]].

Here's a simple and semantically quite meaningless example of working with parameter tables created both ways:

// create a 20-element vector initialized with all zeroes
#v0 := [[Programmer_Guide/Command_Reference/EVAL/fill|eval fill]](20,0,0) // 20 elements, first value 0, increment 0

// create and fill a vector
#v1 := [[Programmer_Guide/Command_Reference/EVAL/fill|eval fill]](30,2,4) // 30 elements, first value 2, increment 4

// create and fill a second vector
#v2 := [[Programmer_Guide/Command_Reference/EVAL/fill|eval fill]](30,3,9) // 30 elements, first value 3, increment 9

// add up both vectors
#v3 := eval $#v1 + $#v2

[[Programmer_Guide/Macro_Library/StdLib#ShowItem|showitem]] $#v3 ; v3 // show the sum vector

// create a vector with 30 elements each of which is the sine
// of its index (not a useful example, but useful for an example)
#v4 := [[Programmer_Guide/Shell_Items/Table/NEW_TABLE|new table]] * * number:x /Parameter
for #i := 0 to $#i < 30 step #i := int $#i + 1
// store the sine of the index, #i, in #a
#a := eval sin($#i)

// set the #i-th value of the vector to the value of #a
$#v4 $#i $#a
end

// transpose a matrix

// create the matrix to transpose – here we must explicitly create the
// matrix because we are going to assign values to its
// individual columns
#mat1 := [[Programmer_Guide/Shell_Items/Table/NEW_TABLE|new table]] * * number:x:4 /Parameter // 4 columns

// fill each of its individual columns with some values
$#mat1[*,0] := [[Programmer_Guide/Command_Reference/EVAL/fill|eval fill]](30,10,4) // fill the first column
$#mat1[*,1] := [[Programmer_Guide/Command_Reference/EVAL/fill|eval fill]](30,2,1) // fill the second column
$#mat1[*,2] := [[Programmer_Guide/Command_Reference/EVAL/fill|eval fill]](30,0.1,1.2) // fill the third column
$#mat1[*,3] := [[Programmer_Guide/Command_Reference/EVAL/fill|eval fill]](30,1.2,1.2) // fill the fourth column

// now transpose mat1 and store the transposed matrix to mat2
#mat2 := [[Programmer_Guide/Command_Reference/EVAL/trn|eval trn]]($#mat1)

// show the transposed matrix
[[Programmer_Guide/Macro_Library/StdLib#ShowItem|showitem]] $#mat2 ; transposed matrix

// now, multiply the matrix by the vector and see what happens
#mat3 := eval $#mat2 * $#v3

[[Programmer_Guide/Macro_Library/StdLib#ShowItem|showitem]] $#mat3 ; Transposed matrix multiplied by a vector

// create and initialize a matrix in a single step
#mat4 := eval init(30,10,1.2) // 30 rows, 10 columns, value 1.2

[[Programmer_Guide/Macro_Library/StdLib#ShowItem|showitem]] $#mat4 ; A matrix containing all 1.2

// important: delete all items not to leak memory
[[Programmer_Guide/Command_Reference/DELETE|delete /Var]] #v0 #v1 #v2 #v3 #v4 #mat1 #mat2 #mat3 #mat4

exit







== {{STx|caps}} Pitfalls ==

When invocating a macro for the second time, third time, or generally the n-th time, n being any finite positive integer, it will find its namespace empty. This is what you would expect from a full-featured programming language, but it is not what you get from many macro languages inferior to {{STX}}, or even from classical languages like the venerable FORTRAN, Basic, or – God forbid – COBOL.

One important implication of this fact is that local variables are not a means for storing data persistently (bluntly put, local variables are no such thing as the local "static" variables of Kernighan's and Ritchie's fine C programming language).

This consistently holds true even when invocating a macro recursively. Its new instance will find all its variables empty, while the calling instance will find its local variables untouched by the macro call.

Hence, local variables are no means at all for passing information to and from a macro. For passing data to a macro, you should use macro arguments. For a macro to return results, you should use the return mechanism (using the verbose form of the "<code>[[Programmer_Guide/Command_Reference/EXIT|exit]]</code>" command). Technically, another means of passing data to and from a macro is using shell-global (or even global) variables, but in the era of structured and modular programming, this is considered harmful to one's career.

Using one and the same variable name in different scopes is technically valid. You may, e.g., have a global variable called <code>@i</code>, a shell-global variable <code>i</code>, and a local variable called <code>#i</code>. Allow for it to be misleading and a source of programmer error, though.

Misspelled variable names tend to be the cause for great confusion. What makes it worse is that there is no way of automatically detecting misspelled variable names: Since variables need not be explicitly declared nor initialized, any syntactically well-formed variable name will be valid at any stage – this is an issue all programming languages without explicit variable declarations share, among them illustrious names like FORTRAN, Basic, or PROLOG. There is no real remedy for this issue other than placing debug statements in the macro source that occasionally print out the values of some important variables, and to check the printed values against one's expectations.

More than the occasional pitfall results from the fact that the expression in an assignment is a rather complex issue. Though this expression is, in last consequence, a string (remember that with {{Stx}}, all variables are being created equal, i.e. as string variables), the way this string is computed may be a surprisingly complex, heart-warmingly powerful, and sometimes even error-prone affair, bearing the potential for unexpected side-effects. That being said, preventing most kinds of trouble is easy by following two rules of thumb: (a) put everything under apostrophes; and (b) use the appropriate expression type selector when directly assigning a value (as opposed to the result of a function call or a built-in function). So, instead of writing "<code>name := hugo</code>", always type "<code>name := set 'hugo'</code>".

Users, especially those familiar with other programming languages, but not with macro languages like the UNIX shells, often confuse when to prefix the name of a variable with the dollar sign and when not to. The rule is easy: If you want to ''mention'' a variable, you do not use the dollar sign. If you want to ''use'' a variable, that is, if you want its occurrence be replaced by its actual contents, you do use the dollar sign. Compiled to a rule of thumb: If the variable is the target of an assignment, you do not use a dollar sign. If the variable is the source of an assignment, or if it is the argument to a function or macro call, you do use the dollar sign.

When using string constants, you should generally use quotation, i.e., place them between single quotes.

Where two or more quoted string constants meet (but see the below exception), they will get concatenated without inserting any whitespace characters. This is a standard feature with many programming languages, especially macro languages, but it is sometimes met with surprise. So please be aware that if you want two string constants to be separated by a blank, you will either need to quote the whole string, or to add the whitespace character at the beginning or at the end of the respective string literal. Hence, the statement "<code>#var := set 'abc' 'def'</code>" will set <var>#var</var> to "abcdef", whereas each of the statements "<code>#var := set 'abc ' 'def'</code>", "<code>#var := set 'abc' ' def'</code>", and "<code>#var := set 'abc def'</code>" will set <var>#var</var> to "abc def".

If a quoted string constant is an argument to a statement or to a built-in function (i.e. not to a user macro), there will be no string concatenation. Hence, each quoted string and each unquoted string is exactly one argument to the function.

If a statement or a built-in function expects a numerical argument, this argument may either be a numerical constant or a numerical expression. Either way, it is more secure to quote even a numerical argument (don't quote me on that, though).

It is easy to mix up the reserved variables "<var>rc</var>" and "<var>result</var>". The former ("<var>rc</var>") contains the numerical return code of the {{STx}} statement or built-in function most-recently executed (or the reason code why some {{STX}} statement could not be executed). The latter ("<var>result</var>") contains whatever information the most recently called user-defined macro (or class method) chose to return.

Unlike most other programming languages and many macro languages, {{Stx}} evaluates logical expressions strictly from left to right. Furthermore, it does not support grouping (i.e. using brackets). Although this is not a bad thing in general, it may be cause for error and misunderstanding. When writing down a logical expression, be aware that no rules of precedence will apply. If in doubt, use a second (third, fourth…) "<code>[[Programmer_Guide/Command_Reference/IF|if]]</code>" statement within the scope of each other.

Note that whitespace characters may at any time freely be interspersed within a number. This means that e.g. the string "<code>123 456</code>", although containing a blank character, will be interpreted as the number "123456". This is not a bad thing in itself, but you should be aware of this fact.

Never forget to free an object (both shell-items and user-defined classes) after use. If you don't, and automatic cleanup will only be done at the termination of the running shell which, when using a complex set of macros, may be very late.

Be careful not to mix up internal {{STx}} item handles on the one hand and variable names on the other hand. Remember that accessing an {{STX}} item by its name means just using this name – there is no dollar sign involved. If, on the other hand, your item handle is stored in an {{Stx}} variable, you will need to refer to the contents of this variable, i.e. use this variable – here there is a need for using the dollar sign.

Programmer Guide/Macro Library/BXMLDoc

2019-10-01T08:41:44Z

Jw: /* "Set" functions */

{{DISPLAYTITLE:{{SUBPAGENAME}} - General XML Document}}
:'''File''': BXMLDOC.STX, linked to library STX.LIB
:'''Parent class''': [[Programmer Guide/Macro Library/COBJ|CObj]], '''Derived classes''': [[Programmer Guide/Macro Library/BSTXIni|BSTXIni]], [[Programmer Guide/Macro Library/BDataSet|BDataSet]]

This class implements a general xml-document. It is mainly used to implement the common part of the two main {{STx}} documents: the project <code>BDataSet</code> and the workspace <code>BSTXIni</code>.

==Construction==
;<code>COBJ NEW BXMLDOC NEW|XNEW ; <var>xmlobj</var>|<var>roottag</var> [; <var>aname</var>=<var>avalue</var>; ...]</code>:
:;<var>xmlobj</var>: The name of a BXMLDoc-instance or the name of a XML-file-item.
:;<var>roottag</var>: The tag of the root element.
:;<var>aname</var>, <var>avalue</var>: The name and the value of a root element attribute.
;Result: The created and initialized instance-item or an empty string
;Description: Create a new empty XML document using the same root element tag as <var>xmldoc</var> or the specified <var>roottag</var>. During initialization the XML doctype is loaded, if it is defined in the {{STX}} configuration file, and the global item table is created. The <code>XNEW</code> variant creates or opens the XML file using the /Exclusive flag.

;<code>COBJ NEW BXMLDOC CREATE|XCREATE ; <var>filepath</var>; <var>roottag</var> [; <var>aname</var>=<var>avalue</var>; ...]</code>:
:;<var>filepath</var>: The name of the XML file.
:;<var>roottag</var>: The tag of the root element.
:;<var>aname</var>, <var>avalue</var>: The name and the value of a root element attribute.
;Result: The created and initialized instance-item or an empty string
;Description: Open an existing or create a new XML file and initialize the XML document. During initialization the XML doctype is loaded, if it is defined in the {{STX}} configuration file, and the global item table is created. If a new file is created, the root element with tag <var>roottag</var> and the specified attributes is created. The <code>XCREATE</code> variant creates or opens the XML file using the /Exclusive flag.

;<code>COBJ NEW BXMLDOC OPEN|XOPEN ; <var>filepath</var></code>:
:;<var>filepath</var>: The name of the existing XML file.
;Result: The created and initialized instance-item or an empty string
;Description: Open an existing XML file and initialize the XML document. During initialization the XML doctype is loaded if it is defined in the {{STX}} configuration file and the global item table is created.

;<code>COBJ NEW BXMLDOC LINK ; <var>xmlobj</var></code>:
:;<var>xmlobj</var>: The name of a BXMLDoc-instance.
;Result: The created and initialized instance-item or an empty string
;Description: Link the new XML document to the XML document <var>xmlobj</var> which was created and initialized in another shell. This constructor allows the sharing of XML documents between shells. This feature is f.i. used to share the global Workspace object (<code>$BSTXIni</code>) and the DataSet object (<code>$BDataSet</code>). Instances create with this method shares the file item and the global item table.

==Access control==
Because an BXMLDoc instance can be used by more than one shell, there must be a mechanism to control the access to the instance and its data content.

====Attach====
;<code><var>bxmldoc</var> Attach [ <var>iref</var> ]</code>:
:;<var>iref</var>: Element reference or xml-position.
;Result: name of file-item of the document
;Description: Lock the XML document to the calling shell. The current position is saved. If an element reference or xml-position <var>iref</var> is specified, the member <code>SELECTIREF</code> is called to select the element. If a shell calls this function for the first time, the current XML file position is saved, for all further calls, only the lock-counter is increment.
:This function should be called any time before a shell uses a shared XML document. If a shell issues more than one <code>Attach</code> function call, it must use the same number of <code>Detach</code> calls to unlock the XML document.

====Detach====
;<code><var>bxmldoc</var> Detach</code>:
;Result: 1 if the xml-file-item was changed while it was locked and 0 if not. The return value is also 0 if the xml-file-item was not unlocked by the <code>Detach</code> function.
;Description: Unlock the XML document from the shell and restores the element selected before the document was locked. If multiple <code>Attach</code> calls were used, the same number of <code>Detach</code> calls is necessary to really unlock the document.

==Query attributes==
====GetFileItem====
;<code><var>bxmldoc</var> GetFileItem</code>: Get the XML file item of the instance. The file should only be accessed directly if the XML document is locked to the shell (see [[#Access control]]). The use of the file item may be necessary to perform attribute access, element data access or special browse / search functions.
;Result: the xml-file-item

====GetDocType====
;<code><var>bxmldoc</var> GetDocType</code>: Retrieve the name of the doctype if a doctype is defined for the root element of the XML file.
;Result: name of XML doctype or empty string (if no doctype is defined for the document)

====GetPath====
;<code><var>bxmldoc</var> GetPath</code>: Retrieve the name of the XML file as stored on the hard drive. The result is empty if no file is associated with the document (this means the file exists in memory and was never loaded or saved). The function sets the <code>&path</code> member variable.
;Result: the path of the the xml-file-item

==File handling==
====Load====
;<code><var>bxmldoc</var> Load [ <var>path</var> ]</code>: Load the content of the file <var>path</var> into the xml-file-item of the document. If <var>path</var> is not specified, the current path is used (see <code>GetPath</code>).
;Result: 0 for success or errorcode

====Save====
;<code><var>bxmldoc</var> Save [ <var>path</var> ]</code>: Save the xml-file-item of the document to the file <var>path</var>. If <var>path</var> is not specified, the current path is used (see <code>GetPath</code>).
;Result: 0 for success or errorcode

====Close====
;<code><var>bxmldoc</var> Close [ <var>save</var>=0 [; <var>path</var> ] ]</code>: Close the xml-file-item and delete the instance <var>bxmldoc</var>. If the argument <var>save</var> is set to <code>1</code>, the document is saved before it is deletec (using the function call <code><var>bxmldoc</var> Save [ <var>path</var> ]</code>).
;Result: 0 for success or errorcode (returned from <code>Save</code>).
;Note: The instance <var>bxmldoc</var> is deleted, even if the function returns an errorcode.

==Global items==
This class implements some members to share items between shells. This feature is used f.i. by the application <code>Viewer1</code> to implement the '''signal copy-paste''' functions and by some other applications.

====AddGlobalItem====
;<code><var>bxmldoc</var> AddGlobalItem <var>id</var> ; <var>item</var></code>:
:;<var>id</var>: The global id-string to use for <var>item</var>.
:;<var>item</var>: The shell-item to add to the global-item-list.
;Result: 0 for success or errorcode
;Description: Add a shell item to the global item list. All items in the global item list can be linked by other shells, which have created a linked (shared) instance of this XML document. All types of items except displays, graphs and dialogs can be used.

====AttachGlobalItem====
;<code><var>bxmldoc</var> AttachGlobalItem <var>id</var> [; <var>lock</var>=0 ]</code>:
:;<var>id</var>: The id-string of the global-item.
:;<var>lock</var>: If set to <code>1</code> the returned shell-item is locked.
;Result: name of shell-item linked to the global-item or empty string
;Description: Creates a [[Programmer_Guide/Shell_Items#References_to_shell_items|linked instance (reference)]] of the global item with the specified id. If lock is set to 1 the linked instance is locked to the calling shell.

====DetachGlobalItem====
;<code><var>bxmldoc</var> DetachGlobalItem <var>item</var> [; <var>unlock</var>=0 ]</code>:
:;<var>item</var>: A shell-item linked to a global-item.
:;<var>unlock</var>: If set to <code>1</code> the <var>item</var> is unlocked before it is deleted.
;Result: no return value (void)
;Description: Deletes a linked item. If unlock is set to 1 the linked item is unlocked before it is removed.

====DeleteGlobalItem====
;<code><var>bxmldoc</var> DeleteGlobalItem <var>id</var> [; <var>delete</var>=0 ]</code>:
:;<var>id</var>: The id-string of the global-item.
:;<var>delete</var>: If set to <code>1</code> the shell-item is deleted.
;Result: 0 for success or errorcode
;Description: Remove the global-item with id-string <var>id</var>from the global-item-list. If <var>delete</var> is set to 1, the item is deleted after removing from the list. An item can only be removed by the same shell that adds it to the list.

==Element manipulation==
====AddElement====
;<code><var>bxmldoc</var> AddElement <var>tag</var> ; <var>where</var> ; <var>goto</var> ; <var>attr</var>=<var>value</var> ; ...</code>:
:;<var>tag</var>: The element tag.
:;<var>where</var>: Controls where the element should be created: create the element on the current level (<code>CURRENT</code> or <code>0</code>) or as a child of the current element (<code>CHILD</code> or <code>1</code>).
:;<var>goto</var>: Controls how the current position should be changed after the new element is created: select the created element (<code>SELECT</code> or <code>1</code>), step into the created element (<code>INSIDE</code> or <code>2</code>) or do not change the selected element (<code>HOLD</code> or <code>0</code>).
:;<var>attr</var>=<var>value</var>: Name(s) and value(s) of attributes to be assigned to the new element. All <var>name</var> arguments must specifiy a valid XML attribute name.
;Result: 0 for success or errorcode
;Description: Add a new element with the specified tag to the XML document. The element is added on the same level as the current element (<var>where</var>=<code>CURRENT</code>) or as child element (<var>where</var>=<code>CHILD</code>) of the current element. The attribute assignment <var>attr</var>=<var>value</var> are used to initialize the new elements attributes. If the function returns <code>0</code> the new element is created and the position is changed according to the argument <var>goto</var>, otherwise the document content and the current element position are not changed. To assign the attributes to the element the function call <code><var>bxmldoc</var> SetElement * ; <var>attr</var>=<var>value</var> ; ...</code> is used.

====SetElement====
;<code><var>bxmldoc</var> SetElement <var>pos</var> ; <var>attrarg</var> ; ... </code>:
:;<var>pos</var>: The xml-position or element reference of the element to be changed. The value <code>*</code> :;attrarg: Defines the name and the value of the attribute(s) to be set.
::;<var>aname</var>=<var>avalue</value>: Assign the value <var>avalue</var> to the attribute <var>aname</var>. The <var>aname</var> must be a valid xml-attribute name. If <var>avalue</var> is empty, the attribute <var>aname</var> is deleted.
::;<var>attrtab</var>: The name of a simple-table containing one attribute setting <code> <var>aname</var> = <var>avalue</var> </code> per entry. This table gets deleted after processing!
;Result: 0 for success or errorcode.
;Description: Set the attributes of a specific element. The current position is not changed by this function. An error is returned, if no element is found at the specified position <var>pos</var>, or an attribute assignment fails. If an error is returned, some attributes of the element may be changed! To remove an attribute, an empty attribute value can be used (<code> <var>aname</var>=; </code>).

====GetElement====
;<code><var>bxmldoc</var> GetElement <var>pos</var> ; <var>info</var> ; aname1 ; ... </code>:
:;<var>pos</var>: The xml-position or element reference of the element.The value <code>*</code> can be used for the element at the current position.
:;<var>info</var>:
::{|class="einrahmen"
|<code>0</code> ||get attribute values ||result = <var>avalue1; ...</var>
|-
|<code>1</code> ||get element tag and attribute values ||:result = <var>tag; avalue1; ...</var>
|-
|<code>2</code> ||get element tag, number of children and attribute values ||result = <var>tag; nchildren; avalue1; ...</var>
|}
:;<var>aname1</var>, ...: list of attribute names
;Result: empty string (element not found) or a string containing selected informations (see argument <var>info</var>)
;Description: Retrieve general informations about the specified element and/or element attribute values. The current element position is not changed by this function.

====DeleteElement====
;<code><var>bxmldoc</var> DeleteElement <var>pos</var></code>:
:;<var>pos</var>: The xml-position or element reference of the element.The value <code>*</code> can be used for the element at the current position.
;Result: 0 for success (deleted) or 1 for error
;Description: Delete the selected element. The current element position is only changed, if the current element was deleted.

==Data manipulation==
====GetDataType====
;<code><var>bxmldoc</var> GetDataType [ <var>tag</var> ]</code>:
:;<var>tag</var>: The element tag to be tested; if not specified or set to <code>*</code> the tag of the current element is used.
;Result: The data type defined in the doctype or the element tag if no data type is defined for the specified tag.
;Description: Returns type of date stored in elements with the specified tag. This function is used by <code>LoadData</code> and <code>SaveData</code> to retrieve data type information. In the current doctype-version only the types <code>TABLE</code> and '<code>XTABLE tabledef</code>' are supported.

====CreateXTable====
;<code><var>bxmldoc</var> CreateXTable <var>typedef</var> [ <var>fname1</var> ... ]</code>:
:;<var>typedef</var>: The name (ID) of the <code>XTableTypeDef</code> element.
:;<var>fname1</var>, ...: The name of the extra fields to be added to the extended table.
;Result: The name of the new and initialized extended table-item or an empty string.
;Description: Creates an extended table using the specified <var>typedef</var> or retrieves data type information for the current element (if no <var>typedef</var> is specified). If extra fields are specified and the <var>typedef</var> contains a definition statement for the extra fields, they are added to the table.
;Note: A <var>typedef</var> for an extended table is defined in an xml element with the tag <code>XTableTypeDef</code> with the attribute <code>ID="<var>typedef</var>"</code>. This element must be defined in the definition-section of the {{STX}} configuration file or on level of the current element.

====LoadData====
;<code><var>bxmldoc</var> LoadData</code>:
;Result: The name of the shell-item (table) containing the loaded data or an empty string.
;Description: Loads the data stored in the current element. The item for the data is created in the function and returned to the caller. Data type information is retrieved by calling <code>GetDataType</code> and <code>CreateXTable</code>.
;Example: Load data from the {{STX}} configuration file at the IRef <code>/Definitions/DataSet/Methods</code>.
<pre>
...
$bstxini attach
$bstxini selectiref '/Definitions/DataSet/Methods'
if '$result' == 0 #data := $bstxini loaddata
$bstxini detach
...
</pre>

====SaveData====
;<code><var>bxmldoc</var> SaveData <var>item</var> [ ; <var>del</var>=0 ]</code>:
:;<var>item</var>: Shell-item (table) containing the data to be saved.
:;<var>del</var>: If set to <code>1</code> the shell-item is deleted after saving
;Result: 0 for success or errorcode
;Description:Save <var>item</var> into the data section of the current element. The data format is selected by calling <code>GetDataType</code>. The item is only saved, if it is valid for the data type. If <var>item</var> is saved successful and <var>del</var> is set to <code>1</code>, <var>item</var> is deleted.

==IRef functions==
* This group of functions was originally developed, to deal with unique references to elements of type '''Set''' with the special unique id attribute '''ID'''. This implementation was modified, because the attribute '''ID''' is now used as a unique identifier for elements of any type.
* A string in the format ''' /''id1''/''id2''/.../''idn'' ''' is called '''IRef''' (for "(unique) Internal REFerence"). This string is interpreted as follows:
** ''id1'' is the unique element id (value of attribute '''ID''') on the root-level
** ''id2'' is the unique element id inside the element selected by ''id1''
** and so on

====SelectIRef====
{{/SelectIRef}}

====FormatIRef====
;<code><var>bxmldoc</var> FormatIRef [ <var>pos</var>=* ]</code>
:;<var>pos</var>: The XML element position or <code>*</code> for the current element.
;Result: A reference (IRef) to the selected element or an empty string.
;Description:Generates the internal XML reference string for the specified element at position <var>pos</var>. This string can only be created if all elements in the path except the root element have an ID attribute.
;see also: commands [[Programmer_Guide/Command_Reference/IREF|IREF]] and [[Programmer_Guide/Command_Reference/POSITION|POSITION]]

====UniqueID====
;<code><var>bxmldoc</var> UniqueID [ <var>pos</var>=* ; <var>id</var>=* ; <var>ext</var>=0 ; <var>start</var>=-1 ; <var>digits</var>=0 ]</code>
:;<var>pos</var>: The position/reference of the parent element (<code>*</code> = current element)
:;<var>id</var>: The fixed part of the id-string. If an asterisk is specified, the string "Auto" is used.
:;<var>ext</var>: Use the counter in the id-extension (<code>yes</code> or <code>1</code>) or append the counter directly to the id-string (<code>no</code> or <code>0</code>).
;<var>start</var>: The counter start value. Use <code>-1</code> to test <var>id</var> without the counter suffix: if <var>id</var> is unique it is returned without any modifications.
;<var>digits</var>: The number of digits. Use a value outside the range <code>2..9</code> to disable zero padding. If e.g. <var>digits</var> equals 3, the generated counter values will be <code>000</code>, <code>001</code>, <code>002</code>, etc.
;Result: A unique id string (unique on the selected level) or an empty string on failure.
;Description: Generate a unique id for the current level or inside the specified parent element. If <var>id</var> is unique, then <var>id</var> is returned. Otherwise, the counter is appended to <var>id</var> in the requested format.

=="Set" functions==
* This group of functions was originally developed to deal with elements of type '''Set''' with the special unique id attribute '''ID'''. This implementation was modified, because the attribute '''ID''' is now used as a unique identifier for elements of any type.

===ListSetElements===
<code><var>bxmldoc</var> ListSetElements [ <var>table</var>=* ; <var>iref</var>=* ]</code>
:;<var>table</var>: simple table-item to store result; if <code>*</code> is used a new table is created
:;<var>iref</var>: reference of the set-element containing the elements to be listed; use <code>*</code> for the current level
;Result: the table-item containing the result (list of id's) or an empty string
;Description: Lists all element id's on the current level (<var>iref</var>=*) or inside the specified set-element. If a table-item is passed, it is emptied before the id list is stored, otherwise a new table is created.

===FindSetElement===
<code><var>bxmldoc</var> FindSetElement [ <var>tag</var>=* ; <var>id</var>=* ; <var>iref</var>=* ]</code>
:;<var>tag</var>: element tag; use <code>*</code> for all elements
:;<var>id</var>: value of ID attribute; wildcards are possible
:;<var>iref</var>: reference of the set-element to be searched; use <code>*</code> for the current level
;Result: 0 if the element was found and 1 if not
;Description: Find the (first element) with the specified <var>tag</var> (* = search all element tags) and <var>id</var>. For the matching of tag and id a case-sensitive comparison is used! If no <var>iref</var> is specified, the current level is searched from the beginning, otherwise the search is performed inside the specified set.

===AddSetElement===
<code><var>bxmldoc</var> AddSetElement [ <var>tag</var> ; <var>id</var> ; <var>iref</var>=* ]</code>
:;<var>tag</var>: element tag
:;<var>id</var>: element id (value of ID attribute)
:;<var>iref</var>: reference of the set-element where the element should be created; use <code>*</code> for the current level
;Result: 0 if the element was selected/created and 1 if not
;Description: Create a new element with specified tag and id in the set selected by <var>iref</var>. If the specified set does not exist, it will be created. If a set must be created, for each set element the tag <code>SET</code> is used by default, but it is possible to specify another tag in the argument <code>ref</code> with the format: <code>/setid/.../settag:setid/.../</code>. If the element is created, the new element is selected, otherwise the position is not changed. If the element exists already, it is selected but not changed.

===LoadSetElement===
<code><var>bxmldoc</var> LoadSetElement [ <var>tag</var>=* ; <var>id</var>=* ; <var>iref</var>=* ]</code>
;Result: The loaded data object (table-item, value returned from <code>LoadData</code>) or an empty string.
:Description: This function uses the call <code><var>bxmldoc</var> FindSetElement <var>tag</var>;<var>id</var>;<var>iref</var></code> to select the element and the call <code><var>bxmldoc</var> LoadData</var></code> to load the content of the selected element. If element selection or loading data failes (error), the file position is not changed, otherwise (success) the loaded element is selected.

===SaveSetElement===
<code><var>bxmldoc</var> SaveSetElement [ <var>item</var> ; <var>del</var>=0 ; <var>tag</var>=* ; <var>id</var>=* ; <var>iref</var>=* ]</code>
;Result: 0 if the data item was saved successful and 1 otherwise
:Description: This function uses the call <code><var>bxmldoc</var> AddSetElement <var>tag</var>;<var>id</var>;<var>iref</var></code> to select or create the element and the call <code><var>bxmldoc</var> SaveData</var></code> to save the item into the element. If element selection or save operation failes (error), the file position is not changed, otherwise (success) the created/updated element is selected.

===DeleteSetElement===
<code><var>bxmldoc</var> DeleteSetElement [ <var>tag</var>=* ; <var>id</var>=* ; <var>iref</var>=* ]</code>
;Result: 0 if the element was deleted and 1 otherwise
:Description: This function calls <code><var>bxmldoc</var> FindSetElement <var>tag</var>;<var>id</var>;<var>iref</var></code> to select an element and than deletes the selected element.

==Misc==

====SavePos====
<code><var>bxmldoc</var> SavePos [ <var>delpos</var>=* ]</code>
;Result: current xml position id or empty string if position can not be saved (no element selected)
;Description: Returns the xml position id of the currently selected element. If the xmp position id <var>delpos</var> is not equal <code>*</code>, this position is closed (reset).
;See Also: [[Programmer_Guide/Command_Reference/POSITION|POSITION]]

====ResetPos====
<code><var>bxmldoc</var> ResetPos <var>pos</var>=* [ ; * ; <var>delemem</var>=0 ] </code>
;Result: always 0
;Description: Restore the the xml position id <var>pos</var>. If <var>delelem</var> equals 1 the element at the restored position is deleted.

<code><var>bxmldoc</var> ResetPos <var>table</var>=* [ ; <var>row</var>=* ; <var>delemem</var>=0 ; <var>deltable</var>=0 ] </code>
;Result: always 0
;Description: Restore all xml positions stored in <var>table[*,row]</var>. If <var>table</var> is a simple table, the argument <var>row</var> is ignored.
::* If <var>delelem</var> equals <code>1</code> the elements at the restored positions are deleted
::* If <var>deltable</var> equals <code>1</code> the <var>table</var> is deleted
::* This function can be used to reset positions returned by [[Programmer_Guide/Shell_Items/File/SET_FILE#Find_2|FIND]] or [[Programmer_Guide/Shell_Items/File/SET_FILE#EXTRACTTABLE|EXTRACTTABLE]] commands.

====ExtractSubDoc====
;<code><var>bxmldoc</var> ExtractSubDoc <var>file</var> ; <var>posattr</var> ; <var>tag1</var> ; <var>sub1</var> ; <var>tag2</var> ; <var>sub2</var> ; ...</code>:
:;<var>file</var>: The target XML file item for extracted elements.
:;<var>posattr</var>: The name of element attribute for positions of original elements.
:;<var>tagX</var>: The element tags to be extracted.
:;<var>subX</var>: Flag determining if child elements of <var>tagX</var> should be scanned scan too (yes=<code>1</code>, no=<code>0</code>).
;Result: none (void), <var>file</var> contains extracted elemenents
;Description: Extract the elements with the specified tags from the document and copy them into the specified target <var>file</var>. The original tree structure is retained. The content of an element with <var>tagX</var> is only scanned if the corresponding <var>subX</var> argument is set to <code>1</code> (or <code>yes</code>). The element data are not extracted. If <var>posattr</var> is not set to '<code>*</code>' the position string of the original element is stored in the attribute <code>posattr</code> of the copied (extracted) element. If a XML doctype is defined for the original document it is applied to the target file. The element extraction is performed with the command [[Programmer_Guide/Shell_Items/File/SET_FILE#EXTRACTFILE|EXTRACTFILE]].
:Note: If the positions of the original elements are saved, the function <code>ResetSubDoc</code> must be used to reset the positions before the target file is deleted.

====ResetSubDoc====
;<code><var>bxmldoc</var> ResetSubDoc <var>file</var> ; <var>posattr</var></code>:
:;<var>file</var>: A XML containing extracted elements.
:;<var>posattr</var>: The name of element attribute for positions of original elements.
;Result: none
;Description: Reset the extracted file and all saved positions. This function must be called for all XML files created with EXTRACTSUBDOC.

====DialogSelectElement====
<code><var>bxmldoc</var> DialogSelectElement <var>title</var> ; <var>selmode</var> ; <var>outmode</var> ; <var>tag1</var> ; <var>sub1</var> ; <var>tagX</var> ; <var>subX</var> ; ...</code>
:;<var>title</var>: The dialog window caption.
:;<var>selmode</var>: The selection mode {<code>SINGLE</code>|<code>MULTIMPLE</code>}.
:;<var>outmode</var>: The output mode {<code>POSITION</code>|<code>IREF</code>}
:;<var>tagX, subX</var>: The tag names and subtree scan flags which are passed to function <code>ExtractSubDoc</code>
;Result: An empty string for error/cancel or one of the values listed in the table below:
::{|class="einrahmen"
!selmode !!outmode !!result
|-
|SINGLE
|POSITION
|position string of selected element
|-
|SINGLE
|IREF
|internal reference of selected element
|-
|MULTIPLE
|POSITION
|simple table containing position strings of selected elements
|-
|MULTIPLE
|IREF
|simple table containing internal references of selected elements
|}
;Description: Extracts a sub-document using the function <code>ExtractSubDoc</code> and displays the sub-document tree in a dialog where the user can select one or more elements (depending on <var>selmode</var>). Depending on <var>outmode</var>, either the position/s or the internal reference/s of the selected element/s is/are returned. If <var>outmode</var> is set to <code>POSITION</code> the user must cleanup the positions when the element processing is finished.
;Examples: The following code displays a dialog with all audio files and sets in the current DataSet and retrieves the audio set information for the file chosen by the user (if any).

<pre>
#pos := $BDataSet DialogSelectElement title ; single ; position ; Set ; 1 ; AFile ; 0
if '$#pos' != '' then
readstr '$($BDataSet GetASetInfo $#pos soundfile)' #sf';'#setId';'#srate';'#ch';'#fPath
if '$#fPath' != '' #file := $#fPath
if '$#sRate' != '' #sr := $#srate
#iref := $($BDataSet FormatIRef $#pos)
#result := '$#file ; $#sr ; $#iref ; $#ch'
end
</pre>

====Table2VarSpace====
;<code><var>bxmldoc</var> Table2VarSpace <var>table ; del ; prefix ; inst</var></code>:
:;<var>table</var>: name of table containing variable settings
:;<var>del</var>: delete table after conversion (<code>0</code>=yes, <code>1</code>=no)
:;<var>prefix</var>: prefix string for variable names
:;<var>inst</var>: name of an instance item (optional);
;Result: none
;Description: Converts the variable assignments (<code>varname = varvalue</code>) stored in the table to variables. For each entry of the table a variable named <var>prefix</var><code>varname</code> is created and the value <code>varvalue</code> is assigned. If an instance item <var>inst</var> is specified, the variables are stored as member variables of the instance, otherwise the variable space used to store the variables depends on the prefix (e.g. if prefix equals '@', the variables are stored as global variables). If the argument <var>del</var> is set to <code>1</code> the table is deleted after conversion. See <code>VarSpace2Table</code> for conversion in the other direction.

====VarSpace2Table====
;<code><var>bxmldoc</var> VarSpace2Table table ; prefix; inst</code>:
:;<var>table</var>: name of table containing variable settings
:;<var>prefix</var>: prefix string for variable names
:;<var>inst</var>: name of an instance item (optional);
;Result: none
;Description: Convert variables to table. Each entry of <var>table</var> must define one variable in the format <code>varname = varvalue</code>. The <code>varvalue</code> is replaced by the current value of the variable <var>prefix</var><code>varname</code>. If an instance item <var>inst</var> is specified the variables are read from the instance item, otherwise the variables must be stored in the global or the shell variable space. See VarSpace2Table for conversion in the other direction.

====AFun====
;<code><var>bxmldoc</var> AFun <var>memberFunctionName</var> [ ; <var>memberFunctionArgs</var> ]</code>:
;Result: result returned from member function call
;Description: This function attaches the XML document to the calling shell, executes the member function call <code><var>bxmldoc</var> <var>memberFunctionName</var> [ <var>memberFunctionArgs</var> ]</code> and detaches the XML document.

Programmer Guide/Macro Library/BXMLDoc

2019-10-01T08:41:14Z

Jw: /* FormatIRef */

{{DISPLAYTITLE:{{SUBPAGENAME}} - General XML Document}}
:'''File''': BXMLDOC.STX, linked to library STX.LIB
:'''Parent class''': [[Programmer Guide/Macro Library/COBJ|CObj]], '''Derived classes''': [[Programmer Guide/Macro Library/BSTXIni|BSTXIni]], [[Programmer Guide/Macro Library/BDataSet|BDataSet]]

This class implements a general xml-document. It is mainly used to implement the common part of the two main {{STx}} documents: the project <code>BDataSet</code> and the workspace <code>BSTXIni</code>.

==Construction==
;<code>COBJ NEW BXMLDOC NEW|XNEW ; <var>xmlobj</var>|<var>roottag</var> [; <var>aname</var>=<var>avalue</var>; ...]</code>:
:;<var>xmlobj</var>: The name of a BXMLDoc-instance or the name of a XML-file-item.
:;<var>roottag</var>: The tag of the root element.
:;<var>aname</var>, <var>avalue</var>: The name and the value of a root element attribute.
;Result: The created and initialized instance-item or an empty string
;Description: Create a new empty XML document using the same root element tag as <var>xmldoc</var> or the specified <var>roottag</var>. During initialization the XML doctype is loaded, if it is defined in the {{STX}} configuration file, and the global item table is created. The <code>XNEW</code> variant creates or opens the XML file using the /Exclusive flag.

;<code>COBJ NEW BXMLDOC CREATE|XCREATE ; <var>filepath</var>; <var>roottag</var> [; <var>aname</var>=<var>avalue</var>; ...]</code>:
:;<var>filepath</var>: The name of the XML file.
:;<var>roottag</var>: The tag of the root element.
:;<var>aname</var>, <var>avalue</var>: The name and the value of a root element attribute.
;Result: The created and initialized instance-item or an empty string
;Description: Open an existing or create a new XML file and initialize the XML document. During initialization the XML doctype is loaded, if it is defined in the {{STX}} configuration file, and the global item table is created. If a new file is created, the root element with tag <var>roottag</var> and the specified attributes is created. The <code>XCREATE</code> variant creates or opens the XML file using the /Exclusive flag.

;<code>COBJ NEW BXMLDOC OPEN|XOPEN ; <var>filepath</var></code>:
:;<var>filepath</var>: The name of the existing XML file.
;Result: The created and initialized instance-item or an empty string
;Description: Open an existing XML file and initialize the XML document. During initialization the XML doctype is loaded if it is defined in the {{STX}} configuration file and the global item table is created.

;<code>COBJ NEW BXMLDOC LINK ; <var>xmlobj</var></code>:
:;<var>xmlobj</var>: The name of a BXMLDoc-instance.
;Result: The created and initialized instance-item or an empty string
;Description: Link the new XML document to the XML document <var>xmlobj</var> which was created and initialized in another shell. This constructor allows the sharing of XML documents between shells. This feature is f.i. used to share the global Workspace object (<code>$BSTXIni</code>) and the DataSet object (<code>$BDataSet</code>). Instances create with this method shares the file item and the global item table.

==Access control==
Because an BXMLDoc instance can be used by more than one shell, there must be a mechanism to control the access to the instance and its data content.

====Attach====
;<code><var>bxmldoc</var> Attach [ <var>iref</var> ]</code>:
:;<var>iref</var>: Element reference or xml-position.
;Result: name of file-item of the document
;Description: Lock the XML document to the calling shell. The current position is saved. If an element reference or xml-position <var>iref</var> is specified, the member <code>SELECTIREF</code> is called to select the element. If a shell calls this function for the first time, the current XML file position is saved, for all further calls, only the lock-counter is increment.
:This function should be called any time before a shell uses a shared XML document. If a shell issues more than one <code>Attach</code> function call, it must use the same number of <code>Detach</code> calls to unlock the XML document.

====Detach====
;<code><var>bxmldoc</var> Detach</code>:
;Result: 1 if the xml-file-item was changed while it was locked and 0 if not. The return value is also 0 if the xml-file-item was not unlocked by the <code>Detach</code> function.
;Description: Unlock the XML document from the shell and restores the element selected before the document was locked. If multiple <code>Attach</code> calls were used, the same number of <code>Detach</code> calls is necessary to really unlock the document.

==Query attributes==
====GetFileItem====
;<code><var>bxmldoc</var> GetFileItem</code>: Get the XML file item of the instance. The file should only be accessed directly if the XML document is locked to the shell (see [[#Access control]]). The use of the file item may be necessary to perform attribute access, element data access or special browse / search functions.
;Result: the xml-file-item

====GetDocType====
;<code><var>bxmldoc</var> GetDocType</code>: Retrieve the name of the doctype if a doctype is defined for the root element of the XML file.
;Result: name of XML doctype or empty string (if no doctype is defined for the document)

====GetPath====
;<code><var>bxmldoc</var> GetPath</code>: Retrieve the name of the XML file as stored on the hard drive. The result is empty if no file is associated with the document (this means the file exists in memory and was never loaded or saved). The function sets the <code>&path</code> member variable.
;Result: the path of the the xml-file-item

==File handling==
====Load====
;<code><var>bxmldoc</var> Load [ <var>path</var> ]</code>: Load the content of the file <var>path</var> into the xml-file-item of the document. If <var>path</var> is not specified, the current path is used (see <code>GetPath</code>).
;Result: 0 for success or errorcode

====Save====
;<code><var>bxmldoc</var> Save [ <var>path</var> ]</code>: Save the xml-file-item of the document to the file <var>path</var>. If <var>path</var> is not specified, the current path is used (see <code>GetPath</code>).
;Result: 0 for success or errorcode

====Close====
;<code><var>bxmldoc</var> Close [ <var>save</var>=0 [; <var>path</var> ] ]</code>: Close the xml-file-item and delete the instance <var>bxmldoc</var>. If the argument <var>save</var> is set to <code>1</code>, the document is saved before it is deletec (using the function call <code><var>bxmldoc</var> Save [ <var>path</var> ]</code>).
;Result: 0 for success or errorcode (returned from <code>Save</code>).
;Note: The instance <var>bxmldoc</var> is deleted, even if the function returns an errorcode.

==Global items==
This class implements some members to share items between shells. This feature is used f.i. by the application <code>Viewer1</code> to implement the '''signal copy-paste''' functions and by some other applications.

====AddGlobalItem====
;<code><var>bxmldoc</var> AddGlobalItem <var>id</var> ; <var>item</var></code>:
:;<var>id</var>: The global id-string to use for <var>item</var>.
:;<var>item</var>: The shell-item to add to the global-item-list.
;Result: 0 for success or errorcode
;Description: Add a shell item to the global item list. All items in the global item list can be linked by other shells, which have created a linked (shared) instance of this XML document. All types of items except displays, graphs and dialogs can be used.

====AttachGlobalItem====
;<code><var>bxmldoc</var> AttachGlobalItem <var>id</var> [; <var>lock</var>=0 ]</code>:
:;<var>id</var>: The id-string of the global-item.
:;<var>lock</var>: If set to <code>1</code> the returned shell-item is locked.
;Result: name of shell-item linked to the global-item or empty string
;Description: Creates a [[Programmer_Guide/Shell_Items#References_to_shell_items|linked instance (reference)]] of the global item with the specified id. If lock is set to 1 the linked instance is locked to the calling shell.

====DetachGlobalItem====
;<code><var>bxmldoc</var> DetachGlobalItem <var>item</var> [; <var>unlock</var>=0 ]</code>:
:;<var>item</var>: A shell-item linked to a global-item.
:;<var>unlock</var>: If set to <code>1</code> the <var>item</var> is unlocked before it is deleted.
;Result: no return value (void)
;Description: Deletes a linked item. If unlock is set to 1 the linked item is unlocked before it is removed.

====DeleteGlobalItem====
;<code><var>bxmldoc</var> DeleteGlobalItem <var>id</var> [; <var>delete</var>=0 ]</code>:
:;<var>id</var>: The id-string of the global-item.
:;<var>delete</var>: If set to <code>1</code> the shell-item is deleted.
;Result: 0 for success or errorcode
;Description: Remove the global-item with id-string <var>id</var>from the global-item-list. If <var>delete</var> is set to 1, the item is deleted after removing from the list. An item can only be removed by the same shell that adds it to the list.

==Element manipulation==
====AddElement====
;<code><var>bxmldoc</var> AddElement <var>tag</var> ; <var>where</var> ; <var>goto</var> ; <var>attr</var>=<var>value</var> ; ...</code>:
:;<var>tag</var>: The element tag.
:;<var>where</var>: Controls where the element should be created: create the element on the current level (<code>CURRENT</code> or <code>0</code>) or as a child of the current element (<code>CHILD</code> or <code>1</code>).
:;<var>goto</var>: Controls how the current position should be changed after the new element is created: select the created element (<code>SELECT</code> or <code>1</code>), step into the created element (<code>INSIDE</code> or <code>2</code>) or do not change the selected element (<code>HOLD</code> or <code>0</code>).
:;<var>attr</var>=<var>value</var>: Name(s) and value(s) of attributes to be assigned to the new element. All <var>name</var> arguments must specifiy a valid XML attribute name.
;Result: 0 for success or errorcode
;Description: Add a new element with the specified tag to the XML document. The element is added on the same level as the current element (<var>where</var>=<code>CURRENT</code>) or as child element (<var>where</var>=<code>CHILD</code>) of the current element. The attribute assignment <var>attr</var>=<var>value</var> are used to initialize the new elements attributes. If the function returns <code>0</code> the new element is created and the position is changed according to the argument <var>goto</var>, otherwise the document content and the current element position are not changed. To assign the attributes to the element the function call <code><var>bxmldoc</var> SetElement * ; <var>attr</var>=<var>value</var> ; ...</code> is used.

====SetElement====
;<code><var>bxmldoc</var> SetElement <var>pos</var> ; <var>attrarg</var> ; ... </code>:
:;<var>pos</var>: The xml-position or element reference of the element to be changed. The value <code>*</code> :;attrarg: Defines the name and the value of the attribute(s) to be set.
::;<var>aname</var>=<var>avalue</value>: Assign the value <var>avalue</var> to the attribute <var>aname</var>. The <var>aname</var> must be a valid xml-attribute name. If <var>avalue</var> is empty, the attribute <var>aname</var> is deleted.
::;<var>attrtab</var>: The name of a simple-table containing one attribute setting <code> <var>aname</var> = <var>avalue</var> </code> per entry. This table gets deleted after processing!
;Result: 0 for success or errorcode.
;Description: Set the attributes of a specific element. The current position is not changed by this function. An error is returned, if no element is found at the specified position <var>pos</var>, or an attribute assignment fails. If an error is returned, some attributes of the element may be changed! To remove an attribute, an empty attribute value can be used (<code> <var>aname</var>=; </code>).

====GetElement====
;<code><var>bxmldoc</var> GetElement <var>pos</var> ; <var>info</var> ; aname1 ; ... </code>:
:;<var>pos</var>: The xml-position or element reference of the element.The value <code>*</code> can be used for the element at the current position.
:;<var>info</var>:
::{|class="einrahmen"
|<code>0</code> ||get attribute values ||result = <var>avalue1; ...</var>
|-
|<code>1</code> ||get element tag and attribute values ||:result = <var>tag; avalue1; ...</var>
|-
|<code>2</code> ||get element tag, number of children and attribute values ||result = <var>tag; nchildren; avalue1; ...</var>
|}
:;<var>aname1</var>, ...: list of attribute names
;Result: empty string (element not found) or a string containing selected informations (see argument <var>info</var>)
;Description: Retrieve general informations about the specified element and/or element attribute values. The current element position is not changed by this function.

====DeleteElement====
;<code><var>bxmldoc</var> DeleteElement <var>pos</var></code>:
:;<var>pos</var>: The xml-position or element reference of the element.The value <code>*</code> can be used for the element at the current position.
;Result: 0 for success (deleted) or 1 for error
;Description: Delete the selected element. The current element position is only changed, if the current element was deleted.

==Data manipulation==
====GetDataType====
;<code><var>bxmldoc</var> GetDataType [ <var>tag</var> ]</code>:
:;<var>tag</var>: The element tag to be tested; if not specified or set to <code>*</code> the tag of the current element is used.
;Result: The data type defined in the doctype or the element tag if no data type is defined for the specified tag.
;Description: Returns type of date stored in elements with the specified tag. This function is used by <code>LoadData</code> and <code>SaveData</code> to retrieve data type information. In the current doctype-version only the types <code>TABLE</code> and '<code>XTABLE tabledef</code>' are supported.

====CreateXTable====
;<code><var>bxmldoc</var> CreateXTable <var>typedef</var> [ <var>fname1</var> ... ]</code>:
:;<var>typedef</var>: The name (ID) of the <code>XTableTypeDef</code> element.
:;<var>fname1</var>, ...: The name of the extra fields to be added to the extended table.
;Result: The name of the new and initialized extended table-item or an empty string.
;Description: Creates an extended table using the specified <var>typedef</var> or retrieves data type information for the current element (if no <var>typedef</var> is specified). If extra fields are specified and the <var>typedef</var> contains a definition statement for the extra fields, they are added to the table.
;Note: A <var>typedef</var> for an extended table is defined in an xml element with the tag <code>XTableTypeDef</code> with the attribute <code>ID="<var>typedef</var>"</code>. This element must be defined in the definition-section of the {{STX}} configuration file or on level of the current element.

====LoadData====
;<code><var>bxmldoc</var> LoadData</code>:
;Result: The name of the shell-item (table) containing the loaded data or an empty string.
;Description: Loads the data stored in the current element. The item for the data is created in the function and returned to the caller. Data type information is retrieved by calling <code>GetDataType</code> and <code>CreateXTable</code>.
;Example: Load data from the {{STX}} configuration file at the IRef <code>/Definitions/DataSet/Methods</code>.
<pre>
...
$bstxini attach
$bstxini selectiref '/Definitions/DataSet/Methods'
if '$result' == 0 #data := $bstxini loaddata
$bstxini detach
...
</pre>

====SaveData====
;<code><var>bxmldoc</var> SaveData <var>item</var> [ ; <var>del</var>=0 ]</code>:
:;<var>item</var>: Shell-item (table) containing the data to be saved.
:;<var>del</var>: If set to <code>1</code> the shell-item is deleted after saving
;Result: 0 for success or errorcode
;Description:Save <var>item</var> into the data section of the current element. The data format is selected by calling <code>GetDataType</code>. The item is only saved, if it is valid for the data type. If <var>item</var> is saved successful and <var>del</var> is set to <code>1</code>, <var>item</var> is deleted.

==IRef functions==
* This group of functions was originally developed, to deal with unique references to elements of type '''Set''' with the special unique id attribute '''ID'''. This implementation was modified, because the attribute '''ID''' is now used as a unique identifier for elements of any type.
* A string in the format ''' /''id1''/''id2''/.../''idn'' ''' is called '''IRef''' (for "(unique) Internal REFerence"). This string is interpreted as follows:
** ''id1'' is the unique element id (value of attribute '''ID''') on the root-level
** ''id2'' is the unique element id inside the element selected by ''id1''
** and so on

====SelectIRef====
{{/SelectIRef}}

====FormatIRef====
;<code><var>bxmldoc</var> FormatIRef [ <var>pos</var>=* ]</code>
:;<var>pos</var>: The XML element position or <code>*</code> for the current element.
;Result: A reference (IRef) to the selected element or an empty string.
;Description:Generates the internal XML reference string for the specified element at position <var>pos</var>. This string can only be created if all elements in the path except the root element have an ID attribute.
;see also: commands [[Programmer_Guide/Command_Reference/IREF|IREF]] and [[Programmer_Guide/Command_Reference/POSITION|POSITION]]

====UniqueID====
;<code><var>bxmldoc</var> UniqueID [ <var>pos</var>=* ; <var>id</var>=* ; <var>ext</var>=0 ; <var>start</var>=-1 ; <var>digits</var>=0 ]</code>
:;<var>pos</var>: The position/reference of the parent element (<code>*</code> = current element)
:;<var>id</var>: The fixed part of the id-string. If an asterisk is specified, the string "Auto" is used.
:;<var>ext</var>: Use the counter in the id-extension (<code>yes</code> or <code>1</code>) or append the counter directly to the id-string (<code>no</code> or <code>0</code>).
;<var>start</var>: The counter start value. Use <code>-1</code> to test <var>id</var> without the counter suffix: if <var>id</var> is unique it is returned without any modifications.
;<var>digits</var>: The number of digits. Use a value outside the range <code>2..9</code> to disable zero padding. If e.g. <var>digits</var> equals 3, the generated counter values will be <code>000</code>, <code>001</code>, <code>002</code>, etc.
;Result: A unique id string (unique on the selected level) or an empty string on failure.
;Description: Generate a unique id for the current level or inside the specified parent element. If <var>id</var> is unique, then <var>id</var> is returned. Otherwise, the counter is appended to <var>id</var> in the requested format.

=="Set" functions==
* This group of functions was originally developed, to deal with elements of type '''Set''' with the special unique id attribute '''ID'''. This implementation was modified, because the attribute '''ID''' is now used as a unique identifier for elements of any type.

===ListSetElements===
<code><var>bxmldoc</var> ListSetElements [ <var>table</var>=* ; <var>iref</var>=* ]</code>
:;<var>table</var>: simple table-item to store result; if <code>*</code> is used a new table is created
:;<var>iref</var>: reference of the set-element containing the elements to be listed; use <code>*</code> for the current level
;Result: the table-item containing the result (list of id's) or an empty string
;Description: Lists all element id's on the current level (<var>iref</var>=*) or inside the specified set-element. If a table-item is passed, it is emptied before the id list is stored, otherwise a new table is created.

===FindSetElement===
<code><var>bxmldoc</var> FindSetElement [ <var>tag</var>=* ; <var>id</var>=* ; <var>iref</var>=* ]</code>
:;<var>tag</var>: element tag; use <code>*</code> for all elements
:;<var>id</var>: value of ID attribute; wildcards are possible
:;<var>iref</var>: reference of the set-element to be searched; use <code>*</code> for the current level
;Result: 0 if the element was found and 1 if not
;Description: Find the (first element) with the specified <var>tag</var> (* = search all element tags) and <var>id</var>. For the matching of tag and id a case-sensitive comparison is used! If no <var>iref</var> is specified, the current level is searched from the beginning, otherwise the search is performed inside the specified set.

===AddSetElement===
<code><var>bxmldoc</var> AddSetElement [ <var>tag</var> ; <var>id</var> ; <var>iref</var>=* ]</code>
:;<var>tag</var>: element tag
:;<var>id</var>: element id (value of ID attribute)
:;<var>iref</var>: reference of the set-element where the element should be created; use <code>*</code> for the current level
;Result: 0 if the element was selected/created and 1 if not
;Description: Create a new element with specified tag and id in the set selected by <var>iref</var>. If the specified set does not exist, it will be created. If a set must be created, for each set element the tag <code>SET</code> is used by default, but it is possible to specify another tag in the argument <code>ref</code> with the format: <code>/setid/.../settag:setid/.../</code>. If the element is created, the new element is selected, otherwise the position is not changed. If the element exists already, it is selected but not changed.

===LoadSetElement===
<code><var>bxmldoc</var> LoadSetElement [ <var>tag</var>=* ; <var>id</var>=* ; <var>iref</var>=* ]</code>
;Result: The loaded data object (table-item, value returned from <code>LoadData</code>) or an empty string.
:Description: This function uses the call <code><var>bxmldoc</var> FindSetElement <var>tag</var>;<var>id</var>;<var>iref</var></code> to select the element and the call <code><var>bxmldoc</var> LoadData</var></code> to load the content of the selected element. If element selection or loading data failes (error), the file position is not changed, otherwise (success) the loaded element is selected.

===SaveSetElement===
<code><var>bxmldoc</var> SaveSetElement [ <var>item</var> ; <var>del</var>=0 ; <var>tag</var>=* ; <var>id</var>=* ; <var>iref</var>=* ]</code>
;Result: 0 if the data item was saved successful and 1 otherwise
:Description: This function uses the call <code><var>bxmldoc</var> AddSetElement <var>tag</var>;<var>id</var>;<var>iref</var></code> to select or create the element and the call <code><var>bxmldoc</var> SaveData</var></code> to save the item into the element. If element selection or save operation failes (error), the file position is not changed, otherwise (success) the created/updated element is selected.

===DeleteSetElement===
<code><var>bxmldoc</var> DeleteSetElement [ <var>tag</var>=* ; <var>id</var>=* ; <var>iref</var>=* ]</code>
;Result: 0 if the element was deleted and 1 otherwise
:Description: This function calls <code><var>bxmldoc</var> FindSetElement <var>tag</var>;<var>id</var>;<var>iref</var></code> to select an element and than deletes the selected element.

==Misc==

====SavePos====
<code><var>bxmldoc</var> SavePos [ <var>delpos</var>=* ]</code>
;Result: current xml position id or empty string if position can not be saved (no element selected)
;Description: Returns the xml position id of the currently selected element. If the xmp position id <var>delpos</var> is not equal <code>*</code>, this position is closed (reset).
;See Also: [[Programmer_Guide/Command_Reference/POSITION|POSITION]]

====ResetPos====
<code><var>bxmldoc</var> ResetPos <var>pos</var>=* [ ; * ; <var>delemem</var>=0 ] </code>
;Result: always 0
;Description: Restore the the xml position id <var>pos</var>. If <var>delelem</var> equals 1 the element at the restored position is deleted.

<code><var>bxmldoc</var> ResetPos <var>table</var>=* [ ; <var>row</var>=* ; <var>delemem</var>=0 ; <var>deltable</var>=0 ] </code>
;Result: always 0
;Description: Restore all xml positions stored in <var>table[*,row]</var>. If <var>table</var> is a simple table, the argument <var>row</var> is ignored.
::* If <var>delelem</var> equals <code>1</code> the elements at the restored positions are deleted
::* If <var>deltable</var> equals <code>1</code> the <var>table</var> is deleted
::* This function can be used to reset positions returned by [[Programmer_Guide/Shell_Items/File/SET_FILE#Find_2|FIND]] or [[Programmer_Guide/Shell_Items/File/SET_FILE#EXTRACTTABLE|EXTRACTTABLE]] commands.

====ExtractSubDoc====
;<code><var>bxmldoc</var> ExtractSubDoc <var>file</var> ; <var>posattr</var> ; <var>tag1</var> ; <var>sub1</var> ; <var>tag2</var> ; <var>sub2</var> ; ...</code>:
:;<var>file</var>: The target XML file item for extracted elements.
:;<var>posattr</var>: The name of element attribute for positions of original elements.
:;<var>tagX</var>: The element tags to be extracted.
:;<var>subX</var>: Flag determining if child elements of <var>tagX</var> should be scanned scan too (yes=<code>1</code>, no=<code>0</code>).
;Result: none (void), <var>file</var> contains extracted elemenents
;Description: Extract the elements with the specified tags from the document and copy them into the specified target <var>file</var>. The original tree structure is retained. The content of an element with <var>tagX</var> is only scanned if the corresponding <var>subX</var> argument is set to <code>1</code> (or <code>yes</code>). The element data are not extracted. If <var>posattr</var> is not set to '<code>*</code>' the position string of the original element is stored in the attribute <code>posattr</code> of the copied (extracted) element. If a XML doctype is defined for the original document it is applied to the target file. The element extraction is performed with the command [[Programmer_Guide/Shell_Items/File/SET_FILE#EXTRACTFILE|EXTRACTFILE]].
:Note: If the positions of the original elements are saved, the function <code>ResetSubDoc</code> must be used to reset the positions before the target file is deleted.

====ResetSubDoc====
;<code><var>bxmldoc</var> ResetSubDoc <var>file</var> ; <var>posattr</var></code>:
:;<var>file</var>: A XML containing extracted elements.
:;<var>posattr</var>: The name of element attribute for positions of original elements.
;Result: none
;Description: Reset the extracted file and all saved positions. This function must be called for all XML files created with EXTRACTSUBDOC.

====DialogSelectElement====
<code><var>bxmldoc</var> DialogSelectElement <var>title</var> ; <var>selmode</var> ; <var>outmode</var> ; <var>tag1</var> ; <var>sub1</var> ; <var>tagX</var> ; <var>subX</var> ; ...</code>
:;<var>title</var>: The dialog window caption.
:;<var>selmode</var>: The selection mode {<code>SINGLE</code>|<code>MULTIMPLE</code>}.
:;<var>outmode</var>: The output mode {<code>POSITION</code>|<code>IREF</code>}
:;<var>tagX, subX</var>: The tag names and subtree scan flags which are passed to function <code>ExtractSubDoc</code>
;Result: An empty string for error/cancel or one of the values listed in the table below:
::{|class="einrahmen"
!selmode !!outmode !!result
|-
|SINGLE
|POSITION
|position string of selected element
|-
|SINGLE
|IREF
|internal reference of selected element
|-
|MULTIPLE
|POSITION
|simple table containing position strings of selected elements
|-
|MULTIPLE
|IREF
|simple table containing internal references of selected elements
|}
;Description: Extracts a sub-document using the function <code>ExtractSubDoc</code> and displays the sub-document tree in a dialog where the user can select one or more elements (depending on <var>selmode</var>). Depending on <var>outmode</var>, either the position/s or the internal reference/s of the selected element/s is/are returned. If <var>outmode</var> is set to <code>POSITION</code> the user must cleanup the positions when the element processing is finished.
;Examples: The following code displays a dialog with all audio files and sets in the current DataSet and retrieves the audio set information for the file chosen by the user (if any).

<pre>
#pos := $BDataSet DialogSelectElement title ; single ; position ; Set ; 1 ; AFile ; 0
if '$#pos' != '' then
readstr '$($BDataSet GetASetInfo $#pos soundfile)' #sf';'#setId';'#srate';'#ch';'#fPath
if '$#fPath' != '' #file := $#fPath
if '$#sRate' != '' #sr := $#srate
#iref := $($BDataSet FormatIRef $#pos)
#result := '$#file ; $#sr ; $#iref ; $#ch'
end
</pre>

====Table2VarSpace====
;<code><var>bxmldoc</var> Table2VarSpace <var>table ; del ; prefix ; inst</var></code>:
:;<var>table</var>: name of table containing variable settings
:;<var>del</var>: delete table after conversion (<code>0</code>=yes, <code>1</code>=no)
:;<var>prefix</var>: prefix string for variable names
:;<var>inst</var>: name of an instance item (optional);
;Result: none
;Description: Converts the variable assignments (<code>varname = varvalue</code>) stored in the table to variables. For each entry of the table a variable named <var>prefix</var><code>varname</code> is created and the value <code>varvalue</code> is assigned. If an instance item <var>inst</var> is specified, the variables are stored as member variables of the instance, otherwise the variable space used to store the variables depends on the prefix (e.g. if prefix equals '@', the variables are stored as global variables). If the argument <var>del</var> is set to <code>1</code> the table is deleted after conversion. See <code>VarSpace2Table</code> for conversion in the other direction.

====VarSpace2Table====
;<code><var>bxmldoc</var> VarSpace2Table table ; prefix; inst</code>:
:;<var>table</var>: name of table containing variable settings
:;<var>prefix</var>: prefix string for variable names
:;<var>inst</var>: name of an instance item (optional);
;Result: none
;Description: Convert variables to table. Each entry of <var>table</var> must define one variable in the format <code>varname = varvalue</code>. The <code>varvalue</code> is replaced by the current value of the variable <var>prefix</var><code>varname</code>. If an instance item <var>inst</var> is specified the variables are read from the instance item, otherwise the variables must be stored in the global or the shell variable space. See VarSpace2Table for conversion in the other direction.

====AFun====
;<code><var>bxmldoc</var> AFun <var>memberFunctionName</var> [ ; <var>memberFunctionArgs</var> ]</code>:
;Result: result returned from member function call
;Description: This function attaches the XML document to the calling shell, executes the member function call <code><var>bxmldoc</var> <var>memberFunctionName</var> [ <var>memberFunctionArgs</var> ]</code> and detaches the XML document.

Programmer Guide/Macro Library/BXMLDoc/SelectIRef

2019-10-01T08:38:25Z

Jw:

;<code><var>bxmldoc</var> SelectIRef [ <var>pos</var>=* ; <var>in</var>=0 ]</code>:
:;<var>pos</var>: An (unique internal) element reference, a xml-position or the character <code>*</code> for the current element.
:;<var>in</var>: Go into the selected element (<code>1</code>) or not (<code>0</code>).
;Result: 0 for success or an errorcode
;Description: Selects the element referred to by <var>pos</var>. If the element is selected successfully and <var>in</var> equals <code>1</code>, the child element level of the element is selected. You can create an IRef for an element with the member function <code>[[Programmer_Guide/Macro_Library/BXMLDoc#FormatIRef|FormatIRef]]</code>.
;see also: commands [[Programmer_Guide/Command_Reference/IREF|IREF]] and [[Programmer_Guide/Command_Reference/POSITION|POSITION]]

Programmer Guide/Macro Library/BXMLDoc/SelectIRef

2019-10-01T08:37:44Z

Jw:

;<code><var>bxmldoc</var> SelectIRef [ <var>pos</var>=* ; <var>in</var>=0 ]</code>:
:;<var>pos</var>: An (unique internal) element reference, a xml-position or the character <code>*</code> for the current element.
:;<var>in</var>: Go into the selected element (<code>1</code>) or not (<code>0</code>).
;Result: 0 for success or an errorcode
;Description: Selects the element referred to by <var>pos</var>. A reference a file item position string, an internal XML reference or the value * (= current element) can be used. If the element is selected successfully and <var>in</var> equals <code>1</code>, the child element level of the element is selected. You can create an IRef for an element with the member function <code>[[Programmer_Guide/Macro_Library/BXMLDoc#FormatIRef|FormatIRef]]</code>.
;see also: commands [[Programmer_Guide/Command_Reference/IREF|IREF]] and [[Programmer_Guide/Command_Reference/POSITION|POSITION]]

Programmer Guide/Macro Library/BXMLDoc/SelectIRef

2019-10-01T08:26:36Z

Jw:

;<code><var>bxmldoc</var> SelectIRef [ <var>pos</var>=* ; <var>in</var>=0 ]</code>:
:;<var>pos</var>: An (unique internal) element reference, a xml-position or the character <code>*</code> for the current element.
:;<var>in</var>: Go into the selected element (<code>1</code>) or not (<code>0</code>).
;Result: 0 for success or an errorcode
;Description: Selects the element referred to by <var>pos</var>. A reference a file item position string, an internal XML reference or the value * (= current element) can be used. If the element is selected successful and <var>in</var> equals <code>1</code> the child element level of the element is selected. You can create an IRef for an element with the member function <code>[[Programmer_Guide/Macro_Library/BXMLDoc#FormatIRef|FormatIRef]]</code>.
;see also: commands [[Programmer_Guide/Command_Reference/IREF|IREF]] and [[Programmer_Guide/Command_Reference/POSITION|POSITION]]

User Guide/Tutorials

2019-09-30T07:04:08Z

Jw:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{User Guide}}
Here are a few tutorials to get you started with {{STX}}. If you have any feedback, or need help with a particular task not covered, please get in touch (stxsupport@kfs.oeaw.ac.at).

===Simple===
* [[User_Guide/Tutorials/Analysing_a_sound_file|Analysing a sound file]]
* [[User_Guide/Tutorials/Opening_the_samples.stxpr_project|Opening the sample project]]
* [[User_Guide/Tutorials/Playing_a_sound_file|Play a sound file]]
* [[User_Guide/Tutorials/Running_an_application|Running an application]]
* [[User_Guide/Tutorials/Setting_the_default_application|Setting the default application]]
* [[User_Guide/Tutorials/Zooming_in_a_Viewer|Zooming in a viewer]]

User Guide/Tutorials/Opening the samples.stxpr project

2019-09-30T07:03:29Z

Jw:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{UG_Tutorial}}
{{STX}} includes a sample project which you can open when {{STX}} starts. This [[User_Guide/Project|project]] contains examples of [[User_Guide/Project/Segment|segments]], sequences, parameters and segment lists, and is used in examples throughout the documentation. The project is called ''samples.stxpr'' and is located in the directory <code>data</code> in the {{STX}} installation directory.

If the samples.stxpr is not open, please do the following.

====Start {{STX}}====

If {{STX}} is not running then start {{STX}}. The Workspace should appear (if not, please see [[User Guide/Tutorials/Setting the default application|Setting the default application]]).

====Select the Open Project dialog====

Choose the Workspace File menu item Project->Open.

[[File:ws_menu_file_dataset_open.png]]

====Find the samples.stxpr project====

The sample project is located in the directory ''data'' in the {{STX}} installation directory. Navigate into the directory, select the samples.stxpr file and press OK. Save your previous project if asked.

[[File:ws_dialog_open_dataset.png]]

User Guide/Tutorials/Analysing a sound file

2019-09-30T07:01:15Z

Jw: /* Analysing a sample sound file */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{UG_Tutorial}}
==Extended Workspace Mode==

The basic steps needed to analyse a sound file in {{STX}} in the [[User_Guide/Workspace#Compact_and_Extended_Mode|extended workspace mode]] are as follows:
*Select the sound file or segment you wish to analyse.
*Select the desired analysis profile from the Signal Analysis & Display branch of the [[User_Guide/Workspace/Application_and_Setup_Tree|Application & Setup Tree tree]].
*Press the run button [[File:resource_run.png]]

====Analysing a sample sound file====

Assuming that we want to display a spectrogram of the <code>Samples1.wav</code> we will do the following:

* [[User_Guide/Tutorials/Opening_the_samples.stxpr_project|Open the sample {{STX}} project]], if it is not already open.
*Select the <code>Samples1.wav</code> file in the Overview.
[[File:5660.gif]]

*Select <code>Signal.All</code> segment in the Detail
[[File:5661.gif]]

*Select a Spectrogram & Parameters Viewer profile from the Application & Setup Tree tree. We will use the FFT_22Hz profile, which is preconfigured to display a spectrogram and waveform of the selected signal using a

Taking the example sound file <code>Samples1.wav</code> from the sample project, we will analyse it using the FFT_22HZ Spectrogram & Parameters Viewer profile.

User Guide/Tutorials/Analysing a sound file

2019-09-30T07:00:04Z

Jw:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{UG_Tutorial}}
==Extended Workspace Mode==

The basic steps needed to analyse a sound file in {{STX}} in the [[User_Guide/Workspace#Compact_and_Extended_Mode|extended workspace mode]] are as follows:
*Select the sound file or segment you wish to analyse.
*Select the desired analysis profile from the Signal Analysis & Display branch of the [[User_Guide/Workspace/Application_and_Setup_Tree|Application & Setup Tree tree]].
*Press the run button [[File:resource_run.png]]

====Analysing a sample sound file====

Assuming that we want to display a spectrogram of the <code>Samples1.wav</code> we will do the following:

*[[User Guide/Tutorials/Opening the samples.xml DataSet|Open the ]][[User Guide/Tutorials/Opening the samples.xml DataSet|samples.xml]][[User Guide/Tutorials/Opening the samples.xml DataSet| DataSet]] if it is not already open.
*Select the <code>Samples1.wav</code> file in the Overview.
[[File:5660.gif]]

*Select <code>Signal.All</code> segment in the Detail
[[File:5661.gif]]

*Select a Spectrogram & Parameters Viewer profile from the Application & Setup Tree tree. We will use the FFT_22Hz profile, which is preconfigured to display a spectrogram and waveform of the selected signal using a

Taking the example sound file <code>Samples1.wav</code> from the sample project, we will analyse it using the FFT_22HZ Spectrogram & Parameters Viewer profile.

User Guide/Tutorials/Analysing a sound file

2019-09-30T06:59:26Z

Jw:

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{UG_Tutorial}}

==Extended Workspace Mode==

The basic steps needed to analyse a sound file in {{STX}} in the [[User_Guide/Workspace#Compact_and_Extended_Mode|extended workspace mode]] are as follows:
*Select the sound file or segment you wish to analyse.
*Select the desired analysis profile from the Signal Analysis & Display branch of the [[User_Guide/Workspace/Application_and_Setup_Tree|Application & Setup Tree tree]].
*Press the run button [[File:resource_run.png]]

====Analysing a sample sound file====

Assuming that we want to display a spectrogram of the <code>Samples1.wav</code> we will do the following:

*[[User Guide/Tutorials/Opening the samples.xml DataSet|Open the ]][[User Guide/Tutorials/Opening the samples.xml DataSet|samples.xml]][[User Guide/Tutorials/Opening the samples.xml DataSet| DataSet]] if it is not already open.
*Select the <code>Samples1.wav</code> file in the Overview.
[[File:5660.gif]]

*Select <code>Signal.All</code> segment in the Detail
[[File:5661.gif]]

*Select a Spectrogram & Parameters Viewer profile from the Application & Setup Tree tree. We will use the FFT_22Hz profile, which is preconfigured to display a spectrogram and waveform of the selected signal using a

Taking the example sound file <code>Samples1.wav</code> from the sample project, we will analyse it using the FFT_22HZ Spectrogram & Parameters Viewer profile.

User Guide/Workspace/Extended Mode

2019-09-30T06:56:59Z

Jw:

[[File:ws_schematics.png|600px]]

The Workspace ''extended mode'' makes all of {{STX}}'s functionality available to the user. For a simpler Workspace, see the [[User_Guide/Workspace|compact mode]].

The Workspace is divided into the following four areas:

* [[User_Guide/Workspace/Application_and_Setup_Tree|The Application & Setup Tree]]. The Application & Setup Tree provides access to the installed applications (e.g. Recorder, FindFile, Real-Time Analyser), the profiles used for signal analysis (Signal Analysis & Display), the analysis parameter export dialog, the digital signal processing functions (Signal Processing), general S_TOOLS-STx settings like color schemes, audio settings etc. (Options), and links to frequently used scripts.

* [[User Guide/Workspace/The Workspace Overview|The Overview]] displays the basic elements in the current [[User Guide/Project|project]], e.g. sound files and sequences.

* [[User Guide/Workspace/Detail|The Detail]] displays the metadata in the currently selected element in the Overview. Depending on which [[User Guide/Workspace/Detail/Detail View|view]] is selected, you can see the existing segments, parameters or signal definitions.

* [[User_Guide/The Script_Controller|The Script Controller]] can be used to edit and run {{Stx}} macros or run the {{STX}} console. For a guide to programming {{Stx}} macros, see the [[Programmer_Guide|Programmer Guide]].

==Buttons==

{|
|-
|[[File:resource_script_edit.png]]
|Edit the Script Controller script file using the application associated with *.stx or *.stx files.
|-
|[[File:resource_script_test.png]]
|Test the Script Controller script.
|-
|[[File:resource_script_run.png]]
|Run the Script Controller script.
|-
|[[File:resource_run.png]]
|<div id="button_run"></div>Run selected profile with selected Detail element.
|-
|[[File:resource_setup.png]]
|Open the settings for the selected profile with the option to run with selected Detail element.
|-
|[[File:resource_edit.png]]
|Edit the properties for the selected element in the Detail or the Overview (whichever is active <nowiki>-</nowiki> default: Detail). Do nothing if no element is selected.
|-
|[[File:resource_attribute.png]]
|Search for [[User Guide/Workspace/Detail/Search for Element Attributes|element attributes]].
|-
|[[File:resource_refresh.png]]
|Force an update to the Workspace window.
|-
|[[File:resource_new.png]]
|Add an element to the selected element in the Detail or the Overview (whichever is active <nowiki>-</nowiki> default: Detail). The type of element you can add depends on the context (e.g. you cannot add a sound file to a sound file).
|-
|[[File:resource_dosave.png]]
|Save the Workspace settings and the Project file to disk.
|-
|[[File:resource_toolbox.png]]
|Open the Toolbox.
|}

==Channel Mapping==

{{STX}} can map individual channels from wave files with more than two channels to the stereo channels available on a Windows system.

[[File:ws_channel_mapping.png]]

==Hotkeys==

There are many [[User_Guide/Workspace/Workspace_Hotkeys|hotkeys]] available in the Workspace.

==Drag & Drop Support==

You can drag and drop a number of different file types into the Workspace window:

*Project files
*{{STX}} INI files
*Sound files
*Scripts
You can also drag and drop these files onto the Log window.

==Title==

The Workspace title shows the path to the current [[User_Guide/Workspace/Application_and_Setup_Tree/Workspace_File|Workspace]] file and the current [[User_Guide/Project|Project]] file.

[[File:ws_title.png]]

==Wildcards==

{{STX}} supports the use of wildcards in many dialog boxes. [[User_Guide/Workspace/Wildcards|Here]] is an explanation of the syntax.

User Guide/Workspace

2019-09-30T06:56:16Z

Jw: /* Modes */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{UG_Workspace}}
The Workspace is the default application in {{STX}}. The Workspace is where you organise your project's sound files and run your analyses.

[[File:Stx ug workspace compact overview.png|600px]]

__TOC__

When you open a sound file in {{STX}}, it is added to your project file. The sound files in your project are listed in the ''Files'' list:

[[File:Stx_ug_workspace_compact_overview_files.png]]

When you select a sound file in the Files list, any segments the sound file contains are displayed in the segment detail view:

[[File:Stx_ug_workspace_compact_overview_detail.png]]

When you want to analyse part of your sound file, you select a segment of the sound file and then choose either ''Start'' from the ''Analysis'' or ''Transcription'' controls. This will open a new window with the relevant analysis.

===Analysis===

The ''Analysis'' section will by default display a narrowband spectrogram with formants tracks as well as an F0, RMS and wave graph of the selected segment.

[[File:stx_ug_workspace_compact_analysis.png]]

You can enable/disable graphs here, before starting the analysis. If you need other features, please use the [[User_Guide/Spectrogram_and_Parameter_Viewer/Settings_Dialog|''Setup'']] dialog.

===Transcription===

The ''Transcription'' section of the workspace lets you start the [[User_Guide/SPExL/Transcription_Script|Transcription]] application. This application was specifically designed for transcribing.

[[File:stx_ug_workspace_compact_transcription.png]]

You can change some basic settings here:
;view:Display the sound file as a waveform or both a waveform and a spectrogram (see [[User_Guide/SPExL/Transcription_Script#Spectrogram_.2F_Waveform_Views|here]] for more details).
;block length:If the sound file is long, you can view it in blocks to increase loading speed.
;step size:When scrolling through blocks, the next block will overlap by this value with the last block.
;Start:Start the Transcription application.
;Setup:Open the setup dialog for further settings.

===Compact and Extended Mode===

By default, the Workspace starts in the ''Compact Mode''. This is a simplified GUI which enables quick access to the most frequently used functions of STx. The Workspace can also be run in ''[[/Extended_Mode|Extended Mode]]'', which exposes all STx functionality to the user. To change mode, choose either <samp>Compact</samp> or <samp>Extended</samp> from the <samp>File->Select Workspace Mode</samp> menu.

The ''Compact'' mode was added to {{STX}} in version 5.0.

===Extras===

The ''Extras'' menu contains some extra functionality, you might like to quickly access from the ''Compact'' mode.
;Start Realtime Spectrum Analyser:Analyse an audio input signal in real-time.
;Start Signal Recorder:Record a sound file from any audio input.
;Start Signal Plot and Edit:Plot a waveform of the selected segment. This is also a basic wave editor.
;Export Parameters:[[User_Guide/Workspace/Application_and_Setup_Tree/Parameter_Processing#Parameter_Export|Export previously calculated parameters]].
;Copy Parameters to Clipboard:Copy the selected segment's parameters to the clipboard.
;Import Segments from Wordlist-File:Import a transcription from a file. One sentence per line. This estimates the position of the segments based on word length.
;Import Segments from Textgrid-File:[[User_Guide/Toolbox/Import_PRAAT_TextGrid|Import a TextGrid file into the selected sound file]].
;Segment automatically using runMAUSBasic:Segment the selected sound file using the WebMAUS interface [[User_Guide/Toolbox/runMAUSBasicDlg|runMAUSBasic]].
;Export Segments to Sound Files: Export each of the selected segments to an individual sound file.
;Anonymize Signals and Transcriptions:[[User_Guide/Scripts/Anonymize.sts|Anonymize the selected sound file's segments based on a segment attribute]].
;Signal Up/Down Sampling:Upsample or downsample a sound file.
;Show Scripts Dialog:Display the [[User_Guide/The_Script_Controller|scripts dialog]] in the Workspace to load and run scripts.
;Show Find/Select Dialog:Display the [[User_Guide/Workspace_/Detail_Find_Select|Find/Select dialog]] in the Workspace to search for segments contain the search term.
;General Settings:Open the [[User_Guide/Workspace/Application_and_Setup_Tree/Options/General_Settings|general settings dialog]].

User Guide

2019-09-30T06:53:01Z

Jw: /* Tutorials */

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{User Guide}}
==Organise your sound files==

{{STX}} can play, analyse, annotate and modify wave files. The main application - the [[User_Guide/Workspace|Workspace]] - is where you load your sound files and start your analysis from. Your sound files are organised in a [[User_Guide/Project|project]] file. You can use the [[User_Guide/FindFile|FindFile]] application to search for wave files on disk and import them into {{STX}}.

==Analyse a Signal==

There are a number of applications for analysing signals in {{STX}}.

* [[User_Guide/Real_Time_Analyser|Real-Time Analyser]] - analyse the current sound input as a spectrum, wave or spectrogram graph
* [[User Guide/Waveform and Segmentation Viewer|Waveform and Segmentation Viewer]] - useful for segmenting signals
* [[User Guide/Spectrogram and Parameter Viewer|Spectrogram and Parameter Viewer]] - calculate, edit and extract parameters from the signal. Segmentation is also easy here.
* [[User Guide/Spectrum Viewer|Spectrum Viewer]] - average the spectra of a signal segment.
* [[User Guide/Transcription Script|Transcription]] - an application specifically designed for segmentation and transcription.

==Record a Signal==

The [[User Guide/Recorder|Recorder]] can be used to save an input stream to disk and whilst segmenting it on the fly.

==Command-Line Parameters==

There is a minimal set of [[User Guide/Command-Line Parameters|command line parameters]] which can be passed to {{STX}}.

==Concepts and Terminology==

{{STX}} uses some concepts and terminology which might benefit from some explanation. See [[User Guide/Concepts and Terminology|Concepts and Terminology]].

==Tutorials==

There are a few [[User Guide/Tutorials|tutorials available]].

* [[User_Guide/Tutorials/Analysing_a_sound_file|Analysing a sound file]]
* [[User_Guide/Tutorials/Opening_the_samples.stxpr_project|Opening the sample project]]
* [[User_Guide/Tutorials/Playing_a_sound_file|Play a sound file]]
* [[User_Guide/Tutorials/Running_an_application|Running an application]]
* [[User_Guide/Tutorials/Setting_the_default_application|Setting the default application]]
* [[User_Guide/Tutorials/Zooming_in_a_Viewer|Zooming in a viewer]]

==Scripts, Toolboxes, Development, and Extending {{STX}}==

{{STX}} comes with a number of [[User Guide/Pre-installed scripts|pre-installed scripts]] - applications written in the {{STX}} scripting language, and loaded and run from a text file. You can write your own {{STX}} scripts, [[User Guide/Toolbox|toolboxes]] and applications. All the functionality that you find in {{STX}} is available to you in the script language. The [[User Guide/The_Script_Controller|script controller]] dialog, the [[User Guide/STX_Console|command line console]], the integrated [[User Guide/Debugger|debugger]] and the [[Programmer Guide]] will help you.

==The Log Window==
The little window up on the left hand corner of the screen is the {{STX}} [[/Log Window/]]. You can start a number of applications from here, change some general {{STX}} settings, and view the log messages.