Chapter 18: Tutorial - Creating a Sample Screenset

In this chapter you follow the steps for creating an application using Dialog System as described in the chapter Introduction to Dialog System.

In this tutorial, imagine you are a director of a road running race that members of the public can enter by sending in entry forms published in various newspapers and sporting magazines. You need to design an interface for a system that will process the entries and allocate a unique running number to each entrant. You also want to monitor the effectiveness of your advertising by recording the response from each advertisement.

The first screen of your interface needs to collect details such as name, address, age, sex, running club, and advertisement code.

To create the screenset for the race entry system, first start Dialog System in the usual way.

18.1 The Sample Data Definition

You do not need to create the data model for the sample screenset. A data model has been created for you, and this section will guide you through defining the data according to that model.

18.1.1 Defining the Data Block

You need to define the Data Block and create master fields for the display fields you will set up as objects. Each entry field has an associated master field in which to store the data entered.

To define the Data Block:

1. Select Data Block on the Screenset menu.

   Dialog System displays the Data Definition window.

2. Select Prompted mode on the Options menu.

   The Data Type dialog box is shown.

3. Select Field and click OK.

   Dialog System displays the Field Details dialog box.

4. Specify NAME, select Alphanumeric, and specify 15 in Int.

   This defines the Name field and is the master field for the object called D-NAME that you will define in the next step.

5. Click OK to create a blank line ready for the next entry.

Now repeat the above process to define the following fields:

Field Name	Field Type and Size	Field Usage
MALE	9(1)	flag field used to hold the state of the radio buttons.
ADDRESS	X(100)	master field for D-ADDRESS.
CLUB	X(30)	master field for D-CLUB.
AGE	X(3)	used in the age list box.
CODE	X(3)	master field for D-CODE.
FLAG-GROUP		Group start with 1 repeat. Used to hold flags.
EXIT-FLG	9(1)	flag used to indicate user has selected Exit.
SAVE-FLG	9(1)	flag used to indicate user has pressed Save.
CLR-FLG	9(1)	flag used to indicate user has pressed Clear.

This completes the Data Block for the sample program. The Data Definition window should now look similar to the one shown in Figure 18-1.

Figure 18-1: Data Definition

18.1.2 Creating the Sample Window Object

The sample screenset has a single window containing various control objects, and a message box. You must define the window first, because you do not have access to control objects until you have defined a window on which to place them.

Before you start to define objects, set Auto properties to off, so that you can label objects as you create them:

1. Select Include on the Options menu on the main menu bar.

2. Select Auto properties on the drop down menu.

To define the Primary window:

1. Select the primary window icon on the Objects toolbar or choose Primary window on the Object menu.

2. Move the window box until the top left-hand corner is near the top left of your desktop.

3. Click to fix the position.

4. Enlarge the window by moving the mouse down and right.

   Make the window larger than the Dialog System window.

5. Click to fix its size.

6. When the Properties dialog box appears, specify a name of MAIN and a title of Redvale 5-Miler Entries.

7. Select the Options tab and deselect Menu.

8. Leave the rest of the dialog box unaltered to accept the default property values.

   The screen now looks like the one shown in Figure 18-2.

   
   Figure 18-2: Defining the Main Window

18.1.3 Creating the Sample Control Objects

Now define the controls in the following list by:

1. Selecting them on the Objects toolbar or the Object menu.

2. Placing them in the primary window, to look like Figure 18-3.

   
   Figure 18-3: Adding Controls

