Programmer Guide/Macro Library/Kernal/StdLib

File

STDLIB.STX, linked to library STX.LIB

Title

STx main library

Content

Variables and items used by this library

name	type	description

AppLoad

APPLOAD caller ; appname [ ; appargs ]

Load and run a registered STx application.

argument	description	default
caller	The caller shell id (* = master shell)
appname	Name of a registered STx application.
appargs	Arguments for the application.
RESULT	description
void	This macro has no return value.

Examples

• Start the realtime analyser: appload rtanalyse
• Start a script: appload bscript run ; $@root\scripts\myscript.sts ; mymacro ; arg1 arg2

AppMain

This is the STx application main macro. It is called by the application management system to initialize, run and finish STx applications. This macro can not be called from other macros.

To end an application and return directly to APPMAIN the command EXIT -1 can be used.

Note

At the end of an application, the sourcecode is unloaded. To avoid unloading the variable AppNoUnload must be set to 1 before returning to APPMAIN.

AppCleanup

This macro is called by APPMAIN to cleanup shell items. It deletes all shell items created by an application. It can also be called from the application to remove all shell items (APPCLEANUP ALL) or spu-items only (APPCLEANUP SPU).

AppHelp

This macro implements an interface to the online-help for STx.

Sub-Commands

MSG

AppHelp MSG message

Processes help messages (called by GETMESSAGE and message handlers) and calls the relevant function.

message					function
SHELL * HELP|HOTKEYS|ABOUT		APPHELP HELP|HOTKEYS|ABOUT|PROGRAMMER
*     * KEY * F1|CF1			APPHELP HELP (F1) or APPHELP HOTKEYS (CF1)
*     * POPUP n*100+0|1|2		APPHELP HELP (0), APPHELP HOTKEYS (1) or APPHELP ABOUT (2)

BEGIN

AppHelp BEGIN contextid [; autodelete]

Begin of a new help context. A help context can be used to define special links for a dialog. Set autoDelete to /Tagged for context menus. They are then automatically cleaned up by the End command. Help contexts are defined in the config file.

END

AppHelp END

Ends the current and enables the previous help context.

ABOUT

AppHelp ABOUT

Load the about text from the main help context and display the about dialog.

PROGRAMMER

AppHelp PROGRAMMER

Open the programmer guide. When STx closes, the programmer guide is not closed, since it was opened using system open, not system help.

SEARCH|INDEX

AppHelp Search|Index expression

Search for expression in the helpfiles or index

UPDATE

AppHelp Update

Check for updates

PostMessage

POSTMESSAGE shellid msgid [ msgpar ]

Post a message to a shell. The meaning of the message depends on the target shell. The target shell must implement message handling for shell messages.

argument	description	default
shellid	Unique id of the target shell.
msgid	The message id.
msgpar	The optional message parameter(s).
RESULT	description
0	success
1	failed

The following special values can be used for the argument shellid to the specify the target shell(s):

• CALLER → the caller of the application
• MASTER → the STx master shell
• SELF or THIS → the shell itself
• ALL or * → all running shells except the sender

Notes:

• The id of the current shell and the calling shell are stored in the variable SHELL: SHELL = current_shell_id calling_shell_id. The shell id is 8 digit hex number.

See also

command MESSAGE

SetMsgHandler

SETMSGHANDLER type name handler

Install the message handler handler for messages from type name.

SETMSGHANDLER type name

Remove the message handler for messages from type name.

argument	description	default
type	A type of a shell item or the keyword SHELL (see PostMessage).
name	The name of the shell item or the id of the shell. The character * can be used to catch the messages of all shell items of the specified type or of all shells.
handler	The message handler: macroname → messages are passed to the macro macroname function instance → messages are passed to the memberfunction function of the instance-item instance IGNORE → the messages are ignored (not processed) RETURN → the messages are returned to the message loop KILLSPUONSTOP → the sending spu-item is finished and deleted when the STOP message is received KILLSPUONEXIT → the sending spu-item is deleted when the EXIT message is received
RESULT	description
void	no return value

Notes

