diff options
| -rw-r--r-- | doc/chooseDirectory.n | 4 | ||||
| -rw-r--r-- | doc/clipboard.n | 4 | ||||
| -rw-r--r-- | doc/dialog.n | 4 | ||||
| -rw-r--r-- | doc/font.n | 4 | ||||
| -rw-r--r-- | doc/labelframe.n | 8 | ||||
| -rw-r--r-- | doc/ttk_combobox.n | 82 | ||||
| -rw-r--r-- | doc/ttk_image.n | 78 | ||||
| -rw-r--r-- | doc/ttk_intro.n | 150 | ||||
| -rw-r--r-- | doc/ttk_panedwindow.n | 97 | ||||
| -rw-r--r-- | doc/ttk_progressbar.n | 74 | ||||
| -rw-r--r-- | doc/ttk_scrollbar.n | 162 | ||||
| -rw-r--r-- | doc/ttk_sizegrip.n | 6 | ||||
| -rw-r--r-- | doc/ttk_treeview.n | 461 | ||||
| -rw-r--r-- | doc/ttk_widget.n | 239 |
14 files changed, 674 insertions, 699 deletions
diff --git a/doc/chooseDirectory.n b/doc/chooseDirectory.n index 32f9166..e0e2d90 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.4 2004/10/28 10:22:51 dkf Exp $ +'\" RCS: @(#) $Id: chooseDirectory.n,v 1.5 2007/10/22 14:33:13 dkf Exp $ '\" .so man.macros .TH tk_chooseDirectory n 8.3 Tk "Tk Built-In Commands" @@ -45,7 +45,7 @@ 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 \\ +set dir [\fBtk_chooseDirectory\fR \e \-initialdir ~ \-title "Choose a directory"] if {$dir eq ""} { label .l -text "No directory selected" diff --git a/doc/clipboard.n b/doc/clipboard.n index 18e6c54..0341d62 100644 --- a/doc/clipboard.n +++ b/doc/clipboard.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: clipboard.n,v 1.11 2005/08/04 10:01:59 dkf Exp $ +'\" RCS: @(#) $Id: clipboard.n,v 1.12 2007/10/22 14:33:13 dkf Exp $ '\" .so man.macros .TH clipboard n 8.4 Tk "Tk Built-In Commands" @@ -125,7 +125,7 @@ pack $c $c create text 150 30 -text "cut and paste me" bind $c <<Cut>> { \fBclipboard clear\fR - \fBclipboard append -type\fR TkCanvasItem \\ + \fBclipboard append -type\fR TkCanvasItem \e [getItemConfig %W current] # Delete because this is cut, not copy. %W delete current diff --git a/doc/dialog.n b/doc/dialog.n index 269726a..9b7effa 100644 --- a/doc/dialog.n +++ b/doc/dialog.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: dialog.n,v 1.3 2004/06/21 14:28:56 dkf Exp $ +'\" RCS: @(#) $Id: dialog.n,v 1.4 2007/10/22 14:33:13 dkf Exp $ '\" .so man.macros .TH tk_dialog n 4.1 Tk "Tk Built-In Commands" @@ -62,7 +62,7 @@ grab. This prevents the user from interacting with the application in any way except to invoke the dialog box. .SH EXAMPLE .CS -set reply [\fBtk_dialog\fR .foo "The Title" "Do you want to say yes?" \\ +set reply [\fBtk_dialog\fR .foo "The Title" "Do you want to say yes?" \e questhead 0 Yes No "I'm not sure"] .CE @@ -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: font.n,v 1.11 2007/05/03 23:55:29 dkf Exp $ +'\" RCS: @(#) $Id: font.n,v 1.12 2007/10/22 14:33:13 dkf Exp $ '\" .so man.macros .TH font n 8.0 Tk "Tk Built-In Commands" @@ -291,7 +291,7 @@ set count 0 set tabwidth 0 foreach family [lsort -dictionary [\fBfont families\fR]] { .t tag configure f[incr count] -font [list $family 10] - .t insert end ${family}:\\t {} \\ + .t insert end ${family}:\\t {} \e "This is a simple sampler\\n" f$count set w [\fBfont measure\fR [.t cget -font] ${family}:] if {$w+5 > $tabwidth} { diff --git a/doc/labelframe.n b/doc/labelframe.n index 2937893..07a2647 100644 --- a/doc/labelframe.n +++ b/doc/labelframe.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: labelframe.n,v 1.3 2006/12/13 23:04:32 hobbs Exp $ +'\" RCS: @(#) $Id: labelframe.n,v 1.4 2007/10/22 14:33:13 dkf Exp $ '\" .so man.macros .TH labelframe n 8.4 Tk "Tk Built-In Commands" @@ -143,9 +143,9 @@ This shows how to build part of a GUI for a hamburger vendor. The the kinds of things that the choices are being made over. .PP .CS -grid [\fBlabelframe\fR .burger -text "Burger"] \\ +grid [\fBlabelframe\fR .burger -text "Burger"] \e [\fBlabelframe\fR .bun -text "Bun"] -sticky news -grid [\fBlabelframe\fR .cheese -text "Cheese Option"] \\ +grid [\fBlabelframe\fR .cheese -text "Cheese Option"] \e [\fBlabelframe\fR .pickle -text "Pickle Option"] -sticky news foreach {type name val} { burger Beef beef @@ -168,7 +168,7 @@ foreach {type name val} { pickle Onions onion pickle Chili chili } { - set w [radiobutton .$type.$val -text $name -anchor w \\ + set w [radiobutton .$type.$val -text $name -anchor w \e -variable $type -value $val] pack $w -side top -fill x } diff --git a/doc/ttk_combobox.n b/doc/ttk_combobox.n index 85b2a24..598ea0f 100644 --- a/doc/ttk_combobox.n +++ b/doc/ttk_combobox.n @@ -3,8 +3,8 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: ttk_combobox.n,v 1.5 2007/08/28 15:16:11 dkf Exp $ +'\" +'\" RCS: @(#) $Id: ttk_combobox.n,v 1.6 2007/10/22 14:33:13 dkf Exp $ '\" .so man.macros .TH ttk_combobox n 8.5 Tk "Tk Themed Widget" @@ -18,8 +18,8 @@ ttk_combobox \- text field with popdown selection list .SH DESCRIPTION A \fBttk::combobox\fR combines a text field with a pop-down list of values; -the user may select the value of the text field from among the -values in the list. +the user may select the value of the text field from among the values in the +list. .SO \-class \-cursor \-takefocus \-style .SE @@ -27,30 +27,25 @@ values in the list. .SH "WIDGET-SPECIFIC OPTIONS" .OP \-exportselection exportSelection ExportSelection -Boolean value. -If set, the widget selection is linked to the X selection. +Boolean value. If set, the widget selection is linked to the X selection. .OP \-justify justify Justify -Specifies how the text is aligned within the widget. -One of \fBleft\fR, \fBcenter\fR, or \fBright\fR. +Specifies how the text is aligned within the widget. One of \fBleft\fR, +\fBcenter\fR, or \fBright\fR. .OP \-height height Height Specifies the height of the pop-down listbox, in rows. .OP \-postcommand postCommand PostCommand -A Tcl script to evaluate immediately before displaying the listbox. -The \fB-postcommand\fR script may specify the \fB-values\fR to display. +A Tcl script to evaluate immediately before displaying the listbox. The +\fB\-postcommand\fR script may specify the \fB\-values\fR to display. .OP \-state state State -One of \fBnormal\fR, \fBreadonly\fR, or \fBdisabled\fR. -In the \fBreadonly\fR state, -the value may not be edited directly, and -the user can only select one of the \fB-values\fR from the -dropdown list. -In the \fBnormal\fR state, -the text field is directly editable. -In the \fBdisabled\fR state, no interaction is possible. +One of \fBnormal\fR, \fBreadonly\fR, or \fBdisabled\fR. In the \fBreadonly\fR +state, the value may not be edited directly, and the user can only select one +of the \fB\-values\fR from the dropdown list. In the \fBnormal\fR state, the +text field is directly editable. In the \fBdisabled\fR state, no interaction +is possible. .OP \-textvariable textVariable TextVariable -Specifies the name of a variable whose value is linked -to the widget value. -Whenever the variable changes value the widget value is updated, -and vice versa. +Specifies the name of a variable whose value is linked to the widget value. +Whenever the variable changes value the widget value is updated, and vice +versa. .OP \-values values Values Specifies the list of values to display in the drop-down listbox. .OP \-width width Width @@ -61,39 +56,44 @@ in average-size characters of the widget's font. .SH "WIDGET COMMAND" .TP \fIpathName \fBcget\fR \fIoption\fR -Returns the current value of the specified \fIoption\fR. -See \fIttk_widget(n)\fR. +. +Returns the current value of the specified \fIoption\fR. See +\fIttk_widget(n)\fR. .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -Modify or query widget options. -See \fIttk_widget(n)\fR. +. +Modify or query widget options. See \fIttk_widget(n)\fR. .TP \fIpathName \fBcurrent\fR ?\fInewIndex\fR? -If \fInewIndex\fR is supplied, sets the combobox value -to the element at position \fInewIndex\fR in the list of \fB-values\fR. -Otherwise, returns the index of the current value in the list of \fB-values\fR -or \fB-1\fR if the current value does not appear in the list. +. +If \fInewIndex\fR is supplied, sets the combobox value to the element at +position \fInewIndex\fR in the list of \fB\-values\fR. Otherwise, returns the +index of the current value in the list of \fB\-values\fR or \fB\-1\fR if the +current value does not appear in the list. .TP \fIpathName \fBget\fR +. Returns the current value of the combobox. .TP \fIpathName \fBidentify \fIx y\fR -Returns the name of the element at position \fIx\fR, \fIy\fR, -or the empty string if the coordinates are outside the window. +. +Returns the name of the element at position \fIx\fR, \fIy\fR, or the empty +string if the coordinates are outside the window. .TP \fIpathName \fBinstate \fIstateSpec\fR ?\fIscript\fR? -Test the widget state. -See \fIttk_widget(n)\fR. +. +Test the widget state. See \fIttk_widget(n)\fR. .TP \fIpathName \fBset\fR \fIvalue\fR +. Sets the value of the combobox to \fIvalue\fR. .TP \fIpathName \fBstate\fR ?\fIstateSpec\fR? -Modify or query the widget state. -See \fIttk_widget(n)\fR. +. +Modify or query the widget state. See \fIttk_widget(n)\fR. .PP -The combobox widget also supports the following \fIttk::entry\fR -widget commands (see \fIttk_entry(n)\fR for details): +The combobox widget also supports the following \fIttk::entry\fR widget +commands (see \fIttk_entry(n)\fR for details): .DS .ta 5.5c 11c bbox delete icursor @@ -102,9 +102,9 @@ xview .DE .SH "VIRTUAL EVENTS" -The combobox widget generates a \fB<<ComboboxSelected>>\fR virtual event -when the user selects an element from the list of values. -This event is generated after the listbox is unposted. +The combobox widget generates a \fB<<ComboboxSelected>>\fR virtual event when +the user selects an element from the list of values. This event is generated +after the listbox is unposted. .SH "SEE ALSO" ttk_widget(n), ttk_entry(n) diff --git a/doc/ttk_image.n b/doc/ttk_image.n index 26034cf..c308533 100644 --- a/doc/ttk_image.n +++ b/doc/ttk_image.n @@ -3,9 +3,9 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: ttk_image.n,v 1.6 2007/04/23 21:19:51 das Exp $ -'\" +'\" +'\" RCS: @(#) $Id: ttk_image.n,v 1.7 2007/10/22 14:33:13 dkf Exp $ +'\" .so man.macros .TH ttk_image n 8.5 Tk "Tk Themed Widget" .BS @@ -16,50 +16,50 @@ ttk_image \- Define an element based on an image .BE .SH DESCRIPTION -The \fIimage\fR element factory creates a new element -in the current theme whose visual appearance is determined -by Tk images. -\fIimageSpec\fP is a list of one or more elements. -The first element is the default image name. -The rest of the list is a sequence of \fIstatespec / value\fR -pairs specifying other images to use when the element is -in a particular state or combination of states. +The \fIimage\fR element factory creates a new element in the current theme +whose visual appearance is determined by Tk images. \fIimageSpec\fP is a list +of one or more elements. The first element is the default image name. The rest +of the list is a sequence of \fIstatespec / value\fR pairs specifying other +images to use when the element is in a particular state or combination of +states. .SH OPTIONS Valid \fIoptions\fR are: .TP -\fB-border\fR \fIpadding\fR -\fIpadding\fR is a list of up to four integers, specifying -the left, top, right, and bottom borders, respectively. -See \fBIMAGE STRETCHING\fR, below. +\fB\-border\fR \fIpadding\fR +. +\fIpadding\fR is a list of up to four integers, specifying the left, top, +right, and bottom borders, respectively. See \fBIMAGE STRETCHING\fR, below. .TP -\fB-height \fIheight\fR -Specifies a minimum height for the element. -If less than zero, the base image's height is used as a default. +\fB\-height \fIheight\fR +. +Specifies a minimum height for the element. If less than zero, the base +image's height is used as a default. .TP -\fB-padding\fR \fIpadding\fR -Specifies the element's interior padding. Defaults to -\fI-border\fR if not specified. +\fB\-padding\fR \fIpadding\fR +. +Specifies the element's interior padding. Defaults to \fI\-border\fR if not +specified. .TP -\fB-sticky\fR \fIspec\fR -Specifies how the image is placed within the final parcel. -\fIspec\fR contains zero or more characters "n", "s", "w", or "e". +\fB\-sticky\fR \fIspec\fR +. +Specifies how the image is placed within the final parcel. \fIspec\fR contains +zero or more characters "n", "s", "w", or "e". .TP -\fB-width \fIwidth\fR -Specifies a minimum width for the element. -If less than zero, the base image's width is used as a default. +\fB\-width \fIwidth\fR +. +Specifies a minimum width for the element. If less than zero, the base image's +width is used as a default. .SH "IMAGE STRETCHING" -If the element's allocated parcel is larger than the image, -the image will be placed in the parcel based on the \fB-sticky\fR option. -If the image needs to stretch horizontally (i.e., \fB-sticky ew\fR) -or vertically (\fB-sticky ns\fR), -subregions of the image are replicated to fill the parcel -based on the \fB-border\fR option. -The \fB-border\fR divides the image into 9 regions: -four fixed corners, top and left edges (which may be tiled horizontally), -left and right edges (which may be tiled vertically), -and the central area (which may be tiled in both directions). +If the element's allocated parcel is larger than the image, the image will be +placed in the parcel based on the \fB\-sticky\fR option. If the image needs to +stretch horizontally (i.e., \fB\-sticky ew\fR) or vertically (\fB\-sticky +ns\fR), subregions of the image are replicated to fill the parcel based on the +\fB\-border\fR option. The \fB\-border\fR divides the image into 9 regions: +four fixed corners, top and left edges (which may be tiled horizontally), left +and right edges (which may be tiled vertically), and the central area (which +may be tiled in both directions). .SH "EXAMPLE" .CS @@ -67,8 +67,8 @@ set img1 [image create photo -file button.png] set img2 [image create photo -file button-pressed.png] set img3 [image create photo -file button-active.png] style element create Button.button image \e - [list $img1 pressed $img2 active $img3] \e - -border {2 4} -sticky we + [list $img1 pressed $img2 active $img3] \e + -border {2 4} -sticky we .CE .SH "SEE ALSO" diff --git a/doc/ttk_intro.n b/doc/ttk_intro.n index 2ee1944..38afd18 100644 --- a/doc/ttk_intro.n +++ b/doc/ttk_intro.n @@ -3,9 +3,9 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: ttk_intro.n,v 1.3 2006/12/13 23:04:33 hobbs Exp $ -'\" +'\" +'\" RCS: @(#) $Id: ttk_intro.n,v 1.4 2007/10/22 14:33:13 dkf Exp $ +'\" .so man.macros .TH ttk_intro n 8.5 Tk "Tk Themed Widget" .BS @@ -14,20 +14,16 @@ ttk_intro \- Introduction to the Tk theme engine .BE .SH "OVERVIEW" -The Tk themed widget set is based on a revised and enhanced version -of TIP #48 (http://tip.tcl.tk/48) specified style engine. -The main concepts are described below. -The basic idea is to separate, to the extent possible, -the code implementing a widget's behavior from -the code implementing its appearance. -Widget class bindings are primarily responsible for -maintaining the widget state and invoking callbacks; -all aspects of the widgets appearance is +The Tk themed widget set is based on a revised and enhanced version of TIP #48 +(http://tip.tcl.tk/48) specified style engine. The main concepts are described +below. The basic idea is to separate, to the extent possible, the code +implementing a widget's behavior from the code implementing its appearance. +Widget class bindings are primarily responsible for maintaining the widget +state and invoking callbacks; all aspects of the widgets appearance is .SH "THEMES" -A \fItheme\fR is a collection of elements and styles -that determine the look and feel of the widget set. -Themes can be used to: +A \fItheme\fR is a collection of elements and styles that determine the look +and feel of the widget set. Themes can be used to: .IP \(bu Isolate platform differences (X11 vs. classic Windows vs. XP vs. Aqua ...) .IP \(bu @@ -42,26 +38,22 @@ Blend in with the rest of the desktop (Gnome, KDE, Java) And, of course: eye candy. .SH "ELEMENTS" -An \fIelement\fR displays an individual part of a widget. -For example, a vertical scrollbar widget contains \fBuparrow\fR, -\fBdownarrow\fR, \fBtrough\fR and \fBslider\fR elements. +An \fIelement\fR displays an individual part of a widget. For example, a +vertical scrollbar widget contains \fBuparrow\fR, \fBdownarrow\fR, +\fBtrough\fR and \fBslider\fR elements. .PP -Element names use a recursive dotted notation. -For example, \fBuparrow\fR identifies a generic arrow element, -and \fBScrollbar.arrow\fR and \fBCombobox.uparrow\fR identify -widget-specific elements. -When looking for an element, the style engine looks for -the specific name first, and if an element of that name is -not found it looks for generic elements by stripping off +Element names use a recursive dotted notation. For example, \fBuparrow\fR +identifies a generic arrow element, and \fBScrollbar.arrow\fR and +\fBCombobox.uparrow\fR identify widget-specific elements. When looking for an +element, the style engine looks for the specific name first, and if an element +of that name is not found it looks for generic elements by stripping off successive leading components of the element name. .PP -Like widgets, elements have \fIoptions\fR which -specify what to display and how to display it. -For example, the \fBtext\fR element -(which displays a text string) has -\fB-text\fR, \fB-font\fR, \fB-foreground\fR, \fB-background\fR, -\fB-underline\fR, and \fB-width\fR options. -The value of an element resource is taken from: +Like widgets, elements have \fIoptions\fR which specify what to display and +how to display it. For example, the \fBtext\fR element (which displays a text +string) has \fB\-text\fR, \fB\-font\fR, \fB\-foreground\fR, +\fB\-background\fR, \fB\-underline\fR, and \fB\-width\fR options. The value of +an element resource is taken from: .IP \(bu A dynamic setting specified by \fBstyle map\fR and the current state; .IP \(bu @@ -71,15 +63,12 @@ The default setting specified by \fBstyle default\fR; or .IP \(bu The element's built-in default value for the resource. .SH "LAYOUTS" -A \fIlayout\fR specifies which elements make up a widget -and how they are arranged. -The layout engine uses a simplified version of the \fBpack\fR -algorithm: starting with an initial cavity equal to the size -of the widget, elements are allocated a parcel within the cavity along -the side specified by the \fB-side\fR option, -and placed within the parcel according to the \fB-sticky\fR -option. -For example, the layout for a horizontal scrollbar +A \fIlayout\fR specifies which elements make up a widget and how they are +arranged. The layout engine uses a simplified version of the \fBpack\fR +algorithm: starting with an initial cavity equal to the size of the widget, +elements are allocated a parcel within the cavity along the side specified by +the \fB\-side\fR option, and placed within the parcel according to the +\fB\-sticky\fR option. For example, the layout for a horizontal scrollbar: .CS style layout Horizontal.TScrollbar { Scrollbar.trough -children { @@ -89,32 +78,28 @@ style layout Horizontal.TScrollbar { } } .CE -By default, the layout for a widget is the same as its class name. -Some widgets may override this (for example, the \fBscrollbar\fR -widget chooses different layouts based on the \fB-orient\fR option). +By default, the layout for a widget is the same as its class name. Some +widgets may override this (for example, the \fBscrollbar\fR widget chooses +different layouts based on the \fB-orient\fR option). .SH "STATES" -In standard Tk, many widgets have a \fB-state\fR option -which (in most cases) is either \fBnormal\fR or \fBdisabled\fR. -Some widgets support additional states, such -as the \fBentry\fR widget which has a \fBreadonly\fR state -and the various flavors of buttons which have \fBactive\fR state. +In standard Tk, many widgets have a \fB\-state\fR option which (in most cases) +is either \fBnormal\fR or \fBdisabled\fR. Some widgets support additional +states, such as the \fBentry\fR widget which has a \fBreadonly\fR state and +the various flavors of buttons which have \fBactive\fR state. .PP -The themed Tk widgets generalizes this idea: -every widget has a bitmap of independent state flags. -Widget state flags include \fBactive\fR, \fBdisabled\fR, -\fBpressed\fR, \fBfocus\fR, etc., -(see \fIttk_widget(n)\fR for the full list of state flags). +The themed Tk widgets generalizes this idea: every widget has a bitmap of +independent state flags. Widget state flags include \fBactive\fR, +\fBdisabled\fR, \fBpressed\fR, \fBfocus\fR, etc., (see \fIttk_widget(n)\fR for +the full list of state flags). .PP -Instead of a \fB-state\fR option, every widget now has -a \fBstate\fR widget command which is used to set or query -the state. -A \fIstate specification\fR is a list of symbolic state names -indicating which bits are set, each optionally prefixed with an -exclamation point indicating that the bit is cleared instead. +Instead of a \fB\-state\fR option, every widget now has a \fBstate\fR widget +command which is used to set or query the state. A \fIstate specification\fR +is a list of symbolic state names indicating which bits are set, each +optionally prefixed with an exclamation point indicating that the bit is +cleared instead. .PP -For example, the class bindings for the \fBtbutton\fR -widget are: +For example, the class bindings for the \fBttk::button\fR widget are: .CS bind TButton <Enter> { %W state active } bind TButton <Leave> { %W state !active } @@ -124,27 +109,23 @@ bind TButton <Button1-Enter> { %W state pressed } bind TButton <ButtonRelease-1> \e { %W instate {pressed} { %W state !pressed ; %W invoke } } .CE -This specifies that the widget becomes \fBactive\fR when -the pointer enters the widget, and inactive when it leaves. -Similarly it becomes \fBpressed\fR when the mouse button is pressed, -and \fB!pressed\fR on the ButtonRelease event. -In addition, the button unpresses if -pointer is dragged outside the widget while Button-1 is held down, -and represses if it's dragged back in. -Finally, when the mouse button is released, the widget's -\fB-command\fR is invoked, but only if the button is currently -in the \fBpressed\fR state. -(The actual bindings are a little more complicated than the above, -but not by much). +This specifies that the widget becomes \fBactive\fR when the pointer enters +the widget, and inactive when it leaves. Similarly it becomes \fBpressed\fR +when the mouse button is pressed, and \fB!pressed\fR on the ButtonRelease +event. In addition, the button unpresses if pointer is dragged outside the +widget while Button-1 is held down, and represses if it's dragged back in. +Finally, when the mouse button is released, the widget's \fB\-command\fR is +invoked, but only if the button is currently in the \fBpressed\fR state. (The +actual bindings are a little more complicated than the above, but not by +much). .PP -\fINote to self: rewrite that paragraph. It's horrible.\fR +\fINote to self: rewrite that paragraph. It's horrible.\fR .SH "STYLES" -Each widget is associated with a \fIstyle\fR, -which specifies values for element resources. -Style names use a recursive dotted notation like layouts and elements; -by default, widgets use the class name to look up a style in the current theme. -For example: +Each widget is associated with a \fIstyle\fR, which specifies values for +element resources. Style names use a recursive dotted notation like layouts +and elements; by default, widgets use the class name to look up a style in the +current theme. For example: .CS style default TButton \e -background #d9d9d9 \e @@ -152,11 +133,10 @@ style default TButton \e -relief raised \e ; .CE -Many elements are displayed differently depending on the widget state. -For example, buttons have a different background when they are active, -a different foreground when disabled, and a different relief when pressed. -The \fBstyle map\fR command specifies dynamic resources -for a particular style: +Many elements are displayed differently depending on the widget state. For +example, buttons have a different background when they are active, a different +foreground when disabled, and a different relief when pressed. The \fBstyle +map\fR command specifies dynamic resources for a particular style: .CS style map TButton \e -background [list disabled #d9d9d9 active #ececec] \e diff --git a/doc/ttk_panedwindow.n b/doc/ttk_panedwindow.n index b7d0210..ff88473 100644 --- a/doc/ttk_panedwindow.n +++ b/doc/ttk_panedwindow.n @@ -3,9 +3,9 @@ '\" '\" 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.6 2007/06/10 03:25:32 jenglish Exp $ -'\" +'\" +'\" RCS: @(#) $Id: ttk_panedwindow.n,v 1.7 2007/10/22 14:33:13 dkf Exp $ +'\" .so man.macros .TH ttk_panedwindow n 8.5 Tk "Tk Themed Widget" .BS @@ -23,81 +23,82 @@ ttk_panedwindow \- Multi-pane container window .SH DESCRIPTION A \fBttk::panedwindow\fR widget displays a number of subwindows, stacked -either vertically or horizontally. The user may adjust the relative sizes -of the subwindows by dragging the sash between panes. +either vertically or horizontally. The user may adjust the relative sizes 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. -If \fBvertical\fR, subpanes are stacked top-to-bottom; -if \fBhorizontal\fR, subpanes are stacked left-to-right. +Specifies the orientation of the window. If \fBvertical\fR, subpanes are +stacked top-to-bottom; if \fBhorizontal\fR, subpanes are stacked +left-to-right. .OP \-width width Width -If present and greater than zero, -specifies the desired width of the widget in pixels. -Otherwise, the requested width is determined by the width -of the managed windows. +If present and greater than zero, specifies the desired width of the widget in +pixels. Otherwise, the requested width is determined by the width of the +managed windows. .OP \-height height Height -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. +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. +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. -Additional commands: +Supports the standard \fBconfigure\fR, \fBcget\fR, \fBstate\fR, and +\fBinstate\fR commands; see \fIttk_widget(n)\fR for details. Additional +commands: .TP \fIpathname \fBadd\fR \fIsubwindow\fR \fIoptions...\fR -Adds a new pane to the window. -\fIsubwindow\fR must be a direct child of the paned window \fIpathname\fR. -See \fBPANE OPTIONS\fR for the list of available options. +. +Adds a new pane to the window. \fIsubwindow\fR must be a direct child of the +paned window \fIpathname\fR. See \fBPANE OPTIONS\fR for the list of available +options. .TP \fIpathname \fBforget\fR \fIpane\fR -Removes the specified subpane from the widget. -\fIpane\fR is either an integer index or the name of a managed subwindow. +. +Removes the specified subpane from the widget. \fIpane\fR is either an integer +index or the name of a managed subwindow. .TP \fIpathname \fBinsert\fR \fIpos\fR \fIsubwindow\fR \fIoptions...\fR -Inserts a pane at the specified position. -\fIpos\fR is either the string \fBend\fR, an integer index, -or the name of a managed subwindow. -If \fIsubwindow\fR is already managed by the paned window, -moves it to the specified position. -See \fBPANE OPTIONS\fR for the list of available options. +. +Inserts a pane at the specified position. \fIpos\fR is either the string +\fBend\fR, an integer index, or the name of a managed subwindow. If +\fIsubwindow\fR is already managed by the paned window, moves it to the +specified position. See \fBPANE OPTIONS\fR for the list of available options. .TP \fIpathname \fBpane\fR \fIpane -option \fR?\fIvalue \fR?\fI-option value...\fR -Query or modify the options of the specified \fIpane\fR, -where \fIpane\fR is either an integer index or the name of a managed subwindow. -If no \fI-option\fR is specified, returns a dictionary of the pane -option values. -If one \fI-option\fR is specified, returns the value of that \fIoption\fR. -Otherwise, sets the \fI-option\fRs to the corresponding \fIvalue\fRs. +. +Query or modify the options of the specified \fIpane\fR, where \fIpane\fR is +either an integer index or the name of a managed subwindow. If no +\fI\-option\fR is specified, returns a dictionary of the pane option values. +If one \fI\-option\fR is specified, returns the value of that \fIoption\fR. +Otherwise, sets the \fI\-option\fRs to the corresponding \fIvalue\fRs. .TP \fIpathname\fR \fBsashpos\fR \fIindex\fR ?\fInewpos\fR? -If \fInewpos\fR is specified, sets the position -of sash number \fIindex\fR. -May adjust the positions of adjacent sashes -to ensure that positions are monotonically increasing. -Sash positions are further constrained to be between 0 -and the total size of the widget. +. +If \fInewpos\fR is unspecified, returns the current position of sash number +\fIindex\fR. If \fInewpos\fR is specified, sets the position of sash number +\fIindex\fR, with the aim of making \fInewpos\fR its new position. May adjust +the positions of adjacent sashes to ensure that positions are monotonically +increasing. Sash positions are further constrained to be between 0 and the +total size of the widget; these may mean that the actual new sash position is +not what was requested. .\" Full story: "total size" is either the -height (resp -width), .\" or the actual window height (resp actual window width), .\" depending on which changed most recently. Returns the new position of sash number \fIindex\fR. -.\" Full story: new position may be different than the requested position. .TP \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. +. +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_progressbar.n b/doc/ttk_progressbar.n index f94c12e..ae353c4 100644 --- a/doc/ttk_progressbar.n +++ b/doc/ttk_progressbar.n @@ -3,9 +3,9 @@ '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id: ttk_progressbar.n,v 1.3 2006/12/13 23:04:33 hobbs Exp $ -'\" +'\" +'\" RCS: @(#) $Id: ttk_progressbar.n,v 1.4 2007/10/22 14:33:13 dkf Exp $ +'\" .so man.macros .TH ttk_progressbar n 8.5 Tk "Tk Themed Widget" .BS @@ -17,9 +17,9 @@ ttk_progressbar \- Provide progress feedback .BE .SH DESCRIPTION -A \fBttk::progressbar\fR widget shows the status of a long-running -operation. They can operate in two modes: \fIdeterminate\fR mode shows the -amount completed relative to the total amount of work to be done, and +A \fBttk::progressbar\fR widget shows the status of a long-running operation. +They can operate in two modes: \fIdeterminate\fR mode shows the amount +completed relative to the total amount of work to be done, and \fIindeterminate\fR mode provides an animated display to let the user know that something is happening. .SO @@ -28,62 +28,64 @@ that something is happening. .SH "WIDGET-SPECIFIC OPTIONS" .OP \-orient orient Orient -One of \fBhorizontal\fR or \fBvertical\fR. -Specifies the orientation of the progress bar. +One of \fBhorizontal\fR or \fBvertical\fR. Specifies the orientation of the +progress bar. .OP \-length length Length -Specifies the length of the long axis of the progress bar -(width if horizontal, height if vertical). +Specifies the length of the long axis of the progress bar (width if +horizontal, height if vertical). .OP \-mode mode Mode One of \fBdeterminate\fR or \fBindeterminate\fR. .OP \-maximum maximum Maximum -A floating point number specifying the maximum \fB-value\fR. -Defaults to 100. +A floating point number specifying the maximum \fB\-value\fR. Defaults to 100. .OP \-value value Value -The current value of the progress bar. -In \fIdeterminate\fR mode, this represents the amount of work completed. -In \fIindeterminate\fR mode, it is interpreted modulo \fB-maximum\fR; -that is, the progress bar completes one "cycle" when -the \fB-value\fR increases by \fB-maximum\fR. +The current value of the progress bar. In \fIdeterminate\fR mode, this +represents the amount of work completed. In \fIindeterminate\fR mode, it is +interpreted modulo \fB\-maximum\fR; that is, the progress bar completes one +"cycle" when the \fB\-value\fR increases by \fB\-maximum\fR. .OP \-variable variable Variable -The name of a Tcl variable which is linked to the \fB-value\fR. -If specified, the \fB-value\fR of the progress bar is -automatically set to the value of the variable whenever -the latter is modified. +The name of a Tcl variable which is linked to the \fB\-value\fR. If specified, +the \fB\-value\fR of the progress bar is automatically set to the value of the +variable whenever the latter is modified. .OP \-phase phase Phase -Read-only option. -The widget periodically increments the value of this option -whenever the \fB-value\fR is greater than 0 and, -in \fIdeterminate\fR mode, less than \fB-maximum\fR. -This option may be used by the current theme -to provide additional animation effects. +Read-only option. The widget periodically increments the value of this option +whenever the \fB\-value\fR is greater than 0 and, in \fIdeterminate\fR mode, +less than \fB\-maximum\fR. This option may be used by the current theme to +provide additional animation effects. .SH "WIDGET COMMAND" .TP \fIpathName \fBcget\fR \fIoption\fR -Returns the current value of the specified \fIoption\fR; see \fIttk_widget(n)\fR. +. +Returns the current value of the specified \fIoption\fR; see +\fIttk_widget(n)\fR. .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +. Modify or query widget options; see \fIttk_widget(n)\fR. .TP \fIpathName \fBinstate \fIstatespec\fR ?\fIscript\fR? +. Test the widget state; see \fIttk_widget(n)\fR. .TP \fIpathName \fBstart\fR ?\fIinterval\fR? -Begin autoincrement mode: -schedules a recurring timer event that calls \fBstep\fR -every \fIinterval\fR milliseconds. -If omitted, \fIinterval\fR defaults to 50 milliseconds (20 steps/second). +. +Begin autoincrement mode: schedules a recurring timer event that calls +\fBstep\fR every \fIinterval\fR milliseconds. If omitted, \fIinterval\fR +defaults to 50 milliseconds (20 steps/second). .TP \fIpathName \fBstate\fR ?\fIstateSpec\fR? +. Modify or query the widget state; see \fIttk_widget(n)\fR. .TP \fIpathName \fBstep\fR ?\fIamount\fR? -Increments the \fB-value\fR by \fIamount\fR. -\fIamount\fR defaults to 1.0 if omitted. +. +Increments the \fB\-value\fR by \fIamount\fR. \fIamount\fR defaults to 1.0 if +omitted. .TP \fIpathName \fBstop\fR -Stop autoincrement mode: -cancels any recurring timer event initiated by \fIpathName \fBstart\fR. +. +Stop autoincrement mode: cancels any recurring timer event initiated by +\fIpathName \fBstart\fR. .SH "SEE ALSO" ttk_widget(n) diff --git a/doc/ttk_scrollbar.n b/doc/ttk_scrollbar.n index de4a666..6c1efeb 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.3 2006/12/13 23:04:33 hobbs Exp $ +'\" RCS: @(#) $Id: ttk_scrollbar.n,v 1.4 2007/10/22 14:33:13 dkf Exp $ '\" .so man.macros .TH ttk_scrollbar n 8.5 Tk "Tk Themed Widget" @@ -19,140 +19,138 @@ ttk_scrollbar \- Control the viewport of a scrollable widget .BE .SH DESCRIPTION -\fBttk::scrollbar\fR widgets are typically linked to an associated window -that displays a document of some sort, such as a file being edited or a -drawing. -A scrollbar displays a \fIthumb\fR in the middle portion of the scrollbar, -whose position and size provides information about the portion of the -document visible in the associated window. -The thumb may be dragged by the user to control the visible region. -Depending on the theme, two or more arrow buttons may also be present; -these are used to scroll the visible region in discrete units. +\fBttk::scrollbar\fR widgets are typically linked to an associated window that +displays a document of some sort, such as a file being edited or a drawing. A +scrollbar displays a \fIthumb\fR in the middle portion of the scrollbar, whose +position and size provides information about the portion of the document +visible in the associated window. The thumb may be dragged by the user to +control the visible region. Depending on the theme, two or more arrow buttons +may also be present; these are used to scroll the visible region in discrete +units. .SO \-class \-cursor \-style \-takefocus .SE .SH "WIDGET-SPECIFIC OPTIONS" .OP \-command command Command -A Tcl script prefix to evaluate -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. +A Tcl script prefix to evaluate 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 -This option typically consists of a two-element list, -containing the name of a scrollable widget followed by -either \fBxview\fR (for horizontal scrollbars) +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). .OP \-orient orient Orient -One of \fBhorizontal\fR or \fBvertical\fR. -Specifies the orientation of the scrollbar. +One of \fBhorizontal\fR or \fBvertical\fR. Specifies the orientation of the +scrollbar. .BE .SH "WIDGET COMMAND" .TP \fIpathName \fBcget\fR \fIoption\fR -Returns the current value of the specified \fIoption\fR; see \fIttk_widget(n)\fR. +. +Returns the current value of the specified \fIoption\fR; see +\fIttk_widget(n)\fR. .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +. Modify or query widget options; see \fIttk_widget(n)\fR. .TP \fIpathName \fBget\fR -Returns the scrollbar settings in the form of a list whose -elements are the arguments to the most recent \fBset\fR widget command. +. +Returns the scrollbar settings in the form of a list whose elements are the +arguments to the most recent \fBset\fR widget command. .TP \fIpathName \fBinstate \fIstatespec\fR ?\fIscript\fR? +. Test the widget state; see \fIttk_widget(n)\fR. .TP \fIpathName \fBset\fR \fIfirst last\fR -This command is normally invoked by the scrollbar's associated widget -from an \fB-xscrollcommand\fR or \fB-yscrollcommand\fR callback. -Specifies the visible range to be displayed. -\fIfirst\fR and \fIlast\fR are real fractions between 0 and 1. +. +This command is normally invoked by the scrollbar's associated widget from an +\fB\-xscrollcommand\fR or \fB\-yscrollcommand\fR callback. Specifies the +visible range to be displayed. \fIfirst\fR and \fIlast\fR are real fractions +between 0 and 1. .TP \fIpathName \fBstate\fR ?\fIstateSpec\fR? +. Modify or query the widget state; see \fIttk_widget(n)\fR. .SH "INTERNAL COMMANDS" -The following widget commands are used internally -by the TScrollbar widget class bindings. +The following widget commands are used internally by the TScrollbar widget +class bindings. .TP \fIpathName \fBdelta \fIdeltaX deltaY\fR -Returns a real number indicating the fractional change in -the scrollbar setting that corresponds to a given change -in thumb position. For example, if the scrollbar is horizontal, -the result indicates how much the scrollbar setting must change -to move the thumb \fIdeltaX\fR pixels to the right (\fIdeltaY\fR is -ignored in this case). -If the scrollbar is vertical, the result indicates how much the -scrollbar setting must change to move the thumb \fIdeltaY\fR pixels -down. The arguments and the result may be zero or negative. +. +Returns a real number indicating the fractional change in the scrollbar +setting that corresponds to a given change in thumb position. For example, if +the scrollbar is horizontal, the result indicates how much the scrollbar +setting must change to move the thumb \fIdeltaX\fR pixels to the right +(\fIdeltaY\fR is ignored in this case). If the scrollbar is vertical, the +result indicates how much the scrollbar setting must change to move the thumb +\fIdeltaY\fR pixels down. The arguments and the result may be zero or +negative. .TP \fIpathName \fBfraction \fIx y\fR -Returns a real number between 0 and 1 indicating where the point -given by \fIx\fR and \fIy\fR lies in the trough area of the scrollbar, -where 0.0 corresponds to the top or left of the trough -and 1.0 corresponds to the bottom or right. -\fIX\fR and \fIy\fR are pixel coordinates relative to the scrollbar -widget. -If \fIx\fR and \fIy\fR refer to a point outside the trough, the closest -point in the trough is used. +. +Returns a real number between 0 and 1 indicating where the point given by +\fIx\fR and \fIy\fR lies in the trough area of the scrollbar, where 0.0 +corresponds to the top or left of the trough and 1.0 corresponds to the bottom +or right. \fIX\fR and \fIy\fR are pixel coordinates relative to the scrollbar +widget. If \fIx\fR and \fIy\fR refer to a point outside the trough, the +closest point in the trough is used. .TP \fIpathName \fBidentify\fR \fIx y\fR -Returns the name of the element under the point given -by \fIx\fR and \fIy\fR, or an empty string if the point does -not lie in any element of the scrollbar. +. +Returns the name of the element under the point given by \fIx\fR and \fIy\fR, +or an empty string if the point does not lie in any element of the scrollbar. \fIX\fR and \fIy\fR are pixel coordinates relative to the scrollbar widget. .SH "SCROLLING COMMANDS" -When the user interacts with the scrollbar, for example by dragging -the thumb, the scrollbar notifies the associated widget that it -must change its view. -The scrollbar makes the notification by evaluating a Tcl command -generated from the scrollbar's \fB\-command\fR option. -The command may take any of the following forms. -In each case, \fIprefix\fR is the contents of the +When the user interacts with the scrollbar, for example by dragging the thumb, +the scrollbar notifies the associated widget that it must change its view. +The scrollbar makes the notification by evaluating a Tcl command generated +from the scrollbar's \fB\-command\fR option. The command may take any of the +following forms. In each case, \fIprefix\fR is the contents of the \fB\-command\fR option, which usually has a form like \fB.t yview\fR .TP \fIprefix \fBmoveto \fIfraction\fR -\fIFraction\fR is a real number between 0 and 1. -The widget should adjust its view so that the point given -by \fIfraction\fR appears at the beginning of the widget. -If \fIfraction\fR is 0 it refers to the beginning of the -document. 1.0 refers to the end of the document, 0.333 -refers to a point one-third of the way through the document, -and so on. +. +\fIFraction\fR is a real number between 0 and 1. The widget should adjust its +view so that the point given by \fIfraction\fR appears at the beginning of the +widget. If \fIfraction\fR is 0 it refers to the beginning of the document. 1.0 +refers to the end of the document, 0.333 refers to a point one-third of the +way through the document, and so on. .TP \fIprefix \fBscroll \fInumber \fBunits\fR -The widget should adjust its view by \fInumber\fR units. -The units are defined in whatever way makes sense for the widget, -such as characters or lines in a text widget. -\fINumber\fR is either 1, which means one unit should scroll off -the top or left of the window, or \-1, which means that one unit -should scroll off the bottom or right of the window. +. +The widget should adjust its view by \fInumber\fR units. The units are defined +in whatever way makes sense for the widget, such as characters or lines in a +text widget. \fINumber\fR is either 1, which means one unit should scroll off +the top or left of the window, or \-1, which means that one unit should scroll +off the bottom or right of the window. .TP \fIprefix \fBscroll \fInumber \fBpages\fR -The widget should adjust its view by \fInumber\fR pages. -It is up to the widget to define the meaning of a page; typically -it is slightly less than what fits in the window, so that there -is a slight overlap between the old and new views. -\fINumber\fR is either 1, which means the next page should -become visible, or \-1, which means that the previous page should -become visible. +. +The widget should adjust its view by \fInumber\fR pages. It is up to the +widget to define the meaning of a page; typically it is slightly less than +what fits in the window, so that there is a slight overlap between the old and +new views. \fINumber\fR is either 1, which means the next page should become +visible, or \-1, which means that the previous page should become visible. .SH "WIDGET STATES" -The scrollbar automatically sets the \fBdisabled\fR state bit. -when the entire range is visible (range is 0.0 to 1.0), -and clears it otherwise. -It also sets the \fBactive\fR and \fBpressed\fR state flags -of individual elements, based on the position and state of the mouse pointer. +The scrollbar automatically sets the \fBdisabled\fR state bit when the entire +range is visible (range is 0.0 to 1.0), and clears it otherwise. It also sets +the \fBactive\fR and \fBpressed\fR state flags of individual elements, based +on the position and state of the mouse pointer. .SH EXAMPLE .CS set f [frame .f] ttk::scrollbar $f.hsb -orient horizontal -command [list $f.t xview] ttk::scrollbar $f.vsb -orient vertical -command [list $f.t yview] -text $f.t -xscrollcommand [list $f.hsb set] -yscrollcommand [list $f.vsb set] +text $f.t -xscrollcommand [list $f.hsb set] -yscrollcommand [list $f.vsb set] grid $f.t -row 0 -column 0 -sticky nsew grid $f.vsb -row 0 -column 1 -sticky nsew grid $f.hsb -row 1 -column 0 -sticky nsew diff --git a/doc/ttk_sizegrip.n b/doc/ttk_sizegrip.n index 58f5626..ad293f4 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.5 2007/10/15 20:59:34 dkf Exp $ +'\" RCS: @(#) $Id: ttk_sizegrip.n,v 1.6 2007/10/22 14:33:13 dkf Exp $ '\" .so man.macros .TH ttk_sizegrip n 8.5 Tk "Tk Themed Widget" @@ -42,8 +42,8 @@ pack [ttk::frame $top.statusbar] -side bottom -fill x pack [ttk::sizegrip $top.statusbar.grip] -side right -anchor se # Using grid: -grid [ttk::sizegrip $top.statusbar.grip] \ - -row $lastRow -column $lastColumn -sticky se +grid [ttk::sizegrip $top.statusbar.grip] \e + -row $lastRow -column $lastColumn -sticky se # ... optional: add vertical scrollbar in $lastColumn, # ... optional: add horizontal scrollbar in $lastRow .CE diff --git a/doc/ttk_treeview.n b/doc/ttk_treeview.n index f80b458..f724fe7 100644 --- a/doc/ttk_treeview.n +++ b/doc/ttk_treeview.n @@ -3,9 +3,9 @@ '\" '\" 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.5 2007/05/03 23:55:30 dkf Exp $ -'\" +'\" +'\" RCS: @(#) $Id: ttk_treeview.n,v 1.6 2007/10/22 14:33:13 dkf Exp $ +'\" .so man.macros .TH ttk_treeview n 8.5 Tk "Tk Themed Widget" .\" Use _ instead of :: as the name becomes a filename on install @@ -17,33 +17,28 @@ ttk_treeview \- hierarchical multicolumn data display widget .SH DESCRIPTION The \fBttk::treeview\fR widget displays a hierarchical collection of items. -Each item has a textual label, an optional image, -and an optional list of data values. -The data values are displayed in successive columns after -the tree label. +Each item has a textual label, an optional image, and an optional list of data +values. The data values are displayed in successive columns after the tree +label. .PP -The order in which data values are displayed may be controlled -by setting the \fB-displaycolumns\fR widget option. -The tree widget can also display column headings. -Columns may be accessed by number or by symbolic names -listed in the \fB-columns\fR widget option; -see \fBCOLUMN IDENTIFIERS\fR. +The order in which data values are displayed may be controlled by setting the +\fB\-displaycolumns\fR widget option. The tree widget can also display column +headings. Columns may be accessed by number or by symbolic names listed in the +\fB\-columns\fR widget option; see \fBCOLUMN IDENTIFIERS\fR. .PP -Each item is identified by a unique name. -The widget will generate item IDs if they are not supplied by the caller. -There is a distinguished root item, named \fB{}\fR. -The root item itself is not displayed; -its children appear at the top level of the hierarchy. +Each item is identified by a unique name. The widget will generate item IDs if +they are not supplied by the caller. There is a distinguished root item, named +\fB{}\fR. The root item itself is not displayed; its children appear at the +top level of the hierarchy. .PP -Each item also has a list of \fItags\fR, -which can be used to associate event bindings with individual items -and control the appearance of the item. +Each item also has a list of \fItags\fR, which can be used to associate event +bindings with individual items and control the appearance of the item. .\" .PP .\" @@@HERE: describe selection, focus item .PP -Treeview widgets support horizontal and vertical scrolling with the -standard \fB-[xy]scrollcommand\fR options -and \fB[xyview\fR widget commands. +Treeview widgets support horizontal and vertical scrolling with the standard +\fB\-\fR[\fBxy\fR]\fBscrollcommand\fR options and \fB[xyview\fR widget +commands. .SO \-class \-cursor \-takefocus \-style \-xscrollcommand \-yscrollcommand @@ -51,306 +46,320 @@ and \fB[xyview\fR widget commands. .SH "WIDGET-SPECIFIC OPTIONS" .OP \-columns columns Columns -A list of column identifiers, -specifying the number of columns and their names. +A list of column identifiers, specifying the number of columns and their +names. .\"X: This is a read-only option; it may only be set when the widget is created. .OP \-displaycolumns displayColumns DisplayColumns -A list of column identifiers -(either symbolic names or integer indices) -specifying which data columns are displayed -and the order in which they appear, -or the string \fB#all\fP. +A list of column identifiers (either symbolic names or integer indices) +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. .OP \-height height Height -Specifies the number of rows which should be visible. -Note: -the requested width is determined from the sum of the column widths. +Specifies the number of rows which should be visible. Note: the requested +width is determined from the sum of the column widths. .OP \-padding padding Padding -Specifies the internal padding for the widget. -The padding is a list of up to four length specifications; -see \fBTtk_GetPaddingFromObj()\fR for details. +Specifies the internal padding for the widget. The padding is a list of up to +four length specifications; 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. +Controls how the built-in class bindings manage the selection. One of +\fBextended\fR, \fBbrowse\fR, or \fBnone\fR. .br -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. +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 -Note that application code and tag bindings can set the selection -however they wish, regardless of the value of \fB-selectmode\fR. +Note that application code and tag bindings can set the selection however they +wish, regardless of the value of \fB\-selectmode\fR. .OP \-show show Show -A list containing zero or more of the following values, specifying -which elements of the tree to display. +A list containing zero or more of the following values, specifying which +elements of the tree to display. .RS .IP \fBtree\fR -Display tree labels in column #0. +Display tree labels in column #0. .IP \fBheadings\fR Display the heading row. .PP The default is \fBtree headings\fR, i.e., show all elements. .PP -\fBNOTE:\fR Column #0 always refers to the tree column, -even if \fB-show tree\fR is not specified. +\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? -Returns the bounding box (relative to the treeview widget's window) -of the specified \fIitem\fR -in the form \fIx y width height\fR. -If \fIcolumn\fR is specified, returns the bounding box of that cell. -If the \fIitem\fR is not visible -(i.e., if it is a descendant of a closed item or is scrolled offscreen), -returns the empty list. +. +Returns the bounding box (relative to the treeview widget's window) of the +specified \fIitem\fR in the form \fIx y width height\fR. If \fIcolumn\fR is +specified, returns the bounding box of that cell. If the \fIitem\fR is not +visible (i.e., if it is a descendant of a closed item or is scrolled +offscreen), returns the empty list. .TP \fIpathname \fBcget\fR \fIoption\fR -Returns the current value of the specified \fIoption\fR; see \fIttk_widget(n)\fR. +. +Returns the current value of the specified \fIoption\fR; see +\fIttk_widget(n)\fR. .TP \fIpathname \fBchildren\fR \fIitem\fR ?\fInewchildren\fR? -If \fInewchildren\fR is not specified, -returns the list of children belonging to \fIitem\fR. +. +If \fInewchildren\fR is not specified, returns the list of children belonging +to \fIitem\fR. .br -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. -.TP -\fIpathname \fBcolumn\fR \fIcolumn\fR ?\fI-option \fR?\fIvalue -option value...\fR? -Query or modify the options for the specified \fIcolumn\fR. -If no \fI-option\fR is specified, -returns a dictionary of option/value pairs. -If a single \fI-option\fR is specified, -returns the value of that option. -Otherwise, the options are updated with the specified values. -The following options may be set on each column: +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. +.TP +\fIpathname \fBcolumn\fR \fIcolumn\fR ?\fI\-option \fR?\fIvalue \-option value...\fR? +. +Query or modify the options for the specified \fIcolumn\fR. If no +\fI\-option\fR is specified, returns a dictionary of option/value pairs. If a +single \fI\-option\fR is specified, returns the value of that option. +Otherwise, the options are updated with the specified values. The following +options may be set on each column: .RS .TP -\fB-id \fIname\fR -The column name. This is a read-only option. -For example, [\fI$pathname \fBcolumn #\fIn \fB-id\fR] -returns the data column associated with data column #\fIn\fR. -.TP -\fB-anchor\fR -Specifies how the text in this column should be aligned -with respect to the cell. One of -\fBn\fR, \fBne\fR, \fBe\fR, \fBse\fR, -\fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, or \fBcenter\fR. -.TP -\fB-minwidth\fR -The minimum width of the column in pixels. -The treeview widget will not make the column any smaller than -\fB-minwidth\fR when the widget is resized or the user drags a -column separator. -.TP -\fB-stretch\fR -Specifies whether or not the column's width should be adjusted -when the widget is resized. -.TP -\fB-width \fIw\fR -The width of the column in pixels. Default is something reasonable, -probably 200 or so. +\fB\-id \fIname\fR +. +The column name. This is a read-only option. For example, [\fI$pathname +\fBcolumn #\fIn \fB\-id\fR] returns the data column associated with data +column #\fIn\fR. +.TP +\fB\-anchor\fR +. +Specifies how the text in this column should be aligned with respect to the +cell. One of \fBn\fR, \fBne\fR, \fBe\fR, \fBse\fR, \fBs\fR, \fBsw\fR, \fBw\fR, +\fBnw\fR, or \fBcenter\fR. +.TP +\fB\-minwidth\fR +. +The minimum width of the column in pixels. The treeview widget will not make +the column any smaller than \fB\-minwidth\fR when the widget is resized or the +user drags a column separator. +.TP +\fB\-stretch\fR +. +Specifies whether or not the column's width should be adjusted when the widget +is resized. +.TP +\fB\-width \fIw\fR +. +The width of the column in pixels. Default is something reasonable, probably +200 or so. .PP Use \fIpathname column #0\fR to configure the tree column. .RE .TP \fIpathname \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +. Modify or query widget options; see \fIttk_widget(n)\fR. .TP \fIpathname \fBdelete\fR \fIitemList\fR -Deletes each of the items in \fIitemList\fR and all of their descendants. -The root item may not be deleted. -See also: \fBdetach\fR. +. +Deletes each of the items in \fIitemList\fR and all of their descendants. The +root item may not be deleted. See also: \fBdetach\fR. .TP \fIpathname \fBdetach\fR \fIitemList\fR -Unlinks all of the specified items in \fIitemList\fR from the tree. -The items and all of their descendants are still present -and may be reinserted at another point in the tree -but will not be displayed. -The root item may not be detached. -See also: \fBdelete\fR. +. +Unlinks all of the specified items in \fIitemList\fR from the tree. The items +and all of their descendants are still present and may be reinserted at +another point in the tree but will not be displayed. The root item may not be +detached. See also: \fBdelete\fR. .TP \fIpathname \fBexists \fIitem\fR -Returns 1 if the specified \fIitem\fR is present in the tree, -0 otherwise. +. +Returns 1 if the specified \fIitem\fR is present in the tree, 0 otherwise. .TP \fIpathname \fBfocus \fR?\fIitem\fR? -If \fIitem\fR is specified, sets the focus item to \fIitem\fR. -Otherwise, returns the current focus item, or \fB{}\fR if there is none. +. +If \fIitem\fR is specified, sets the focus item to \fIitem\fR. Otherwise, +returns the current focus item, or \fB{}\fR if there is none. .\" Need: way to clear the focus item. {} works for this... -.TP -\fIpathname \fBheading\fR \fIcolumn\fR ?\fI-option \fR?\fIvalue -option value...\fR? -Query or modify the heading options for the specified \fIcolumn\fR. -Valid options are: +.TP +\fIpathname \fBheading\fR \fIcolumn\fR ?\fI\-option \fR?\fIvalue \-option value...\fR? +. +Query or modify the heading options for the specified \fIcolumn\fR. Valid +options are: .RS .TP -\fB-text \fItext\fR +\fB\-text \fItext\fR +. The text to display in the column heading. .TP -\fB-image \fIimageName\fR +\fB\-image \fIimageName\fR +. Specifies an image to display to the right of the column heading. .TP -\fB-anchor \fIanchor\fR -Specifies how the heading text should be aligned. -One of the standard Tk anchor values. +\fB\-anchor \fIanchor\fR +. +Specifies how the heading text should be aligned. One of the standard Tk +anchor values. .TP -\fB-command \fIscript\fR +\fB\-command \fIscript\fR +. A script to evaluate when the heading label is pressed. .PP Use \fIpathname heading #0\fR to configure the tree column heading. .RE .TP \fIpathname \fBidentify \fIcomponent x y\fR -Returns a description of the specified \fIcomponent\fR -under the point given by \fIx\fR and \fIy\fR, -or the empty string if no such \fIcomponent\fR is present at that position. -The following subcommands are supported: +. +Returns a description of the specified \fIcomponent\fR under the point given +by \fIx\fR and \fIy\fR, or the empty string if no such \fIcomponent\fR is +present at that position. The following subcommands are supported: .RS .TP \fIpathname \fBidentify row\fR \fIx y\fR +. Returns the item ID of the item at position \fIy\fR. .TP \fIpathname \fBidentify column\fR \fIx y\fR -Returns the data column identifier of the cell at position \fIx\fR. -The tree column has ID \fB#0\fR. +. +Returns the data column identifier of the cell at position \fIx\fR. The tree +column has ID \fB#0\fR. .PP -See \fBCOLUMN IDENTIFIERS\fR for a discussion of display columns -and data columns. +See \fBCOLUMN IDENTIFIERS\fR for a discussion of display columns and data +columns. .RE .TP \fIpathname \fBindex \fIitem\fR +. Returns the integer index of \fIitem\fR within its parent's list of children. .TP -\fIpathname \fBinsert\fR \fIparent\fR \fIindex\fR ?\fB-id \fIid\fR? \fIoptions...\fR -Creates a new item. -\fIparent\fR is the item ID of the parent item, -or the empty string \fB{}\fR -to create a new top-level item. -\fIindex\fR is an integer, or the value \fBend\fR, specifying where in the -list of \fIparent\fR's children to insert the new item. -If \fIindex\fR is less than or equal to zero, -the new node is inserted at the beginning; -if \fIindex\fR is greater than or equal to the current number of children, -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. +\fIpathname \fBinsert\fR \fIparent\fR \fIindex\fR ?\fB\-id \fIid\fR? \fIoptions...\fR +. +Creates a new item. \fIparent\fR is the item ID of the parent item, or the +empty string \fB{}\fR to create a new top-level item. \fIindex\fR is an +integer, or the value \fBend\fR, specifying where in the list of +\fIparent\fR's children to insert the new item. If \fIindex\fR is less than or +equal to zero, the new node is inserted at the beginning; if \fIindex\fR is +greater than or equal to the current number of children, 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 -\fIpathname \fBinsert\fR returns the item identifier of the -newly created item. -See \fBITEM OPTIONS\fR for the list of available options. +\fIpathname \fBinsert\fR returns the item identifier of the newly created +item. See \fBITEM OPTIONS\fR for the list of available options. .TP \fIpathname \fBinstate \fIstatespec\fR ?\fIscript\fR? +. Test the widget state; see \fIttk_widget(n)\fR. .TP -\fIpathname \fBitem\fR \fIitem\fR ?\fI-option \fR?\fIvalue -option value...\fR? -Query or modify the options for the specified \fIitem\fR. -If no \fI-option\fR is specified, -returns a dictionary of option/value pairs. -If a single \fI-option\fR is specified, -returns the value of that option. -Otherwise, the item's options are updated with the specified values. -See \fBITEM OPTIONS\fR for the list of available options. +\fIpathname \fBitem\fR \fIitem\fR ?\fI\-option \fR?\fIvalue \-option value...\fR? +. +Query or modify the options for the specified \fIitem\fR. If no \fI\-option\fR +is specified, returns a dictionary of option/value pairs. If a single +\fI\-option\fR is specified, returns the value of that option. Otherwise, the +item's options are updated with the specified values. See \fBITEM OPTIONS\fR +for the list of available options. .TP \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 -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. -.TP +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. +.TP \fIpathname \fBnext \fIitem\fR -Returns the identifier of \fIitem\fR's next sibling, -or \fB{}\fR if \fIitem\fR is the last child of its parent. +. +Returns the identifier of \fIitem\fR's next sibling, or \fB{}\fR if \fIitem\fR +is the last child of its parent. .TP \fIpathname \fBparent \fIitem\fR -Returns the ID of the parent of \fIitem\fR, -or \fB{}\fR if \fIitem\fR is at the top level of the hierarchy. -.TP +. +Returns the ID of the parent of \fIitem\fR, or \fB{}\fR if \fIitem\fR is at +the top level of the hierarchy. +.TP \fIpathname \fBprev \fIitem\fR -Returns the identifier of \fIitem\fR's previous sibling, -or \fB{}\fR if \fIitem\fR is the first child of its parent. +. +Returns the identifier of \fIitem\fR's previous sibling, or \fB{}\fR if +\fIitem\fR is the first child of its parent. .TP \fIpathname \fBsee\fR \fIitem\fR -Ensure that \fIitem\fR is visible: -sets all of \fIitem\fR's ancestors to \fB-open true\fR, -and scrolls the widget if necessary so that \fIitem\fR is +. +Ensure that \fIitem\fR is visible: sets all of \fIitem\fR's ancestors to +\fB\-open true\fR, and scrolls the widget if necessary so that \fIitem\fR is within the visible portion of the tree. .TP \fIpathname \fBselection\fR ?\fIselop\fR \fIitemList\fR? +. If \fIselop\fR is not specified, returns the list of selected items. Otherwise, \fIselop\fR is one of the following: .RS .TP \fIpathname \fBselection set \fIitemList\fR +. \fIitemList\fR becomes the new selection. .TP \fIpathname \fBselection add \fIitemList\fR +. Add \fIitemList\fR to the selection .TP \fIpathname \fBselection remove \fIitemList\fR +. Remove \fIitemList\fR from the selection .TP \fIpathname \fBselection toggle \fIitemList\fR +. Toggle the selection state of each item in \fIitemList\fR. .RE .TP \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. -With three arguments, sets the value of column \fIcolumn\fR -in item \fIitem\fR to the specified \fIvalue\fR. -See also \fBCOLUMN IDENTIFIERS\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. With three arguments, sets the value of column +\fIcolumn\fR in item \fIitem\fR to the specified \fIvalue\fR. See also +\fBCOLUMN IDENTIFIERS\fR. .TP \fIpathname \fBstate\fR ?\fIstateSpec\fR? +. Modify or query the widget state; see \fIttk_widget(n)\fR. .TP \fIpathName \fBtag \fIargs...\fR +. .RS .TP \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. +. +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 -\fB<KeyPress>\fR, \fB<KeyRelease>\fR, and virtual events -are sent to the focus item. -\fB<ButtonPress>\fR, \fB<ButtonRelease>\fR, and \fB<Motion>\fR events -are sent to the item under the mouse pointer. -No other event types are supported. +\fB<KeyPress>\fR, \fB<KeyRelease>\fR, and virtual events are sent to the focus +item. \fB<ButtonPress>\fR, \fB<ButtonRelease>\fR, and \fB<Motion>\fR events +are sent to the item under the mouse pointer. No other event types are +supported. .br -The binding \fIscript\fR undergoes \fB%\fR-substitutions before -evaluation; see \fBbind(n)\fR for details. +The binding \fIscript\fR undergoes \fB%\fR-substitutions before evaluation; +see \fBbind(n)\fR for details. .TP \fIpathName \fBtag configure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -Query or modify the options for the specified \fItagName\fR. -If one or more \fIoption/value\fR pairs are specified, -sets the value of those options for the specified tag. -If a single \fIoption\fR is specified, -returns the value of that option -(or the empty string if the option has not been specified for \fItagName\fR). -With no additional arguments, -returns a dictionary of the option settings for \fItagName\fR. -See \fBTAG OPTIONS\fR for the list of available options. +. +Query or modify the options for the specified \fItagName\fR. If one or more +\fIoption/value\fR pairs are specified, sets the value of those options for +the specified tag. If a single \fIoption\fR is specified, returns the value of +that option (or the empty string if the option has not been specified for +\fItagName\fR). With no additional arguments, returns a dictionary of the +option settings for \fItagName\fR. See \fBTAG OPTIONS\fR for the list of +available options. .RE .TP \fIpathName \fBxview \fIargs\fR +. 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. +The following item options may be specified for items in the \fBinsert\fR and +\fBitem\fR widget commands. .OP \-text text Text The textual label to display for the item. .OP \-image image Image @@ -358,17 +367,15 @@ A Tk image, displayed to the left of the label. .OP \-values values Values The list of values associated with the item. .br -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. +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. .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). +A boolean value indicating whether the item's children should be displayed +(\fB\-open true\fR) or hidden (\fB\-open false\fR). .OP \-tags tags Tags -A list of tags associated with this item. +A list of tags associated with this item. .SH "TAG OPTIONS" The following options may be specified on tags: .IP \-foreground @@ -381,47 +388,43 @@ Specifies the font to use when drawing text. .\" ??? Maybe: .IP \-padding .\" ??? Maybe: .IP \-text .IP \-image -Specifies the item image, in case the item's \fB-image\fR option is empty. +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 - .SH "COLUMN IDENTIFIERS" Column identifiers take any of the following forms: .IP \(bu -A symbolic name from the list of \fB-columns\fR. +A symbolic name from the list of \fB\-columns\fR. .IP \(bu An integer \fIn\fR, specifying the \fIn\fRth data column. .IP \(bu -A string of the form \fB#\fIn\fR, where \fIn\fR is an integer, -specifying the \fIn\fRth display column. +A string of the form \fB#\fIn\fR, where \fIn\fR is an integer, specifying the +\fIn\fRth display column. .PP -\fBNOTE:\fR -Item \fB-values\fR may be displayed in a different order than -the order in which they are stored. +\fBNOTE:\fR Item \fB\-values\fR may be displayed in a different order than the +order in which they are stored. .PP -\fBNOTE:\fR Column #0 always refers to the tree column, -even if \fB-show tree\fR is not specified. +\fBNOTE:\fR Column #0 always refers to the tree column, even if \fB\-show +tree\fR is not specified. .PP -A \fIdata column number\fR is an index into an item's \fB-values\fR list; -a \fIdisplay column number\fR is the column number in the tree -where the values are displayed. -Tree labels are displayed in column #0. -If \fB-displaycolumns\fR is not set, -then data column \fIn\fR is displayed in display column \fB#\fIn+1\fR. -Again, \fBcolumn #0 always refers to the tree column\fR. +A \fIdata column number\fR is an index into an item's \fB\-values\fR list; a +\fIdisplay column number\fR is the column number in the tree where the values +are displayed. Tree labels are displayed in column #0. If +\fB\-displaycolumns\fR is not set, then data column \fIn\fR is displayed in +display column \fB#\fIn+1\fR. Again, \fBcolumn #0 always refers to the tree +column\fR. .SH "VIRTUAL EVENTS" The treeview widget generates the following virtual events. .IP <<TreeviewSelect>> Generated whenever the selection changes. .IP <<TreeviewOpen>> -Generated just before setting the focus item to \fB-open true\fR. +Generated just before setting the focus item to \fB\-open true\fR. .IP <<TreeviewClose>> -Generated just after setting the focus item to \fB-open false\fR. +Generated just after setting the focus item to \fB\-open false\fR. .PP -The \fBfocus\fR and \fBselection\fR widget commands can be used -to determine the affected item or items. -In Tk 8.5, the affected item is also passed as the \fB-detail\fR field -of the virtual event. +The \fBfocus\fR and \fBselection\fR widget commands can be used to determine +the affected item or items. In Tk 8.5, the affected item is also passed as the +\fB\-detail\fR field of the virtual event. .SH "SEE ALSO" ttk_widget(n), listbox(n), image(n), bind(n) diff --git a/doc/ttk_widget.n b/doc/ttk_widget.n index 1c70d67..b9599ad 100644 --- a/doc/ttk_widget.n +++ b/doc/ttk_widget.n @@ -1,11 +1,11 @@ '\" '\" Copyright (c) 2004 Joe English -'\" +'\" '\" 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.3 2006/12/13 23:04:33 hobbs Exp $ -'\" +'\" +'\" RCS: @(#) $Id: ttk_widget.n,v 1.4 2007/10/22 14:33:13 dkf Exp $ +'\" .so man.macros .TH ttk_widget n 8.5 Tk "Tk Themed Widget" .BS @@ -19,83 +19,71 @@ 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 -Specifies the window class. -The class is used when querying the option database -for the window's other options, to determine the default -bindtags for the window, and to select the widget's default -layout and style. -This is a read-only option: -it may only be specified when the window is created, -and may not be changed with the \fBconfigure\fR widget command. +Specifies the window class. The class is used when querying the option +database for the window's other options, to determine the default bindtags for +the window, and to select the widget's default layout and style. This is a +read-only option: it may only be specified when the window is created, and may +not be changed with the \fBconfigure\fR widget command. .OP \-cursor cursor Cursor -Specifies the mouse cursor to be used for the widget. -See \fBTk_GetCursor\fR and \fIcursors(n)\fR in the Tk reference manual -for the legal values. -If set to the empty string (the default), -the cursor is inherited from the parent widget. +Specifies the mouse cursor to be used for the widget. See \fBTk_GetCursor\fR +and \fIcursors(n)\fR in the Tk reference manual for the legal values. If set +to the empty string (the default), the cursor is inherited from the parent +widget. .OP \-takefocus takeFocus TakeFocus -Determines whether the window accepts the focus during keyboard traversal. -Either \fB0\fR, \fB1\fR, a command prefix (to which the widget path -is appended, and which should return \fB0\fR or \fB1\fR), -or the empty string. +Determines whether the window accepts the focus during keyboard traversal. +Either \fB0\fR, \fB1\fR, a command prefix (to which the widget path is +appended, and which should return \fB0\fR or \fB1\fR), 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 -are controllable by a scrollbar. -See \fIscrollbar(n)\fR for more information +The following options are supported by widgets that 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 -When the view in the widget's window changes, the widget will -generate a Tcl command by concatenating the scroll command and -two numbers. -Each of the numbers is a fraction between 0 and 1 indicating -a position in the document; 0 indicates the beginning, -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. +When the view in the widget's window changes, the widget will generate a Tcl +command by concatenating the scroll command and two numbers. Each of the +numbers is a fraction between 0 and 1 indicating a position in the document; 0 +indicates the beginning, 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 -Typically the \fBxScrollCommand\fR option consists of the path name -of a \fBscrollbar\fR widget followed by ``set'', e.g. ``.x.scrollbar set''. -This will cause the scrollbar to be updated whenever the view in the -window changes. +Typically the \fBxScrollCommand\fR option consists of the path name of a +\fBscrollbar\fR widget followed by ``set'', e.g. ``.x.scrollbar set''. This +will cause the scrollbar to be updated whenever the view in the window +changes. .br -If this option is set to the empty string (the default), -then no command is be executed. +If this option is set to the empty string (the default), then no command is be +executed. .OP \-yscrollcommand yScrollCommand ScrollCommand -A command prefix, used to communicate with vertical scrollbars. -See the description of \fB-xscrollcommand\fR above for details. +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: +The following options are supported by labels, buttons, and other button-like +widgets: .OP \-text text Text -Specifies a text string to be displayed inside the widget -(unless overridden by \fB-textvariable\fR). +Specifies a text string to be displayed inside the widget (unless overridden +by \fB\-textvariable\fR). .OP \-textvariable textVariable Variable -Specifies the name of variable whose value will be used -in place of the \fB-text\fR resource. +Specifies the name of variable whose value will be used in place of the +\fB\-text\fR resource. .OP \-underline underline Underline -If set, specifies the integer index (0-based) of a character to underline -in the text string. -The underlined character is used for mnemonic activation. +If set, specifies the integer index (0-based) of a character to underline in +the text string. The underlined character is used for mnemonic activation. .OP \-image image Image -Specifies an image to display. -This is a list of 1 or more elements. -The first element is the default image name. -The rest of the list is a sequence of \fIstatespec / value\fR pairs -as per \fBstyle map\fR, specifying different images to use when -the widget is in a particular state or combination of states. -All images in the list should have the same size. +Specifies an image to display. This is a list of 1 or more elements. The first +element is the default image name. The rest of the list is a sequence of +\fIstatespec / value\fR pairs as per \fBstyle map\fR, specifying different +images to use when the widget is in a particular state or combination of +states. All images in the list should have the same size. .OP \-compound compound Compound -Specifies how to display the image relative to the text, -in the case both \fB-text\fR and \fB-image\fR are present. -Valid values are: +Specifies how to display the image relative to the text, in the case both +\fB\-text\fR and \fB\-image\fR are present. Valid values are: .RS .IP text Display text only. @@ -112,123 +100,126 @@ Display image above, below, left of, or right of the text, respectively. The default; display the image if present, otherwise the text. .RE .OP \-width width Width -If greater than zero, specifies how much space, in character widths, -to allocate for the text label. -If less than zero, specifies a minimum width. -If zero or unspecified, the natural width of the text label is used. +If greater than zero, specifies how much space, in character widths, to +allocate for the text label. If less than zero, specifies a minimum width. If +zero or unspecified, the natural width of the text label is used. .SH "COMPATIBILITY OPTIONS" .OP \-state state State -May be set to \fBnormal\fR or \fBdisabled\fR -to control the \fBdisabled\fR state bit. -This is a ``write-only'' option: setting it changes the -widget state, but the \fBstate\fR widget command does -not affect the state option. +May be set to \fBnormal\fR or \fBdisabled\fR to control the \fBdisabled\fR +state bit. This is a ``write-only'' option: setting it changes the widget +state, but the \fBstate\fR widget command does not affect the state option. .SH COMMANDS .TP \fIpathName \fBcget\fR \fIoption\fR -Returns the current value of the configuration option given -by \fIoption\fR. +. +Returns the current value of the configuration option given by \fIoption\fR. .TP \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -Query or modify the configuration options of the widget. -If one or more \fIoption\-value\fR pairs are specified, -then the command modifies the given widget option(s) -to have the given value(s); -in this case the command returns an empty string. -If \fIoption\fR is specified with no \fIvalue\fR, -then the command returns a list describing the named option: -the elements of the list are the -option name, database name, database class, default value, -and current value. +. +Query or modify the configuration options of the widget. If one or more +\fIoption\-value\fR pairs are specified, then the command modifies the given +widget option(s) to have the given value(s); in this case the command returns +an empty string. If \fIoption\fR is specified with no \fIvalue\fR, then the +command returns a list describing the named option: the elements of the list +are the option name, database name, database class, default value, and current +value. .\" Note: Ttk widgets don't use TK_OPTION_SYNONYM. -If no \fIoption\fR is specified, returns a list describing all of -the available options for \fIpathName\fR. -.TP +If no \fIoption\fR is specified, returns a list describing all of the +available options for \fIpathName\fR. +.TP \fIpathName \fBinstate\fR \fIstatespec\fR ?\fIscript\fR? -Test the widget's state. -If \fIscript\fR is not specified, returns 1 if -the widget state matches \fIstatespec\fR and 0 otherwise. -If \fIscript\fR is specified, equivalent to +. +Test the widget's state. If \fIscript\fR is not specified, returns 1 if the +widget state matches \fIstatespec\fR and 0 otherwise. If \fIscript\fR is +specified, equivalent to +.RS .CS if {[\fIpathName\fR instate \fIstateSpec\fR]} \fIscript\fR .CE -.TP +.RE +.TP \fIpathName \fBstate\fR ?\fIstateSpec\fR -Modify or inquire widget state. -If \fIstateSpec\fR is present, sets the widget state: -for each flag in \fIstateSpec\fR, sets the corresponding flag -or clears it if prefixed by an exclamation point. -Returns a new state spec indicating which flags were changed: +. +Modify or inquire widget state. If \fIstateSpec\fR is present, sets the widget +state: for each flag in \fIstateSpec\fR, sets the corresponding flag or clears +it if prefixed by an exclamation point. Returns a new state spec indicating +which flags were changed: +.RS .CS set changes [\fIpathName \fRstate \fIspec\fR] \fIpathName \fRstate $changes .CE -will restore \fIpathName\fR to the original state. -If \fIstateSpec\fR is not specified, -returns a list of the currently-enabled state flags. +will restore \fIpathName\fR to the original state. If \fIstateSpec\fR is not +specified, returns a list of the currently-enabled state flags. +.RE .SH "WIDGET STATES" -The widget state is a bitmap of independent state flags. -Widget state flags include: +The widget state is a bitmap of independent state flags. Widget state flags +include: .TP \fBactive\fR -The mouse cursor is over the widget -and pressing a mouse button will cause some action to occur. -(aka "prelight" (Gnome), "hot" (Windows), "hover"). +. +The mouse cursor is over the widget and pressing a mouse button will cause +some action to occur. (aka "prelight" (Gnome), "hot" (Windows), "hover"). .TP \fBdisabled\fR -Widget is disabled under program control -(aka "unavailable", "inactive") +. +Widget is disabled under program control (aka "unavailable", "inactive") .TP \fBfocus\fR -Widget has keyboard focus +. +Widget has keyboard focus. .TP \fBpressed\fR -Widget is being pressed (aka "armed" in Motif). +. +Widget is being pressed (aka "armed" in Motif). .TP \fBselected\fR -"On", "true", or "current" for things like checkbuttons and radiobuttons. +. +The widget is "On", "true", or "current" (for things like checkbuttons and +radiobuttons). .TP \fBbackground\fR -Windows and the Mac have a notion of an "active" or foreground window. -The \fBbackground\fR state is set for widgets in a background window, -and cleared for those in the foreground window. +. +Windows and the Mac have a notion of an "active" or foreground window. The +\fBbackground\fR state is set for widgets in a background window, and cleared +for those in the foreground window. .TP \fBreadonly\fR +. Widget should not allow user modification. .TP \fBalternate\fR -A widget-specific alternate display format. -For example, used for checkbuttons and radiobuttons -in the "tristate" or "mixed" state, -and for buttons with \fB-default active\fR. +. +A widget-specific alternate display format. For example, used for checkbuttons +and radiobuttons in the "tristate" or "mixed" state, and for buttons with +\fB\-default active\fR. .TP \fBinvalid\fR -The widget's value is invalid. -(Potential uses: scale widget value out of bounds, -entry widget value failed validation.) +. +The widget's value is invalid. (Potential uses: scale widget value out of +bounds, entry widget value failed validation.) .PP -A \fIstate specification\fR or \fIstateSpec\fR is a list -of state names, optionally prefixed with an exclamation point (!) -indicating that the bit is off. +A \fIstate specification\fR or \fIstateSpec\fR is a list of state names, +optionally prefixed with an exclamation point (!) indicating that the bit is +off. .SH EXAMPLES .CS 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) - .SH KEYWORDS state, configure, option |