3. Making the indicated changes to their properties in their property dialog boxes.

   Leave all the other properties as the default values.

   Text	Label for the competitor name field. Specify Name.
   Entry field	To contain the competitor's name. Specify D-NAME in Name, X(15) in Picture and NAME in Master.
   Text	Label for the competitor address field. Specify Address.
   Multiple line entry field	To contain the competitor's address. Specify D-ADDRESS in Name, 120 in Length and ADDRESS in Master.
   Text	Label for the competitor's club field. Specify Club.
   Entry field	To contain the competitor's running club. Specify D-CLUB in Name, X(30) in Picture and CLUB in Master.
   Radio button	To show the competitor's sex. Specify M in Text and set the Initial state to Enabled.
   Radio button	To show competitor's sex. Specify F in Text and set the Initial state to Enabled.
   Group box	Position over the two radio buttons. Specify Sex in Text.
   Text	Label for age class field. Specify Age class.
   List box	To show the competitor's age class. Select Initial Text Defined. Click on List text and specify the age classes, one per line, as follows: 10-18, 19-35, 36-40, 41-45, 46-50, 51-55, 56-60, 60+. Deselect Horizontal scroll bar check box.
   Text	Label for advertisement code field. Specify Code.
   Entry field	To contain an advertisement code. Specify D-CODE in Name, X(3) in Picture and CODE in Master.
   Push button	Button to enter the data into the competitor data base. Specify "Save" in Text, enable Default Button and set the Initial State to Enabled.
   Push button	Button to clear the current entry. Specify Clear in Text and set the Initial State to Enabled.
   Push button	Button to get help. Specify Help in Text and set the Initial State to Enabled.

Move and size the controls (and the primary window if necessary) to tidy your window.

To make the radio buttons work correctly, you need to place them in a control group. Similarly, the push buttons should be in a control group.

To define control groups:

1. Select Edit.

2. Select Define control group.

3. Position the top left corner of the box that appears.

4. Click and extend the box until it covers the required controls.

5. Click again.

18.1.4 Creating a Message Box

Create a message box to present a help message when the user presses Help:

1. Select a message box object on the Objects toolbar or the Object menu.

   The Properties dialog box is displayed immediately.

2. Specify HELP-MSG in Name.

3. Specify Help in Heading.

4. Specify some suitable help text about the window in Text.

5. Select Information on the Icon drop down list.

This completes the object definitions for the sample screenset.

18.1.5 Saving Your Screenset

It is a good idea to save a screenset whenever you have finished a stage in the definition process. To save this sample screenset:

1. Select Save As because this is the first time you have saved it.

   Dialog System displays a dialog box for you to enter the filename and directory under which you want to save.

2. Specify entries.gs as the name.

After saving the sample screenset once, you can use Save whenever you want to save the screenset. If you want to try out different versions of the screenset, use Save As with a new name to create another version.

18.1.6 Testing

You can test your screenset even without dialog, to make sure that the desktop layout looks good and that you have set up the fields correctly. To test the sample screenset:

1. Select Debug on the File menu.

   Dialog System displays the Screenset Animator window.

2. Now select Run on the Execute menu.

   Your sample screenset should look similar to the one shown in Figure 18-4.

   
   Figure 18-4: Running the Screenset from the Screenset Animator

   Try entering some data into the fields. If you try to enter more than 15 characters into the Name field, Dialog System just produces a beep.

   Notice that you can only select either M or F because the radio buttons are grouped as a control group and you can select only one age class from the list box.

3. Press Esc to return to the Screenset Animator window.

   The "RETC has just been executed" dialog box is shown.

4. Click Interrupt.

5. Select Exit on the Execute menu to return to Dialog System's main window.

The Screenset Animator is more useful after you have defined the dialog for the sample screenset.

18.1.7 Defining Dialog

The sample screenset would not be complete without dialog definitions. The following sections explain how to define the object and global dialog for the sample screenset.

18.1.7.1 The Sample Object Dialog Definitions

To define dialog for an object:

1. Select the Save push button object.

2. Select Object dialog on the Edit menu.

   Dialog System displays the Dialog Definition window. The default event BUTTON-SELECTED is already displayed in the Dialog Definition window.

3. Select Prompted mode on the Options menu.

   Dialog System then prompts you for dialog entries in a similar way to when you define data.

4. Use the cursor key to move down one line.

   Dialog System displays a dialog box for you to choose the type of line you want to enter.

5. Select Comment and enter some text explaining what your dialog does.

   For example, "Dialog System passes control to a procedure that handles creating or changing a record in the entry database".

6. Specify Action when SAVE pressed.

7. Select Function.

8. Select SET-FLAG from the scrollable list.

   A parameter dialog box appears.

9. Specify the name of the flag to be set against parameter 1.

   The spaces for parameters 2 and 3 are disabled because they are not required with this function.

