Format 11

DISPLAY FLOATING WINDOW creates and displays a floating window.

 [ UPON parent-window ]

Remaining phrases are optional, can appear in any order.

{MODAL   }



       {COL     }
       {POS     }

AT screen-loc


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

SIZE  length

LINES height

FONT {IS} font-1
     {= }

             {= }

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


{REVERSE      }

WITH {COLOR } color-val



{HIGH     }
{BOLD     }
{LOW      }


{        USER-COLORS       }

         [RIGHT   ]




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

CONTROL VALUE {IS} control-val
              {= }

               {= }

VISIBLE {IS} {TRUE         }
        {= } {FALSE        }

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

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

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

ACTION {IS} action
       {= }

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. parent-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-line and screen-col are numeric expressions.
  4. 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.
  5. 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.
  6. 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.
  7. cell-units is a positive integer data item or literal.
  8. control-type-name is one of the control type reserved words known by the compiler.
  9. color-val is a numeric data item or literal. color-val can also be an arithmetic expression, except when used in the Screen Section.
  10. 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.
  11. min-size, max-size, min-lines, and max-lines are integer literals or data items.
  12. title is an alphanumeric literal or data item.
  13. control-value is a numeric expression.
  14. The word NO-CLOSE is reserved by the compiler only when it appears in a Format 11 or 12 DISPLAY statement.
  15. manager is a USAGE HANDLE or HANDLE OF LAYOUT-MANAGER that contains a valid reference to a layout manager.
  16. visible-state is a numeric literal or data item.
  17. menu-1 is a USAGE HANDLE or HANDLE OF MENU data item.
  18. handle-name is a USAGE HANDLE, HANDLE OF WINDOW, or PIC X(10) data item.
  19. proc-1 and proc-2 are procedure names.
  20. action is a numeric literal or data item.
  21. 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.
  22. If the UPON phrase is specified, it must be the first optional phrase.
  23. 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.
  24. If the AT phrase is specified, neither the LINE nor the COLUMN phrase may be specified.
  25. If the COLOR phrase is specified, neither the FOREGROUND-COLOR nor the BACKGROUND-COLOR phrase may be specified.
  26. The POP-UP/HANDLE phrase may be specified anywhere in the statement after the required initial elements.
  27. IS and "=" are synonymous.
  28. COLUMN, COL, POSITION, and POS are equivalent.
  29. BLANK and ERASE are equivalent.
  30. HIGHLIGHT, HIGH, and BOLD are synonymous.
  31. LOWLIGHT and LOW are equivalent.
  32. REVERSE-VIDEO, REVERSE, and REVERSED are equivalent.
  33. COLOR and COLOUR are synonymous.

