| 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=""/> 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/> </h6> |
|---|
| 32 | |
|---|
| 33 | <h2> 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"> 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"> 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"> 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"> 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"> 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"> 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"> 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"> 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"> 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"> 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"> 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"> 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"> 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"> 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"> 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"> 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"> 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"> 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"> 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"> 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"> 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> |
|---|