PreviousMigrating to Different Platforms Using the Client/Server BindingNext

Chapter 13: Using Panels V2

Dialog System has Panels Version 2 (Panels V2) as its underlying technology.

Using Panels V2 with Dialog System enables you to:

This chapter shows how you can enhance your Dialog System application with Panels V2.

13.1 Calling Panels V2

The following fragment is an example of a Panels V2 call statement.

 call "PANELS2" using p2-parameter-block
                      p2d-dialog-box-record
                      new-title-buffer
                      attribute-buffer

Panels V2 calls Pan2win, and Pan2win issues the appropriate Windows API calls.

The set of functions that Panels V2 provides are the same regardless of the environment you are using, assuming of course that the environment supports the display feature.

Dialog System is based on this technology.

13.2 Dialog System and Panels V2 Events

Figure 13-1 shows a typical Dialog System application that contains calls to Panels V2.

Calls to Panels V2

Figure 13-1: Dialog System/Panels V2 Events

Notice how events are handled. There is no direct line for events between Panels V2 and your application. When an event occurs, Panels V2 detects the event and returns the event information through Dialog System (Dsgrun). Dialog System then returns the event information to your program through the Dialog System Event Block (dssysinf.cpy). You must use dialog to determine if (and how) you want to handle the event in Dialog System or your application.

13.3 Copyfiles

You must include several copyfiles in the Working-Storage Section of your program. For example:

 working-storage section.

     copy "ds-cntrl.mf".
     copy "clip.cpb".
     copy "pan2link.cpy".
     copy "dssysinf.cpy".

The first two you are already familiar with: the Dialog System Control Block and the Data Block generated from your screenset. See the topic The Call Interface in the Help for a description of these files.

The other two copyfiles are described in the next two sections.

13.3.1 Panels V2 Copyfile (pan2link.cpy)

Your COBOL program also should contain the pan2link.cpy copyfile .

The file contains:

Although this file is not absolutely necessary, the definitions in this file greatly simplify the writing of the Panels V2 part of the application.

Browse this file to get an idea of the type of information it contains.

13.3.2 Dialog System Event Block (dssysinf.cpy)

This file contains the definitions of the Dialog System Event Block. When an event occurs, information about the event is passed through the Panels V2 Event Block back to Dialog System. (Refer to Figure 13-1.) dssysinf.cpy is just a copy of the Panels V2 Event Block with extra fields added on for Dialog System use.

 01 ds-event-block.
 78 ds-eb-start         value next.
    03 ds-ancestor                       pic 9(9)  comp-5.
    03 ds-descendant                     pic 9(9)  comp-5.
    03 ds-screenset-id                   pic x(8).
    03 ds-event-screenset-details.
       05 ds-event-screenset-id          pic x(8).
       05 ds-event-screenset-instance-no pic 9(2)  comp-x.
    03 ds-event-reserved                 pic x(11).
    03 ds-event-type                     pic 9(4)  comp-5.
    03 ds-event-data.
       05 ds-gadget-event-data.
          07 ds-gadget-type              pic 9(2)  comp-x.
          07 ds-gadget-command           pic 9(2)  comp-x.
          07 ds-gadget-id                pic 9(4)  comp-5.
          07 ds-gadget-return            pic 9(4)  comp-5.
       05 ds-mouse-event-data.
          07 ds-mouse-x                  pic s9(4) comp-5.
          07 ds-mouse-y                  pic s9(4) comp-5.
          07 ds-mouse-state              pic 9(2)  comp-x.
          07 ds-mouse-moved-flag         pic 9(2)  comp-x.
          07 ds-mouse-over               pic 9(2)  comp-x.
          07 filler                      pic x(3).
 78 ds-eb-size          value next - ds-eb-start.

       05 ds-keyboard-event-data redefines ds-mouse-event-data.
          07 ds-char-1.
             09 ds-byte-1                pic 9(2)  comp-x.
          07 ds-char-2.
             09 ds-byte-2                pic 9(2)  comp-x.
          07 filler                      pic x(8).
       05 ds-window-event-data redefines ds-mouse-event-data.
          07 ds-window-x                 pic s9(9) comp-5.
          07 ds-window-y                 pic s9(9) comp-5.
          07 ds-window-command           pic 9(2)  comp-x.
          07 filler                      pic x.

The fields in dssysinf.cpy of particular interest are ds-descendant and ds-ancestor. When Dialog System creates an object it gets back a unique identifier for that object called a handle. If an event occurs on that object, Panels V2 passes back to Dialog System the handle of the object as well as the handle of the parent window of the object. These two handles, ds-descendant and ds-ancestor, are filled whenever an event occurs.


Note: The format of dssysinf.cpy has changed from Dialog System V2.1. If you have any Dialog System V2.1 programs that used dssysinf.cpy, you must re-compile them.


13.4 Building a Dialog System/Panels V2 Application

The steps you must follow in a Dialog System/Panels V2 application are:

To illustrate these steps, the following sections present a simple example of a Panels V2 function that renames a push button. Although a dialog function is available to do this (SET-OBJECT-LABEL), this example illustrates the main features of the Panels V2 call interface.

13.4.1 Establishing Dialog System and Panels V2 Communication

In your COBOL program, initialize Dialog System with a statement like:

call "dsgrun" using ds-control-block
                    data-block
                    ds-event-block

One of the items returned by Dialog System is ds-session-id (this item is stored in the Control Block). ds-session-id is the thread identifier of the Dialog System session. For your application to cooperate with Dialog System in its communication with Panels V2, you must make this identifier known to Panels V2. Do this with a statement like:

move ds-session-id to p2-mf-reserved

where p2-mf-reserved is a data item in the Panels V2 parameter block.

This statement establishes the necessary communication link between Dialog System and Panels V2. Now you can make direct Panels V2 calls.

13.4.2 Identifying Dialog System Objects to Panels V2

The MOVE-OBJECT-HANDLE function lets you save the handle of an object in a numeric data item in the Data Block. This ensures the same objects are being referenced by both the Panels V2 and the Dialog System parts of your application. As an example:

MOVE-OBJECT-HANDLE RENAME-PB PB-HAND
MOVE-OBJECT-HANDLE RENAME-WIN WIND-HAND

stores the handle of a push button named RENAME-PB in a numeric item PB-HAND and the handle of the window named RENAME-WIN in WIND-HAND. RENAME-WIN and WIND-HAND are defined in data definition as:

RENAME-HAND             C     4.00
WIND-HAND               C     4.00

Now your application (and hence Panels V2), has access to your Dialog System objects.

13.4.3 Perform Panels V2 functions

This fragment shows the code necessary to change the title of a push button.

 1 rename-button section.
 2
 3    initialize p2-parameter-block
 4    initialize p2g-button-record
 5    move 250                   to p2g-button-text-length
 6    move pb-hand               to p2-descendant
 7    move ds-session-id         to p2-mf-reserved
 8    move pf-get-button-details to p2-function
 9    call "PANELS2" using p2-parameter-block
10                         p2g-button-record
11                         text-buffer
12    end-call
13    perform varying ndx1 from 30 by -1 until ndx1 = 1 or
14               rename-text(ndx1:1) not = " "
15        continue
16    end-perform
17    move ndx1                  to p2g-button-text-length
18    move pf-set-button-details to p2-function
19    call "PANELS2" using p2-parameter-block
20                         p2g-button-record
21                         rename-text
22    end-call.
Line 1:
 rename-button section.

This section illustrates the Panels V2 call interface.

Lines 3-5:
     initialize p2-parameter-block
     initialize p2g-button-record
     move 250                   to p2g-button-text-length

Initialize some Panels V2 parameters.

Line 6:
     move pb-hand               to p2-descendant

pb-hand is the handle of the push button. This field is in the Data Block.

Line 7:
     move ds-session-id         to p2-mf-reserved

ds-session-id is the thread identifier of the Dialog System session. See the section Establishing Dialog System and Panels V2 Communication.

Line 8:
     move pf-get-button-details to p2-function

pf-get-button-details is a Panels V2 function to retrieve the details of a push button. Because we are only interested in changing the title, all the remaining features are the same.

Lines 9-12:
     call "PANELS2" using p2-parameter-block
                                  p2g-button-record
                                  text-buffer
     end-call

Panels V2 call statement.

Lines 13-16:
     perform varying ndx1 from 30 by -1 until ndx1 = 1 or
                        rename-text(ndx1:1) not = " "
         continue
     end-perform

This perform clause removes trailing spaces from rename-text, which contains the new name for the button.

Line 17:
     move ndx1                  to p2g-button-text-length

After removing trailing spaces, ndx1 contains the actual length of the name. p2g-button-text-length is the Panels V2 parameter that contains the length of the title buffer.

Line 18:
     move pf-set-button-details to p2-function

This Panels V2 function changes the attributes of a push button.

Lines 19-22:
     call "PANELS2" using p2-parameter-block
                                 p2g-button-record
                                  rename-text
     end-call.

Another Panels V2 call.


Warning: Do not create or delete any objects with Panels V2. Dialog System assumes it is in complete control. For example, if Panels V2 creates an object, the handle is never passed to Dialog System. As a result, any events related to that object by-pass Dialog System.


13.5 Sample Program

Two more extensive applications illustrating the Dialog System/Panels V2 interface are available in the demo directory. One, Clip, shows how you can incorporate some basic Panels V2 clipboard read and write functions into your Dialog System application. The other, Dsp2demo, shows some clipboard functions, setting colors, and window scrolling.

13.6 Panels V2 User Events

You can generate and receive Panels V2 user events in Dialog System. See the function descriptions for POST-USER-EVENT and GET-USER-EVENT-DATA in the Help. The first 32,000 events are reserved for Micro Focus use.


Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousMigrating to Different Platforms Using the Client/Server BindingNext