Command: wtab

Syntax

{ <window> = } wtab <file>

    or

{<window> = } wtab "{"
    <sub_panel_block>
"}"

Description

Define a tab window, which is a panel window with a set of canvas windows selectable by a row of tab buttons, followed optionally by other sub-panels.

Parameters

• <window>
  A window identifier whose contents are to be a layout of sub-panels. If this is omitted, the next free window will be used.

• <file>
  A text file containing the layout and contents of sub-panels. there is no default file extension. If this parameter is not present, sub-panel details will be expected to appear in a language block following the line command.

• <sub_panel_block>
  A language block, providing the layout and contents of sub-panels.

Switches

• -at=<atable>
  An atable to be searched within callback procedures for this window. This means that any identifiers within <atable> referenced in a callback do not have to be prefixed by ~<atable>. This cannot be the local atable.

• -col=<color>
  The background color of the window contents. If omitted, a default color is used.

• -dec=<n>
  A specification of the window decoration to be added by the window manager. Possible values are:
      0 (or -no_dec) for no decoration at all,
      1 for full decoration (the default),
      >1 for custom decoration, see Window Decoration.

• -dim=<screen_xy>
  Define the dimensions of the panel contents area in pixels. This is a two element numeric array. If omitted, the area is computed to enclose all the defined sub-panels.

• -emb=<string>
  Embed the window into a container provided by an external client. <string> is the name of an embed container created by the embed command. If the embed container does not exist or is invalid, this switch is ignored.

• -ent
  Use the behavior such that pressing the Enter key activates (selects) push buttons. The default behavior is for the space key to perform this function. This switch is valid on Windows systems only.

• -fix
  Open the window fixed size, i.e. non-resizable. This is the default behavior. Use -no_fix to make the window resizable. When a panel window is resizable and has scrollbars (-sc) it cannot be grown to a size larger than the sum of its contents.

• -fo=<font>
  The font to be used for sub-panel text. This must be a fixed font. If omitted a default fixed font is used.

• -gap=<num>
  The gap, in pixels, to be used between sub-panels. The default value is four.

• -geo=<screen_box>
  The geometry of the window in screen coordinates, either just its position (a two element array) or its full rectangle geometry (a four element array). The default is the value of <window>.outrect. This will get contracted to just enclose the panel contents.

• -gh
  The window should be initially ghosted, i.e. insensitive to user-interaction. The default is the value of <window>.ghosted.

• -ic
  Open the window in iconic form. The default is the value of <window>.open.

• -inv
  Open the window invisible. The default is the value of <window>.visibility.

• -m=<num>
  The size of the window margin, in pixels, within which sub-panels are positioned. The default value is four.

• -mas
  Define the window as a master window. When a master window is iconized, this also iconizes all other windows.

• -mb
  Give the window a menubar for user buttons. If omitted, the window will be created without a menubar.

• -mf=<font>
  The font to be used for menubar text. This must be a fixed font. If omitted a default fixed font is used. This option has no effect on Windows systems, where menubar font and color are controlled by the window manager.

• -num
  Include the window slot number in the window's title. Use -no_num to suppress it. The default behavior is governed by the value of the system numeric window_numbers.

• -ocol=<color>
  The other color for use in the window, e.g. for text. If omitted, a default color is used.

• -pos=<screen_xy>
  The position of the top left corner of the window in screen coordinates. This is a 2-element array. The default is the value of <window>.outrect[1:2].

• -sc
  Give the window scrollbars. When a window has scrollbars defined, they are only visible when the window size is too small for all sub-panels to be visible. Scrollbars are only defined as default when the window is fixed size (-fix) and external window dimensions have been given (-geo).

• -sh=<string>
  A shell name for communication with X application resources. If omitted, the value panel is used.

• -tb
  Display the window icon in the Windows taskbar. The default behavior is not to display it in the taskbar but only to display it on the desktop when minimized. This switch has no meaning on Unix systems.

• -tit=<string>
  Provide a title for the window. The default is the value of <window>.title.

Block

The <sub_panel_block> or the contents of <file> is made up of definition statements each describing a sub-panel or providing control information for layout purposes.

The window must have as its first sub-panels one or more sub-window definitions. These become selectable by clicking on the tab buttons across the top of the window, so that only one sub-window is visible at any time.

The general form is:

{<name> :} <window-command> {<parameters>} {<switches>}

where:

• <name>
  A user-given name for subsequent sub-window reference purposes.

• <window-command>
  A window insert definition, one of the following commands:

• walpha - an alpha window

• wcomponent - a component window

• wdisplay - a display window

• wgraphic - a graphic window

• window - an empty window slot

• wpanel - a panel window

• wtab - a tab window

• wtable - a table window

• wtree - a tree window

• wweb - a web window

For details of window-command parameters and switches, consult the relevant command. For additional switches pertaining to a sub-window's use within the tab window, refer to the SubWindow Switches paragraph below.

In addition to sub-windows, other sub-panels may be added to the tab window, e.g. push buttons etc. These are displayed below the sub-window area. Their definition is the same as those in panel windows and their general form is:

{<name> :} <sub-panel> {<parameters>} {<switches>}

Please refer to the wpanel command for a description.

Subwindow Switches

These are switches which may be added to a window creation command, e.g. wgraphic, when used within a tab window.

• -im=<file>
  An image file containing an image to appear in the tab-button left justified. Ideally the image should be a 16x16 pixel image but other sizes will be scaled if necessary.

• -inv
  This switch is ignored. Initially, the first sub-window is made visible, other sub-windows are made invisible.

• -link=<text>
  The resize linkage for the sub-window. This ties sub-window edges to one or more edges of the parent tab window, with the result that when the parent window gets resized, the sub-window gets automatically resized as well. <text> is a combination of the characters L, R, T, B and M.

 A value of "LRTB" means that the left, right, top and bottom edges of a sub-window are linked to its parent. The default value is "TL", which links the left and top edges to the parent tab window but does no resizing because its right and bottom edges are not linked. More complicated linkage requirements should be done via the window.resize callback on the parent tab window.

• -tit=<string>
  Text to appear in the tab-button right- justified. If this is omitted, the sub-windows panel name is used. To indicate empty text, e.g. if only an image is required in the button, use -tit=null.

• -tt=<string>
  A tool tip for the sub-window's tab button which will appear when the user rests the mouse cursor over the button. This is available on Windows systems only.

Notes

Interaction with sub-panels may be made during command polling or during pop-up menu selection when used with the -m option.

Details of sub-panel attributes may be examined or set after window creation via the window structure member panels.
Details of tab button attribues may be accessed via the structure member tab_buttons.

Once a tab window is displayed, sub-window selection is made interactively by clicking on the appropriate tab button. Programmatic selection is made by setting to 1 the visibility attribute of a sub-window, or via the selected attribute of the parent tab window.

Examples

# Create a simple resizable tab window to display 4
#    elevation views of the current entity graphics
    window tabwin = wtab -tit='Elevations',-no_fix {
    # The first section comprises 4 sub-windows
        gnorth: wgraphic -dim=<400,400>,-tit='North',-link='TLBR'
        gsouth: wgraphic -dim=<400,400>,-tit='South',-link='TLBR'
        geast: wgraphic -dim=<400,400>,-tit='East',-link='TLBR'
        gwest: wgraphic -dim=<400,400>,-tit='West',-link='TLBR'
    # The second section comprises one push-button sub-panel
        gap 10
        b: button 'Close',-link='B'
        gap 10
    }
 
# Set up initial views
    north tabwin.gnorth
    south tabwin.gsouth
    east tabwin.geast
    west tabwin.gwest
 
# Simple termination button callback
    tabwin.b.exec = {
        args w=window
        ifyes 'Are you sure' { wdelete w }
    }

See Also