Panels | Windowing Support for Text-based Systems |
This chapter shows you how you can use Panels in your Program.
Panels is a callable module which you can call from your COBOL program to create and manipulate user windows in your application. A program can create any number of panels, and might display up to 254 sets of data (panels) in overlapping rectangular views (windows) on a screen.
Text and attributes (such as highlighting or reverse video, for example) are written to the panel through the use of text and attribute buffers.
A panel can be larger or smaller than the user screen, up to 65,535 bytes and up to 2000 characters wide.
With Panels, you can:
Note: The Tutorials use sample programs and files that are copied to your system during installation. If you did not request these programs and files when you installed the product, please run Setup again now and specify that the sample programs be loaded onto your system.
Set your default directory to the one containing the Micro Focus sample programs before you begin the tutorial.
The sample programs used in this tutorial are:
Two other sample programs, pandemo.cbl and panbigsc.cbl, are also included. pandemo.cbl is used to illustrate the concepts behind Panels. panbigsc.cbl shows you how to create large windows that fill the screen.
For each panel you define a window - a view into the panel. A window, which is an area on your screen, is described in the program in terms of height, width, and screen position.
You can:
The Panels facility provides the basic functions necessary to manipulate windows and panels from your application. This is all accomplished by calling a subprogram called Panels.
Panels can be called from a COBOL program in one of the following forms:
call "PANELS" using panels-parameter-block
call "PANELS" using panels-parameter-block text-buffer
call "PANELS" using panels-parameter-block text-buffer attribute-buffer
The panels-parameter-block
has to be provided on every
call to Panels. This is a group item - you need to fill in the required
fields (elementary items) for any particular Panels function, and it tells
Panels what to do. The text-buffer
and attribute-buffer
only need to be supplied when the panel is being written to, read from or
scrolled.
Each call to Panels is typically preceded by MOVE statements to fill in these parameters.
The first program used by this tutorial is panelex1.cbl. It was created with Panels and illustrates some of the things you can do using Panels. Four panels used by the program appear on your screen:
You are able to use the cursor keys and menu options to experiment with the panels.
To compile panelex1.cbl enter one of the following commands:
DOS:
On DOS enter:
xm cobol panelex1 anim nognt;
Windows:
On Windows enter:
cobolw panelex1 anim nognt;
OS/2:
On OS/2 enter:
cobol panelex1 anim nognt;
UNIX :
On UNIX enter:
cob -a panelex1.cbl
DOS:
To run the program on DOS enter:
xm run panelex1
Windows:
On Windows enter:
runw panelex1
OS/2:
On OS/2 enter:
run panelex1
UNIX :
On UNIX enter:
cobrun panelex1
You can also animate panelex1.
DOS:
On DOS enter:
xm animate panelex1
Windows:
On Windows enter:
animatew panelex1
OS/2:
On OS/2 enter:
animate panelex1
UNIX :
On UNIX enter:
anim panelex1
As mentioned above, four panels are visible on your screen after you invoke panelex1 by running or animating it.
The Help panel is actually a window into a larger panel. You can scroll the contents of the panel by holding down the Ctrl key and pressing an arrow key. Press Ctrl+<down-arrow> (cursor down) key to scroll the text up, displaying more information.
Press any of the arrow keys (without Ctrl) to move the currently selected (Help) panel on the screen.
If a selected panel is disabled or made not visible, pressing F2=Bring to Top enables the panel or makes it visible. Pressing F3=Make Invisible disables a panel.
Pressing F2=Bring to Top also causes the selected panel to overlay all other panels that were previously covering it.
A selected panel responds to the menu commands at the bottom of the screen.
Pressing F4=Next Panel selects a new panel in the following order:
Pressing F5=Select Panel displays a new selection panel on the screen.
Use the <up-arrow> key and the <down-arrow> key to highlight the panel you wish to select and press Enter.
Pressing F6=Back to Start Position puts the selected panel in the position it was in when you started the demo.
If the panel is invisible you must make it visible with the F2=Bring to Top key to see the panel back at its starting position.
The second program used by this tutorial is panelex2.cbl. It was created with Panels and allows you to change parameters in the parameter block and see the results on the screen. There are two panels on the screen, one with a large A and one with a large B. Panel A has Panel ID 10 and Panel B has Panel ID 11.
DOS:
To compile panelex2.cbl on DOS enter:
xm cobol panelex2 anim nognt;
Windows:
On Windows enter:
cobolw panelex2 anim nognt;
OS/2:
On OS/2 enter:
cobol panelex2 anim nognt;
UNIX:
On UNIX enter:
cob -a panelex2.cbl
DOS:
To run the program on DOS enter:
xm run panelex2
Windows:
On Windows enter:
runw panelex2
OS/2:
On OS/2 enter:
run panelex2
UNIX:
On UNIX enter:
cobrun panelex2
Pressing F2=Alter Parameter Block displays the parameter block:
Function PIC 9(2) COMP VALUE 0 Status PIC 9(2) COMP VALUE 0 Panel ID PIC 9(4) COMP VALUE 0 Panel Control Group Panel Update Group Fill character PIC X VALUE " " Fill Attribute PIC X VALUE X"00" Update Mask PIC X VALUE X"00" Scroll Direction PIC 9(2) COMP VALUE 0 Scroll Count PIC 9(4) COMP VALUE 0
Use the arrow keys or press Enter to move the cursor through the list.
When you move the cursor to the Panel Control Group a new panel of options appears:
Panel Width PIC 9(4) COMP VALUE 0 Panel Height PIC 9(4) COMP VALUE 0 Visible-Width PIC 9(4) COMP VALUE 0 Visible-Height PIC 9(4) COMP VALUE 0 First Visible Col PIC 9(4) COMP VALUE 0 First Visible Row PIC 9(4) COMP VALUE 0 Panel Start Column PIC 9(4) COMP VALUE 0 Panel Start Row PIC 9(4) COMP VALUE 0
When you move the cursor to the Panel Update Group a new panel of options appears:
Buffer Offset PIC 9(4) COMP VALUE 0 Vertical Stride PIC 9(4) COMP VALUE 0 Update Count PIC 9(4) COMP VALUE 0 Rectangle Offset PIC 9(4) COMP VALUE 0 Update Start Col PIC 9(4) COMP VALUE 0 Update Start Row PIC 9(4) COMP VALUE 0 Update Width PIC 9(4) COMP VALUE 0 Update Height PIC 9(4) COMP VALUE 0
Each function has required fields, detailed in the chapter Panels. One example of using panelex2 is given here. If you read the Panels chapter, you can experiment with some of the functions using this program.
Keep in mind that some functions do not automatically update the screen, and some require that certain rectangles, windows, or buffers are defined before executing the function. These might not appear to do anything in the demo.
To look at how the parameters are passed to the program, you can animate panelex2.cbl.
Use this program in conjunction with the animated example at the end of this tutorial to learn how to most effectively use the combinations of functions available with Panels to get the results you want.
This example changes the size of the window (displayed portion) in Panel A.
The third program used by this tutorial is pantutor.cbl. To benefit the most from this example, it is suggested that you run this program under control of the Animator.
To compile pantutor.cbl and prepare it for Animation enter one of the following:
DOS:
On DOS enter:
xm cobol pantutor anim nognt;
Windows:
On Windows enter:
cobolw pantutor anim nognt;
OS/2:
On OS/2 enter:
cobol pantutor anim nognt;
UNIX:
On UNIX enter:
cob -a pantutor.cbl
DOS:
To animate the program on DOS enter:
xm animate pantutor
Windows:
On Windows enter:
animatew pantutor
OS/2:
On OS/2 enter:
animate pantutor
UNIX:
On UNIX enter:
anim pantutor
This tutorial demonstrates the following Panels functions:
and use of the following Adis functions:
After you animate the file the tutorial goes through the following steps:
The first thing the program does is inform Adis that it will be using Panels. This is done via an x"AF" function call. In addition, this paragraph disables the Adis error message panel and all of its indicators.
The program creates 2 panels. One is used as a work panel and the other is used for displaying messages to the user.
The program displays a panel that is 11 characters wide by 7 rows. This panel is called the work panel or panel #1. In this panel, text is displayed in reverse video. The panel is displayed on screen line 2, column 5, and looks like Figure 12-1.
Up to this point, all the text written to panel #1 is not visible on the screen because the panel is created disabled, that is, invisible. When it is enabled, it is made visible.
The second panel is then displayed (panel #2). This panel occupies 1 screen line and is 80 characters wide. This panel is displayed on screen line 25. In this panel, we display messages like Press return to continue.
The program then issues an ACCEPT statement. This makes the program wait until the user is ready to continue. The user should press Enter to continue. The ACCEPT is done in the message panel (panel #2). This is an example of using ACCEPT and Panels together.
At this point the program issues a move panel function call to move panel #1 to screen line 10, column 8.
The program then waits until the user is ready to continue. Repeat steps #5 and #6 above.
You now write over one line of the panel. This new line is printed in green text on a black background. The updated panel looks like Figure 12-2.
The program then pauses and waits for the user to press Enter (see steps #5 and #6).
Panel #1 is cleared via an ADIS DISPLAY SPACES statement.
The program then issues an ADIS ACCEPT statement. It is accepting information within a panel. You should fill the panel in. Notice that when you reach the end of one line of the panel the text automatically wraps around to the next line.
The program pauses until the user presses Enter (see steps #5 and 6).
Panel #1 is disabled, making it invisible. At this point all the user sees is a blank screen.
The program then displays the information it just ACCEPTed. This is to show you that it did indeed retrieve the information.
The program pauses again, as in steps #5 and 6.
Now the program creates another panel. It is 3 characters wide and uses 2 screen lines. This panel is displayed at screen line 5, column 2.
Now text is written to this panel. It consists of ABC on the first line of the panel and DEF on the second. At this time the text is not visible as the panel, when created, is automatically disabled.
Next the program enables the panel, making it visible on the screen.
The program then pauses (see steps #5 and 6).
After you press Enter, the text in the panel is scrolled up 3 characters. When the program wrote to the panel in step #18 it provided a text buffer. The buffer contains the following:
ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890
The panel is 3 characters wide by 2 lines. It can display only 6 characters (3 * 2 = 6) at a time. When you press Enter, it displays the next 3 characters of the text buffer. The first time you press Enter, therefore, you see Figure 12-3.
Steps 20 and 21 are repeated until you reach the end of the text buffer. Therefore, every time you press Enter, three more characters of the text buffer are displayed.
At this point the program disables (make invisible) all the panels it has created and quits.
This concludes the Panels tutorial.
Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
Panels | Windowing Support for Text-based Systems |