diff options
author | hobbs <hobbs@noemail.net> | 2010-08-26 02:06:07 (GMT) |
---|---|---|
committer | hobbs <hobbs@noemail.net> | 2010-08-26 02:06:07 (GMT) |
commit | f82f8325629eae0249664454d7c6bd9b2ab444c4 (patch) | |
tree | fa90e1e6d32590addfbb0a1599a40b1f7f99ea3b /doc | |
parent | acbf7d0c30dab4aeb6c469af96b254bbce5c9f59 (diff) | |
download | tk-f82f8325629eae0249664454d7c6bd9b2ab444c4.zip tk-f82f8325629eae0249664454d7c6bd9b2ab444c4.tar.gz tk-f82f8325629eae0249664454d7c6bd9b2ab444c4.tar.bz2 |
Major backport of 8.6 Ttk for 8.5.9. Most changes were only being
committed to head (8.6), although they could apply for 8.5 as well.
This re-sync makes future work easier to maintain and adds some
useful work for 8.5 users. Notable changes:
- Lots of code cleanup
- Some bug fixes never backported
- Addition of ttk::spinbox
- minor color changes
- Improved Vista/7 styling
- Move to tile version 0.8.6 (pseudo-package)
- ABI and API compatible (even $w identify)
- minor new features (extended $w identify)
FossilOrigin-Name: 4cd6631df4dd9ec673677a7834f9b7e9d10b8e1c
Diffstat (limited to 'doc')
-rw-r--r-- | doc/ttk_Geometry.3 | 45 | ||||
-rw-r--r-- | doc/ttk_Theme.3 | 4 | ||||
-rw-r--r-- | doc/ttk_button.n | 8 | ||||
-rw-r--r-- | doc/ttk_checkbutton.n | 11 | ||||
-rw-r--r-- | doc/ttk_combobox.n | 62 | ||||
-rw-r--r-- | doc/ttk_entry.n | 117 | ||||
-rw-r--r-- | doc/ttk_frame.n | 8 | ||||
-rw-r--r-- | doc/ttk_image.n | 9 | ||||
-rw-r--r-- | doc/ttk_intro.n | 49 | ||||
-rw-r--r-- | doc/ttk_label.n | 7 | ||||
-rw-r--r-- | doc/ttk_labelframe.n | 7 | ||||
-rw-r--r-- | doc/ttk_menubutton.n | 11 | ||||
-rw-r--r-- | doc/ttk_notebook.n | 26 | ||||
-rw-r--r-- | doc/ttk_panedwindow.n | 68 | ||||
-rw-r--r-- | doc/ttk_progressbar.n | 7 | ||||
-rw-r--r-- | doc/ttk_radiobutton.n | 12 | ||||
-rw-r--r-- | doc/ttk_scale.n | 5 | ||||
-rw-r--r-- | doc/ttk_scrollbar.n | 11 | ||||
-rw-r--r-- | doc/ttk_separator.n | 7 | ||||
-rw-r--r-- | doc/ttk_sizegrip.n | 9 | ||||
-rw-r--r-- | doc/ttk_spinbox.n | 88 | ||||
-rw-r--r-- | doc/ttk_style.n | 15 | ||||
-rw-r--r-- | doc/ttk_treeview.n | 106 | ||||
-rw-r--r-- | doc/ttk_vsapi.n | 11 | ||||
-rw-r--r-- | doc/ttk_widget.n | 79 |
25 files changed, 552 insertions, 230 deletions
diff --git a/doc/ttk_Geometry.3 b/doc/ttk_Geometry.3 index 74e44f4..042caf0 100644 --- a/doc/ttk_Geometry.3 +++ b/doc/ttk_Geometry.3 @@ -1,7 +1,7 @@ '\" '\" Copyright (c) 2004 Joe English '\" -'\" RCS: @(#) $Id: ttk_Geometry.3,v 1.4 2007/12/13 15:23:44 dgp Exp $ +'\" RCS: @(#) $Id: ttk_Geometry.3,v 1.4.2.1 2010/08/26 02:06:09 hobbs Exp $ '\" .so man.macros .TH Geometry 3 8.5 Tk "Tk Themed Widget" @@ -42,7 +42,7 @@ Ttk_Padding Ttk_Padding \fBTtk_AddPadding\fR(Ttk_Padding \fIpadding1\fR, Ttk_Padding \fIpadding2\fR; -Ttk_Padding +Ttk_Padding \fBTtk_RelievePadding\fR(Ttk_Padding \fIpadding\fR, int \fIrelief\fR); int @@ -57,7 +57,6 @@ int int \fBTtk_GetStickyFromObj\fR(Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIobjPtr\fR, int *\fIsticky_rtn\fR); .fi - .SH ARGUMENTS .AP Tk_Anchor anchor in One of the symbolic constants \fBTK_ANCHOR_N\fR, \fBTK_ANCHOR_NE\fR, @@ -118,16 +117,16 @@ X coordinate of upper-left corner of region. .AP int y in Y coordinate of upper-left corner of region. .BE - .SH "BOXES" -The \fBTtk_Box\fR structure represents a rectangular region of a window: +.PP +The \fBTtk_Box\fR structure represents a rectangular region of a window: .CS -typedef struct { - int x; - int y; - int width; - int height; -} Ttk_Box; +typedef struct { + int \fIx\fR; + int \fIy\fR; + int \fIwidth\fR; + int \fIheight\fR; +} \fBTtk_Box\fR; .CE All coordinates are relative to the window. .PP @@ -136,12 +135,12 @@ a \fBTtk_Box\fR structure representing a region \fIwidth\fR pixels wide, \fIheight\fR pixels tall, at the specified \fIx, y\fR coordinates. .PP \fBTtk_PadBox\fR returns a new box located inside the specified \fIparcel\fR, -shrunken according to the left, top, right, and bottom margins +shrunken according to the left, top, right, and bottom margins specified by \fIpadding\fR. .PP \fBTtk_ExpandBox\fR is the inverse of \fBTtk_PadBox\fR: it returns a new box surrounding the specified \fIparcel\fR, -expanded according to the left, top, right, and bottom margins +expanded according to the left, top, right, and bottom margins specified by \fIpadding\fR. .PP \fBTtk_PackBox\fR allocates a parcel \fIwidth\fR by \fIheight\fR @@ -149,7 +148,7 @@ pixels wide on the specified \fIside\fR of the \fIcavity\fR, and shrinks the \fIcavity\fR accordingly. .PP \fBTtk_StickBox\fR places a box with the requested \fIwidth\fR -and \fIheight\fR inside the \fIparcel\fR according to the +and \fIheight\fR inside the \fIparcel\fR according to the \fIsticky\fR bits. .PP \fBTtk_PlaceBox\fR combines \fBTtk_PackBox\fR and \fBTtk_StickBox\fR: @@ -164,20 +163,21 @@ specified \fIanchor\fR option. \fBTtk_BoxContains\fR tests if the specified \fIx, y\fR coordinate lies within the rectangular region \fIbox\fR. .SH "PADDDING" -The \fBTtk_Padding\fR structure is used to represent +.PP +The \fBTtk_Padding\fR structure is used to represent borders, internal padding, and external margins: .CS typedef struct { - short left; - short top; - short right; - short bottom; -} Ttk_Padding; + short \fIleft\fR; + short \fItop\fR; + short \fIright\fR; + short \fIbottom\fR; +} \fBTtk_Padding\fR; .CE -.PP +.PP \fBTtk_MakePadding\fR is a convenience routine that contsructs a \fBTtk_Padding\fR structure with the specified left, top, right, and bottom -components. +components. .PP \fBTtk_UniformPadding\fR constructs a \fBTtk_Padding\fR structure with all components equal to the specified \fIborder\fR. @@ -200,6 +200,7 @@ This is typically used in element geometry procedures to simulate a .QW pressed-in look for pushbuttons. .SH "CONVERSION ROUTINES" +.PP \fBTtk_GetPaddingFromObj\fR converts the string in \fIobjPtr\fR to a \fBTtk_Padding\fR structure. The string representation is a list of diff --git a/doc/ttk_Theme.3 b/doc/ttk_Theme.3 index fb16978..86b84da 100644 --- a/doc/ttk_Theme.3 +++ b/doc/ttk_Theme.3 @@ -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_Theme.3,v 1.1 2006/10/31 01:42:25 hobbs Exp $ +'\" RCS: @(#) $Id: ttk_Theme.3,v 1.1.4.1 2010/08/26 02:06:09 hobbs Exp $ '\" .so man.macros .TH Ttk_CreateTheme 3 8.5 Tk "Tk Themed Widget" @@ -28,7 +28,7 @@ inherit elements and layouts. The name of the theme. .BE .SH DESCRIPTION - +.\" TODO - Document these functions better! .SH "SEE ALSO" Ttk_RegisterLayout, Ttk_BuildLayout .\" .SH KEYWORDS diff --git a/doc/ttk_button.n b/doc/ttk_button.n index a3b7c89..c6807bf 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.11.2.2 2009/04/30 13:52:55 dkf Exp $ +'\" RCS: @(#) $Id: ttk_button.n,v 1.11.2.3 2010/08/26 02:06:09 hobbs Exp $ '\" .so man.macros .TH ttk::button n 8.5 Tk "Tk Themed Widget" @@ -56,12 +56,17 @@ in the style. .\" .OP \-padding padding Padding .\" .OP \-relief relief Relief .SH "WIDGET COMMAND" +.PP In addition to the standard \fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR commands, buttons support the following additional widget commands: .TP \fIpathName \fBinvoke\fR Invokes the command associated with the button. +.SH "STANDARD STYLES" +.PP +\fBTtk::button\fR widgets support the \fBToolbutton\fR style in all standard +themes, which is useful for creating widgets for toolbars. .SH "COMPATIBILITY OPTIONS" .OP \-state state State May be set to \fBnormal\fR or \fBdisabled\fR to control the @@ -75,5 +80,4 @@ ttk::widget(n), button(n) widget, button, default, command '\" Local Variables: '\" mode: nroff -'\" fill-column: 78 '\" End: diff --git a/doc/ttk_checkbutton.n b/doc/ttk_checkbutton.n index 241022e..9edfa35 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.12.2.1 2008/05/11 00:31:01 patthoyts Exp $ +'\" RCS: @(#) $Id: ttk_checkbutton.n,v 1.12.2.2 2010/08/26 02:06:09 hobbs Exp $ '\" .so man.macros .TH ttk::checkbutton n 8.5 Tk "Tk Themed Widget" @@ -37,6 +37,7 @@ when the widget is selected. Defaults to \fB1\fR. The name of a global variable whose value is linked to the widget. Defaults to the widget pathname if not specified. .SH "WIDGET COMMAND" +.PP In addition to the standard \fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR commands, checkbuttons support the following additional @@ -53,6 +54,7 @@ Returns the result of the \fB\-command\fR. .\" Are these useful? They don't invoke the -command .\" Missing: flash. This is definitely not useful. .SH "WIDGET STATES" +.PP The widget does not respond to user input if the \fBdisabled\fR state is set. The widget sets the \fBselected\fR state whenever the linked \fB\-variable\fR is set to the widget's \fB\-onvalue\fR, @@ -64,7 +66,14 @@ linked \fB\-variable\fR is unset. or .QW indeterminate selection.) +.SH "STANDARD STYLES" +.PP +\fBTtk::checkbutton\fR widgets support the \fBToolbutton\fR style in all +standard themes, which is useful for creating widgets for toolbars. .SH "SEE ALSO" ttk::widget(n), ttk::radiobutton(n), checkbutton(n) .SH "KEYWORDS" widget, button, toggle, check, option +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_combobox.n b/doc/ttk_combobox.n index de025d0..d8603e1 100644 --- a/doc/ttk_combobox.n +++ b/doc/ttk_combobox.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_combobox.n,v 1.15.2.1 2008/05/11 00:31:01 patthoyts Exp $ +'\" RCS: @(#) $Id: ttk_combobox.n,v 1.15.2.2 2010/08/26 02:06:09 hobbs Exp $ '\" .so man.macros .TH ttk::combobox n 8.5 Tk "Tk Themed Widget" @@ -15,6 +15,7 @@ ttk::combobox \- text field with popdown selection list \fBttk::combobox\fR \fIpathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION +.PP 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. @@ -29,7 +30,7 @@ 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. +Must be 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 @@ -55,14 +56,16 @@ Specifies the list of values to display in the drop-down listbox. Specifies an integer value indicating the desired width of the entry window, 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. -.TP -\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? -Modify or query widget options. -See \fIttk::widget(n)\fR. +.PP +The following subcommands are possible for combobox widgets: +'\".TP +'\"\fIpathName \fBcget\fR \fIoption\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 \fBcurrent\fR ?\fInewIndex\fR? If \fInewIndex\fR is supplied, sets the combobox value @@ -72,31 +75,39 @@ Otherwise, returns the index of the current value in the list of .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. -See \fIttk::widget(n)\fR. -.TP -\fIpathName \fBinstate \fIstateSpec\fR ?\fIscript\fR? -Test the widget state. -See \fIttk::widget(n)\fR. +'\".TP +'\"\fIpathName \fBidentify \fIx y\fR +'\"Returns the name of the element at position \fIx\fR, \fIy\fR. +'\"See \fIttk::widget(n)\fR. +'\".TP +'\"\fIpathName \fBinstate \fIstateSpec\fR ?\fIscript\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. +'\".TP +'\"\fIpathName \fBstate\fR ?\fIstateSpec\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 \fBttk::entry\fR +widget subcommands (see \fIttk::entry(n)\fR for details): .DS .ta 5.5c 11c \fBbbox\fR \fBdelete\fR \fBicursor\fR \fBindex\fR \fBinsert\fR \fBselection\fR \fBxview\fR .DE +The combobox widget also supports the following generic \fBttk::widget\fR +widget subcommands (see \fIttk::widget(n)\fR for details): +.DS +.ta 5.5c 11c +\fBcget\fR \fBconfigure\fR \fBidentify\fR +\fBinstate\fR \fBstate\fR +.DE .SH "VIRTUAL EVENTS" +.PP The combobox widget generates a \fB<<ComboboxSelected>>\fR virtual event when the user selects an element from the list of values. If the selection action unposts the listbox, @@ -105,3 +116,6 @@ this event is delivered after the listbox is unposted. ttk::widget(n), ttk::entry(n) .SH KEYWORDS choice, entry, list box, text box, widget +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_entry.n b/doc/ttk_entry.n index 2be5714..6184fa6 100644 --- a/doc/ttk_entry.n +++ b/doc/ttk_entry.n @@ -7,7 +7,7 @@ '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" '\" SOURCE: entry.n, r1.12 -'\" RCS: @(#) $Id: ttk_entry.n,v 1.11 2008/01/29 15:38:00 dkf Exp $ +'\" RCS: @(#) $Id: ttk_entry.n,v 1.11.2.1 2010/08/26 02:06:09 hobbs Exp $ '\" .so man.macros .TH ttk::entry n 8.5 Tk "Tk Themed Widget" @@ -88,6 +88,7 @@ in average-size characters of the widget's font. .\" Not in ttk: If the value is less than or equal to zero, the widget picks a .\" Not in ttk: size just large enough to hold its current text. .SH NOTES +.PP A portion of the entry may be selected as described below. If an entry is exporting its selection (see the \fBexportSelection\fR option), then it will observe the standard X11 protocols for handling the @@ -105,6 +106,7 @@ the standard \fBxScrollCommand\fR mechanism for interacting with scrollbars (see the description of the \fBxScrollCommand\fR option for details). .SH "INDICES" +.PP Many of the \fBentry\fR widget commands take one or more indices as arguments. An index specifies a particular character in the entry's string, in any of the following ways: @@ -132,15 +134,15 @@ Indicates the character just after the last one in the selection. It is an error to use this form if the selection is not in the entry window. .LP -Abbreviations may be used for any of the forms above, e.g. +Abbreviations may be used for any of the forms above, e.g.\| .QW \fBe\fR or -.QW \fBsel.f\fR . +.QW \fBsel.l\fR . In general, out-of-range indices are automatically rounded to the nearest legal value. .SH "WIDGET COMMAND" .PP -The following commands are possible for entry widgets: +The following subcommands are possible for entry widgets: .TP \fIpathName \fBbbox \fIindex\fR Returns a list of four numbers describing the bounding box of the @@ -151,14 +153,14 @@ the upper-left corner of the screen area covered by the character the width and height of the character, in pixels. The bounding box may refer to a region outside the visible area of the window. -.TP -\fIpathName \fBcget\fR \fIoption\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 \fBcget\fR \fIoption\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 \fBdelete \fIfirst \fR?\fIlast\fR? Delete one or more elements of the entry. @@ -175,10 +177,10 @@ Returns the entry's string. \fIpathName \fBicursor \fIindex\fR Arrange for the insert cursor to be displayed just before the character given by \fIindex\fR. Returns the empty string. -.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. +'\".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. .TP \fIpathName \fBindex\fI index\fR Returns the numerical index corresponding to \fIindex\fR. @@ -186,10 +188,10 @@ Returns the numerical index corresponding to \fIindex\fR. \fIpathName \fBinsert \fIindex string\fR Insert \fIstring\fR just before the character indicated by \fIindex\fR. Returns the empty string. -.TP -\fIpathName \fBinstate \fIstatespec\fR ?\fIscript\fR? -Test the widget state. -See \fIttk::widget(n)\fR. +'\".TP +'\"\fIpathName \fBinstate \fIstatespec\fR ?\fIscript\fR? +'\"Test the widget state. +'\"See \fIttk::widget(n)\fR. .TP \fIpathName \fBselection \fIoption arg\fR This command is used to adjust the selection within an entry. It @@ -212,16 +214,17 @@ before \fIend\fR. If \fIend\fR refers to the same character as \fIstart\fR or an earlier one, then the entry's selection is cleared. .RE -.TP -\fIpathName \fBstate\fR ?\fIstateSpec\fR? -Modify or query the widget state. -See \fIttk::widget(n)\fR. +'\".TP +'\"\fIpathName \fBstate\fR ?\fIstateSpec\fR? +'\"Modify or query the widget state. +'\"See \fIttk::widget(n)\fR. .TP \fIpathName \fBvalidate\fR Force revalidation, independent of the conditions specified by the \fB\-validate\fR option. Returns 0 if validation fails, 1 if it succeeds. Sets or clears the \fBinvalid\fR state accordingly. +See \fBVALIDATION\fR below for more details. .TP \fIpathName \fBxview \fIargs\fR This command is used to query and change the horizontal position of the @@ -261,10 +264,20 @@ If \fInumber\fR is negative then characters farther to the left become visible; if it is positive then characters farther to the right become visible. .RE +.PP +The entry widget also supports the following generic \fBttk::widget\fR +widget subcommands (see \fIttk::widget(n)\fR for details): +.DS +.ta 5.5c 11c +\fBcget\fR \fBconfigure\fR \fBidentify\fR +\fBinstate\fR \fBstate\fR +.DE .SH VALIDATION +.PP The \fB\-validate\fR, \fB\-validatecommand\fR, and \fB\-invalidcommand\fR options are used to enable entry widget validation. .SS "VALIDATION MODES" +.PP There are two main validation modes: \fIprevalidation\fR, in which the \fB\-validatecommand\fR is evaluated prior to each edit and the return value is used to determine whether to accept @@ -274,6 +287,7 @@ evaluated to determine whether the current value is valid. .PP The \fB\-validate\fR option determines when validation occurs; it may be set to any of the following values: +.RS .IP \fBnone\fR Default. This means validation will only occur when specifically requested by the \fBvalidate\fR widget command. @@ -290,6 +304,7 @@ The entry is revalidated when the entry receives focus. The entry is revalidated when the entry loses focus. .IP \fBall\fR Validation is performed for all above conditions. +.RE .PP The \fB\-invalidcommand\fR is evaluated whenever the \fB\-validatecommand\fR returns a false value. @@ -305,10 +320,12 @@ regardless of the value returned by the \fB\-validatecommand\fR. If \fB\-validatecommand\fR is empty (the default), validation always succeeds. .SS "VALIDATION SCRIPT SUBSTITUTIONS" +.PP It is possible to perform percent substitutions on the -\fB\-validatecommand\fR and \fBinvalidCommand\fR, +\fB\-validatecommand\fR and \fB\-invalidcommand\fR, just as in a \fBbind\fR script. The following substitutions are recognized: +.RS .IP \fB%d\fR Type of action: 1 for \fBinsert\fR prevalidation, 0 for \fBdelete\fR prevalidation, @@ -329,8 +346,9 @@ The validation condition that triggered the callback (\fBkey\fR, \fBfocusin\fR, \fBfocusout\fR, or \fBforced\fR). .IP \fB%W\fR The name of the entry widget. +.RE .SS "DIFFERENCES FROM TK ENTRY WIDGET VALIDATION" -.IP \(bu +.PP The standard Tk entry widget automatically disables validation (by setting \fB\-validate\fR to \fBnone\fR) if the \fB\-validatecommand\fR or \fB\-invalidcommand\fR modifies @@ -338,53 +356,54 @@ the entry's value. The Tk themed entry widget only disables validation if one of the validation scripts raises an error, or if \fB\-validatecommand\fR does not return a valid boolean value. -(Thus, it is not necessary to reenable validation after +(Thus, it is not necessary to re-enable validation after modifying the entry value in a validation script). -.IP \(bu -The standard entry widget invokes validation whenever the linked +.PP +In addition, the standard entry widget invokes validation whenever the linked \fB\-textvariable\fR is modified; the Tk themed entry widget does not. .SH "DEFAULT BINDINGS" +.PP The entry widget's default bindings enable the following behavior. In the descriptions below, .QW word refers to a contiguous group of letters, digits, or .QW _ characters, or any single character other than these. -.IP \(bu +.IP \0\(bu 4 Clicking mouse button 1 positions the insert cursor just before the character underneath the mouse cursor, sets the input focus to this widget, and clears any selection in the widget. Dragging with mouse button 1 down strokes out a selection between the insert cursor and the character under the mouse. -.IP \(bu +.IP \0\(bu 4 Double-clicking with mouse button 1 selects the word under the mouse and positions the insert cursor at the end of the word. Dragging after a double click strokes out a selection consisting of whole words. -.IP \(bu +.IP \0\(bu 4 Triple-clicking with mouse button 1 selects all of the text in the entry and positions the insert cursor at the end of the line. -.IP \(bu +.IP \0\(bu 4 The ends of the selection can be adjusted by dragging with mouse button 1 while the Shift key is down. If the button is double-clicked before dragging then the selection will be adjusted in units of whole words. -.IP \(bu +.IP \0\(bu 4 Clicking mouse button 1 with the Control key down will position the insert cursor in the entry without affecting the selection. -.IP \(bu +.IP \0\(bu 4 If any normal printing characters are typed in an entry, they are inserted at the point of the insert cursor. -.IP \(bu +.IP \0\(bu 4 The view in the entry can be adjusted by dragging with mouse button 2. If mouse button 2 is clicked without moving the mouse, the selection is copied into the entry at the position of the mouse cursor. -.IP \(bu +.IP \0\(bu 4 If the mouse is dragged out of the entry on the left or right sides while button 1 is pressed, the entry will automatically scroll to make more text visible (if there is more text off-screen on the side where the mouse left the window). -.IP \(bu +.IP \0\(bu 4 The Left and Right keys move the insert cursor one character to the left or right; they also clear any selection in the entry. If Left or Right is typed with the Shift key down, then the insertion @@ -393,38 +412,39 @@ Control-Left and Control-Right move the insert cursor by words, and Control-Shift-Left and Control-Shift-Right move the insert cursor by words and also extend the selection. Control-b and Control-f behave the same as Left and Right, respectively. -.IP \(bu +.IP \0\(bu 4 The Home key and Control-a move the insert cursor to the beginning of the entry and clear any selection in the entry. Shift-Home moves the insert cursor to the beginning of the entry and extends the selection to that point. -.IP \(bu +.IP \0\(bu 4 The End key and Control-e move the insert cursor to the end of the entry and clear any selection in the entry. Shift-End moves the cursor to the end and extends the selection to that point. -.IP \(bu +.IP \0\(bu 4 Control-/ selects all the text in the entry. -.IP \(bu +.IP \0\(bu 4 Control-\e clears any selection in the entry. -.IP \(bu +.IP \0\(bu 4 The standard Tk <<Cut>>, <<Copy>>, <<Paste>>, and <<Clear>> virtual events operate on the selection in the expected manner. -.IP \(bu +.IP \0\(bu 4 The Delete key deletes the selection, if there is one in the entry. If there is no selection, it deletes the character to the right of the insert cursor. -.IP \(bu +.IP \0\(bu 4 The BackSpace key and Control-h delete the selection, if there is one in the entry. If there is no selection, it deletes the character to the left of the insert cursor. -.IP \(bu +.IP \0\(bu 4 Control-d deletes the character to the right of the insert cursor. -.IP \(bu +.IP \0\(bu 4 Control-k deletes all the characters to the right of the insertion cursor. .SH "WIDGET STATES" +.PP In the \fBdisabled\fR state, the entry cannot be edited and the text cannot be selected. In the \fBreadonly\fR state, @@ -448,3 +468,6 @@ and clears it whenever validation succeeds. ttk::widget(n), entry(n) .SH KEYWORDS entry, widget, text field +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_frame.n b/doc/ttk_frame.n index f9acc02..c40edd1 100644 --- a/doc/ttk_frame.n +++ b/doc/ttk_frame.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_frame.n,v 1.9.2.1 2008/05/11 00:31:01 patthoyts Exp $ +'\" RCS: @(#) $Id: ttk_frame.n,v 1.9.2.2 2010/08/26 02:06:09 hobbs Exp $ '\" .so man.macros .TH ttk::frame n 8.5 Tk "Tk Themed Widget" @@ -15,6 +15,7 @@ ttk::frame \- Simple container widget \fBttk::frame\fR \fIpathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION +.PP A \fBttk::frame\fR widget is a container, used to group other widgets together. .SO ttk_widget @@ -36,10 +37,12 @@ If specified, the widget's requested width in pixels. .OP \-height height Height If specified, the widget's requested height in pixels. .SH "WIDGET COMMAND" +.PP Supports the standard widget commands \fBconfigure\fR, \fBcget\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR; see \fIttk::widget(n)\fR. .SH "NOTES" +.PP Note that if the \fBpack\fR, \fBgrid\fR, or other geometry managers are used to manage the children of the \fBframe\fR, by the GM's requested size will normally take precedence @@ -50,3 +53,6 @@ to change this. ttk::widget(n), ttk::labelframe(n), frame(n) .SH "KEYWORDS" widget, frame, container +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_image.n b/doc/ttk_image.n index 0c38e94..0d8ea69 100644 --- a/doc/ttk_image.n +++ b/doc/ttk_image.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_image.n,v 1.12.2.1 2009/05/14 00:53:04 patthoyts Exp $ +'\" RCS: @(#) $Id: ttk_image.n,v 1.12.2.2 2010/08/26 02:06:09 hobbs Exp $ '\" .so man.macros .TH ttk_image n 8.5 Tk "Tk Themed Widget" @@ -15,6 +15,7 @@ ttk_image \- Define an element based on an image \fBttk::style element create \fIname\fR \fBimage\fR \fIimageSpec\fR ?\fIoptions\fR? .BE .SH DESCRIPTION +.PP The \fIimage\fR element factory creates a new element in the current theme whose visual appearance is determined by Tk images. @@ -24,6 +25,7 @@ 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 +.PP Valid \fIoptions\fR are: .TP \fB\-border\fR \fIpadding\fR @@ -52,6 +54,7 @@ or Specifies a minimum width for the element. If less than zero, the base image's width is used as a default. .SH "IMAGE STRETCHING" +.PP 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) @@ -63,6 +66,7 @@ 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" +.PP .CS set img1 [image create photo \-file button.png] set img2 [image create photo \-file button-pressed.png] @@ -75,3 +79,6 @@ style element create Button.button image \e ttk::intro(n), ttk::style(n), ttk_vsapi(n), image(n), photo(n) .SH KEYWORDS style, theme, appearance, pixmap theme, image +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_intro.n b/doc/ttk_intro.n index 912a5c0..81a1c7b 100644 --- a/doc/ttk_intro.n +++ b/doc/ttk_intro.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_intro.n,v 1.10.2.1 2010/03/09 04:20:56 hobbs Exp $ +'\" RCS: @(#) $Id: ttk_intro.n,v 1.10.2.2 2010/08/26 02:06:09 hobbs Exp $ '\" .so man.macros .TH ttk::intro n 8.5 Tk "Tk Themed Widget" @@ -13,6 +13,7 @@ ttk::intro \- Introduction to the Tk theme engine .BE .SH "OVERVIEW" +.PP 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. @@ -24,22 +25,24 @@ maintaining the widget state and invoking callbacks; all aspects of the widget's appearance are controlled by the style of the widget (i.e. the style of the elements of the widget). .SH "THEMES" +.PP 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 ...) +isolate platform differences (X11 vs. classic Windows vs. XP vs. Aqua ...) .IP \(bu -Adapt to display limitations (low-color, grayscale, monochrome, tiny screens) +adapt to display limitations (low-color, grayscale, monochrome, tiny screens) .IP \(bu -Accessibility (high contrast, large type) +accessibility (high contrast, large type) .IP \(bu -Application suite branding +application suite branding .IP \(bu -Blend in with the rest of the desktop (Gnome, KDE, Java) +blend in with the rest of the desktop (Gnome, KDE, Java) .IP \(bu -And, of course: eye candy. +and, of course: eye candy. .SH "ELEMENTS" +.PP 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. @@ -61,14 +64,15 @@ For example, the \fBtext\fR element \fB\-underline\fR, and \fB\-width\fR options. The value of an element option is taken from: .IP \(bu -An option of the same name and type in the widget containing the element; +an option of the same name and type in the widget containing the element; .IP \(bu -A dynamic setting specified by \fBstyle map\fR and the current state; +a dynamic setting specified by \fBstyle map\fR and the current state; .IP \(bu -The default setting specified by \fBstyle configure\fR; or +the default setting specified by \fBstyle configure\fR; or .IP \(bu -The element's built-in default value for the option. +the element's built-in default value for the option. .SH "LAYOUTS" +.PP 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 @@ -77,9 +81,10 @@ 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 +For example, the layout for a horizontal scrollbar is: +.PP .CS -ttk::style layout Horizontal.TScrollbar { +ttk::\fBstyle layout\fR Horizontal.TScrollbar { Scrollbar.trough \-children { Scrollbar.leftarrow \-side left \-sticky w Scrollbar.rightarrow \-side right \-sticky e @@ -87,10 +92,12 @@ ttk::style layout Horizontal.TScrollbar { } } .CE +.PP By default, the layout for a widget is the same as its class name. Some widgets may override this (for example, the \fBttk::scrollbar\fR widget chooses different layouts based on the \fB\-orient\fR option). .SH "STATES" +.PP 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 @@ -112,6 +119,7 @@ exclamation point indicating that the bit is cleared instead. .PP For example, the class bindings for the \fBttk::button\fR widget are: +.PP .CS bind TButton <Enter> { %W state active } bind TButton <Leave> { %W state !active } @@ -121,6 +129,7 @@ bind TButton <Button1-Enter> { %W state pressed } bind TButton <ButtonRelease-1> \e { %W instate {pressed} { %W state !pressed ; %W invoke } } .CE +.PP 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, @@ -133,28 +142,31 @@ Finally, when the mouse button is released, the widget's 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 +'\" Note to self: rewrite that paragraph. It's horrible. .SH "STYLES" +.PP Each widget is associated with a \fIstyle\fR, which specifies values for element options. 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: +.PP .CS -ttk::style configure TButton \e +ttk::\fBstyle configure\fR TButton \e \-background #d9d9d9 \e \-foreground black \e \-relief raised \e ; .CE +.PP 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 option settings for a particular style: +.PP .CS -ttk::style map TButton \e +ttk::\fBstyle map\fR TButton \e \-background [list disabled #d9d9d9 active #ececec] \e \-foreground [list disabled #a3a3a3] \e \-relief [list {pressed !disabled} sunken] \e @@ -162,3 +174,6 @@ ttk::style map TButton \e .CE .SH "SEE ALSO" ttk::widget(n), ttk::style(n) +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_label.n b/doc/ttk_label.n index 6592c08..3987585 100644 --- a/doc/ttk_label.n +++ b/doc/ttk_label.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_label.n,v 1.9.2.1 2008/05/11 00:31:01 patthoyts Exp $ +'\" RCS: @(#) $Id: ttk_label.n,v 1.9.2.2 2010/08/26 02:06:09 hobbs Exp $ '\" .so man.macros .TH ttk::label n 8.5 Tk "Tk Themed Widget" @@ -15,6 +15,7 @@ ttk::label \- Display a text string and/or image \fBttk::label\fR \fIpathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION +.PP A \fBttk::label\fR widget displays a textual label and/or image. The label may be linked to a Tcl variable to automatically change the displayed text. @@ -68,8 +69,12 @@ then automatic wrapping is not performed; otherwise the text is split into lines such that no line is longer than the specified value. .SH "WIDGET COMMAND" +.PP Supports the standard widget commands \fBconfigure\fR, \fBcget\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR; see \fIttk::widget(n)\fR. .SH "SEE ALSO" ttk::widget(n), label(n) +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_labelframe.n b/doc/ttk_labelframe.n index 11681d6..44f2d4b 100644 --- a/doc/ttk_labelframe.n +++ b/doc/ttk_labelframe.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_labelframe.n,v 1.9.2.1 2008/05/11 00:31:03 patthoyts Exp $ +'\" RCS: @(#) $Id: ttk_labelframe.n,v 1.9.2.2 2010/08/26 02:06:09 hobbs Exp $ '\" .so man.macros .TH ttk::labelframe n 8.5 Tk "Tk Themed Widget" @@ -15,6 +15,7 @@ ttk::labelframe \- Container widget with optional label \fBttk::labelframe\fR \fIpathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION +.PP A \fBttk::labelframe\fR widget is a container used to group other widgets together. It has an optional label, which may be a plain text string or another widget. @@ -64,6 +65,7 @@ If specified, the widget's requested height in pixels. (See \fIttk::frame(n)\fR for further notes on \fB\-width\fR and \fB\-height\fR). .SH "WIDGET COMMAND" +.PP Supports the standard widget commands \fBconfigure\fR, \fBcget\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR; see \fIttk::widget(n)\fR. @@ -71,3 +73,6 @@ see \fIttk::widget(n)\fR. ttk::widget(n), ttk::frame(n), labelframe(n) .SH "KEYWORDS" widget, frame, container, label, groupbox +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_menubutton.n b/doc/ttk_menubutton.n index a9baf7d..8552c6d 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.9.2.1 2008/05/11 00:31:03 patthoyts Exp $ +'\" RCS: @(#) $Id: ttk_menubutton.n,v 1.9.2.2 2010/08/26 02:06:09 hobbs Exp $ '\" .so man.macros .TH ttk::menubutton n 8.5 Tk "Tk Themed Widget" @@ -15,6 +15,7 @@ ttk::menubutton \- Widget that pops down a menu when pressed \fBttk::menubutton\fR \fIpathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION +.PP A \fBttk::menubutton\fR widget displays a textual label and/or image, and displays a menu when pressed. .SO ttk_widget @@ -38,10 +39,18 @@ menubutton. .\" .OP \-anchor anchor Anchor .\" .OP \-padding padding Pad .SH "WIDGET COMMAND" +.PP Menubutton widgets support the standard \fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR methods. No other widget methods are used. +.SH "STANDARD STYLES" +.PP +\fBTtk::menubutton\fR widgets support the \fBToolbutton\fR style in all +standard themes, which is useful for creating widgets for toolbars. .SH "SEE ALSO" ttk::widget(n), menu(n), menubutton(n) .SH "KEYWORDS" widget, button, menu +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_notebook.n b/doc/ttk_notebook.n index e8f8dbe..69c124a 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.12.2.1 2008/05/11 00:31:03 patthoyts Exp $ +'\" RCS: @(#) $Id: ttk_notebook.n,v 1.12.2.2 2010/08/26 02:06:09 hobbs Exp $ '\" .so man.macros .TH ttk::notebook n 8.5 Tk "Tk Themed Widget" @@ -13,10 +13,10 @@ ttk::notebook \- Multi-paned container widget .SH SYNOPSIS .nf -\fBttk::notebook\fR \fIpathName \fR?\fIoptions...\fR? +\fBttk::notebook\fR \fIpathname \fR?\fIoptions...\fR? .br -\fIpathName \fBadd\fR \fIwindow\fR ?\fIoptions...\fR? -\fIpathName \fBinsert\fR \fIindex\fR \fIwindow\fR ?\fIoptions...\fR? +\fIpathname \fBadd\fR \fIwindow\fR ?\fIoptions...\fR? +\fIpathname \fBinsert\fR \fIindex\fR \fIwindow\fR ?\fIoptions...\fR? .fi .BE .SH DESCRIPTION @@ -124,9 +124,18 @@ The tab will not be displayed, but the associated window remains managed by the notebook and its configuration remembered. Hidden tabs may be restored with the \fBadd\fR command. .TP -\fIpathName \fBidentify\fR \fIx y\fR -Returns the name of the element at position \fIx\fR, \fIy\fR. -See \fIttk::widget(n)\fR. +\fIpathname \fBidentify\fR \fIcomponent\fR \fIx\fR \fIy\fR +Returns the name of the element under the point given by \fIx\fR and \fIy\fR, +or the empty string if no component is present at that location. +The following subcommands are supported: +.RS +.TP +\fIpathname \fBidentify\fR \fBelement\fR \fIx\fR \fIy\fR +Returns the name of the element at the specified location. +.TP +\fIpathname \fBidentify\fR \fBtab\fR \fIx\fR \fIy\fR +Returns the index of the tab at the specified location. +.RE .TP \fIpathname \fBindex\fR \fItabid\fR Returns the numeric index of the tab specified by \fItabid\fR, @@ -201,3 +210,6 @@ ttk::notebook::enableTraversal .nb ttk::widget(n), grid(n) .SH "KEYWORDS" pane, tab +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_panedwindow.n b/doc/ttk_panedwindow.n index 5955f56..89708ad 100644 --- a/doc/ttk_panedwindow.n +++ b/doc/ttk_panedwindow.n @@ -3,26 +3,27 @@ '\" '\" 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.15.2.1 2008/05/11 00:31:03 patthoyts Exp $ -'\" +'\" +'\" RCS: @(#) $Id: ttk_panedwindow.n,v 1.15.2.2 2010/08/26 02:06:09 hobbs Exp $ +'\" .so man.macros -.TH ttk::panedwindow n 8.5 Tk "Tk Themed Widget" +.TH ttk::panedwindow n 8.5.9 Tk "Tk Themed Widget" .BS .SH NAME ttk::panedwindow \- Multi-pane container window .SH SYNOPSIS .nf -\fBttk::panedwindow\fR \fIpathName \fR?\fIoptions\fR? +\fBttk::panedwindow\fR \fIpathname \fR?\fIoptions\fR? .br -\fIpathName \fBadd\fR \fIwindow\fR ?\fIoptions...\fR? -\fIpathName \fBinsert\fR \fIindex\fR \fIwindow\fR ?\fIoptions...\fR? +\fIpathname \fBadd\fR \fIwindow\fR ?\fIoptions...\fR? +\fIpathname \fBinsert\fR \fIindex\fR \fIwindow\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 -of the subwindows by dragging the sash between panes. +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. .SO ttk_widget \-class \-cursor \-takefocus \-style @@ -33,12 +34,12 @@ 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, +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, +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. @@ -49,45 +50,57 @@ 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, +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 +\fIpathname\fR \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. .TP -\fIpathname \fBforget\fR \fIpane\fR +\fIpathname\fR \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. .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. +\fIpathname\fR \fBidentify\fR \fIcomponent\fR \fIx\fR \fIy\fR +Returns the name of the element under the point given by \fIx\fR and \fIy\fR, +or the empty string if no component is present at that location. +If \fIcomponent\fR is omitted, it defaults to \fBsash\fR. +The following subcommands are supported: +.RS +.TP +\fIpathname\fR \fBidentify\fR \fBelement\fR \fIx\fR \fIy\fR +Returns the name of the element at the specified location. .TP -\fIpathname \fBinsert\fR \fIpos\fR \fIsubwindow\fR \fIoptions...\fR +\fIpathname\fR \fBidentify\fR \fBsash\fR \fIx\fR \fIy\fR +Returns the index of the sash at the specified location. +.RE +.TP +\fIpathname\fR \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, +\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, +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 +\fIpathname\fR \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 +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 \fBpanes\fR +Returns the list of all windows managed by the widget. +.TP \fIpathname\fR \fBsashpos\fR \fIindex\fR ?\fInewpos\fR? -If \fInewpos\fR is specified, sets the position +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 +Sash positions are further constrained to be between 0 and the total size of the widget. .\" Full story: "total size" is either the -height (resp -width), .\" or the actual window height (resp actual window width), @@ -96,3 +109,6 @@ Returns the new position of sash number \fIindex\fR. .\" Full story: new position may be different than the requested position. .SH "SEE ALSO" ttk::widget(n), ttk::notebook(n), panedwindow(n) +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_progressbar.n b/doc/ttk_progressbar.n index 0b97176..af3e312 100644 --- a/doc/ttk_progressbar.n +++ b/doc/ttk_progressbar.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_progressbar.n,v 1.10.2.1 2008/05/11 00:31:03 patthoyts Exp $ +'\" RCS: @(#) $Id: ttk_progressbar.n,v 1.10.2.2 2010/08/26 02:06:09 hobbs Exp $ '\" .so man.macros .TH ttk::progressbar n 8.5 Tk "Tk Themed Widget" @@ -15,6 +15,7 @@ ttk::progressbar \- Provide progress feedback \fBttk::progressbar\fR \fIpathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION +.PP 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 @@ -56,6 +57,7 @@ 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" +.PP .TP \fIpathName \fBcget\fR \fIoption\fR Returns the current value of the specified \fIoption\fR; see \fIttk::widget(n)\fR. @@ -88,3 +90,6 @@ Stop autoincrement mode: cancels any recurring timer event initiated by \fIpathName \fBstart\fR. .SH "SEE ALSO" ttk::widget(n) +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_radiobutton.n b/doc/ttk_radiobutton.n index 0880a39..8cb341a 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.11.2.1 2008/05/11 00:31:03 patthoyts Exp $ +'\" RCS: @(#) $Id: ttk_radiobutton.n,v 1.11.2.2 2010/08/26 02:06:09 hobbs Exp $ '\" .so man.macros .TH ttk::radiobutton n 8.5 Tk "Tk Themed Widget" @@ -15,6 +15,7 @@ ttk::radiobutton \- Mutually exclusive option widget \fBttk::radiobutton\fR \fIpathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION +.PP \fBttk::radiobutton\fR widgets are used in groups to show or change a set of mutually-exclusive options. Radiobuttons are linked to a Tcl variable, @@ -36,6 +37,7 @@ when the widget is selected. The name of a global variable whose value is linked to the widget. Default value is \fB::selectedButton\fR. .SH "WIDGET COMMAND" +.PP In addition to the standard \fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR commands, radiobuttons support the following additional @@ -49,6 +51,7 @@ string if no \fB\-command\fR is specified. .\" Missing: select, deselect. Useful? .\" Missing: flash. This is definitely not useful. .SH "WIDGET STATES" +.PP The widget does not respond to user input if the \fBdisabled\fR state is set. The widget sets the \fBselected\fR state whenever the linked \fB\-variable\fR is set to the widget's \fB\-value\fR, @@ -60,7 +63,14 @@ linked \fB\-variable\fR is unset. or .QW indeterminate selection.) +.SH "STANDARD STYLES" +.PP +\fBTtk::radiobutton\fR widgets support the \fBToolbutton\fR style in all +standard themes, which is useful for creating widgets for toolbars. .SH "SEE ALSO" ttk::widget(n), ttk::checkbutton(n), radiobutton(n) .SH "KEYWORDS" widget, button, option +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_scale.n b/doc/ttk_scale.n index e9c8743..2358ddd 100644 --- a/doc/ttk_scale.n +++ b/doc/ttk_scale.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. .\" -.\" CVS: @(#) $Id: ttk_scale.n,v 1.1.4.1 2008/05/11 00:31:03 patthoyts Exp $ +.\" CVS: @(#) $Id: ttk_scale.n,v 1.1.4.2 2010/08/26 02:06:09 hobbs Exp $ .\" .so man.macros .TH ttk::scale n 8.5 Tk "Tk Themed Widget" @@ -15,6 +15,7 @@ ttk::scale \- Create and manipulate a scale widget \fBttk::scale \fIpathName \fR?\fIoptions...\fR? .BE .SH DESCRIPTION +.PP A \fBttk::scale\fR widget is typically used to control the numeric value of a linked variable that varies uniformly over some range. A scale displays a \fIslider\fR that can be moved along over a \fItrough\fR, with the relative @@ -49,6 +50,7 @@ value of the variable changes, the scale will update to reflect this value. Whenever the scale is manipulated interactively, the variable will be modified to reflect the scale's new value. .SH "WIDGET COMMAND" +.PP .TP \fIpathName \fBcget \fIoption\fR . @@ -84,6 +86,7 @@ named in the \fB\-variable\fR option) does not cause such clipping. . Modify or query the widget state; see \fIttk::widget(n)\fR. .SH "INTERNAL COMMANDS" +.PP .TP \fIpathName \fBcoords \fR?\fIvalue\fR? . diff --git a/doc/ttk_scrollbar.n b/doc/ttk_scrollbar.n index b42b160..eec877a 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.12.2.1 2008/05/11 00:31:03 patthoyts Exp $ +'\" RCS: @(#) $Id: ttk_scrollbar.n,v 1.12.2.2 2010/08/26 02:06:09 hobbs Exp $ '\" .so man.macros .TH ttk::scrollbar n 8.5 Tk "Tk Themed Widget" @@ -17,6 +17,7 @@ ttk::scrollbar \- Control the viewport of a scrollable widget \fBttk::scrollbar\fR \fIpathName \fR?\fIoptions...\fR? .BE .SH DESCRIPTION +.PP \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. @@ -48,6 +49,7 @@ or \fByview\fR (for vertical scrollbars). One of \fBhorizontal\fR or \fBvertical\fR. Specifies the orientation of the scrollbar. .SH "WIDGET COMMAND" +.PP .TP \fIpathName \fBcget\fR \fIoption\fR Returns the current value of the specified \fIoption\fR; see \fIttk::widget(n)\fR. @@ -75,6 +77,7 @@ Specifies the visible range to be displayed. \fIpathName \fBstate\fR ?\fIstateSpec\fR? Modify or query the widget state; see \fIttk::widget(n)\fR. .SH "INTERNAL COMMANDS" +.PP The following widget commands are used internally by the TScrollbar widget class bindings. .TP @@ -99,6 +102,7 @@ widget. If \fIx\fR and \fIy\fR refer to a point outside the trough, the closest point in the trough is used. .SH "SCROLLING COMMANDS" +.PP 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. @@ -134,12 +138,14 @@ is a slight overlap between the old and new views. become visible, or \-1, which means that the previous page should become visible. .SH "WIDGET STATES" +.PP 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 +.PP .CS set f [frame .f] ttk::scrollbar $f.hsb \-orient horizontal \-command [list $f.t xview] @@ -155,3 +161,6 @@ grid rowconfigure $f 0 \-weight 1 ttk::widget(n), scrollbar(n) .SH KEYWORDS scrollbar, widget +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_separator.n b/doc/ttk_separator.n index 9598b54..8aa91ea 100644 --- a/doc/ttk_separator.n +++ b/doc/ttk_separator.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_separator.n,v 1.8.2.1 2008/05/11 00:31:03 patthoyts Exp $ +'\" RCS: @(#) $Id: ttk_separator.n,v 1.8.2.2 2010/08/26 02:06:09 hobbs Exp $ '\" .so man.macros .TH ttk::separator n 8.5 Tk "Tk Themed Widget" @@ -15,6 +15,7 @@ ttk::separator \- Separator bar \fBttk::separator\fR \fIpathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION +.PP A \fBttk::separator\fR widget displays a horizontal or vertical separator bar. .SO ttk_widget @@ -26,6 +27,7 @@ bar. One of \fBhorizontal\fR or \fBvertical\fR. Specifies the orientation of the separator. .SH "WIDGET COMMAND" +.PP Separator widgets support the standard \fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR methods. No other widget methods are used. @@ -33,3 +35,6 @@ methods. No other widget methods are used. ttk::widget(n) .SH "KEYWORDS" widget, separator +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_sizegrip.n b/doc/ttk_sizegrip.n index 698f14d..304a56a 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.15.2.1 2008/05/11 00:31:03 patthoyts Exp $ +'\" RCS: @(#) $Id: ttk_sizegrip.n,v 1.15.2.2 2010/08/26 02:06:09 hobbs Exp $ '\" .so man.macros .TH ttk::sizegrip n 8.5 Tk "Tk Themed Widget" @@ -15,6 +15,7 @@ ttk::sizegrip \- Bottom-right corner resize widget \fBttk::sizegrip\fR \fIpathName \fR?\fIoptions\fR? .BE .SH DESCRIPTION +.PP A \fBttk::sizegrip\fR widget (also known as a \fIgrow box\fR) allows the user to resize the containing toplevel window by pressing and dragging the grip. @@ -23,10 +24,12 @@ by pressing and dragging the grip. \-style \-takefocus .SE .SH "WIDGET COMMAND" +.PP Sizegrip widgets support the standard \fBcget\fR, \fBconfigure\fR, \fBidentify\fR, \fBinstate\fR, and \fBstate\fR methods. No other widget methods are used. .SH "PLATFORM-SPECIFIC NOTES" +.PP On Mac OSX, toplevel windows automatically include a built-in size grip by default. Adding a \fBttk::sizegrip\fR there is harmless, since @@ -47,6 +50,7 @@ grid [\fBttk::sizegrip\fR $top.statusbar.grip] \e # ... optional: add horizontal scrollbar in $lastRow .CE .SH "BUGS" +.PP If the containing toplevel's position was specified relative to the right or bottom of the screen (e.g., @@ -62,3 +66,6 @@ resizing. ttk::widget(n) .SH "KEYWORDS" widget, sizegrip, grow box +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_spinbox.n b/doc/ttk_spinbox.n new file mode 100644 index 0000000..854c2d1 --- /dev/null +++ b/doc/ttk_spinbox.n @@ -0,0 +1,88 @@ +'\" +'\" Copyright (c) 2008 Pat Thoyts +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id: ttk_spinbox.n,v 1.2.2.2 2010/08/26 02:06:09 hobbs Exp $ +'\" +.so man.macros +.TH ttk::spinbox n 8.5.9 Tk "Tk Themed Widget" +.BS +.SH NAME +ttk::spinbox \- Selecting text field widget +.SH SYNOPSIS +\fBttk::spinbox\fR \fIpathName \fR?\fIoptions\fR? +.BE +.SH DESCRIPTION +.PP +A \fBttk::spinbox\fR widget is a \fBttk::entry\fR widget with built-in +up and down buttons that are used to either modify a numeric value or +to select among a set of values. The widget implements all the features +of the \fBttk::entry\fR widget including support of the +\fB\-textvariable\fR option to link the value displayed by the widget +to a Tcl variable. +.SO ttk_widget +\-class \-cursor \-style +\-takefocus \-xscrollcommand +.SE +.SO ttk_entry +\-validate \-validatecommand +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-from from From +A floating\-point value specifying the lowest value for the spinbox. This is +used in conjunction with \fI\-to\fR and \fI\-increment\fR to set a numerical +range. +.OP \-to to To +A floating\-point value specifying the highest permissible value for the +widget. See also \fI\-from\fR and \fI\-increment\fR. +range. +.OP \-increment increment Increment +A floating\-point value specifying the change in value to be applied each +time one of the widget spin buttons is pressed. The up button applies a +positive increment, the down button applies a negative increment. +.OP \-values values Values +This must be a Tcl list of values. If this option is set then this will +override any range set using the \fI\-from\fR, \fI\-to\fR and +\fI\-increment\fR options. The widget will instead use the values +specified beginning with the first value. +.OP \-wrap wrap Wrap +Must be a proper boolean value. If on, the spinbox will wrap around the +values of data in the widget. +.OP \-format format Format +Specifies an alternate format to use when setting the string value +when using the \fB\-from\fR and \fB\-to\fR range. +This must be a format specifier of the form \fB%<pad>.<pad>f\fR, +as it will format a floating-point number. +.OP \-command command Command +Specifies a Tcl command to be invoked whenever a spinbutton is invoked. +.SH "INDICES" +.PP +See the \fBttk::entry\fR manual for information about indexing characters. +.SH "VALIDATION" +.PP +See the \fBttk::entry\fR manual for information about using the +\fI\-validate\fR and \fI\-validatecommand\fR options. +.SH "WIDGET COMMAND" +.PP +The following subcommands are possible for spinbox widgets in addition to +the commands described for the \fBttk::entry\fR widget: +.TP +\fIpathName \fBcurrent \fIindex\fR +.TP +\fIpathName \fBget\fR +Returns the spinbox's current value. +.TP +\fIpathName \fBset \fIvalue\fR +Set the spinbox string to \fIvalue\fR. If a \fI\-format\fR option has +been configured then this format will be applied. If formatting fails +or is not set or the \fI\-values\fR option has been used then the value +is set directly. +.SH "SEE ALSO" +ttk::widget(n), ttk::entry(n), spinbox(n) +.SH KEYWORDS +entry, spinbox, widget, text field +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_style.n b/doc/ttk_style.n index b5d4121..a459e9a 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.13.2.1 2009/05/14 00:53:04 patthoyts Exp $ +'\" RCS: @(#) $Id: ttk_style.n,v 1.13.2.2 2010/08/26 02:06:09 hobbs Exp $ '\" .so man.macros .TH ttk::style n 8.5 Tk "Tk Themed Widget" @@ -15,9 +15,11 @@ ttk::style \- Manipulate style database \fBttk::style\fR \fIoption\fR ?\fIargs\fR? .BE .SH NOTES +.PP See also 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, which specifies the set of elements making up the widget and how they are arranged, along with dynamic and default @@ -28,6 +30,7 @@ this may be overridden by the \fB\-style\fR option. A \fItheme\fR is a collection of elements and styles which controls the overall look and feel of an application. .SH DESCRIPTION +.PP The \fBttk::style\fR command takes the following arguments: .TP \fBttk::style configure \fIstyle\fR ?\fI\-option\fR ?\fIvalue option value...\fR? ? @@ -86,9 +89,12 @@ though arbitrary Tcl code may appear. \fBttk::style theme names\fR Returns a list of all known themes. .TP -\fBttk::style theme use\fR \fIthemeName\fR -Sets the current theme to \fIthemeName\fR, and refreshes all widgets. +\fBttk::style theme use\fR ?\fIthemeName\fR? +Without an argument the result is the name of the current theme. +Otherwise this command sets the current theme to \fIthemeName\fR, +and refreshes all widgets. .SH LAYOUTS +.PP A \fIlayout\fR specifies a list of elements, each followed by one or more options specifying how to arrange the element. The layout mechanism uses a simplified version of the \fBpack\fR @@ -122,3 +128,6 @@ ttk::style layout Horizontal.TScrollbar { ttk::intro(n), ttk::widget(n), photo(n), ttk_image(n) .SH KEYWORDS style, theme, appearance +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_treeview.n b/doc/ttk_treeview.n index fbe84b1..50bd38c 100644 --- a/doc/ttk_treeview.n +++ b/doc/ttk_treeview.n @@ -4,17 +4,18 @@ '\" 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.17 2008/01/29 15:38:00 dkf Exp $ +'\" RCS: @(#) $Id: ttk_treeview.n,v 1.17.2.1 2010/08/26 02:06:09 hobbs Exp $ '\" .so man.macros -.TH ttk::treeview n 8.5 Tk "Tk Themed Widget" +.TH ttk::treeview n 8.5.9 Tk "Tk Themed Widget" .BS .SH NAME ttk::treeview \- hierarchical multicolumn data display widget .SH SYNOPSIS -\fBttk::treeview\fR \fIpathname \fR?\fIoptions\fR? +\fBttk::treeview \fIpathname \fR?\fIoptions\fR? .BE .SH DESCRIPTION +.PP 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. @@ -58,11 +59,8 @@ A list of column identifiers specifying which data columns are displayed and the order in which they appear, or the string \fB#all\fP. -.RS -.PP -If set to \fB#all\fP (the default), all columns are shown in the order -given. -.RE +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: @@ -98,20 +96,21 @@ The default is \fBtree headings\fR, i.e., show all elements. even if \fB\-show tree\fR is not specified. .RE .SH "WIDGET COMMAND" +.PP .TP -\fIpathname \fBbbox\fR \fIitem\fR ?\fIcolumn\fR? +\fIpathname \fBbbox \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 +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 +\fIpathname \fBcget \fIoption\fR Returns the current value of the specified \fIoption\fR; see \fIttk::widget(n)\fR. .TP -\fIpathname \fBchildren\fR \fIitem\fR ?\fInewchildren\fR? +\fIpathname \fBchildren \fIitem\fR ?\fInewchildren\fR? If \fInewchildren\fR is not specified, returns the list of children belonging to \fIitem\fR. .RS @@ -124,7 +123,7 @@ 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? +\fIpathname \fBcolumn \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. @@ -165,16 +164,17 @@ Use \fIpathname column #0\fR to configure the tree column. \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 +\fIpathname \fBdelete \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. .TP -\fIpathname \fBdetach\fR \fIitemList\fR +\fIpathname \fBdetach \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. +with the \fBmove\fR operation, +but will not be displayed until that is done. The root item may not be detached. See also: \fBdelete\fR. .TP @@ -187,7 +187,7 @@ 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? +\fIpathname \fBheading \fIcolumn\fR ?\fI\-option \fR?\fIvalue \-option value...\fR? Query or modify the heading options for the specified \fIcolumn\fR. Valid options are: .RS @@ -215,12 +215,35 @@ 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 +\fIpathname \fBidentify region \fIx y\fR +.RS +Returns one of: +.IP heading +Tree heading area; +use [\fBpathname identify column \fIx y\fR] +to determine the heading number. +.IP separator +Space between two column headings; +[\fBpathname identify column \fIx y\fR] +will return the display column identifier +of the heading to left of the separator. +.IP tree +The tree area. +.IP cell +A data cell. +.RE +\fIpathname \fBidentify item \fIx y\fR Returns the item ID of the item at position \fIy\fR. .TP -\fIpathname \fBidentify column\fR \fIx y\fR +\fIpathname \fBidentify column \fIx y\fR Returns the data column identifier of the cell at position \fIx\fR. The tree column has ID \fB#0\fR. +.TP +\fIpathname \fBidentify element \fIx y\fR +The element at position \fIx,y\fR. +.TP +\fIpathname \fBidentify row \fIx y\fR +Obsolescent synonym for \fIpathname \fBidentify item\fR. .PP See \fBCOLUMN IDENTIFIERS\fR for a discussion of display columns and data columns. @@ -229,7 +252,7 @@ and data columns. \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 +\fIpathname \fBinsert \fIparent index\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 @@ -253,7 +276,7 @@ See \fBITEM OPTIONS\fR for the list of available options. \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? +\fIpathname \fBitem \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. @@ -284,13 +307,13 @@ or \fB{}\fR if \fIitem\fR is at the top level of the hierarchy. 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 +\fIpathname \fBsee \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 within the visible portion of the tree. .TP -\fIpathname \fBselection\fR ?\fIselop\fR \fIitemList\fR? +\fIpathname \fBselection\fR ?\fIselop itemList\fR? If \fIselop\fR is not specified, returns the list of selected items. Otherwise, \fIselop\fR is one of the following: .RS @@ -308,9 +331,9 @@ 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 \fIitem\fR ?\fIcolumn\fR? ?\fIvalue\fR? With one argument, returns a dictionary of column/value pairs -for the specified \fIitem\fR. +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. @@ -339,7 +362,7 @@ The binding \fIscript\fR undergoes \fB%\fR-substitutions before evaluation; see \fBbind(n)\fR for details. .RE .TP -\fIpathName \fBtag configure\fR \fItagName\fR ?\fIoption\fR? ?\fIvalue option value...\fR? +\fIpathName \fBtag configure \fItagName\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. @@ -349,6 +372,26 @@ returns the value of that option With no additional arguments, returns a dictionary of the option settings for \fItagName\fR. See \fBTAG OPTIONS\fR for the list of available options. +.TP +\fIpathName \fBtag has \fItagName\fR ?\fIitem\fR? +If \fIitem\fR is specified, returns 1 or 0 +depending on whether the specified item has the named tag. +Otherwise, returns a list of all items which have +the specified tag. +.TP +\fIpathName \fBtag names\fR +Returns a list of all tags used by the widget. +.TP +\fIpathName \fBtag add\fR \fItag\fR \fIitems\fR +Adds the specified \fItag\fR to each of the listed \fIitems\fR. +If \fItag\fR is already present for a particular item, +then the \fB-tags\fR for that item are unchanged. +.TP +\fIpathName \fBtag remove\fR \fItag\fR ?\fIitems\fR? +Removes the specified \fItag\fR from each of the listed \fIitems\fR. +If \fIitems\fR is omitted, removes \fItag\fR from each item in the tree. +If \fItag\fR is not present for a particular item, +then the \fB-tags\fR for that item are unchanged. .RE .TP \fIpathName \fBxview \fIargs\fR @@ -357,6 +400,7 @@ Standard command for horizontal scrolling; see \fIwidget(n)\fR. \fIpathName \fByview \fIargs\fR Standard command for vertical scrolling; see \fIttk::widget(n)\fR. .SH "ITEM OPTIONS" +.PP The following item options may be specified for items in the \fBinsert\fR and \fBitem\fR widget commands. .OP \-text text Text @@ -380,6 +424,7 @@ 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. .SH "TAG OPTIONS" +.PP The following options may be specified on tags: .IP \fB\-foreground\fR Specifies the text foreground color. @@ -392,9 +437,10 @@ Specifies the font to use when drawing text. .\" ??? Maybe: .IP \-text .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 +.\" .PP +.\" \fI(@@@ TODO: sort out order of precedence for options)\fR .SH "COLUMN IDENTIFIERS" +.PP Column identifiers take any of the following forms: .IP \(bu A symbolic name from the list of \fB\-columns\fR. @@ -419,6 +465,7 @@ 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" +.PP The treeview widget generates the following virtual events. .IP <<TreeviewSelect>> Generated whenever the selection changes. @@ -434,3 +481,6 @@ to determine the affected item or items. '\" of the virtual event. .SH "SEE ALSO" ttk::widget(n), listbox(n), image(n), bind(n) +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_vsapi.n b/doc/ttk_vsapi.n index ef510dc..15f18fd 100644 --- a/doc/ttk_vsapi.n +++ b/doc/ttk_vsapi.n @@ -1,10 +1,10 @@ -'\" -*- nroff -*- +'\" '\" Copyright (c) 2008 Pat Thoyts '\" '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: ttk_vsapi.n,v 1.4.2.2 2009/05/14 00:53:04 patthoyts Exp $ +'\" RCS: @(#) $Id: ttk_vsapi.n,v 1.4.2.3 2010/08/26 02:06:09 hobbs Exp $ '\" .so man.macros .TH ttk_vsapi n 8.5 Tk "Tk Themed Widget" @@ -15,6 +15,7 @@ ttk_vsapi \- Define a Microsoft Visual Styles element \fBttk::style element create \fIname\fR \fBvsapi\fR \fIclassName\fR \fIpartId\fR ?\fIstateMap\fR? ?\fIoptions\fR? .BE .SH DESCRIPTION +.PP The \fIvsapi\fR element factory creates a new element in the current theme whose visual appearance is drawn using the Microsoft Visual Styles API which is reponsible for the themed styles @@ -27,6 +28,7 @@ the Visual Styles class and part as given in the Microsoft documentation. The \fIstateMap\fR may be provided to map ttk states to Visual Styles API states (see \fBSTATE MAP\fR). .SH "OPTIONS" +.PP Valid \fIoptions\fR are: .TP \fB\-padding\fR \fIpadding\fR @@ -51,6 +53,7 @@ be mixed with the \fI-padding\fR or \fI-margins\fR options. \fB\-height\fR \fIheight\fR Specifies the height of the element. See the comments for \fI-width\fR. .SH "STATE MAP" +.PP The \fIstateMap\fR parameter is a list of ttk states and the corresponding Visual Styles API state value. This permits the element appearence to respond to changes in the @@ -66,6 +69,7 @@ versions of the Windows Development Kit this is \fIvssym32.h\fR. If no \fIstateMap\fR parameter is given there is an implicit default map of {{} 1} .SH "EXAMPLE" +.PP Create a correctly themed close button by changing the layout of a \fBttk::button\fR(n). This uses the WINDOW part WP_SMALLCLOSEBUTTON and as documented the states CBS_DISABLED, CBS_HOT, CBS_NORMAL and @@ -95,3 +99,6 @@ pack [ttk::checkbutton .pin -style Explorer.Pin] ttk::intro(n), ttk::widget(n), ttk::style(n), ttk_image(n) .SH "KEYWORDS" style, theme, appearance, windows +'\" Local Variables: +'\" mode: nroff +'\" End: diff --git a/doc/ttk_widget.n b/doc/ttk_widget.n index 8b19f62..7c0ba88 100644 --- a/doc/ttk_widget.n +++ b/doc/ttk_widget.n @@ -1,13 +1,13 @@ '\" '\" 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.13.2.2 2009/05/14 00:53:04 patthoyts Exp $ -'\" +'\" +'\" RCS: @(#) $Id: ttk_widget.n,v 1.13.2.3 2010/08/26 02:06:09 hobbs Exp $ +'\" .so man.macros -.TH ttk::widget n 8.5 Tk "Tk Themed Widget" +.TH ttk::widget n 8.5.9 Tk "Tk Themed Widget" .BS .SH NAME ttk::widget \- Standard options and commands supported by Tk themed widgets @@ -18,11 +18,11 @@ This manual describes common widget options and commands. 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 +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: +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 @@ -32,16 +32,16 @@ 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. +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), +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" The following options are supported by widgets that -are controllable by a scrollbar. +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. @@ -56,12 +56,12 @@ 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. .PP -Typically the \fBxScrollCommand\fR option consists of the path name +Typically the \fBxScrollCommand\fR option consists of the path name of a \fBscrollbar\fR widget followed by .QW set , e.g. .QW ".x.scrollbar set" . -This will cause the scrollbar to be updated whenever the view in the +This will cause the scrollbar to be updated whenever the view in the window changes. .PP If this option is set to the empty string (the default), @@ -80,7 +80,7 @@ Specifies a text string to be displayed inside the widget 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 +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 @@ -94,7 +94,7 @@ 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: +Valid values are: .RS .IP text Display text only. @@ -111,8 +111,8 @@ 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 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" @@ -120,10 +120,9 @@ If zero or unspecified, the natural width of the text label is used. 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 +setting it changes the widget state, +but the \fBstate\fR widget command does not affect the \fB\-state\fR option. - .SH COMMANDS .TP \fIpathName \fBcget\fR \fIoption\fR @@ -133,36 +132,37 @@ by \fIoption\fR. \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); +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, +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, +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 -\fIpathName \fBidentify\fR \fIx y\fR -Returns the name of the element under the point given +\fIpathName \fBidentify\fR \fBelement\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 within any element. \fIx\fR and \fIy\fR are pixel coordinates relative to the widget. -.TP +Some widgets accept other \fBidentify\fR subcommands. +.TP \fIpathName \fBinstate\fR \fIstatespec\fR ?\fIscript\fR? Test the widget's state. -If \fIscript\fR is not specified, returns 1 if +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 .CS if {[\fIpathName\fR instate \fIstateSpec\fR]} \fIscript\fR .CE -.TP +.TP \fIpathName \fBstate\fR ?\fIstateSpec\fR? Modify or inquire widget state. -If \fIstateSpec\fR is present, sets the 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. .RS @@ -172,7 +172,7 @@ set changes [\fIpathName \fRstate \fIspec\fR] \fIpathName \fRstate $changes .CE will restore \fIpathName\fR to the original state. -If \fIstateSpec\fR is not specified, +If \fIstateSpec\fR is not specified, returns a list of the currently-enabled state flags. .RE .SH "WIDGET STATES" @@ -180,7 +180,7 @@ The widget state is a bitmap of independent state flags. Widget state flags include: .TP \fBactive\fR -The mouse cursor is over the widget +The mouse cursor is over the widget and pressing a mouse button will cause some action to occur. (aka .QW prelight (Gnome), @@ -191,22 +191,22 @@ and pressing a mouse button will cause some action to occur. (aka \fBdisabled\fR Widget is disabled under program control (aka .QW unavailable , -.QW inactive ) +.QW inactive ) .TP \fBfocus\fR -Widget has keyboard focus +Widget has keyboard focus .TP \fBpressed\fR Widget is being pressed (aka .QW armed -in Motif). +in Motif). .TP \fBselected\fR .QW On , .QW true , or .QW current -for things like checkbuttons and radiobuttons. +for things like checkbuttons and radiobuttons. .TP \fBbackground\fR Windows and the Mac have a notion of an @@ -228,7 +228,7 @@ 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, +(Potential uses: scale widget value out of bounds, entry widget value failed validation.) .TP \fBhover\fR @@ -256,6 +256,9 @@ $b instate {pressed !disabled} { .b invoke } $b state !disabled .CE .SH "SEE ALSO" -ttk::intro(n), style(n) +ttk::intro(n), ttk::style(n) .SH KEYWORDS state, configure, option +'\" Local Variables: +'\" mode: nroff +'\" End: |