mkWidgets Manual, Part 2 of 2
Author: Michael Kraus
Description: Tcl/Tk mkWidgets collection
Keywords: Tcl, Tk, Tcl/Tk, Scriptics, Scripting, Programming, Extension, Package, mkWidgets

# mkWidgets 1.3 Manual, Part 2 of 2

###### Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted. The author makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. By use of this software the user agrees to indemnify and hold harmless the author from any claims or liability for loss arising out of such use.

## CONTENTS

mkWidgets 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

## INTRODUCTION

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

### Name

aclock - An "analog clock" metawidget

### Description

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.

### Default

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.

### Options

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

### Commands

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

### Name

calendar - A calendar metawidget

### Description

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.

### Default

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.

### Options

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

### Commands

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

### Name

combobox - An entry widget with a pull-down menu, a.k.a. "combobox"

### Description

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.

### Default

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.

### Options

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

### Commands

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

### Name

document - A "multiple document interface"-like thing

### Description

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.

### Default

The default widget is of type frame. The metawidget accepts all commands and configuration options of this widget type.

### Options

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

### Commands

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

### Name

gridcontrol - A spreadsheed, or table widget.

### Description

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.

### Default

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.

### Options

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

### Commands

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

### Name

ibutton - A button with an image

### Description

The ibutton metawidget is just like a regular button, except it can have an image inside it.

### Default

The default widget is a regular button. The metawidget accepts all commands and configuration options of this widget type.

### Options

-image image-name
Specifies the image to be displayed.

### Commands

(none)

## Iconbox

### Name

iconbox - A container widget for icons

### Description

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.

### Default

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.

### Options

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

### Commands

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

### Name

listcontrol - An enhanced listbox type widget

### Description

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.

### Default

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.

### Options

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

### Commands

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

### Name

pane - A pane widget

### Description

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.

### Default

The default widget is the draggable frame. The metawidget accepts all commands and configuration options of this widget type.

### Options

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

### Commands

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

### Name

progressbar - A simple "analog" progress bar

### Description

The progressbar metawidget allows to visualize the progress of some process, e.g. the loading of a file or processing of data.

### Default

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.

### Options

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

### Commands

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

### Name

scrollbox - A standard listbox with automatic scrollbars

### Description

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.

### Default

The default widget is the listbox. The metawidget accepts all commands and configuration options of this widget type.

### Options

-scrollbar auto|on|off
Controls if the scrollbars should be displayed automatically when needed, or if they should always be on respectively off.

### Commands

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

### Name

spinentry - An entry field with up and down arrows

### Description

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.

### Default

The default widget is the entry widget. The metawidget accepts all commands and configuration options of this widget type.

### Options

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

### Commands

(none)

## Statusbar

### Name

statusbar - A flexible status bar at the bottom of a window

### Description

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.

### Default

The default widget is the label that displays the status text. The metawidget accepts all commands and configuration options of this widget type.

### Options

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

### Commands

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

### Name

tabcontrol - A multi-row tab widget

### Description

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.

### Default

The default widget is the outer frame of the container. The metawidget accepts all commands and configuration options of this widget type.

### Options

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

### Commands

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

### Name

textframe - A frame with a title text

### Description

The textframe metawidget is a regular frame widget with a title text

### Default

The default widget is the frame itself. The metawidget accepts all commands and configuration options of this widget type.

### Options

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

### Commands

pack|place|grid window ?args?
Packs, places or grids user widgets inside the textframe widget.

## Toolbar

### Name

toolbar - A container widget for tool buttons

### Description

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.

### Default

The default widget is the outer frame that contains the tool buttons. The metawidget accepts all commands and configuration options of this widget type.

### Options

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

### Commands

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

### Name

tooltip - Pop-up information when moving over a widget

### Description

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.

### Default

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.

### Options

-delay milliseconds
Time to expire before the tooltip shall pop up after the user entered a widget's area.

### Commands

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

### Name

treecontrol - A fairly nice tree widget

### Description

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!

### Default

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.

### Options

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

### Commands

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

### Name

window - A wrapper around the toplevel widget and the wm command

### Description

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.

### Default

The default widget is a toplevel widget. The metawidget accepts all commands and configuration options of this widget type.

### Options

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

### Commands

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.

## AUTHOR

Michael Kraus
mailto:michael@kraus5.de
http://mkextensions.sourceforge.net