DISPLAY INITIAL WINDOW

Format 12

DISPLAY INITIAL WINDOW creates and displays the main application window and independent windows. 

DISPLAY {INITIAL    } [GRAPHICAL] WINDOW
        {STANDARD   }
        {INDEPENDENT}

Remaining phrases are optional, can appear in any order. 

MODELESS
LINK TO THREAD
SCREEN LINE NUMBER screen-line

SCREEN {COLUMN  } NUMBER screen-col
       {COL     }
       {POSITION}
       {POS     }

AT screen-loc                       (independent only)
AT LINE NUMBER screen-line          (independent only)
AT {COLUMN  } NUMBER screen-col     (independent only)
   {COL     }
   {POSITION}
   {POS     }

SIZE  length

LINES height

FONT {IS} font-1
     {= }

CONTROL FONT {IS} font-3
             {= }

CELL 
 {SIZE  } [IS]  {cell-units                                 }
 {HEIGHT} [= ]  {control-type-name  FONT font-2 [SEPARATE  ]}
 {WIDTH }       {control-type-name  FONT        [OVERLAPPED]}

{ERASE} SCREEN
{BLANK}

{REVERSE-VIDEO}
{REVERSE      }
{REVERSED     }

WITH {COLOR } color-val
     {COLOUR}

{FOREGROUND-COLOR } IS fg-color
{FOREGROUND-COLOUR}

{BACKGROUND-COLOR } IS bg-color
{BACKGROUND-COLOUR}

{HIGHLIGHT}
{HIGH     }
{BOLD     }
{LOWLIGHT }
{LOW      }
{STANDARD }

{BACKGROUND-HIGH    }
{BACKGROUND-LOW     }
{BACKGROUND-STANDARD}

{ [USER-GRAY] [USER-WHITE] }
{        USER-COLORS       }

TITLE-BAR
[TOP   ] [CENTERED] TITLE IS title
[BOTTOM] [LEFT    ]
         [RIGHT   ]

WITH SYSTEM MENU
WITH NO SCROLL
WITH NO WRAP
{NO-CLOSE}

{AUTO-RESIZE}
{RESIZABLE  }

MIN-SIZE  {= } min-size
          {IS}
MAX-SIZE  {= } max-size
          {IS}
MIN-LINES {= } min-lines
          {IS}
MAX-LINES {= } max-lines
          {IS}

AUTO-MINIMIZE
CONTROL VALUE {IS} control-val
              {= }

LAYOUT-MANAGER {IS} manager
               {= }

VISIBLE {IS} {TRUE         }
        {= } {FALSE        }
             {visible-state}

POP-UP MENU {IS}  {menu-1}
            {= }  {NULL}

{POP-UP AREA IS  } handle-name
{HANDLE     {IS} }
            {IN}

CONTROLS-UNCROPPED
EVENT PROCEDURE IS { proc-1 [ {THROUGH} proc-2 ] }
                              {THRU   }
                   { NULL                        }

Syntax Rules

  1. Different formats of the DISPLAY statement may be mixed together in one DISPLAY statement, as long as no ambiguity results. The effect is the same as specifying each DISPLAY statement separately.
  2. screen-line and screen-col are numeric expressions.
  3. screen-loc is an integer data item or literal containing exactly 4 or 6 digits. It may also be a group item of 4 or 6 characters. If a numeric item is used, it must be a non-negative integer.
  4. line-num, col-num, length, and height are numeric data items or literals. They may be non-integer values. You can also specify the value of any of these items with an arithmetic expression.
  5. font-1, font-2, and font-3 are data items described as USAGE HANDLE or HANDLE OF FONT. They should contain valid handles to screen fonts.
  6. cell-units is a positive integer data item or literal.
  7. control-type-name is one of the control type reserved words known by the compiler.
  8. color-val is a numeric data item or literal. color-val can also be an arithmetic expression, except when used in the Screen Section.
  9. fg-color and bg-color are integer literals or numeric data items. They may be arithmetic expressions. See FOREGROUND-COLOR and BACKGROUND-COLOR Phrases for more information on color settings and values.
  10. Title is an alphanumeric literal or data item.
  11. min-size, max-size, min-lines, and max-lines are integer literals or data items.
  12. control-value is a numeric expression.
  13. The word NO-CLOSE is reserved by the compiler only when it appears in a Format 11 or 12 DISPLAY statement.
  14. Manager is a USAGE HANDLE or HANDLE OF LAYOUT-MANAGER that contains a valid reference to a layout manager.
  15. visible-state is a numeric literal or data item.
  16. menu-1 is a USAGE HANDLE or HANDLE OF MENU data item.
  17. handle-name is a USAGE HANDLE, HANDLE OF WINDOW, or PIC X(10) data item.
  18. proc-1 and proc-2 are procedure names.
  19. You must compile allowing for recursive paragraphs in order to specify the EVENT PROCEDURE phrase. Compiling for recursive paragraphs is allowed by default, but can be turned off with the -Zr0 compiler option.
  20. The SCREEN LINE phrase and the SCREEN COLUMN phrase must be used together. If they are used, you cannot use the AT, LINE, or COLUMN phrases.
  21. If the COLOR phrase is specified, neither the FOREGROUND-COLOR nor the BACKGROUND-COLOR phrase may be specified.
  22. The POP-UP/HANDLE phrase may be specified anywhere in the statement after the required initial elements.
  23. IS and "=" are synonymous.
  24. COLUMN, COL, POSITION, and POS are equivalent.
  25. BLANK and ERASE are equivalent.
  26. HIGHLIGHT, HIGH, and BOLD are synonymous.
  27. LOWLIGHT and LOW are equivalent.
  28. REVERSE-VIDEO, REVERSE, and REVERSED are equivalent.
  29. COLOR and COLOUR are synonymous.
  30. FOREGROUND-COLOR and FOREGROUND-COLOUR are synonymous.
  31. BACKGROUND-COLOR and BACKGROUND-COLOUR are synonymous.

