Programmer Guide/Command Reference/MESSAGE: Difference between revisions

From STX Wiki
Jump to navigationJump to search
No edit summary
No edit summary
 
(37 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:{{SUBPAGENAME}}}}__NOTOC__
{{DISPLAYTITLE:{{SUBPAGENAME}}}}__NOTOC__
==MESSAGE==
The <code>MESSAGE</code> 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 <var>#msg</var> to return values. The <code>MESSAGE</code> command may be abbreviated to <code>MSG</code>.


The <code>MESSAGE</code> command can be called using <code><code>MESSAGE</code></code> or the abbreviation <code><code>MSG</code>. There are a number of different commands you can pass to the command (see below). Many of the sub-commands use and set the variable <code>#msg</code> variable to return values.</code>
If you want to use macro message handlers in an application, you need to call the macro <code>[[Programmer_Guide/Macro_Library#GetMessage|GETMESSAGE]]</code> to retrieve messages, instead of  directly using the <code>MESSAGE</code> command. In conjunction with the macros <code>[[Programmer_Guide/Macro_Library#SetMsgHandler|SETMSGHANDLER]]</code>
and <code>[[Programmer_Guide/Macro_Library#DispatchMsg|DISPATCHMSG]]</code>, the <code>[[Programmer_Guide/Macro_Library#GetMessage|GETMESSAGE]]</code> macro implements the standard {{STX}} message handling system.


If you want to use macro message handlers in an application, you must call the macro <code>GetMessage</code> to retrieve messages instead of using this command directly. This macro implements, in conjunction with the macros
'''Note:''' For message handling in ''classes'', you may use the member functions <code>[[Programmer_Guide/Macro_Library/COBJ#AttachItem_.2F_AttachShell|AttachItem]]</code>, <code>[[Programmer_Guide/Macro_Library/COBJ#DetachItem_.2F_DetachShell|DetachItem]]</code> and <code>[[Programmer_Guide/Macro_Library/COBJ#MsgHandler|MsgHandler]]</code> as an alternative better suited to the object-oriented use-case.
[[Programmer_Guide/Macro_Library#SetMsgHandler|SETMSGHANDLER]], [[Programmer_Guide/Macro_Library#DispatchMsg|DISPATCHMSG]] and [[Programmer_Guide/Macro_Library#GetMessage|GETMESSAGE]]the standard {{STX}} message handling system.


;Content: [[#BEEP]]
;Sub-commands: [[#MESSAGE BEEP|BEEP]], [[#MESSAGE DEBUG|DEBUG]], [[#MESSAGE DESKTOP|DESKTOP]], [[#MESSAGE EXIT|EXIT]], [[#MESSAGE LOGFILE|LOGFILE]], [[#MESSAGE LOOP|LOOP]], [[#MESSAGE MAIN|MAIN]], [[#MESSAGE MENU|MENU]], [[#MESSAGE NOMAIN|NOMAIN]], [[#MESSAGE RUN|RUN]], [[#MESSAGE QUEUE|QUEUE]]


The complete set of {{STX}} messages is listed under [[Messages/Communication Messages]].<!-- where's the link? XXX -->


== Sub-commands ==


=== <code>MESSAGE BEEP</code> ===


The complete set of {{STX}} messages is listed under Communication Messages.
MESSAGE BEEP /Speaker|Asterisk|Exclamation|Hand|Question|Okay
MESSAGE BEEP <var>frequency</var> <var>duration</var>


====BEEP====
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.


<code>MESSAGE BEEP /Speaker|Asterisk|Exclamation|Hand|Question|Okay</code>
=== <code>MESSAGE DEBUG</code> ===


<code>MESSAGE BEEP <var>frequency duration</var></code>
The <code>MSG DEBUG</code> command interacts with the {{STX}} interactive debugging tool. The command has the following general syntax:


Play a tone via the PC loudspeaker. A standard windows sound (selected with an option) or a <var>frequency</var> (Hz) and <var>duration</var> (ms) can be specified. No commands are processed while the sound is played.
MSG DEBUG <var>cmd</var> [ <var>par</var> ] [ option ]


====DEBUG====
There are a number of different sub-sub-commands which are described below.


The <code>MSG DEBUG</code> command has the following general syntax:
MSG DEBUG INIT [ <var>shell</var> ] [ /Step ]


<code>MSG DEBUG</code> <var>cmd</var> <code>[</code> <var>par</var> <code>] [</code> option <code>]</code>
Initialize the debugger. This must be called exactly ''once'', and it must be called ''first'', i.e., before any other <code>MSG DEBUG</code> commands.
 
There are a number of different sub-commands which are described below.
 
<code>MSG DEBUG INIT [ <var>shell</var> ] [ /Step ]</code>
 
Initialise the debugger. This must be called once, before any other <code>MSG DEBUG</code> commands.


;<var>shell</var>
;<var>shell</var>
: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.
;<var>/Step</var>
:If specified, the debugger interrupts execution (like calling <code>MSG DEBUG STEP</code>). It will wait for an interactive command to resume.


:The shell in which to start the debugger. If this is not specified, the caller's shell is debugged.
MSG DEBUG STEP [ <var>text</var> ]


;<var>/Step</var>
Open the debugger and interrupt execution. That's just the same like <code>MSG DEBUG INIT /Step</code>.


:If specified, the debugger breaks execution (like calling <code>MSG DEBUG STEP</code>).
MSG DEBUG ON [ <var>macroName</var> ]


<code>MSG DEBUG STEP [ <var>text</var> ]</code>
Open the debugger. If a macro is specified, the debugger will stop execution as soon as the control flow enters the respective macro.


Open the debugger and break execution.
MSG DEBUG OFF


<code>MSG DEBUG ON [ <var>macroName</var> ]</code>
Close the debugger.
 
Open the debugger. If a macro is specified, the debugger will break as soon as this macro is called.


<code>MSG DEBUG OFF</code>
MSG DEBUG NO


Close the debugger.
Close the debugger and disable debugging. If you wish to re-enable the debugger, you must restart {{STX}} altogether.


<code>MSG DEBUG NO</code>
=== <code>MESSAGE DESKTOP</code> ===


Close the debugger and disable debugging. If you wish to re-enable the debugger, you must restart {{STX}}.
MESSAGE DESKTOP


====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. Furthermore, for each monitor, it will return its virtual coordinates (left, top, right, and bottom, in this order). It returns this information in the <var>#MSG</var> variable in the following format:


<code>MESSAGE DESKTOP</code>
<var>desktopWidth</var> <var>desktopHeight</var> <var>desktopXOrigin</var> <var>desktopYOrigin</var> <var>numberOfMonitors</var>
<var>left<sub>1</sub></var> <var>top<sub>1</sub></var> <var>right<sub>1</sub></var> <var>bottom<sub>1</sub></var>&hellip; <var>left<sub>N</sub></var> <var>top<sub>N</sub></var> <var>right<sub>N</sub></var> <var>bottom<sub>N</sub></var>


Get the origin, height and width of the whole desktop (all monitors) and the number of monitors connected to the computer. Note that the primary monitor always has an 0/0 x/y origin. 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>.
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 <var>desktopXOrigin</var> will be negative.


<code>#msg = desktopWidth desktopHeight desktopXOrigin desktopYOrigin numberOfMonitors</code>
Code example:
msg desktop
readvar #msg #width #height #x0 #y0 #screencount #


====EXIT====
=== <code>MESSAGE EXIT</code> ===


<code>MESSAGE EXIT <var>shellid</var></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====
=== <code>MESSAGE LOGFILE</code> ===
 
MESSAGE LOGFILE <var>logfilename</var>
MESSAGE LOGFILE *


<code>MESSAGE LOGFILE <var>logfilename</var></code>
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.
=== <code>MESSAGE LOOP</code> ===


====LOOP====
MESSAGE LOOP [ /Nowait ]


<code>MESSAGE LOOP [/Nowait]</code>
Get the next message from the message queue of the shell. If the message queue is empty, the <code>MESSAGE LOOP</code> command will normally block until there is a message available. For non-blocking operation, use the <code>/Nowait</code> option: With <code>/Nowait</code> supplied, the command will return immediately should the message queue be empty.


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 <code>#MSG</code>.
The return values of the <code>MESSAGE LOOP</code> command are stored in the <var>#MSG</var> variable in the following format:


<code>#MSG = sendertype sendername msgid msgparameter(s)</code>
<var>sendertype</var> <var>sendername</var> <var>msgid</var> <var>msgparameter<sub>1</sub></var>&hellip;<var>msgparameter<sub>n</sub></var>


====MAIN====
Code example:
msg loop
readvar #msg #sendertype #sendername #msgid #parms


<code>MESSAGE MAIN <var>mode</var> [<var>style xpos ypos width height title</var>]</code>
=== <code>MESSAGE MAIN</code> ===


Set and/or get the log-window's mode (<code>HIDDEN</code>|<code>VISIBLE</code>|<code>ENABLED</code>|<code>*</code>), style (<code>MINIMIZED</code>|<code>RESTORED</code>|<code>MAXIMIZED</code>|<code>*</code>), position, size and/or caption. The current settings are stored in the message variable <code>#MSG</code>.
MESSAGE MAIN <var>mode</var> [<var>style</var> <var>xpos</var> <var>ypos</var> <var>width</var> <var>height </var> <var>title</var>]


<code>#MSG = mode style xpos ypos width height title</code>
Set and/or get the mode of the log window (one out of <code>HIDDEN</code>, <code>VISIBLE</code>, <code>ENABLED</code>, <code>*</code>), its style (one out of <code>MINIMIZED</code>, <code>RESTORED</code>, <code>MAXIMIZED</code>, <code>*</code>), and its position, size and/or caption. The current settings are stored in the message variable <code>#MSG</code> in the following format:


====MENU====
<var>mode</var> <var>style</var> <var>xpos</var> <var>ypos</var> <var>width</var> <var>height</var> <var>title</var>


<code>MESSAGE MENU /Add <var>name item1 item2</var> ...</code>
=== <code>MESSAGE MENU</code> ===


<code>MESSAGE MENU /Add <var>name table</var> /Table</code>
MESSAGE MENU /Addpopup <var>name</var> <var>item<sub>1</sub></var> <var>item<sub>2</sub></var>&hellip;
MESSAGE MENU /Addpopup <var>name</var> <var>table</var> /Table
MESSAGE MENU /Show
MESSAGE MENU /Delete


<code>MESSAGE MENU /Show</code>
The <code>MESSAGE MENU</code> command is for handling log window popup menus. Its sub-commands are similar to the corresponding [[Programmer_Guide/Shell_Items/Dialog/SET_DIALOG#Dialog_Context_Menus|dialog item commands]] for handling popup menus, <code>[[Programmer_Guide/Shell_Items/Dialog/SET_DIALOG#ADDPOPUP|ADDPOPUP]]</code> and <code>[[Programmer_Guide/Shell_Items/Dialog/SET_DIALOG#DELPOPUP|DELPOPUP]]</code> (see there).


<code>MESSAGE MENU /Delete</code>
=== <code>MESSAGE NOMAIN</code> ===


Log window popup-menu handling. All log-window menu commands are similar to the equivalent display/dialog-item commands.
MESSAGE NOMAIN


====NOMAIN====
This will hide the log window and all other {{STX}} windows.


<code>MESSAGE NOMAIN</code>
=== <code>MESSAGE RUN</code> ===


Hide the log window and all other {{STX}} windows.
MESSAGE RUN <var>shellid</var> <var>messageid</var> <var>messegaparameters</var>


====RUN====
The <code>MESSAGE RUN</code> command will send a message to the shell <var>shellid</var>. ''Do not'' use this command directly! Instead, always call the macro <code>POSTMESSAGE</code>.


<code>MESSAGE RUN <var>shellid messageid messegaparameters</var></code>
If you supply an asterisk, <code>*</code> for the <var>shellid</var> argument (which you won't because you never call this command directly), the message will be sent to ''all'' shells except the sending shell. If you supply the character &quot;<code>=</code>&quot; (which you won't either, because you never call this command directly), the message will be sent to the sending shell itself.


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>!
Messages sent using the <code>MESSAGE RUN</code> command are pre-processed by the macro <code>GETMESSAGE</code>.


====QUEUE====
=== <code>MESSAGE QUEUE</code> ===


<code>MESSAGE QUEUE [ <var>qtable</var> ]</code>
MESSAGE QUEUE [ <var>qtable</var> ]


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 actually clearing the message queue.

Latest revision as of 14:39, 6 August 2019

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.

Sub-commands
BEEP, DEBUG, DESKTOP, EXIT, LOGFILE, LOOP, MAIN, MENU, NOMAIN, RUN, QUEUE

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. Furthermore, for each monitor, it will return its virtual coordinates (left, top, right, and bottom, in this order). It returns this information in the #MSG variable in the following format:

desktopWidth desktopHeight desktopXOrigin desktopYOrigin numberOfMonitors
left1 top1 right1 bottom1leftN topN rightN bottomN

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.

Code example:

msg desktop
readvar #msg #width #height #x0 #y0 #screencount #

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
MESSAGE LOGFILE *

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 message queue of the shell. If the message queue is empty, the MESSAGE LOOP command will normally block until there is a message available. For non-blocking operation, use the /Nowait option: With /Nowait supplied, the command will return immediately should the message queue be empty.

The return values of the MESSAGE LOOP command are stored in the #MSG variable in the following format:

sendertype sendername msgid msgparameter1msgparametern

Code example:

msg loop
readvar #msg #sendertype #sendername #msgid #parms

MESSAGE MAIN

MESSAGE MAIN mode [style xpos ypos width height  title]

Set and/or get the mode of the log window (one out of HIDDEN, VISIBLE, ENABLED, *), its style (one out of MINIMIZED, RESTORED, MAXIMIZED, *), and its position, size and/or caption. The current settings are stored in the message variable #MSG in the following format:

mode style xpos ypos width height title

MESSAGE MENU

MESSAGE MENU /Addpopup name item1 item2…
MESSAGE MENU /Addpopup name table /Table
MESSAGE MENU /Show
MESSAGE MENU /Delete

The MESSAGE MENU command is for handling log window popup menus. Its sub-commands are similar to the corresponding dialog item commands for handling popup menus, ADDPOPUP and DELPOPUP (see there).

MESSAGE NOMAIN

MESSAGE NOMAIN

This will hide the log window and all other STx windows.

MESSAGE RUN

MESSAGE RUN shellid messageid messegaparameters

The MESSAGE RUN command will send a message to the shell shellid. Do not use this command directly! Instead, always call the macro POSTMESSAGE.

If you supply an asterisk, * for the shellid argument (which you won't because you never call this command directly), the message will be sent to all shells except the sending shell. If you supply the character "=" (which you won't either, because you never call this command directly), the message will be sent to the sending shell itself.

Messages sent using the MESSAGE RUN 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 actually clearing the message queue.

Navigation menu

Personal tools