| Panels Version 2 | Directory Facility V2 | |
This chapter introduces you to using Panels Version 2 (Panels V2) to create sophisticated graphical user interfaces (GUIs). The chapter is split into three main sections:
Once you have read and understood this chapter you should, in conjunction with your Panels V2 On-line Reference, be able to write simple Panels V2 programs. See the chapter Panels Version 2 for details of accessing the Panels V2 on-line reference.
UNIX:
Panels V2 is not available in UNIX environments.
Panels V2 is a run-time module that enables you to develop sophisticated, generic GUIs that can be used on many operating environments, including DOS Character, OS/2 Character, Microsoft Windows, and OS/2 Presentation Manager (PM).
The interface between your application and Panels V2 is a function call to Panels V2. Then, depending on the environment your application is running in, the function call is translated into the relevant application programming interface (API) call.
For example, if you are on a Windows environment, Panels V2 calls pan2win, then pan2win issues the appropriate Windows API calls. In this way, the calls issued by your application are translated into the relevant API calls regardless of the operating environment. See Figure 20-1.
Figure 20-1: Panels V2 Architecture
Panels V2 offers you benefits of ease of use, portability, and choice of GUI style.
A character based GUI emulation is provided for use under DOS or OS/2 character mode. This uses character graphics to emulate the objects typical of true graphics environments, and enables you to have a graphical interface even on limited hardware.
Panels V2 does not restrict you to any particular style or format of interface design, but allows you to develop user interfaces that are CUA compliant.
If you intend to use COBOL to program a GUI, there are a number of options open to you:
Each option has its strengths and weaknesses, with the option you choose being dependent on the requirements of your application.
The following sections discuss these options.
API programming is the traditional method of programming user interfaces. It involves programming using the API of the relevant environment, something that most COBOL programmers might not be familiar with. Here are some considerations about API programming:
Panels V2 is one step removed from API programming. Allowing you to use standard programming techniques, Panels V2 converts your COBOL calls into API instructions. Here are some considerations about Panels V2 programming:
Dialog System is an optional product available from Micro Focus. With a sophisticated interface of its own, Dialog System allows you to create the interface you require by building it on the screen interactively, using the functionality of Panels V2 to do so. Here are some considerations about Dialog System programming:
Using Dialog System in conjunction with Panels V2 offers you the ease of Dialog System with the additional flexibility of Panels V2.
In summary, each programming option has its advantages, and each has its disadvantages. Figure 20-2 shows the relation between each of the options.
Figure 20-2: Summary of Programming Options
API programming is shown as the closest to the operating environment, giving access to all the functionality offered by the operating environment, but resulting in the GUI being completely tied to that environment.
Panels V2 is one level removed from API programming. Moving further away from the operating environment results in a slight loss in the breadth of functionality available, but offers the benefits of portability and ease of use.
Dialog System is one step further removed from the operating environment than Panels V2. As a result, there is a further slight loss in functionality, but the resultant GUI will be portable across all supported environments, and developing a GUI using Dialog System is even simpler than using Panels V2.
When choosing which option is right for your GUI applications you should ask yourself the following questions:
This section gives information to help you understand the concepts behind Panels V2. It describes the components of GUI environments, the structure of all Panels V2 programs, the concept of Panels V2 events, and the relationship between GUIs and COBOL.
Panels V2 can be used with various graphical user interface (GUI) systems. It is designed to work with Presentation Manager (CUA compliant), and Windows. You can use Panels V2 to create an interface on one of these systems, and then use it on another, provided that you use Panels V2 functions that are portable. See the chapter Panels Version 2 for information about the portability of Panels V2 functions.
Some of the behavior described in this section is not automatically carried out by Panels V2. Instead, Panels V2 can provide your application with the information it needs to carry out the behavior if you decide it should. For example, a common way to close a window is to double-click on its system menu. In Panels V2, double-clicking on a system menu icon does not close the window, but an event is generated which allows your application to detect that the user wishes to close the window. Your application can then delete the window.
A window is the primary means of communication between the user and your application. This is the area where you present information to the user and, in turn, the user provides information to your application.
A window is a rectangular area on the screen in which other objects, such as list boxes, pushbuttons, and selection boxes can appear.
You can define a window either as a child of the desktop (as an independent object) or as a child of another window.
Figure 20-3 shows the visual components of a typical window on Presentation Manager.
Figure 20-3: A Typical Window
The components you choose for your window depend on what you want to display and how you want the user to react to your application. The example in Figure 20-3 contains the following components:
Windows can be related hierarchically by specifying one window to be a child of another. This relationship between windows has a significant effect on how the user interacts with your application.
A primary window lives on the desktop and exists independently of any other window. Any action taken on any other window does not have an effect on the primary window.
Different environments have different meanings for the terms secondary window and child window. In this chapter, the term secondary window is taken to mean a window that is not clipped by its parent window's boundaries, and a child window is a window that is clipped by its parent window's boundaries. See the section Clipping for a description of clipping.
Secondary and child windows are associated with a primary window. Many of the actions of secondary and child windows are determined by the boundaries of the primary window.
Some characteristics of the relationship between primary, secondary and child windows are:
Secondary windows, child windows, and dialog boxes have similar functions; that is, the displaying and collection of information. See the section Dialog Boxes later in this chapter for a description of dialog boxes.
Panels V2 lets you choose whether or not a window is to be clipped within the boundaries of its primary window.
A window is a child window if its information is truncated at the border of its parent window. A window is a secondary window if its information is not truncated at the border of its parent window, but it still has a parent.
Figure 20-5 shows an example of both a secondary and a child window on Presentation Manager.
Figure 20-5: Secondary and Child Windows
You should use a child window if you have a particular visual layout of your screen that you want to maintain. For example, if the window displayed is similar to a form the user is familiar with, you can use child windows to maintain that visual similarity.
On the other hand, a secondary window offers the maximum flexibility. Users can take advantage of all the available space and move the secondary windows anywhere on the desktop.
This section describes various ways of manipulating windows, using the mouse and the icons that form part of most windows. The actual appearance of the window and the icons used will vary depending upon whether you are using Windows, or Presentation Manager.
When you are not using a primary window, you can reduce it to a small symbol called an icon. You can do this by either:
The exact symbol used for the minimize icon varies between the operating systems but its location is the same in all. Double-click on the minimized icon to restore the window.
You can also move a window and, if it is a window that can be sized, you can change the size of the window. To move a window, put the mouse pointer in the window title bar, hold down the mouse button, and drag the window to a new location, then release the mouse button.
Similarly, to size a window, put the mouse pointer in the side or corner of the window and click and drag it. As you drag the window side or corner, the window changes shape. When the window reaches the required size and shape, release the mouse button.
To close a window, double-click on the system menu icon at the top left corner of the window.
To move between windows on the desktop, click on any part of the window you want to move to.
DOS, Windows and OS/2:
On DOS, Windows and OS/2, if the window is not visible, press Ctrl
and Esc together to bring up the window list. You can then select
the window you want and switch to it. The
current window (that is, the one that is active) has a border
colored in the active border color for the current environment.
All of the options discussed in this section can be selected using the keyboard, via the Alt key.
A dialog box is a type of window that enables users to enter data of some kind. It cannot be resized and cannot have a menu bar; it can have any of the other gadgets. A dialog box can be a child of another window, or of the desktop. Figure 20-6 shows a typical dialog box on Presentation Manager.
Figure 20-6: A Typical Dialog Box
There are two types of dialog boxes, application modal and application modeless. An application modal dialog box has to be removed before the focus can be set on another object, for example by clicking on it. This can be used to force the user to complete the dialog box before continuing. With a modeless dialog box, the input focus can be moved from the dialog box to another object.
Use dialog boxes in your application whenever you want to force a particular way of working onto your users. Dialog boxes stay in place until they are closed by the actions of a user. Typically, dialog boxes require users to press pushbuttons to accept user actions (for example, to push OK to accept a selection from a list) or to ignore these actions (for example, to push Cancel to close a dialog box ignoring any input). The section Mouse Actions describes how the mouse is used to push buttons.
Dialog boxes are often used to create File Selection boxes. These enable users to choose from a selection of files or other items and to enter their selections in another field.
A message box is another type of window that appears on the screen to give users a message. Message boxes can contain only text and graphics to give the message, and pushbuttons to respond to the message. They have to be explicitly cleared by a user pushing one of the pushbuttons. The section Mouse Actions describes how the mouse is used to push buttons.
Figure 20-7 shows a typical message box.
Figure 20-7: A Typical Message Box
Use message boxes to give warnings when incorrect data has been entered, or to ask a user to confirm that they want to continue with a potentially destructive action (such as deleting an object).
The mouse operates a pointer which shows your position on screen. The mouse pointer can move across window borders and is in addition to the selection cursor which shows your position within a window. Before you perform any of the mouse actions, you should move the mouse pointer to the appropriate position on the screen. For example, if you want to select a menu choice, move the pointer to that choice.
The shape of the mouse pointer changes as it encounters different objects on the desktop. For example, in a text field, it will appear as an I-beam pointer , showing you the exact place where any text will be added. At the corner of a sizable window, it will appear as a double headed arrow, and while waiting for an action to complete, it will appear as a timer. The shape of the mouse pointer should give you some clues as to what you can do at a particular place on the desktop.
The mouse works the various buttons on the screen, as well as selecting objects, items, and scrolling. In the following list of mouse actions, the mouse button to use for each action is not specified because some behaviors are specific to an underlying operating system.
| Action | Description | Effect |
|---|---|---|
| Click | Press and release the
mouse button. |
Selects an item or object, pushes a pushbutton or radio button, toggles a check box or a checkmarked choice. |
| Click and
drag |
Press and hold down the mouse button and move
the mouse pointer to the desired position. Release the mouse button. |
Moves or sizes an object on screen, or selects a range of items. |
| Double-click | Press and release the
mouse button twice. This should be done quickly; there should be a minimal break between clicks. |
Selects a list item and pushes the default pushbutton. |
| Release | Release the mouse button which has been held down. | Stops scrolling, stops dragging the object in a move operation, stops moving the window or object boundaries in a sizing operation. |
In a GUI system, the application is driven by users selecting objects and then selecting actions to be applied to the objects.
The following list shows how to select different objects:
Some windows contain scrollable areas. These are indicated by scroll bars at the right hand edge (for vertical scrolling) and the bottom edge (for horizontal scrolling). Each scroll bar contains a slider which moves along the bar, and arrows indicating the direction of scrolling.
To scroll line-by-line, click on the scroll arrow that points in the direction you want to scroll.
To scroll a screen at a time, click on the scroll bar itself, next to the slider. Scrolling is towards the point at which you clicked.
To scroll more than a screen at a time, click and drag the mouse pointer on the slider in the appropriate scroll bar and in the desired direction. Release the mouse button when the desired part of the window contents come into view.
Scrolling is not controlled automatically by Panels V2; unless you use a virtual window, your application must manage the scroll bars in order to scroll the display.
The menu bar is a list of commands at the top of the window - or more accurately, it is a list of groups of commands, because selecting one usually presents the user with further choices.
Graphical environments tend to be object-action oriented. That is, the user selects the object to act upon before selecting the action.
When you select a choice from the menu bar, a list of possibilities called a pulldown drops down from the choice. These are the actions you can perform on the object. A typical pulldown menu is shown in Figure 20-8.
Figure 20-8: A Typical Pulldown Menu
Various things can happen when you select a choice, and usually a visual cue tells you what. To show this, the options from the pulldown in Figure 20-8 are explained below:
| Option
|
Description
|
|---|---|
| Alternatives | Brings up another pulldown beside the current one to give you further alternatives from which you can choose. This is indicated by the arrow at the right hand side of the pulldown choice. |
| More Choice... | Brings up a dialog box so you can make a more complex choice, choosing from a list of files for instance. This is indicated by the ellipsis (...) at the right hand side of the pulldown choice. |
| Go For It | Performs an action immediately, and has no distinguishing marks. |
| On Or Off | Toggles on and off alternately. When it is on, it is characterized by a checkmark at the left hand side. When it is off, you cannot distinguish it from an immediate-action choice except by context. |
| Free Lunch | Is dimmed, indicating that it is not available for selection. |
Panels V2 uses a hierarchy of objects, with windows, dialog boxes and message boxes being at the top of the hierarchy. All other objects can only be displayed inside windows, dialog boxes and message boxes and are known as gadgets or widgets depending on the graphical environment in use. Pushbuttons, radio buttons, and entry fields are examples of gadgets.
Gadgets can be used to:
The most basic gadgets are entry fields (which enable you to read and enter data items) and labels (which are used for text labeling). Figure 20-9 shows a number of gadgets on Presentation Manager.
Figure 20-9: Gadgets on a Dialog Box
A check box is a square box with associated text. When selected, the check box is marked with a cross or a checkmark, depending on your operating system. Unlike radio buttons, selection boxes are not mutually exclusive. You deselect a check box by selecting it again. Unless you explicitly specify otherwise, selecting a check box does not automatically toggle its state; it is up to your application to track and represent the state of check boxes. Figure 20-9 shows three check boxes, labeled Compress file, Binary data, and CRLF to LF, with Compress file and CRLF to LF being selected.
An entry field displays the contents of a data item at run time and allows these contents to be changed. Figure 20-9 shows an entry field, labeled File to transfer.
A group box is a graphic frame used to outline a gadget or number of gadgets purely for the visual convenience of the user. Figure 20-9 shows two group boxes, labeled Parity and Options.
Use labels to enter any textual information into the window. Figure 20-9 contains two labels: File to transfer and Speed.
List boxes are used to display a list of choices which the user can select.
A multiple-line entry field enables you to display and edit the contents of a data item. It appears on the screen as a box with horizontal and vertical scroll bars, and is particularly suitable when you have a lot of characters to display or the layout is important.
The user can bring characters which extend beyond the right hand or lower boundary into view by using the scroll bars.
The text can also be word wrapped so that it never extends beyond the right hand boundary. Single words which cannot fit are simply split.
Pushbuttons are rectangular objects, labeled with text or bitmap, that represent an action. The action can be started when the button is selected. When selected, a pushbutton appears to be pushed in on the screen. Figure 20-9 shows three pushbuttons, labeled Transfer, Cancel, and Help.
A radio button is a labeled circle. When the radio button is selected, all other radio buttons in the same control group are deselected. The circle is partially filled when selected. Unless you explicitly specify otherwise, selecting a radio button does not automatically toggle its state; it is up to your application to track and represent the current state of buttons.
Figure 20-9 shows three radio buttons, labeled Odd, Even and Off, with Odd being selected.
A scroll bar is a window component that shows the user that more information is available in a particular direction and can be scrolled into view. A slider on the scroll bar shows how much information there is to show and indicates where the currently visible part of the information is in relation to the complete file. The window in Figure 20-1 has a vertical and a horizontal scroll bar.
A selection box is a box from which the user can make one or more selections. Selection boxes are also known as combination boxes or combo boxes.
There are four types of selection boxes available, depending on the environment:
A simple selection box consists of an entry field and a list box. The user can either type in to the entry field, or select an item from the list, which is then placed in the entry field.
A dropdown selection box is very similar to a simple selection box. However, the list box is normally hidden. The user presses an arrow button to the right of the entry field to make the list drop down, and it disappears again either when a selection is made, or when the user clicks elsewhere.
A dropdown list is very similar to a dropdown selection box except that the entry field is display-only. The user can only select an item or items from the list.
A popup list initially looks like a pushbutton containing one of the possible values. On selection of the button, a list of all possible values for that field appears. A value can then be selected from the list.
Figure 20-9 shows a dropdown selection box labeled Speed.
The aim of a GUI is to provide an interface which is easy to learn and easy to use.
The object oriented GUI should encourage users to concentrate on the tasks they have to do with an application, rather than the functions the application is capable of providing. A GUI should be intuitive, and should encourage users to experiment and explore. This, together with being forgiving with mistakes, means that users can learn in their own way and at their own pace. When they come back to the GUI after a while, they are more likely to remember how to use the GUI; if they don't, it doesn't matter because they can experiment all over again.
Where a conventional application interface uses a hierarchy of menus, requiring either navigation through the different levels to the required function, or the memorizing of obscure shortcut keys, the GUI application approaches the task to be done more directly. Users select an object and then an action; this cuts out some of the menu levels. By using the point and click actions of the mouse, users can move easily through the interface until they can do the required task. Contextual help is available, using On-line, providing links to related areas. This means that users can acquire the background knowledge they require to do a task, without needing to traverse a hierarchical help tree.
All Panels V2 programs have the same structure regardless of operating environment.
The basic steps are:
Example
This example, written in pseudo-code, shows the structure of a typical Panels V2 program.
1 procedure division 2 main-process section 3 4 initialize Panels V2 5 create windows/dialog boxes 6 show initial window 7 get first event 8 perform until terminate condition 9 process event 10 get next event 11 end perform 12 terminate Panels V2 13 stop run 14 15 process-event section 16 evaluate event-type 17 when event-type 1 18 process event 1 19 when event-type 2 20 process event 2 21 ... 22 when other 23 end-evaluate
Line 4:
initialize Panels V2
The initialization action allows you to select the environment (graphics or character) and determine screen dimensions and font characteristics.
Line 5:
create windows/dialog boxes
Create the windows and dialog boxes for your application. This action sets up the initial characteristics of the windows and dialog boxes.
Line 6:
show initial window
Display the initial window. As events are processed, the characteristics and status of the windows might change.
Line 7:
get first event
Access the first event. As noted in the following section, events can be either user events, window events or gadget events.
Lines 8-11:
perform until terminate condition
process event
get next event
end perform
This loop processes the events until some ending condition is met.
Line 12:
terminate Panels V2
Tells Panels V2 to shut down and release the resources that it used during program execution.
Line 15:
process-event section
This section is invoked when an event related to your application is encountered.
Lines 16-21:
evaluate event-type
when event-type 1
process event 1
when event-type 2
process event 2
...
Determine the type of event, and for each event take an appropriate action.
Line 22:
when other
Ignore all other events.
Panels V2 uses events to tell your application that something has happened at the user interface; this can be anything from a mouse button click to a window being moved. Every time something happens at the user interface, Panels V2 automatically puts information about the event into an event queue.
A Panels V2 event can be:
In order to find out what is happening, your application must ask Panels V2 for the next event in the event queue, sending the event record contained in the copy file pan2link.cpy for the reply. This copyfile is located in the directory cobol\source. Each time you make such a request, Panels V2 sends you the oldest event in the queue - in other words, it is a first-in, first-out (FIFO) queue. If there are no events in the queue, Panels V2 tells you so by returning the special event P2E-No-Event.
To request the next event, you call Panels V2 with the data records P2-Parameter-Block and P2E-Parameter-Block. P2-Parameter-Block is a record that is used on all calls to Panels V2, and P2E-Parameter-Block is a data record capable of reporting any kind of event.
There are two functions, Pf-Get-Event-With-Wait and Pf-Get-Event-No-Wait, that request the next event from the event queue.
When you use Pf-Get-Event-No-Wait or Pf-Get-Event-With-Wait:
The procedure for requesting an event is as follows:
When the call returns, the two records contain the information you need to find out what event has occurred and where. The next section tells you how to interpret this information.
Example code to request the next event:
move pf-get-event-with-wait to p2-function
move 0 to p2e-event-time-out
call "panels2" using p2-parameter-block
p2e-parameter-block
Note: Your Panels V2 program must poll the Panels V2 event queue to retrieve events on a regular basis. Failure to poll the event queue regularly could cause the loss of events or the slowing down of the application.
When the event record P2E-Parameter-Block is returned, the event which is reported could be any one of a large number of possible events. In order to make it easy to narrow down what is being reported, the information is returned in a hierarchical arrangement.
First of all, you need to examine P2E-Event-Type. This will be one of:
| Value of P2E-Event-Type
|
Meaning
|
|---|---|
| P2E-Window-Event | A window event occurred. |
| P2E-Gadget-Event | A gadget event occurred. |
| P2E-Mouse-Event | A mouse event occurred. |
| P2E-Lock-Key | A lock key event occurred. |
| P2E-Shift-Key | A shift key event occurred. |
| P2E-Data-Key | A data key event occurred. |
| P2E-Function-Key | A function key event occurred. |
| P2E-Shutdown-Event | A shutdown event occurred. |
| P2E-Windows-Shutdown-Event | The user tried to shutdown 16-bit Windows, but was prevented from doing so by Pf-Disable-Windows-Shutdown |
| P2E-No-Event | No event occurred.
|
Depending on the type of event, you need to interpret the rest of the record differently:
Suppose that P2E-Event-Type in P2E-Parameter-Block is examined and found to contain P2E-Gadget-Event, numerical value 56. As this is a gadget event, the next data item to check is P2E-Gadget-Type. Suppose that P2E-Gadget-Type is set to P2E-Scroll-Bar, numerical value 8. These two values tell us that a scroll bar event has happened.
The exact event has still not been determined, only that it relates to a scroll bar, so we need to further interrogate P2E-Parameter-Block. For gadgets, P2E-Gadget-Command is the data item that defines which event took place, so we need to check this data item.
So, if P2E-Gadget-Command contains the value 1, the event that took place was P2E-SB-Line-Up; the arrow on a scroll bar was used to move the display up by one line. By looking at the value of P2E-Gadget-Id we can discover the identifier of the scroll bar that caused the event.
*find out what sort of event happened
evaluate p2e-event-type
when p2e-window-event
perform window-event-section
when p2e-gadget-event
perform gadget-event-section
...
when p2e-no-event
continue
end evaluate.
...
gadget-event-section.
*find out what type of gadget it was
evaluate p2e-gadget-type
when p2e-button
perform button-event-section
...
button-event-section.
*find out what happened to the button
evaluate p2e-gadget-event......
This section introduces you to the basic principles you will need to know to write your first Panels V2 program: the format of the Panels V2 call, information returned from a call to a Panels V2 function, initialization and termination.
These techniques, and others, are illustrated in the example program p2hello1.cbl. The program is shown in its entirety, then its function is explained in detail.
All calls to Panels V2 functions have the same simple call interface, shown below:
call "PANELS2" using p2-parameter-block
[object-record]
[your-text-buffer]
[your-attribute-buffer]
As an example, look at the call for creating a window, taken from p2hello1.cbl:
66 create-window section.
67 move pf-create-window to p2-function
68 move 0 to p2-ancestor
69 move 10 to p2p-window-x
70 move 1 to p2p-window-y
71 move 40 to p2p-window-width
72 move 10 to p2p-window-height
73
74 move 0 to p2p-panel-width
75 p2p-panel-height
76
77 move pfl-sizeborder to p2p-window-flags
78 add pfl-minmax to p2p-window-flags
79 add pfl-visible to p2p-window-flags
80 add pfl-sysmenu to p2p-window-flags
81 add pfl-titlebar to p2p-window-flags
82
83 move "p2hello1 window" to text-buffer
84 move 15 to p2p-title-length
85 perform panels2-window-call
86 .
87
...
106*--------------------------------------------------------
107 panels2-window-call section.
108 multiply p2i-font-width by p2p-window-x
109 multiply p2i-font-height by p2p-window-y
110 multiply p2i-font-width by p2p-window-width
111 multiply p2i-font-height by p2p-window-height
112 call panels2 using p2-parameter-block
113 p2p-parameter-block
114 text-buffer
115 .
In this case, lines 67-68 are used to move data (the name of the function to be performed, and the parent of the created window) to P2-Parameter-Block. Lines 69-75 are concerned with the moving of data to the object record P2P-Parameter-Block.
Lines 77-84 are further moves for data items within P2P-Parameter-Block,
and the actual call to Panels V2 is on lines 112-114. text-buffer
is used as a third parameter, having been specified at line 83.
For further discussion of these lines, see the section Description of p2hello1 .
When you have made any call, the records you used to pass information to Panels V2 are used to return information about the function you just performed. You should check the contents of the returned records to verify that what you wanted to happen actually happened.
All calls result in the setting of P2-Status. P2-Status is a data item in P2-Parameter-Block, in the copy file pan2link.cpy , indicating the success or otherwise of the call. If the call was successful, P2-Status is zero. If P2-Status is not zero, some error occurred when Panels V2 tried to carry out the function you specified. A list of the possible errors can be found in the Panels V2 On-line Reference.
If the call is to create an object, P2-Descendant contains the identifying handle of the new object. P2-Descendant is a data item in P2-Parameter-Block. You should store this value, and use it when referring to the object in future.
If you use an object record, that could contain useful information on exit. This could happen in two ways:
Before your application can use Panels V2 functionality, it must make an initialization call. This call registers your application with Panels V2, as well as returning some information about the current environment.
The initialization call must be the first Panels V2 call made by your application.
Pf-Initialize is used to initialize Panels V2, but the information returned from a call to Pf-Initialize includes the following:
When your application has finished all of its calls to Panels V2 it must terminate its Panels V2 session. This releases any system resources allocated on initialization and removes any Panels V2 objects still on the screen. Although it is possible for a Panels V2 program to finish cleanly if it does not make a call to Pf-Terminate, we recommend that you end all Panels V2 programs with a Pf-Terminate call.
Pf-Terminate is used to terminate a Panels V2 session when your application has finished all of its calls to Panels V2. The termination call is made in the same way as any other call, specifying P2-MF-Reserved to tell Panels V2 which session is to be terminated.
When the call returns, P2-Status indicates the success or otherwise of the request to terminate.
Calls made by an application after Pf-Terminate returns will fail unless the application re-initializes.
This section introduces the sample program p2hello1.cbl, and contains the following subsections:
p2hello1.cbl is located in the directory cobol\demo\pandemo.
The purpose of p2hello1.cbl is to display a window containing "Hello World!". Panels V2 is terminated when the Close option is selected from the system menu. Figure 20-10 shows the display after running p2hello1.cbl. The display will appear slightly different on other operating environments.
Figure 20-10: Output from p2hello1.cbl
It is written in a modular style, as all Panels V2 programs should be, making visible the four steps that all Panels V2 programs exhibit:
p2hello1.cbl is completely portable, so you can use it on any environment supported by Panels V2.
1 ************************************************************* 2 * Copyright Micro Focus Limited 1993. All Rights Reserved.* 3 * This demonstration program is provided for use by users of* 4 * Micro Focus products and can be used, modified and * 5 * distributed as part of your application provided that you * 6 * properly acknowledge the copyright of Micro Focus in this * 7 * material. * 8 ************************************************************* 9 10 data division. 11 working-storage section. 12 13 78 panels2 value "PANELS2". 14 15 copy "pan2link.cpy". 16 17 01 exit-flag pic 9(4) comp-5 value 0. 18 88 exit-application value 1. 19 20 01 window-handle pic 9(9) comp-5. 21 01 text-buffer pic x(80). 22 23*-------------------------------------------------------- 24 procedure division. 25 main section. 26 perform initialize-panels2 27 perform create-window 28 move p2-descendant to window-handle 29 perform display-text 30 31 perform until exit-application 32 move pf-get-event-with-wait to p2-function 33 move 0 to p2e-event-time-out 34 call panels2 using p2-parameter-block 35 p2e-parameter-block 36 evaluate p2e-event-type 37 38 when p2e-window-event 39 evaluate true 40 when p2e-close-request 41 move 1 to exit-flag 42 43 when other 44 continue 45 end-evaluate 46 47 when other 48 continue 49 end-evaluate 50 51 end-perform 52 53 perform terminate-panels2 54 stop run. 55 56*-------------------------------------------------------- 57 initialize-panels2 section. 58 move pf-initialize to p2-function 59 move zero to p2-mf-reserved 60 move p2i-current-environment to p2i-environment 61 move zero to p2i-name-length 62 call panels2 using p2-parameter-block 63 p2i-initialization-record 64 . 65*-------------------------------------------------------- 66 create-window section. 67 move pf-create-window to p2-function 68 move 0 to p2-ancestor 69 move 10 to p2p-window-x 70 move 1 to p2p-window-y 71 move 40 to p2p-window-width 72 move 10 to p2p-window-height 73 74 move 0 to p2p-panel-width 75 p2p-panel-height 76 77 move pfl-sizeborder to p2p-window-flags 78 add pfl-minmax to p2p-window-flags 79 add pfl-visible to p2p-window-flags 80 add pfl-sysmenu to p2p-window-flags 81 add pfl-titlebar to p2p-window-flags 82 83 move "p2hello1 window" to text-buffer 84 move 15 to p2p-title-length 85 perform panels2-window-call 86 . 87 88*-------------------------------------------------------- 89 display-text section. 90 move pf-display-text to p2-function 91 move window-handle to p2-descendant 92 move 14 to p2t-text-x 93 move 5 to p2t-text-y 94 move "Hello World!" to text-buffer 95 move 0 to p2t-text-attribute 96 move 12 to p2t-text-length 97 perform panels2-display-text-call 98 . 99 100*-------------------------------------------------------- 101 terminate-panels2 section. 102 move pf-terminate to p2-function 103 call panels2 using p2-parameter-block 104 105 106*-------------------------------------------------------- 107 panels2-window-call section. 108 multiply p2i-font-width by p2p-window-x 109 multiply p2i-font-height by p2p-window-y 110 multiply p2i-font-width by p2p-window-width 111 multiply p2i-font-height by p2p-window-height 112 call panels2 using p2-parameter-block 113 p2p-parameter-block 114 text-buffer 115 . 116 117*-------------------------------------------------------- 118 panels2-display-text-call section. 119 multiply p2i-font-width by p2t-text-x 120 multiply p2i-font-height by p2t-text-y 121 call panels2 using p2-parameter-block 122 p2t-text-record 123 text-buffer 124 .
Line 15:
copy "pan2link.cpy"
Include the copy file pan2link.cpy . This copy file must be included in all Panels V2 programs. It contains the definitions for all functions, events and data records.
Lines 17-18:
01 exit-flag pic 9(4) comp-5 value 0. 88 exit-application value 1.
Set up a flag to set when the Close option has been selected from the system menu. The setting of this flag triggers the exit from the event processing loop.
Line 20:
01 window-handle pic 9(9) comp-5.
Set up a variable to hold the handle of the window that is created. This receives the handle of the window that is created, and is then passed to the Pf-Display-Text call to specify the window that is to receive the text.
Although not strictly necessary when there is only one window being created, it is standard practice to create a variable to hold the handles of any windows and gadgets created.
Line 21:
01 text-buffer pic x(80).
Create a buffer to hold the name of the created window and the text to be displayed on that window. The same buffer is used for both operations.
Line 26:
perform initialize-panels2
Perform the Initialize-Panels2 section to initialize Panels V2. The steps for initializing Panels V2 are included in a section of their own for the sake of program modularity.
Line 27:
perform create-window
Perform the Create-Window section. This creates a primary window. See lines 66-85.
Line 28:
move p2-descendant to window-handle
The handle of the created window is returned in P2-Descendant from the creation of the window, and its value is stored in Window-Handle.
Line 29:
perform display-text
Perform the Display-Text section. This displays "Hello World!" in the window. See lines 89-97.
Line 31:
perform until exit-application
Start of the event processing loop. Events are to be processed until Exit-Flag is set to 1, which happens in the event processing loop when the Close option is selected from the system menu.
Lines 32-35:
move pf-get-event-with-wait to p2-function move 0 to p2e-event-time-out call panels2 using p2-parameter-block p2e-parameter-block
Get an event from the event queue. Pf-Get-Event-With-Wait is moved to P2-Function to specify that an event is requested, and the value of zero in P2E-Event-Time-Out indicates that Panels V2 will wait indefinitely for an event to occur. The call to get the event is then made, specifying P2E-Parameter-Block as well as P2-Parameter-Block.
Line 36:
evaluate p2e-event-type
To have reached this point in the code, an event must have happened, so it is evaluated. The first data item to evaluate is always P2E-Event-Type as it contains the basic event information. See the section Panels V2 Events earlier in this chapter for more details about events.
Lines 38-51:
when p2e-window-event
evaluate true
when p2e-close-request
move 1 to exit-flag
when other
continue
end-evaluate
when other
continue
end-evaluate
Deal with the events. In this case, the only event of interest is the
selection of the Close option from the system menu. This has happened when
P2E-Event-Type is set to P2E-Window-Event, and the event returned is
P2E-Close-Request, so these conditions are tested for. If the Close option
has been selected, exit-flag is set to 1, which will
exit the event processing loop.
Line 53:
perform terminate-panels2
Perform the Terminate-Panels section to terminate Panels V2. The steps for terminating Panels V2 are included in a section of their own to aid program modularity.
Lines 57-63:
initialize-panels2 section.
move pf-initialize to p2-function
move zero to p2-mf-reserved
move p2i-current-environment to p2i-environment
move zero to p2i-name-length
call panels2 using p2-parameter-block
p2i-initialization-record
Initialize Panels V2. The initialization function Pf-Initialize is moved to P2-Function, zero is moved to P2-MF-Reserved to initialize that field, P2I-Current-Environment is moved to P2I-Environment to specify that the current operating environment is to be used, P2I-Name-Length is set to zero as there is no side file to be used, and the call to initialize is made, specifying the initialization record as well as P2-Parameter-Block.
This set of statements is a standard way to initialize Panels V2 and could be used in most Panels V2 programs.
Lines 66-67:
create-window section.
move pf-create-window to p2-function
The section for the creation of the window. The first operation is to specify the function to perform, which is done by moving Pf-Create-Window to P2-Function.
Line 68:
move 0 to p2-ancestor
Specify that the window is to be a top level window; that is, its parent is the desktop.
Lines 69-70:
move 10 to p2p-window-x move 1 to p2p-window-y
Specify the location of the window. In this case, the window is to be located 10 units to the right and 1 unit down from the origin.
Lines 71-72:
move 40 to p2p-window-width move 10 to p2p-window-height
Specify the dimensions of the window. In this case, the window is to be 40 units wide by 10 units high.
Lines 74-75:
move 0 to p2p-panel-width
p2p-panel-height
Specify that no underlying panel is required for this window.
Lines 77-81:
move pfl-sizeborder to p2p-window-flags add pfl-minmax to p2p-window-flags add pfl-visible to p2p-window-flags add pfl-sysmenu to p2p-window-flags add pfl-titlebar to p2p-window-flags
Specify the properties of the window. In this case, the window will:
P2P-Window-Flags is an example of a data item that can take a combination of values. In these cases, you should follow the example here: first move one value to the data item, then add each different value in a separate statement.
Lines 83-84:
move "p2hello1 Window" to text-buffer move 15 to p2p-title-length
Specify the text, and its length, to be inserted into the title bar of the window. In this case, the text is "p2hello1 window" and its length is 15 characters.
Line 85:
perform panels2-window-call
Perform a section to make the call to Panels V2. See lines 107-114.
Although this is not strictly necessary when there is only one call to this section, as in this case, using this method will make a program easier to read (and therefore, easier to maintain) when there are many calls to Panels V2 windows functions.
Lines 89-90:
display-text section. move pf-display-text to p2-function
The section to display some text on the window. The first operation to perform is to move Pf-Display-Text to P2-Function.
Line 91:
move window-handle to p2-descendant
Specify the window on which the text is to be displayed. In this case,
the handle of the required window is contained in window-handle,
so window-handle is moved to P2-Descendant.
Lines 92-93:
move 14 to p2t-text-x move 5 to p2t-text-y
Specify the location of the text within the window. The values specified position the text in the middle of the window.
Lines 94-96:
move "Hello World!" to text-buffer move 0 to p2t-text-attribute move 12 to p2t-text-length
Specify the text that is to be displayed in the window. In this case the text is "Hello World!", it is to be displayed in the default window attribute, and the length of the text to be displayed is 12 characters.
Line 97:
perform panels2-display-text-call
Perform a section to make the call to Panels V2. See lines 118-123.
Although this is not strictly necessary when there is only one call to this section, as in this case, using this method will make a program easier to read (and therefore easier to maintain) when there are many calls to display text.
Lines 107-111:
panels2-window-call section.
multiply p2i-font-width by p2p-window-x
multiply p2i-font-height by p2p-window-y
multiply p2i-font-width by p2p-window-width
multiply p2i-font-height by p2p-window-height
The section to perform the call to create and display the window. The MULTIPLY statements are necessary to ensure that the window is sized and located correctly on both graphic and GUI emulation environments. On GUI emulation environments P2I-Font-Width and P2I-Font-Height are 1, so will not affect the sizing and locating values; on graphics environments the values of P2I-Font-Width and P2I-Font-Width scale the sizing and locating to be in pixels.
Lines 112-114:
call panels2 using p2-parameter-block
p2p-parameter-block
text-buffer
Call Panels V2 to create the window, specifying P2P-Parameter-Block and
text-buffer as well as P2-Parameter-Block.
Lines 118-123:
panels2-display-text-call section.
multiply p2i-font-width by p2t-text-x
multiply p2i-font-height by p2t-text-y
call panels2 using p2-parameter-block
p2t-text-record
text-buffer
The section to perform the call to display the text in the window,
specifying P2T-Text-Record and text-buffer as well
as P2P-Parameter-Block.
The MULTIPLY statements are necessary to ensure that the text is located correctly on both graphic and character environments. On character environments P2I-Font-Width and P2I-Font-Height are 1, so will not affect the sizing and locating values; on graphics environments the values of P2I-Font-Width and P2I-Font-Width will scale the sizing and locating to be in pixels.
Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Panels Version 2 | Directory Facility V2 | |