source: tol/tolbase/lib/mkWidgets1.3/mkWidgetsCol13.htm

devel
Last change on this file was 32535cc, checked in by Jorge Pérez <josp.jorge@…>, 18 years ago

adding more types to config, added mkWidget1.3

git-svn-id: ​https://www.tol-project.org/svn/tolp/trunk@16 be4846ae-f051-483a-831f-b64e7d08527f

  • Property mode set to 100644
File size: 62.4 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
2<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
3
4<head>
5  <title>mkWidgets Manual, Part 2 of 2</title>
6  <meta http-equiv="Content-Type" content="text/html"/>
7  <meta name="DESCRIPTION" content="Tcl/Tk mkWidgets collection"/>
8  <meta name="AUTHOR"      content="Michael Kraus"/>
9  <meta name="KEYWORDS"    content="Tcl, Tk, Tcl/Tk, Scriptics, Scripting, Programming, Extension, Package, mkWidgets"/>
10  <style type="text/css"><!--
11    body { font-family: Lucida Sans Unicode, Arial, Helvetica }
12    p    { font-family: Arial, Helvetica; font-size: .8em; margin: 1em }
13    h1   { font-size: 1.2em; font-weight: normal; color: #000000; background: #FFFF40; padding: 0.4em }
14    h2   { font-size: 1.0em; font-weight: normal; color: #000080; background: #DDDDDD; padding: 0.1em }
15    h3   { font-size: 0.8em; font-weight: normal; color: #000080 }
16    h6   { font-size: 0.7em; font-weight: normal; margin: 1em }
17    em   { font-size: 1em; font-weight: normal; font-style: normal; color: #AA0000 }
18    pre  { color: blue; margin: 1em 1em 1em 1em }
19    ul   { font-family: Arial, Helvetica; font-size: .8em; margin: 1em 1em 1em 3em }
20    a    { text-decoration: none }
21    img  { float: right; clear: right; margin: .5em }
22  --></style>
23</head>
24
25<body>
26  <h1><img src="images/TclLogo.gif" alt=""/>&nbsp;mkWidgets 1.3 Manual, Part 2 of 2</h1>
27  <h6>Permission to use, copy, modify, and distribute this software and its documentation
28  for any purpose and without fee is hereby granted. The author makes no representations
29  about the suitability of this software for any purpose.  It is provided "as is" without
30  express or implied warranty.  By use of this software the user agrees to indemnify and
31  hold harmless the author from any claims or liability for loss arising out of such use.<br/>&nbsp;</h6>
32
33  <h2>&nbsp;CONTENTS</h2>
34  <p>
35    mkWidgets 1.3 - A method for writing metawidgets, and a collection of these.
36    Part 2: My metawidget collection (<a href="mkWidgets13.htm">Part 1</a>)
37  </p>
38  <p>
39    <a href="#introduction">Introduction</a><br/>
40    <a href="#aclock">Aclock</a><br/>
41    <a href="#calendar">Calendar</a><br/>
42    <a href="#combobox">Combobox</a><br/>
43    <a href="#document">Document</a><br/>
44    <a href="#gridcontrol">Gridcontrol</a><br/>
45    <a href="#ibutton">Ibutton</a><br/>
46    <a href="#iconbox">Iconbox</a><br/>
47    <a href="#listcontrol">Listcontrol</a><br/>
48    <a href="#pane">Pane</a><br/>
49    <a href="#progressbar">Progressbar</a><br/>
50    <a href="#scrollbox">Scrollbox</a><br/>
51    <a href="#spinentry">Spinentry</a><br/>
52    <a href="#statusbar">Statusbar</a><br/>
53    <a href="#tabcontrol">Tabcontrol</a><br/>
54    <a href="#textframe">Textframe</a><br/>
55    <a href="#toolbar">Toolbar</a><br/>
56    <a href="#tooltip">Tooltip</a><br/>
57    <a href="#treecontrol">Treecontrol</a><br/>
58    <a href="#window">Window</a><br/>
59    <a href="#author">Author</a><br/>
60  </p>
61
62  <h2><a name="introduction">&nbsp;INTRODUCTION</a></h2>
63  <p>
64    The following sections are the man pages for the metawidget collection that comes
65    with the mkWidgets extension. The mkWidgets extension is primarily a <i>method</i>
66    for defining metawidgets, i.e. compound widgets that consist of an arbitrary number
67    of regular TK standard widgets. The included metawidget collection, however, should
68    already cover most of the needs and wishes of GUI designers. It was a lot of work,
69    after all ;)
70  </p>
71  <p>
72    Particularly worth to mention are the complex metawidgets gridcontrol, treecontrol,
73    listcontrol and iconbox. They demonstrate nicely how powerful the standard text
74    widget can actually be.
75    Follow these links to screenshots for <a href="DemoWin.gif">Windows</a> and <a href="DemoLin.gif">Linux</a>.
76  </p>
77  <p>
78    Every metawidget understands the commands <em>cget</em> and <em>configure</em>.
79    Also, in each metawidget there is exactly <i>one</i> standard widget that is called the
80    <i>default widget</i>. All it means is that all options and commands not explicitely
81    implemented as part of the metawidget definiton are redirected to it.
82  </p>
83  <p>
84    Consequently, a metawidget understands all options and commands that the default widget
85    understands. E.g. if the default widget is a simple frame, then the metawidget will
86    understand the -relief option, but not the -font option (unless the -font option
87    is defined and implemented as part of the metawidget itself) . These default widget options
88    and commands are not described here but can rather be found in the Tcl/Tk man pages.
89  </p>
90  <p>
91    In addition, it is also important to
92    understand the limitations that apply to metawidgets as opposed to standard widgets.
93    Please see <a href="mkWidgets13.htm">Part 1</a> of this manual for details on these
94    and for information about how metawidgets are built with the <em>metawidget</em> command.
95  </p>
96
97  <h2><a name="aclock">&nbsp;Aclock</a></h2>
98  <h3>Name</h3>
99  <p>
100    aclock - An "analog clock" metawidget
101  </p>
102  <h3>Description</h3>
103  <p>
104    The <em>aclock</em> metawidget resembles an analog clock, with an hour and a minute
105    pointer. The pointers can be dragged with the mouse. The clock can also be set with
106    two arrow buttons and a time entry field. A double-click on the gray area between
107    the buttons and the time entry field sets the current time.
108  </p>
109  <h3>Default</h3>
110  <p>
111    The default widget is of type <em>canvas</em> and displays the clock's graphical
112    elements, such as the pointers.
113    The metawidget accepts all commands and configuration options of this widget type.
114  </p>
115  <h3>Options</h3>
116  <p>
117    <em>-controls top|bottom</em><br/><br/>
118    Specifies the location of the control elements of the clock. The control elements are
119    the two arrow buttons and the time entry field. They can be either above or below the
120    clock.
121  </p>
122  <p>
123    <em>-format <i>format-string</i></em><br/><br/>
124    Accepts a format string like for the standard <em>clock format</em> command. The format
125    string controls the way the time is displayed in the entry field. Also, the <em>get</em>
126    widget command returns the time according to the format option.
127  </p>
128  <p>
129    <em>-font <i>font-spec</i></em><br/><br/>
130    Accepts a font specification like for the standard <em>-font</em> option. This options
131    is applied to the time entry field.
132  </p>
133  <h3>Commands</h3>
134  <p>
135    <em>set <i>?time-string?</i></em><br/><br/>
136    Sets the time of the clock. If no time-string is given, the current time is taken. the
137    string must be in a format acceptable to the standard <em>clock scan</em> command.
138  </p>
139  <p>
140    <em>get</em><br/><br/>
141    Returns the time the clock is set to, in the format specified by the <em>-format</em>
142    option.
143  </p>
144  <p>
145    <em>scroll <i>minutes</i></em><br/><br/>
146    Sets the clock's time forward or backward according to the specified minutes.
147  </p>
148  <p>
149    <em>bind <i>bind-arguments</i></em><br/><br/>
150    Same as the standard <em>bind</em> command, except that it applies bindings to the
151    clock's time entry field.
152  </p>
153
154  <h2><a name="calendar">&nbsp;Calendar</a></h2>
155  <h3>Name</h3>
156  <p>
157    calendar - A calendar metawidget
158  </p>
159  <h3>Description</h3>
160  <p>
161    The <em>calendar</em> metawidget provides a calendar that allows for selection
162    of a date by using the mouse or the keyboard. The user can scroll through the
163    days and weeks by using the cursor keys, and through the month and years with
164    two arrow buttons and the control key. A double-click on the date display field
165    sets the current day.
166  </p>
167  <h3>Default</h3>
168  <p>
169    The default widget is of type <em>text</em> and displays the calendar's days.
170    The metawidget accepts all commands and configuration options of this widget type.
171  </p>
172  <h3>Options</h3>
173  <p>
174    <em>-controls top|bottom</em><br/><br/>
175    Specifies the location of the control elements of the clock. The control elements are
176    the two arrow buttons and the date display field. They can be either above or below the
177    clock.
178  </p>
179  <p>
180    <em>-font <i>font-spec</i></em><br/><br/>
181    Accepts a font specification like for the standard <em>-font</em> option. This options
182    is applied to the calendar interior and the date display field.
183  </p>
184  <h3>Commands</h3>
185  <p>
186    <em>set <i>?date-string?</i></em><br/><br/>
187    Sets the date of the calendar. If no date-string is given, the current date is taken. the
188    string must be in a format acceptable to the standard <em>clock scan</em> command.
189  </p>
190  <p>
191    <em>get <i>?format-string?</i></em><br/><br/>
192    Returns the date the calendar is set to, using an optional format string. The latter
193    defaults to %m/%d/%Y, if not specified. The format string must be
194    acceptable to the standard <em>clock format</em> command.
195  </p>
196  <p>
197    <em>scroll <i>integer</i> ?days|months|years?</em><br/><br/>
198    Sets the calendar's date forward or backward according to the specified integer value
199    and unit. The latter defaults to months, if not specified.
200  </p>
201  <p>
202    <em>bind <i>bind-arguments</i></em><br/><br/>
203    Same as the standard <em>bind</em> command, except that it applies bindings to the
204    calendar's interior.
205  </p>
206  <p>
207    <em>headerconfig <i>option-value pairs</i></em><br/><br/>
208    Applies all option-value pairs to the calendar's headline, showing the weekdays.
209    Accepts all options that can be applied to a text widget tag.
210  </p>
211  <p>
212    <em>headercget <i>option</i></em><br/><br/>
213    Retrieves an option value of the calendar's headline, showing the weekdays.
214    Accepts all options that can be applied to a text widget tag.
215  </p>
216
217  <h2><a name="combobox">&nbsp;Combobox</a></h2>
218  <h3>Name</h3>
219  <p>
220    combobox - An entry widget with a pull-down menu, a.k.a. "combobox"
221  </p>
222  <h3>Description</h3>
223  <p>
224    The <em>combobox</em> metawidget is a combination of an entry widget and a
225    listbox. One can enter any text into the entry widget but also select one
226    of several predefined values from a pull-down list. This list appears whenever
227    the user clicks on the button on the right side of the entry widget.
228    In addition, the cursor keys can be used to scroll through the list whenever
229    the focus is in the entry widget.
230  </p>
231  <h3>Default</h3>
232  <p>
233    The default widget is of type <em>entry</em>. It is the entry field itself.
234    The metawidget accepts all commands and configuration options of this widget type.
235  </p>
236  <h3>Options</h3>
237  <p>
238    <em>-lines <i>integer</i></em><br/><br/>
239    Specifies the number of lines to be displayed in the list.
240  </p>
241  <p>
242    <em>-entries <i>arg arg ...</i></em><br/><br/>
243    Sets the values to be displayed in the list.
244  </p>
245  <p>
246    <em>-state normal|disabled|restricted</em><br/><br/>
247    Similar to the <em>-state</em> option of a regular <em>entry</em> widget.
248    In restricted mode, the combobox does only allow selection from the list.
249  </p>
250  <p>
251    <em>-command <i>command-string</i></em><br/><br/>
252    Executes the specified command-string whenever a new value is picked
253    from the list.
254  </p>
255  <h3>Commands</h3>
256  <p>
257    <em>see <i>?index?</i></em><br/><br/>
258    Sets a particular value from the pull-down menu, specified by <em>index</em>.
259    If <em>index</em> is not provided, the index of the current value is returned.
260    If this value is not part of the list, -1 is returned instead.
261  </p>
262
263  <h2><a name="document">&nbsp;Document</a></h2>
264  <h3>Name</h3>
265  <p>
266    document - A "multiple document interface"-like thing
267  </p>
268  <h3>Description</h3>
269  <p>
270    On Windows, MDI is a popular concept for applications that can have
271    several documents open at a time (e.g. a word processor). Instead of each open
272    document being displayed in its own window on the desktop, the documents are
273    organized in "sub-windows" that can only be moved around within the application's
274    main window.<br/><br/>
275    The <em>document</em> metawidget resembles this behavior. Other widgets can be
276    packed, placed or gridded inside a document window like in a toplevel window.
277    The document windows can be resized, minimized, maximized, moved around and, of course,
278    closed. The class function <em>Arrange</em> can be used to arrange all
279    document windows inside their parent window, which should be a <em>frame</em>.
280  </p>
281  <h3>Default</h3>
282  <p>
283    The default widget is of type <em>frame</em>.
284    The metawidget accepts all commands and configuration options of this widget type.
285  </p>
286  <h3>Options</h3>
287  <p>
288    <em>-title <i>string</i></em><br/><br/>
289    Sets the title to be displayed in the title bar.
290  </p>
291  <p>
292    <em>-image <i>image-name</i></em><br/><br/>
293    Specifies an icon to be displayed in the document window's title bar.
294  </p>
295  <p>
296    <em>-icontext <i>string</i></em><br/><br/>
297    Sets the title text to be used when the document window is iconfied.
298  </p>
299  <p>
300    <em>-x|-y|-width|-height <i>pixels</i></em><br/><br/>
301    These four options control position and size of the document window within
302    its parent window.
303  </p>
304  <p>
305    <em>-font <i>font-spec</i></em><br/><br/>
306    Sets the font for the document window's title bar.
307  </p>
308  <p>
309    <em>-foreground|-background <i>color</i></em><br/><br/>
310    For the active window, controls the foreground and background color for the title bar.
311  </p>
312  <p>
313    <em>-state normal|minimized|maximized|withdrawn</em><br/><br/>
314    Transforms the document window into one of four possible states. The <em>withdrawn</em>
315    state means that the document window disappears but is not actually deleted.
316  </p>
317  <p>
318    <em>-minsize <i>{width height}</i></em><br/><br/>
319    Controls the minimum width and height for a document window. The option argument must
320    be a proper tcl list with two integers.
321  </p>
322  <h3>Commands</h3>
323  <p>
324    <em>menu <i>options</i></em><br/><br/>
325    Modifies the pull-down menu that pops up below the document window's icon, when clicked
326    on the icon. The <em>options</em> can be all option-value pairs that the standard
327    <em>menu</em> widget accepts. This command allows to add or disable entries to the menu.
328  </p>
329  <p>
330    <em>lower|raise <i></i></em><br/><br/>
331    The document window is lowered, i.e. put behind all other windows, or raised respectively,
332    i.e., made the topmost, active window.
333  </p>
334  <p>
335    <em>pack|grid|place <i>widget args</i></em><br/><br/>
336    Allows for putting other widgets inside the document window. It is recommended to pack
337    a simple frame inside with <em>-fill both -expand 1</em> and then put all other windows
338    inside this frame by means of the standard pack, grid and place commands.
339  </p>
340  <p>
341    <em>Arrange horizontally|vertically|cascade|tile|icons|maximize|minimize</em><br/><br/>
342    Arranges all document windows according to the given parameter. <em>Arrange icons</em>
343    will arrange the icons rather than the windows.
344    This is a class-function and hence has to be called in the format <em>::Document::Arrange mode</em>
345  </p>
346
347  <h2><a name="gridcontrol">&nbsp;Gridcontrol</a></h2>
348  <h3>Name</h3>
349  <p>
350    gridcontrol - A spreadsheed, or table widget.
351  </p>
352  <h3>Description</h3>
353  <p>
354    The <em>gridcontrol</em> metawidget is a rather complex widget and can be used to display
355    data in rows and columns, hence in table format. Columns are addressed by name, rows by
356    number. Selection is supported in the regular way. Cells and cell ranges can be tagged
357    similar to text in a text widget. By configuring the tags, cells can change their color,
358    font etc. Columns can be resized with proper text clipping.<br/><br/>
359    Some commands require to specify a cell or a cell range. This is done in the format
360    <em><i>column-name.row-number</i></em>. E.g. <em>salary.4</em> specifies the cell in
361    the fourth row of the <em>salary</em> column. Wildcard are also allowed: <em>lastname.*</em>
362    specifies all cells of the column <em>lastname</em>, <em>*.12</em> all cells of row 12.
363    Consequently, <em>*.*</em> identifies the entire table.<br/><br/>
364    The entire widget is based on only three text widgets, regardless of the number of columns
365    specified.
366  </p>
367  <h3>Default</h3>
368  <p>
369    The default widget is the widget's interior area and is of type <em>text</em>.
370    The metawidget accepts all commands and configuration options of this widget type.
371  </p>
372  <h3>Options</h3>
373  <p>
374    <em>-font <i>font-spec</i></em><br/><br/>
375    Sets the font of the gridcontrol, including the column and row headers. The font for
376    individual cells or cell ranges can be controlled by means of the <em>tag</em> command.
377    (see below).
378  </p>
379  <p>
380    <em>-update full|partial|none</em><br/><br/>
381    Controls how a column is updated during a resize operation. <em>none</em> only resizes
382    the column header during dragging, <em>partial</em> resizes the column, too, but does
383    not perform clipping, <em>full</em> resizes and clips both the header and the column.
384  </p>
385  <p>
386    <em>-selectmode single|multiple</em><br/><br/>
387    Sets the select mode. If it is <em>single</em>, only one cell can be selected. In
388    <em>multiple</em> mode, cells and cell ranges can be selected by clicking on column
389    or row headers, or by using the shift and control key in combination with the mouse.
390  </p>
391  <p>
392    <em>-onselect <i>command-string</i></em><br/><br/>
393    If <em>command-string</em> is not empty, then it is evaluated each time the selection changes.
394  </p>
395  <h3>Commands</h3>
396  <p>
397    <em>column insert|delete|configure|cget|fit|bind|names|exists <i>?args?</i></em><br/><br/>
398    This command handles all column related matters. Columns are identified by a unique name and
399    have several configuration options.<br/>
400    <em>column insert <i>column-name position ?options?</i></em> inserts a new column
401    at the specified position (a non-negative integer, or "end"). In addition, configuration options
402    can be passed. <em>column delete <i>column-name</i></em> deletes the specified column.<br/>
403    <em>column configure <i>column-name ?options?</i></em> configures a column. There are three
404    special options: <em>-width <i>pixels</i></em> specifies the column's width.
405    <em>-align left|right|center|numeric</em> controls the alignment of text inside the column.
406    <em>-text <i>string</i></em> specifies the column heading. Otherwise, all options are accepted
407    that a text widget tag would accept. <em>column cget <i>column-name option</i></em> returns
408    the value of the given option.<br/>
409    <em>column fit <i>column-name</i></em> resizes a column so that all values of that columns can
410    be displayed without being clipped.
411    <em>column bind <i>column-name ?bind-args?</i></em> accepts arguments like the <em>bind</em>
412    command. They are passed directly to the column header.
413    Finally, <em>column names</em> returns a list of all currently defined columns, and
414    <em>column exists <i>column-name</i></em> returns 1 if a column exists, 0 otherwise.
415  </p>
416  <p>
417    <em>insert <i>row-number ?value-list ...?</i></em><br/><br/>
418    Inserts one or more rows, starting at the specified row number, and fill them up with
419    values. Each <em>valueList</em> must contain the values for an entire row and hence
420    have the same number of elements as columns specified. Row-number can be the string "end".
421  </p>
422  <p>
423    <em>delete <i>from-row ?to-row?</i></em><br/><br/>
424    Deletes a row or a range of rows. The string "end" can be used to denote the last row.
425  </p>
426  <p>
427    <em>set <i>cell-spec ?value-list ...?</i></em><br/><br/>
428    Sets values inside the grid. <em>cell-spec</em> specifies a cell that represents the top left
429    corner of the cell range whos values are to be replaced. E.g. <em>set Salary.5 80000</em> sets the
430    value in the Salary column in row 5 to 80000. <em>set Monday.3 {71 75 79} {58 65 61}</em> sets a
431    rectangular area of 3 columns by 2 rows. The top left cell is Monday.3 and is set to 71. Assumed
432    there is a column for every weekday, then Wednesday.4 is set to 61.
433  </p>
434  <p>
435    <em>get <i>?cell-spec1? ?cell-spec2?</i></em><br/><br/>
436    Returns the values of a cell or a range of cells. <em>cell-spec1</em> specifies the
437    top left corner, <em>cell-spec2</em> the bottom right corner of a rectangular-shaped
438    grid area. The values of that area are returned as a list, where each element represents
439    a row and is itself a list with the values of that row. If neither cell-spec is
440    specified, the entire grid contents is returned. In the above example,
441    <em>get Tuesday.3 Wednesday.4</em> returns {{75 79} {65 61}}.
442  </p>
443  <p>
444    <em>tag add|delete|remove|cget|configure|lower|raise|ranges|names|bind ?args?<i></i></em><br/><br/>
445    This command allows to apply and control tags for cells and cell ranges. This is very
446    similar to the way tags are used in the original <em>text</em> widget. Cells can have one
447    or more tags, which are identified by a name. Each tag can be configured, e.g. with a
448    certain background color, which in turn would apply this color to all cells that have this
449    particular tag.<br/>
450    <em>tag add <i>tag-name cell-spec1 ?cell-spec2?</i></em> adds the tag specified by tag-name to
451    the cell (range) specified by cell-spec1 (and cell-spec2).
452    <em>tag remove <i>tag-name cell-spec1 ?cell-spec2?</i></em> removes a previously added tag
453    from a cell or a cell range.
454    <em>tag names <i>cell-spec</i></em> returns all tags attached to a single cell. If a cell
455    range is specified, the first cell is taken.
456    <em>tag ranges <i>tag-name</i></em> returns all cells that have the specified tag currently
457    attached.
458    All other tag commands work exactly like the tag commands for the <em>text</em> widget.
459    In particular, the selection can be set by using the special tag "sel".
460  </p>
461  <p>
462    <em>bind <i>bind-arguments</i></em><br/><br/>
463    Applies bind arguments directly to the spreadsheet. The column and row headers do not
464    accept bindings.
465  </p>
466  <p>
467    <em>see <i>cell-spec</i></em><br/><br/>
468    Makes a particular cell visible, if it out of sight.
469  </p>
470  <p>
471    <em>rows</em><br/><br/>
472    Returns the total number of rows.
473  </p>
474
475  <h2><a name="ibutton">&nbsp;Ibutton</a></h2>
476  <h3>Name</h3>
477  <p>
478    ibutton - A button with an image
479  </p>
480  <h3>Description</h3>
481  <p>
482    The <em>ibutton</em> metawidget is just like a regular button, except it can have an image
483    inside it.
484  </p>
485  <h3>Default</h3>
486  <p>
487    The default widget is a regular <em>button</em>.
488    The metawidget accepts all commands and configuration options of this widget type.
489  </p>
490  <h3>Options</h3>
491  <p>
492    <em>-image <i>image-name</i></em><br/><br/>
493    Specifies the image to be displayed.
494  </p>
495  <h3>Commands</h3>
496  <p>
497    (none)
498  </p>
499
500  <h2><a name="iconbox">&nbsp;Iconbox</a></h2>
501  <h3>Name</h3>
502  <p>
503    iconbox - A container widget for icons
504  </p>
505  <h3>Description</h3>
506  <p>
507    The <em>iconbox</em> metawidget acts as a container for icons. An icon consists of
508    an image and a label and usually represent some object (e.g. a file). Hence, attributes
509    can also be displayed for each icon. There are three different views available: Large
510    icons, small icons, and list view. Only the latter one would display the attributes.
511    Bindings for the icons allow for callback scripts on events.
512  </p>
513  <h3>Default</h3>
514  <p>
515    The default widget is the inner area of the iconbox and is of type <em>text</em>.
516    The metawidget accepts all commands and configuration options of this widget type.
517  </p>
518  <h3>Options</h3>
519  <p>
520    <em>-font <i>font-spec</i></em><br/><br/>
521    Sets the font that is used for the label of the icons.
522  </p>
523  <p>
524    <em>-update full|partial|none</em><br/><br/>
525    When in list view, controls how a column is updated during a resize operation.
526    <em>none</em> only resizes the column header during dragging, <em>partial</em> resizes
527    the column, too, but does not perform clipping, <em>full</em> resizes and clips both
528    the header and the column while dragging.
529  </p>
530  <p>
531    <em>-selectmode single|multiple</em><br/><br/>
532    Sets the select mode. If it is <em>single</em>, only one icon can be selected. In
533    <em>multiple</em> mode, more than one icon can be selected
534    by using the shift and control key in combination with the mouse.
535  </p>
536  <p>
537    <em>-onselect <i>command-string</i></em><br/><br/>
538    If <em>command-string</em> is not empty, then it is evaluated each time the selection changes.
539  </p>
540  <p>
541    <em>-view large|small|list</em><br/><br/>
542    Sets the display mode for the iconbox: Large icons, small icons, and list view.
543    For list view, a column header row appears and the icon attributes are displayed.
544  </p>
545  <p>
546    <em>-columns <i>column-spec-list</i></em><br/><br/>
547    Specifies how to display icon attributes when the iconbox is in list view. Each
548    column specification in the list must itself be a proper list containing up to
549    4 elements: Caption, alignment, width and minimal width. The caption
550    is mandatory, the others are optional. An alignmentis specified by one of l (left),
551    r (right), c (center) or n (numeric). Width and minimal is be specified in pixels.
552  </p>
553  <h3>Commands</h3>
554  <p>
555    <em>insert <i>position icon-name ?options?</i></em><br/><br/>
556    Inserts a new icon at the specified position (an integer, or "end"). Icons are
557    referenced by their name, which must be unique for the iconbox. The icon is
558    configured with optional option-value pairs (see <em>iconconfigure</em> below).
559  </p>
560  <p>
561    <em>delete <i>?icon-name ...?</i></em><br/><br/>
562    Deletes one or more icons from the iconbox. If no icon names are given, then all
563    icons are deleted.
564  </p>
565  <p>
566    <em>iconconfigure <i>icon-name option value ?option value ...?</i></em><br/><br/>
567    Configures an icon. Icon specific options are<br/>
568    <em>-text <i>string</i></em>: The label to be used for the icon<br/>
569    <em>-image <i>image-name</i></em>: The image to be used when in "large icons" view<br/>
570    <em>-smallimage <i>image-name</i></em>: The image to be used when in "small icons" and list view<br/>
571    <em>-values <i>list</i></em>: The attributes to be displayed when in list view<br/>
572    <em>-user <i>user-data</i></em>: Arbitrary user data. Just stored with the icon but never used<br/>
573    All other options are applied to the icon's label (-font, -bg etc.).
574  </p>
575  <p>
576    <em>iconcget <i>icon-name option</i></em><br/><br/>
577    Returns an option value. For accepted options, see above.
578  </p>
579  <p>
580    <em>iconbind <i>icon-name bind-arguments</i></em><br/><br/>
581    Defines a binding script for an icon. See the generic <em>bind</em> man page for
582    more information. This is used primarily for mouse events, e.g. double-clicks,
583    whereas key events are defined using the <em>bind</em> metawidget command (an
584    icon cannot have the focus, since it consists of just two labels. Therefore it
585    does not generate key events).
586  </p>
587  <p>
588    <em>selection clear|get|set <i>?icon-names-list?</i></em><br/><br/>
589    Controls the selection. <em>clear</em> clears the selection, <em>set icon-names-list</em>
590    sets the selections for the specified icons, <em>get</em> returns a list of all icons
591    that are currently selected.
592  </p>
593  <p>
594    <em>sort ?-column <i>column-caption? ?lsort-options?</i></em><br/><br/>
595    Sorts the icons, either by their label or by a particular column, specified by its
596    caption as set with the <em>-columns</em> option. In addition, the options accepted
597    by the <em>lsort</em> command can be used.
598  </p>
599  <p>
600    <em>see <i>icon-name</i></em><br/><br/>
601    Makes an icon visible if it is out of sight.
602  </p>
603  <p>
604    <em>bind <i>bind-arguments</i></em><br/><br/>
605    Same as the standard <em>bind</em> command, except that it applies bindings to the
606    iconbox (a text widget).
607  </p>
608  <p>
609    <em>size</em><br/><br/>
610    Returns the number of icons in the iconbox.
611  </p>
612  <p>
613    <em>names</em><br/><br/>
614    Returns a list with the names of all icons in the iconbox.
615  </p>
616
617  <h2><a name="listcontrol">&nbsp;Listcontrol</a></h2>
618  <h3>Name</h3>
619  <p>
620    listcontrol - An enhanced listbox type widget
621  </p>
622  <h3>Description</h3>
623  <p>
624    The <em>listcontrol</em> metawidget is a multicolumn listbox. Columns can be resized
625    by dragging them. An icon can be placed into each column for each row individually.
626    Cells or cell ranges can be tagged similar like with the <em>gridcontrol</em> widget.
627    By configuring the tags, cells can change their color, font etc. A cell is specified with
628    <em><i>column-name.row-number</i></em>. E.g. <em>salary.4</em> specifies the cell in
629    the fourth row of the <em>salary</em> column. Wildcard are also allowed: <em>lastname.*</em>
630    specifies all cells of the column <em>lastname</em>, <em>*.12</em> all cells of row 12.
631    Consequently, <em>*.*</em> identifies the entire listcontrol.<br/><br/>
632    The entire widget is based on only two text widgets, regardless of the number of columns
633    specified.
634  </p>
635  <h3>Default</h3>
636  <p>
637    The default widget is the widget's interior area and is of type <em>text</em>.
638    The metawidget accepts all commands and configuration options of this widget type.
639  </p>
640  <h3>Options</h3>
641  <p>
642    <em>-font <i>font-spec</i></em><br/><br/>
643    Sets the font of the listcontrol, including the column headers. The font for
644    individual rows can be controlled by means of the <em>tag</em> command.
645    (see below).
646  </p>
647  <p>
648    <em>-update full|partial|none</em><br/><br/>
649    Controls how a column is updated during a resize operation. <em>none</em> only resizes
650    the column header during dragging, <em>partial</em> resizes the column, too, but does
651    not perform clipping, <em>full</em> resizes and clips both the header and the column.
652  </p>
653  <p>
654    <em>-selectmode single|multiple</em><br/><br/>
655    Sets the select mode. If it is <em>single</em>, only one row can be selected. In
656    <em>multiple</em> mode, several rows can be selected
657    by using the shift and control key in combination with the mouse.
658  </p>
659  <p>
660    <em>-onselect <i>command-string</i></em><br/><br/>
661    If <em>command-string</em> is not empty, then it is evaluated each time the selection changes.
662  </p>
663  <h3>Commands</h3>
664  <p>
665    <em>column insert|delete|configure|cget|fit|bind|names|exists <i>?args?</i></em><br/><br/>
666    This command handles all column related matters. Columns are identified by a unique name and
667    have several configuration options.<br/>
668    <em>column insert <i>column-name position ?options?</i></em> inserts a new column
669    at the specified position (a non-negative integer, or "end"). In addition, configuration options
670    can be passed. <em>column delete <i>column-name</i></em> deletes the specified column.<br/>
671    <em>column configure <i>column-name ?options?</i></em> configures a column. There are four
672    special options: <em>-width <i>pixels</i></em> specifies the column's width.
673    <em>-align left|right|center|numeric</em> controls the alignment of text inside the column.
674    <em>-text <i>string</i></em> specifies the column heading. <em>-minsize <i>pixels</i></em>
675    specifies the column's minimal width. Otherwise, all options are accepted
676    that a text widget tag would accept. <em>column cget <i>column-name option</i></em> returns
677    the value of the given option.<br/>
678    <em>column fit <i>column-name</i></em> resizes a column so that all values of that columns can
679    be displayed without being clipped.
680    <em>column bind <i>column-name ?bind-args?</i></em> accepts arguments like the <em>bind</em>
681    command. They are passed directly to the column header.
682    Finally, <em>column names</em> returns a list of all currently defined columns, and
683    <em>column exists <i>column-name</i></em> returns 1 if a column exists, 0 otherwise.
684  </p>
685  <p>
686    <em>insert <i>row-number ?value-list ...?</i></em><br/><br/>
687    Inserts one or more rows, starting at the specified row number, and fill them up with
688    values. Each <em>valueList</em> must contain the values for an entire row and hence
689    have the same number of elements as columns specified. Row-number can be the string "end".
690  </p>
691  <p>
692    <em>delete <i>from-row ?to-row?</i></em><br/><br/>
693    Deletes a row or a range of rows. The string "end" can be used to denote the last row.
694  </p>
695  <p>
696    <em>set ?-columns <i>column-list? start-row ?value-list ...?</i></em><br/><br/>
697    Sets new values for one or more rows. If the <em>-columns</em> option is specified, only
698    the values for certain columns will be set. Columns are addressed by their caption
699    as specified with the column property <em>-text</em>.
700  </p>
701  <p>
702    <em>get ?-columns <i>column-list? first-row ?last-row?</i></em><br/><br/>
703    Returns the values of a row or a range of rows. If the <em>-columns</em> option is specified,
704    only the values for the given columns are returned.
705  </p>
706  <p>
707    <em>tag add|delete|remove|cget|configure|lower|raise|ranges|names|bind ?args?<i></i></em><br/><br/>
708    This command allows to apply and control tags. This is very
709    similar to the way tags are used in the original <em>text</em> widget. Cells can have one
710    or more tags, which are identified by a name. Each tag can be configured, e.g. with a
711    certain background color, which in turn would apply this color to all cells that have this
712    particular tag.<br/>
713    <em>tag add <i>tag-name cell-spec1 ?cell-spec2?</i></em> adds the tag specified by tag-name to
714    the cell (range) specified by cell-spec1 (and cell-spec2).
715    <em>tag remove <i>tag-name cell-spec1 ?cell-spec2?</i></em> removes a previously added tag
716    from a cell or a cell range.
717    <em>tag names <i>cell-spec</i></em> returns all tags attached to a single cell. If a cell
718    range is specified, the first cell is taken.
719    <em>tag ranges <i>tag-name</i></em> returns all cells that have the specified tag currently
720    attached.
721    All other tag commands work exactly like the tag commands for the <em>text</em> widget.
722  </p>
723  <p>
724    <em>selection clear|get|set <i>?row-range ...?</i></em><br/><br/>
725    Controls the selection. <em>clear</em> clears the selection, <em>set row-range ?...?</em>
726    sets the selection for the specified row or range of rows,
727    <em>get</em> returns a list of all rows that are currently selected.
728  </p>
729  <p>
730    <em>image create|delete|configure|cget|names <i>?cell-spec? ?image-options?</i></em><br/><br/>
731    Allows to attach an image to a particular cell or cell range. The image options must
732    be those as accepted by the <em>image</em> command of the <em>text</em> widget.
733  </p>
734  <p>
735    <em>bind <i>bind-arguments</i></em><br/><br/>
736    Applies bind arguments directly to the listcontrol. The column headers do not
737    accept bindings.
738  </p>
739  <p>
740    <em>see <i>row</i></em><br/><br/>
741    Makes a particular cell visible, if it out of sight.
742  </p>
743  <p>
744    <em>size</em><br/><br/>
745    Returns the total number of rows.
746  </p>
747
748  <h2><a name="pane">&nbsp;Pane</a></h2>
749  <h3>Name</h3>
750  <p>
751    pane - A pane widget
752  </p>
753  <h3>Description</h3>
754  <p>
755    The <em>pane</em> metawidget is a container for two user-defined widgets.
756    Between these two widgets is a thin frame that can be dragged and hereby
757    resizes the two user widgets.
758  </p>
759  <h3>Default</h3>
760  <p>
761    The default widget is the draggable frame.
762    The metawidget accepts all commands and configuration options of this widget type.
763  </p>
764  <h3>Options</h3>
765  <p>
766    <em>-orientation vertical|horizontal</em><br/><br/>
767    Determines if the pane shall separate the two user widgets horizontally or vertically.
768  </p>
769  <p>
770    <em>-width <i>pixels</i></em><br/><br/>
771    Sets the width of the draggable frame.
772  </p>
773  <p>
774    <em>-resize both|first|second</em><br/><br/>
775    Controls how the two user widgets are being resized when the pane widget itself is
776    resized. <em>both</em> resizes the widgets proportionally, <em>first</em> resizes
777    only the left (top) widget, and <em>second</em> resizes only the
778    right (top) widget.
779  </p>
780  <p>
781    <em>-update <i>boolean</i></em><br/><br/>
782    Defines if the two user widgets shall be redrawn during dragging. If not, they
783    will be redrawn only after the mouse button is released.
784  </p>
785  <h3>Commands</h3>
786  <p>
787    <em>set <i>position</i> ?both|first|second?</em><br/><br/>
788    Sets the pane to a new position.  If <em>both</em> (the default) is specified,
789    <em>position</em> is taken as a percentage value (e.g. <em>set 50</em> would center the pane).
790    Otherwise as a pixel value (e.g. <em>set 50 first</em> makes the left (top) widget 50 pixels
791    wide (tall)).
792  </p>
793  <p>
794    <em>get ?both|first|second?</em><br/><br/>
795    The counterpart of <em>set</em>. Returns the position of the pane, either in percent
796    or in pixels.
797  </p>
798  <p>
799    <em>place|pack|grid first|second <i>window-name ?args?</i></em><br/><br/>
800    Places, packgs or grids a window either into the first (left, top) or second (right, bottom) part of the
801    container widget.
802  </p>
803
804  <h2><a name="progressbar">&nbsp;Progressbar</a></h2>
805  <h3>Name</h3>
806  <p>
807    progressbar - A simple "analog" progress bar
808  </p>
809  <h3>Description</h3>
810  <p>
811    The <em>progressbar</em> metawidget allows to visualize the progress of some process,
812    e.g. the loading of a file or processing of data.
813  </p>
814  <h3>Default</h3>
815  <p>
816    The default widget is the area behind the progress bar and is of type <em>frame</em>.
817    The metawidget accepts all commands and configuration options of this widget type.
818  </p>
819  <h3>Options</h3>
820  <p>
821    <em>-background <i>color</i></em><br/><br/>
822    Sets the color of the progress bar.
823  </p>
824  <p>
825    <em>-foreground <i>color</i></em><br/><br/>
826    Sets the color of the text display.
827  </p>
828  <p>
829    <em>-font <i>font-spec</i></em><br/><br/>
830    Sets the font of the text display.
831  </p>
832  <p>
833    <em>-format <i>format-string</i></em><br/><br/>
834    Defines the format to be used for the text display.
835  </p>
836  <h3>Commands</h3>
837  <p>
838    <em>set <i>value ?base-value?</i></em><br/><br/>
839    Sets the progress bar. If no base value is given, <em>value</em> is interpreted as
840    a percent value (0-100). The base value determines the maximum value to be used for
841    <em>value</em>. For value==base-value, the progress bar is fully displayed.
842  </p>
843
844  <h2><a name="scrollbox">&nbsp;Scrollbox</a></h2>
845  <h3>Name</h3>
846  <p>
847    scrollbox - A standard listbox with automatic scrollbars
848  </p>
849  <h3>Description</h3>
850  <p>
851    The <em>scrollbox</em> metawidget is identical to a regular listbox, except it has
852    a vertical and a horizonal scrollbar attached that pop up only when they are
853    needed. That is, they are not displayed, when all lines of the listbox can be
854    displayed in full, and no information is outside the viewable area.
855    In addition, a few "luxury commands" have been implemented. They allow to address
856    entries in the listbox by their name (i.e. the text that is displayed) rather than their index.
857  </p>
858  <h3>Default</h3>
859  <p>
860    The default widget is the listbox.
861    The metawidget accepts all commands and configuration options of this widget type.
862  </p>
863  <h3>Options</h3>
864  <p>
865    <em>-scrollbar auto|on|off</em><br/><br/>
866    Controls if the scrollbars should be displayed automatically when needed, or if
867    they should always be on respectively off.
868  </p>
869  <h3>Commands</h3>
870  <p>
871    <em>find <i>entry ?entry ...?</i></em><br/><br/>
872    A list is returned containing the indexes (position) of those entries that could be found in the listbox.
873  </p>
874  <p>
875    <em>selection setbyval|get|<i>standard-options ?args?</i></em><br/><br/>
876    Extents the standard listbox selection command by two functions: <em>setbyval</em> sets the selection
877    for all entries (not indexes) in <em>args</em>. <em>get</em> returns a list of all currently selected
878    entries (not indexes).
879  </p>
880  <p>
881    <em>set <i>entry ?entry ...?</i></em><br/><br/>
882    Deletes all existing entries and inserts new ones.
883  </p>
884  <p>
885    <em>remove <i>entry ?entry ...?</i></em><br/><br/>
886    Removes particular entries from the list.
887  </p>
888  <p>
889    <em>sort <i>standard-lsort-args</i></em><br/><br/>
890    Sorts the entries. The arguments must be those accepted by the <em>lsort</em> command.
891  </p>
892
893  <h2><a name="spinentry">&nbsp;Spinentry</a></h2>
894  <h3>Name</h3>
895  <p>
896    spinentry - An entry field with up and down arrows
897  </p>
898  <h3>Description</h3>
899  <p>
900    The <em>spinentry</em> metawidget is almost identical to a standard entry widget, except
901    it has two arrow buttons on the right side. Pressing these buttons or using the up and
902    down cursor keys increments or decrements a numeric value inside the entry widget.
903  </p>
904  <h3>Default</h3>
905  <p>
906    The default widget is the entry widget.
907    The metawidget accepts all commands and configuration options of this widget type.
908  </p>
909  <h3>Options</h3>
910  <p>
911    <em>-step <i>value</i></em><br/><br/>
912    Sets the step width to be used for increments and decrements.
913  </p>
914  <p>
915    <em>-speed <i>milliseconds</i></em><br/><br/>
916    Sets the scrolling speed to be used when the mouse is held down on the arrow buttons.
917  </p>
918  <p>
919    <em>-minimum|-maximum <i>value</i></em><br/><br/>
920    Defines a minimum and maximum value for the entry widget.
921  </p>
922  <p>
923    <em>-onerror <i>cmd</i></em><br/><br/>
924    Defines a script to be called when the value in the entry widget cannot be incremented
925    respectively decremented. If <em>cmd</em> is an empty string, then errors will not be caught.
926  </p>
927  <p>
928    <em>-value <i>value</i></em><br/><br/>
929    Sets the value inside the entry widget. Also checks if the value is of numeric type.
930    If not, an error is returned.
931  </p>
932  <h3>Commands</h3>
933  <p>
934    (none)
935  </p>
936
937  <h2><a name="statusbar">&nbsp;Statusbar</a></h2>
938  <h3>Name</h3>
939  <p>
940    statusbar - A flexible status bar at the bottom of a window
941  </p>
942  <h3>Description</h3>
943  <p>
944    The <em>statusbar</em> metawidget sticks to the bottom of a window and displays some
945    text (normally some helpful status information). In addition, it may show a "digital" progress
946    bar and an arbitrary number of additional fields, which may contain an icon and text.
947
948  </p>
949  <h3>Default</h3>
950  <p>
951    The default widget is the label that displays the status text.
952    The metawidget accepts all commands and configuration options of this widget type.
953  </p>
954  <h3>Options</h3>
955  <p>
956    <em>-ticks <i>number</i></em><br/><br/>
957    Displays a progress bar at the right side of the status bar, with the specified number of "lights"
958    (i.e., gray rectangles). To show a certain progress value, use the option <em>-progress</em>.
959  </p>
960  <p>
961    <em>-progress <i>value</i></em><br/><br/>
962    Visualizes a certain progress in the progress bar. The value must be between 0 and 1. 1 would
963    switch on all "lights" in the progress bar, 0.5 only the left half of them, 0 none.
964  </p>
965  <p>
966    <em>-state normal|withdrawn</em><br/><br/>
967    Shows or hides the status bar. The status bar is always drawn inside its parent window.
968  </p>
969  <p>
970    <em>-text <i>string</i></em><br/><br/>
971    Sets a text in the status bar. The text can be overloaded with the <em>push</em> command
972    and be recovered without redefinition with the <em>pop</em> command.
973  </p>
974  <h3>Commands</h3>
975  <p>
976    <em>push <i>string</i></em><br/><br/>
977    Overloads the currently displayed text with a new text. The metawidget maintains a stack
978    of all overloaded texts, so they can be recovered in the opposite order.
979  </p>
980  <p>
981    <em>pop</em><br/><br/>
982    Removes the text defined with the last <em>push</em> command and displays the text that
983    is "underneath" it.
984  </p>
985  <p>
986    <em>add <i>field-name ?args?</i></em><br/><br/>
987    Installs a new field, which can display an icon and text. The field name must be unique for
988    the status bar. Any additional arguments are passed to <em>itemconf</em>.
989  </p>
990  <p>
991    <em>delete <i>field-name ?field-name ...?</i></em><br/><br/>
992    Removes fields from the status bar.
993  </p>
994  <p>
995    <em>itemconf <i>field-name option value ?option value ...?</i></em><br/><br/>
996    Configures a field. Each field consists of a frame, an image and a text label. Consequently,
997    all options are accepted that these three widget types would accept. The metawidget will
998    apply them to the appropriate inner widget(s).
999  </p>
1000  <p>
1001    <em>itemcget <i>field-name option</i></em><br/><br/>
1002    Returns the value of a particular option of a field.
1003  </p>
1004
1005  <h2><a name="tabcontrol">&nbsp;Tabcontrol</a></h2>
1006  <h3>Name</h3>
1007  <p>
1008    tabcontrol - A multi-row tab widget
1009  </p>
1010  <h3>Description</h3>
1011  <p>
1012    The <em>tabcontrol</em> metawidget is a container widget that contains a row of
1013    tabs at the top. Depending on what tab is activated, the widget will show a different
1014    content. Usually, this is used for modal dialogs.
1015  </p>
1016  <h3>Default</h3>
1017  <p>
1018    The default widget is the outer frame of the container.
1019    The metawidget accepts all commands and configuration options of this widget type.
1020  </p>
1021  <h3>Options</h3>
1022  <p>
1023    <em>-width auto|<i>pixels</i>|<i>percent</i>%</em><br/><br/>
1024    Controls the width of the tab row. For <em>auto</em> the tabs will have the individual
1025    size required to display the tab label. If a percentage value is specified, the tabs
1026    will cover that percent of the entire widget's width. If a plain pixel value is specified,
1027    the tabs will be drawn to cover exactly that amount of pixels.
1028  </p>
1029  <h3>Commands</h3>
1030  <p>
1031    <em>insert <i>tab-name row ?args?</i></em><br/><br/>
1032    Creates a new tab. Tabs are identified by a tab-name which must be unique for the metawidget.
1033    Tabs are filled into the specified row from the left to the right. Any additional arguments
1034    are passed to <em>tabconfigure</em>.
1035  </p>
1036  <p>
1037    <em>delete <i>tab-name</i></em><br/><br/>
1038    Deletes the specified tab.
1039  </p>
1040  <p>
1041    <em>tabconfigure <i>tab-name option value ?option value ...?</i></em><br/><br/>
1042    Configures a tab. Each tab is actually a label, therefore all label options are accepted.
1043    In addition there are two special options: <em>-window</em> specifies the user widget to
1044    be displayed when the tab is active. <em>-command</em> specifies a script to be evaluated
1045    each time the tab is activated.
1046  </p>
1047  <p>
1048    <em>tabcget <i>tab-name option</i></em><br/><br/>
1049    Returns an option value for a tab.
1050  </p>
1051  <p>
1052    <em>invoke <i></i></em><br/><br/>
1053    Activates a tab and shows its associated user widget.
1054  </p>
1055  <p>
1056    <em>get ?active|<i>row</i>?</em><br/><br/>
1057    If no arguments is specified, returns all tab names. If <em>active</em> is specified,
1058    returns the active tab. If a valid row number is specified, returns the tabs in this row.
1059  </p>
1060  <p>
1061    <em>bind <i>tab-name bind-arguments</i></em><br/><br/>
1062    Applies bind arguments directly to a tab.
1063  </p>
1064
1065  <h2><a name="textframe">&nbsp;Textframe</a></h2>
1066  <h3>Name</h3>
1067  <p>
1068    textframe - A frame with a title text
1069  </p>
1070  <h3>Description</h3>
1071  <p>
1072    The <em>textframe</em> metawidget is a regular frame widget with a title text
1073  </p>
1074  <h3>Default</h3>
1075  <p>
1076    The default widget is the frame itself.
1077    The metawidget accepts all commands and configuration options of this widget type.
1078  </p>
1079  <h3>Options</h3>
1080  <p>
1081    <em>-anchor n|s|w|e|c</em><br/><br/>
1082    Specifies the anchor position of the title text relative to the frame.
1083  </p>
1084  <p>
1085    <em>-offset <i>value</i></em><br/><br/>
1086    Sets an offset value for the title text. There are three different formats:
1087    E.g. 20% sets the label 20% of the frame's width off from the left.
1088    20 sets the label 20 pixel from the left border (good with -anchor w).
1089    end-20 sets it from the frame's right border (good with -anchor e).
1090  </p>
1091  <p>
1092    <em>-font <i>font-spec</i></em><br/><br/>
1093    Sets the font for the title text.
1094  </p>
1095  <p>
1096    <em>-text <i>string</i></em><br/><br/>
1097    Sets the title text.
1098  </p>
1099  <h3>Commands</h3>
1100  <p>
1101    <em>pack|place|grid <i>window ?args?</i></em><br/><br/>
1102    Packs, places or grids user widgets inside the textframe widget.
1103  </p>
1104
1105  <h2><a name="toolbar">&nbsp;Toolbar</a></h2>
1106  <h3>Name</h3>
1107  <p>
1108    toolbar - A container widget for tool buttons
1109  </p>
1110  <h3>Description</h3>
1111  <p>
1112    Toolbars are popular elements in graphical applications. Toolbars contain a number
1113    of icons that represent entries from the application's menu. Hence, they are like
1114    shortcuts to certain application functions. The icons often behave like regular
1115    buttons, but can also act like checkbuttons and radiobuttons.
1116    The <em>toolbar</em> metawidget resembles such a complex widget. Buttons, checkbuttons
1117    and radiobuttons can be defined, groups of buttons can be separated by a separator line,
1118    and the entire toolbar can be dragged to the four sides of its parent window.
1119  </p>
1120  <h3>Default</h3>
1121  <p>
1122    The default widget is the outer frame that contains the tool buttons.
1123    The metawidget accepts all commands and configuration options of this widget type.
1124  </p>
1125  <h3>Options</h3>
1126  <p>
1127    <em>-side top|bottom|left|right</em><br/><br/>
1128    Attaches the toolbar to one of the four sides of its parent widget.
1129  </p>
1130  <p>
1131    <em>-state normal|fixed|withdrawn</em><br/><br/>
1132    Controls whether the toolbar shall be hidden or visible. For <em>-state fixed</em> the toolbar
1133    cannot be dragged.
1134  </p>
1135  <h3>Commands</h3>
1136  <p>
1137    <em>add button|checkbutton|radiobutton|separator <i>name ?args?</i></em><br/><br/>
1138    Adds a new item to the toolbar. Items are identifed by a name that must be unique for the
1139    toolbar. Additional arguments are expected to be option-value pairs and are passed on to <em>itemconf</em>.
1140    For the <em>radiobutton</em> type, there is one special option <em>-group <i>group-name</i></em>, which
1141    identifies to which radiobutton group the item shall belong.
1142  </p>
1143  <p>
1144    <em>delete <i>name ?name ...?</i></em><br/><br/>
1145    Deletes items from the toolbar.
1146  </p>
1147  <p>
1148    <em>itemconf <i>name option value ?option value ...?</i></em><br/><br/>
1149    Configures an item. Accepts all options that a button widget would accept. In particular, <em>-image</em>
1150    to set an icon and <em>-command</em> to define an action are important here.
1151  </p>
1152  <p>
1153    <em>itemcget <i>name option</i></em><br/><br/>
1154    Returns an option value of the specified item.
1155  </p>
1156  <p>
1157    <em>invoke <i>name ?new-state?</i></em><br/><br/>
1158    Invokes a tool button. Same as if it was pressed. If the item is of type checkbutton, then <em>new-state</em>,
1159    a boolean, may define the new state of the checkbutton. This argument does not apply to button and radiobutton
1160    item types.
1161  </p>
1162  <p>
1163    <em>set <i>name ?new-state?</i></em><br/><br/>
1164    Same as <em>invoke</em> except that the item's associated command is not called. This is used e.g. when the
1165    function that the tool button represents has been called from somewhere else (e.g. from the menu) and now
1166    the tool button needs to be updated only.
1167  </p>
1168  <p>
1169    <em>get <i>name</i></em><br/><br/>
1170    Returns the state of a tool button as boolean. For regular buttons, always returns 0.
1171  </p>
1172  <p>
1173    <em>names <i>?pattern?</i></em><br/><br/>
1174    Returns a list with the names of all tool buttons. If a glob-style pattern is given, only those names
1175    are returned that match the pattern.
1176  </p>
1177
1178  <h2><a name="tooltip">&nbsp;Tooltip</a></h2>
1179  <h3>Name</h3>
1180  <p>
1181    tooltip - Pop-up information when moving over a widget
1182  </p>
1183  <h3>Description</h3>
1184  <p>
1185    The <em>tooltip</em> metawidget provides a feature that is standard of nowadays user interfaces:
1186    Whenever the user hovers over an element, such as an icon, a often yellowish little text window pops up
1187    after a second or so that explains the meaning of that button. The text disappers when the mouse leaves
1188    the area of the button.
1189  </p>
1190  <h3>Default</h3>
1191  <p>
1192    The default widget is of type <em>label</em>. It is the tooltip window itself.
1193    The metawidget accepts all commands and configuration options of this widget type.
1194  </p>
1195  <h3>Options</h3>
1196  <p>
1197    <em>-delay <i>milliseconds</i></em><br/><br/>
1198    Time to expire before the tooltip shall pop up after the user entered a widget's area.
1199  </p>
1200  <h3>Commands</h3>
1201  <p>
1202    <em>add <i>widget-name string</i></em><br/><br/>
1203    Activates the tooltip feature for a particular user-defined widget and defines the text to be displayed.
1204    The text can be changed by calling this command again without having to call <em>forget</em> before.
1205  </p>
1206  <p>
1207    <em>forget <i>widget-name</i></em><br/><br/>
1208    Removes the tooltip feature for a particular widget.
1209  </p>
1210
1211  <h2><a name="treecontrol">&nbsp;Treecontrol</a></h2>
1212  <h3>Name</h3>
1213  <p>
1214    treecontrol - A fairly nice tree widget
1215  </p>
1216  <h3>Description</h3>
1217  <p>
1218    The <em>treecontrol</em> metawidget allows to built an Explorer-style tree with an arbitrary number
1219    of nodes. A node consists of a +/- icon (to expand and collapse them), a user-defined icon and a label.
1220    Selection behaves as expected, including the use of the Shift and Control keys. Navigation through
1221    the tree is done via mouse or keyboard. A double-click on the +/- icon expands or collapses a node,
1222    and so do the cursor keys for left and right. If, in addition, the Shift key is pressed then all
1223    subnodes are expanded respectively collapsed as well.<br/><br/>
1224    Callbacks are defined via node bindings. A particular useful feature is that the tree does not have
1225    to be completely defined before being able to use it. Instead, it is sufficient to define the toplevel
1226    nodes only, and then let the tree widget ask for a node's children whenever one of the toplevel nodes
1227    is expanded. This is done via a special callback.<br/><br/>
1228    The entire tree widget is built from a single text widget. My highest respect for its developer!
1229  </p>
1230  <h3>Default</h3>
1231  <p>
1232    The default widget is the tree widget itself and is of type <em>text</em>.
1233    The metawidget accepts all commands and configuration options of this widget type.
1234  </p>
1235  <h3>Options</h3>
1236  <p>
1237    <em>-text <i>string</i></em><br/><br/>
1238    Every tree has one root node that is always at the top of the widget. This option
1239    sets the label of the root node.
1240  </p>
1241  <p>
1242    <em>-image <i>image-name</i></em><br/><br/>
1243    Sets the image to be used for the root node.
1244  </p>
1245  <p>
1246    <em>-fullexpand <i>boolean</i></em><br/><br/>
1247    Controls whether automatic expanding of all subnodes of a node shall be allowed, when the Shift key
1248    was pressed by the user. This feature may be not desired e.g. if the tree represents a file system and the
1249    user is in a high level directory, e.g. / or c:\. Expansion might virtually take forever.
1250  </p>
1251  <p>
1252    <em>-selectmode <i>single|multiple</i></em><br/><br/>
1253    Controls whether only one or more than one node can be selected at a time.
1254  </p>
1255  <p>
1256    <em>-onexpand <i>command</i></em><br/><br/>
1257    The command specified herein is evaluated whenever a node is being expanded and the children of that
1258    node are not known yet, or the node is not defined as "final" (see <em>nodeconfigure</em> below).
1259    The to-be-expanded node is appended to the command as an argument, and the command is expected to
1260    add all children to the tree by means of the <em>insert</em> command. If <em>command</em> is an
1261    empty string, no callback will be made.
1262  </p>
1263  <p>
1264    <em>-onselect <i>command</i></em><br/><br/>
1265    If the command is not an empty string, it is evaluated each time the selection changes.
1266  </p>
1267  <h3>Commands</h3>
1268  <p>
1269    <em>insert <i>node ?args?</i></em><br/><br/>
1270    Inserts a new node to the tree. Nodes are referenced by a name that must be unique over the
1271    entire tree. Additional arguments are expected to be option-value pairs and are passed on
1272    to the <em>nodeconfigure</em> commmand (see below).
1273  </p>
1274  <p>
1275    <em>delete <i>?node?</i></em><br/><br/>
1276    Deletes a particular node and all its children, or the entire tree, if no name is specified.
1277  </p>
1278  <p>
1279    <em>nodeconfigure <i>node option value ?option value ...?</i></em><br/><br/>
1280    Configures a node. Allowed options are:<br/>
1281    <em>-parent <i>node</i></em>: Sets a new parent node. The node will be drawn as a child of
1282    that parent node. The tree's root node is represented by an empty string.<br/>
1283    <em>-text <i>string</i></em>: Sets the nodes label.<br/>
1284    <em>-image <i>image-name</i></em>: Sets an icon for the node. If the image name is an empty
1285    string, removes the icon.<br/>
1286    <em>-final <i>boolean</i></em>: Tells the tree wigdet that the given node is complete, i.e.
1287    all of its children are defined. The tree widget will not call the <em>-onexpand</em> command
1288    any more when this node gets expanded.<br/>
1289    <em>-user <i>string</i></em>: Arbitrary user data. Just stored with the node but never used.<br/>
1290  </p>
1291  <p>
1292    <em>nodecget <i>node option</i></em><br/><br/>
1293    Returns the value of a node option. Besides from the options described under <em>nodeconfigure</em>,
1294    the following options are accepted:<br/>
1295    <em>-children</em> returns a list of all child nodes.<br/>
1296    <em>-indention</em> returns the current indention level of the node.<br/>
1297    <em>-expanded</em> returns a boolean indicating if the node is currently expanded.<br/>
1298    <em>-tags</em> returns a list of all tags currently associated with the node (see below).<br/>
1299    <em>-visible</em> returns a boolean indicating if the node is visible, i.e. all of its parents
1300    are expanded. (The node can still be not on the screen because the tree's viewport is somewhere else.)
1301  </p>
1302  <p>
1303    <em>nodebind <i>node ?bind-arguments?</i></em><br/><br/>
1304    Creates bindings for a particular node. This allows to define different actions for different node types.
1305    E.g. in a filesystem tree, double-clicking a directory normally expands it, while double-clicking a file
1306    displays it.
1307  </p>
1308  <p>
1309    <em>expand <i>node ?recursive-flag?</i></em><br/><br/>
1310    Expands a node and, if the optional flag is true, all of its subnodes.
1311  </p>
1312  <p>
1313    <em>collapse <i>node ?recursive-flag?</i></em><br/><br/>
1314    Collapses a node and, if the optional flag is true, all of its subnodes.
1315  </p>
1316  <p>
1317    <em>move <i>node</i> ?-byname? ?-after? <i>position</i></em><br/><br/>
1318    Moves a node to a specified position within its siblings. If <em>-byname</em> is specified, <em>position</em>
1319    must be the name of a sibling node (or any other node, in which case the node specified by <em>node</em> gets
1320    reparented). The node will be placed before the sibling node, unless <em>-after</em> is specified.
1321  </p>
1322  <p>
1323    <em>tag add|delete|remove|cget|configure|lower|raise|names|nodes|bind ?args?<i></i></em><br/><br/>
1324    This command allows to apply and control tags for nodes in the tree. This is very
1325    similar to the way tags are used in the original <em>text</em> widget. Nodes can have one
1326    or more tags, which are identified by a name. Each tag can be configured, e.g. with a
1327    certain background color, which in turn would apply this color to all nodes that have this
1328    particular tag.<br/>
1329    <em>tag add <i>tag-name node ?node ...?</i></em> adds the tag specified by tag-name to one or more nodes.
1330    <em>tag remove <i>tag-name node ?node ...?</i></em> removes a previously added tag from one or more nodes.
1331    <em>tag names <i>node</i></em> returns all tags attached to a node.
1332    <em>tag nodes <i>tag-name</i></em> returns all nodes that currently have the specified tag.
1333    All other tag commands work exactly like the tag commands for the <em>text</em> widget.
1334  </p>
1335  <p>
1336    <em>selection clear|get|set <i>?node-names-list?</i></em><br/><br/>
1337    Controls the selection. <em>clear</em> clears the selection, <em>set node-names-list</em>
1338    sets the selections for the specified nodes, <em>get</em> returns a list of all nodes
1339    that are currently selected.
1340  </p>
1341  <p>
1342    <em>get <i>from-row ?to-row?</i></em><br/><br/>
1343    Returns a list of nodes that are between the two specified rows. The returned list depends on which
1344    nodes are expanded and which ones are collapsed, i.e., nodes that are not visible because their parent is
1345    collapsed, are not part of the list.
1346  </p>
1347  <p>
1348    <em>see <i>node</i></em><br/><br/>
1349    Makes a node visible on the screen. If any of the node's parents are collapsed, then they are expanded first, so that
1350    the node is drawn into the widget. Then the viewport is set, so that the node appears on the screen.
1351  </p>
1352  <p>
1353    <em>bind <i>bind-arguments</i></em><br/><br/>
1354    Applies bindings directly to the tree widget.
1355  </p>
1356  <p>
1357    <em>nodes</em><br/><br/>
1358    Returns an unordered list of all nodes, whether visible or not.
1359  </p>
1360  <p>
1361    <em>tree <i>node</i></em><br/><br/>
1362    Returns the structure of the subtree starting at the specified node as a recursive list.
1363    Each list element is itself a list with two elements: the node's unique name and its child nodes.
1364  </p>
1365
1366  <h2><a name="window">&nbsp;Window</a></h2>
1367  <h3>Name</h3>
1368  <p>
1369    window - A wrapper around the toplevel widget and the wm command
1370  </p>
1371  <h3>Description</h3>
1372  <p>
1373    The <em>window</em> metawidget's purpose is to unify the window widget and the wm command.
1374    It is in so far not a true metawidget, but it makes the handling of toplevel widgets easier.
1375  </p>
1376  <h3>Default</h3>
1377  <p>
1378    The default widget is a toplevel widget.
1379    The metawidget accepts all commands and configuration options of this widget type.
1380  </p>
1381  <h3>Options</h3>
1382  <p>
1383    <em>-geometry <i>geometry-string</i></em><br/><br/>
1384    Sets position and size of the window. The geometry string must have the same format
1385    as described under "wm geometry".
1386  </p>
1387  <p>
1388    <em>-minsize|-maxsize <i>list</i></em><br/><br/>
1389    Sets the minimum and maximum size of the window. The list must contain the width and height to be set.
1390  </p>
1391  <p>
1392    <em>-resizable <i>list</i></em><br/><br/>
1393    Specifies if the window can be resized in x and/or y direction. The list must contain two booleans
1394    for the x and y direction.
1395  </p>
1396  <p>
1397    <em>-override <i>boolean</i></em><br/><br/>
1398    Controls if the window is ignored by the window manager.
1399  </p>
1400  <p>
1401    <em>-ondelete <i>command</i></em><br/><br/>
1402    Specifies a command to run whenever the window manager wants to close the window. The command
1403    must eventually destroy the window itself.
1404  </p>
1405  <p>
1406    <em>-title <i>string</i></em><br/><br/>
1407    Sets the window title.
1408  </p>
1409  <p>
1410    <em>-state normal|iconic|withdrawn</em><br/><br/>
1411    Sets the window's state: Normal, iconified, or hidden.
1412  </p>
1413  <h3>Commands</h3>
1414  <p>
1415    <em>resize <i>width height</i></em><br/><br/>
1416    Sets the size of the window.
1417  </p>
1418  <p>
1419    <em>move <i>x y</i></em><br/><br/>
1420    Moves the window to a new position.
1421  </p>
1422  <p>
1423    <em>protocol <i>wm-protocol-args</i></em><br/><br/>
1424    All arguments are directly passed to <em>wm protocol</em>.
1425  </p>
1426
1427  <h2><a name="author">&nbsp;AUTHOR</a></h2>
1428  <p>
1429    Michael Kraus<br/>
1430    <a href="mailto:michael@kraus5.de">mailto:michael@kraus5.de</a><br/>
1431    <a href="http://mkextensions.sourceforge.net">http://mkextensions.sourceforge.net</a><br/>
1432  </p>
1433</body>
1434
1435</html>
Note: See TracBrowser for help on using the repository browser.