Programmer Guide/Macro Library/SETMSGHANDLER: Difference between revisions
From STX Wiki
Jump to navigationJump to search
m (1 revision: Initial import) |
|||
| (6 intermediate revisions by the same user not shown) | |||
| Line 2: | Line 2: | ||
==SETMSGHANDLER== | ==SETMSGHANDLER== | ||
Install the message handler <var>handler</var> for the sender(s) defined by <var>type name</var>. If no handler is supplied, the message handler is deinstalled. If a message handler is installed for <var>type name</var>, the macro <code>GETMESSAGE</code> calls the handler function when receiving messages of <var>type name</var>. This means the messages are not returned (except if the keyword <code>RETURN</code> was used as a handler argument). A message handler function receives the whole message (<code>type name id par</code>) as an argument string. | Install the message handler <var>handler</var> for the sender(s) defined by <var>type name</var>. If no handler is supplied, the message handler is deinstalled. If a message handler is installed for <var>type name</var>, the macro <code>[[Programmer_Guide/Macro_Library/GETMESSAGE|GETMESSAGE]]</code> calls the handler function when receiving messages of <var>type name</var>. This means the messages are not returned (except if the keyword <code>RETURN</code> was used as a handler argument). A message handler function receives the whole message (<code>type name id par</code>) as an argument string. | ||
The message dispatching system is only active while the macro <code>GETMESSAGE</code> is running! | The message dispatching system is only active while the macro <code>GETMESSAGE</code> is running! | ||
| Line 12: | Line 12: | ||
=====Parameters:===== | =====Parameters:===== | ||
;type:The item type of sender; any shell item type (sending messages) or <code>SHELL</code> | |||
;name:The name of the sender; shell item name, shell id or <code>*</code> for all items of the specified type <var>type</var>. | |||
;handler:The message handler function. This function will be called when a message for an item corresponding to <var>type</var> and <var>name</var> is received. If <var>handler</var> is not supplied, any previously installed message handler for <var>type name</var> is removed. The handler function can be either a macro (<var>handler</var> = macroname) or a class member-function (<var>handler</var> = memberfunction instance). The following keywords are also supported: <code>IGNORE</code> (all messages for <var>type</var> <var>name</var> are ignored) and <code>RETURN</code> (return from <code>GETMESSAGE</code> if a message for <var>type</var> <var>name</var> is received). If the <var>type</var> is <code>SPU</code>,the following keywords are also supported: <code>KILLSPUONSTOP</code> (the SPU is deleted when the <code>STOP</code> message is received) and <code>KILLSPUONEXIT</code> (the SPU is deleted when the <code>EXIT</code> message is received). The message handler function receives the whole message (<code>type name id par</code>) as an argument string. | |||
=====Result:===== | |||
void | void | ||
| Line 22: | Line 26: | ||
SETMSGHANDLER VALUE * MH_VALUEITEM | SETMSGHANDLER VALUE * MH_VALUEITEM | ||
</pre> | </pre> | ||
==See also== | |||
[[Programmer_Guide/Macro_Library/GETMESSAGE|GETMESSAGE]] | |||
Latest revision as of 08:04, 6 August 2019
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) andRETURN(return fromGETMESSAGEif a message for type name is received). If the type isSPU,the following keywords are also supported:KILLSPUONSTOP(the SPU is deleted when theSTOPmessage is received) andKILLSPUONEXIT(the SPU is deleted when theEXITmessage 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
