Control Objects | Using the Screenset |
The preceding chapters have described the visual aspects of the screenset. Now we are going to look at how to activate the interface using dialog. In this chapter you will see how powerful dialog is, by looking at:
Dialog is a language which works behind the scenes to trap events and perform the actions you want to happen when the event occurs. A simple event and response could be, for example, "if the user presses a button labelled Next window, set the focus on a new window". You specify the code to perform this using dialog which is accessed by your application program.
A piece of dialog consists of:
An event or a procedure name ends the dialog for the preceding event. For example, consider the following dialog fragment attached to a window.
CLOSED-WINDOW SET-EXIT-FLAG RETC F1 MOVE 1 ACTION RETC SET-FOCUS EMPLOYEE-WIN DELETE-EMPLOYEE-PROC MOVE 2 ACTION RETC SET-FOCUS EMPLOYEE-WIN
The functions SET-EXIT-FLAG
and RETC
are
attached to the CLOSED-WINDOW
event. That is, RETC
is the last function associated with the CLOSED-WINDOW
event. The functions MOVE 1 ACTION
, RETC
and
SET-FOCUS EMPLOYEE-WIN
are attached to the F1
event and so on.
You should use comments in your dialog statements, as you do in your COBOL program, to make the code more readable. Comments allow you to:
Commented lines begin with an asterisk in the first column.
This sample dialog shows examples of using comments in dialog:
******************** SCREENSET-INITIALIZED * * Save the handles of each of the bitmaps * MOVE-OBJECT-HANDLE DENMARK DENMARK-HANDLE MOVE-OBJECT-HANDLE FRANCE FRANCE-HANDLE * MOVE-OBJECT-HANDLE US US-HANDLE * MOVE-OBJECT-HANDLE UK UK-HANDLE SET-FOCUS GERMAN-DLG *********************
You attach dialog to a window or control where an event can occur, or to the interface in general. These represent three classes of objects, but there is no essential difference between dialog applied to any of them. The dialog for each object is stored in a dialog table. The different classes of object dialog are:
This is where you attach dialog to any control except text, User Controls, ActiveX Controls and group boxes.
For example the following dialog is attached to a push button and changes the title of a window:
BUTTON-SELECTED MOVE "Customer Address Details" NEW-TITLE SET-OBJECT-LABEL CUSTOMER-ADDRESS-WIN NEW-TITLE SET-FOCUS CUSTOMER-ADDRESS-WIN
This is where you attach dialog to any window, dialog box or tab control page.
For example the following dialog is attached to a window and handles the user selecting the Close option:
CLOSED-WINDOW SET-EXIT-FLAG RETC
This is where you attach dialog to the entire screenset.
For example the following dialog initializes the first few entries of a list box:
SCREENSET-INITIALIZED INSERT-LIST-ITEM MONTH-LB "Jan" 1 INSERT-LIST-ITEM MONTH-LB "Feb" 2 INSERT-LIST-ITEM MONTH-LB "Mar" 3
The location used to define the dialog associated with a particular object or window depends on your requirements. If a procedure is:
Well structured dialog will execute more efficiently, and is easier to maintain and debug. When you write your dialog, apply the same coding principles that apply to any programming language.
There are three types of dialog:
For an event to be passed to a screenset, it must be defined explicitly. If an event is not defined, it will be ignored. You can define dialog events in the global dialog, in window dialog, and in individual control dialog.
Dialog System imposes a limit of 255 events for each dialog table.
An event signifies some change in the user interface. For example, it can be:
When an event occurs, Dialog System searches for the event, looking first in the control dialog, then in the dialog for the window which contains the control, and finally in the global (screenset) dialog.
Note: The same rules apply to procedures. If you call a procedure name in a control's dialog and it is not found there, the window dialog is searched for the procedure and then the global dialog.
If Dialog System does not find the event listed in any of these three places, it then looks for the event ANY-OTHER-EVENT at the control level, the window level, and then the global level.
If ANY-OTHER-EVENT is not found, no action is taken.
When Dialog System finds an event, the functions attached to it are processed step by step. Processing continues until the end of the functions listed under the event is reached, unless control branches to another procedure. Processing is delimited by another event. Dialog System processes events one at a time, queuing events and processing them as required. Dialog System imposes a limit of 255 events for each dialog table.
Dialog System events are controlled by the Panels V2 module. This module recognizes when an event occurs and processes it accordingly. Normally, the calling program does not receive information about these events from Panels V2. However, you can have these events returned to the calling program via the ds-event-block, found in the copyfile dssysinf.cpy. This file should be copied into the Working-Storage Section of the calling program and specified in the call to Dialog System. You might want to do this where a screen event is not explicitly defined in Dialog System.
You can find a complete description of events in the topic Dialog Statements: Events in the Help.
Note: If a window is a secondary window, the primary window dialog is not searched.
Functions are instructions to Dialog System to do something. They operate when:
The number of functions you can enter under each event or procedure is limited by the size of the buffer for functions and events (2K), and the maximum size of the dialog table (64K).
You could enter up to 2048 functions, depending on the function, but for average length functions, a more practical limit is 341. If you need more than this, you can call a procedure containing the extra functions. For example:
... function-340 function-341 EXECUTE-PROCEDURE FUNCTIONS-342-TO-350 ... FUNCTIONS-342-TO-350 function-342 function-343 function-344 ...
where function-340
through function-344
are
some of the Dialog System functions listed in the Help.
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.
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 an event; in this case, the event "happens" when an EXECUTE-PROCEDURE or BRANCH-TO-PROCEDURE function is activated.
As an example, the following fragment of dialog shows how to code a "loop" using procedures. This loop can be used in processing lists.
... BUTTON-SELECTED MOVE 1 INDX BRANCH-TO-PROCEDURE CLEAR-LOOP CLEAR-LOOP MOVE " " SELECTED-ITEM(INDX) INCREMENT INDX IF= INDX MAX-LOOP-SIZE EXIT-CLEAR-LOOP BRANCH-TO-PROCEDURE CLEAR-LOOP EXIT-CLEAR-LOOP ...
Dialog System provides several registers and variables that you can use as parameters:
Dialog System provides a rich set of events and functions that lets you control the behavior of your screenset. But how do you get started? How do you select menu choices? How do you return to your program and then what happens when you return to the screenset?
The following sections describe some basic functions with examples of dialog that may be appropriate to that function.
When you enter a screenset for the first time, you might want to set the default state of your screenset, setting such features as the state of radio buttons, the size of a data group, default values, or which menu options are enabled. The SCREENSET-INITIALIZED event lets you do this. As an example:
1 SCREENSET-INITIALIZED 2 SET-BUTTON-STATE OK-BUTTON 1 3 SET-BUTTON-STATE CANCEL-BUTTON 0 4 ENABLE-OBJECT SAVE-AS-PB 5 DISABLE-OBJECT SAVE-PB 6 SET-DATA-GROUP-SIZE SALES-GROUP 100 7 MOVE "*.*" SELECTION-CRITERIA
SCREENSET-INITIALIZED
This event is triggered when a screenset is entered for the first time (or when the calling program asks Dialog System for a new screenset).
SET-BUTTON-STATE OK-BUTTON 1 SET-BUTTON-STATE CANCEL-BUTTON 0
SET-BUTTON-STATE sets the state of a check box, a push button or a radio button. These two statements set the OK-BUTTON on and the CANCEL-BUTTON off.
ENABLE-OBJECT SAVE-AS-PB DISABLE-OBJECT SAVE-PB
The ENABLE-OBJECT function enables the SAVE-AS push button, the DISABLE-OBJECT disables the SAVE push button. You could use these, for example, when you have a new file and you want to force the user to enter a filename using the Save-as option.
SET-DATA-GROUP-SIZE SALES-GROUP 100
The SET-DATA-GROUP-SIZE function defines the internal size of a data group. Any occurrence greater than this size is retained but is not accessible to list boxes.
MOVE "*.*" SELECTION-CRITERIA
This statement sets the default value for an entry field.
Once you have defined the visual characteristics of a window, you can use dialog to create and initialize the window.
An example of dialog for creating a window is:
F2 CREATE-WINDOW WINDOW1
where F2
is the event triggered when the user presses F2
and WINDOW1
is the name of the window you want to create.
This is the name you entered when you defined the window.
This dialog statement initializes the window, making it ready to show. Although nothing visible happens, the window is created in the background. You can then make the window visible by using the SHOW-WINDOW dialog statement.
Although window initialization is not very time-consuming, it does take a little time. To avoid the effect of this, you can create your windows before you need them, then when you are ready to make them visible, use SHOW-WINDOW to display the window.
One of the first functions you want to do when you start a screenset is to show the main window or dialog box for your application. By default, the first window or dialog box you define when you define the screenset is the first window object displayed at run time. There are two ways to specify a different window or dialog box as the first window.
You can use the definition software to define your application's main window or dialog box as the first window using First window on the Screenset menu. First window is a property of the screenset that defines the window object that is displayed at run time. If you use this method to specify the first window, you do not need to add any dialog to do this.
However, there may be cases where you explicitly want to set the focus on or show your application's main window. For example, you may not know which window is the main window at definition time and you want to select it at run time. Use the SET-FOCUS, SHOW-WINDOW or SET-FIRST-WINDOW function to do this. You need to be aware that if you use SHOW-WINDOW, you need to explicitly close the first window by entering:
SET-FIRST-WINDOW $NULL
before entering the SHOW-WINDOW function. If you use SET-FIRST-WINDOW, you do not need to do this.
SHOW-WINDOW makes the window visible, but does not set the focus on the window. (An object is said to have the input focus (or focus) if any interaction with the keyboard or mouse is directed to that object.)
If the window has not already been created, SHOW-WINDOW creates the window automatically.
An example of the dialog for showing a window is:
F3 SHOW-WINDOW WINDOW2
where F3
is the event triggered when the user presses the
F3 key and WINDOW2
is the name of the window to be
shown.
If the window has a parent window, it is also shown.
UNSHOW-WINDOW makes the window, all child windows, and any controls invisible. The window still exists and does not need to be re-created.
You can use UNSHOW-WINDOW to clear a cluttered client area.
If you need to see the window again, SHOW-WINDOW brings the window, its child windows and all its controls back into view in exactly the same state as before it was unshown.
UNSHOW-WINDOW has two parameters. The first identifies the window to be unshown ($WINDOW means the currently selected window) and the second identifies the window that you want to receive the focus.
For example:
F4 UNSHOW-WINDOW $WINDOW WINDOW2
unshows the window that currently has the focus ($WINDOW
)
and sets the focus on WINDOW2
.
The chapter Using the Screenset discusses the advantages and disadvantages of using UNSHOW-WINDOW rather than using DELETE-WINDOW.
SET-DESKTOP-WINDOW sets the window specified by the parameter to be the parent of all objects that are normally children of the desktop.
As an example, you might have three primary windows that are all
children of the desktop; WIN1
(with handle WIN1-HAND
),
WIN2
, and WIN3
. The function:
SET-DESKTOP-WINDOW WIN1-HAND
results in:
WIN1
is still a child of the desktop.
WIN2
and WIN3
are children of WIN1
.
One use for this is the situation where selecting a function from the current screenset causes that screenset to be pushed onto the stack and a new screenset started. However, you want the first window of the new screenset to be a child of the current window in the first screenset.
You can do this by using the following functions:
... MOVE-OBJECT-HANDLE WIN1 $REGISTER SET-DESKTOP-WINDOW $REGISTER RETC
in the first screenset. Then in your program, load the second screenset.
WIN1
is now the parent window of all the windows in the
second screenset.
See the chapter Multiple Screensets for a discussion of using multiple screensets.
The default parent window can be reset to the desktop by:
SET-DESKTOP-WINDOW $NULL
Note: Windows that are already created are not changed. This function works only for new windows that are normally created as children of the desktop.
Visually, deleting a window is the same as unshowing a window. However, deletion removes the instance of the window, all child windows, and all controls that are attached to the window. Before another instance of this window can be referenced, it must be created.
An example of the dialog for deleting a window is:
F6 DELETE-WINDOW WINDOW2 WINDOW1
where WINDOW2
is the window to delete and WINDOW1
is the window to receive the focus.
Unless the user no longer needs that window for the session, for example a session log-on window, use UNSHOW-WINDOW rather than DELETE-WINDOW.
The chapter Using the Screenset discusses the advantages and disadvantages of using DELETE-WINDOW rather than UNSHOW-WINDOW.
The SET-FOCUS dialog sets the keyboard and mouse focus on the window. This means that any interaction with the keyboard or mouse is directed to this window.
If necessary, the function creates and shows the window before it sets the focus on it. An example of a dialog statement for setting focus on a window is:
F7 SET-FOCUS WINDOW2
where WINDOW2
is the window to receive the focus.
MOVE-WINDOW lets you reorganize the windows on the screen by moving a window from its current position to a new position. For example, if you create a window to use as a monitor and display a set of values, you can use MOVE-WINDOW to move the window, rather than a function that hides it, when another window is displayed.
As an example of the syntax:
F8 MOVE-WINDOW $WINDOW 2 5
where $WINDOW
indicates the current window, 2
indicates the "right" direction and 5
indicates
the number of system units by which to move the window. Refer to the
description of MOVE-WINDOW in the Help for a definition of these
parameters.
If you have multiple windows that perform similar functions, you can use a single window and change the window title using SET-OBJECT-LABEL. An example of the syntax is:
F9 SET-OBJECT-LABEL WINDOW1 NEW-TITLE
where WINDOW1
identifies the window and NEW-TITLE
is a data item that contains the new name.
Note: SET-OBJECT-LABEL does not automatically show the window if the window is in an unshow state. However, if the window is displayed, the change in title is immediately apparent.
One of the options in the window system menu is Close. If the Close option is selected, Dialog System automatically closes the window. However, you can also perform additional actions if this option is selected for example, terminate the application. The CLOSED-WINDOW event enables you to do this. As an example, the dialog:
CLOSED-WINDOW SET-FLAG EXIT-FLAG RETC
detects the "Close" event, sets a flag indicating the user wants to terminate the user interface, and returns to the calling program. Your program could then close files and do any other necessary processes to terminate the application.
BUTTON-SELECTED is the primary event associated with a push button, check box or radio button. It is triggered when you click on a button, or a check box has been selected.
For example:
BUTTON-SELECTED MOVE 0 ORD-NO($REGISTER) MOVE 0 ORD-DATE($REGISTER) MOVE 0 ORD-VAL($REGISTER) MOVE 0 ORD-BAL($REGISTER) UPDATE-LIST-ITEM ORDER-BOX $NULL $EVENT-DATA RETC REFRESH-OBJECT-TOTAL
When the BUTTON-SELECTED event is triggered, all the functions associated with that event are performed.
The SET-BUTTON-STATE and GET-BUTTON-STATE functions enable you to control the state of buttons and check boxes. To set the state of the buttons the first time you enter the screenset, see the section Initializing the Screenset.
You can also set and retrieve the states of buttons any time while the screenset is running. For example, the following dialog fragment sets the state of a radio button based on some action performed in the calling program:
BUTTON-SELECTED MOVE 2 ACTION-CODE RETC SET-BUTTON-STATE FILE-ACCESSED-RB 1 ...
You can also control the state of a check box by moving values of 1 or 0
to its Master Field. For example, if you have a data item named check-credit
that is the master field tied to a check box, you can change the state of
the check box by moving a 1 or a 0 to check-credit
. Assuming
the check box object is already created, you must refresh it to display
its change of state.
You can also define dialog to respond to the user selecting one of the actions of a pulldown menu. However, before you can add dialog to an action item, the action must have a name. See the topic Objects and Properties in the Help for details on naming actions.
As an example, the following dialog is taken from the Saledata sample application, where INSERT-CHOICE, CHANGE-CHOICE and DELETE-CHOICE are the names assigned to the menu bar actions. In the dialog, the "@" in front of the choice indicates that this is a menu choice.
@INSERT-CHOICE IF= $REGISTER 0 NO-SELECTION-PROC CLEAR-OBJECT INSERT-DB SET-FOCUS INSERT-DB @CHANGE-CHOICE IF= $REGISTER 0 NO-SELECTION-PROC MOVE SALES-NAME($REGISTER) TMP-NAME MOVE SALES-REGION($REGISTER) TMP-REGION MOVE SALES-STATE($REGISTER) TMP-STATE REFRESH-OBJECT CHANGE-DB SET-FOCUS CHANGE-DB @DELETE-CHOICE IF= $REGISTER 0 NO-SELECTION-PROC MOVE SALES-NAME($REGISTER) TMP-NAME MOVE SALES-REGION($REGISTER) TMP-REGION MOVE SALES-STATE($REGISTER) TMP-STATE REFRESH-OBJECT DELETE-DB SET-FOCUS DELETE-DB
When the user selects Change on the menu bar the event @CHANGE-CHOICE is triggered and all the functions under the event are performed.
Sometimes a menu choice does not apply. For example, you might have a new data file that has been updated, but not saved. Because it is a new file, it is not yet assigned a name, and you want to force the user to select a Save as choice (that requests a filename) rather than a Save choice. One way of coding the dialog for this situation is:
1 ... 2 XIF= FILE-SAVED-FLAG 0 DISABLE-SAVE 3 ... 4 DISABLE-SAVE 5 DISABLE-MENU-CHOICE $WINDOW SAVE-CHOICE 6 ENABLE-MENU-CHOICE $WINDOW SAVE-AS-CHOICE 7 ...
XIF= FILE-SAVED-FLAG 0 DISABLE-SAVE
XIF
is a conditional function. FILE-SAVE-FLAG
is a data item in the Data Block. A value of 0 indicates a file that has
not been saved. DISABLE-SAVE
is the procedure to perform.
Thus this statement says: If the file has not been saved, perform the
DISABLE-SAVE procedure.
DISABLE-SAVE
The start of the procedure to perform.
DISABLE-MENU-CHOICE $WINDOW SAVE-CHOICE
This statement makes the Save choice unavailable.
ENABLE-MENU-CHOICE $WINDOW SAVE-AS-CHOICE
This statement ensures the Save as choice is available.
Menu bar choices are used to define what will happen when you select one of the choices. For example, the following code fragment shows one way of coding the Cut, Copy and Paste options of an Edit menu choice:
... @CUT-CHOICE MOVE 5 ACTION-CODE RETC @COPY-CHOICE MOVE 6 ACTION-CODE RETC @PASTE-CHOICE MOVE 7 ACTION-CODE RETC ...
Note: The @ in column one indicates that this is a menu choice.
The section The Menu Bar in the chapter Window Objects describes the dialog for handling menu bar choices, including how to enable and disable choices.
You can validate a specific field or all fields attached to a window using the VALIDATE function. For example:
VALIDATE SALARY-RANGE-EF
validates only the SALARY-RANGE-EF entry field.
The statement:
VALIDATE SALARY-DETAILS-WIN
would validate all fields on the SALARY-DETAILS-WIN window.
If an error is detected, the VAL-ERROR event is triggered. For example, the following dialog fragment illustrates one way of coding the validation of all the fields on the current window.
BUTTON-SELECTED VALIDATE $WINDOW INVOKE-MESSAGE-BOX ERROR-MB "All fields OK" $REGISTER RETC VAL-ERROR INVOKE-MESSAGE-BOX ERROR-MB ERROR-MSG-FIELD $REGISTER SET-FOCUS $EVENT-DATA
See the section Validating Entry Fields in the chapter Sample Programs for a detailed explanation of the syntax.
Typically, you use a procedure as a common routine. For example, you usually have at least two ways to initiate a Cancel function; you can use a Cancel button or you can use the Esc key. The best way to code this is by calling a common procedure if either Cancel is selected or Esc is pressed. The following dialog fragment illustrates this method:
BUTTON-SELECTED BRANCH-TO-PROCEDURE CANCEL-PROC ESC BRANCH-TO-PROCEDURE CANCEL-PROC CANCEL-PROC cancel-functions ...
Dialog System provides two methods of invoking procedures; branching to the procedure (similar to a COBOL GOTO statement), and executing the procedure (similar to a COBOL PERFORM statement). To illustrate the difference, consider the following dialog fragments.
F1 BRANCH-TO-PROCEDURE CLEAR-OK RETC
F2 EXECUTE-PROCEDURE CLEAR-OK RETC
In the first case (when the F1 key is selected), control is passed to the CLEAR-OK procedure. What happens next depends on the functions contained in CLEAR-OK. The RETC function will never be executed.
When the F2 key is selected, the functions in CLEAR-OK are executed and then control is returned to the statement following the EXECUTE-PROCEDURE statement, that is, the RETC function.
Dialog System also provides a set of branching functions. The ones you use depend on whether you want to branch to a procedure or execute the procedure.
For example, the IF= function compares two values and if they are equal, the procedure is "branched to". The XIF= function also compares two values and if they are equal, the procedure is "executed".
In both cases, if the values are not equal, the statement following the IF= or XIF= statement is executed.
While your screenset is running, you may need to return to your program. For example, you may need to retrieve more data from a database, update a file, or do a complex validation. The RETC function returns control to the calling program.
For example, the following dialog fragment returns to the calling program so that the program can carry out the file deletion function.
BUTTON-SELECTED SET-FLAG DELETE-FILE-FLAG RETC
Normally, on return from your program, the statement following the RETC is executed. However, you can change this behavior if you want.
Some of the actions you may want to do when you return from the program are:
As an example of the syntax, the following dialog fragment refreshes the SALES-LIST list box and displays the window after returning from the calling program.
@SORT-NAME-CHOICE MOVE 2 ACTION-CODE RETC REFRESH-OBJECT SALES-LIST SHOW-WINDOW SALES-WIN
Some events are trapped by the Windows Operating System before they get to Dialog System.
For example, the standard Windows system menu has a set of accelerator keys that allow you to access the functions on that menu quickly. One accelerator key is Alt+F4, which removes the active window and all associated windows from the screen. If you define dialog for the event caused by the Alt+F4 key press, AF4, that event is trapped by Windows, and never reaches Dialog System.
Therefore, the following dialog defined for the key press will never be executed because Dialog System does not detect the event:
AF4 SET-FOCUS NEW-EMPLOYEE-WIN
To see some of the attributes and behavior of the window object, the sample application Objects is included in your demonstration directory. This application consists of a COBOL program, a screenset, and an error file. When you run the application, select the object you wish to see demonstrated on the Object menu.
To compile, animate and run the program, see the Help for your COBOL system.
For an example of manipulating menu bar choices dynamically at run time, refer to the Dynmenu demonstration in your Dialog System demonstration directory.
Of course the dialog can be more complex than that shown in this chapter. As an example, the following fragment is taken from the Dialog System definition facility. (Dialog System itself is a Dialog System application.) The following piece of dialog is attached to the mouse configuration option and lets you redefine how you want the mouse configured.
... @MOUSE-CONFIG-PD MOVE LEFT-BUTTON TMP-LEFT-BUTTON MOVE MIDDLE-BUTTON TMP-MIDDLE-BUTTON MOVE RIGHT-BUTTON TMP-RIGHT-BUTTON MOVE MOUSE-DEFAULT $REGISTER REFRESH-OBJECT LEFT-BTN-SB REFRESH-OBJECT MIDDLE-BTN-SB REFRESH-OBJECT RIGHT-BTN-SB IF= 1 MOUSE-DEFAULT DS21 IF= 2 MOUSE-DEFAULT CUA IF= 3 MOUSE-DEFAULT BTN3 * Must be user defined action, EXECUTE-PROCEDURE ENABLE-CHOICES SET-BUTTON-STATE USER-DEFINED-RB 1 SET-FOCUS USER-DEFINED-RB * DS2.1 mouse behavior, DS21 EXECUTE-PROCEDURE DISABLE-CHOICES SET-BUTTON-STATE DS21-RB 1 SET-FOCUS DS21-RB * CUA behavior, CUA SET-BUTTON-STATE CUA89-RB 1 EXECUTE-PROCEDURE DISABLE-CHOICES SET-FOCUS CUA89-RB * DISABLE-CHOICES DISABLE-OBJECT LEFT-BTN-SB DISABLE-OBJECT MIDDLE-BTN-SB DISABLE-OBJECT RIGHT-BTN-SB ENABLE-CHOICES ENABLE-OBJECT LEFT-BTN-SB ENABLE-OBJECT MIDDLE-BTN-SB ENABLE-OBJECT RIGHT-BTN-SB ...
Notice that all this functionality is within Dialog System. Control is not returned to the COBOL program.
Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
Control Objects | Using the Screenset |