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 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 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" />