10. Specify SAVE-FLG(1) against parameter 1, to set the Save flag when the user presses Save.

11. Select Function.

12. Select RETC from the scrollable list.

    RETC does not have any parameters. It returns control to the calling program. The COBOL program that uses this screenset checks the Save flag and saves the contents of the screen if the flag is set.

In a similar way you can attach dialog to the other objects in the sample screenset.

Dialog System helps you by providing context menus. If you right-click on any of the dialog lines, Dialog System displays a context-sensitive menu of choices. For a more detailed explanation of context menus, see the chapter Window Objects.

The dialog for the remaining objects is described below.

18.1.7.1.1 Clear Button

Dialog:

 BUTTON-SELECTED
     SET-FLAG CLR-FLG(1)
     RETC

Effect:

When the user presses Clear, Dialog System sets the Clear flag and returns control to the calling program. The calling program will clear the entry fields (effectively cancelling the entry).

18.1.7.1.2 Help Button

Dialog:

 BUTTON-SELECTED
     INVOKE-MESSAGE-BOX HELP-MSG $NULL $EVENT-DATA

Effect:

When the user presses Help, Dialog System displays the message box you created. This provides appropriate help text.

18.1.7.1.3 M Radio Button

Dialog:

 BUTTON-SELECTED
     SET-FLAG MALE

Effect:

When the user presses M, Dialog System sets the flag MALE to 1, meaning M (for male competitor).

18.1.7.1.4 F Radio Button

Dialog:

 BUTTON-SELECTED
     CLEAR-FLAG MALE

Effect:

When the user presses F, Dialog System sets the flag MALE to 0, meaning F (for female competitor).

18.1.7.1.5 Age Class List Box

Dialog

 ITEM-SELECTED
     RETRIEVE-LIST-ITEM $CONTROL AGE $EVENT-DATA

Effect

When the user selects an age class from the list, Dialog System puts the value of the selected list item into the AGE field.

18.1.7.2 The Sample Global Dialog Definition

Now define global dialog for the screenset, by selecting Global dialog on the Screenset menu.

The default global dialog is as follows:

 ESC
     RETC
 CLOSED-WINDOW
     RETC

Add two lines to the dialog so it reads:

 ESC
     SET-FLAG EXIT-FLG(1)
     RETC
 CLOSED-WINDOW
     SET-FLAG EXIT-FLG(1)
     RETC

This dialog sets the exit flag and returns control to your application (the calling) program if the user presses Esc or uses the system menu to close the window.

Add the following dialog:

   REFRESH-DATA
     REFRESH-OBJECT MAIN

This dialog refreshes the main window whenever the calling program directs Dialog System to do so. The chapter Using the Screenset describes how your application program interfaces with the call interface.

Add the following dialog:

   SCREENSET-INITIALIZED
     SET-FLAG MALE
     SET-BUTTON-STATE RB1 1

This sets the first radio button (Male) on as a default. Whenever you enter a group of radio buttons, one of these has to be set on initially.

See the chapter Using Dialog for more information on how to use dialog.

18.1.8 Testing the Screenset Again

Now save the screenset again, then try running the sample again. Enter data into the fields and choose the appropriate radio button and list item. This time, when you press Save after you have made these changes, Dialog System displays the Screenset Animator window again.

18.1.9 Changing the Screenset

After you test the sample screenset again, you may want to make changes to it (for example, to improve the screen layout). You can repeat any of the steps described in this chapter until you are satisfied with the screenset.

18.1.10 Summary

In this chapter, you have:

• Created a sample screenset.

• Defined data.

• Defined objects.

• Saved the screenset.

• Tested the screenset.

• Added dialog to the screenset.

• Tested it again.

• Made any changes by repeating steps as necessary.

Now you need to write the COBOL program that will use the user interface contained in your sample screenset. The DialogSystem\demo\entries directory contains a demonstration version of the sample screenset, called entriesx.gs.

18.2 Further Information

The next chapter, Tutorial - Using the Sample Screenset, gives advice on writing the COBOL program for the sample screenset. The chapter contains sample code to produce a very simple program that will read the user inputs and store or clear them as indicated by the user.