Programmer Guide/Command Reference/MESSAGE: Difference between revisions
(→DEBUG) |
|||
Line 13: | Line 13: | ||
== Sub-commands == | == Sub-commands == | ||
=== BEEP === | === <code>MESSAGE BEEP</code> === | ||
MESSAGE BEEP /Speaker|Asterisk|Exclamation|Hand|Question|Okay | MESSAGE BEEP /Speaker|Asterisk|Exclamation|Hand|Question|Okay | ||
Line 20: | Line 20: | ||
Play a tone via the PC loudspeaker. A standard windows sound (selected with an option) or a <var>frequency</var> ([http://en.wikipedia.org/wiki/Hertz Hz]) and <var>duration</var> ([http://en.wikipedia.org/wiki/Millisecond ms]) may be specified. No commands are processed while the sound is being played. | Play a tone via the PC loudspeaker. A standard windows sound (selected with an option) or a <var>frequency</var> ([http://en.wikipedia.org/wiki/Hertz Hz]) and <var>duration</var> ([http://en.wikipedia.org/wiki/Millisecond ms]) may be specified. No commands are processed while the sound is being played. | ||
=== DEBUG === | === <code>MESSAGE DEBUG</code> === | ||
The <code>MSG DEBUG</code> command interacts with the {{STX}} interactive debugging tool. The command has the following general syntax: | The <code>MSG DEBUG</code> command interacts with the {{STX}} interactive debugging tool. The command has the following general syntax: | ||
Line 53: | Line 53: | ||
Close the debugger and disable debugging. If you wish to re-enable the debugger, you must restart {{STX}} altogether. | Close the debugger and disable debugging. If you wish to re-enable the debugger, you must restart {{STX}} altogether. | ||
=== DESKTOP === | === <code>MESSAGE DESKTOP</code> === | ||
MESSAGE DESKTOP | |||
The <code>MESSAGE DESKTOP</code> command retrieves the origin, the height and the width of the whole desktop (all monitors), as well as the number of monitors connected to the computer. It returns this information in the <var>#msg</var> variable in the following format: | |||
desktopWidth desktopHeight desktopXOrigin desktopYOrigin numberOfMonitors | |||
Note that the primary monitor always has an origin of 0/0 (x/y). Therefore, if you have three monitors, and the middle one is the primary monitor, the value <code>desktopXOrigin</code> will be negative. The return values are stored in the variable <code>#msg</code>. | |||
<code>MESSAGE EXIT <var>shellid</var | === <code>MESSAGE EXIT</code> === | ||
MESSAGE EXIT <var>shellid</var> | |||
Terminate a shell <var>shellid</var> immediately. This message is processed by the internal message loop and not by the macros. It can be used to abort shells which are not responding. | Terminate a shell <var>shellid</var> immediately. This message is processed by the internal message loop and not by the macros. It can be used to abort shells which are not responding. | ||
=== LOGFILE === | === MESSAGE LOGFILE === | ||
<code>MESSAGE LOGFILE <var>logfilename</var></code> | <code>MESSAGE LOGFILE <var>logfilename</var></code> | ||
Line 73: | Line 75: | ||
Redirect all log-window output to the specified file. Set <var>logfilename</var> to <code>*</code> to turn redirection off. | Redirect all log-window output to the specified file. Set <var>logfilename</var> to <code>*</code> to turn redirection off. | ||
=== LOOP === | === MESSAGE LOOP === | ||
<code>MESSAGE LOOP [/Nowait]</code> | <code>MESSAGE LOOP [/Nowait]</code> | ||
Line 81: | Line 83: | ||
<code>#MSG = sendertype sendername msgid msgparameter(s)</code> | <code>#MSG = sendertype sendername msgid msgparameter(s)</code> | ||
=== MAIN === | === MESSAGE MAIN === | ||
<code>MESSAGE MAIN <var>mode</var> [<var>style xpos ypos width height title</var>]</code> | <code>MESSAGE MAIN <var>mode</var> [<var>style xpos ypos width height title</var>]</code> | ||
Line 89: | Line 91: | ||
<code>#MSG = mode style xpos ypos width height title</code> | <code>#MSG = mode style xpos ypos width height title</code> | ||
=== MENU === | === MESSAGE MENU === | ||
<code>MESSAGE MENU /Add <var>name item1 item2</var> ...</code> | <code>MESSAGE MENU /Add <var>name item1 item2</var> ...</code> | ||
Line 101: | Line 103: | ||
Log window popup-menu handling. All log-window menu commands are similar to the equivalent display/dialog-item commands. | Log window popup-menu handling. All log-window menu commands are similar to the equivalent display/dialog-item commands. | ||
=== NOMAIN === | === MESSAGE NOMAIN === | ||
<code>MESSAGE NOMAIN</code> | <code>MESSAGE NOMAIN</code> | ||
Line 107: | Line 109: | ||
Hide the log window and all other {{STX}} windows. | Hide the log window and all other {{STX}} windows. | ||
=== RUN === | === MESSAGE RUN === | ||
<code>MESSAGE RUN <var>shellid messageid messegaparameters</var></code> | <code>MESSAGE RUN <var>shellid messageid messegaparameters</var></code> | ||
Line 113: | Line 115: | ||
Send a message to the shell <var>shellid</var>. Do not use this command directly, call the macro <code>POSTMESSAGE</code> instead. The special <var>shellid</var> '<code>*</code>' (all shells, except sender) or '<code>=</code>' (to the sender itself) can be used. Messages sent using this command are pre-processed by the macro <code>GETMESSAGE</code>! | Send a message to the shell <var>shellid</var>. Do not use this command directly, call the macro <code>POSTMESSAGE</code> instead. The special <var>shellid</var> '<code>*</code>' (all shells, except sender) or '<code>=</code>' (to the sender itself) can be used. Messages sent using this command are pre-processed by the macro <code>GETMESSAGE</code>! | ||
=== QUEUE === | === MESSAGE QUEUE === | ||
<code>MESSAGE QUEUE [ <var>qtable</var> ]</code> | <code>MESSAGE QUEUE [ <var>qtable</var> ]</code> | ||
Empty the internal message queue. If the argument <var>qtable</var> is a simple table, a copy of the internal message queue is stored in the table before the queue is cleared. | Empty the internal message queue. If the argument <var>qtable</var> is a simple table, a copy of the internal message queue is stored in the table before the queue is cleared. |
Revision as of 23:44, 25 May 2012
The MESSAGE
command is a low-level means for processing shell messages in STx. There are a number of different sub-commands you may pass to the command (see below). Many of the sub-commands use the variable #msg
to return values. The MESSAGE
command may be abbreviated to MSG
.
If you want to use macro message handlers in an application, you need to call the macro GETMESSAGE
to retrieve messages, instead of directly using the MESSAGE
command. In conjunction with the macros SETMSGHANDLER
and DISPATCHMSG
, the GETMESSAGE
macro implements the standard STx message handling system.
Note: For message handling in classes, you may use the member functions AttachItem
, DetachItem
and MsgHandler
as an alternative better suited to the object-oriented use-case.
The complete set of STx messages is listed under Messages/Communication Messages.
Sub-commands
MESSAGE BEEP
MESSAGE BEEP /Speaker|Asterisk|Exclamation|Hand|Question|Okay MESSAGE BEEP frequency duration
Play a tone via the PC loudspeaker. A standard windows sound (selected with an option) or a frequency (Hz) and duration (ms) may be specified. No commands are processed while the sound is being played.
MESSAGE DEBUG
The MSG DEBUG
command interacts with the STx interactive debugging tool. The command has the following general syntax:
MSG DEBUG cmd [ par ] [ option ]
There are a number of different sub-sub-commands which are described below.
MSG DEBUG INIT [ shell ] [ /Step ]
Initialize the debugger. This must be called exactly once, and it must be called first, i.e., before any other MSG DEBUG
commands.
- shell
- The shell in which to start the debugger (i.e., whose script to debug). If you omit this information, the caller's shell will be debugged.
- /Step
- If specified, the debugger interrupts execution (like calling
MSG DEBUG STEP
). It will wait for an interactive command to resume.
MSG DEBUG STEP [ text ]
Open the debugger and interrupt execution. That's just the same like MSG DEBUG INIT /Step
.
MSG DEBUG ON [ macroName ]
Open the debugger. If a macro is specified, the debugger will stop execution as soon as the control flow enters the respective macro.
MSG DEBUG OFF
Close the debugger.
MSG DEBUG NO
Close the debugger and disable debugging. If you wish to re-enable the debugger, you must restart STx altogether.
MESSAGE DESKTOP
MESSAGE DESKTOP
The MESSAGE DESKTOP
command retrieves the origin, the height and the width of the whole desktop (all monitors), as well as the number of monitors connected to the computer. It returns this information in the #msg variable in the following format:
desktopWidth desktopHeight desktopXOrigin desktopYOrigin numberOfMonitors
Note that the primary monitor always has an origin of 0/0 (x/y). Therefore, if you have three monitors, and the middle one is the primary monitor, the value desktopXOrigin
will be negative. The return values are stored in the variable #msg
.
MESSAGE EXIT
MESSAGE EXIT shellid
Terminate a shell shellid immediately. This message is processed by the internal message loop and not by the macros. It can be used to abort shells which are not responding.
MESSAGE LOGFILE
MESSAGE LOGFILE logfilename
Redirect all log-window output to the specified file. Set logfilename to *
to turn redirection off.
MESSAGE LOOP
MESSAGE LOOP [/Nowait]
Get the next message from the shell's message queue. Use /Nowait if you do not want to wait should the message queue be empty. The return values are stored in the variable #MSG
.
#MSG = sendertype sendername msgid msgparameter(s)
MESSAGE MAIN
MESSAGE MAIN mode [style xpos ypos width height title]
Set and/or get the log-window's mode (HIDDEN
|VISIBLE
|ENABLED
|*
), style (MINIMIZED
|RESTORED
|MAXIMIZED
|*
), position, size and/or caption. The current settings are stored in the message variable #MSG
.
#MSG = mode style xpos ypos width height title
MESSAGE MENU
MESSAGE MENU /Add name item1 item2 ...
MESSAGE MENU /Add name table /Table
MESSAGE MENU /Show
MESSAGE MENU /Delete
Log window popup-menu handling. All log-window menu commands are similar to the equivalent display/dialog-item commands.
MESSAGE NOMAIN
MESSAGE NOMAIN
Hide the log window and all other STx windows.
MESSAGE RUN
MESSAGE RUN shellid messageid messegaparameters
Send a message to the shell shellid. Do not use this command directly, call the macro POSTMESSAGE
instead. The special shellid '*
' (all shells, except sender) or '=
' (to the sender itself) can be used. Messages sent using this command are pre-processed by the macro GETMESSAGE
!
MESSAGE QUEUE
MESSAGE QUEUE [ qtable ]
Empty the internal message queue. If the argument qtable is a simple table, a copy of the internal message queue is stored in the table before the queue is cleared.