DISPLAY WINDOW

Format 3

DISPLAY WINDOW creates and displays a subwindow.

DISPLAY {SUBWINDOW}
        {WINDOW   }

 [ UPON new-window ]

Remaining phrases are optional, can appear in any order.

AT screen-loc

AT LINE NUMBER line-num

AT {COLUMN  } NUMBER col-num
   {COL     }
   {POSITION}
   {POS     }

SIZE length

LINES height

{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}

BOXED
SHADOW
[TOP   ] [CENTERED] TITLE IS title
[BOTTOM] [LEFT    ]
         [RIGHT   ]

WITH NO SCROLL
WITH NO WRAP
CONTROL VALUE IS control-val

POP-UP AREA IS save-area

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. new-window is a USAGE HANDLE or PIC X(10) data item. If used, the UPON phrase must be the first optional phrase specified.
  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. color-val is a numeric data item or literal. It can also be an arithmetic expression, except when used in the Screen Section.
  6. fg-color and bg-color are integer literals or numeric data items. They may be arithmetic expressions. See Common Screen Options for more information on color settings and values.
  7. title is an alphanumeric literal or data item.
  8. control-value is a numeric expression.
  9. save-area is a USAGE HANDLE or PIC X(10) data item.
  10. If the UPON phrase is specified, it must be the first optional phrase.
  11. If the AT phrase is specified, neither the LINE nor the COLUMN phrase may be specified.
  12. If the COLOR phrase is specified, neither the FOREGROUND-COLOR nor the BACKGROUND-COLOR phrase may be specified.
  13. The POP-UP phrase may be specified anywhere in the statement after the required initial elements.
  14. WINDOW and SUBWINDOW are synonymous. The SUBWINDOW synonym is available to improve code clarity. Its use makes it clear that a SUBWINDOW is created.
  15. IS and "=" are synonymous.
  16. COLUMN, COL, POSITION, and POS are equivalent.
  17. BLANK and ERASE are equivalent.
  18. HIGHLIGHT, HIGH, and BOLD are synonymous.
  19. LOWLIGHT and LOW are equivalent.
  20. UNDERLINE and UNDERLINED are equivalent.
  21. REVERSE-VIDEO, REVERSE, and REVERSED are equivalent.
  22. COLOR and COLOUR are synonymous.
  23. FOREGROUND-COLOR and FOREGROUND-COLOUR are synonymous.
  24. BACKGROUND-COLOR and BACKGROUND-COLOUR are synonymous.
  25. The LINES phrase can take a numeric expression.

General Rules

  1. The DISPLAY SUBWINDOW verb creates or modifies the current subwindow. The subwindow is a rectangular region of the screen. In essence, the current subwindow defines a virtual terminal screen that occupies some area of the user's physical screen. Line and column numbers for ACCEPT and DISPLAY statements are computed from the upper left-hand corner of the current subwindow. For example, the statement DISPLAY SPACE, ERASE SCREEN erases only the current subwindow.
  2. When used with floating windows (Format 11), this verb creates a subwindow in the current floating window. Note that every floating window has an implicit subwindow. Each time a floating window is made current, its subwindow is also made current.
  3. When used with floating windows, subwindow coordinates are relative to the current floating window. Initially, this is the main application window. The subwindow never extends past the boundaries of the current floating window.
  4. The initial subwindow is set to the entire screen. When created inside a floating window, the subwindow is set to the floating window's display area (the area inside the borders, menu bar, toolbar, and title bar).
  5. Any subwindows contained in a floating window are automatically closed if the floating window is closed.
LINE NUMBER Phrase
  1. The LINE NUMBER phrase sets the top line of the subwindow. In this context, line number one refers to the top line of the current floating window.
  2. If this phrase is missing, then the top line of the current floating window is used.
COLUMN NUMBER Phrase
  1. The COLUMN NUMBER phrase sets the leftmost column of the window. Column number one refers to the left side of the current floating window.
  2. If this phrase is not specified, column number one is used.
AT Phrase

The AT phrase sets both the starting line and column number. The line and column numbers arrived at are interpreted as described in the LINE NUMBER and COLUMN NUMBER sections described above. See Common Screen Options for more information.

SIZE Phrase
  1. The SIZE phrase sets the number of columns the subwindow will contain. If this causes the window to extend past the right edge of the current floating window, the subwindow's width is adjusted to fit.
  2. If this phrase is missing, the subwindow extends to the right edge of the current floating window.
LINES Phrase
  1. The LINES phrase sets the number of rows the subwindow will contain. If this causes the window to extend past the bottom of the current floating window, the height will be adjusted to fit.
  2. If this phrase is missing, the subwindow extends to the bottom edge of the current floating window.
  3. The LINES phrase of a DISPLAY WINDOW, DISPLAY LINE, or DISPLAY BOX verb can take a numeric expression.
ERASE Phrase
  1. When the ERASE phrase is specified, the window will be cleared immediately after it is created. Otherwise the window's contents will not be changed. When a window is cleared, it is set to spaces with the current foreground and background colors.
  2. This phrase is implied by the BOXED and REVERSED phrases.
BOXED Phrase
  1. The BOXED phrase causes a box to be drawn around the new window. The box is drawn outside of the window. Any portions of the box that lie off the screen will not be drawn.
  2. The terminal's line drawing set is used to draw the box. If the terminal does not have a line drawing set, hyphens and vertical bar characters are used.
  3. If the POP-UP phrase is also specified, the box will overlay any other boxes on the screen. If this phrase is not specified, the box drawn will be attached to any other boxes it intersects.
  4. This phrase implies the ERASE phrase.
REVERSED Phrase
  1. The REVERSED phrase exchanges the window's foreground and background colors. This will affect every ACCEPT and DISPLAY statement in the new window.
  2. This phrase implies the ERASE phrase. Note that this will usually cause the entire window to be set to reverse video spaces when it is initially created.
COLOR Phrase
  1. The COLOR phrase sets the window's foreground and background colors. These colors are used whenever the window is erased and as default colors for future ACCEPT and DISPLAY statements. Color-val contains a numeric representation of the colors to use. See Common Screen Options for more information on setting numeric values for colors.
  2. If the foreground color is not specified, the new window inherits the current window's foreground color. If the background color is not specified, the new window inherits the current window's background color.
  3. You may use the WINDOW_INTENSITY configuration variable to control whether the intensity information in the COLOR setting should be used or ignored (see Appendix H for details).
HIGH, LOW, and STANDARD Phrases

The HIGH, LOW, and STANDARD phrases set the foreground intensity of the subwindow. This affects any drawing done to the subwindow itself (such as its border or title). In addition, they set the default intensity for any future ACCEPT/DISPLAY statements made to this window.

The STANDARD option indicates that a system-dependent default value should be used. You can affect this value with the FOREGROUND-INTENSITY configuration option.

If no option is given, the current subwindow's foreground intensity is used (inherit the foreground intensity of the parent).

BACKGROUND-HIGH, BACKGROUND-LOW, and BACKGROUND-STANDARD Phrases

The BACKGROUND-HIGH, BACKGROUND-LOW, and BACKGROUND-STANDARD phrases set the background intensity for the subwindow. This works in a fashion analogous to the foreground intensity described above. Note that the COLOR phrase, if present, takes precedence over the BACKGROUND phrases.

CONTROL VALUE Phrase

The CONTROL VALUE phrase provides a method for specifying certain window characteristics at run time. control-value must be a numeric expression that contains one or more of the following values added together:

Boxed 1
Shadow 2
No Scroll 4
No Wrap 8
Reverse 16
TITLE Phrase
  1. The TITLE phrase causes a title to be printed in the window's border. This has effect only if the BOXED phrase is also specified.
  2. One top title and one bottom title may be specified for each window. Top titles can be placed in one of three positions in the border region: top left, top center, or top right. Bottom titles can be placed in the bottom left, bottom center, or bottom right. If TOP or BOTTOM is not specified, TOP is used. If LEFT, CENTERED, or RIGHT is not specified, CENTERED is used.
    Note: Some GUIs (including Windows) cannot display more than one window title and do not give you a choice of title position. On these systems, the specified TITLE appears in the location determined by the GUI (usually top center, or top left). If you specify more than one title, the TOP title is the one used. If you specify only one title (either TOP or BOTTOM), it is used regardless of the title location.
NO SCROLL and NO WRAP Phrases
  1. Specifying NO SCROLL disables automatic scrolling for the new window. Normally, when the cursor is moved past the bottom edge of the window, the window is scrolled up one line. If NO SCROLL is specified, then the window will not be scrolled. The bottom line will be overwritten instead. When NO SCROLL is specified, then the only way to scroll a window is explicitly with a SCROLL phrase on a Format 1 DISPLAY statement.
  2. Specifying NO WRAP disables line wrap for the window. Normally, a line that extends past the right edge of the window is wrapped around to the next line. If NO WRAP is specified, then the line is truncated instead. This will leave the cursor logically positioned on the same line just to the right of the window's edge. Further output will not be visible until the cursor is repositioned inside the window.
  3. The scroll and wrap states of the current window are saved when a pop-up window is created. When that pop-up window is closed, the scroll and wrap states of the old window are restored.
  4. Note that the ACUCOBOL-GT runtime system contains two configuration variables, SCROLL and WRAP, that control the scroll and wrap states of all windows. When these variables are set to zero, then scrolling or wrapping for all windows is disabled regardless of the scroll and wrap states of the individual windows. When these variables are non-zero, then the window's individual states determine the use of scrolling and wrapping.
POP-UP AREA Phrase
  1. The POP-UP AREA phrase causes the screen manager to save information about the current subwindow prior to creating the new window. This information can be used by the screen manager later to remove the new window and restore the saved window. This is meant to be used to create pop-up windows.
  2. Boxed pop-up windows are automatically detached slightly from any intersecting line segments, such as the borders of other windows.
  3. The save-area is an elementary data item described by a PICTURE X(10) clause. It is filled in with information about the current window dimensions and contents before the new window is created. This data item is required for restoration of a window and must not be subsequently modified in any way. It can be referenced in a CLOSE WINDOW verb to restore the saved window to the screen and re-establish the saved window as the current window.
  4. Pop-up subwindows are an older technology that is not compatible with graphical controls. You should avoid using pop-up windows if you also use controls. Use floating windows instead.
SHADOW Phrase

The SHADOW phrase causes the window to appear to float over the screen, giving it a three-dimensional effect.

The way the shadow is displayed is determined by the SHADOW-STYLE setting of the SCREEN option in your runtime configuration file.

When a shadow is specified for a window, that window is automatically detached slightly from any intersecting line segments, such as the borders of other windows.

Note: Phrases not described above are described in Common Screen Options.