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
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.
Michael Kraus
mailto:mmg_kraus@compuserve.com
http://ourworld.compuserve.com/homepages/mmg_kraus
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 ?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 - 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
The default widget is of type canvas and displays The metawidget accepts all commands and configuration options of this widget type.
?
?
?
?
? - ?
The ? metawidget
The default widget is of type canvas and displays The metawidget accepts all commands and configuration options of this widget type.
?
?
?
?
? - ?
The ? metawidget
The default widget is of type canvas and displays The metawidget accepts all commands and configuration options of this widget type.
?
?
?
?
? - ?
The ? metawidget
The default widget is of type canvas and displays The metawidget accepts all commands and configuration options of this widget type.
?
?
?
?
? - ?
The ? metawidget
The default widget is of type canvas and displays The metawidget accepts all commands and configuration options of this widget type.
?
?
?
?
? - ?
The ? metawidget
The default widget is of type canvas and displays The metawidget accepts all commands and configuration options of this widget type.
?
?
?
?
? - ?
The ? metawidget
The default widget is of type canvas and displays The metawidget accepts all commands and configuration options of this widget type.
?
?
?
?
? - ?
The ? metawidget
The default widget is of type canvas and displays The metawidget accepts all commands and configuration options of this widget type.
?
?
?
?
? - ?
The ? metawidget
The default widget is of type canvas and displays The metawidget accepts all commands and configuration options of this widget type.
?
?
?
?
? - ?
The ? metawidget
The default widget is of type canvas and displays The metawidget accepts all commands and configuration options of this widget type.
?
?
?
?
? - ?
The ? metawidget
The default widget is of type canvas and displays The metawidget accepts all commands and configuration options of this widget type.
?
?
?
?
? - ?
The ? metawidget
The default widget is of type canvas and displays The metawidget accepts all commands and configuration options of this widget type.
?
?
?
?
? - ?
The ? metawidget
The default widget is of type canvas and displays The metawidget accepts all commands and configuration options of this widget type.
?
?
?
?