From 9ce6a9ef585b01f548bd9b9da7d81fe6e0710c8f Mon Sep 17 00:00:00 2001 From: "donal.k.fellows@manchester.ac.uk" Date: Tue, 30 Oct 2007 21:29:58 +0000 Subject: More documentation improvements --- doc/canvas.n | 38 ++++++++++--------- doc/chooseDirectory.n | 13 +++---- doc/cursors.n | 11 ++---- doc/entry.n | 9 +++-- doc/event.n | 5 +-- doc/getOpenFile.n | 15 ++++---- doc/optionMenu.n | 88 ++++++++++++++++++++++---------------------- doc/spinbox.n | 7 ++-- doc/text.n | 15 ++++++-- doc/ttk_button.n | 6 ++- doc/ttk_checkbutton.n | 4 +- doc/ttk_menubutton.n | 13 ++----- doc/ttk_notebook.n | 4 +- doc/ttk_panedwindow.n | 7 +--- doc/ttk_radiobutton.n | 4 +- doc/ttk_scrollbar.n | 6 ++- doc/ttk_sizegrip.n | 16 ++++---- doc/ttk_style.n | 15 +++----- doc/ttk_treeview.n | 56 ++++++++++++++++------------ doc/ttk_widget.n | 20 +++++----- doc/wm.n | 100 ++++++++++++++++++++++++++------------------------ 21 files changed, 230 insertions(+), 222 deletions(-) diff --git a/doc/canvas.n b/doc/canvas.n index 93e7f7c..fe7f671 100644 --- a/doc/canvas.n +++ b/doc/canvas.n @@ -6,7 +6,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: canvas.n,v 1.29 2007/10/29 16:04:13 dkf Exp $ +'\" RCS: @(#) $Id: canvas.n,v 1.30 2007/10/30 21:29:58 dkf Exp $ '\" .so man.macros .TH canvas n 8.3 Tk "Tk Built-In Commands" @@ -305,16 +305,18 @@ segments are drawn using the color. The other segments are drawn transparent. .PP The second possible syntax is a character list containing only -5 possible characters \fB[.,\-_ ]\fR. The space can be used -to enlarge the space between other line elements, and can not +5 possible characters +.QW "\fB.,\-_ \fR" . +The space can be used +to enlarge the space between other line elements, and cannot occur as the first position in the string. Some examples: .CS - \-dash . = \-dash {2 4} - \-dash \- = \-dash {6 4} - \-dash \-. = \-dash {6 4 2 4} - \-dash \-.. = \-dash {6 4 2 4 2 4} - \-dash {. } = \-dash {2 8} - \-dash , = \-dash {4 4} +\-dash . \(-> \-dash {2 4} +\-dash \- \(-> \-dash {6 4} +\-dash \-. \(-> \-dash {6 4 2 4} +\-dash \-.. \(-> \-dash {6 4 2 4 2 4} +\-dash {. } \(-> \-dash {2 8} +\-dash , \(-> \-dash {4 4} .CE .PP The main difference of this syntax with the previous is that it @@ -1183,7 +1185,7 @@ pairs, each of which sets one of the configuration options for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's configuration. -.br +.PP The following standard options are supported by arcs: .CS \-dash @@ -1253,7 +1255,7 @@ pairs, each of which sets one of the configuration options for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's configuration. -.br +.PP The following standard options are supported by bitmaps: .CS \-state @@ -1319,7 +1321,7 @@ pairs, each of which sets one of the configuration options for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's configuration. -.br +.PP The following standard options are supported by images: .CS \-state @@ -1364,7 +1366,7 @@ pairs, each of which sets one of the configuration options for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's configuration. -.br +.PP The following standard options are supported by lines: .CS \-dash @@ -1476,7 +1478,7 @@ pairs, each of which sets one of the configuration options for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's configuration. -.br +.PP The following standard options are supported by ovals: .CS \-dash @@ -1523,7 +1525,7 @@ pairs, each of which sets one of the configuration options for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's configuration. -.br +.PP The following standard options are supported by polygons: .CS \-dash @@ -1616,7 +1618,7 @@ pairs, each of which sets one of the configuration options for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's configuration. -.br +.PP The following standard options are supported by rectangles: .CS \-dash @@ -1664,7 +1666,7 @@ pairs, each of which sets one of the configuration options for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's configuration. -.br +.PP The following standard options are supported by text items: .CS \-fill @@ -1745,7 +1747,7 @@ pairs, each of which sets one of the configuration options for the item. These same \fIoption\fR\-\fIvalue\fR pairs may be used in \fBitemconfigure\fR widget commands to change the item's configuration. -.br +.PP The following standard options are supported by window items: .CS \-state diff --git a/doc/chooseDirectory.n b/doc/chooseDirectory.n index 29b5bdc..a4f9e37 100644 --- a/doc/chooseDirectory.n +++ b/doc/chooseDirectory.n @@ -2,7 +2,7 @@ '\" Copyright (c) 1998-2000 by Scriptics Corporation. '\" All rights reserved. '\" -'\" RCS: @(#) $Id: chooseDirectory.n,v 1.7 2007/10/29 16:04:13 dkf Exp $ +'\" RCS: @(#) $Id: chooseDirectory.n,v 1.8 2007/10/30 21:29:58 dkf Exp $ '\" .so man.macros .TH tk_chooseDirectory n 8.3 Tk "Tk Built-In Commands" @@ -14,7 +14,6 @@ tk_chooseDirectory \- pops up a dialog box for the user to select a directory. .SH SYNOPSIS \fBtk_chooseDirectory \fR?\fIoption value ...\fR? .BE - .SH DESCRIPTION .PP The procedure \fBtk_chooseDirectory\fR pops up a dialog box for the @@ -31,6 +30,11 @@ the Macintosh. This is not a bug. Rather, the \fIGeneral Controls\fR control panel on the Mac allows the end user to override the application default directory. .TP +\fB\-mustexist\fR \fIboolean\fR +Specifies whether the user may specify non-existent directories. If +this parameter is true, then the user may only select directories that +already exist. The default value is \fIfalse\fR. +.TP \fB\-parent\fR \fIwindow\fR Makes \fIwindow\fR the logical parent of the dialog. The dialog is displayed on top of its parent window. @@ -38,11 +42,6 @@ is displayed on top of its parent window. \fB\-title\fR \fItitleString\fR Specifies a string to display as the title of the dialog box. If this option is not specified, then a default title will be displayed. -.TP -\fB\-mustexist\fR \fIboolean\fR -Specifies whether the user may specify non-existent directories. If -this parameter is true, then the user may only select directories that -already exist. The default value is \fIfalse\fR. .SH EXAMPLE .CS set dir [\fBtk_chooseDirectory\fR \e diff --git a/doc/cursors.n b/doc/cursors.n index 017a1be..fb6c9db 100644 --- a/doc/cursors.n +++ b/doc/cursors.n @@ -4,7 +4,7 @@ '\" '\" Copyright (c) 2006-2007 Daniel A. Steffen '\" -'\" RCS: @(#) $Id: cursors.n,v 1.6 2007/10/29 16:04:13 dkf Exp $ +'\" RCS: @(#) $Id: cursors.n,v 1.7 2007/10/30 21:29:58 dkf Exp $ '\" '\" .so man.macros @@ -14,7 +14,6 @@ .SH NAME cursors \- mouse cursors available in Tk .BE - .SH DESCRIPTION .PP The \fB\-cursor\fR widget option allows a Tk programmer to change the @@ -99,12 +98,10 @@ umbrella ur_angle watch xterm - -The \fBnone\fR cursor can be specified to eliminate the cursor. .CE - +.PP +The \fBnone\fR cursor can be specified to eliminate the cursor. .SH "PORTABILITY ISSUES" - .TP \fBWindows\fR On Windows systems, the following cursors are mapped to native cursors: @@ -135,7 +132,6 @@ uparrow wait .CE .RE - .TP \fBMac OS X\fR On Mac OS X systems, the following cursors are mapped to native cursors: @@ -174,6 +170,5 @@ countingupanddownhand spinning .CE .RE - .SH KEYWORDS cursor, option diff --git a/doc/entry.n b/doc/entry.n index 3a2206a..8ed48ad 100644 --- a/doc/entry.n +++ b/doc/entry.n @@ -6,7 +6,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: entry.n,v 1.19 2007/10/29 16:04:13 dkf Exp $ +'\" RCS: @(#) $Id: entry.n,v 1.20 2007/10/30 21:29:58 dkf Exp $ '\" .so man.macros .TH entry n 8.3 Tk "Tk Built-In Commands" @@ -81,7 +81,6 @@ in average-size characters of the widget's font. If the value is less than or equal to zero, the widget picks a size just large enough to hold its current text. .BE - .SH DESCRIPTION .PP The \fBentry\fR command creates a new window (given by the @@ -192,10 +191,11 @@ The \fBentry\fR command creates a new Tcl command whose name is \fIpathName\fR. This command may be used to invoke various operations on the widget. It has the following general form: .CS -\fIpathName option \fR?\fIarg arg ...\fR? +\fIpathName subcommand \fR?\fIarg arg ...\fR? .CE -\fIOption\fR and the \fIarg\fRs +\fISubcommand\fR and the \fIarg\fRs determine the exact behavior of the command. +.SS INDICES .PP Many of the widget commands for entries take one or more indices as arguments. An index specifies a particular character in the entry's @@ -240,6 +240,7 @@ or .QW \fBsel.f\fR . In general, out-of-range indices are automatically rounded to the nearest legal value. +.SS SUBCOMMANDS .PP The following commands are possible for entry widgets: .TP diff --git a/doc/event.n b/doc/event.n index f35c6e0..809ee73 100644 --- a/doc/event.n +++ b/doc/event.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: event.n,v 1.15 2007/10/29 16:04:13 dkf Exp $ +'\" RCS: @(#) $Id: event.n,v 1.16 2007/10/30 21:29:59 dkf Exp $ '\" .so man.macros .TH event n 8.3 Tk "Tk Built-In Commands" @@ -16,7 +16,6 @@ event \- Miscellaneous event facilities: define virtual events and generate even .SH SYNOPSIS \fBevent\fI option \fR?\fIarg arg ...\fR? .BE - .SH DESCRIPTION .PP The \fBevent\fR command provides several facilities for dealing with @@ -69,7 +68,7 @@ If the \fB\-when\fR option is specified then it determines when the event is processed. Certain events, such as key events, require that the window has focus to receive the event properly. .TP -\fBevent info \fR?<<\fIvirtual\fB>>\fR? +\fBevent info \fR?\fB<<\fIvirtual\fB>>\fR? Returns information about virtual events. If the \fB<<\fIvirtual\fB>>\fR argument is omitted, the return value is a list of all the virtual events that are currently defined. diff --git a/doc/getOpenFile.n b/doc/getOpenFile.n index 8a026c1..a347de1 100644 --- a/doc/getOpenFile.n +++ b/doc/getOpenFile.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: getOpenFile.n,v 1.20 2007/10/29 16:04:13 dkf Exp $ +'\" RCS: @(#) $Id: getOpenFile.n,v 1.21 2007/10/30 21:29:59 dkf Exp $ '\" .so man.macros .TH tk_getOpenFile n 4.2 Tk "Tk Built-In Commands" @@ -13,9 +13,10 @@ .SH NAME tk_getOpenFile, tk_getSaveFile \- pop up a dialog box for the user to select a file to open or save. .SH SYNOPSIS +.nf \fBtk_getOpenFile \fR?\fIoption value ...\fR? -.br \fBtk_getSaveFile \fR?\fIoption value ...\fR? +.fi .BE .SH DESCRIPTION .PP @@ -69,16 +70,16 @@ application default directory. Specifies a filename to be displayed in the dialog when it pops up. This option is ignored on the Macintosh platform. .TP -\fB\-multiple\fR \fIboolean\fR -Allows the user to choose multiple files from the Open dialog. -On the Macintosh, this is only available when Navigation Services are -installed. -.TP \fB\-message\fR \fIstring\fR Specifies a message to include in the client area of the dialog. This is only available on the Macintosh, and only when Navigation Services are installed. .TP +\fB\-multiple\fR \fIboolean\fR +Allows the user to choose multiple files from the Open dialog. +On the Macintosh, this is only available when Navigation Services are +installed. +.TP \fB\-parent\fR \fIwindow\fR Makes \fIwindow\fR the logical parent of the file dialog. The file dialog is displayed on top of its parent window. diff --git a/doc/optionMenu.n b/doc/optionMenu.n index b6d3257..761c99b 100644 --- a/doc/optionMenu.n +++ b/doc/optionMenu.n @@ -1,45 +1,43 @@ -'\" -'\" Copyright (c) 1990-1994 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: optionMenu.n,v 1.3 2004/06/21 14:48:04 dkf Exp $ -'\" -.so man.macros -.TH tk_optionMenu n 4.0 Tk "Tk Built-In Commands" -.BS -'\" Note: do not modify the .SH NAME line immediately below! -.SH NAME -tk_optionMenu \- Create an option menubutton and its menu -.SH SYNOPSIS -\fBtk_optionMenu \fIw varName value \fR?\fIvalue value ...\fR? -.BE - -.SH DESCRIPTION -.PP -This procedure creates an option menubutton whose name is \fIw\fR, -plus an associated menu. -Together they allow the user to select one of the values -given by the \fIvalue\fR arguments. -The current value will be stored in the global variable whose -name is given by \fIvarName\fR and it will also be displayed as the label -in the option menubutton. -The user can click on the menubutton to display a menu containing -all of the \fIvalue\fRs and thereby select a new value. -Once a new value is selected, it will be stored in the variable -and appear in the option menubutton. -The current value can also be changed by setting the variable. -.PP -The return value from \fBtk_optionMenu\fR is the name of the menu -associated with \fIw\fR, so that the caller can change its configuration -options or manipulate it in other ways. -.SH EXAMPLE -.CS -tk_optionMenu .foo myVar Foo Bar Boo Spong Wibble -pack .foo -.CE - -.SH KEYWORDS -option menu +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: optionMenu.n,v 1.4 2007/10/30 21:29:59 dkf Exp $ +'\" +.so man.macros +.TH tk_optionMenu n 4.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +tk_optionMenu \- Create an option menubutton and its menu +.SH SYNOPSIS +\fBtk_optionMenu \fIpathName varName value \fR?\fIvalue value ...\fR? +.BE +.SH DESCRIPTION +.PP +This procedure creates an option menubutton whose name is \fIpathName\fR, +plus an associated menu. +Together they allow the user to select one of the values +given by the \fIvalue\fR arguments. +The current value will be stored in the global variable whose +name is given by \fIvarName\fR and it will also be displayed as the label +in the option menubutton. +The user can click on the menubutton to display a menu containing +all of the \fIvalue\fRs and thereby select a new value. +Once a new value is selected, it will be stored in the variable +and appear in the option menubutton. +The current value can also be changed by setting the variable. +.PP +The return value from \fBtk_optionMenu\fR is the name of the menu +associated with \fIpathName\fR, so that the caller can change its +configuration options or manipulate it in other ways. +.SH EXAMPLE +.CS +tk_optionMenu .foo myVar Foo Bar Boo Spong Wibble +pack .foo +.CE +.SH KEYWORDS +option menu diff --git a/doc/spinbox.n b/doc/spinbox.n index b45bbdc..78c5d81 100644 --- a/doc/spinbox.n +++ b/doc/spinbox.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: spinbox.n,v 1.7 2007/10/29 16:04:14 dkf Exp $ +'\" RCS: @(#) $Id: spinbox.n,v 1.8 2007/10/30 21:29:59 dkf Exp $ '\" .so man.macros .TH spinbox n 8.4 Tk "Tk Built-In Commands" @@ -114,7 +114,6 @@ size just large enough to hold its current text. Must be a proper boolean value. If on, the spinbox will wrap around the values of data in the widget. .BE - .SH DESCRIPTION .PP The \fBspinbox\fR command creates a new window (given by the @@ -147,7 +146,6 @@ may be used to change the view in the window. Spinboxes use the standard \fBxScrollCommand\fR mechanism for interacting with scrollbars (see the description of the \fBxScrollCommand\fR option for details). They also support scanning, as described below. - .SH VALIDATION .PP Validation works by setting the \fBvalidateCommand\fR @@ -220,7 +218,6 @@ in the \fBvalidateCommand\fR or \fBinvalidCommand\fR (whichever one you were editing the spinbox widget from). It is also recommended to not set an associated \fBtextVariable\fR during validation, as that can cause the spinbox widget to become out of sync with the \fBtextVariable\fR. - .SH "WIDGET COMMAND" .PP The \fBspinbox\fR command creates a new Tcl command whose @@ -231,6 +228,7 @@ operations on the widget. It has the following general form: .CE \fIOption\fR and the \fIarg\fRs determine the exact behavior of the command. +.SS INDICES .PP Many of the widget commands for spinboxes take one or more indices as arguments. An index specifies a particular character in the spinbox's @@ -275,6 +273,7 @@ or .QW \fBsel.f\fR . In general, out-of-range indices are automatically rounded to the nearest legal value. +.SS SUBCOMMANDS .PP The following commands are possible for spinbox widgets: .TP diff --git a/doc/text.n b/doc/text.n index d9f5cb0..05bfbee 100644 --- a/doc/text.n +++ b/doc/text.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: text.n,v 1.50 2007/10/30 19:39:26 hobbs Exp $ +'\" RCS: @(#) $Id: text.n,v 1.51 2007/10/30 21:29:59 dkf Exp $ '\" .so man.macros .TH text n 8.5 Tk "Tk Built-In Commands" @@ -115,9 +115,12 @@ at the tab position; if there is no decimal point then the least significant digit of the number is positioned just to the left of the tab position; if there is no number in the text then the text is right-justified at the tab position. -For example, \fB\-tabs {2c left 4c 6c center}\fR creates three -tab stops at two-centimeter intervals; the first two use left +For example, +.QW "\fB\-tabs {2c left 4c 6c center}\fR" +creates three tab stops at two-centimeter intervals; the first two use left justification and the third uses center justification. +.RS +.PP If the list of tab stops does not have enough elements to cover all of the tabs in a text line, then Tk extrapolates new tab stops using the spacing and alignment from the last tab stop in the list. Tab @@ -125,11 +128,13 @@ distances must be strictly positive, and must always increase from one tab stop to the next (if not, an error is thrown). The value of the \fBtabs\fR option may be overridden by \fB\-tabs\fR options in tags. +.PP If no \fB\-tabs\fR option is specified, or if it is specified as an empty list, then Tk uses default tabs spaced every eight (average size) characters. To achieve a different standard spacing, for example every 4 characters, simply configure the widget with .QW "\fB\-tabs \N'34'[expr {4 * [font measure $font 0]}] left\N'34' \-tabstyle wordprocessor\fR" . +.RE .OP \-tabstyle tabStyle TabStyle Specifies how to interpret the relationship between tab stops on a line and tabs in the text of that line. The value must be \fBtabular\fR (the @@ -1488,11 +1493,13 @@ arguments, and the section on \fIpathName \fBdelete\fR for an explanation of the handling of the indices. If \fIindex2\fR corresponds to an index earlier in the text than \fIindex1\fR, an error will be generated. -.br +.RS +.PP The deletion and insertion are arranged so that no unnecessary scrolling of the window or movement of insertion cursor occurs. In addition the undo/redo stack are correctly modified, if undo operations are active in the text widget. The command returns an empty string. +.RE .VE 8.5 .TP \fIpathName \fBscan\fR \fIoption args\fR diff --git a/doc/ttk_button.n b/doc/ttk_button.n index c2286a0..0a9215e 100644 --- a/doc/ttk_button.n +++ b/doc/ttk_button.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: ttk_button.n,v 1.7 2007/10/29 16:04:14 dkf Exp $ +'\" RCS: @(#) $Id: ttk_button.n,v 1.8 2007/10/30 21:29:59 dkf Exp $ '\" .so man.macros .TH ttk_button n 8.5 Tk "Tk Themed Widget" @@ -36,9 +36,11 @@ button (meaning, roughly, \fBnormal\fR means that it may become the default button, and \fBdisabled\fR means that it is not defaultable. The default is \fBnormal\fR. -.br +.RS +.PP Depending on the theme, the default button may be displayed with an extra highlight ring, or with a different border color. +.RE .OP \-width width Width If greater than zero, specifies how much space, in character widths, to allocate for the text label. diff --git a/doc/ttk_checkbutton.n b/doc/ttk_checkbutton.n index eee7d1e..ec28dcd 100644 --- a/doc/ttk_checkbutton.n +++ b/doc/ttk_checkbutton.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: ttk_checkbutton.n,v 1.8 2007/10/29 16:04:14 dkf Exp $ +'\" RCS: @(#) $Id: ttk_checkbutton.n,v 1.9 2007/10/30 21:29:59 dkf Exp $ '\" .so man.macros .TH ttk_checkbutton n 8.5 Tk "Tk Themed Widget" @@ -42,7 +42,7 @@ In addition to the standard commands, checkbuttons support the following additional widget commands: .TP -\fIpathname\fR invoke +\fIpathname\fB invoke\fR Toggles between the selected and deselected states and evaluates the associated \fB\-command\fR. If the widget is currently selected, sets the \fB\-variable\fR diff --git a/doc/ttk_menubutton.n b/doc/ttk_menubutton.n index 4796e0a..15b8f95 100644 --- a/doc/ttk_menubutton.n +++ b/doc/ttk_menubutton.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: ttk_menubutton.n,v 1.5 2007/10/26 20:13:23 dgp Exp $ +'\" RCS: @(#) $Id: ttk_menubutton.n,v 1.6 2007/10/30 21:29:59 dkf Exp $ '\" .so man.macros .TH ttk_menubutton n 8.5 Tk "Tk Themed Widget" @@ -15,7 +15,6 @@ ttk_menubutton \- Widget that pops down a menu when pressed .SH SYNOPSIS \fBttk::menubutton\fR \fIpathName \fR?\fIoptions\fR? .BE - .SH DESCRIPTION A \fBttk::menubutton\fR widget displays a textual label and/or image, and displays a menu when pressed. @@ -24,14 +23,13 @@ and displays a menu when pressed. \-state \-style \-takefocus \-text \-textvariable \-underline \-width .SE - .SH "WIDGET-SPECIFIC OPTIONS" .OP \-direction direction Direction Specifies where the menu is to be popped up relative to the menubutton. -One of: \fIabove\fR, \fIbelow\fR, \fIleft\fR, \fIright\fR, -or \fIflush\fR. The default is \fIbelow\fR. -\fIflush\fR pops the menu up directly over the menubutton. +One of: \fBabove\fR, \fBbelow\fR, \fBleft\fR, \fBright\fR, +or \fBflush\fR. The default is \fBbelow\fR. +\fBflush\fR pops the menu up directly over the menubutton. .OP \-menu menu Menu Specifies the path name of the menu associated with the menubutton. To be on the safe side, the menu ought to be a direct child of the @@ -39,14 +37,11 @@ menubutton. .\" not documented: may go away: .\" .OP \-anchor anchor Anchor .\" .OP \-padding padding Pad - .SH "WIDGET COMMAND" Menubutton widgets support the standard \fBcget\fR, \fBconfigure\fR, \fBinstate\fR, and \fBstate\fR methods. No other widget methods are used. - .SH "SEE ALSO" ttk_widget(n), menu(n), menubutton(n) - .SH "KEYWORDS" widget, button, menu diff --git a/doc/ttk_notebook.n b/doc/ttk_notebook.n index 5ed1e96..58c2332 100644 --- a/doc/ttk_notebook.n +++ b/doc/ttk_notebook.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: ttk_notebook.n,v 1.6 2007/10/29 16:04:14 dkf Exp $ +'\" RCS: @(#) $Id: ttk_notebook.n,v 1.7 2007/10/30 21:29:59 dkf Exp $ '\" .so man.macros .TH ttk_notebook n 8.5 Tk "Tk Themed Widget" @@ -13,10 +13,12 @@ .SH NAME ttk_notebook \- Multi-paned container widget .SH SYNOPSIS +.nf \fBttk::notebook\fR \fIpathName \fR?\fIoptions\fR? .br \fIpathName \fBadd\fR \fIpathName\fR.\fIsubwindow\fR ?\fIoptions...\fR? \fIpathName \fBinsert\fR \fIindex\fR \fIpathName\fR.\fIsubwindow\fR ?\fIoptions...\fR? +.fi .BE .SH DESCRIPTION A \fBttk::notebook\fR widget manages a collection of subpanes diff --git a/doc/ttk_panedwindow.n b/doc/ttk_panedwindow.n index 9976483..1e6793e 100644 --- a/doc/ttk_panedwindow.n +++ b/doc/ttk_panedwindow.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: ttk_panedwindow.n,v 1.10 2007/10/29 16:04:14 dkf Exp $ +'\" RCS: @(#) $Id: ttk_panedwindow.n,v 1.11 2007/10/30 21:29:59 dkf Exp $ '\" .so man.macros .TH ttk_panedwindow n 8.5 Tk "Tk Themed Widget" @@ -20,7 +20,6 @@ ttk_panedwindow \- Multi-pane container window \fIpathName \fBinsert\fR \fIindex\fR \fIpathName.subwindow\fR ?\fIoptions...\fR? .fi .BE - .SH DESCRIPTION A \fBttk::panedwindow\fR widget displays a number of subwindows, stacked either vertically or horizontally. The user may adjust the relative sizes @@ -28,7 +27,6 @@ of the subwindows by dragging the sash between panes. .SO \-class \-cursor \-takefocus \-style .SE - .SH "WIDGET-SPECIFIC OPTIONS" .OP \-orient orient Orient Specifies the orientation of the window. @@ -44,14 +42,12 @@ If present and greater than zero, specifies the desired height of the widget in pixels. Otherwise, the requested height is determined by the height of the managed windows. - .SH "PANE OPTIONS" The following options may be specified for each pane: .OP \-weight weight Weight An integer specifying the relative stretchability of the pane. When the paned window is resized, the extra space is added or subtracted to each pane proportionally to its \fB\-weight\fR. - .SH "WIDGET COMMAND" Supports the standard \fBconfigure\fR, \fBcget\fR, \fBstate\fR, and \fBinstate\fR commands; see \fIttk_widget(n)\fR for details. @@ -98,6 +94,5 @@ Returns the new position of sash number \fIindex\fR. \fIpathname\fR \fBidentify\fR \fIx y\fR Returns the index of the sash at point \fIx,y\fR, or the empty string if \fIx,y\fR is not over a sash. - .SH "SEE ALSO" ttk_widget(n), ttk_notebook(n), panedwindow(n) diff --git a/doc/ttk_radiobutton.n b/doc/ttk_radiobutton.n index 0fd9ec0..ee82390 100644 --- a/doc/ttk_radiobutton.n +++ b/doc/ttk_radiobutton.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: ttk_radiobutton.n,v 1.7 2007/10/29 16:04:14 dkf Exp $ +'\" RCS: @(#) $Id: ttk_radiobutton.n,v 1.8 2007/10/30 21:29:59 dkf Exp $ '\" .so man.macros .TH ttk_radiobutton n 8.5 Tk "Tk Themed Widget" @@ -41,7 +41,7 @@ In addition to the standard commands, radiobuttons support the following additional widget commands: .TP -\fIpathname\fR invoke +\fIpathname\fB invoke\fR Sets the \fB\-variable\fR to the \fB\-value\fR, selects the widget, and evaluates the associated \fB\-command\fR. Returns the result of the \fB\-command\fR, or the empty diff --git a/doc/ttk_scrollbar.n b/doc/ttk_scrollbar.n index 1724f2a..506ddec 100644 --- a/doc/ttk_scrollbar.n +++ b/doc/ttk_scrollbar.n @@ -6,7 +6,7 @@ '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" '\" SOURCE: tk/doc/scrollbar.n, r1.4 -'\" RCS: @(#) $Id: ttk_scrollbar.n,v 1.7 2007/10/29 16:04:14 dkf Exp $ +'\" RCS: @(#) $Id: ttk_scrollbar.n,v 1.8 2007/10/30 21:29:59 dkf Exp $ '\" .so man.macros .TH ttk_scrollbar n 8.5 Tk "Tk Themed Widget" @@ -37,11 +37,13 @@ to change the view in the widget associated with the scrollbar. Additional arguments are appended to the value of this option, as described in \fBSCROLLING COMMANDS\fR below, whenever the user requests a view change by manipulating the scrollbar. -.br +.RS +.PP This option typically consists of a two-element list, containing the name of a scrollable widget followed by either \fBxview\fR (for horizontal scrollbars) or \fByview\fR (for vertical scrollbars). +.RE .OP \-orient orient Orient One of \fBhorizontal\fR or \fBvertical\fR. Specifies the orientation of the scrollbar. diff --git a/doc/ttk_sizegrip.n b/doc/ttk_sizegrip.n index a300896..0b4e371 100644 --- a/doc/ttk_sizegrip.n +++ b/doc/ttk_sizegrip.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: ttk_sizegrip.n,v 1.11 2007/10/29 16:04:14 dkf Exp $ +'\" RCS: @(#) $Id: ttk_sizegrip.n,v 1.12 2007/10/30 21:29:59 dkf Exp $ '\" .so man.macros .TH ttk_sizegrip n 8.5 Tk "Tk Themed Widget" @@ -30,16 +30,16 @@ methods. No other widget methods are used. .SH "PLATFORM-SPECIFIC NOTES" On Mac OSX, toplevel windows automatically include a built-in size grip by default. -Adding an \fBttk::sizegrip\fR there is harmless, since +Adding a \fBttk::sizegrip\fR there is harmless, since the built-in grip will just mask the widget. .SH EXAMPLES .CS # Using pack: pack [ttk::frame $top.statusbar] \-side bottom \-fill x -pack [ttk::sizegrip $top.statusbar.grip] \-side right \-anchor se +pack [\fBttk::sizegrip\fR $top.statusbar.grip] \-side right \-anchor se # Using grid: -grid [ttk::sizegrip $top.statusbar.grip] \e +grid [\fBttk::sizegrip\fR $top.statusbar.grip] \e \-row $lastRow \-column $lastColumn \-sticky se # ... optional: add vertical scrollbar in $lastColumn, # ... optional: add horizontal scrollbar in $lastRow @@ -47,11 +47,13 @@ grid [ttk::sizegrip $top.statusbar.grip] \e .SH "BUGS" If the containing toplevel's position was specified relative to the right or bottom of the screen -(e.g., \fB[wm geometry ... \fIw\fBx\fIh\fB\-\fIx\fB\-\fIy\fB]\fR -instead of \fB[wm geometry ... \fIw\fBx\fIh\fB+\fIx\fB+\fIy\fB]\fR), +(e.g., +.QW "\fBwm geometry ... \fIw\fBx\fIh\fB\-\fIx\fB\-\fIy\fR" +instead of +.QW "\fBwm geometry ... \fIw\fBx\fIh\fB+\fIx\fB+\fIy\fR" ), the sizegrip widget will not resize the window. .PP -ttk::sizegrip widgets only support +\fBttk::sizegrip\fR widgets only support .QW southeast resizing. .SH "SEE ALSO" diff --git a/doc/ttk_style.n b/doc/ttk_style.n index 915aa0b..7520410 100644 --- a/doc/ttk_style.n +++ b/doc/ttk_style.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: ttk_style.n,v 1.7 2007/10/29 16:04:14 dkf Exp $ +'\" RCS: @(#) $Id: ttk_style.n,v 1.8 2007/10/30 21:29:59 dkf Exp $ '\" .so man.macros .TH ttk_style n 8.5 Tk "Tk Themed Widget" @@ -14,13 +14,11 @@ ttk_style \- Control overall look and feel of widgets .SH SYNOPSIS \fBttk::style\fR \fIoption\fR ?\fIargs\fR? .BE - .SH NOTES .PP This manpage has not been written yet. Please see the Tcl'2004 conference presentation, available at http://tktable.sourceforge.net/tile/tile-tcl2004.pdf - .SH DEFINITIONS .PP Each widget is assigned a \fIstyle\fR, @@ -35,10 +33,10 @@ which controls the overall look and feel of an application. .SH DESCRIPTION The \fBttk::style\fR command takes the following arguments: .TP -\fBttk::style configure \fIstyle\fR ?\fI\-option \fR?\fIvalue option value...\fR? ? +\fBttk::style configure \fIstyle\fR ?\fI\-option\fR? ?\fIvalue option value...\fR? Sets the default value of the specified option(s) in \fIstyle\fR. .TP -\fBttk::style map \fIstyle\fR ?\fI\-option\fR { \fIstatespec value\fR } ... ? +\fBttk::style map \fIstyle\fR ?\fI\-option\fB { \fIstatespec value\fB }\fR ... ? Sets dynamic values of the specified option(s) in \fIstyle\fR. Each \fIstatespec / value\fR pair is examined in order; the value corresponding to the first matching \fIstatespec\fR @@ -91,7 +89,6 @@ Returns a list of the available themes. .TP \fBttk::style theme use\fR \fIthemeName\fR Sets the current theme to \fIthemeName\fR, and refreshes all widgets. - .SH LAYOUTS A \fIlayout\fR specifies a list of elements, each followed by one or more options specifying how to arrange the element. @@ -105,10 +102,10 @@ Specifies which side of the cavity to place the element; one of \fBleft\fR, \fBright\fR, \fBtop\fR, or \fBbottom\fR. If omitted, the element occupies the entire cavity. .TP -\fB\-sticky \fI[nswe]\fR +\fB\-sticky [\fInswe\fB]\fR Specifies where the element is placed inside its allocated parcel. .TP -\fB\-children \fI{ sublayout... }\fR +\fB\-children {\fIsublayout... \fB}\fR Specifies a list of elements to place inside the element. .\" Also: -border, -unit, -expand: may go away. .PP @@ -122,9 +119,7 @@ ttk::style layout Horizontal.TScrollbar { } } .CE - .SH "SEE ALSO" ttk_intro(n), ttk_widget(n), photo(n) - .SH KEYWORDS style, theme, appearance diff --git a/doc/ttk_treeview.n b/doc/ttk_treeview.n index e5caf3b..ef3ad9f 100644 --- a/doc/ttk_treeview.n +++ b/doc/ttk_treeview.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: ttk_treeview.n,v 1.10 2007/10/29 16:04:14 dkf Exp $ +'\" RCS: @(#) $Id: ttk_treeview.n,v 1.11 2007/10/30 21:29:59 dkf Exp $ '\" .so man.macros .TH ttk_treeview n 8.5 Tk "Tk Themed Widget" @@ -14,7 +14,6 @@ ttk_treeview \- hierarchical multicolumn data display widget .SH SYNOPSIS \fBttk::treeview\fR \fIpathname \fR?\fIoptions\fR? .BE - .SH DESCRIPTION The \fBttk::treeview\fR widget displays a hierarchical collection of items. Each item has a textual label, an optional image, @@ -48,7 +47,6 @@ and [\fBxy\fR]\fBview\fR widget commands. \-class \-cursor \-takefocus \-style \-xscrollcommand \-yscrollcommand .SE - .SH "WIDGET-SPECIFIC OPTIONS" .OP \-columns columns Columns A list of column identifiers, @@ -60,8 +58,11 @@ A list of column identifiers specifying which data columns are displayed and the order in which they appear, or the string \fB#all\fP. -.br -If set to \fB#all\fP (the default), all columns are shown in the order given. +.RS +.PP +If set to \fB#all\fP (the default), all columns are shown in the order +given. +.RE .OP \-height height Height Specifies the number of rows which should be visible. Note: @@ -73,13 +74,15 @@ see \fBTtk_GetPaddingFromObj()\fR for details. .OP \-selectmode selectMode SelectMode Controls how the built-in class bindings manage the selection. One of \fBextended\fR, \fBbrowse\fR, or \fBnone\fR. -.br +.RS +.PP If set to \fBextended\fR (the default), multiple items may be selected. If \fBbrowse\fR, only a single item will be selected at a time. If \fBnone\fR, the selection will not be changed. -.br +.PP Note that application code and tag bindings can set the selection however they wish, regardless of the value of \fB\-selectmode\fR. +.RE .OP \-show show Show A list containing zero or more of the following values, specifying which elements of the tree to display. @@ -94,7 +97,6 @@ The default is \fBtree headings\fR, i.e., show all elements. \fBNOTE:\fR Column #0 always refers to the tree column, even if \fB\-show tree\fR is not specified. .RE - .SH "WIDGET COMMAND" .TP \fIpathname \fBbbox\fR \fIitem\fR ?\fIcolumn\fR? @@ -112,13 +114,15 @@ Returns the current value of the specified \fIoption\fR; see \fIttk_widget(n)\fR \fIpathname \fBchildren\fR \fIitem\fR ?\fInewchildren\fR? If \fInewchildren\fR is not specified, returns the list of children belonging to \fIitem\fR. -.br +.RS +.PP If \fInewchildren\fR is specified, replaces \fIitem\fR's child list with \fInewchildren\fR. Items in the old child list not present in the new child list are detached from the tree. None of the items in \fInewchildren\fR may be an ancestor of \fIitem\fR. +.RE .TP \fIpathname \fBcolumn\fR \fIcolumn\fR ?\fI\-option \fR?\fIvalue \-option value...\fR? Query or modify the options for the specified \fIcolumn\fR. @@ -240,10 +244,12 @@ it is inserted at the end. If \fB\-id\fR is specified, it is used as the item identifier; \fIid\fR must not already exist in the tree. Otherwise, a new unique identifier is generated. -.br +.RS +.PP \fIpathname \fBinsert\fR returns the item identifier of the newly created item. See \fBITEM OPTIONS\fR for the list of available options. +.RE .TP \fIpathname \fBinstate \fIstatespec\fR ?\fIscript\fR? Test the widget state; see \fIttk_widget(n)\fR. @@ -260,10 +266,12 @@ See \fBITEM OPTIONS\fR for the list of available options. \fIpathname \fBmove \fIitem parent index\fR Moves \fIitem\fR to position \fIindex\fR in \fIparent\fR's list of children. It is illegal to move an item under one of its descendants. -.br +.RS +.PP If \fIindex\fR is less than or equal to zero, \fIitem\fR is moved to the beginning; if greater than or equal to the number of children, -it's moved to the end. +it is moved to the end. +.RE .TP \fIpathname \fBnext \fIitem\fR Returns the identifier of \fIitem\fR's next sibling, @@ -301,7 +309,7 @@ Remove \fIitemList\fR from the selection Toggle the selection state of each item in \fIitemList\fR. .RE .TP -\fIpathname \fBset\fR \fIitem\fR ?\fIcolumn\fR ?\fIvalue\fR?? +\fIpathname \fBset\fR \fIitem\fR ?\fIcolumn\fR? ?\fIvalue\fR? With one argument, returns a dictionary of column/value pairs for the specified \fIitem\fR. With two arguments, returns the current value of the specified \fIcolumn\fR. @@ -315,20 +323,22 @@ Modify or query the widget state; see \fIttk_widget(n)\fR. \fIpathName \fBtag \fIargs...\fR .RS .TP -\fIpathName \fBtag bind \fItagName \fR?\fIsequence \fR?\fIscript\fR?? +\fIpathName \fBtag bind \fItagName \fR?\fIsequence\fR? ?\fIscript\fR? Add a Tk binding script for the event sequence \fIsequence\fR to the tag \fItagName\fR. When an X event is delivered to an item, binding scripts for each of the item's \fB\-tags\fR are evaluated in order as per \fIbindtags(n)\fR. -.br +.RS +.PP \fB\fR, \fB\fR, and virtual events are sent to the focus item. \fB\fR, \fB\fR, and \fB\fR events are sent to the item under the mouse pointer. No other event types are supported. -.br +.PP The binding \fIscript\fR undergoes \fB%\fR-substitutions before evaluation; see \fBbind(n)\fR for details. +.RE .TP \fIpathName \fBtag configure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? Query or modify the options for the specified \fItagName\fR. @@ -347,8 +357,6 @@ Standard command for horizontal scrolling; see \fIwidget(n)\fR. .TP \fIpathName \fByview \fIargs\fR Standard command for vertical scrolling; see \fIttk_widget(n)\fR. - -.PP .SH "ITEM OPTIONS" The following item options may be specified for items in the \fBinsert\fR and \fBitem\fR widget commands. @@ -358,13 +366,15 @@ The textual label to display for the item. A Tk image, displayed to the left of the label. .OP \-values values Values The list of values associated with the item. -.br +.RS +.PP Each item should have the same number of values as the \fB\-columns\fR widget option. If there are fewer values than columns, the remaining values are assumed empty. If there are more values than columns, the extra values are ignored. +.RE .OP \-open open Open A boolean value indicating whether the item's children should be displayed (\fB\-open true\fR) or hidden (\fB\-open false\fR). @@ -372,16 +382,16 @@ should be displayed (\fB\-open true\fR) or hidden (\fB\-open false\fR). A list of tags associated with this item. .SH "TAG OPTIONS" The following options may be specified on tags: -.IP \-foreground +.IP \fB\-foreground\fR Specifies the text foreground color. -.IP \-background +.IP \fB\-background\fR Specifies the cell or item background color. -.IP \-font +.IP \fB\-font\fR Specifies the font to use when drawing text. .\" ??? Maybe: .IP \-anchor .\" ??? Maybe: .IP \-padding .\" ??? Maybe: .IP \-text -.IP \-image +.IP \fB\-image\fR Specifies the item image, in case the item's \fB\-image\fR option is empty. .PP \fI(@@@ TODO: sort out order of precedence for options)\fR diff --git a/doc/ttk_widget.n b/doc/ttk_widget.n index f6cf9db..33448f7 100644 --- a/doc/ttk_widget.n +++ b/doc/ttk_widget.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: ttk_widget.n,v 1.9 2007/10/29 16:04:14 dkf Exp $ +'\" RCS: @(#) $Id: ttk_widget.n,v 1.10 2007/10/30 21:29:59 dkf Exp $ '\" .so man.macros .TH ttk_widget n 8.5 Tk "Tk Themed Widget" @@ -12,10 +12,8 @@ .SH NAME ttk_widget \- Standard options and commands supported by Tk themed widgets .BE - .SH DESCRIPTION This manual describes common widget options and commands. - .SH "STANDARD OPTIONS" The following options are supported by all Tk themed widgets: .OP \-class undefined undefined @@ -41,7 +39,6 @@ or the empty string. See \fIoptions(n)\fR in the Tk reference manual for the full description. .OP \-style style Style May be used to specify a custom widget style. - .SH "SCROLLABLE WIDGET OPTIONS" .PP The following options are supported by widgets that @@ -49,7 +46,8 @@ are controllable by a scrollbar. See \fIscrollbar(n)\fR for more information .OP \-xscrollcommand xScrollCommand ScrollCommand A command prefix, used to communicate with horizontal scrollbars. -.br +.RS +.PP When the view in the widget's window changes, the widget will generate a Tcl command by concatenating the scroll command and two numbers. @@ -59,7 +57,7 @@ and 1 indicates the end. The first fraction indicates the first information in the widget that is visible in the window, and the second fraction indicates the information just after the last portion that is visible. -.br +.PP Typically the \fBxScrollCommand\fR option consists of the path name of a \fBscrollbar\fR widget followed by .QW set , @@ -67,13 +65,13 @@ e.g. .QW ".x.scrollbar set" . This will cause the scrollbar to be updated whenever the view in the window changes. -.br +.PP If this option is set to the empty string (the default), then no command is be executed. +.RE .OP \-yscrollcommand yScrollCommand ScrollCommand A command prefix, used to communicate with vertical scrollbars. See the description of \fB\-xscrollcommand\fR above for details. - .SH "LABEL OPTIONS" The following options are supported by labels, buttons, and other button-like widgets: @@ -234,13 +232,13 @@ indicating that the bit is off. set b [ttk::button .b] # Disable the widget: -$b state disabled +$b state disabled # Invoke the widget only if it is currently pressed and enabled: -$b instate {pressed !disabled} { .b invoke } +$b instate {pressed !disabled} { .b invoke } # Reenable widget: -$b state !disabled +$b state !disabled .CE .SH "SEE ALSO" ttk_intro(n), style(n) diff --git a/doc/wm.n b/doc/wm.n index 93b8011..fb5467e 100644 --- a/doc/wm.n +++ b/doc/wm.n @@ -5,7 +5,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: wm.n,v 1.35 2007/10/29 16:04:14 dkf Exp $ +'\" RCS: @(#) $Id: wm.n,v 1.36 2007/10/30 21:29:59 dkf Exp $ '\" .so man.macros .TH wm n 8.5 Tk "Tk Built-In Commands" @@ -54,42 +54,51 @@ with a window. The first form returns a list of the platform specific flags and their values. The second form returns the value for the specific option. The third form sets one or more of the values. The values are as follows: -.PP -On Windows, the following attributes may be set. .RS +.PP +All platforms support the following attributes (though X11 users +should see the notes below): .TP -\fB\-disabled\fR -Specifies whether the window is in a disabled state. -.TP -\fB\-toolwindow\fR -Specifies a toolwindow style window (as defined in the MSDN). +\fB\-fullscreen\fR +Places the window in a mode that takes up the entire screen, has no +borders, and covers the general use area (i.e. Start menu and taskbar on +Windows, dock and menubar on OSX, general window decorations on X11). .TP \fB\-topmost\fR Specifies whether this is a topmost window (displays above all other windows). -.VS 8.5 +.PP +On Windows, the following attributes may be set. .TP \fB\-alpha\fR +.VS 8.5 Specifies the alpha transparency level of the toplevel. It accepts a value from \fB0.0\fR (fully transparent) to \fB1.0\fR (opaque). Values outside that range will be constrained. This is supported on Windows 2000/XP+. Where not supported, the \fB\-alpha\fR value remains at \fB1.0\fR. +.VE 8.5 +.TP +\fB\-disabled\fR +Specifies whether the window is in a disabled state. +.TP +\fB\-toolwindow\fR +Specifies a toolwindow style window (as defined in the MSDN). .TP \fB\-transparentcolor\fR +.VS 8.5 Specifies the transparent color index of the toplevel. It takes any color value accepted by \fBTk_GetColor\fR. If the empty string is specified (default), no transparent color is used. This is supported on Windows 2000/XP+. Where not supported, the \fB\-transparentcolor\fR value remains at \fB{}\fR. -.TP -\fB\-fullscreen\fR -Places the window in a mode that takes up the entire screen, has no -borders, and covers the Start menu and taskbar. -.RE .VE 8.5 .PP On Mac OS X, the following attributes may be set. -.RS +.TP +\fB\-alpha\fR +Specifies the alpha transparency level of the window. +It accepts a value from \fB0.0\fR (fully transparent) to \fB1.0\fR (opaque), +values outside that range will be constrained. .TP \fB\-modified\fR Specifies the modification state of the window (determines whether the @@ -100,50 +109,27 @@ proxy icon is draggable). Specifies the path of the file referenced as the window proxy icon (which can be dragged and dropped in lieu of the file's finder icon). .TP -\fB\-alpha\fR -Specifies the alpha transparency level of the window. -It accepts a value from \fB0.0\fR (fully transparent) to \fB1.0\fR (opaque), -values outside that range will be constrained. -.TP -\fB\-topmost\fR -Specifies whether this is a topmost window (displays above all other windows). -.TP \fB\-transparent\fR Makes the window content area transparent and turns off the window shadow. For the transparency to be effecive, the toplevel background needs to be set to a color with some alpha, e.g. .QW systemTransparent . -.TP -\fB\-fullscreen\fR -Places the window in a mode that takes up the entire main screen and hides -the dock and menu bar. -.RE .PP On X11, the following attributes may be set. These are not supported by all window managers, and will have no effect under older WMs. .\" See http://www.freedesktop.org/Standards/wm-spec -.RS -.TP -\fB\-topmost\fR -Requests that this window should be kept above -all other windows that do not also have the \fB\-topmost\fR -attribute set. .TP \fB\-zoomed\fR Requests that the window should be maximized. This is the same as \fBwm state zoomed\fR on Windows and Mac OS X. -.TP -\fB\-fullscreen\fR -Requests that the window should fill the entire screen -and have no window decorations. -.RE .PP On X11, changes to window attributes are performed asynchronously. Querying the value of an attribute returns the current state, which will not be the same as the value most recently set if the window manager has not yet processed the request or if it does not support the attribute. +.RE .TP \fBwm client \fIwindow\fR ?\fIname\fR? If \fIname\fR is specified, this command stores \fIname\fR (which @@ -161,6 +147,8 @@ If \fIname\fR is specified as an empty string, the command deletes the This command is used to manipulate the \fBWM_COLORMAP_WINDOWS\fR property, which provides information to the window managers about windows that have private colormaps. +.RS +.PP If \fIwindowList\fR is not specified, the command returns a list whose elements are the names of the windows in the \fBWM_COLORMAP_WINDOWS\fR property. @@ -170,6 +158,7 @@ property with the given windows and returns an empty string. The \fBWM_COLORMAP_WINDOWS\fR property should normally contain a list of the internal windows within \fIwindow\fR whose colormaps differ from their parents. +.PP The order of the windows in the property indicates a priority order: the window manager will attempt to install as many colormaps as possible from the head of this list when \fIwindow\fR gets the colormap focus. @@ -182,6 +171,7 @@ whose colormaps differ from their parents, followed by the top-level itself; the order of the internal windows is undefined. See the ICCCM documentation for more information on the \fBWM_COLORMAP_WINDOWS\fR property. +.RE .TP \fBwm command \fIwindow\fR ?\fIvalue\fR? If \fIvalue\fR is specified, this command stores \fIvalue\fR in \fIwindow\fR's @@ -209,6 +199,8 @@ to the command, then it specifies the focus model for \fIwindow\fR. In this case the command returns an empty string. If no additional argument is supplied, then the command returns the current focus model for \fIwindow\fR. +.RS +.PP An \fBactive\fR focus model means that \fIwindow\fR will claim the input focus for itself or its descendants, even at times when the focus is currently in some other application. \fBPassive\fR means that @@ -218,6 +210,7 @@ once the focus has been given to \fIwindow\fR or one of its descendants, the application may re-assign the focus among \fIwindow\fR's descendants. The focus model defaults to \fBpassive\fR, and Tk's \fBfocus\fR command assumes a passive model of focusing. +.RE .TP \fBwm forget \fIwindow\fR The \fIwindow\fR will be unmapped from the screen and will no longer @@ -246,7 +239,10 @@ may be omitted. \fIWidth\fR and \fIheight\fR are positive integers specifying the desired dimensions of \fIwindow\fR. If \fIwindow\fR is gridded (see \fBGRIDDED GEOMETRY MANAGEMENT\fR below) then the dimensions are specified in grid units; otherwise they are specified in pixel -units. \fIX\fR and \fIy\fR specify the desired location of +units. +.RS +.PP +\fIX\fR and \fIy\fR specify the desired location of \fIwindow\fR on the screen, in pixels. If \fIx\fR is preceded by \fB+\fR, it specifies the number of pixels between the left edge of the screen and the left @@ -258,10 +254,12 @@ number of pixels between the top of the screen and the top of \fIwindow\fR's border; if \fIy\fR is preceded by \fB\-\fR then it specifies the number of pixels between the bottom of \fIwindow\fR's border and the bottom of the screen. +.PP If \fInewGeometry\fR is specified as an empty string then any existing user-specified geometry for \fIwindow\fR is cancelled, and the window will revert to the size requested internally by its widgets. +.RE .TP \fBwm grid \fIwindow\fR ?\fIbaseWidth baseHeight widthInc heightInc\fR? This command indicates that \fIwindow\fR is to be managed as a @@ -278,20 +276,25 @@ that are non-negative integers. Tk will pass this information to the window manager; during manual resizing, the window manager will restrict the window's size to one of these acceptable sizes. +.RS +.PP Furthermore, during manual resizing the window manager will display the window's current size in terms of grid units rather than pixels. If \fIbaseWidth\fR etc. are all specified as empty strings, then \fIwindow\fR will no longer be managed as a gridded window. If \fIbaseWidth\fR etc. are specified then the return value is an empty string. +.PP Otherwise the return value is a Tcl list containing four elements corresponding to the current \fIbaseWidth\fR, \fIbaseHeight\fR, \fIwidthInc\fR, and \fIheightInc\fR; if \fIwindow\fR is not currently gridded, then an empty string is returned. +.PP Note: this command should not be needed very often, since the \fBTk_SetGrid\fR library procedure and the \fBsetGrid\fR option provide easier access to the same functionality. +.RE .TP \fBwm group \fIwindow\fR ?\fIpathName\fR? If \fIpathName\fR is specified, it gives the path name for the leader of @@ -315,7 +318,9 @@ Otherwise it returns the name of the current icon bitmap associated with \fIwindow\fR, or an empty string if \fIwindow\fR has no icon bitmap. On the Windows operating system, an additional flag is supported: -\fBwm iconbitmap \fIwindow\fR ?\fB\-default\fR? ?\fIimage\fR?. +.RS +.TP +\fBwm iconbitmap \fIwindow\fR ?\fB\-default\fR? ?\fIimage\fR? If the \fB\-default\fR flag is given, the icon is applied to all toplevel windows (existing and future) to which no other specific icon has yet been applied. @@ -326,6 +331,7 @@ file for which the shell has assigned an icon. Tcl will first test if the file contains an icon, then if it has an assigned icon, and finally, if that fails, test for a bitmap. +.RE .TP \fBwm iconify \fIwindow\fR Arrange for \fIwindow\fR to be iconified. It \fIwindow\fR has not @@ -358,7 +364,6 @@ as specified with the \fBwm title\fR command). .VS 8.5 .TP \fBwm iconphoto \fIwindow\fR ?\fB\-default\fR? \fIimage1\fR ?\fIimage2 ...\fR? -.RS Sets the titlebar icon for \fIwindow\fR based on the named photo images. If \fB\-default\fR is specified, this is applied to all future created toplevels as well. The data in the images is taken as a snapshot at the @@ -366,6 +371,7 @@ time of invocation. If the images are later changed, this is not reflected to the titlebar icons. Multiple images are accepted to allow different images sizes (e.g., 16x16 and 32x32) to be provided. The window manager may scale provided icons to an appropriate size. +.RS .PP On Windows, the images are packed into a Windows icon structure. This will override an ico specified to \fBwm iconbitmap\fR, and @@ -535,16 +541,16 @@ no source has been specified yet. Most window managers interpret .QW "no source" as equivalent to \fBprogram\fR. .TP -\fBwm stackorder \fIwindow\fR ?\fIisabove|isbelow window\fR? -The stackorder command returns a list of toplevel windows +\fBwm stackorder \fIwindow\fR ?\fBisabove\fR|\fBisbelow \fIwindow\fR? +The \fBstackorder\fR command returns a list of toplevel windows in stacking order, from lowest to highest. When a single toplevel window is passed, the returned list recursively includes all of the window's children that are toplevels. Only those toplevels that are currently mapped to the screen are returned. -The stackorder command can also be used to determine if one +The \fBstackorder\fR command can also be used to determine if one toplevel is positioned above or below a second toplevel. -When two window arguments separated by either \fIisabove\fR or -\fIisbelow\fR are passed, a boolean result indicates whether +When two window arguments separated by either \fBisabove\fR or +\fBisbelow\fR are passed, a boolean result indicates whether or not the first window is currently above or below the second window in the stacking order. .TP -- cgit v0.12