GRIDPLUS: Man Page

gridplus::gridplus mode ?option value(s) ...? ?layout?
gridplus::gpmap itemlist valuelist
gridplus::gpset item value
gridplus::gpset {item value ...}
gridplus::gpunset {item ...}

EXPORTS

gridplus
gpmap
gpset
gpunset

DESCRIPTION

The GRIDPLUS package is used to create and layout the contents of TK windows. The package consists of three commands:

gridplus - Create/control screen layouts.
gpmap - Set values of GRIDPLUS items by mapping a list of items to a list of values.
gpset - Set values of GRIDPLUS items.
gpunset - Unset values of GRIDPLUS items.

OPTIONS

Every mode does not necessarily support every option.

-action: Specifies the type of action to take when clicking on a line in a tablelist -or- a node in a tree. Acceptable values are default (Default), double and single. By default the selected line/node is highlighted. double highlights the line/node for a single click and executes the item command for a double-click. single highlights the line/node and executes the item command for a single-click.
-background: Specifies the background color.
-borderwidth: Specifies a non-negative value indicating the width of the 3-D border to draw around the outside of a grid/layout (if such a border is being drawn; the relief option typically determines this).
-buttoncolor: Specifies the foreground color for buttons. The color for the foreground and background colors are separated by a "/". Either may be null, in which case the default colors are used.
-buttonrelief: Specifies the 3-D effect desired for the buttons. Acceptable values are raised (Default), sunken, flat, ridge, solid, and groove. The value indicates how the interior of the buttons should appear relative to its exterior; for example, raised means the interior of the button should appear to protrude from the screen, relative to the exterior of the button.
-century: Specifies a non-negative integer (1-99) to be used as the century window for entry field date validations (Default: 50). Years after the window are considered to be in the previous century. (Example: Assuming -dateformat is us, if the user enters 120160 this will be validated as 12/01/1960).
-columnsort: Determines whether the column sort option is enabled for a tablelist. A value of 0 means that column sort is disabled. 1 (Default) means that column sort is enabled.
-compound: Specifies (for a compound button) the position of the icon/image relative to the text. Valid values for this option are bottom, center, left (Default), right and top.
-dateformat: Specifies the date format for entry field date validations. Acceptable values are eu (dd.mm.yyyy), uk (dd/mm/yyyy) and us (mm/dd/yyyy) (Default).
-deletewindow: Specifies command to executed when associated top-level window is closed/destroyed.
-errormessage: Specifies a text string to be used as field validation error message text. A percent ("%") substitution can be used to include the validation text.
-fileicon: Specifies the default ICONS package icon name to be used for tree "File" nodes.
-foldericon: Specifies the default ICONS package icon name to be used for tree "Folder" nodes.
-foreground: Specifies the foreground color.
-group: Specifies a text string to identify a state group. When creating grid widgets this identifies to group to which the widgets belong. When using the set mode this identfies the group of widgets which will be set to the specified -state.
-height: Specifies height (in lines) of tablelist or text item (Default: 10).
-icon: Specifies the default ICONS package icon name to be used when ":" is used alone.
-iconfile: Specifies the ICONS package icon library file name to be used (Default: tkIcons).
-iconpath: Specifies the the path to the ICONS package icon library file. (Default: [info library] -or [file join $::starkit::topdir lib] if the "::starkit::" namespace exists).
-insertexpr: Specifies an expression to be executed for each line inserted into a tablelist. If the expression evaluates to "true", the options specified by -insertoptions are applied to the line. The expression must be in the format expected by the if command. A percent subsitution facility is available to refer to column values in the line. The column values are indexed from zero, for example, %1 is the second column.
-insertoptions: Specifies a list of tablelist options to be applied if -insertexpr evaluates to true. If the column ID for the option is set to "*" then the option is applied to all columns (in effect the whole line).
-irelief: Specifies the "internal" 3-D effect desired for the notebook. Acceptable values are raised, sunken (Default), flat, ridge, solid, and groove. The value indicates how the interior of the notebook should appear relative to its exterior relief; for example, sunken means the interior of the notebook should appear to sink into the screen, relative to the exterior relief of the notebook.
-justify: Specifies text label justify (Default: left).
-labelcolor: Specifies the foreground color for both labels in a gridplus cell. The color for the left and right labels are separated by a "/". Either may be null, in which case the default color (black) is used.
-labelstyle: Specifies the label text style (bold or italic) for both labels in a gridplus cell. The style for the left and right labels are separated by a "/". Either may be null, in which case the default label text style is used. The label styles may be a comma delimited list (Example: bold/bold,italic. If the style is to also specify the font size (which must be an integer), the font size must appear first in the list (Example: 12/12,bold).
-linewidth: Specifies the width of a gridplus line (Default: 2).
-linkcolor: Specifies the link foreground color. The colors for "normal" and "mouseover" are separated by a "/". Either may be null, in which case the default color (black) is used.
-linkcursor: Specifies the name of the mouse cursor to be displayed when the mouse pointer is over a link (Default: arrow).
-linkstyle: Specifies the link style. The styles for "normal" and "mouseover" are separated by a "/". Either may be null, in which case the default style (/underline) is used. The "normal" and "mouseover" styles may be a comma delimited list (Example: bold/bold,underline. If the style is to also specify the font size (which must be an integer), the font size must appear first in the list (Example: 12/12,underline). Where the "mouseover" style is based on the normal style, a "&" may be used (Example: 12,bold/&underline is the same as 12,bold/12,bold,underline). The text widget supports the underline style only.
-modal: Determines whether the created top-level window will be modal. A value of 0 (Default) means that window will not be modal. 1 means that the window will be modal.
-options: Specifies a list of item options. Currently this is available for tablelist only. Acceptable values are stripe and separator.
-pad: Specifies a non-negative value indicating how much extra space to request for grids/layouts in both the X and Y directions. When computing how large a window it needs, the widget will add this amount to the height and width it would normally need (as determined by the width and height of the things displayed in the grid/layout); if the geometry manager can satisfy this request, the grid/layout will end up with extra internal space to the left and/or right, top and/or bottom of what it displays inside.
-padx: Specifies a non-negative value indicating how much extra space to request for grids/layouts in the X-direction. When computing how large a window it needs, the widget will add this amount to the width it would normally need (as determined by the width of the things displayed in the grid/layout); if the geometry manager can satisfy this request, the grid/layout will end up with extra internal space to the left and/or right of what it displays inside.
-pady: Specifies a non-negative value indicating how much extra space to request for grids/layouts in the Y-direction. When computing how large a window it needs, the widget will add this amount to the height it would normally need (as determined by the width of the things displayed in the grid/layout); if the geometry manager can satisfy this request, the grid/layout will end up with extra internal space to the top and/or bottom of what it displays inside.
-pattern: Specifies a regular expression -or- procedure to be associated with a validation. To specify a procedure use the proc:procname format.
-prefix: Specifies a prefix to be used to the GRIDPLUS generated callback/procedure names. (Example: if the prefix is set to "myprefix" and the procedure name would normally be "toolbar,save", the procedure name will be "myprefix:toolbar,save".
-proc: Determines whether gpProc will be invoked for a button/menu action rather than a widget specific procedure. A value of 0 means that the widget specific procedure should be invoked (Default). 1 means that gpProc should be invoked.
-relief: Specifies the 3-D effect desired for the gird/layout border. Acceptable values are raised, sunken, flat, ridge, solid, and groove (Default). The value indicates how the interior of the grid/layout should appear relative to its exterior; for example, raised means the interior of the grid/layout should appear to protrude from the screen, relative to the exterior of the grid/layout.
-scroll: Specfies whether the (tablelist or text) item should have scrollbars. Acceptable values are x, y and xy. The value indicates which scrollbars should be used, x (horizontal) and/or y (vertical).
-selectfirst: Determines whether the first line of a tablelist will be automatically selected when the tablelist content is updated using gpset. A value of 0 (Default) means that the first line will not be selected. 1 means that the first line will be selected.
-selectmode: Specifies one of several styles for manipulating the selection. Acceptable values are single, browse (Default), multiple, or extended.
-size: Specfies the default width (Default: 8) in "average" characters of grid widgets (button/entry).
-sortfirst: Determines whether the tablelist contents will be automatically sorted on the first column when the tablelist content is updated using gpset. A value of 0 (Default) means that the tablelist will not be sorted. 1 means that the tablelist will be sorted.
-sortorder: Specifies the default order for tablelist sort when the tablelist content is updated using gpset. Acceptable values are increasing (Default) and decreasing.
-space: Specifies a non-negative value indicating how much extra space to request for between columns in grids/layouts (Default: 20).
-state: Specifies the state which grid widgets will be created/set to. Acceptable values are normal (Default) and disabled.
-style: Specfies to be used. The style must have been previously created using gridplus style.
-subst: Determines whether null array variable substitution will be performed. A value of 0 means that subsitution is not performed. 1 means that substitution will be performed (Default).
-taborder: Specifies the primary direction of keyboard traversal (e.g., Tab and Shift-Tab) of grid widgets. Acceptable values are column (Default) and row.
-tags: Determines whether the text widget will have tag processing enabled. A value of 0 (Default) means that tag processing is not enabled. 1 means that tag processing is enabled.
-takefocus: Determines whether the grid widgets accept the focus during keyboard traversal (e.g., Tab and Shift-Tab). Before setting the focus to a window, the traversal scripts consult the value of the takeFocus option. A value of 0 means that the grid widgets should be skipped entirely during keyboard traversal. 1 means that the grid widgets should receive the input focus.
-text: Specifies the text to be associated with a validation pattern.
-title: Specifies a string of text to be used as a border title. When this option is specified the value of -relief is automatically set to groove.
-treemode: Specifies mode to use when setting the contents of a tree. Acceptable values are contract (Default), or expand.
-validation: Specifies the name of an entry field validation.
-variables: Determines whether the gridplus item variables are cleared when using the gridplus clear command. A value of 1 (Default) means that the variables will be cleared. 0 means that the variables will not be cleared.
-width: Specifies width (in characters) of tablelist or text item (Default: 40).
-wrap: Specifies how to handle lines in the text that are too long to be displayed in a single line of the text's window. Acceptable values are none, char or word. A wrap mode of none means that each line of text appears as exactly one line on the screen; extra characters that don't fit on the screen are not displayed. In the other modes each line of text will be broken up into several screen lines if necessary to keep all the characters visible. In char mode a screen line break may occur after any character; in word mode a line break will only be made at word boundaries.
-wraplength: Specifies length at which to wrap text labels. By default no wrapping occurs.

GRIDPLUS WIDGET OPTIONS

.name: The name of the widget (Example: .b1).
:icon: The name of the icon to be used for button (button) -or node (tree) (Example: :navback16). The icon name can also be null (button), in which case the icon specified by the -icon option is used.
%group: The name of the group to which widget belongs (Example: %mygroup1).
<: Create widget with disabled state. Overrides -state option.
>: Create widget with normal state. Overrides -state option.
@name: Insert specfied grid/layout/widget (Example: @myoptions).
?helptext: Specifies text to be used for button pop-up/balloon help (Example: ?Print). If the text contains spaces double quotes must be used (Example: "?Exit Application").
!name: Specifies name of validation to be used for entry (Example: !int) -or- When "!" is used alone this indicates that entry validations are to be perfomed (for the window containing the button/link/menu) prior to evaluating the callback.
|: Specifies that a vertical bar separator be created.
+value: Specifies that the widget should be created in selected mode (checkbutton/radiobutton) -or- have focus (entry) -or- a "bullet" should be displayed (link) -or- the node is to be "Folder" type (tree). The use of value is for radiobuttons only an dspecifies the value of the radiobutton Grid when this radiobutton is selected.
-value: Specifies that the widget should be created in deselected mode (checkbutton/radiobutton), a separator line is displayed (menu) -or- widget is indented (link). The use of value is for radiobuttons only an dspecifies the value of the radiobutton Grid when this radiobutton is selected.
*: Specifies that the widget should display "*" for each character entered (entry).
~command: Specifies that a command is invoked when the enter key is pressed while the widget has focus (entry). The command name is optional. If not specified command name is based on the name of widget.
integer: Specifies a positive integer which overrides the default size for the widget.
text: Specifies text to be used as widget label. The text may also have an optional colon (":") delimited sticky indicator: n, s, e, w (Default) or c (Centre) (Example: "First Name:e").

GRIDPLUS GRID/LAYOUT

In this section "grid" refers to a "GridPlus grid" and "layout" to a "GridPlus layout".

The positions of display items/widgets is defined as a combination of grid layouts and layouts of grids.

The GridPlus grid command, and all of the GridPlus widget grid commands which are built on the GridPlus grid, create a grid of widgets and labels. Any cell in a grid or entry grid may contain a grid, any TK widget or a layout.

The grids are positioned using a layout. The layout is also a grid, but has different options/properties. Any cell within a layout may contain a grid, any TK widget or another layout.

GRID

The grid uses a relative placement facility. Each cell in the grid may have 0,1 or 2 elements. An element begining with "." is considered to be a path to a widget, anything else is considered to be a text label. Each (non-empty) cell may contain a combination of 1 or 2 elements. Normally this would be a widget and a text label, or a widget only, but two widgets or labels is allowed. Each cell consists of two columns. This allows widgets with labels to be easily created and automatically sized/lined-up based on the size of the contents. The order in which the elements appear in the cell is set by the order in which they are defined. The first element into the first column, the second into the second column. If the cell contains a single element this will span both columns. Each element may optionally have a colon (":") delimited sticky indicator, n, s, e, w (Default) or c (Centre). A cell with 0 elements creates an empty cell. A cell may also contain a vertical bar ("pipe"), which will be displayed as a vertical bar separator.

LAYOUT

The layout command has capabilities similar to that when using the relative placement facility of the TK grid widget. Each cell may optionally have a colon (":") delimited sticky indicator, n, s, e, w (Default) or c (Centre).

-: This increases the columnspan of the cell to the left. Several -'s in a row will successively increase the columnspan. A - may not follow a ^ or a x, nor may it be the first cell.
x: This leaves an empty column between the cell on the left and the cell on the right.
^: This extends the rowspan of the cell above the ^'s in the grid. The number of ^'s in a row must match the number of columns spanned by the cell above it.

COMMANDS

The gridplus command is used to create and control TK screen layouts. It can take several different forms, depending on the mode argument. The legal forms are: