GRIDPLUS - Man Page
Home Reference Manpage Examples Download License Contact
NAME
::gridplus::gridplus - Create/control GridPlus window layouts.
EXPORTS
icons
SYNOPSIS
package require gridplus ?1.2?
gridplus::gridplus mode ?option value(s) ...? ?layout?
gridplus::gpmap itemlist valuelist
gridplus::gpset item value
gridplus::gpset {item value ...}
gridplus::gpunset {item ...}
DESCRIPTION
OPTIONS
-action type
-background color
-borderwidth width
-buttoncolor color/color
-buttonrelief style
-century year
-columnsort boolean
-compound position
-dateformat format
-deletewindow command
-errormessage message
-fileicon icon
-foldericon icon
-foreground color
-group groupname
-height amount
-icon icon
-iconfile filename
-iconpath path
-insertexpr expression
-insertoptions options
-irelief style
-justify position
-labelcolor color/color
-labelstyle style/style
-linkcolor color/color
-linkcursor cursor
-linkstyle style/style
-modal boolean
-options options
-pad amount
-padx amount
-pady amount
-pattern regexp
-prefix prefix
-proc boolean
-relief style
-scroll scrollbars
-selectfirst boolean
-selectmode mode
-size width
-sortfirst boolean
-sortorder order
-space spacing
-state state
-style style
-subst boolean
-taborder order
-tags boolean
-takefocus boolean
-text text
-title text
-treemode mode
-validation text
-variables boolean
-width amount
-wrap mode
-wraplength amount
GRIDPLUS WIDGET OPTIONS
.name
:icon
%group
<
>
@name
?helptext
!name
|
+value
-value
*
~name
integer
text
GRIDPLUS GRID/LAYOUT
COMMANDS
gridplus add name ?option value(s) ...?
-group groupname
gridplus button name ?option value(s) ...? layout
-background color
-borderwidth width
-buttoncolor color/color
-buttonrelief style
-group groupname
-icon icon
-iconfile filename
-iconpath path
-pad amount
-padx amount
-pady amount
-prefix prefix
-proc boolean
-relief style
-size width
-space spacing
-state state
-style style
-subst boolean
-taborder order
-takefocus boolean
-title text
layout
gridplus checkbutton name ?option value(s) ...? layout
-background color
-borderwidth width
-group groupname
-pad amount
-padx amount
-pady amount
-relief style
-size width
-space spacing
-state state
-style style
-subst boolean
-taborder order
-takefocus boolean
-title text
layout
gridplus clear ?option value(s) ...? window
-variables boolean
window
gridplus entry name ?option value(s) ...? layout
-background color
-borderwidth width
-group groupname
-pad amount
-padx amount
-pady amount
-prefix prefix
-relief style
-size width
-space spacing
-state state
-style style
-taborder order
-takefocus boolean
-title text
layout
gridplus grid name ?option value(s) ...? layout
-background color
-borderwidth width
-icon icon
-iconfile filename
-iconpath path
-justify position
-pad amount
-padx amount
-pady amount
-prefix prefix
-relief style
-size width
-space spacing
-state state
-style style
-taborder order
-title text
-wraplength amount
layout
gridplus layout name ?option value(s) ...? layout
-background color
-borderwidth width
-pad amount
-padx amount
-pady amount
-relief style
-taborder order
-title text
-style style
-subst boolean
layout
gridplus line name ?option value(s) ...?
-background color
-borderwidth width
-linewidth width
-pad amount
-padx amount
-pady amount
-style style
-title text
gridplus link name ?option value(s) ...? layout
-background color
-borderwidth width
-foreground color
-icon icon
-iconfile filename
-iconpath path
-linkcolor color/color
-linkursor cursor
-linkstyle style/style
-pad amount
-padx amount
-pady amount
-prefix prefix
-proc boolean
-relief style
-space spacing
-state state
-style style
-subst boolean
-title text
layout
gridplus menu name ?option value(s) ...? layout
-prefix prefix
-proc boolean
-state state
-style style
layout
gridplus notebook name ?option value(s) ...? layout
-background color
-borderwidth amount
-buttoncolor color/color
-irelief style
-relief style
-style style
layout
gridplus radiobutton name ?option value(s) ...? layout
-background color
-borderwidth width
-group groupname
-pad amount
-padx amount
-pady amount
-relief style
-size width
-space spacing
-state state
-style style
-subst boolean
-taborder order
-takefocus boolean
-title text
layout
gridplus set ?option value(s) ...?
-century year
-dateformat dateformat
-errormessage text
-group groupname
-pattern pattern
-prefix prefix
-proc boolean
-state state
-text text
-validation name
gridplus style name options
gridplus tablelist name ?option value(s) ...? layout
-action type
-background color
-columnsort boolean
-group groupname
-height amount
-insertexpr expression
-insertoptions options
-options options
-prefix prefix
-proc boolean
-scroll scrollbars
-selectfirst boolean
-sortfirst boolean
-sortorder order
-state state
-style style
-width amount
layout
gridplus text name ?option value(s) ...?
-background color
-group groupname
-height amount
-iconfile filename
-iconpath path
-linkcolor color/color
-linkursor cursor
-linkstyle style/style
-proc boolean
-scroll scrollbars
-state state
-style style
-tags boolean
-takefocus boolean
-width amount
-wrap boolean
gridplus tree name ?option value(s) ...?
-action type
-background color
-fileicon icon
-foldericon icon
-height amount
-iconfile filename
-iconpath path
-proc boolean
-scroll scrollbars
-treemode boolean
-width amount
gridplus window name ?option value(s) ...?
-deletewindow command
-modal boolean
gpset item value
gpset {item value ...}
item name
value value
gpmap {item ...} {value ...}
item name
value value


