ANSI Standard PL/B Language and Visual PL/B

PL/B PLFORMS CONVENTIONS and HANDLING

Every MMCC program has a similar organization. Form handling is no exception.

PLFORMS are the definition of screen "forms" as defined by the Sunbelt "Forms Designer" and the PLBWIN IDE environment. We generally include the PLFORMs after the general work areas in a program, but the statment can be just about anywhere.

Form handling is largely automatic and controlled by the runtime. Essentially you name the form, load it, respond to events via the WAITEVENT loop, then destroy the form and exit the program.

We have long supported the ability for the user to resize any form. If they make it larger we'd stretch objects to fit the new size. Shrink the form and we'd resize objects to fit. On exit we'd store the ending screen size properties and the next time the program was run, we'd put it back as it was.

The first versions of the forms designer allowed access to the RESIZE event for the main window, but it did little else. We would take that event and modify the width, height, and other properties of many variables on a screen to match the new size.

The current forms designer includes the ability to handle object resizing automatically. When designing the form, you set an "anchor" property for each object. When the user resizes the screen the anchor lets the run-time change the size of objects to match.

Since the runtime took over the hard stuff, all we do is record the form size on exit and put it back the next time the program is run. We also, however, need to make sure that the form is never resized too small for all objects to fit. The forms designer does not have a minimum size setting.

We need a place to record the form size properties if we're to reset it each time the program is run. We use the "XC" file, which every MMCC system supports, to store run-time information about the program.

Each program defines an OPTION_LIST list structure. This list contains any runtime options that we might want to remember from session to session, but it also includes the current screen size properties.

Since most resize activity is now done by the run-time, our responsibilities are almost universal form program to program. That means we can use a standard INCLUDE unit for most screen resize processing. And we do; the include unit is:
     INCLUDE Z:RESIZEF1 (usually found at the end of the program).

(The "Forms Designer" names all objects and allows a standard "prefix" to be applied to each field name. Our standard is to make that prefix "F1_" for every primary form. This enables our standard include unit to work easily without passing parameters.)

---

Basic forms processing components of any program:

OPTION_LIST  LIST
F1_TOP         FORM   5
F1_LEFT        FORM   5
F1_WIDTH       FORM   5
F1_HEIGHT      FORM   5
other options
             LISTEND
B1_TOP         FORM   5
B1_LEFT        FORM   5
B1_WIDTH       FORM   5
B1_HEIGHT      FORM   5	 
......... program initialization and file opening
......... get options from the XC file:
        PACK      XCRECKEY,"PRxxxxx",PORTNUM
        CALL      XCIOREAD
        IF (XCNIF = NO)
            UNPACK  XCDESCR, OPTION_LIST
        ENDIF
..... other stuff then we load the form:
        FORMLOAD  {formname}
        CALL      RESIZE_F1_INITIALIZATION
..... mainline of program
        LOOP
          WAITEVENT
          IF (ACTION = "RESIZE")
              CALL   RESIZE_F1
              CONTINUE
           ENDIF
....       check other events, etc.
        REPEAT
..... then just before closing up:
        CALL      GETSIZE_F1
        PACK      XCRECKEY,"PRxxxxx",PORTNUM
        CALL      XCIOREAD
        PACKKEY   XCDESCR, OPTION_LIST
        CALL      XC_UPDATE
..... wrap up and exit the program

The option list is stored in the XC file by port number. Each time we enter the program we get the options as they were on exit the last time the program was run from this port. (The port number is assinged in the INI file and carried in COMMON storage).

The RESIZE_F1_INITIALIZATION routine gets the size of the form right after it is loaded. This is the "base" size from the forms designer and is considered the minimum allowed size. We save these properties in the B1_xxxx fields.

Once we have the base size the initialization routine looks at the saved options from the last run and changes the form's size properties to match. Like magic, the form now matches what the user last saw. Note that is is possible to lose screens if the size properties are messed up on exit. Some programs have multiple forms. A person might minimize one form then exit from the program. The minimized position is saved and restored the next time around. But there's no way to see the form or conveniently get it back!

To recover from this condition, all MMCC systems have an "auto resize" check box on the main menu screen. That setting is carried in common. If the "auto resize" is OFF, the forms will NOT be resized after loading. They retain their design size and position.

To recover a "lost" form, you get back to the main menu, turn off the "auto size" check box, then call the lost screen program. The form should come back. Now you can go back and turn on the "auto size" again. In the forms designer we write a routine on the RESIZE event to MOVE "RESIZE" TO ACTION. We'll see that action on the form resize event and we'll call the RESIZE_F1 routine from the include unit. This routine will get the new sizes of the screen and check them against the base size. If the user made the screen too small, we set the size back to the base size. If not, we leave it as is.

On exit from the program we call the GETSIZE_F1 routine to retrieve the current size and save in the option list.

Note that the RESIZE_F1 expects the form to be named F1_Window. We use that standard prefix for all primary forms. We should have coded the RESIZE routine to allow us to pass the form name as an argument on the call statment like:
   CALL RESIZE_F1 USING F1_Window
Too bad that we didn't. Someday we may do a second resize routine that takes the window name as a parameter.

Back to Standards Index

---

v1.10