DISPLAY control-type-name

Format 14

DISPLAY control-type-name creates a graphical control, including a graphical ActiveX or COM control. 

DISPLAY {control-type-name  }
        {OBJECT control-type}

 [ title ]

 [ UPON new-window ]

Remaining phrases are optional, can appear in any order. 

{IDENTIFICATION} {IS} control-id
{ID            } {= }

AT screen-loc   [CELL  ]
                [CELLS ]
                [PIXEL ]
                [PIXELS]

AT LINE NUMBER line-num   [CELL  ]
                          [CELLS ]
                          [PIXEL ]
                          [PIXELS]

AT {COLUMN  } NUMBER col-num   [CELL  ]
   {COL     }                  [CELLS ]
   {POSITION}                  [PIXEL ]
   {POS     }                  [PIXELS]

AT CLINE NUMBER cline-num   [CELL ]
                            [CELLS]

AT CCOL NUMBER ccol-num   [CELL ]
                          [CELLS]

SIZE  {IS} length [CELL  ]
      {= }        [CELLS ]
                  [PIXEL ]
                  [PIXELS]

LINES {IS} height [CELL  ]
      {= }        [CELLS ]
                  [PIXEL ]
                  [PIXELS]

CSIZE   {IS} clength  [CELL ]
        {= }          [CELLS]

CLINES  {IS} cheight  [CELL ]
        {= }          [CELLS]

MAX-HEIGHT {IS} max-height
           {= }

MAX-WIDTH  {IS} max-width
           {= }

MIN-HEIGHT {IS} min-height
           {= }

MIN-WIDTH  {IS} min-width
           {= }
TITLE {IS} title
      {= }

KEY   {IS} key-letter
      {= }

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

STYLE {IS} style-flags
      {= }

{style-name} ...

VALUE {IS} [ MULTIPLE ] value [ LENGTH {IS} length-1 ]
      {= } [ TABLE    ]                {= }

FONT {IS} font-handle
     {= }

HANDLE {IN} control-handle
       {IS}

LAYOUT-DATA {IS} layout-data
            {= }
ENABLED  {IS} {TRUE         }
         {= } {FALSE        }
              {enabled-state}

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

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

HELP-ID {IS} help-id
        {= }

EVENT-LIST    {IS} ( event-value { event-value ... } )
              {= }

AX-EVENT-LIST {IS} ( ax-event-value { ax-event-value ... } )
              {= }

EXCLUDE-EVENT-LIST {IS} list-state
                   {= }

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

{{property-name         } {IS } property-option 
                                        [GIVING result-1]}. ...
 {PROPERTY property-type} {ARE}

where property-option is one of the following: 

    { property-value [ LENGTH {IS} length-1 ] }
    {                         {= }            }
    { ( {property-value} ... )                }
    {                                         }
    { {MULTIPLE} property-table               }
    { {TABLE   }                              }

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. control-type-name is one of the control type reserved words known by the compiler.
  3. control-type iNew-windows a numeric literal or data item.
  4. new-window is a USAGE HANDLE or PIC X(10) data items. If used, the UPON phrase must be the first optional phrase specified.
  5. control-id is an integer numeric literal or data item. Its value should be in the range of 0 to 32767.
  6. screen-loc is an integer data item or literal containing exactly 4, 6, or 8 digits. It may also be a group item of 4, 6, or 8 characters. If a numeric item is used, it must be a non-negative integer.
  7. line-num, col-num, cline-num, ccol-num, length, height, clength, and cheight are numeric data items or literals. They may be non-integer values, except when pixels are specified. You can also specify the value of any of these items with an arithmetic expression.
  8. max-height, max-width, min-height, and min-width are numeric data items or literals.
  9. color-val is a numeric data item or literal. color-val can also be an arithmetic expression.
  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. title is an alphanumeric literal or data item. In Format 14, title may appear only once, either in a TITLE phrase or the initial title option. The title option must be the first option specified.
  12. key-letter is an alphanumeric literal or data item.
  13. font-handle is a data item of type USAGE HANDLE or HANDLE OF FONT.
  14. style-flags is a numeric expression.
  15. style-name is the name of a style associated with the class of control being described. If control-type-name is omitted, then you may not use the style-name phrase. You may use the STYLE phrase instead.
  16. value is a literal or data item. If the MULTIPLE option is specified, then value must be a one-dimensional table. In this case, value is not subscripted.
  17. length-1 is a numeric literal or data item. The LENGTH phrase may be specified only if the immediately preceding value or property-value is an alphanumeric literal or data item, and not a figurative constant. In addition, the MULTIPLE option may not be specified along with the LENGTH phrase.
  18. control-handle is a USAGE HANDLE data item.
  19. layout-data is an integer literal, data item, or expression.
  20. enabled-state, visible-state, and help-id are integer numeric literals or data items.
  21. menu-1 is a USAGE HANDLE or HANDLE OF MENU data item.
  22. event-value and ax-event-value are numeric literals or data items that identify an event type. List elements must be enclosed in parentheses. Elements must be separated by a space. If the list contains a single element, the parentheses can be omitted.
  23. list-state is an integer literal or numeric data item. Valid values are 0 and 1.
  24. proc-1 and proc-2 are procedure names.
  25. property-name is the name of a property specific to the type of control being referenced. If the type of control is unknown to the compiler (as in a DISPLAY OBJECT object-1 statement), then property-name may not be used. You must use the PROPERTY property-type option instead.
  26. property-type is a numeric literal or data item. It identifies the property to modify. The numeric values that identify the various control properties can be found in the COPY library "controls.def".
  27. property-value is a literal or data item. Property-value may also be a numeric expression (however, only the first property-value in a phrase may be an expression, subsequent values must be literals or data items). When multiple values are specified, the parentheses are required. An example of their use is: DISPLAY-COLUMNS = ( 1, 20 )
  28. property-table is a data item that appears in a one-dimensional table. No index should be specified.
  29. result-1 is a numeric data item.
  30. If the title option is used, it must be the first optional phrase.
  31. If the UPON phrase is specified, it must be the first optional phrase, except when the title option is used, then the UPON phrase must be second, following the title phrase.
  32. If the AT phrase is specified, neither the LINE nor the COLUMN phrase may be specified.
  33. If the COLOR phrase is specified, neither the FOREGROUND-COLOR nor the BACKGROUND-COLOR phrase may be specified.
  34. If the CELLS option is used in either the SIZE or CSIZE phrase, it must be present in both phrases if both are specified. The same rule applies to the CELLS option in the LINES and CLINES phrases.
  35. The HANDLE phrase may be specified anywhere in the statement after the required initial elements.
  36. IS and "=" are synonymous.
  37. COLUMN, COL, POSITION, and POS are equivalent.
  38. HIGHLIGHT, HIGH, and BOLD are synonymous.
  39. LOWLIGHT and LOW are equivalent.
  40. COLOR and COLOUR are synonymous.
  41. FOREGROUND-COLOR and FOREGROUND-COLOUR are synonymous.
  42. BACKGROUND-COLOR and BACKGROUND-COLOUR are synonymous.
  43. MULTIPLE and TABLE are synonymous.

General Rules

  1. The DISPLAY control-type-name verb creates a new control and displays it on the screen. A handle to the new control is returned in control-handle. The handle is used in future references to the control. If control-handle is not specified, the control is an anonymous control. Anonymous controls can be referenced in future statements only by position.
  2. control-type-name identifies the type of the control. The exact set of controls available and their types are discussed in Control Types Reference in User Interface Programming. Use OBJECT control-type when the control type is not known at compile time. At run time, control-type must contain the identifying number of a control type known to the system. If it does not correspond to any control type, the DISPLAY statement is ignored and control-handle is set to NULL. The identifying number of each control type is defined in the controls.def COPY file.
  3. The LENGTH option of the VALUE and property phrases establishes the exact size of the source data to use. Without the LENGTH option, a text value presented to the control is the data contained in the COBOL data element with trailing spaces removed. When you specify the LENGTH option, exactly length-1 characters of the data are used instead. No trailing space removal occurs. This is useful in a few cases when you need to treat trailing spaces as data.

    If length-1 is a value larger than the size of the data item it is modifying, then the size of the data item is used instead. If length-1 is negative, it is ignored and the default handling occurs.

  4. Some properties return specific values when set. These values are placed in result-1 of the GIVING phrase. The meaning of the value depends on the property being set; see the documentation for the specific property. Properties that do not have a pre-defined return value set result-1 to 1 if the property was set successfully, or 0 if not. When a property is being given multiple values in a single assignment (for example: Display-Columns = (1, 10, 30)), then result-1 is set in response to the last value assigned.
  5. After the DISPLAY statement is executed, the cursor is positioned at the first whole column immediately to the right of the control. If this column is past the right edge of the current subwindow, the cursor is not moved from its previous location.
  6. Once created, a control remains in existence until one of the following events:
    1. The control is explicitly destroyed with a DESTROY verb.
    2. The control has the TEMPORARY style, the control is overwritten.
    3. The window containing the control is destroyed.
  7. Under some systems, controls do not interact properly with pop-up subwindows. This is due to the fact that the controls are maintained by the GUI directly while pop-up subwindows are managed by the ACUCOBOL-GT runtime system. Since the GUI is not aware of the pop-up nature of the subwindow, it displays the control over the subwindow, even if the program's intent is to have the pop-up subwindow on top. For this reason, pop-up subwindows are not recommended for programs that will be using graphical controls. You should use floating windows instead.
  8. The POP-UP MENU phrase associates a pop-up menu with the control. If menu-1 is specified, then the menu associated with menu-1 becomes the pop-up menu. If NULL is specified, the control 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 control.
  9. Any phrases not described there behave in the same manner as in a Format 1 DISPLAY statement. See Common Screen Options for a description of the remaining optional phrases.
  10. The runtime ignores events from all controls while it is creating an ActiveX control, via the DISPLAY statement or otherwise. If you are using a control that delivers significant information using events and you don't want to miss those events while you are creating a new control, set the CONTROL_CREATION_EVENTS runtime configuration variable to 1 (On, True, Yes). Alternatively, you could avoid creating an ActiveX control when you are expecting an event.
Parent topic: DISPLAY Statement