NAME

gridplus::gridplus - Create/control GridPlus window layouts..


SYNOPSIS

package require gridplus ?1.2?

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:


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:

gridplus add name ?option value ...?
Adds a TK widget to a group.

gridplus button name ?option value ...? layout
Creates a GRIDPLUS button grid.

layout

Specifies the GRIDPLUS grid properties of buttons within the grid.

gridplus checkbutton name ?option value ...? layout
Creates a GRIDPLUS checkbutton grid.

layout

Specifies the GRIDPLUS grid properties of checkbuttons within the grid.

gridplus clear ?option value ...? window
Clears all widgets and GRIDPLUS widget references for the specified window.

gridplus entry name ?option value ...? layout
Creates a GRIDPLUS entry grid.

layout

Specifies the GRIDPLUS grid properties of entry fields within the grid.

gridplus grid name ?option value ...? layout
Creates a GRIDPLUS grid.

layout

Specifies the GRIDPLUS grid properties of items/widgets within the grid.

gridplus layout name ?option value ...? layout
Creates a GRIDPLUS layout.

layout

Specifies the GRIDPLUS layout properties of grids/layouts.

gridplus link name ?option value ...? layout
Creates a GRIDPLUS link grid.

layout

Specifies the GRIDPLUS grid properties of buttons within the grid.

gridplus menu name ?option value ...? layout
Creates a GRIDPLUS menu.

layout

Specifies the options.

gridplus notebook name ?option value ...? layout
Creates a GRIDPLUS notebook.

layout

Specifies the names of grids/layouts within the notebook.

gridplus radiobutton name ?option value ...? layout
Creates a GRIDPLUS radiobutton grid.

layout

Specifies the GRIDPLUS grid properties of radiobuttons within the grid.

gridplus style name options
Creates a GRIDPLUS Style.

gridplus tablelist name ?option value ...? layout
Creates a GRIDPLUS tablelist.

layout

Specifies the layout/options of columns within the tablelist.

gridplus text name ?option value ...?
Creates a GRIDPLUS text widget.

gridplus tree name ?option value ...?
Creates a GRIDPLUS tree widget.

gridplus window name ?option value ...?
Creates a toplevel window.


Copyright © 2005 Adrian Davis.