# mkWidgets 1.2 Manual

###### 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.2 - A method for writing metawidgets, and a collection of these.

General
Author
Aclock
Calendar
Combobox
Document
Gridcontrol
Ibutton
Iconbox
Listcontrol
Pane
Progressbar
Scrollbox
Spinentry
Statusbar
Tabcontrol
Textframe
Toolbar
Tooltip
Treecontrol
Window

## General

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.

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 the author's web site for more details.

## AUTHOR

Michael Kraus
mailto:mmg_kraus@compuserve.com
http://ourworld.compuserve.com/homepages/mmg_kraus

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

insert row-number ?valueList ...?
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 ?valueList ...?
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.

bind bind-args
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

### Default

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

### Options

?
?

### Commands

?
?

## Listcontrol

### Name

? - ?

### Description

The ? metawidget

### Default

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

### Options

?
?

### Commands

?
?

## Pane

### Name

? - ?

### Description

The ? metawidget

### Default

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

### Options

?
?

### Commands

?
?

## Progressbar

### Name

? - ?

### Description

The ? metawidget

### Default

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

### Options

?
?

### Commands

?
?

## Scrollbox

### Name

? - ?

### Description

The ? metawidget

### Default

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

### Options

?
?

### Commands

?
?

## Spinentry

### Name

? - ?

### Description

The ? metawidget

### Default

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

### Options

?
?

### Commands

?
?

## Statusbar

### Name

? - ?

### Description

The ? metawidget

### Default

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

### Options

?
?

### Commands

?
?

## Tabcontrol

### Name

? - ?

### Description

The ? metawidget

### Default

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

### Options

?
?

### Commands

?
?

## Textframe

### Name

? - ?

### Description

The ? metawidget

### Default

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

### Options

?
?

### Commands

?
?

## Toolbar

### Name

? - ?

### Description

The ? metawidget

### Default

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

### Options

?
?

### Commands

?
?

## Tooltip

### Name

? - ?

### Description

The ? metawidget

### Default

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

### Options

?
?

### Commands

?
?

## Treecontrol

### Name

? - ?

### Description

The ? metawidget

### Default

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

### Options

?
?

### Commands

?
?

## Window

### Name

? - ?

### Description

The ? metawidget

### Default

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

### Options

?
?

### Commands

?
?