Chapter 2: Creating a Windows GUI Application

You need to do the tutorials in this book in the order shown by the Tutorials Map.

You need to have installed Dialog System to do this session.

Overview

In this and the next session you create a Windows graphical application.

In this session, you use Windows GUI Application Wizard and Dialog System to create the user interface and the program to process the data. You use the IDE to run the application to see the appearance of the interface.

In the next session, Completing and Running Your Windows GUI Application, you add the business logic to the program and run the complete application.

You use Windows GUI Application Wizard to create windows and dialog boxes for display on a Windows system. These are the user interface to your application. From within this Wizard, you enter Dialog System, where you design and edit their layout. The set of windows and dialog boxes you design is called a screenset. Dialog System creates a screenset file defining the windows and dialog boxes you create.

You also use Dialog System to generate a COBOL program to handle the screenset. This is called the associated program.

Creating a Screenset

There are four steps in creating a screenset:

Define the windows and dialog boxes, and their properties such as status bars and toolbars.
Define the data items that will hold data to be passed between the user interface and the COBOL program.
Define the controls (such as entry fields and pushbuttons) to appear on the windows and dialog boxes.
Write dialog to define what will happen when the user does something at the interface, such as clicking a pushbutton.

You write the dialog mentioned in Step 4 in Dialog System's own scripting language.

Generally, the Dialog System documentation uses the term graphical objects, or just objects, when talking about controls.

Preparation

If you have closed Net Express, reopen it. If any project window or other windows are open, close them.

Create the Project and Screenset

You could start by creating a project in the way described in the chapter Using Net Express, but if you go straight ahead and create the screenset Net Express will give you an opportunity to create the project. To create the screenset:

Click File > New, then select Dialog System Screenset on the New dialog box, and click OK.
Click Yes on the message asking if you want to create a project.
Select Windows GUI Project. Enter Welcome as the name of the project. Enter Examples\Net Express IDE\Welcome as the folder to contain the project; this folder doesn't exist yet, so either type it or use the Browse button to set the field to Examples\Net Express IDE and then type \Welcome on the end. Then click Create.
Click Yes when asked whether or not you want to create this directory. (If this session has been run previously, you will instead be asked whether to overwrite the existing project. Click Yes.)
The project window for the project appears. So does the first page of Windows GUI Application Wizard.
Overwrite the default screenset name NewSet.gs with Welcome.gs and click Next. (If this session has been run previously, you will be asked whether to overwrite the existing Welcome.gs. Click Yes.)
Select Yes to create a Multiple Document Interface (MDI) application, enter 1 as the number of MDI children, and click Next.
A Single Document Interface (SDI) consists of just one window. An MDI consists of a number of windows and/or dialog boxes, with one window as their parent.

In an MDI, the parent window is only a background to frame the child windows; you cannot put objects on it. The child windows are what the user actually uses.
Select Status Bar and Toolbar, and click Next.
This specifies that the main window is to have a status bar and toolbar, and also a menu bar - the toolbar and menu bar are created together.
Click Next twice.
The two dialog boxes you are skipping enable the use of Dialog System Extensions, and enable you to modify run-time behavior. We will accept the defaults.
Ensure Generate skeleton COBOL program is checked and Welcome.cbl is the name of the COBOL program to generate, and click Next.
The next dialog box shows a summary of what you have selected.
Click Finish.
The Windows GUI Application Wizard generates the screenset and program, and finishes. The names of the generated files are added to the project, then the project is scanned for dependencies.

Then Dialog System is loaded.

The Dialog System Windows

The Dialog System windows shown in Figure 2-1 appear. The positions of the individual windows may vary. You may want to minimize the Net Express IDE so you can see these new windows clearly.

Figure 2-1: The Dialog System Windows

The two new windows are:

WIN-01
The window titled "WIN-01 Window Title" is where you will design your screenset. This window WIN-01 is the main window of your screenset. A child window, WIN-02, is shown within it because we specified it as an MDI.
Dialog System's own window
This consists of menu bar, toolbars and status bar, with the title "Dialog System - Welcome.gs" above and "Editing WIN-02" below. Initially it may overlap WIN-01 on your screen.

Also, look at the IDE to see how the project has changed.

Define Data for the Screenset

On-screen objects that contain data - objects such as entry fields - need to be associated with data items. Data is passed between these data items and the on-screen objects.

In this tutorial we define the data items now and the objects in a later section. It's not essential to do it this way round. As you'll see later, you can test the appearance and behavior of your screenset without data. However, it's generally best to define your data first, so that you have a clear idea of what information has to be passed to, and obtained from, the user. You can change the appearance of the screenset without changing any data definitions.

The data items you define are called the data block. When the generated program calls Dialog System's run-time support module, DSGRUN, it passes the data block as a parameter. This is how data is passed between the COBOL program and the screenset.

To define data items, you use the Dialog System window. Ignore WIN-01 for now.

Dialog System provides two modes of entering data field definitions. In Prompted mode you are prompted with lists of choices and dialog boxes to complete. This helps if you are not familiar with the syntax of data declarations in Dialog System. In unprompted mode (also called editor mode) you type the declarations directly. We will use unprompted mode.

In the Dialog System window, click Screenset > Data block.
The Data Definition window appears. Specialized edit windows like this are used throughout Dialog System for entering different kinds of information. It has its own menu, which we will be using in the next few steps.

You can see some data declarations already present. These were automatically generated when the screenset was created. They are used in the maintenance of the MDI, toolbar, menu bar, and status bar, and you can ignore them.
On the Data Definition window's Options menu, ensure that Prompted mode has no checkmark by it. (If it has, click it.)
Click in the Data Definition window to select it, then page down to the end of the existing items, and press Enter.
Type: I-NAME X 12.0 and press Enter.
The line is automatically formatted. You can even type in lower case, and it will be changed automatically to upper case. You have now defined your first data item, I-NAME. The X means it is alphanumeric, and the 12.0 means it is 12 characters long with no decimal spaces. The ".0" must be present, even though the field is alphanumeric; however, you can omit it, and it will be automatically inserted.

Because these data items will be accessed from the generated COBOL program as well as from Dialog System, you have to avoid COBOL reserved words (no warning is given if you use one). This is why we've called it I-NAME rather than NAME.
Type: GREETING X 22.0 and press Enter.
This is your second data item, GREETING. It is alphanumeric and 22 characters long.

The Data Definition window should now look like Figure 2-2.

Figure 2-2: Data Definition Window with Data Declarations
In the Data Definition window, click Edit > Exit data definition.
Although the data definitions disappear from the screen, they are still loaded in memory. They will not be saved to disk till you do a Save later to save the screenset.

When Dialog System generated the screenset and the COBOL program earlier, it generated a copyfile (.cpb) containing a definition of the data block, in COBOL. This copyfile is used in the Working-Storage Section of the generated program, which is where the data is actually held. Now that you have changed the data block you must regenerate this copyfile.
In the Dialog System window, click File > Generate > Data block copyfile, accept the default Welcome.cpb as the name of the copyfile, and click Save. Click Yes to confirm the existing copyfile is to be overwritten.
Always remember to regenerate this copyfile whenever you change the data block.

Before going on to the next section, let's save the screenset to safeguard our work so far.
In the Dialog System window, click File > Save.

Add Controls to the Screenset

Next you specify the appearance of the user interface. We have already added a status bar, toolbar and menu bar, when we created the screenset, but we now need to add text and entry fields. Controls such as these are generally referred to as "objects" in Dialog System.

The window now visible on the screen, WIN-01, is the parent, or main window, of your screenset. It frames the child window WIN-02, which is the one we actually use.

You add objects by using the Object menu or the object toolbar. The object toolbar is quick and easy for mouse users, whereas the menu can also be used by keyboard users. The two are completely equivalent. This session uses the object toolbar.

Dialog System gives all the windows the same initial size. Let's start by resizing them so you can see the whole of WIN-02 within WIN-01.

By dragging their corners, resize WIN-01 and WIN-02 so that WIN-02 fits completely within WIN-02.
Click anywhere within WIN-02 to ensure it's selected, and then in the Dialog System window click Edit > Properties. (Alternatively you can right-click in WIN-02, and click Properties on the popup menu, or simply double-click in WIN-02.)
The Window Properties dialog box is displayed for you to edit the properties of WIN-02.
Overtype the default title WIN-02 Window Title with Welcome. Accept the rest of the default settings and click OK.
Click the Entry Field button on the object toolbar, then click in the WIN-02 window.
This creates an entry field - a field where your end-user can enter or display data - at the place where you clicked. You can drag it around with the mouse after you have placed it. Put it towards the right-hand side of the window.
Double-click on the entry field.
The Entry Field Properties dialog box appears for you to define the properties of the entry field.
Overtype the default name EF1 with I-NAME-DISP.
This gives the name I-NAME-DISP to the entry field.
Click Master field.
The Master Fields dialog box is displayed. This lists the fields in the Data Block, so you can link the appropriate data field with the entry field.
In the Master Fields dialog box, page down to the field I-NAME, click it, and then click OK.
The "Master field" field now displays I-NAME, and the "Picture string" field is automatically set to X(12). This means the entry field I-NAME-DISP will be 12 characters long, alphanumeric, and will display whatever data is in the data item I-NAME.
Accept the default choices for the remaining properties, and click OK.
Click the Text button on the object toolbar, and then click to the left of the entry field, to create a label for the entry field.
Double-click on the label to display the Text Properties dialog box.
Overtype the default text Text with Enter name, and click OK.
In the same way, add a second entry field and label. Use "GREETING-DISP" as the name of the field, and select GREETING as its master field. Set the label to "Greeting".
Click the OK button on the Object toolbar, then click in the WIN-02 window to place the button. Put it somewhere toward the bottom of the window.
Double-click on the button.
The Pushbutton Properties dialog box appears for you to define the properties of the button.
Overtype the default name PB1 with START-BUTTON, and overtype the default text ~Pushbutton with Start. Accept the default choices for the remaining properties, and click OK.
You should now have a screenset that looks something like Figure 2-3.

Figure 2-3: Your Screenset with the Entry Fields, Text Fields and Pushbutton

Before going on to the next section, let's save the screenset to safeguard our work so far.
In the Dialog System window, click File > Save.

Add Dialog to the Screenset

So far you have defined the appearance of your window, and defined data items to hold data received from (or for display on) the fields on the window. But when the user uses the window - for example, clicks the Start button - nothing will happen. You define the effect of user actions by writing dialog script, generally referred to as just dialog.

User actions, such as pressing a key or clicking a mouse button, generate events. You write procedures to be executed in response to each event.

You can attach dialog to a particular object - a control or a window - or make it global. This is called the scope of that dialog. Dialog attached to an object is called local. When an event happens on an object, Dialog System looks first for dialog attached to that object. If there is none, Dialog System looks for dialog attached to the window that the object is on. If there is none, Dialog System looks for global dialog.

We need to write dialog so that when the user clicks the Start button, DSGRUN returns to the calling program. Of course we want the data that the user has entered to be moved into the fields in the data block first, but this happens automatically because of the master field associations you defined earlier - you don't need to write dialog to do this.

As with defining data, Dialog System provides a choice of prompted mode or unprompted mode. We will use unprompted mode.

Global Dialog

In this example we don't need to write any global dialog, but it will be useful to look at some that has been generated automatically.

In the Dialog System window, click Screenset > Global dialog.
The Dialog Definition window appears. You can see some dialog already present. This was automatically generated when the screenset was created, to implement the run-time behavior defaults selected in the Wizard.

The first procedure consists of the event ESC and the two functions MOVE and RETC. This specifies that on the event ESC (generated when the user presses Esc), DSGRUN will move 1 to the data item EXIT-FLAG and then return to the calling program.

Because this dialog is global, this procedure will be executed whenever Esc is pressed, regardless of what object currently has focus - unless that object, or the window it is on, has its own dialog for ESC.

The second procedure specifies the same effect for the event CLOSED-WINDOW (generated when the user closes a window).

The rest of this dialog maintains the MDI, menu bar, toolbar and status bar, and you can ignore it.

A procedure in Dialog System is called a dialog table. It consists of an event or procedure-name followed by one or more functions that will be performed if the event occurs or the procedure-name is explicitly performed from another procedure. A complete list of Dialog System events and functions can be found in the Help.

The order in which procedures appear does not matter - unlike in COBOL, control does not fall through from the end of one procedure into the next. At the end of a procedure, DSGRUN simply stops and looks for the next event (unless the last function was RETC, which returns to the calling program).
In the Dialog Definition window, click Edit > Exit dialog defn.

Local Dialog

Now let's write the dialog to make the Start button work. Since this dialog applies only to this one object, we will make it local dialog, attached to this object.

In your Welcome window, right-click on the Start button and click Dialog on the popup menu.
The Dialog Definition window appears. Dialog System has started the dialog off for you by inserting the name of the event you're most likely to want to write dialog for on this type of object. BUTTON-SELECTED (generated when the user clicks the button) is indeed what we want.

The highlight is already positioned on the line below the event, ready for you to type.
Type * The Start button returns to the calling program, then press Enter.
Anything after an asterisk on a line is treated as a comment.
Type RETC and press Enter.
The line is automatically formatted. You can even type in lower case, and it will be changed automatically to upper case. Dialog System recognizes RETC as the name of a function, and positions it indented.
Type REFRESH-OBJECT GREETING-DISP and press Enter.
The dialog should now be as follows:
```
 BUTTON-SELECTED
* The Start button returns to the calling program
    RETC
    REFRESH-OBJECT GREETING-DISP
```
RETC makes DSGRUN return to the COBOL program. When DSGRUN is next called, it continues from where it left off. Often RETC is the last function in a procedure, and so DSGRUN, when it is reentered, finds the procedure finished and simply waits for the next event. However, in this case we want DSGRUN to do something more when it's reentered - we need GREETING-DISP updated with the updated data that the COBOL program will have put in its master field GREETING. The REFRESH-OBJECT function does this.

The syntax of functions is given in the topic Dialog Statements: Functions in the Dialog System Help.
In the Dialog Definition window, click Edit > Exit dialog defn.
In the Dialog System window, click File > Save.

Files Created

You have now created your user interface. The Wizard and Dialog System have created the following files for you and added them to the project (you may have to expand the tree view in the project window by clicking the "+" signs to see them):

welcome.gs is the screenset
welcome.cbl is the associated program
welcome.cpb is a copyfile defining the data block in COBOL
welcomeTBar.cbl is a program to handle the toolbar and menu
welcomeSBar.cbl is a program to handle the status bar

It has also added to the project the following object files, created when you build the project:

welcome.int is the compiled associated program.
welcomeTBar.int is the compiled toolbar/menu program.
welcomeSBar.int is the compiled status bar program.

It has also created several copyfiles (extensions .cp*).

Although the filenames are shown above in lower case, some might appear in upper case in the project. Filenames are not case sensitive.

If you ever need to update the screenset, you simply double-click on Welcome.gs in the project window, and Dialog System opens. When you save the updated screenset, the copyfiles are regenerated, so you should not edit them directly.You can however edit the .cbl program that the Wizard generated.

Build the Application

To build the application:

In the Net Express IDE, click Project > Rebuild All.
Net Express compiles the programs, and builds the executable file. Wait until the message "Rebuild Complete" appears in the Output window before continuing.

Test the Screenset

You can run the screenset within Dialog System, without the associated program. This enables you to evaluate and test its behavior, then alter it, if needed, by simply returning to the screenset definition. This is useful for prototyping your interface.

You had to build before doing this, as the toolbar/menu and status bar programs are executed during this testing.

In the Dialog System window, click File > Run.
The Dialog System window and the WIN-01 window disappear, and WIN-01 is displayed as it will appear at run time. Notice that it has a toolbar, menu bar and status bar, as you specified in the Wizard. WIN-02 is visible within it.

Figure 2-4: The Screenset as Displayed by the Run Function

The toolbar and menu bar created by the Wizard are created by generated control programs using the Net Express Class Library. For details, and to see how to amend the Wizard-created toolbar and menu bar, see the Dialog System User's Guide. When you create menus yourself on your windows, you have the additional option of using Dialog System's own integrated system for creating menus. See the chapter Windows and Objects in the Dialog System User's Guide for details of this.

A small dialog box also appears at the bottom right of your screen, with Debug and Abort buttons. When you use this screenset testing facility in Dialog System, the screenset is run under control of the Screenset Animator, a debugger for dialog similar in concept to the COBOL debugging features in the IDE. The dialog box enables you to do the following:
- Debug - display the dialog so you can use Screenset Animator's features such as single-stepping.
- Abort - stop testing the screenset and return to Dialog System.
Click the Start button you defined.
The dialog box shown in Figure 2-5 appears.

Figure 2-5: RETC dialog box

When you clicked Start, the dialog you wrote for this button was executed, and as you'll remember this includes a RETC command. Whenever a RETC is executed, Screenset Animator changes to this dialog box and you must choose what to do next:
- Continue - continue testing the screenset without animation.
- Interrupt - display the dialog so you can use Screenset Animator's features such as single-stepping.
- Abort - stop testing the screenset and return to Dialog System.
If ever you want to debug dialog when you are running a screenset within an application, there is a parameter to DSGRUN to enable the Screenset Animator. The Screenset Animator is documented in the Dialog System Help.
Click Abort.
In the Dialog System window, click File > Exit.

Before Continuing

In the next session, Completing and Running Your Windows GUI Application, you get this application working fully.

If you want to take a break first, you can close the project, and open it again at the start of the next session. Or you can close Net Express entirely, with or without closing the project first.