• A message handler function receives the whole message type name msgid msgpar as argument string.
• If type equals SPU, the built-in message handler functions KILLSPUONSTOP and KILLSPUONEXIT can be used for argument handler. Both functions delete the spu-item when receiving the STOP/EXIT message from the spu.
• If a message handler is installed for type name the macro GETMESSAGE calls the handler function (via DISPATCHMSG when receiving messages from the sender type name. Messages passed to a handler are not returned to the message loop (except if the keyword RETURN was used as handler argument).
• The message dispatching system is only active while the macro GETMESSAGE is running!
• For message handlers in classes the member functions AttachItem and DetachItem should be used.

DispatchMsg

DISPATCHMSG type name msgid [ msgpar ]

Forward the message to the message handler. The macro can be called from message loops or message handlers to forward or translate messages and it is also called by GETMESSAGE to perform standard message handling.

argument	description	default
type	The type of the sender.
name	The name of the sender.
msgid	The message id (depends on sender).
msgpar	The message parameter(s). (depends on sender and msgid)
RESULT	description
1	The message was processed by the message handler.	0	The message was not processed by the message handler or, no message handler is installed for type name

MsgQueue

MSGQUEUE type name msgid [ msgpar ]

This macro stores the message type name msgid msgpar in a secondary message queue. It can be used in sub-message-loops (e.g. as used for playback, spu-processing or modal dialogs) to queue messages which can not be processed at the time.

Note

While messages are queued in the secondary message queue, the argument queued of the GETMESSAGE call must be set to 0, to avoid the processing of messages stored in the secondary queue.

MsgFilter

MSGFILTER type name msgid [ acopy ]

Remove all messages defined by type name msgid from the internal msg-queues. If the argument acopy is the name of a simple tableitem, it is used to save a copy of the removed messages. The macro returns the number of removed messages.

Example

msgfilter spu * * → remove all spu messages

msgfilter * itemname * msgtab → remove all messages from the item itemname from the queue and store them in the simple table msgtab

GetMessage

GETMESSAGE queued noreturn nodispatch

This macro retrieves and dispatches messages. If a message handler is installed, the message is forwarded to the handler to perform message processing, otherwise the message is returned to the caller.

argument	description	default
queued	process messages from secondary queue (0=no, 1=yes)	1
noreturn	do not dispatch messages, return always - even if a message handler is installed (0=no, 1=yes) if set to 1, all messages are returned	0
RESULT	description
msg	The first message not processed by the message handler.
* * * * *	If the application has been finished (variable AppMode < 1)

• If the argument noreturn equals 0, all messages which were not processed by a handler, are returned. If it equals 1, all not processed messages are ignored and GETMESSAGE stays active until the application is finished (variable APPMODE < 1). Most applications uses the call getmessage 1 1 (process secondary queue, return never), to implement the main message loop.
• The argument queued controls the processing of messages stored in the secondary queue. This queue is filled with messages which can not be processed at the time. The processing of the secondary queue must be disabled in sub-message loops which queues (unknown) messages by calling the macro MSGQUEUE.
• If the argument nodispatch is set to 1, message dispatching is disabled and all messages are returned to the caller.
• Following special variables and items are used:
  • AppMode: application mode (< 1 → application finished, ≥ 1 → application running)
  • @LOGMSG: controls the STx log-level; all received messages are logged if @LOGMSG ≥ 1
  • tMsgQueue: secondary message queue (a simple table)
  • HWndTab, MWndTab: simple tables used to manage displays and modal dialogs of the shell

The script gui_basic_example.sts shows a simple example how message handling can be used in a STx GUI.

<include src="script_examples/gui_basic_example.sts" highlight="cpp" />

ExtSetup

This macro implements some special settings functions used by the STx applications.

EXTSETUP SEGNAME [ aset ]

Retrieve the next automatic segment name according to segname-settings and arguments. If an audioset reference aset is specified, the segment information is used to compute the next possible index. Otherwise the last used index is incremented by 1. The macro returns the generated segment id.

EXTSETUP SEGNAMEDLG

Show the settings dialog for automatic segment names.

EXTSETUP PRINTOUT item

Print the specified item (graph or display). Returns 0 for success or a numeric error code.

EXTSETUP PRINTOUT item

Show the print settings dialog.

PlayCursor

Implements a set of functions to display a running cursor in one or more graphs during signal playback.

Note: This implementation uses the variable PlayCrsPar and the table PlayCrsTab to store the settings and state values. Therefore a shell (STx application or script) can only use one instance of the PlayCursor.

PLAYCURSOR ADD gitem xmin xmax

Add the graphitem gitem to the playcursor graph-list. The arguments xmin and xmax specify the x-range where the playcursor should be visibile in graph gitem.

PLAYCURSOR SET x1 x2 dt t2x

Set the start- and end-time (x1..x2, values must be specified in the x-unit of the graphs), the time-increment (dt, timer step in ms) and the factor t2x to convert timer-values (ms) to the x-unit of the graphs (e.g. if x-values are specified in seconds t2x must be set to 0.001)

PLAYCURSOR ON [ witem ]

If playcursor is inactive → Start the playcursor and, if witem is a waveitem, the playback of witem.

If playcursor is active → If witem is a waveitem, update the playback gain.

PLAYCURSOR OFF

Stop the playcursor, reset settings and empty the graph-list.

PLAYCURSOR GETPOS

If playcursor is inactive → Return always 0.

If playcursor is active → Return the current x-position of the playcursor.

PLAYCURSOR VALUE ...

This is the message handler entry for the timer (valueitem) which is used by the playcursor functions. This entry should not be called directly (only via the message handling system).

GenerateScaleParams

GENERATESCALEPARAMS min max ; [unit=s] ; [format=clock] ; [nlabels=6] ; [nminor=3] ; [srate]

Generate the paramaters for the SET graph XSCALE ... command which is used to assign the time-scale settings of the viewer-graphs.

min max		The minimum and maximum x-value.
unit		The unit of the minimum and maximum x-value; either seconds (s) or milliseconds (ms).
format		s|ms|samples). Note that the unitStr parameter is returned for the formats s and ms, but not for clock and samples.
nlabels		Number of labels; must be ≥ 2
nminor		Number of minor ticks; must be ≥ 2
srate		The signal sampling rate in Hz. This argument is required only for the format samples.

