StdLib

From STX Wiki
Jump to navigationJump to search
  • File: STDLIB.STX, linked to library STX.LIB
  • Title: STx main library

Content
application management AppLoad · AppMain · AppCleanup · AppHelp
message handling PostMessage · SetMsgHandler · DispatchMsg · MsgQueue · MsgFilter · GetMessage
utilities for standard
STx applications
ExtSetup · PlayCursor · GenerateScaleParams · MetaSegment
file functions stxFileTypeList · stxFileType · SectionFile · FileToolBox
display functions LogWindow · ConLog · UM and EM · ShowItem
dialog and window functions CreateMenu · DoModalDialog · SetModalWindow · GetWindowPos · SetWindowPos · WindowSizeDlg · GetMonitor · GetDesktop · ProgressBox · InitDialogItem · SetControlMode
SPU and graph functions SetGraphXScale · GetOutputValue
SPUs XScaleLinear · XScaleBark · Table2Output · Wave2output
Variables and items used by this library
name type description

AppLoad

APPLOAD appname [ ; appargs ]

Load and run a registered STx application.
argument description default
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. It is currently under development.

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 typen 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 procesing 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 following script shows a simple example how message handling can be used in a STx GUI. [1] <include src="script_examples/gui_basic_example.sts" highlight="cpp" />

Navigation menu

Personal tools