Using GUIs from Third Party Tools

Using Panels Version 2

Chapter 19: Panels Version 2

UNIX:
Panels V2 is not available in UNIX environments.

Panels Version 2 (Panels V2) is a run-time module which enables your program to have a sophisticated graphical user interface. Simple calls to Panels V2 mean that you need no knowledge of the environment API . The user interface can also be ported between different graphical environments without alteration . Panels V2 is supplied with a comprehensive on-line reference in addition to the information given here.

19.1 Overview

Panels Version 2 (Panels V2) enables your application to have a graphical user interface (GUI), without the need for you to know how to program the API of the graphical environment you are working in. Your application simply calls Panels V2 with generic instructions about the action needed, and Panels V2 translates them into the correct form for the environment.

This not only simplifies programming, but also means you can use exactly the same source program in a number of different environments: the correct version of Panels V2 is used automatically at run time. Panels V2 gives you the nearest approximation available in the environment, including a GUI Emulation on DOS and OS/2 when only character mode is available.

When a call from your application requests it, Panels V2:

• Creates, modifies or deletes a graphic object to your specifications.

• Gives you information about an existing graphic object.

• Gives you information about interactions between the user and the interface, including keystrokes from the keyboard.

You can also sound the bell and control Panels V2 itself.

Panels V2 provides a wide range of graphical objects, such as windows, pulldown menus, push buttons and icons. The objects are typical of whatever environment is in use. For example, in a Presentation Manager environment under OS/2, Panels V2 provides CUA objects with their characteristic behaviors.

Associated with each type of object are:

• Functions to control or interrogate the object.

• Events which may involve the object.

• A record which carries information about the object.

To help you write your application, Panels V2 comes with a copyfile, pan2link.cpy, which contains all the record definitions. This file also contains convenient mnemonics (78 level data items) which represent numerical codes indicating:

• Functions.

• Events.

• Statuses.

• Multiple choices, for example, gadget type.

19.2 Operation

Panels V2 provides a user interface for your application. It has no user interface itself: you have to write an application which makes calls to it and gives it instructions about what to do. See section Using Panels V2 for a broad outline of what your application has to do. Further sections outline other important concepts and facts concerning Panels V2.

19.2.1 Using Panels V2

In order to use Panels V2 to provide its user interface, your program needs to contain the following:

1. The copyfile pan2link.cpy (supplied) in the Data Division Working-Storage Section.

   This contains record definitions and mnemonics (78 level items) for numeric codes. You can use the COPY statement to include this file in your program. See your Language Reference for information on the COPY statement.

2. An initialization call to Panels V2 to register your application with it.

   This call returns some information, such as the current environment.

   All calls to Panels V2 follow a similar pattern: Panels V2 carries out the instructions you give it, and then returns control to your application. See the section The Call Interface for a description of how to make a call to Panels V2.

   You might want to process some of the information you have received back from the initialization. For instance, depending on the environment which Panels V2 tells you it is operating in, you can arrange to specify object sizes in units of pixels or characters.

3. Calls to Panels V2 with instructions to create and display graphical and text objects on the screen. Each call specifies the function that you want Panels V2 to carry out and passes records containing the parameters for the function.

   When you have shown the initial windows and objects via Panels V2, you need to find out if the user is giving the application any input, and respond accordingly.

4. A call to Panels V2 requesting the next event from the event queue, sending the event record contained in pan2link.cpy for the reply.

   You can instruct Panels V2 not to come back until there is an event or a certain time has elapsed, or to come back immediately.

5. Code to process the returned event record.

   Take advantage of the implied tree structure of the information in this record to structure your program into sections dealing with different kinds of events and different kinds of objects.

   Each event conveys an elementary piece of information such as "the keyboard focus has been set on window reference XXXX". Be aware that several events may have occurred and queued up since you last called Panels V2. You may want to ignore some of them.

