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
     You'll use these new features of R:BASE 5.5.
       Combo boxes
       Radio buttons
       Check boxes
       EDIT MDI formname AT location AS aliasname
     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. 
     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.
     -- validate data
     IF vdate1 IS NULL THEN
       PAUSE 2 USING 'You must enter a beginning date.'
       SKIP TO vdate1
     IF vdate2 IS NULL THEN
       PAUSE 2 USING 'You must enter an ending date.'
      SKIP TO vdate                      
     IF vdate2 < .vdate1 THEN
       PAUSE 2 USING +
     'Ending date must be greater than beginning date.'
       SKIP TO vdate2
     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
     -- set the return variable
     SET VAR vreturn = 'OK'
     -- playback the [Esc] key
     PLAYBACK esc.pla
     -- set the return variable
     SET VAR vreturn = 'Cancel'
     -- playback the [Esc] key
     PLAYBACK esc.pla
     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.
     -- 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
     -- run the form
     EDIT MDI dialog_form AT 10,100,430,470 AS dialog1 +
       CAPTION 'Choose Print Options'
     SETFOCUS dialog1 WAIT
     CASE 'OK'
       IF vdevice = 'File' THEN
         SET VAR vdevice = .vfile
       IF vcompany IS NOT NULL THEN
         OUTPUT .vdevice
         PRINT salesrpt +
           WHERE transdate BETWEEN .vdate1 AND .vdate2 +
           AND company = .vcompany
         SET VAR vcompany = NULL
         OUTPUT .vdevice
         PRINT salesrpt +
           WHERE transdate BETWEEN .vdate1 AND .vdate2
     CASE ' Cancel'
     SET VAR vreturn =NULL, vcompany = NULL, +
             vdevice = 'Printer', vwhere = NULL
     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
     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))
     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
         SET VAR vwhere = NULL
         OUTPUT .vdevice
         PRINT salesrpt
     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
     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.