DISPLAY TOOL-BAR

Format 13

DISPLAY TOOL-BAR adds a toolbar to the current window.

DISPLAY TOOL-BAR
HANDLE {IS} handle-name
       {IN}

Remaining phrases are optional, can appear in any order.

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

CONTROL FONT {IS} font-1
             {= }

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

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}

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. height is a numeric data item or literal. It may be a non-integer value. You can also specify the value as an arithmetic expression.
  3. color-val is a numeric data item, numeric literal, or arithmetic expression
  4. 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.
  5. font-1 is a USAGE HANDLE or HANDLE OF FONT data item. It should contain a valid handle to a screen font.
  6. handle-name is a USAGE HANDLE, HANDLE OF WINDOW, or PIC X(10) data item.
  7. If the COLOR phrase is specified, neither the FOREGROUND-COLOR nor the BACKGROUND-COLOR phrase may be specified.
  8. The HANDLE phrase may be specified anywhere in the statement after the required initial elements.
  9. IS and "=" are synonymous.
  10. HIGHLIGHT, HIGH and BOLD are synonymous.
  11. LOWLIGHT and LOW are equivalent.
  12. COLOR and COLOUR are synonymous.
  13. FOREGROUND-COLOR and FOREGROUND-COLOUR are synonymous.
  14. BACKGROUND-COLOR and BACKGROUND-COLOUR are synonymous.
  15. cell-units is a positive integer data item or literal.

General Rules

  1. DISPLAY TOOL-BAR adds a toolbar to the current floating or main-application window. A toolbar is a region of the window that is devoted to holding buttons and other controls that are used as mouse accelerators that the user can activate with the mouse to quickly specify a program operation. Toolbars extend across the entire width of the window. They appear at either the top or the bottom of the window depending on the host system. Under Microsoft Windows, toolbars appear at the top of the window.

    On character-based systems, toolbars are created but are always invisible. This is done to simplify cross-platform support: you can unconditionally create toolbars in your application. They will seem to behave properly on character-based systems, but they will not actually show up.

  2. You may have more than one toolbar associated with a particular window. All toolbars associated with a window are stacked vertically in the order that they are created. You may have a maximum of five toolbars associated with each window.
  3. Like menu-bars, the space that a toolbar occupies is not part of the body (client area) of the window. When you create a toolbar, the window it is attached to is enlarged to accommodate the space required by the toolbar (unless the window is RESIZABLE; see the description of the RESIZABLE phrase in the General Rules section of the Format 11 DISPLAY statement). You do not lose any application space when adding a toolbar to a window, except as constrained by the physical screen. Toolbars do not scroll when the body of the window is scrolled. Instead, the toolbar remains accessible at the top of the window. Toolbars automatically grow and shrink horizontally to match the width of the owning window.
  4. In several respects, toolbars act like windows. Because of this, they are called child windows of the window they are attached to. When you create a toolbar, a handle that identifies it is returned in handle-name. Like other window handles, you can use handle-name in an UPON phrase of a DISPLAY statement to direct output to the toolbar. You can also use handle-name in a DESTROY statement to remove the toolbar. Unlike other windows, toolbars are not made current or active when they are created. This means that the only way to place a control on the toolbar is with the UPON phrase.
  5. Toolbars cannot take textual output (i.e., text-style ACCEPT and DISPLAY statements cannot refer to a toolbar). You can only place graphical controls on a toolbar. However, any type of graphical control may be placed on a toolbar. Most commonly, push buttons appear on toolbars (either text or bitmap buttons), as well as bitmap check-boxes and radio-buttons.
  6. font-1 identifies the default font to use for any controls shown in the toolbar. If font-1 is not specified, DEFAULT-FONT is used.
  7. height specifies the height of the toolbar. Height units are derived from the height of font-1 (or DEFAULT-FONT if font-1 is not used). If height is omitted, then the toolbar uses a host-dependent default height.
  8. The color and intensity phrases have their usual meaning as described in Common Screen Options. The toolbar directly uses the background-color and background-intensity only when it is drawn. The foreground-color and intensity are used as defaults for controls displayed on the toolbar. Any color and intensity elements that are omitted from the DISPLAY TOOL-BAR statement are inherited from the window that the toolbar is attached to.
  9. The easiest way to make effective use of a toolbar is to populate it with controls that can act like function keys. When you do this, the toolbar acts in a manner that is very similar to a menu bar. This simplifies other programming because you do not need to attempt to directly activate the controls on the toolbar. Controls that can act like function keys are push buttons, check boxes and radio buttons. For push buttons, use the SELF-ACT style. For check boxes and radio buttons, use both the SELF-ACT and NOTIFY styles. This ensures that these controls behave like function keys (i.e., they activate themselves when clicked, and inform your program).