GRIDPLUS2: Man Page

gridplus::gridplus mode ?option value(s) ...? ?layout?
gridplus::gpclear ?item?
gridplus::gpcopy ?item?
gridplus::gpcut ?item?
gridplus::gpfind item string ?direction?
gridplus::gpfind_dialog ?item?
gridplus::gpinsert item position value
gridplus::gpmap itemlist valuelist ?direct|left|right?
gridplus::gpmap itemlist elementlist array
gridplus::gppaste ?item?
gridplus::gpselect item match ?column?
gridplus::gpset item value
gridplus::gpset {item value ...}
gridplus::gpunset {item ...}

EXPORTS

gridplus
gpclear
gpcopy
gpcut
gpfind
gpfind_dialog
gpinsert
gpmap
gppaste
gpselect
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.
gpclear - Clear (delete) selected text.
gpcopy - Copy seleted text to clipboard.
gpcut - Copy seleted text to clipboard and then delete.
gpfind - Find and select specified string in text item.
gpfind_dialog - Popup "Find" dialog box to find and select specified string in text item.
gpinsert - Insert a row at a specfied position into a text or tablelist item.
gpmap - Set values of GRIDPLUS widgets by mapping a list of items to a list of values or array elements.
gppaste - Paste text from clipboard.
gpselect - Select a specified row/node in a tablelist/tree widget.
gpset - Set values of GRIDPLUS widgets.
gpunset - Unset values of GRIDPLUS widgets.

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.
-anchor: Specifies how to place the grid within the master when no row/column has any weight (Default: s).
-attach: Specifies where in a cell that the contents will be "attached". Valid values for this option are n, w and "null" (Default). If the default value (null) is used the contents will be attached to all points - meaning the contents will "stretch" to fill the cell. The other values allow the contents to be attached (justified) to the top and/or left of the cell.
-autogroup: Specifies a string to identify a state group to be set to the "normal" state when the associated entry/text widget is updated. When specified for an entry/widget grid, the group is associated with all entry widgets in the grid.
-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).
-ccmd: Specifies command to executed when an associated checkbutton is selected. Alias -checkbuttoncommand.
-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).
-cfmt: Specifies, on a per-column basis, the width of the left and right elements. The format is specifed as a list. Each item in the list is applied to the corresponding column in the grid. Each item consists of up to two elements separated by a "/" (left_width/right_width). Each element is optional. Where an element is not specified the width of the column element will be based on the size of the largest widget (as normal). Acceptable formats are: left_width , left_width/right_width, /right_width (Examples: 15 15/25 /25). Alias -columnformat.
-checkbuttoncommand: Specifies command to executed when an associated checkbutton is selected. Alias -ccmd.
-columnformat: Specifies, on a per-column basis, the width of the left and right elements. The format is specifed as a list. Each item in the list is applied to the corresponding column in the grid. Each item consists of up to two elements separated by a "/" (left_width/right_width). Each element is optional. Where an element is not specified the width of the column element will be based on the size of the largest widget (as normal). Acceptable formats are: left_width , left_width/right_width, /right_width (Examples: 15 15/25 /25). Alias -cfmt.
-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.
-command: Specifies command to executed when a Tablelist/Tree action is invoked.
-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).
-dropdowncommand: Specifies command to executed when an item is selected from an associated dropdown list. When specified for a dropdown/widget grid the command is associated with all dropdown widgets in the grid.
-ecmd: Specifies command to executed, or event to be generated, when the enter/return key is pressed in an associated entry widget. When specified for a entry/widget grid the command/event is associated with all entry widgets in the grid. Alias -entrycommand.
-entrycommand: Specifies command to executed, or event to be generated, when the enter/return key is pressed in an associated entry widget. When specified for a entry/widget grid the command/event is associated with all entry widgets in the grid. Alias -ecmd.
-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.
-fixed: Specifies the maximum number of characters an entry widget will accept (Default 999999 characters). If the number of characters is set to null, the value will be taken from the width of the entry widget.
-foldericon: Specifies the default ICONS package icon name to be used for tree "Folder" nodes.
-font: Specifies the font to use when drawing text inside the text widget. This option is ignored if the -tags option is set to "1".
-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 path to the ICONS package icon library file. (Default: [info library] -or [file join $::starkit::topdir lib] if the "::starkit::" namespace exists).
-icons: Determines whether the Tree nodes display icons. A value of 0 means that the Tree will not display icons. 1 (Default) means that the Tree will display icons.
-in: Specifies the name of a container in which to put the window. The default is for the window to be created as a normal (managed) toplevel window.
-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).
-justify: Specifies text label justify (Default: left).
-labelanchor: Specifies where to place the label. Allowed values are (clockwise from the top upper left corner): nw, n, ne, en, e, es, se, s, sw, ws, w and wn. The default value is theme-dependent.
-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).
-linerelief: Specifies the 3-D effect desired for the girdplus line. Acceptable values are raised, sunken (Default), flat, ridge, solid, and groove. The value indicates how the line should appear relative to its exterior; for example, raised means the line should appear to protrude from the screen.
-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.
-menu: Specifies name of menu to pop-up when right-clicking to select a tablelist/tree item.
-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.
-optionset: Specfies optionset to be used. The optionset must have been previously created using gridplus optionset.
-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.
-padding: Specifies the amount of extra space to allocate for the widget. The padding is a list of up to four length specifications left top right bottom. If fewer than four elements are specified, bottom defaults to top, right defaults to left, and top defaults to left.
-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.
-radiobuttoncommand: Specifies command to executed when an associated radiobutton is selected. Alias -rcmd.
-rcmd: Specifies command to executed when an associated radiobutton is selected. Alias -radiobuttoncommand.
-relief: Specifies the 3-D effect desired for the gird/layout border. Acceptable values are raised, sunken, flat (Default), ridge, solid, groove and theme. 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. When set to theme the Tile theme style is used.
-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.
-show: Specifies a list containing zero or more of the following values, specifying which elements of the tree to display. Acceptable values are tree (Display tree labels in column #0), headings (Display the heading row). The default is tree headings.
-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.
-sticky: Specifies where in the container that the contents will be "attached". Valid values for this option are n, s, e, w (and combinations thereof) and "null" (Default).
-stretchx: Determines whether the contents of a grid will stretch in the "x" (horizontal) direction. A value of 0 means that the space between the grid columns will not stretch. 1 (Default) means that the space between columns will stretch.
-stretchy: Determines whether the contents of a grid will stretch in the "y" (vertical) direction. A value of 0 means that the space between the grid rows will not stretch. 1 (Default) means that the space between rows will stretch.
-style: Specfies Tile style to be used. If there is an optionset with the same name as the style, it will also be applied.
-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).
-tableoptions: Specifies a list of tablelist options. Acceptable values are stripe and separator.
-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 theme (Use style defined for Tile labelframe).
-topmost: Determines whether the created top-level window will be a "topmost" (stay on top) window. A value of 0 (Default) means that window will not be topmost. 1 means that the window will be topmost.
-validate: Determines whether entry validation will be performed when a Tablelist/Tree row/node is selected. A value of 0 (Default) means that validation processing is not enabled. 1 means that validation processing is enabled.
-validateauto: Determines whether entry validation will be performed automatically when an entry looses focus. A value of 0 means that validations are performed only when explicity invoked. 1 (Default) means that validations are performed automatically when an entry looses focus.
-validatepopup: Determines whether entry validation popup error messages are to be displayed. A value of 0 (Default) means that validation popups are not enabled. 1 means that validation popups are enabled.
-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.
-wcmd: Specifies command to executed when associated top-level window is closed/destroyed (Default: gridplus clear and destroy the window). Alias -windowcommand.
-widget: Specifies the default widget type for the grid. Acceptable values are b (Button), c (Checkbutton), d (Dropdown "combobox"), e (Entry), l (Link), m (Menubutton), r (Radiobutton), w (Widget grid). Whole words can be specified as only the first character is used. For example: "radiobutton" could be used instead of "r". By default label widgets are created.
-width: Specifies width of button and entry widgets (Default 10 characters), tablelist and text widgets (Default: 40 characters), tree widget (Default: 200 pixels).
-windowcommand: Specifies command to executed when associated top-level window is closed/destroyed (Default: gridplus clear and destroy the window). Alias -wcmd.
-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.
-wtitle: Specifies a string of text to be used as a window title.