General Rules

  1. The syntax for DISPLAY FLOATING WINDOW is a superset of the DISPLAY WINDOW verb. This simplifies conversion of DISPLAY WINDOW statements to DISPLAY FLOATING WINDOW statements.
  2. The DISPLAY FLOATING WINDOW verb creates a new floating window and stores a handle to the window in handle-name. Use the value of handle-name with other verbs (such as DESTROY) when you need to refer to the window.
  3. After the new window is created, it becomes both the current and active window.
  4. The window created may be either modal or modeless. A modal window is a window that the user cannot leave until it is closed. A modeless window is a window that the user can leave (switch to another window) while it is still open. These names are derived from the idea that a modal window enters a new mode in the program (for example, selecting a file to open) while a modeless window does not (since the user can continue working on tasks in other windows).
  5. The DISPLAY FLOATING WINDOW verb also creates a new subwindow that exactly covers the interior of the floating window. This is identical to an implied DISPLAY SUBWINDOW statement (with no options). Any HIGH, LOW, STANDARD, BACKGROUND-HIGH, BACKGROUND-LOW, BACKGROUND-STANDARD, REVERSE, COLOR, NO SCROLL, or NO WRAP phrases specified in the DISPLAY FLOATING WINDOW verb are inherited by the implied subwindow.
  6. Each window has a controlling thread. A window's controlling thread is the most recent thread to have created that window or done an ACCEPT from that window. When a thread performs an ACCEPT from a window, and that thread is not the controlling thread of the active window, the thread suspends. The thread remains suspended until the window it is accessing becomes active (either because the user activates it or the program does).
  7. Most of the optional phrases have the same meaning as they do for DISPLAY SUBWINDOW. However, note the following exceptions:
    1. The ERASE SCREEN phrase is always implied by DISPLAY FLOATING WINDOW, so specifying this phrase has no additional effect.
    2. Most GUIs (including Windows) cannot display shadowed pop-up windows. On these systems, the SHADOW phrase has no effect. On character-based systems, the SHADOW phrase has its normal effect.
    3. All GUIs create borders around their windows. If there is a choice of border thickness, specifying BOXED will select a thicker border than omitting BOXED. Under character-based systems, the BOXED phrase determines whether or not there will be a border.
    4. The HIGH, LOW, STANDARD, BACKGROUND-HIGH, BACKGROUND-LOW, BACKGROUND-STANDARD, REVERSE, COLOR, NO WRAP, and NO SCROLL phrases do not directly affect the created window. Instead, they are passed on to the initial subwindow as described in Rule 5, above.
    5. Most 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.

The optional GRAPHICAL phrase directs the compiler to use a default CELL phrase equivalent to:


This phrase establishes the window's coordinate space based on the font used by controls that occupy the window. The CELL phrase can still be used and any values set in that phrase take precedence over the default value established with GRAPHICAL option. In other words, if you specify only a CELL HEIGHT or CELL WIDTH, then the other dimension receives the default assignment.

The intent of the GRAPHICAL option is to make it easier to consistently establish an appropriate coordinate space for windows that contain only controls (see the discussion of cell sizing and coordinate space that is included with the CELL phrase rules, below).

For example, the window that is specified with:


can be more simply specified with:

UPON Phrase

The UPON phrase specifies the parent of the new floating window. Parent-window must be a valid floating window handle. If the UPON phrase is omitted, the current window is used as the parent. If you create a new floating window in the scope of an UPON phrase, the new window becomes the current window when the DISPLAY statement terminates.

  1. The word MODAL makes a floating window modal. Floating windows are modal by default, so this word is just commentary. When a modal window is active, all other windows are disabled. The user cannot activate another window, including any of its components (such as its menu or close button). Note, however, that while a user cannot activate another window, the program can (see Format 10 of the SET statement).
  2. The word MODELESS makes a window modeless. When a modeless window is active, the user can activate another window by using the host system's techniques for doing so (for example, by clicking on another window with the mouse). When this happens, any ACCEPT that is active is terminated by a CMD-ACTIVATE event. Your program should respond by performing an ACCEPT in the window requested by the user. Alternatively, you can link your modeless window to a thread, see rule 1 under LINK TO THREAD and BIND TO THREAD Phrases (below).
  1. The LINK TO THREAD phrase allows the runtime to automate the handling of the CMD-ACTIVATE event. If the user activates a window created with the LINK TO THREAD phrase, the runtime will examine that window to see if it has a controlling thread different from the current thread. If it does, then the current thread suspends and the thread controlling the newly active window is allowed to run. The runtime handles all aspects of the window activation. The CMD-ACTIVATE event is not returned to the program in this case. If the controlling thread of the new window is the same as the current thread, then the runtime does not perform any special handling and the CMD-ACTIVATE event is passed on to your program. In order to get the best benefit from the LINK TO THREAD phrase, you should arrange to have a separate thread control each modeless window in your program.
  2. The BIND TO THREAD phrase has the same effect as the LINK TO THREAD phrase. In addition, the window is automatically destroyed when its controlling thread terminates.

