PreviousPanels Windowing Support for Text-based SystemsNext"

Chapter 12: Using Panels

This chapter shows you how you can use Panels in your Program.

12.1 Overview

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.

12.2 Panels and Windows in Your Program

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:

12.2.1 Using the Panels Facility

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.

12.3 Example 1 - The Panelex1 Program

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.

12.3.1 Compiling and Running Panelex1

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

12.3.2 Scrolling the Panel

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.

12.3.3 Moving the Panel on the Screen

Press any of the arrow keys (without Ctrl) to move the currently selected (Help) panel on the screen.

12.3.4 Making a Panel Visible or Invisible

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.

12.3.4.1 Selecting Panels

A selected panel responds to the menu commands at the bottom of the screen.

12.3.4.1.1 Selecting the Next Panel

Pressing F4=Next Panel selects a new panel in the following order:

12.3.4.1.2 Selecting a Specific Panel

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.

12.3.4.2 Moving a Panel Back to its Starting Position

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.

12.4 Example 2 - The Panelex2 Program

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.

12.4.1 Compiling and Running Panelex2

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

12.4.2 The Parameter Block in 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.

12.4.3 Changing the Size of a Window

This example changes the size of the window (displayed portion) in Panel A.

  1. Press F2=Alter Parameter Block. The first parameter window appears.

  2. Type 5 then press Enter for function 5. Function 5 retrieves information about a panel. Use this function to display the values already entered for this panel.

  3. Move the cursor to the Panel ID parameter. Type 10 for the Panel ID and press Esc.

  4. Press F3=Execute to have these entries take effect. The message "Function executed successfully. Press any key to continue" appears. Press any key to clear the message.

  5. Press F2=Alter Parameter Block again to alter the parameter block.

  6. Enter 4 for the Function parameter. Function 4 moves and changes the size of the window. Again, move to the Panel ID parameter and type 10.

  7. Move the cursor down to the Panel Control Group. A second parameter window appears.

  8. Move the cursor to Visible-Width and change the value to 12.

  9. Move the cursor to Visible Height and change the value to 6.

  10. Press Esc to return to the menu and press F3=Execute to implement the changes. The displayed portion of Panel A is now 6 columns wide and 12 rows high. If the displayed portion does not change verify that the function parameter is 4 and the Panel ID is 10, then verify that you have changed the visible height and width fields.

12.5 Example 3 - The Pantutor Program

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.

12.5.1 Compiling Pantutor

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:

  1. Paragraph 110-Enable-Adis-For-Panels.

    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.

  2. Paragraph 120-Create-A-Panel.

    The program creates 2 panels. One is used as a work panel and the other is used for displaying messages to the user.

  3. Paragraph 130-Write-1st-Panel.

    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.



    Figure 12-1: Panel #1

  4. Paragraph 140-Enable-Panel.

    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.

  5. Paragraph 170-Pause.

    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.

  6. Paragraph 170-Pause

    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.

  7. Paragraph 150-Move-Panel.

    At this point the program issues a move panel function call to move panel #1 to screen line 10, column 8.

  8. Paragraph 170-Pause.

    The program then waits until the user is ready to continue. Repeat steps #5 and #6 above.

  9. Paragraph 160-Update-The-Panel.

    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.



    Figure 12-2: Panel #2

  10. Paragraph 170-Pause.

    The program then pauses and waits for the user to press Enter (see steps #5 and #6).

  11. Paragraph 180-Clear-Panel-1.

    Panel #1 is cleared via an ADIS DISPLAY SPACES statement.

  12. Paragraph 190-Accept-Input-From-Panel.

    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.

  13. Paragraph 170-Pause.

    The program pauses until the user presses Enter (see steps #5 and 6).

  14. Paragraph 200-Disable-Panel.

    Panel #1 is disabled, making it invisible. At this point all the user sees is a blank screen.

  15. Paragraph 220-Display-Accepted-Info.

    The program then displays the information it just ACCEPTed. This is to show you that it did indeed retrieve the information.

  16. Paragraph 170-Pause.

    The program pauses again, as in steps #5 and 6.

  17. Paragraph 230-Create-Panel-2.

    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.

  18. Paragraph 240-Write-Panel-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.

  19. Paragraph 250-Enable-Panel-2.

    Next the program enables the panel, making it visible on the screen.

  20. Paragraph 170-Pause.

    The program then pauses (see steps #5 and 6).

  21. Paragraph 260-Scroll-Panel-2.

    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.



    Figure 12-3: Panel #3

  22. Paragraph 260-Scroll-Panel-2 and 170-Pause.

    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.

  23. Paragraph 200-Disable-Panel and 210-Disable-Msg-Panel.

    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.

PreviousPanels Windowing Support for Text-based SystemsNext"