GRIDPLUS WIDGET OPTIONS

&type: The type of the widget (Example: &e). Acceptable values are b (Button), c (Checkbutton), d (Dropdown "combobox"), e (Entry), l (Link), m (Menubutton), r (Radiobutton), w (Embedded Widget grid), wc (Embedded Checkbutton grid), wd (Embedded Dropdown grid), we (Embedded Entry grid), wl (Embedded Link grid), wm (Embedded Menubutton grid), wr (Embedded Radiobutton grid).
&type:style/optionset: As above but with specified style/optionset.
.name: The name of the widget (Example: .b1).
.proc=parameter: The name of the widget. This is an optional way to define a widget name for buttons. Using the example: .myproc=myparameter, the widget will be called ".myproc=myparameter", the procedure called when the button is pressed will be "myproc" to which will be passed a parameter, in this case "myparameter".
: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.
<group: Specifies that widgets belonging to group will have state set to "disabled" when the widget content is modified.
>: Create widget with normal state. Overrides -state option.
>group: Specifies that widgets belonging to group will have state set to "normal" when the widget content is modified.
@name: Insert specfied grid/layout/widget (Example: @myoptions).
?helptext: Specifies text to be used for widget pop-up/balloon help (Example: ?Print). If the text contains spaces double quotes must be used (Example: "?Exit Application").
?!: Specifies text to be used for widget pop-up/balloon help is set to be the same as the validation error message.
!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.
!name?message: Specifies name of validation to be used for entry and the validation error message to be displayed if the validation fails (Example: "!date?Must be a valid date").
!@name: Specifies name of validation to be used for entry. This format (prefixed "!@") indicates that the entry may also be null. (Example: !@int - The value of the entry must be an integer or may be left blank)
!@name?message: Specifies name of validation to be used for entry and the validation error message to be displayed if the validation fails (Example: "!@date?Must be a valid date" - The value of the entry must be a valid date or may be left blank).
|: Specifies that a vertical bar separator be created.
=: Specifies that a horizontal bar separator be created.
+value: Specifies that the widget should be created in selected mode (checkbutton/radiobutton) -or- have focus (entry) -or- the dropdown list should be set to the specified list (dropdown) -or- a "bullet" should be displayed (link) -or- the node is to be "Folder" type (tree). The use of value is for dropdowns where the dropdown list should be set to the specified list with the widget value set to the first item in the list -and- radiobuttons where it specifies 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/event is invoked when the enter key is pressed while the widget has focus (entry), that a command is invoked when a checkbutton/radiobutton is selected -or- that a command is invoked when a list item is selected (dropdown). The command name is optional. If not specified command name is based on the name of widget. This option may also be used to specify the name of the command to be invoked for buttons and menu items.
integer: Specifies a positive integer which overrides the default size for the widget.
integer1/integer2: Specifies two positve integers which override the default "size" (integer1) and "fixed" number of characters (integer2) for the entry widget. Both integer values are optional. If integer1 is not specified the current default "size" is used for the entry. If integer2 is not specifed the fixed number of characters is set to the same value as the specified/default "size".
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 -or- "=" which will be displayed as a horizontal 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). A cell may also contain a vertical bar ("pipe"), which will be displayed as a vertical bar separator -or- "=" which will be displayed as a horizontal bar separator.

-: 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: