PreviousCreating a Web Database Application Completing and Running Your Windows GUI ApplicationNext

Chapter 12: Creating a Windows GUI Application

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 need to have read the chapter Start Here for the Tutorials and worked through the first session, Using NetExpress, before you do this session.

12.1 Overview

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.

12.1.1 Creating a Screenset

There are four steps in creating a screenset:

  1. Define the windows and dialog boxes, and their properties such as status bars and toolbars.
  2. Define the data items that will hold data to be passed between the user interface and the COBOL program.
  3. Define the controls (such as entry fields and pushbuttons) to appear on the windows and dialog boxes.
  4. 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.

12.2 Preparation

If you have closed NetExpress, open it as before. If any project window or other windows are open, close them.

12.3 Sample Session

In this sample session you:

  1. Create the project and screenset
  2. Define data items for the screenset
  3. Add controls to the screenset
  4. Add dialog to the screenset
  5. Build the application
  6. Test the screenset

12.3.1 Creating the Project and Screenset

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

  1. Click New on the File menu, then select Dialog System Screenset on the New dialog box, and click Yes.

  2. Click OK on the message asking if you want to create a project.

  3. Select Windows GUI Project. Enter Welcome as the name of the project, and d:\NetExpress\Base\Demo\Welcome as the folder to contain the project, then click Create.

  4. 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.

  5. Overwrite the default screenset name NewSet.gs with Welcome.gs (leave the path unchanged) and click Next. (If this session has been run previously, you will be asked whether to overwrite the existing Welcome.gs. Click Yes.)

  6. Select Yes to create a Multiple Document Interface (MDI) application, enter 2 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.

  7. Select Status Bar and Main window 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.

  8. 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.

  9. Ensure Generate skeleton COBOL program is checked and d:\NetExpress\Base\Demo\Welcome\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.

  10. 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.

12.3.2 Your Screen at this Point

You screen now looks something like Figure 12-1. The positions of the three individual windows may vary. You may want to move them around your screen so you can see them all clearly.

Form

Figure 12-1: The Screen with Dialog System Loaded

The two new windows are:

You may want to bring the project window to the foreground (click in it) to see how the project has changed. Then click in Dialog System and WIN-01 to bring them to the foreground again.

12.3.3 Defining 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.

  1. Click Data block on Dialog System's Screenset menu.

    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.

  2. Ensure that Prompted mode on the Data Definition window's Options menu has no checkmark by it. (If it has, click it.)

  3. Click in the Data Definition window to select it, then page down to the end of the existing items, and press Enter.

  4. 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.

  5. 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 12-2.



    Figure 12-2: Data Definition Window with Data Declarations

  6. Click Exit data definition on the Data Definition windows's Edit menu.

    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.

  7. Click Generate on Dialog System's File menu, then click 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.

  8. Click Save on Dialog System's File menu.

12.3.4 Adding 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. The rectangular outline at the top, marked Welcome TBar, indicates the presence of a menu bar and tool bar, and the one at the bottom, marked Welcome SBar, indicates the presence of a status bar.

In an MDI, the parent window is only a frame for the child windows; you cannot put objects on it. The child windows are what the user actually uses. We have created an MDI with two child windows to show how it's done, but we will use only one of the child windows.

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 by 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.

  1. Move WIN-01 up your screen, then drag its bottom right-hand corner to make it bigger, so you can see the bottom right-hand corner of WIN-02. Then drag that to make WIN-02 smaller, so it fits easily between the two rectangles marked Welcome TBar and Welcome SBar. Then change WIN-01 back to its original size - just big enough to enclose these two rectangles.

  2. Click anywhere within WIN-02 to ensure it's selected, and click Properties on Dialog System's Edit menu. (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.

  3. Overtype the default title WIN-02 Window Title with Welcome. Accept the rest of the default settings and click OK.

  4. 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.

  5. Double-click on the entry field.

    The Entry Field Properties dialog box appears for you to define the properties of the entry field.

  6. Overtype the default name EF1 with I-NAME-DISP.

    This gives the name I-NAME-DISP to the entry field.

  7. 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.

  8. 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.

  9. Accept the default choices for the remaining properties, and click OK.

  10. 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.

  11. Double-click on the label to display the Text Properties dialog box.

  12. Overtype the default text Text with Enter name, and click OK.

  13. 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".

  14. 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.

  15. Double-click on the button.

    The Pushbutton Properties dialog box appears for you to define the properties of the button.

  16. 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 12-3.



    Figure 12-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.

  17. Click Save on Dialog System's File menu.

12.3.5 Adding 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.

12.3.5.1 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.

  1. Click Global dialog on Dialog System's Screenset menu.

    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).

  2. Click Exit dialog defn on the Dialog Definition window's Edit menu.

12.3.5.2 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.

  1. On your window Welcome, 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.

  2. Type * The Start button returns to the calling program, then press Enter.

    Anything after an asterisk on a line is treated as a comment.

  3. 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.

  4. 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.

  5. Click Exit dialog defn on the Dialog Definition window's Edit menu.

  6. Click Save on Dialog System's File menu.

12.3.6 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):

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

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.

12.3.7 Building the Application

To build the application:

  1. Click Rebuild All on the Project menu.

    NetExpress compiles the programs, and builds the executable file. Wait until the message "Rebuild Complete" appears in the Output window before continuing.

12.3.8 Testing 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.

  1. Click Run on Dialog System's File menu.

    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 12-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 NetExpress Class Library. For details, and to see how to amend the Wizard-created toolbar and menu bar, see the Dialog System User 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 theDialog System User 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. This is a debugger for dialog, similar in concept to the COBOL debugging features in the IDE. The dialog box enables you to do the following:

  2. Click the Start button you defined.

    The dialog box shown in Figure 12-5 appears.



    Figure 12-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:

    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.

  3. Click Abort.

  4. Click Exit on Dialog System's File menu.

12.4 Before Continuing

In the next session, Completing and Running Your Windows GUI Application, you get this application working fully. If you're planning to go onto that session right away, you can keep the project open. 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 NetExpress entirely, with or without closing the project first.

Copyright © 1998 Micro Focus Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.
PreviousCreating a Web Database Application Completing and Running Your Windows GUI ApplicationNext