The Graphical User Interface

Creating a Data Definition and Screenset

Chapter 2: Introduction to Dialog System

The previous chapter described the advantages of using a graphical user interface (GUI). This chapter introduces you to the basic concepts which you need in order to use Dialog System when creating GUIs for your COBOL applications. These include:

The benefits of using Dialog System.
An overview of the constituent parts of Dialog System.
The steps that you need to follow to create an application with Dialog System.

2.1 Benefits of Using Dialog System

Dialog System offers you the following benefits:

Independence of the user interface from the main program logic.
When the program requires interaction with the user at run time, it calls Dialog System to handle this. This independence encourages well-structured programming.
Independence of the user interface from the program.
You can create several different user interfaces for the same program.
Ease of defining graphical objects.
Dialog System provides a library of graphical objects that you can tailor for your application and manages these objects' behavior, including stacking and unstacking windows. Dialog System also deals with screen handling, both during definition and at run time.
Complete handling of input, output and navigation between windows.
You can instruct Dialog System to handle user input and output and decide what to display to the user, using a simple set of instructions called dialog.
Automatic Data Block generation.
Dialog System can supply your calling program with the definitions for the Data Block that are needed to interface with Dialog System at run time.
Validation capability.
Dialog System handles most validation of input and can deliver error messages to users. The calling program can also use these error messages if required.
Prototyping and testing.
Dialog System can run the interface in a similar way to the calling program, which gives a high degree of confidence in the validity of the results. You do not need to wait until you have a complete interface as Dialog System enables you to test small parts of the interface as you develop them.

2.2 Overview of Dialog System's Capabilities

Dialog System enables you to design and edit windows and dialog boxes for display on a Windows system and to pass data between this interface and your application program. The two aspects of Dialog System which enable these functions are:

The definition software, which enables the creation and tailoring of the items to appear on your user interface.
The program Dsgrun, which communicates with both your interface and your application program and controls the run-time behavior of your interface components.

This section describes in outline what the definition software is and how it enables you to create a user interface, covering:

The design of your interface and its elements.
How to activate these elements using dialog.
How you link the above parts to your calling program using the Data Block.

2.2.1 Designing Your Interface

The first step when you develop a Dialog System application with a GUI is to design a data model. The model defines the data which is to be both captured by the user interface and provided by the application to be presented to the user.

This data model provides the basic data items that must be passed to the calling program. You must also decide on any validation criteria for these items.

Some of the desirable features you should consider for your user interface are:

User controlled	Users are in control of the interface. They determine the course of action of the application.
Easy to use	The user can move easily and naturally around a window and between windows. The information displayed is well organized, easy to read, and appears uncluttered.
Consistent	The user interface is consistent internally as well as across applications. For example, the Exit choice on a window is always the last option in the File menu. Another example is that any delete action requiresadditional confirmation.
Helpful	Users are given clear, informative feedback on where they are in the system, what actions they have taken, and what action they should take next. It is better for the user to select an item from a list rather than enter the item in a data entry field.
Forgiving	User actions are easily reversed. Error messages explain what the error was, why the error occurred, and possible corrections to the error.
Efficient	System response times are kept as short as possible.
Complete	If a user has a list of choices, all choices are valid and available to the user.
Logical	Choices on a menu are logically organized, with the most frequently chosen item listed first or with the items listed alphabetically.

You also need to consider how the user interacts with the data – the user interface.

The user interface you build can take many forms, ranging from simple menu selection and data entry fields to fully developed windows complete with menu bars, radio buttons and other controls.

The level of sophistication of the interface you choose depends on many factors including:

Who the users are and their level of training.
The hardware and software resources available.
The complexity of the task to be performed.

In all cases:

The user determines the normal course of action.
The user, rather than your program, is in control of the interface.
The user interaction with the computer should be as simple and natural as possible.

The basic visual elements which you define for your user interface are called objects. These objects, such as windows, dialog boxes and push buttons, appear on an area bounded by the screen, in which everything else appears.

In Dialog System, there are two main categories of objects:

2.2.1.1 Window Objects

These are the most basic (and often the most important) objects. They can be primary or secondary and are very similar to dialog boxes and message boxes. The appearance of windows and dialog boxes is the same at both definition and run time.

You can define window objects at any time and place them anywhere on the desktop. You can move these objects by dragging the title bar and you can size windows using their sizable borders. When selected, you see them surrounded by a colored, shaded border.

For further information, see the chapter Window Objects.

2.2.1.2 Control Objects

All other objects are control objects. These are the objects that appear in the windows and include entry fields, push buttons, radio buttons, check boxes and list boxes.

You can define other control objects which extend Dialog System's default range of objects. When you define such a control object, Dialog System can generate a tailored controlling program for the control.

The two types of additional controls that you can define are:

User controls.
These enable the definition of a container or outline for objects not paintable by Dialog System.

At definition time, the generated controlling program name appears inside the control's outline. Specifying a meaningful name helps you to identify the control and its purpose in the GUI.
ActiveX controls.
These are third-party supplied controls. You need to create the program code to create and manipulate them at run time. When selected, you see them as they appear at run time.

Both of these types of controls are described in the chapters Control Objects and Programming Your Own Controls.

2.2.1.3 Object Properties

Every window object and control object has properties, for example, background color. You can change these properties to specify the object's appearance and behavior.

You can use the default properties of an object by selecting Include on the Options menu and selecting Auto properties. In this case Dialog System uses the default property values for that object and does not display the Properties dialog box. You can change the properties of the object using the Properties dialog box by selecting Properties on the Edit menu or double-clicking on the object.

If Auto properties is not selected, Dialog System immediately displays the Properties dialog box for an object, so you can set the properties. If you click Cancel in this dialog box at this stage, the object is removed. If you click OK, the object is defined using the properties displayed in the dialog box.

If you define a message box, bitmap, ActiveX or User control, the Properties dialog box is always displayed, regardless of the setting of Auto properties.

2.2.1.4 Working with Objects

To work with an object, you must make it the current object. When you define an object initially, Dialog System automatically makes it the current object.

2.2.1.5 Naming Objects

A common property of all objects is a name. For some objects, it is required, and for some it is optional. If you give an object a name, that name must be unique.

A good programming practice is to set up a naming convention for the variables in your COBOL program. A consistent naming convention enables you or another developer to understand your application more easily.

We also recommend that you establish a similar naming convention for the objects in your user interface.

One fairly simple naming convention consists of the concatenation of:

windowname-objectinfo-objecttype

where the concatenated parts are:

`windowname`	The name of the window the object is located on, or if the object is itself a window, just the window name.
`objectinfo`	Some identifying information about the object. The information should uniquely identify the object on this window, for example, the text that appears on a push button.
`objecttype`	An abbreviated name that identifies the type of object. For example, you could use win for window, pb for push button, db for dialog box and so on.

Using this convention, a window used to gather information about a new employee could be named NEW-EMPLOYEE-WIN. A push button on the same window could be named NEW-EMPLOYEE-OK-PB. An entry field on the window that is used to input salary information could be named NEW-EMPLOYEE-SALARY-EF.

2.2.2 Using Dialog

A user interface is more than just a graphical display. A complete specification also describes how the user and computer interact and how the user interface software interacts with the application software.

Once you have defined the appearance of the display, you must define this run-time interaction between the user and the machine. This interaction is called dialog. Dialog consists of events and functions. When an event occurs, the functions associated with the event are executed. Events can be caused by a key on the keyboard being pressed, or a menu choice or an object being selected.

For example, a Dialog System event such as BUTTON-SELECTED occurs when a user selects a push button (with the mouse or keyboard). If the button selected is Enter, the function associated with it might be CREATE-WINDOW, to create a new window for the user to enter more information.

Dialog System lets you create or customize the dialog between the user and the display objects.

For more information on dialog statements, see the chapter Using Dialog and the topic Dialog System Overview in the Help.

2.2.2.1 Events

