GUI ScreenIO for Windows

ScreenIO.com

Sample GUI ScreenIO Application

This annotated sample will show you how easy it is to get a GUI ScreenIO application up and running. 

This program:

• Opens up your application's container by displaying SAMPMAIN, the main panel
• Displays SAMPLE1, a base panel.  SAMPLE1 has a menu, buttons, and a few controls on it, so you can see how to manage them
• Shows you a simple way to display a message in a messagebox
• When requested, displays popup panel SAMPLE2 and shows how GUI ScreenIO automatically closes it when appropriate
• Shows you how to properly terminate your application

Try the sample application

You can copy the sample application to your system, so that you can compile and test it yourself. 

The sample application consists of:

• SAMPLE.COB  -  the sample (monolithic) program
• SAMPMAIN.COB  -  the main panel
• SAMPLE1.COB  -  the base panel
• SAMPLE2.COB  -  the popup

We assume that you've already modified and compiled GS.COB as discussed in the Getting Started section.  To build the sample application, just compile SAMPLE.COB and link it (with the subroutine GS from Getting Started).

You may also find it instructive to run the sample application under your COBOL interactive debugger so that you can see exactly what's going on.  Interactive debuggers are great!

How the Sample Application works

Here's how the sample works, if it were written monolithically:

IDENTIFICATION DIVISION

This portion of the program is just like any other COBOL program; nothing special here.

DATA DIVISION

You copy your panel copybooks in here.  Since this program has a main (SAMPMAIN) and two panels (SAMPLE1 and SAMPLE2), we copy them here.

PROCEDURE DIVISION

The driver logic

Open the main window by calling GS to display the main panel, SAMPMAIN. 

In this case, we PERFORM the routine DISPLAY-MAIN-PANEL to do the actual CALL to GUI ScreenIO.

GUI ScreenIO will return immediately after it's opened up your main window. 

Next, PERFORM the paragraph that handles SAMPLE1, the first  application panel. 

When DISPLAY-SAMPLE1 is finished, close your main window - this is the ONLY time you should explicitly close a panel - and exit your application.

That constitutes the core of your application.  As you can see, it's quite simple.

Handling SAMPMAIN

Now, let's look at the PERFORMed routines.

This CALL to GUI ScreenIO passes the definition of SAMPMAIN, the main panel, to the runtime. 

The first time it's displayed, GUI ScreenIO opens the application's main window and immediately returns to your program. 

It also returns immediately when you CLOSE your main window before you terminate your application.

In most cases, this will be your only interaction with the main panel.

Handling SAMPLE1

SAMPLE1 is a base panel.  A base panel occupies the entire client area of the main window when it is displayed.

If you display a different base panel, it will automatically replace the one that previously occupied the main.  You don't need to do anything special to display or remove panels; GUI ScreenIO does it for you, automatically.  It's that simple.

A panel is usually displayed in a a loop that redisplays the panel after each event (user interaction), until the user asks to close the application (by clicking the X box in the upper-right corner of the window), or selects an option that will cause another panel panel to be displayed. 

Here's the first part of the code that handles SAMPLE1.  The first statement initializes the radiobutton DISPLAY-IN-MESSAGEBOX to ON (the checked state). 

Then, the program does an inline perform for the panel display loop.

SAMPLE1 looks like this when it is displayed.  You will note that it contains a menu, some static text, edit controls, pushbuttons, and pushbuttons.  That is, it looks like Windows applications are expected to look.

GUI ScreenIO will return when the user presses a button or selects an option from the menu. 

Here's how we handle the events that may come back.

First, we increment a counter that will display how many times the panel has been displayed.  This just demonstrates how easy it is to update EDIT-COUNTER, a numeric edit control:

Next, we'll determine what caused GUI ScreenIO to return using EVALUATE logic, and take the appropriate action.

If the user selected File/Display Popup from the menu, we'll PERFORM the paragraph that displays SAMPLE2, our popup panel.

When control returns from performing DISPLAY-SAMPLE2, this logic will loop around and redisplay SAMPLE1; this will cause GUI ScreenIO to automatically close the popup window SAMPLE2. 

You do not need to worry about closing application panels; GUI ScreenIO will take care of it for you.

If the user pressed the button "Display Popup" we'll also display our popup, same as above.  This just illustrates that you handle a pushbutton event the same way you'd handle a menu selection.

If the user pressed the button "Move data from field 1 to field 2" we'll move the content of the EDIT-CONTROL-1 to EDIT-CONTROL-2.  This shows how easy it is to obtain data from your panel, and to update a field on the panel. 

After we've moved the data, we'll clear the first edit control by moving SPACE to it.

 If the user pressed the button "Display message text" we move the content of the "message text" field to the panel's message area SAMPLE1-MESSAGE-TEXT, then we evaluate the status of the radiobuttons to determine whether the user wants to display the message in a popup message box, or in the status bar at the bottom of the panel.

That constitutes all of the events that we'll need to process.  Any other events are ignored.

Now that we've handled all of the possible events, loop back through the PERFORM until the user has finished with this application (when control will fall through the PERFORMed loop and return to the driver logic, which will close the application).

Handling SAMPLE2

SAMPLE2 is a popup panel.  Unlike a base panel, when a popup panel is displayed it doesn't affect any previously displayed panels; it appears on top of them.  You can display a string of popup panels "on top" of one another.  The user can only interact with the last popup that was displayed, which is standard Windows behavior.

The logic to handle a popup is identical to that required for a base panel (or any other type of panel, including property sheets and wizards).  Simply display the popup panel in a loop that redisplays the panel after each event (user interaction), until the user is finished with it. 

SAMPLE2 looks like this when it is displayed.  Unlike base panels, popups do not have a menu line.  Other than that, they're pretty much identical to base panels except that they appear as a popups which the user can move around as they wish.

Like base panels, popups can contain controls and display messages. 

Like SAMPLE1, GUI ScreenIO returns when the user presses a button (or the X box in the upper-right corner). 

We handle events that come back exactly as we did for SAMPLE1.

We didn't define any other events for SAMPLE2, so this covers all of the events that we'll need to process.  Any other events are ignored until the PERFORM logic detects that the user is finished and falls through the END-PERFORM.

Now that we've handled all of the possible events, loop back through the PERFORM. 

When the user has finished with this panel (which in this case, occurs when the X box is clicked), control will fall through this PERFORMed loop and return to the PERFORMed loop in SAMPLE1.

The logic for SAMPLE1 will loop around and redisplay panel SAMPLE1, which will cause this popup to close automatically.  You don't have to worry about closing application panels - GUI ScreenIO will do it for you! 

Related topics:

• A modular version of the sample application, which is how we recommend you develop GUI ScreenIO applications.