General Rules

  1. The DISPLAY INITIAL WINDOW verb creates the main application window. The main application window has several special properties. If it is minimized, all other windows in the application are also minimized. If it is closed, the application terminates. A program can have only one main application window.
  2. If you attempt to create a main application window after one already exists, the DISPLAY INITIAL WINDOW statement will have no effect other than to set handle-name to NULL.
  3. The runtime automatically constructs the main application window if needed. This occurs any time a screen operation is dictated by the program and the program has not yet constructed a main application window. When this occurs, the runtime executes the following implied statement: 
    DISPLAY INITIAL WINDOW
    TITLE-BAR,
    SYSTEM MENU,
    AUTO-MINIMIZE,
    AUTO-RESIZE.
  4. The main application window is always modeless. A modeless window is one where the user can switch to another window while the current window is still open. You can include the word MODELESS in the statement as commentary.
  5. The INDEPENDENT phrase creates an independent window. Independent windows act like additional main application windows. Independent windows have the following traits:
    1. Independent windows do not have a parent. As a result, any other window in the application can be placed over them. Also, destroying another window in the application will not destroy the independent window.
    2. Although they do not have a parent, independent windows use the current window to determine their default fonts, cell size, and colors. Also, independent windows use the current window when determining their position. This is computed in the same manner as it is for floating windows.
    3. Independent windows can be minimized separately. Under Windows and Windows NT, each visible independent window has its own button on the task bar.
    4. Independent windows process their close box in the same manner as floating windows--by generating a CMD-CLOSE event.
    5. Independent windows can be created before the main window. In this case, there is no current window to provide defaults, so the independent window uses the same defaults as the main application window would. The window is located on the screen as follows:

      According to SCREEN LINE and SCREEN COL, if specified; otherwise

      If the window has a title bar, the host system places the window as if it were a new application; otherwise

      The window is centered in the screen.

      Note that LINE and COL (without the SCREEN option) are ignored in these cases.

    6. If an independent window is current when the main application window is created, the defaults for the main window are derived from the independent window.
  6. Most of the phrases allowed for DISPLAY INITIAL WINDOW work in exactly the same way that they work in a DISPLAY FLOATING WINDOW (format 11) statement. The following rules are supplemental.
SCREEN-LINE and SCREEN-COLUMN Phrases

Under Windows, the runtime ensures that the initial window is fully visible, so the location specified by screen-line and screen-col may not be used if that would place a portion of the window off the screen (the closest allowed location is used).

TITLE-BAR Phrase

If you specify a TITLE-BAR but do not give a TITLE, the default title is the name of the program (PROGRAM-ID in the IDENTIFICATION DIVISION).

AUTO-MINIMIZE Phrase
  1. The AUTO-MINIMIZE phrase indicates that a minimize button should be displayed. The runtime handles the minimizing and restoring of the application automatically. If you do not specify AUTO-MINIMIZE, the user is not allowed to minimize the application.
  2. In addition, the AUTO-MINIMIZE phrase implies the SYSTEM MENU and TITLE-BAR phrases.
Window Location and Size
  1. The window's location on the screen is determined by the host system, as are its initial dimensions if it is resizable. You can use the SCREEN runtime configuration variable to specify the initial window dimensions (including whether it is maximized or minimized).

    On a character-based system, the initial window always occupies the entire terminal surface. Setting the various sizing options has no effect.

  2. If you do not use the LINES and SIZE phrases, the lines and size values are taken from the SIZE option of the SCREEN runtime configuration variable. If SCREEN is not set, the default size is 25 lines by 80 columns. The host system may provide a smaller default (for example, 24line character-based terminals will default to 24 lines).
STANDARD Phrase

The STANDARD option is identical to the INITIAL option except that it automatically implies the following options:

  1. TITLE-BAR
  2. SYSTEM MENU
  3. AUTO-MINIMIZE
  4. USER-COLORS
  5. For graphical systems, a black foreground on a white background. For character-based systems, a white foreground on a black background. You may override these default colors with the various color setting phrases.
SIZE and LINES Phrases
  1. The SIZE phrase indicates the width (columns) of the interior of the new window. If it is omitted, then the width is the same as the main application window. If there is no main application window available, the default size of the floating window is the same as the current window.
    Note: A non-integer SIZE is allowed. If the SIZE is not an integer, then the partial column created cannot be used to display textual characters; however, graphical controls can be located there. The partial column is always shown as spaces with the floating window's background color. The minimum SIZE value allowed is 1. The runtime currently limits the maximum SIZE to 655 columns.
  2. The LINES phrase indicates the height (rows) of the new window's interior. If it is omitted, then the height is the same as the main application window. As with the SIZE phrase, a non-integer number of lines may be specified. Any partial lines created are always displayed as spaces with the background color. The minimum value for LINES is 1 (one). The runtime currently limits the maximum size of LINES as 655 lines.
GRAPHICAL Phrase

The GRAPHICAL phrase has the same effect as in the DISPLAY FLOATING WINDOW statement.

VISIBLE Phrase

The VISIBLE option determines whether the window created is visible or invisible. If the FALSE option is used, or visible-state is the value zero, then the window is invisible. Otherwise, the window is visible. If the VISIBLE phrase is omitted, then the window is visible.

POP-UP MENU Phrase

The POP-UP MENU phrase associates a pop-up menu with the window. If menu-1 is specified, then the menu associated with menu-1 becomes the pop-up menu. If NULL is specified, the window is not given a pop-up menu. Pop-up menus are activated by a machine-dependent technique. Under Windows, the technique is to right-click on the window's background.

CONTROLS-UNCROPPED Phrase

Normally, when you create a control in a window, the control is cropped to fit the current subwindow's dimensions. In addition, if the control's home position is outside of the current subwindow, the control is not created. Adding the phrase CONTROLS-UNCROPPED overrides these rules. When this phrase is used, the control is created with the specified location and dimensions, regardless of whether the control will be physically in the window.

This can be useful when you are dealing with RESIZABLE windows. Sometimes a resizable window is too small to show all of the controls that your program creates. Normally, these controls either would not be created or would be cropped. This could produce odd results when the window is later resized larger by the user. Although the resized window is now large enough to show everything, the controls still show their cropped appearance, because their (cropped) creation size is recorded in the controls as their actual size. Specifying CONTROLS-UNCROPPED avoids the cropping behavior.

This style is useful also when you want to place a combo-box near the bottom of a window. Because the size of the drop-down portion of the combo-box is determined by the control's overall height, cropping the control limits the drop-down box to the window's boundaries. If you want the box to drop down beyond the edge of the window, you need to use the CONTROLS-UNCROPPED window style to allow this.

EVENT PROCEDURE Phrase
  1. A window's event procedure is executed whenever an event is processed for that window. The event procedure is executed as if it were the target of a PERFORM statement. Only the window's own events trigger the event procedure. Events generated by controls contained in the window do not trigger the window's event procedure (they trigger the control's event procedure instead). The event procedure executes while the event is being processed, before the event causes termination of any executing ACCEPT statement. See PROCEDURE Clause for more information about event procedures.
  2. Specifying proc-1 assigns that procedure as the window's event procedure. Flow of control returns at the end of proc-1, unless proc-2 is specified, in which case flow of control returns at the end of proc-2. If you specify the NULL option, the window does not have an event procedure. This is the default, so the NULL option is treated as commentary.
  3. Note: The Support area of the Micro Focus Web site includes a sample program that demonstrates how a main application window can be coded to detect the system display's screen resolution and then size itself to fill the entire screen. To download, go to: https://supportline.microfocus.com/examplesandutilities/index.aspx, and select ACUCOBOL-GT® Samples > Graphical User Interface (GUI) Sample Programs > WIN-START-MAX.cbl.
Parent topic: DISPLAY Statement