GuiSay()

Pops up a modal message box, displaying the text that you specified as GuiSay's first argument. There will be one or more push buttons that the user can click the mouse upon in order to manually dismiss the message box. The box remains displayed, and your script is suspended, until the user dismisses that box, at which time your script resumes its processing (on the next REXX line after the call to GuiSay). The user will also not be able to interact with your other windows while the message box is displayed.

button_name = GuiSay(Message, Options, Heading, Window)


Args

Message is the text that you wish displayed in the body of the message box. If there are multiple lines of text, then each line should end with '0A0D'X (ie, a carriage return and linefeed characters).

Options are which buttons, and icons, to display. It must be one of the following:

Options> Meaning
'OK'Show only an "Ok" button.
'OKCANCEL'Show an "Ok" and "Cancel" buttons.
'YES'Show a "Yes" and "No" buttons.
'YESCANCEL'Show a "Yes", "No", and "Cancel" buttons.
'ABORT'Show an "Abort", "Retry", and "Ignore" buttons.
'RETRY'Show a "Retry" and "Cancel" buttons.

A further option may be specified, separated by a | character:

Options Meaning
'INFO' Show an icon consisting of a lowercase letter 'i' in a circle.
'!' Show an icon consisting of an exclamation point.
'STOP' Show an icon consisting of a stop sign. A sound is also made from the speaker.
'?' Show an icon consisting of a question mark.

If Options is omitted, then it defaults to 'OK|STOP'.

Heading is the text that you wish displayed in the titlebar of the message box. If omitted, it defaults to the name of the script that called GuiSay.

Window is the handle to some window you have open (such as the value of the GuiWindow variable set by GuiCreateWindow). If omitted, then the message box will block the user from accessing all of your windows until he dismisses your message box. By specifying a particular window, then only that window is blocked from being accessed by the user until he dismisses your message box.


Returns

If successful, the name of the button pushed is returned. (ie, If the "Ok" button is pushed, then "OK" is returned). If an error, an empty string is returned.


Notes

If an error occurs, it is usually due to low resources (ie, perhaps low memory), GuiSay() will raise a SYNTAX error.

GuiSay() differs from the REXX standard SAY command. The SAY command will cause a console window to be opened to display the message, and your script will continue on while that console window is left open. Also, the text from a SAY command may be captured by some program that launches your script.

Since REXX GUI offers other facilities to open windows and display text, there are other ways of displaying text, but GuiSay is the easiest and is a direct replacement for the standard SAY command (mostly). Just change any reference from SAY to CALL GuiSay, and you've changed a REXX script to output via Desktop message boxes. GuiSay doesn't recognize any ANSI sequences to change color or move the cursor. And sometimes programmers use the fact that SAY outputs to only 1 window in order to spread output of one "statement" across several calls to SAY. On the other hand, each call to GuiSay produces a distinct message box. So, the translation isn't exact, but it's close enough. Generally, what GuiSay is used for is to display error messages, or to offer the user a simple prompt, such as to ask him if he wants to overwrite an existing file.

You can cause GuiSay to display several lines of text by inserting the hex literal string '0A0D'X where you wish a new line to start. For example, here we display the text "Line 1", and then display "Line 2" below it upon a second line:

GuiSay('Line 1' || '0A0D'X || 'Line 2')
GuiSay offers a choice of various pushbuttons that can be created at the bottom of the message box, which the user can click upon to dismiss the message box. GuiSay will then return different values depending upon which button the user clicked. For example, you can use GuiSay to present a box that displays a question and offers the user a YES or NO button, and write your REXX script to do different things based upon the returned string.


Examples

/* Pop up a dialog with the question "Is your name Marvin"?
 * Note that we stored the name in a variable. We also include
 * YES and NO buttons, and a Question Mark symbol.
 */

txt = 'Marvin'
button = GuiSay('Is your name "' || txt '"?', 'YES', 'Answer this question')
IF button = 'YES' THEN CALL GuiSay('Yes, your name is "' || txt || '"')