The function returns the string minval maxval unitstr formatStr or minval maxval unitstr labelTab for success and the error code -1 if the scale parameter generation fails. The result can be directly used to assign the x-scale settings: <SET>SET graph XSCALE $RESULT.

MetaSegment

This macro implements a set of functions to display, edit and manage the meta-segments (segment marker) in the applications VIEWER1 and VIEWER2. It is very deep connected with the internals of the viewer applications and should not be used for other purposes.

stxFileTypeList

STXFILETYPELIST Workspace|Project|SMDF|Segments|Wave|Script|Export

Returns the semi-colon seperated list of filename-extensions for the selected type. The result can be used to pass filetype-arguments to the BUTIL FileDialog functions.

Example: The macro call stxfiletypelist smdf returns the string stxsm=STX Segment Metadata; xml=STX Segment Metadata (old).

stxFileType

STXFILETYPE Workspace|Project|SMDF|Segments|Wave|Script|Export

Returns the default filename-extensions for the selected type.

Example: The macro call stxfiletype smdf returns the string stxsm.

SectionFile

SECTIONFILE path ; todo table type name

Section file handling. In STx files in the INI-file format are called section-files. All source files (scripts, macros, ..) and some data files are stored in this format.

Note: A file processed with this macro may contain pre-processor commands, continuation-lines and comments.

todo=LOAD

Load the content of section [type] or section [type name] from file path into table. If table is set to * a new table is created.

Result: The table containing the loaded data (success) or an empty string (error)

todo=LIST

List all sections (type name not specified) or matching sections defined in file path. If table is set to * a new table is created.

Result: The table containing the section-list (success) or an empty string (error)

todo=SAVE

Save the table in the section [type] or section [type name] of file path. If the section exists already its content is replaced by the new data. If table is set to * the section is deleted.

Result: Always an empty string.

FileToolBox

A toolbox of useful file functions which take paths as parameters, shielding the user from the file objects themselves.

ATTRIBUTE

Get a file's attributes.

usage

FILETOOLBOX ATTRIBUTE filename attribute

return

the requested attribute

-1 if the macro failed

-2 if the attribute doesn't exist

note

all attributes supported by file items are supported by this command. just don't use the exclamation mark !

COMPARE

Simple files comparison.

usage

FILETOOLBOX COMPARE file1 file2

return

1 if they are different:0 if they are the same:-1 if the macro fails

notes

only the size in bytes is compared at the moment

COPY

Copy a file on disk.

usage

FILETOOLBOX COPY sourcefile targetfile

return

0 if file was copied:-1 if file was not copied

DELETE

Delete a file from disk.

usage

FILETOOLBOX DELETE filename

return

0 if file was deleted:-1 if file was not deleted

EXISTS

Test for a file's existence on disk.

usage

FileToolBox EXISTS filename

return

0 if file FileName exists

1 if file FileName does not exist

2 if FileName is a directory

RENAME

Rename a file on disk.

usage

FileToolBox RENAME Source Destination

return

Sets RESULT to 0 if the file was renamed or -1 if the file was not renamed. See the Log Window for a more detailed error message.

TOKENIZE

Tokenize the file path into drive, directory, name and extension. Note that this only works if the directory path exists!

usage

FileToolBox TOKENIZE filename [ keyword{drive|directory|name|extension} ]

return

Empty string on failure or 'drive ; directory ; name ; extension' or the part of the filename specified by keyword

example

FileToolBox Tokenize $#file
readstr '$result' #drive';'#dir';'#name';'#ext

UM and EM

UM text [; title ]

User Message → Display text in a message box with the caption title. This macro is an alias for BUTIL MSGBOX MSG ; text ; title. The return value is always 0.

EM [ rc [ n ]] ; emsg [; title ]

Error Message → Display the text "ERROR (rc): emsg" in a message box with the caption title. The macro exits from n (default: 2 = exit from caller) and returns the value rc.

ShowItem

Show content of a shell item in a popup dialog.

Usage

SHOWITEM item [; dialogTitle]

Result

none (void)

Note

Works with wave (playback), file, value and table items.

DoModalDialog

See Programmer_Guide/Macro_Library/DOMODALDIALOG

Wave2Output

[SPU WAVE2OUTPUT waveitem length=10000 factor=1 OUT x1 ... x8 sr n]

Uses the sp-atom asigin to read signal-blocks of the specified length (in samples) from the waveitem.

waveitem

name of the source waveitem

length

block length in samples

factor

linear amplification factor

x1, x2, ..

signal vector containing signal of channel 1, 2, ...

sr

samping rate of waveitem in Hz

n

number of blocks