PreviousControl Objects Using the ScreensetNext

Chapter 6: Using Dialog

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:

6.1 What is Dialog?

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.

6.1.1 Comments

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

6.1.2 Levels of Dialog

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:

6.1.2.1 Control Dialog

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

6.1.2.2 Window Dialog

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

6.1.2.3 Global Dialog

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
        

6.1.2.4 Where to Locate Your Dialog Statements

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.

6.1.3 Types of Dialog

There are three types of dialog:

6.1.3.1 Events

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:

6.1.3.1.1 How Dialog System Searches for Event Dialog

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.


6.1.3.2 Functions

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.

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

6.2 Special Registers

Dialog System provides several registers and variables that you can use as parameters:

$REGISTER An internal register for general use. For example, you can use $REGISTER as an index into an array or to store temporary numeric values.
$NULL A parameter used to provide a default value or to space other parameters when no real parameter is needed.
$CONTROL The currently selected Control. It can be used in a general procedure where you do not know the name of the control. For example, you can use $CONTROL with the CLEAR-OBJECT function:

F3
   CLEAR-OBJECT $CONTROL

When the user presses F3, the current object is cleared.

$WINDOW The currently selected Window. For example, $WINDOW also can be used with the CLEAR-OBJECT function to clear the current window:

F2
   CLEAR-OBJECT $WINDOW

$EVENT-DATA A register that is written to by some events. For example, you can use $EVENT-DATA with the VAL-ERROR event. When Dialog System detects a validation error, the VAL-ERROR event is triggered and the identifier of the field in error is placed in $EVENT-DATA. This enables you then to set the focus on the field in error so the user can make corrections. The appendix Fonts and Color has a detailed example of using $EVENT-DATA this way.

See the topic Dialog Statements: Events in the Help for those events that write to $EVENT-DATA.

$INSTANCE An instance number that you can use to refer to a particular tab control page.

6.3 Important Dialog Events and Functions

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.

6.3.1 Initializing the Screenset

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
Line 1:
 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).

Lines 2-3:
     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.

Lines 4-5:
     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.

Line 6:
    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.

Line 7:
     MOVE "*.*" SELECTION-CRITERIA

This statement sets the default value for an entry field.

6.3.2 Window Dialog

Once you have defined the visual characteristics of a window, you can use dialog to create and initialize the window.

6.3.2.1 Creating a 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.

6.3.2.2 Showing the First 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.

6.3.2.3 Showing a Window

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.

6.3.2.4 Unshowing a Window

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.

6.3.2.5 Changing the Default Parent 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:

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.


6.3.2.6 Deleting a Window

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.

6.3.2.7 Setting the Focus on a 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.

6.3.2.8 Moving a Window

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.

6.3.2.9 Changing the Title of a Window

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.


6.3.2.10 Closing the Window

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.

6.3.3 Pressing Buttons

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.

6.3.3.1 Setting and Getting Button States

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.

6.3.4 Menu Bar Dialog

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.

6.3.4.1 Enabling and Disabling Choices

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     ...
Line 2:
    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.

Line 4:
    DISABLE-SAVE

The start of the procedure to perform.

Line 5:
    DISABLE-MENU-CHOICE $WINDOW SAVE-CHOICE

This statement makes the Save choice unavailable.

Line 6:
    ENABLE-MENU-CHOICE $WINDOW SAVE-AS-CHOICE

This statement ensures the Save as choice is available.

6.3.4.2 Selecting Menu Choices

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.

6.3.5 Validating Input

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.

6.3.6 Using Procedures

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.

6.3.7 Returning Control to the Calling Program

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

6.3.8 Regaining Control from the Calling Program

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

6.4 Events Trapped by the Windows Operating System

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

6.5 Sample Programs

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.

6.6 Sample Dialog

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.

PreviousControl Objects Using the ScreensetNext