mkWidgets 1.3 Manual, Part 2 of 2 mkWidgets 1.3 Manual, Part 2 of 2mkWidgets 1.3 - A method for writing metawidgets, and a collection of these. Part 2: My metawidget collection (Part 1)
Introduction
Aclock
Calendar
Combobox
Document
Gridcontrol
Ibutton
Iconbox
Listcontrol
Pane
Progressbar
Scrollbox
Spinentry
Statusbar
Tabcontrol
Textframe
Toolbar
Tooltip
Treecontrol
Window
Author
The following sections are the man pages for the metawidget collection that comes with the mkWidgets extension. The mkWidgets extension is primarily a method for defining metawidgets, i.e. compound widgets that consist of an arbitrary number of regular TK standard widgets. The included metawidget collection, however, should already cover most of the needs and wishes of GUI designers. It was a lot of work, after all ;)
Particularly worth to mention are the complex metawidgets gridcontrol, treecontrol, listcontrol and iconbox. They demonstrate nicely how powerful the standard text widget can actually be. Follow these links to screenshots for Windows and Linux.
Every metawidget understands the commands cget and configure. Also, in each metawidget there is exactly one standard widget that is called the default widget. All it means is that all options and commands not explicitely implemented as part of the metawidget definiton are redirected to it.
Consequently, a metawidget understands all options and commands that the default widget understands. E.g. if the default widget is a simple frame, then the metawidget will understand the -relief option, but not the -font option (unless the -font option is defined and implemented as part of the metawidget itself) . These default widget options and commands are not described here but can rather be found in the Tcl/Tk man pages.
In addition, it is also important to understand the limitations that apply to metawidgets as opposed to standard widgets. Please see Part 1 of this manual for details on these and for information about how metawidgets are built with the metawidget command.
aclock - An "analog clock" metawidget
The aclock metawidget resembles an analog clock, with an hour and a minute pointer. The pointers can be dragged with the mouse. The clock can also be set with two arrow buttons and a time entry field. A double-click on the gray area between the buttons and the time entry field sets the current time.
The default widget is of type canvas and displays the clock's graphical elements, such as the pointers. The metawidget accepts all commands and configuration options of this widget type.
-controls top|bottom
Specifies the location of the control elements of the clock. The control elements are
the two arrow buttons and the time entry field. They can be either above or below the
clock.
-format format-string
Accepts a format string like for the standard clock format command. The format
string controls the way the time is displayed in the entry field. Also, the get
widget command returns the time according to the format option.
-font font-spec
Accepts a font specification like for the standard -font option. This options
is applied to the time entry field.
set ?time-string?
Sets the time of the clock. If no time-string is given, the current time is taken. the
string must be in a format acceptable to the standard clock scan command.
get
Returns the time the clock is set to, in the format specified by the -format
option.
scroll minutes
Sets the clock's time forward or backward according to the specified minutes.
bind bind-arguments
Same as the standard bind command, except that it applies bindings to the
clock's time entry field.
calendar - A calendar metawidget
The calendar metawidget provides a calendar that allows for selection of a date by using the mouse or the keyboard. The user can scroll through the days and weeks by using the cursor keys, and through the month and years with two arrow buttons and the control key. A double-click on the date display field sets the current day.
The default widget is of type text and displays the calendar's days. The metawidget accepts all commands and configuration options of this widget type.
-controls top|bottom
Specifies the location of the control elements of the clock. The control elements are
the two arrow buttons and the date display field. They can be either above or below the
clock.
-font font-spec
Accepts a font specification like for the standard -font option. This options
is applied to the calendar interior and the date display field.
set ?date-string?
Sets the date of the calendar. If no date-string is given, the current date is taken. the
string must be in a format acceptable to the standard clock scan command.
get ?format-string?
Returns the date the calendar is set to, using an optional format string. The latter
defaults to %m/%d/%Y, if not specified. The format string must be
acceptable to the standard clock format command.
scroll integer ?days|months|years?
Sets the calendar's date forward or backward according to the specified integer value
and unit. The latter defaults to months, if not specified.
bind bind-arguments
Same as the standard bind command, except that it applies bindings to the
calendar's interior.
headerconfig option-value pairs
Applies all option-value pairs to the calendar's headline, showing the weekdays.
Accepts all options that can be applied to a text widget tag.
headercget option
Retrieves an option value of the calendar's headline, showing the weekdays.
Accepts all options that can be applied to a text widget tag.
combobox - An entry widget with a pull-down menu, a.k.a. "combobox"
The combobox metawidget is a combination of an entry widget and a listbox. One can enter any text into the entry widget but also select one of several predefined values from a pull-down list. This list appears whenever the user clicks on the button on the right side of the entry widget. In addition, the cursor keys can be used to scroll through the list whenever the focus is in the entry widget.
The default widget is of type entry. It is the entry field itself. The metawidget accepts all commands and configuration options of this widget type.
-lines integer
Specifies the number of lines to be displayed in the list.
-entries arg arg ...
Sets the values to be displayed in the list.
-state normal|disabled|restricted
Similar to the -state option of a regular entry widget.
In restricted mode, the combobox does only allow selection from the list.
-command command-string
Executes the specified command-string whenever a new value is picked
from the list.
see ?index?
Sets a particular value from the pull-down menu, specified by index.
If index is not provided, the index of the current value is returned.
If this value is not part of the list, -1 is returned instead.
document - A "multiple document interface"-like thing
On Windows, MDI is a popular concept for applications that can have
several documents open at a time (e.g. a word processor). Instead of each open
document being displayed in its own window on the desktop, the documents are
organized in "sub-windows" that can only be moved around within the application's
main window.
The document metawidget resembles this behavior. Other widgets can be
packed, placed or gridded inside a document window like in a toplevel window.
The document windows can be resized, minimized, maximized, moved around and, of course,
closed. The class function Arrange can be used to arrange all
document windows inside their parent window, which should be a frame.
The default widget is of type frame. The metawidget accepts all commands and configuration options of this widget type.
-title string
Sets the title to be displayed in the title bar.
-image image-name
Specifies an icon to be displayed in the document window's title bar.
-icontext string
Sets the title text to be used when the document window is iconfied.
-x|-y|-width|-height pixels
These four options control position and size of the document window within
its parent window.
-font font-spec
Sets the font for the document window's title bar.
-foreground|-background color
For the active window, controls the foreground and background color for the title bar.
-state normal|minimized|maximized|withdrawn
Transforms the document window into one of four possible states. The withdrawn
state means that the document window disappears but is not actually deleted.
-minsize {width height}
Controls the minimum width and height for a document window. The option argument must
be a proper tcl list with two integers.
menu options
Modifies the pull-down menu that pops up below the document window's icon, when clicked
on the icon. The options can be all option-value pairs that the standard
menu widget accepts. This command allows to add or disable entries to the menu.
lower|raise
The document window is lowered, i.e. put behind all other windows, or raised respectively,
i.e., made the topmost, active window.
pack|grid|place widget args
Allows for putting other widgets inside the document window. It is recommended to pack
a simple frame inside with -fill both -expand 1 and then put all other windows
inside this frame by means of the standard pack, grid and place commands.
Arrange horizontally|vertically|cascade|tile|icons|maximize|minimize
Arranges all document windows according to the given parameter. Arrange icons
will arrange the icons rather than the windows.
This is a class-function and hence has to be called in the format ::Document::Arrange mode
gridcontrol - A spreadsheed, or table widget.
The gridcontrol metawidget is a rather complex widget and can be used to display
data in rows and columns, hence in table format. Columns are addressed by name, rows by
number. Selection is supported in the regular way. Cells and cell ranges can be tagged
similar to text in a text widget. By configuring the tags, cells can change their color,
font etc. Columns can be resized with proper text clipping.
Some commands require to specify a cell or a cell range. This is done in the format
column-name.row-number. E.g. salary.4 specifies the cell in
the fourth row of the salary column. Wildcard are also allowed: lastname.*
specifies all cells of the column lastname, *.12 all cells of row 12.
Consequently, *.* identifies the entire table.
The entire widget is based on only three text widgets, regardless of the number of columns
specified.
The default widget is the widget's interior area and is of type text. The metawidget accepts all commands and configuration options of this widget type.
-font font-spec
Sets the font of the gridcontrol, including the column and row headers. The font for
individual cells or cell ranges can be controlled by means of the tag command.
(see below).
-update full|partial|none
Controls how a column is updated during a resize operation. none only resizes
the column header during dragging, partial resizes the column, too, but does
not perform clipping, full resizes and clips both the header and the column.
-selectmode single|multiple
Sets the select mode. If it is single, only one cell can be selected. In
multiple mode, cells and cell ranges can be selected by clicking on column
or row headers, or by using the shift and control key in combination with the mouse.
-onselect command-string
If command-string is not empty, then it is evaluated each time the selection changes.
column insert|delete|configure|cget|fit|bind|names|exists ?args?
This command handles all column related matters. Columns are identified by a unique name and
have several configuration options.
column insert column-name position ?options? inserts a new column
at the specified position (a non-negative integer, or "end"). In addition, configuration options
can be passed. column delete column-name deletes the specified column.
column configure column-name ?options? configures a column. There are three
special options: -width pixels specifies the column's width.
-align left|right|center|numeric controls the alignment of text inside the column.
-text string specifies the column heading. Otherwise, all options are accepted
that a text widget tag would accept. column cget column-name option returns
the value of the given option.
column fit column-name resizes a column so that all values of that columns can
be displayed without being clipped.
column bind column-name ?bind-args? accepts arguments like the bind
command. They are passed directly to the column header.
Finally, column names returns a list of all currently defined columns, and
column exists column-name returns 1 if a column exists, 0 otherwise.
insert row-number ?value-list ...?
Inserts one or more rows, starting at the specified row number, and fill them up with
values. Each valueList must contain the values for an entire row and hence
have the same number of elements as columns specified. Row-number can be the string "end".
delete from-row ?to-row?
Deletes a row or a range of rows. The string "end" can be used to denote the last row.
set cell-spec ?value-list ...?
Sets values inside the grid. cell-spec specifies a cell that represents the top left
corner of the cell range whos values are to be replaced. E.g. set Salary.5 80000 sets the
value in the Salary column in row 5 to 80000. set Monday.3 {71 75 79} {58 65 61} sets a
rectangular area of 3 columns by 2 rows. The top left cell is Monday.3 and is set to 71. Assumed
there is a column for every weekday, then Wednesday.4 is set to 61.
get ?cell-spec1? ?cell-spec2?
Returns the values of a cell or a range of cells. cell-spec1 specifies the
top left corner, cell-spec2 the bottom right corner of a rectangular-shaped
grid area. The values of that area are returned as a list, where each element represents
a row and is itself a list with the values of that row. If neither cell-spec is
specified, the entire grid contents is returned. In the above example,
get Tuesday.3 Wednesday.4 returns {{75 79} {65 61}}.
tag add|delete|remove|cget|configure|lower|raise|ranges|names|bind ?args?
This command allows to apply and control tags for cells and cell ranges. This is very
similar to the way tags are used in the original text widget. Cells can have one
or more tags, which are identified by a name. Each tag can be configured, e.g. with a
certain background color, which in turn would apply this color to all cells that have this
particular tag.
tag add tag-name cell-spec1 ?cell-spec2? adds the tag specified by tag-name to
the cell (range) specified by cell-spec1 (and cell-spec2).
tag remove tag-name cell-spec1 ?cell-spec2? removes a previously added tag
from a cell or a cell range.
tag names cell-spec returns all tags attached to a single cell. If a cell
range is specified, the first cell is taken.
tag ranges tag-name returns all cells that have the specified tag currently
attached.
All other tag commands work exactly like the tag commands for the text widget.
In particular, the selection can be set by using the special tag "sel".
bind bind-arguments
Applies bind arguments directly to the spreadsheet. The column and row headers do not
accept bindings.
see cell-spec
Makes a particular cell visible, if it out of sight.
rows
Returns the total number of rows.
ibutton - A button with an image
The ibutton metawidget is just like a regular button, except it can have an image inside it.
The default widget is a regular button. The metawidget accepts all commands and configuration options of this widget type.
-image image-name
Specifies the image to be displayed.
(none)
iconbox - A container widget for icons
The iconbox metawidget acts as a container for icons. An icon consists of an image and a label and usually represent some object (e.g. a file). Hence, attributes can also be displayed for each icon. There are three different views available: Large icons, small icons, and list view. Only the latter one would display the attributes. Bindings for the icons allow for callback scripts on events.
The default widget is the inner area of the iconbox and is of type text. The metawidget accepts all commands and configuration options of this widget type.
-font font-spec
Sets the font that is used for the label of the icons.
-update full|partial|none
When in list view, controls how a column is updated during a resize operation.
none only resizes the column header during dragging, partial resizes
the column, too, but does not perform clipping, full resizes and clips both
the header and the column while dragging.
-selectmode single|multiple
Sets the select mode. If it is single, only one icon can be selected. In
multiple mode, more than one icon can be selected
by using the shift and control key in combination with the mouse.
-onselect command-string
If command-string is not empty, then it is evaluated each time the selection changes.
-view large|small|list
Sets the display mode for the iconbox: Large icons, small icons, and list view.
For list view, a column header row appears and the icon attributes are displayed.
-columns column-spec-list
Specifies how to display icon attributes when the iconbox is in list view. Each
column specification in the list must itself be a proper list containing up to
4 elements: Caption, alignment, width and minimal width. The caption
is mandatory, the others are optional. An alignmentis specified by one of l (left),
r (right), c (center) or n (numeric). Width and minimal is be specified in pixels.
insert position icon-name ?options?
Inserts a new icon at the specified position (an integer, or "end"). Icons are
referenced by their name, which must be unique for the iconbox. The icon is
configured with optional option-value pairs (see iconconfigure below).
delete ?icon-name ...?
Deletes one or more icons from the iconbox. If no icon names are given, then all
icons are deleted.
iconconfigure icon-name option value ?option value ...?
Configures an icon. Icon specific options are
-text string: The label to be used for the icon
-image image-name: The image to be used when in "large icons" view
-smallimage image-name: The image to be used when in "small icons" and list view
-values list: The attributes to be displayed when in list view
-user user-data: Arbitrary user data. Just stored with the icon but never used
All other options are applied to the icon's label (-font, -bg etc.).
iconcget icon-name option
Returns an option value. For accepted options, see above.
iconbind icon-name bind-arguments
Defines a binding script for an icon. See the generic bind man page for
more information. This is used primarily for mouse events, e.g. double-clicks,
whereas key events are defined using the bind metawidget command (an
icon cannot have the focus, since it consists of just two labels. Therefore it
does not generate key events).
selection clear|get|set ?icon-names-list?
Controls the selection. clear clears the selection, set icon-names-list
sets the selections for the specified icons, get returns a list of all icons
that are currently selected.
sort ?-column column-caption? ?lsort-options?
Sorts the icons, either by their label or by a particular column, specified by its
caption as set with the -columns option. In addition, the options accepted
by the lsort command can be used.
see icon-name
Makes an icon visible if it is out of sight.
bind bind-arguments
Same as the standard bind command, except that it applies bindings to the
iconbox (a text widget).
size
Returns the number of icons in the iconbox.
names
Returns a list with the names of all icons in the iconbox.
listcontrol - An enhanced listbox type widget
The listcontrol metawidget is a multicolumn listbox. Columns can be resized
by dragging them. An icon can be placed into each column for each row individually.
Cells or cell ranges can be tagged similar like with the gridcontrol widget.
By configuring the tags, cells can change their color, font etc. A cell is specified with
column-name.row-number. E.g. salary.4 specifies the cell in
the fourth row of the salary column. Wildcard are also allowed: lastname.*
specifies all cells of the column lastname, *.12 all cells of row 12.
Consequently, *.* identifies the entire listcontrol.
The entire widget is based on only two text widgets, regardless of the number of columns
specified.
The default widget is the widget's interior area and is of type text. The metawidget accepts all commands and configuration options of this widget type.
-font font-spec
Sets the font of the listcontrol, including the column headers. The font for
individual rows can be controlled by means of the tag command.
(see below).
-update full|partial|none
Controls how a column is updated during a resize operation. none only resizes
the column header during dragging, partial resizes the column, too, but does
not perform clipping, full resizes and clips both the header and the column.
-selectmode single|multiple
Sets the select mode. If it is single, only one row can be selected. In
multiple mode, several rows can be selected
by using the shift and control key in combination with the mouse.
-onselect command-string
If command-string is not empty, then it is evaluated each time the selection changes.
column insert|delete|configure|cget|fit|bind|names|exists ?args?
This command handles all column related matters. Columns are identified by a unique name and
have several configuration options.
column insert column-name position ?options? inserts a new column
at the specified position (a non-negative integer, or "end"). In addition, configuration options
can be passed. column delete column-name deletes the specified column.
column configure column-name ?options? configures a column. There are four
special options: -width pixels specifies the column's width.
-align left|right|center|numeric controls the alignment of text inside the column.
-text string specifies the column heading. -minsize pixels
specifies the column's minimal width. Otherwise, all options are accepted
that a text widget tag would accept. column cget column-name option returns
the value of the given option.
column fit column-name resizes a column so that all values of that columns can
be displayed without being clipped.
column bind column-name ?bind-args? accepts arguments like the bind
command. They are passed directly to the column header.
Finally, column names returns a list of all currently defined columns, and
column exists column-name returns 1 if a column exists, 0 otherwise.
insert row-number ?value-list ...?
Inserts one or more rows, starting at the specified row number, and fill them up with
values. Each valueList must contain the values for an entire row and hence
have the same number of elements as columns specified. Row-number can be the string "end".
delete from-row ?to-row?
Deletes a row or a range of rows. The string "end" can be used to denote the last row.
set ?-columns column-list? start-row ?value-list ...?
Sets new values for one or more rows. If the -columns option is specified, only
the values for certain columns will be set. Columns are addressed by their caption
as specified with the column property -text.
get ?-columns column-list? first-row ?last-row?
Returns the values of a row or a range of rows. If the -columns option is specified,
only the values for the given columns are returned.
tag add|delete|remove|cget|configure|lower|raise|ranges|names|bind ?args?
This command allows to apply and control tags. This is very
similar to the way tags are used in the original text widget. Cells can have one
or more tags, which are identified by a name. Each tag can be configured, e.g. with a
certain background color, which in turn would apply this color to all cells that have this
particular tag.
tag add tag-name cell-spec1 ?cell-spec2? adds the tag specified by tag-name to
the cell (range) specified by cell-spec1 (and cell-spec2).
tag remove tag-name cell-spec1 ?cell-spec2? removes a previously added tag
from a cell or a cell range.
tag names cell-spec returns all tags attached to a single cell. If a cell
range is specified, the first cell is taken.
tag ranges tag-name returns all cells that have the specified tag currently
attached.
All other tag commands work exactly like the tag commands for the text widget.
selection clear|get|set ?row-range ...?
Controls the selection. clear clears the selection, set row-range ?...?
sets the selection for the specified row or range of rows,
get returns a list of all rows that are currently selected.
image create|delete|configure|cget|names ?cell-spec? ?image-options?
Allows to attach an image to a particular cell or cell range. The image options must
be those as accepted by the image command of the text widget.
bind bind-arguments
Applies bind arguments directly to the listcontrol. The column headers do not
accept bindings.
see row
Makes a particular cell visible, if it out of sight.
size
Returns the total number of rows.
pane - A pane widget
The pane metawidget is a container for two user-defined widgets. Between these two widgets is a thin frame that can be dragged and hereby resizes the two user widgets.
The default widget is the draggable frame. The metawidget accepts all commands and configuration options of this widget type.
-orientation vertical|horizontal
Determines if the pane shall separate the two user widgets horizontally or vertically.
-width pixels
Sets the width of the draggable frame.
-resize both|first|second
Controls how the two user widgets are being resized when the pane widget itself is
resized. both resizes the widgets proportionally, first resizes
only the left (top) widget, and second resizes only the
right (top) widget.
-update boolean
Defines if the two user widgets shall be redrawn during dragging. If not, they
will be redrawn only after the mouse button is released.
set position ?both|first|second?
Sets the pane to a new position. If both (the default) is specified,
position is taken as a percentage value (e.g. set 50 would center the pane).
Otherwise as a pixel value (e.g. set 50 first makes the left (top) widget 50 pixels
wide (tall)).
get ?both|first|second?
The counterpart of set. Returns the position of the pane, either in percent
or in pixels.
place|pack|grid first|second window-name ?args?
Places, packgs or grids a window either into the first (left, top) or second (right, bottom) part of the
container widget.
progressbar - A simple "analog" progress bar
The progressbar metawidget allows to visualize the progress of some process, e.g. the loading of a file or processing of data.
The default widget is the area behind the progress bar and is of type frame. The metawidget accepts all commands and configuration options of this widget type.
-background color
Sets the color of the progress bar.
-foreground color
Sets the color of the text display.
-font font-spec
Sets the font of the text display.
-format format-string
Defines the format to be used for the text display.
set value ?base-value?
Sets the progress bar. If no base value is given, value is interpreted as
a percent value (0-100). The base value determines the maximum value to be used for
value. For value==base-value, the progress bar is fully displayed.
scrollbox - A standard listbox with automatic scrollbars
The scrollbox metawidget is identical to a regular listbox, except it has a vertical and a horizonal scrollbar attached that pop up only when they are needed. That is, they are not displayed, when all lines of the listbox can be displayed in full, and no information is outside the viewable area. In addition, a few "luxury commands" have been implemented. They allow to address entries in the listbox by their name (i.e. the text that is displayed) rather than their index.
The default widget is the listbox. The metawidget accepts all commands and configuration options of this widget type.
-scrollbar auto|on|off
Controls if the scrollbars should be displayed automatically when needed, or if
they should always be on respectively off.
find entry ?entry ...?
A list is returned containing the indexes (position) of those entries that could be found in the listbox.
selection setbyval|get|standard-options ?args?
Extents the standard listbox selection command by two functions: setbyval sets the selection
for all entries (not indexes) in args. get returns a list of all currently selected
entries (not indexes).
set entry ?entry ...?
Deletes all existing entries and inserts new ones.
remove entry ?entry ...?
Removes particular entries from the list.
sort standard-lsort-args
Sorts the entries. The arguments must be those accepted by the lsort command.
spinentry - An entry field with up and down arrows
The spinentry metawidget is almost identical to a standard entry widget, except it has two arrow buttons on the right side. Pressing these buttons or using the up and down cursor keys increments or decrements a numeric value inside the entry widget.
The default widget is the entry widget. The metawidget accepts all commands and configuration options of this widget type.
-step value
Sets the step width to be used for increments and decrements.
-speed milliseconds
Sets the scrolling speed to be used when the mouse is held down on the arrow buttons.
-minimum|-maximum value
Defines a minimum and maximum value for the entry widget.
-onerror cmd
Defines a script to be called when the value in the entry widget cannot be incremented
respectively decremented. If cmd is an empty string, then errors will not be caught.
-value value
Sets the value inside the entry widget. Also checks if the value is of numeric type.
If not, an error is returned.
(none)
statusbar - A flexible status bar at the bottom of a window
The statusbar metawidget sticks to the bottom of a window and displays some text (normally some helpful status information). In addition, it may show a "digital" progress bar and an arbitrary number of additional fields, which may contain an icon and text.
The default widget is the label that displays the status text. The metawidget accepts all commands and configuration options of this widget type.
-ticks number
Displays a progress bar at the right side of the status bar, with the specified number of "lights"
(i.e., gray rectangles). To show a certain progress value, use the option -progress.
-progress value
Visualizes a certain progress in the progress bar. The value must be between 0 and 1. 1 would
switch on all "lights" in the progress bar, 0.5 only the left half of them, 0 none.
-state normal|withdrawn
Shows or hides the status bar. The status bar is always drawn inside its parent window.
-text string
Sets a text in the status bar. The text can be overloaded with the push command
and be recovered without redefinition with the pop command.
push string
Overloads the currently displayed text with a new text. The metawidget maintains a stack
of all overloaded texts, so they can be recovered in the opposite order.
pop
Removes the text defined with the last push command and displays the text that
is "underneath" it.
add field-name ?args?
Installs a new field, which can display an icon and text. The field name must be unique for
the status bar. Any additional arguments are passed to itemconf.
delete field-name ?field-name ...?
Removes fields from the status bar.
itemconf field-name option value ?option value ...?
Configures a field. Each field consists of a frame, an image and a text label. Consequently,
all options are accepted that these three widget types would accept. The metawidget will
apply them to the appropriate inner widget(s).
itemcget field-name option
Returns the value of a particular option of a field.
tabcontrol - A multi-row tab widget
The tabcontrol metawidget is a container widget that contains a row of tabs at the top. Depending on what tab is activated, the widget will show a different content. Usually, this is used for modal dialogs.
The default widget is the outer frame of the container. The metawidget accepts all commands and configuration options of this widget type.
-width auto|pixels|percent%
Controls the width of the tab row. For auto the tabs will have the individual
size required to display the tab label. If a percentage value is specified, the tabs
will cover that percent of the entire widget's width. If a plain pixel value is specified,
the tabs will be drawn to cover exactly that amount of pixels.
insert tab-name row ?args?
Creates a new tab. Tabs are identified by a tab-name which must be unique for the metawidget.
Tabs are filled into the specified row from the left to the right. Any additional arguments
are passed to tabconfigure.
delete tab-name
Deletes the specified tab.
tabconfigure tab-name option value ?option value ...?
Configures a tab. Each tab is actually a label, therefore all label options are accepted.
In addition there are two special options: -window specifies the user widget to
be displayed when the tab is active. -command specifies a script to be evaluated
each time the tab is activated.
tabcget tab-name option
Returns an option value for a tab.
invoke
Activates a tab and shows its associated user widget.
get ?active|row?
If no arguments is specified, returns all tab names. If active is specified,
returns the active tab. If a valid row number is specified, returns the tabs in this row.
bind tab-name bind-arguments
Applies bind arguments directly to a tab.
textframe - A frame with a title text
The textframe metawidget is a regular frame widget with a title text
The default widget is the frame itself. The metawidget accepts all commands and configuration options of this widget type.
-anchor n|s|w|e|c
Specifies the anchor position of the title text relative to the frame.
-offset value
Sets an offset value for the title text. There are three different formats:
E.g. 20% sets the label 20% of the frame's width off from the left.
20 sets the label 20 pixel from the left border (good with -anchor w).
end-20 sets it from the frame's right border (good with -anchor e).
-font font-spec
Sets the font for the title text.
-text string
Sets the title text.
pack|place|grid window ?args?
Packs, places or grids user widgets inside the textframe widget.
toolbar - A container widget for tool buttons
Toolbars are popular elements in graphical applications. Toolbars contain a number of icons that represent entries from the application's menu. Hence, they are like shortcuts to certain application functions. The icons often behave like regular buttons, but can also act like checkbuttons and radiobuttons. The toolbar metawidget resembles such a complex widget. Buttons, checkbuttons and radiobuttons can be defined, groups of buttons can be separated by a separator line, and the entire toolbar can be dragged to the four sides of its parent window.
The default widget is the outer frame that contains the tool buttons. The metawidget accepts all commands and configuration options of this widget type.
-side top|bottom|left|right
Attaches the toolbar to one of the four sides of its parent widget.
-state normal|fixed|withdrawn
Controls whether the toolbar shall be hidden or visible. For -state fixed the toolbar
cannot be dragged.
add button|checkbutton|radiobutton|separator name ?args?
Adds a new item to the toolbar. Items are identifed by a name that must be unique for the
toolbar. Additional arguments are expected to be option-value pairs and are passed on to itemconf.
For the radiobutton type, there is one special option -group group-name, which
identifies to which radiobutton group the item shall belong.
delete name ?name ...?
Deletes items from the toolbar.
itemconf name option value ?option value ...?
Configures an item. Accepts all options that a button widget would accept. In particular, -image
to set an icon and -command to define an action are important here.
itemcget name option
Returns an option value of the specified item.
invoke name ?new-state?
Invokes a tool button. Same as if it was pressed. If the item is of type checkbutton, then new-state,
a boolean, may define the new state of the checkbutton. This argument does not apply to button and radiobutton
item types.
set name ?new-state?
Same as invoke except that the item's associated command is not called. This is used e.g. when the
function that the tool button represents has been called from somewhere else (e.g. from the menu) and now
the tool button needs to be updated only.
get name
Returns the state of a tool button as boolean. For regular buttons, always returns 0.
names ?pattern?
Returns a list with the names of all tool buttons. If a glob-style pattern is given, only those names
are returned that match the pattern.
tooltip - Pop-up information when moving over a widget
The tooltip metawidget provides a feature that is standard of nowadays user interfaces: Whenever the user hovers over an element, such as an icon, a often yellowish little text window pops up after a second or so that explains the meaning of that button. The text disappers when the mouse leaves the area of the button.
The default widget is of type label. It is the tooltip window itself. The metawidget accepts all commands and configuration options of this widget type.
-delay milliseconds
Time to expire before the tooltip shall pop up after the user entered a widget's area.
add widget-name string
Activates the tooltip feature for a particular user-defined widget and defines the text to be displayed.
The text can be changed by calling this command again without having to call forget before.
forget widget-name
Removes the tooltip feature for a particular widget.
treecontrol - A fairly nice tree widget
The treecontrol metawidget allows to built an Explorer-style tree with an arbitrary number
of nodes. A node consists of a +/- icon (to expand and collapse them), a user-defined icon and a label.
Selection behaves as expected, including the use of the Shift and Control keys. Navigation through
the tree is done via mouse or keyboard. A double-click on the +/- icon expands or collapses a node,
and so do the cursor keys for left and right. If, in addition, the Shift key is pressed then all
subnodes are expanded respectively collapsed as well.
Callbacks are defined via node bindings. A particular useful feature is that the tree does not have
to be completely defined before being able to use it. Instead, it is sufficient to define the toplevel
nodes only, and then let the tree widget ask for a node's children whenever one of the toplevel nodes
is expanded. This is done via a special callback.
The entire tree widget is built from a single text widget. My highest respect for its developer!
The default widget is the tree widget itself and is of type text. The metawidget accepts all commands and configuration options of this widget type.
-text string
Every tree has one root node that is always at the top of the widget. This option
sets the label of the root node.
-image image-name
Sets the image to be used for the root node.
-fullexpand boolean
Controls whether automatic expanding of all subnodes of a node shall be allowed, when the Shift key
was pressed by the user. This feature may be not desired e.g. if the tree represents a file system and the
user is in a high level directory, e.g. / or c:\. Expansion might virtually take forever.
-selectmode single|multiple
Controls whether only one or more than one node can be selected at a time.
-onexpand command
The command specified herein is evaluated whenever a node is being expanded and the children of that
node are not known yet, or the node is not defined as "final" (see nodeconfigure below).
The to-be-expanded node is appended to the command as an argument, and the command is expected to
add all children to the tree by means of the insert command. If command is an
empty string, no callback will be made.
-onselect command
If the command is not an empty string, it is evaluated each time the selection changes.
insert node ?args?
Inserts a new node to the tree. Nodes are referenced by a name that must be unique over the
entire tree. Additional arguments are expected to be option-value pairs and are passed on
to the nodeconfigure commmand (see below).
delete ?node?
Deletes a particular node and all its children, or the entire tree, if no name is specified.
nodeconfigure node option value ?option value ...?
Configures a node. Allowed options are:
-parent node: Sets a new parent node. The node will be drawn as a child of
that parent node. The tree's root node is represented by an empty string.
-text string: Sets the nodes label.
-image image-name: Sets an icon for the node. If the image name is an empty
string, removes the icon.
-final boolean: Tells the tree wigdet that the given node is complete, i.e.
all of its children are defined. The tree widget will not call the -onexpand command
any more when this node gets expanded.
-user string: Arbitrary user data. Just stored with the node but never used.
nodecget node option
Returns the value of a node option. Besides from the options described under nodeconfigure,
the following options are accepted:
-children returns a list of all child nodes.
-indention returns the current indention level of the node.
-expanded returns a boolean indicating if the node is currently expanded.
-tags returns a list of all tags currently associated with the node (see below).
-visible returns a boolean indicating if the node is visible, i.e. all of its parents
are expanded. (The node can still be not on the screen because the tree's viewport is somewhere else.)
nodebind node ?bind-arguments?
Creates bindings for a particular node. This allows to define different actions for different node types.
E.g. in a filesystem tree, double-clicking a directory normally expands it, while double-clicking a file
displays it.
expand node ?recursive-flag?
Expands a node and, if the optional flag is true, all of its subnodes.
collapse node ?recursive-flag?
Collapses a node and, if the optional flag is true, all of its subnodes.
move node ?-byname? ?-after? position
Moves a node to a specified position within its siblings. If -byname is specified, position
must be the name of a sibling node (or any other node, in which case the node specified by node gets
reparented). The node will be placed before the sibling node, unless -after is specified.
tag add|delete|remove|cget|configure|lower|raise|names|nodes|bind ?args?
This command allows to apply and control tags for nodes in the tree. This is very
similar to the way tags are used in the original text widget. Nodes can have one
or more tags, which are identified by a name. Each tag can be configured, e.g. with a
certain background color, which in turn would apply this color to all nodes that have this
particular tag.
tag add tag-name node ?node ...? adds the tag specified by tag-name to one or more nodes.
tag remove tag-name node ?node ...? removes a previously added tag from one or more nodes.
tag names node returns all tags attached to a node.
tag nodes tag-name returns all nodes that currently have the specified tag.
All other tag commands work exactly like the tag commands for the text widget.
selection clear|get|set ?node-names-list?
Controls the selection. clear clears the selection, set node-names-list
sets the selections for the specified nodes, get returns a list of all nodes
that are currently selected.
get from-row ?to-row?
Returns a list of nodes that are between the two specified rows. The returned list depends on which
nodes are expanded and which ones are collapsed, i.e., nodes that are not visible because their parent is
collapsed, are not part of the list.
see node
Makes a node visible on the screen. If any of the node's parents are collapsed, then they are expanded first, so that
the node is drawn into the widget. Then the viewport is set, so that the node appears on the screen.
bind bind-arguments
Applies bindings directly to the tree widget.
nodes
Returns an unordered list of all nodes, whether visible or not.
tree node
Returns the structure of the subtree starting at the specified node as a recursive list.
Each list element is itself a list with two elements: the node's unique name and its child nodes.
window - A wrapper around the toplevel widget and the wm command
The window metawidget's purpose is to unify the window widget and the wm command. It is in so far not a true metawidget, but it makes the handling of toplevel widgets easier.
The default widget is a toplevel widget. The metawidget accepts all commands and configuration options of this widget type.
-geometry geometry-string
Sets position and size of the window. The geometry string must have the same format
as described under "wm geometry".
-minsize|-maxsize list
Sets the minimum and maximum size of the window. The list must contain the width and height to be set.
-resizable list
Specifies if the window can be resized in x and/or y direction. The list must contain two booleans
for the x and y direction.
-override boolean
Controls if the window is ignored by the window manager.
-ondelete command
Specifies a command to run whenever the window manager wants to close the window. The command
must eventually destroy the window itself.
-title string
Sets the window title.
-state normal|iconic|withdrawn
Sets the window's state: Normal, iconified, or hidden.
resize width height
Sets the size of the window.
move x y
Moves the window to a new position.
protocol wm-protocol-args
All arguments are directly passed to wm protocol.
Michael Kraus
mailto:michael@kraus5.de
http://mkextensions.sourceforge.net