6. One or more calls to Panels V2 to respond.

   If the event signals to your program that some action is needed at the interface, such as displaying a dialog box, you need to call Panels V2 to do this. Each separate function, such as sounding the bell, moving the position of a scroll bar slider or scrolling text in a window, requires a separate call. You can change the appearance of the user interface dynamically during the session, for example by renaming a menu option or button depending on previous history.

7. A call to terminate Panels V2 when the session is finished.

   This releases the resources which were allocated to it, and removes any Panels V2 objects from the screen.

Steps 4 through 6 will be carried out many, many times during the execution of a typical application. This implies that your program will likely contain some kind of event processing loop.

19.2.2 The Call Interface

When your application wants to start, control, interrogate or terminate Panels V2, it calls Panels V2, passing one or more records.

The exact form of the syntax is shown in the On-line Reference with each function, but the general form is:

call "panels2" using P2-Parameter-Block
                     object-record
                     text-buffer
                     attribute-buffer

The first record is always P2-Parameter-Block. Your application needs to write information to it to tell Panels V2 basic information such as which function is requested. When the call returns, it contains information such as the success or otherwise of the call.

The second record depends on the object to which the function relates. When the function requests the next event in the queue, which could be from any object, a universal record P2E-Parameter-Block is sent.

If Panels V2 needs more information to carry out the function - for instance, you are modifying an object, or making an interrogation which is not completely defined by the data items in P2-Parameter-Block , your application needs to write to the appropriate data items before making the call.

Certain functions need further records containing text and or attributes, shown as text-buffer and attribute-buffer. These records are not supplied with Panels V2 and must be defined in the Working-Storage Section of your program.

When the call returns, the object record contains information which your application can process. Even if the function was a controlling function rather than an interrogating one, it may return information. See the individual function for details.

19.2.3 Records

Every time your application calls Panels V2, it passes one or more records to it, which are passed back when the call returns. Both your program and Panels V2 can read and write to them. The definitions for all these records are contained in pan2link.cpy , supplied with Panels V2 for inclusion in your application.

When you make a call to Panels V2 to create or modify something, you describe what you want to happen by assigning suitable values to data items first, then sending the record with the call.

When you make a call to Panels V2 to interrogate it, you pass the appropriate record to it in order that it can assign values to the data items. You can then interpret these values when it returns the record.

In some cases you can both send and receive the information you want on a single call.

The interface to Panels V2 uses the following records:

In addition, a text buffer and/or attribute buffer can be specified where an object uses some text and/or attributes.

19.2.4 Functions

Whenever your application calls Panels V2, it tells Panels V2 what it wants by means of a function code.

This function code is a numerical value sent in data item P2-Function of record P2-Parameter-Block. However, you do not need to remember or find out numerical codes, because each one has a mnemonic such as Pf-Create-Window so that you can use a statement such as:

move pf-create-window to p2-function.

Many functions are available, to create, modify, interrogate and delete the various types of objects (as appropriate), and request event information.

Some functions just require record P2-Parameter-Block to be sent with the call.

Depending on the function, you might need to pass more information, for example, the size and position of a window. You provide this by passing a further record. Each object type has its own record for this purpose, containing relevant parameters.

Some functions need a third record to carry text, and some a fourth to carry text attributes.

When the call returns, the records contain information about the success of the function, and possibly other details. For instance, if you tell Panels V2 to create a button making it big enough to contain the text label you specify, it tells you how big it actually made the button.

19.2.5 Events

Events signify any changes that happen at the user interface provided by Panels V2. They can be:

• Events directly caused by the user, for instance, a mouse button click or a key press.

• Events which are the consequence of your application telling
  Panels V2 to do something. For instance, if you set the focus on a graphical object, you cause a gained-focus event citing that object.

Each object has a range of associated events. For instance, a button can be clicked, a window can be sized, moved or closed. A single event conveys an elementary piece of information such as "the scroll bar slider has been moved and released at this position".

Whenever an event occurs, it is put into a first-in, first-out queue inside Panels V2. Your application has to request the next event in the queue by calling Panels V2. Since it is not possible to predict what object may have experienced the event, a universal event record, P2E-Parameter-Block, is sent with the call to collect the information.

Depending on the values returned in some data items in P2-Event-Record, your application needs to interpret other parts of the record in a particular way. This allows the application to use a tree-search method to find out which event has occurred.

Example

P2E-Parameter-Block is returned to your application after a call to return the next event from the event queue.

The application evaluates data-item P2E-Event-Type and finds that it is set to P2E-Gadget-Event. This means that an event occurred, and the event was from a gadget.

Your application now has to determine what type of gadget caused the event. It evaluates P2E-Gadget-Type, finding that it is set to P2E-Button. This means that the gadget that caused the event was a button.

To find out what happened to the button, the application evaluates P2E-Gadget-Command and finds that it is set to P2E-BN-Clicked. This means that the button was clicked on.

P2E-BN-Clicked is not a unique numerical code. It has a value of 1, the same as events such as P2E-SB-Line-Up and P2E-LB-Cursor-Moved. However, your application is able to differentiate because it has evaluated P2E-Gadget-Type to find that the event is related to a button.

Your application could contain code similar to this:

 sort-events section.
* What sort of event has happened?
     evaluate p2e-event-type
       when p2e-gadget-event perform gadgets
       when < some other kind of event> ...

 gadgets section.
* What kind of gadget caused this event?
     evaluate p2e-gadget-type
       when p2e-button perform buttons
       when p2e-scroll-bar perform scrolls
       when < other kinds of gadget> ...

 buttons section.
* What happened to the button?
     evaluate p2e-gadget-command
       when p2e-bn-clicked perform button-click section
       when < other button events > ...

 scrolls section.
* What happened to the scroll bar?
     evaluate p2e-gadget-command
       when p2e-sb-line-up perform scroll-up section
       when < other scroll bar events > ... 

19.2.6 Error Codes

When any call comes back from Panels V2, a numerical status code is returned in data item P2-Status. This gives you information about what happened to the call; either that it was successful, or what went wrong.

Each status has a descriptive mnemonic by which it is known. You can substitute this mnemonic for the numerical status code in your program; they are defined in copyfile pan2err.cpy.

19.2.7 Accessing the On-line Reference Material

Panels Version 2 comes complete with detailed help and reference material on-line, so that you can access it quickly and easily when you need it. This is presented in the form of hypertext, so that you can search for a key word, click on key phrases (hot-spots) to get further information or follow up a line of enquiry, or make use of many other facilities which would not be available to you in a conventional book.

You can access this help in two ways:

• From the command prompt. See the section Invoking Hyhelp and On-line in the chapter On-line Help System for information on invoking Hyhelp and On-line. The name of the .hnf file for Panels V2 help is panelsv2.hnf, so examples of command lines to invoke on-line help for Panels V2 are:

  runpm on-line panelsv2!pf-initialize

  hyhelpw panelsv2!pf-add-menu-item

  cobrun on-line panelsv2!

• When in the COBOL Editor, you can get help on, for example, a function, by placing the cursor on a word (perhaps a function or event name) and pressing Alt+1.

In either case, a new window appears containing the help. If you are not sure how to use the help system, click on Help on the menu bar at the top of the window, and click on Help for Help in the pulldown menu to see instructions.

19.2.8 Files Required at Run Time

When your end user runs an application which uses Panels V2 to provide its user interface, the files appropriate to the environment (see Table 19-1 below) must be present. They should be located in a directory which is on both the operating system path and the COBDIR environment variable. Additionally, OS/2 .dll files must be in a directory specified by the LIBPATH environment variable.

Table 19-1: Files Required for Panels V2 at Run Time

19.2.9 Using Functions in More Than One Environment

Some environments do not support certain features, although Panels V2 allows you to use them where they are available. This table tells you about the availability of functions in different environments, so that you can ensure that your application is generic across environments where necessary. Environments shown are not necessarily supported at present.

Environments are shown as:

Key to symbols in table:

Table 19-2 : Environment Support for Functions

Using GUIs from Third Party Tools

Using Panels Version 2