843.TXT
=====================================================================
Displaying Messages in R:BASE 5.5 for Windows
=====================================================================
PRODUCT: R:BASE VERSION: 5.5 or Higher
=====================================================================
CATALOG: Programming in R:BASE AREA : General Information
=====================================================================
There are times when an application developer has a need to display
messages to application users. The developer may want to display
informational messages, or a custom error message. There are three
different techniques to use in R:BASE 5.5 for Windows applications to
display messages to the application user. Each technique is slightly
different, so use the one that best fits your application needs. The
three techniques are:
ú Using the PAUSE command
ú Using the DIALOG command
ú Using an MDI form
Using the PAUSE Command
The PAUSE command displays single line messages in a Windows style
message box. These messages can be up to 78 characters in length. The
message is displayed in a standard Windows- style message box with
the word "Message" as the window title, a "stop sign" icon, and an OK
button for the user to click after they have read the message. For
example, the following command displays a message letting the user
know their report printed successfully:
PAUSE 2 USING `The sales report has finished printing.'
The PAUSE command can be positioned at a screen location using the AT
option, or if no position is given, the message box is displayed in
the center of the screen. The user can then grab the message box with
the mouse and move the message box to any other location on the
screen. Once moved, the next PAUSE command displays in the new, moved
location unless the AT option is used. You cannot specify your own
title for the message box displayed by PAUSE; it will always say
"Message."
The message displayed can be literal text or a dotted variable.
Using a variable, the message displayed is dynamic and easily
changed. The same command can display different messages depending on
program conditions. The following command shows how to use a variable
in the PAUSE command.
SET VAR vmsg TEXT = `This is the message text.'
PAUSE 2 USING .vmsg
Most of the different PAUSE command options, for example, PAUSE 3,
are valid for R:BASE 5.5 for DOS only. In 5.5 for Windows, we
recommend using the PAUSE 2 command unless you want to automatically
clear the screen after the user clicks OK, then use PAUSE 1. Another
option available in Windows is to require the user to press a key to
clear the message box from the screen, or to program the PAUSE
command to automatically clear the message box after a specified
number of seconds. When you use the FOR option to automatically clear
the message box after a specified time, the user can also clear it
themselves by clicking OK. The following command clears the message
box after 30 seconds. The display is the same as for the command that
requires a keystroke.
PAUSE FOR 30 USING `The sales report has finished printing.'
Since the command can require the user to press a key in order to
clear the message from the screen, the PAUSE command is the best
display option to use for short, informational messages you want to
be sure the user reads. The application continues only after the
user clears the message from the screen.
Using the DIALOG command
The DIALOG command is used to display messages too long for the PAUSE
command. The DIALOG command can display messages up to 750 characters
(15-50 character lines). In addition, you can put a custom title in
the DIALOG message box.
The DIALOG command displays in a standard Windows style message box
with the word "Message" as the box title, an additional title or
short message, and the longer message display within the box. There
are two buttons in the box, OK and Cancel.
Using this technique, your message must first be placed in a
variable, then the variable is used in the DIALOG command. You cannot
use a literal text message. For example,
SET VAR vmsg TEXT = `This is my dialog box message text. +
The message can be more than one line long.'
DIALOG ` ' vmsg, vkey, 4
Notice that a dotted variable is not used in the DIALOG command to
display the message. By default, the DIALOG command displays the
value of the return variable, vmsg, in the message box. By setting
the value of this variable before the command you control the text
that is displayed in the dialog box. Make sure the number of display
lines specified in the DIALOG command is large enough to display the
full message text.
No text displays above the message when the ` ' (quote-space-quote)
is used in the DIALOG command. If you want descriptive text to appear
above the message, insert the text as usual after the keyword DIALOG.
For example,
DIALOG `Click OK when done.' vmsg, vkey, 4
You can also place the additional text in a variable. Because this
variable is replacing a literal text string, the variable is dotted
when used in the DIALOG command. For example,
SET VAR vInfo TEXT = `Click OK when done.'
DIALOG .vinfo vmsg, vkey, 4
The user can type into the dialog box area and change the variable
text, then click either the OK or the Cancel button. If they have
changed or added text by typing in the dialog message area, the OK
button will save the changes to the variable, the Cancel button will
not.
The DIALOG command can also be used to display a Yes/No question to
the user. However, when used with the Yes/No option, the message text
is limited to 50 characters.
Like the PAUSE command, the DIALOG command uses the AT option to
position the box at a particular screen location. If no location is
specified the box is displayed in the center of the screen. The user
can grab the box and move it to any location on the screen. The
position is not remembered, however. Each time the DIALOG command is
issued the box displays in the center of the screen or at the
location specified by the AT option.
The DIALOG command is useful for displaying longer messages that the
user must read since it requires pressing a key to remove the message
from the screen. The application continues only after the dialog box
message is cleared from the screen.
Using an MDI form
Both the PAUSE command and the DIALOG command require the message box
to be cleared from the screen for the application to continue
processing. These commands can't be used to display a message that
stays on the screen while a report is printing, for example. To
display a message and have the message remain on the screen while
the application continues other processes, you can use an MDI form.
To make a generic form for displaying messages, first create a new
custom form based on a dummy table or a database table with only a
few rows of data. Modify the form settings to turn off the runtime
toolbar and select no menus for adding or editing data. Place a
single variable object, vmsg, on the form. The variable can be
defined as a literal text string, or can be set to a value in the
application. Use the object properties to customize the color and
font of the message (the variable vmsg). You can add a 3-D box or
other customization features to the form as well. If you are
displaying a long message, be sure to set the object properties so
that the text will wrap.
Once the form is created, you call it from your application using the
EDIT MDI command syntax. Using a form you have the option to specify
a custom window title, a location using the AT option, and the size
of the message window display. Be sure to minimize the "R:BASE R>
Prompt" window before displaying the form.
SET VAR vmsg = `'This is the message to display. +
It can be more than one line long. +
The message can be displayed in any size font.'
MINIMIZE
EDIT MDI msgform WHERE LIMIT=1 AT 10,20,300,400 AS msgform +
CAPTION `This is my window title'
-- other commands here
CLOSEWINDOW msgform
An MDI form must be closed by your application. The CLOSEWINDOW
command is used to clear an MDI form from the screen. The form can
include a push button object to close the form and clear the message
display from the screen, or you can programmatically close the form
and clear the message, as in the example above.
With the options to specify font size and style, colors, and borders
through a form object, an MDI form provides many more customization
features for the messages displayed to the user than either the PAUSE
or DIALOG commands.