The SCREEN LINE and SCREEN COLUMN phrases determine the initial location of the window on the screen. screen-line and screen-col give the coordinates of the upper left corner of the window in screen base units. Screen base units are machine dependent. On character systems, they are character cells. On graphical systems, they are pixels. The upper left corner of the screen is location 1,1. Under Windows, the runtime ensures that the initial window is fully visible, so the specified location may not be used if that would place a portion of the window off the screen (the closest allowed location is used). Windows other than the initial window may be placed arbitrarily. On graphical systems, the location of a floating window is interpreted to mean the location of its exterior. On character systems, the location is the same as it is for subwindows: the location of the window's interior.

LINE, COLUMN, and AT Phrases
  1. The LINE phrase indicates the starting row of the new window. This is always relative to the first line of the parent window. Non-integer values are allowed. If the LINE phrase is omitted, then the new window is first centered vertically over the parent window and then adjusted to be fully on the screen.
    Note: This rule differs from the handling of DISPLAY SUBWINDOW. With DISPLAY SUBWINDOW, omitting the LINE phrase is the same as specifying LINE 1.

    In all cases, the positioning is relative to the parent window as physically displayed on the screen, ignoring any aspect of the window not currently displayed. Thus, if the current window is the main application window, and that window has been scrolled by the user, line 1 refers to the first line of the physical window--not the (undisplayed) first line of the main application window.

  2. The COLUMN phrase works analogously to the LINE phrase, except that it controls the horizontal positioning.
  3. The AT phrase screen-loc item must be either a 4-digit or 6-digit number. The first half of this number is the starting row, the second half the starting column. These values are interpreted in the same manner as they are for the LINE and COLUMN phrases. A value of zero is treated as zero (i.e., AT 0000 is equivalent to ROW 0, COL 0).
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.
FONT Phrase

The FONT phrase assigns the font that will be used for all textual ACCEPT and DISPLAY statements used in the window. This also sets the default cell size to the size of the 0 (zero) character described by font-1. The cell size determines the height of one row and the width of one column. The font described by font-1 must be a fixed-width font. If it is not, or if the FONT phrase is not specified, then the font used is the same as the one used by the parent window.


The CONTROL FONT phrase specifies the default font to use for any graphical controls displayed in this window. If you omit the CONTROL FONT phrase, a system default is used (the font DEFAULT-FONT).

CELL Phrase

The CELL phrase defines the height, or width, or height and width of one cell in the window. A cell defines the height of one row and the width of one column. The default cell size is set by the size of the font used in the window.

The cell size is described in terms of cell units. The exact meaning of a cell unit is machine-dependent. Typically, for character-based systems, one cell unit is equal to the height or width (as appropriate) of one screen character. On graphical systems, a cell unit is typically one pixel in size. When developing programs, you should avoid writing code that depends on fixed (hard-coded) values for cell units.

The HEIGHT option of the CELL phrase defines the cell height for the new window. The WIDTH option defines the width. The SIZE phrase defines both the height and width together.

The cell-units option sets the cell's height, or width, or both, to the value of cell-units.

The control-type-name phrase causes the cell height, or width, or both, to be based on a particular font and control type. The system measures the size of font-2 when it is used in a control described by control-type-name, and sets the cell size accordingly. This option is typically used to set the coordinate space of the window to one that is convenient for aligning several controls of a particular type and font. Note that the font handle (font-2) is not required. When it is omitted, the window's CONTROL FONT is used. Also note that if the font handle is omitted, the optional word FONT is required (in order to avoid ambiguity with the FONT phrase).

If the SEPARATE option is specified, then a system-dependent amount is added to the measured font height to provide for some vertical separation between controls. This is typically used to provide some space between boxed entry-fields on adjacent rows. On the other hand, if OVERLAPPED is specified, the height is reduced by the size of the top border of a boxed entry field. This causes boxed fields on adjacent rows to share a common border.

The runtime currently limits control-type-name to be either a LABEL or ENTRY-FIELD. If another control type name is used, the runtime treats it as if it were type "LABEL".

If a window's cell width does not match the width of its font, or if its cell height is less than the height of its font, then the effects of a textual ACCEPT or DISPLAY statement in that window are undefined. If its cell height is larger than its font's height, then the characters are positioned at the top of each cell, and the lower portion of the cell is filled with the text's background color.

Note: The purpose of the CELL phrase is to simplify the construction of windows that contain only controls. We strongly recommend that you use it (or the GRAPHICAL phrase described above) whenever you create a window that will only contain controls. If you do not, your screens will be less portable.

In particular, if the relative size of the font you use in your controls changes in relation to the system's fixed font, then you will experience problems, including overlapping controls. This is because the default cell size that defines the coordinate space is based on a fixed-size font in order to maintain compatibility with character-based applications. The size relationship between the variable-pitch font used in controls and the default fixed-font that defines the coordinate space determines the appearance of the screen. If the relationship changes, the appearance of the screen changes. One way that this can happen is if the end user's machine is missing one of the fonts. In this case, Windows will substitute a different font, which may be a different size. To avoid these problems, define your coordinate space based on the same font that your controls use (with the CELL phrase). Then if the font changes the entire screen is rescaled uniformly.

For example, the following statement defines the coordinate space based on the font used with entry fields. This definition allows you to easily position entry fields vertically with LINE 1, LINE 2, etc., and have it look right.


The USER-GRAY, USER-WHITE, and USER-COLORS phrases provide a convenient way of matching your application's normal colors to those chosen by the user. The USER-GRAY option causes the palette manager to map color number 8 (low-intensity white) to the color that the user has chosen to use with 3-D objects on the host system. Similarly, USER-WHITE maps color number 16 (high-intensity white) to the color the user has chosen to be the normal background color for application windows. If you arrange your application so that it uses color number 8 as the background for regions populated with graphical controls, and color number 16 for plain text regions, your application will look much like other applications on the system.

The USER-COLORS phrase indicates that you want to apply both the USER-GRAY and USER-WHITE options. These phrases are effective only on host graphical systems that have a palette manager. On other systems, these phrases have no effect. Also, note that the palette applies to the entire application. Because of this, you usually specify these options only on the first window you create.

Note: Because Windows make abundant use of 3-D effects in displaying controls, we strongly suggest that you use the USER-GRAY or USER-COLORS options for programs with graphical controls that run under Windows. Graphical controls look best when placed on a "gray" background (color number 8). Other color choices may make 3-D controls look odd.

The TITLE-BAR phrase indicates that you want to have a title bar placed along the top edge of the new window. This phrase is automatically implied by the TITLE phrase (exception: this is not true if you also use the CONTROL VALUE phrase). Under some GUIs (including Windows), you must place a title bar in order to move the floating window with the mouse. Without a title bar, the user's ability to move the window depends on the host GUI. Note that you can have a title bar without specifying a title.

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.


The SYSTEM MENU phrase causes a system menu (also known as a close box) to appear on the created window. This menu allows the user to close the floating window. It may also have additional properties depending on the host system. Under Windows, this menu contains the Move and Close operations. If you include a system menu, your program must be ready to act on a close window event (cmd_close) at any time. See Configuration Section, and Events Reference, in User Interface Programming for more information. See QUIT_MODE Appendix H for shutdown handling options. Note that the SYSTEM MENU phrase also implies the TITLE-BAR phrase.


The NO-CLOSE phrase causes the window's Close menu option to be disabled. This option can be applied only when the window is created and its effects cannot be reversed (the associated window's Close option is permanently disabled). The NO-CLOSE option takes precedence over other settings, including the setting of the QUIT_MODE configuration variable.

  1. The AUTO-RESIZE phrase specifies that the window be displayed with resizable borders. When the window is created, it is displayed full size as defined by the SIZE and LINES phrases. By dragging the resizable borders the user can reduce or increase the size of the window. The runtime automatically adds scroll bars as needed and manages any required scrolling. The window also has a maximize button that allows the user to immediately resize the window to its full size. The exact representation and functioning of the resizable borders and the maximize button is host system dependent. Although the user can change the physical size of the window, the logical size does not change. Neither do controls in the window change size or position. If AUTO-RESIZE is omitted, the window is a fixed size.
  2. The RESIZABLE phrase creates a window that the user can resize but omits the automatic handling provided by the AUTO-RESIZE phrase. When the user resizes the window, the size of the logical window is changed to match the new physical window. Any area that is new is displayed with spaces in the window's background color. Any area that has been removed is lost (although any permanent controls in that area will still exist). The window's subwindow is resized to fill the interior of the resized window. The subwindow's background color is changed to match the window's background color. Other traits of the subwindow remain unchanged. The program receives a NTF-RESIZED event to inform it of the new size. Windows that have the RESIZABLE attribute can use a resize layout manager to help handle the resizing and positioning of controls in the window. See The Resize Layout Manager for more information.
  3. For windows with the RESIZABLE phrase, min-size and min-lines set the windows' smallest width and height respectively. This value is expressed in character cells (fractional cells are ignored). If omitted, or set to zero, the smallest window size is determined by the host system. Similarly, the max-size and max-lines values set the window's largest width and height. If omitted, or set to zero, the host system determines the largest size (usually the entire screen). For windows without the RESIZABLE phrase, these values are ignored.
    Note: Adding or removing a menu or toolbar from a window normally causes the window to be resized to maintain its interior dimensions. For windows with the RESIZABLE phrase, the window is not resized. Instead, the interior dimensions are reduced or increased as needed. You should either modify the window to be the desired size, or inquire the current dimensions when you add or remove a menu or toolbar for resizable windows.
  1. The ACTION phrase allows you to programmatically maximize, minimize, or restore a window. To use ACTION, assign it one of the following values (these names are found in acugui.def):
    ACTION-MAXIMIZE    maximizes the window. It has the same effect as if the user clicked the maximize button. Allowed only for windows that have RESIZABLE or AUTO-RESIZE specified or implied for them.
    ACTION-MINIMIZE minimizes the window. Allowed only with INDEPENDENT windows that have the AUTO-MINIMIZE property set to true. It is not supported with other types of floating windows; if set, it is ignored by the runtime.

    ACTION-MINIMIZE has the same effect as if the user clicked the minimize button.

    ACTION-RESTORE If the window is currently maximized or minimized, restores the window to its previous size and position; otherwise, it has no effect. Allowed only for windows that can be maximized or minimized.
  2. If you assign an ACTION value that is not allowed, then there is no effect other than to trigger the ON EXCEPTION phrase of the MODIFY statement (if present). Note that you can use the ACTION phrase to create a window that is initially maximized or minimized.

The CONTROL VALUE phrase allows you to specify certain attributes of the new window at run time instead of at compile time. control-val must be a numeric expression. In it, you can specify certain floating window traits by adding together any of the following values:

Boxed 1
Shadow 2
No Scroll 4
No Wrap 8
Reverse 16
Title-Bar 32
System Menu 64
User-Gray 128
User-White 256

For each value specified, the corresponding attribute is given to the new window. When a value is not specified, the presence or absence of that trait depends on the other phrases included in the DISPLAY FLOATING WINDOW statement. Note that you can only give traits to a window with the CONTROL VALUE phrase; you cannot negate traits specified by the DISPLAY FLOATING WINDOW statement. For example, if you want to specify at run time whether or not a window gets a shadow, you should omit the SHADOW phrase from the DISPLAY FLOATING WINDOW statement and use a CONTROL VALUE phrase to add shadowing when you want it.


The LAYOUT-MANAGER phrase attaches a layout manager to the window.


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.


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.


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.

  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.
Note: Phrases not described above are described in Common Screen Options.