SETMSGHANDLER

From STX Wiki
Jump to navigation Jump to search

SETMSGHANDLER

Install the message handler handler for the sender(s) defined by type name. If no handler is supplied, the message handler is deinstalled. If a message handler is installed for type name, the macro GETMESSAGE calls the handler function when receiving messages of type name. This means the messages are not returned (except if the keyword RETURN was used as a handler argument). A message handler function receives the whole message (type name id par) as an argument string.

The message dispatching system is only active while the macro GETMESSAGE is running!

Usage:

SETMSGHANDLER type name [handler]

Parameters:
type
The item type of sender; any shell item type (sending messages) or SHELL
name
The name of the sender; shell item name, shell id or * for all items of the specified type type.
handler
The message handler function. This function will be called when a message for an item corresponding to type and name is received. If handler is not supplied, any previously installed message handler for type name is removed. The handler function can be either a macro (handler = macroname) or a class member-function (handler = memberfunction instance). The following keywords are also supported: IGNORE (all messages for type name are ignored) and RETURN (return from GETMESSAGE if a message for type name is received). If the type is SPU,the following keywords are also supported: KILLSPUONSTOP (the SPU is deleted when the STOP message is received) and KILLSPUONEXIT (the SPU is deleted when the EXIT message is received). The message handler function receives the whole message (type name id par) as an argument string.
Result:

void

Examples:
// Any messages for value items are passed to the macro MH_VALUEITEM.
SETMSGHANDLER VALUE * MH_VALUEITEM

See also

GETMESSAGE