828.TXT
=====================================================================
Add Dialog Boxes to Your Applications
=====================================================================
PRODUCT: R:BASE VERSION: 5.5 for Windows or Higher
=====================================================================
CATALOG: Programming in R:BASE AREA : General Information
=====================================================================
Make your applications more Windows-like by using dialog boxes
instead of pop-up menus in applications. You build your own custom
dialog box using an MDI form. You can build your own "Print" dialog
box for printing specific reports, call the Where Builder, put hot
keys on buttons, check that valid data is entered_the possibilities
are endless. The form collects data from the user into variables,
then the variable data is used to print a report or run other
commands.
You'll use these new features of R:BASE 5.5.
Combo boxes
Radio buttons
Check boxes
EDIT MDI formname AT location AS aliasname
SETFOCUS
MINIMIZE, MAXIMIZE
PRNSETUP
CAPTION
Features from 5.1 that you'll use are push buttons, 3D boxes, hot
keys on push buttons, playback files, and EEPs. Some of these
features have been enhanced in 5.5.
The following steps go through the basic process for building a
"dialog box" form:
1. Because a form requires a table, create a "dummy" table in your
database. This is a single-column table. The table is used as the
driving table for the "dialog box" form.
CREATE TABLE dummy (column1 INTEGER)
2. Add one row of data to the table so that you can call the "dialog
box" form with the EDIT command.
INSERT INTO dummy VALUES 1
3. Start the Form Designer and create a new custom form. Select
dummy as the form table.
4. Choose Layout: Form Settings. Uncheck the option "Use Form for
Entering data". Click the Change Edit Menu... button. Select
"No Menu", and click the OK button. Uncheck the option "Runtime
Toolbar". Click the OK button to leave the "Form Settings" dialog
box and save your changes.
5. Choose Layout: Resolution Guidelines... to define an area on the
form. Define a custom area, 400 x 350 is a good size to start with.
This option makes it easy to design the "dialog box" form to be a
specific size, and provides the coordinates for displaying the form
at runtime.
6. Place the desired objects (combo boxes, push buttons, radio
buttons, etc.) on the form. All of the objects are based on, or
return values back to, variables. Make note of the EEP file names
associated with located push buttons. Place an EEP at the table
level, "After Leaving Sec.", to execute on leaving the form. This
EEP checks how the user left the form and performs the desired
actions when the user clicks the OK button. Save the form.
7. Write the EEPs called by the push buttons and the exit EEP. You
can use RBEdit or any ASCII text editor. See below for tips on
writing EEPs for some of the common push buttons you'll put on a
"dialog box" form.
8. Write the command file that controls access to the form.
9. Test the command file and the form.
10. Add the command file to your application. From the "Menu Item
Actions" dialog box, select "Custom Actions" from the New Action
list. Refer to online Help or the User's Manual for more information
on adding custom code to your application.
OK and Cancel Push Buttons
Forms created using the no menu option can only be exited by [Esc] or
by using the form window's system menu. You can place OK and Cancel
push buttons on the form and have the push buttons execute an [Esc]
keystroke when pressed. The [Esc] keystroke is generated by a
playback file. Using push buttons gives the form developer control
over actions after the form is closed and provides easily visible
instructions to the form user.
The push buttons call separate EEPs, but the EEPs can call the same
playback file to execute the [Esc] keystroke. To create the playback
file, start the text editor, RBEdit, and open a new file. Enter
"[Esc]", then choose File: Save Playback File. Name the file
esc.pla. The file contains the single keystroke [Esc].
The EEP called by the OK push button validates data that was entered
as well as exiting the form. The EEP called by the Cancel button just
exits the form. In addition, the EEPs set a variable so that you know
which button the user clicked to leave the form, or if the user just
pressed [Esc] or left by using the system menu to close the form
window. The controlling command file, control.rmd, checks this
variable, vreturn, to determine what action to perform.
*(OK.EEP)
-- validate data
IF vdate1 IS NULL THEN
PAUSE 2 USING 'You must enter a beginning date.'
SKIP TO vdate1
RETURN
ENDIF
IF vdate2 IS NULL THEN
PAUSE 2 USING 'You must enter an ending date.'
SKIP TO vdate
RETURN
ENDIF
IF vdate2 < .vdate1 THEN
PAUSE 2 USING +
'Ending date must be greater than beginning date.'
SKIP TO vdate2
RETURN
ENDIF
IF vfile IS NULL AND vdevice = 'File' THEN
PAUSE 2 USING +
'You must enter a file name, output is set to File.'
SKIP TO vfile
RETURN
ENDIF
-- set the return variable
SET VAR vreturn = 'OK'
-- playback the [Esc] key
PLAYBACK esc.pla
RETURN
*(CANCEL.EEP)
-- set the return variable
SET VAR vreturn = 'Cancel'
-- playback the [Esc] key
PLAYBACK esc.pla
RETURN
The Controlling Command File
The controlling command file initializes variables and calls the
form, Before calling the form, the file sets the return variable to
null or to a value other than "OK" or "Cancel". The new R:BASE 5.5
form management commands are used to display the form in a window and
set focus to that form. The CAPTION keyword on the EDIT command
specifies the window title when the form displays.
After the form is closed, focus returns to the command file. The
return variable is checked and determines how the user left the form
and then actions are executed based on the values the user entered
in the form. The file control.rmd is run from the "R:BASE R> Prompt"
window or added to an application as custom code.
*(control.rmd)
-- initialize variables for the form
SET VAR vreturn TEXT = NULL, vcompany TEXT = NULL, +
vdevice TEXT = 'Printer', vwhere TEXT = NULL
-- set the size of the R> prompt window
MINIMIZE
-- run the form
EDIT MDI dialog_form AT 10,100,430,470 AS dialog1 +
CAPTION 'Choose Print Options'
SETFOCUS dialog1 WAIT
MAXIMIZE
SWITCH(.vreturn)
CASE 'OK'
IF vdevice = 'File' THEN
SET VAR vdevice = .vfile
ENDIF
IF vcompany IS NOT NULL THEN
OUTPUT .vdevice
PRINT salesrpt +
WHERE transdate BETWEEN .vdate1 AND .vdate2 +
AND company = .vcompany
OUTPUT SCREEN
SET VAR vcompany = NULL
ELSE
OUTPUT .vdevice
PRINT salesrpt +
WHERE transdate BETWEEN .vdate1 AND .vdate2
OUTPUT SCREEN
ENDIF
BREAK
CASE ' Cancel'
RETURN
BREAK
DEFAULT
BREAK
ENDSW
SET VAR vreturn =NULL, vcompany = NULL, +
vdevice = 'Printer', vwhere = NULL
RETURN
When the user leaves the form by clicking the OK button, the return
variable is set to "OK" in ok.eep. When the user leaves the form by
clicking the Cancel button, the return variable is set to "Cancel" in
cancel.eep. When the user leaves the form by pressing [Esc], the
return variable is null or the pre-defined value. This lets you, as
the application developer, determine the key the user left the form
with. The command file prints the report, or does other processes
only if user left the form by clicking the OK button.
Listing Reports or Forms
To access a list of reports or forms from a combo box in a form, you
need to first build a view. System tables cannot be accessed from
combo boxes or pop-up menus, but a view can be. For example:
CREATE VIEW listrep (report_name, report_desc) +
AS SELECT sys_report_name, sys_comment +
FROM sys_reports2
In the Form Designer, place a combo box. The combo box draws its data
from the view listrep and places the resulting report name into a
variable, vreportname.
To retrieve the table or view the report is based on, use this
command:
SELECT sys_report_table INTO vtable +
FROM sys_reports2 +
WHERE sys_report_name = .vreportname
To retrieve the table or view a form is based on, use this command:
SELECT sys_form_table INTO vtable +
FROM sys_forms2 +
WHERE sys_form_name = .vformname
If you include the report description along with the report name by
using the Expression option in the combo box, you'll need to parse
the report name out of the expression. A combo box returns the
expression value to the form when you use the Expression option.
IF vreportname CONT '-' THEN
SET VAR vreport = (SGET(.vreportname,(SLOC(.vreportname,'-')-1),1))
ENDIF
A Where Builder Button
To call the Where Builder from a push button in a form, use the
CHOOSE command with the #WHERE option. The CHOOSE command needs a
table or view name as part of the #WHERE syntax. You can code the
table name directly in the command, or retrieve it from the database
if the user selected a report or form. For example, an EEP on a Where
Builder push button might contain these commands:
SELECT sys_table_name INTO vtable ind1 +
FROM sys_reports2 +
WHERE sys_report_name = .vreportname
CHOOSE vwhere FROM #WHERE IN &vtable
If you are displaying the WHERE clause on the form, be sure to
include a RECALC VARIABLES command in the EEP.
Only the table or view specified in the CHOOSE command is available
in the Where Builder. You can type directly in the edit box to add
WHERE clause conditions referencing other tables and columns. The
CHOOSE command returns the WHERE clause conditions and includes the
word WHERE as part of the variable data. Use the variable as an
ampersand variable. For example:
PRINT salesrpt &vwhere
The user can test their WHERE clause in the Where Builder, the
application developer needs to check the variable vwhere in the
command file to see if the user built a WHERE clause using the Where
Builder. For example:
IF vwhere IS NOT NULL THEN
OUTPUT .vdevice
PRINT salesrpt &vwhere
OUTPUT SCREEN
SET VAR vwhere = NULL
ELSE
OUTPUT .vdevice
PRINT salesrpt
OUTPUT SCREEN
ENDIF
A Print Setup Button
You can place a Print Setup button on your "dialog box" form and use
the new PRNSETUP command to call the Windows "Print Setup" dialog
box.
*(prnsetup.eep)
PRNSETUP
RETURN
A Help Button
You cannot use the ZIP command in an EEP, so a help push button can't
call a Windows help file. Instead, call another form that displays
data from a table. The table can use a VARCHAR data type column to
hold the formatted help text.