An event signifies some change in the user interface: events happen to objects such as windows, bitmaps, list boxes and buttons. There are many different operations which can trigger an event, such as:

The user pressing a key.
A click on a mouse button when the mouse pointer is located over a push button.
A window or control receiving focus.
A validation error occurring.
The user moving the slider on a scroll bar.

Intrinsically, all events are the same. However, for convenience, they can be divided into three types:

Menu Events - An option is selected from a menu, for example, when you choose Exit on the File menu.
Object Events - Objects are activated, such as windows, push buttons, radio buttons, list boxes and dialog boxes.
Keyboard Events - Events occur when a key is pressed on the keyboard.

When an event occurs, Dialog System searches first in the relevant control dialog, then the relevant window dialog, then the global dialog. Defining an event is part of the process of creating a Dialog Definition. Events are defined by associating Functions with them.

2.2.2.2 Functions

Functions are instructions to Dialog System to do something. They are associated with events and operate when:

An event they are listed under occurs.
A procedure they are listed under is executed.

Dialog System has a comprehensive set of functions. Some are specific to moving around screensets, for example SET-FOCUS or INVOKE-MESSAGE-BOX. Some are similar to other programming language instructions, for example MOVE data from one data item to another.

You can find a complete description of the functions in the topic Dialog Statements: Functions in the Help.

2.2.2.3 Procedures

A procedure is an arbitrary name with a set of functions listed under it; in other words, a subroutine. You can think of a procedure as being like an event.

2.2.3 Using the Data Block and Screenset

Dialog System creates a file, called a screenset, which holds the definitions of all the windows and dialog boxes as you create them for your interface. It is called filename.gs. This includes any on-screen objects which you may need in your interface, for example, entry fields.

When you run your interface, objects such as entry fields contain data which you need to pass between the interface and your application program. You do this by associating your on-screen objects with data items defined in your application program. These data items are called master fields in Dialog System. You make the association by selecting the appropriate master field when editing the control's properties.

These data definitions are held in the screenset file and form the Data Block. When the generated program calls Dialog System's run-time support module, dsgrun, it passes the Data Block as a parameter.

The screenset file holds:

The data block.
The data definitions for all of the input and output.
Objects for windows and dialog boxes (including validation rules).
The actions associated with those objects.
These are called dialog events and functions, and you define them.

2.3 Steps for Creating an Application Using Dialog System

To start Dialog System:

Select Dialog System on the IDE Tools menu.
- or -
Select Net Express Command Prompt and enter dswin.

The steps that you need to follow to create an application with Dialog System are:

Define data and validations.
See the section Steps for Creating a Data Definition in the chapter Creating a Data Definition and Screenset and the topic Data Definition and Validation in the Help.
Define windows, dialog boxes and message boxes.
See the chapters Window Objects and Control Objects.
Define control objects (such as entry fields, text fields and radio buttons) and place them on the windows and dialog boxes.
See the chapters Window Objects, Control Objects and Using Dialog.
Save your screenset.
It is a good idea to save a screenset whenever you have finished a stage in the definition process. The first time you save a screenset, use Save As. Dialog System displays a dialog box for you to enter the filename and directory you want to save under.

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.
Test your screenset.
Examine the behavior of the screenset using the Screenset Animator. See the section Screenset Animator in the Help.
Define dialog.
Define object dialog that controls the behavior of objects.
Test the screenset again.
See the section Screenset Animator in the Help.
Change the screenset as required.
Go back to earlier stages of this process.
Generate the COBOL copyfile from the screenset.
See the section Steps for Creating a Data Definition in the chapter Creating a Data Definition and Screenset.
Write the COBOL application program with the necessary calls to the Dialog System run-time system.
See the chapter Using the Screenset.
Animate and test the COBOL program.
See the topic Debugging in the Help.
Package your application.
See the topic Compiling and Linking in the Help.

You do not need to follow this order strictly. You can define objects before you define data if you wish, but you cannot define object dialog until you have defined an object to which you can attach the dialog.

The Graphical User Interface

Creating a Data Definition and Screenset