diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ttk_Geometry.3 | 226 | ||||
| -rw-r--r-- | doc/ttk_Theme.3 | 34 | ||||
| -rw-r--r-- | doc/ttk_button.n | 75 | ||||
| -rw-r--r-- | doc/ttk_checkbutton.n | 61 | ||||
| -rw-r--r-- | doc/ttk_combobox.n | 96 | ||||
| -rw-r--r-- | doc/ttk_dialog.n | 120 | ||||
| -rw-r--r-- | doc/ttk_entry.n | 438 | ||||
| -rw-r--r-- | doc/ttk_frame.n | 43 | ||||
| -rw-r--r-- | doc/ttk_image.n | 73 | ||||
| -rw-r--r-- | doc/ttk_intro.n | 160 | ||||
| -rw-r--r-- | doc/ttk_label.n | 75 | ||||
| -rw-r--r-- | doc/ttk_labelframe.n | 64 | ||||
| -rw-r--r-- | doc/ttk_menubutton.n | 41 | ||||
| -rw-r--r-- | doc/ttk_notebook.n | 179 | ||||
| -rw-r--r-- | doc/ttk_panedwindow.n | 78 | ||||
| -rw-r--r-- | doc/ttk_progressbar.n | 79 | ||||
| -rw-r--r-- | doc/ttk_radiobutton.n | 57 | ||||
| -rw-r--r-- | doc/ttk_scrollbar.n | 160 | ||||
| -rw-r--r-- | doc/ttk_separator.n | 30 | ||||
| -rw-r--r-- | doc/ttk_sizegrip.n | 53 | ||||
| -rw-r--r-- | doc/ttk_style.n | 121 | ||||
| -rw-r--r-- | doc/ttk_treeview.n | 401 | ||||
| -rw-r--r-- | doc/ttk_widget.n | 224 |
23 files changed, 2888 insertions, 0 deletions
diff --git a/doc/ttk_Geometry.3 b/doc/ttk_Geometry.3 new file mode 100644 index 0000000..f902122 --- /dev/null +++ b/doc/ttk_Geometry.3 @@ -0,0 +1,226 @@ +'\" +'\" Copyright (c) 2004 Joe English +'\" +'\" RCS: @(#) $Id: ttk_Geometry.3,v 1.1 2006/10/31 01:42:25 hobbs Exp $ +'\" +.so man.macros +.TH Geometry 3 8.5 Tk "Tk Themed Widget" +.BS +.SH NAME +Ttk_MakeBox, Ttk_PadBox, Ttk_ExpandBox, Ttk_PackBox, Ttk_StickBox, Ttk_PlaceBox, Ttk_BoxContains, Ttk_MakePadding, Ttk_UniformPadding, Ttk_AddPadding, Ttk_RelievePadding, Ttk_GetPaddingFromObj, Ttk_GetBorderFromObj, Ttk_GetStickyFromObj \- Tk themed geometry utilities +.SH SYNOPSIS +.nf +\fB#include <tkTheme.h>\fR + +Ttk_Box +\fBTtk_MakeBox\fR(int \fIx\fR, int \fIy\fR, int \fIwidth\fR, int \fIheight\fR); + +Ttk_Box +\fBTtk_PadBox\fR(Ttk_Box \fIparcel\fR, Ttk_Padding \fIpadding\fR); + +Ttk_Box +\fBTtk_ExpandBox\fR(Ttk_Box \fIparcel\fR, Ttk_Padding \fIpadding\fR); + +Ttk_Box +\fBTtk_PackBox\fR(Ttk_Box *\fIcavity\fR, int \fIwidth\fR, int \fIheight\fR, Ttk_Side \fIside\fR); + +Ttk_Box +\fBTtk_StickBox\fR(Ttk_Box \fIparcel\fR, int \fIwidth\fR, int \fIheight\fR, unsigned \fIsticky\fR); + +Ttk_Box +\fBTtk_PlaceBox\fR(Ttk_Box *\fIcavity\fR, int \fIwidth\fR, int \fIheight\fR, Ttk_Side \fIside\fR, unsigned \fIsticky\fR); + +Ttk_Box +\fBTtk_AnchorBox\fR(Ttk_Box \fIparcel\fR, int \fIwidth\fR, int \fIheight\fR, Tk_Anchor \fIanchor\fR); + +Ttk_Padding +\fBTtk_MakePadding\fR(short \fIleft\fR, short \fItop\fR, short \fIright\fR, short \fIbottom\fR); + +Ttk_Padding +\fBTtk_UniformPadding\fR(short \fIborder\fR); + +Ttk_Padding +\fBTtk_AddPadding\fR(Ttk_Padding \fIpadding1\fR, Ttk_Padding \fIpadding2\fR; + +Ttk_Padding +\fBTtk_RelievePadding\fR(Ttk_Padding \fIpadding\fR, int \fIrelief\fR); + +int +\fBTtk_BoxContains\fR(Ttk_Box \fIbox\fR, int \fIx\fR, int \fIy\fR); + +int +\fBTtk_GetPaddingFromObj\fR(Tcl_Interp *\fIinterp\fR, Tk_Window \fItkwin\fR, Tcl_Obj *\fIobjPtr\fR, Ttk_Padding *\fIpadding_rtn\fR); + +int +\fBTtk_GetBorderFromObj\fR(Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIobjPtr\fR, Ttk_Padding *\fIpadding_rtn\fR); + +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, +etc. See \fITk_GetAnchorFromObj(3)\fR. +.AP "Ttk_Box *" cavity in/out +A rectangular region from which a parcel is allocated. +.AP short border in +Extra padding (in pixels) to add uniformly to each side of a region. +.AP short bottom in +Extra padding (in pixels) to add to the bottom of a region. +.AP Ttk_Box box in +.AP "Ttk_Box *" box_rtn out +Specifies a rectangular region. +.AP int height in +The height in pixels of a region. +.AP "Tcl_Interp *" interp in +Used to store error messages. +.AP int left in +Extra padding (in pixels) to add to the left side of a region. +.AP "Tcl_Obj *" objPtr in +String value contains a symbolic name +to be converted to an enumerated value or bitmask. +Internal rep may be be modified to cache corresponding value. +.AP Ttk_Padding padding in +.AP "Ttk_Padding *" padding_rtn out +Extra padding to add on the inside of a region. +.AP Ttk_Box parcel in +A rectangular region, allocated from a cavity. +.AP int relief in +One of the standard Tk relief options +(TK_RELIEF_RAISED, TK_RELIEF_SUNKEN, etc.). +See \fBTk_GetReliefFromObj\fR. +.AP short right in +Extra padding (in pixles) to add to the right side of a region. +.AP Ttk_Side side in +One of \fBTTK_SIDE_LEFT\fR, \fBTTK_SIDE_TOP\fR, +\fBTTK_SIDE_RIGHT\fR, or \fBTTK_SIDE_BOTTOM\fR. +.AP unsigned sticky in +A bitmask containing one or more of the bits +\fBTTK_STICK_W\fR (west, or left), +\fBTTK_STICK_E\fR (east, or right, +\fBTTK_STICK_N\fR (north, or top), and +\fBTTK_STICK_S\fR (south, or bottom). +\fBTTK_FILL_X\fR is defined as a synonym for (TTK_STICK_W|TTK_STICK_E), +\fBTTK_FILL_Y\fR is a synonym for (TTK_STICK_N|TTK_STICK_S), +and \fBTTK_FILL_BOTH\fR and \fBTTK_STICK_ALL\fR +are synonyms for (TTK_FILL_X|TTK_FILL_Y). +See also: \fIgrid(n)\fR. +.AP Tk_Window tkwin in +Window whose screen geometry determines +the conversion between absolute units and pixels. +.AP short top in +Extra padding at the top of a region. +.AP int width in +The width in pixels of a region. +.AP int x in +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: +.CS +typedef struct { + int x; + int y; + int width; + int height; +} Ttk_Box; +.CE +All coordinates are relative to the window. +.PP +\fBTtk_MakeBox\fR is a convenience routine that contsructs +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 +specified by \fIpadding\fR. +.PP +\fBTtk_ExpandBox\fR is the inverse of \fBTtk_PadBox\fP: +it returns a new box surrounding the specified \fIparcel\fR, +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 +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 +\fIsticky\fR bits. +.PP +\fBTtk_PlaceBox\fP combines \fBTtk_PackBox\fP and \fBTtk_StickBox\fP: +it allocates a parcel on the specified \fIside\fP of the \fIcavity\fP, +places a box of the requested size inside the parcel according to \fIsticky\fP, +and shrinks the \fIcavity\fP. +.PP +\fBTtk_AnchorBox\fR places a box with the requested \fIwidth\fR +and \fIheight\fR inside the \fIparcel\fR according to the +specified \fIanchor\fR option. +.PP +\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 +borders, internal padding, and external margins: +.CS +typedef struct { + short left; + short top; + short right; + short bottom; +} Ttk_Padding; +.CE +.PP +\fBTtk_MakePadding\fR is a convenience routine that contsructs +a \fBTtk_Padding\fR structure with the specified left, top, right, and bottom +components. +.PP +\fBTtk_UniformPadding\fR constructs a \fBTtk_Padding\fR structure +with all components equal to the specified \fIborder\fR. +.PP +\fBTtk_AddPadding\fR adds two \fBTtk_Padding\fRs together +and returns a combined padding containing the sum of the +individual padding components. +.PP +\fBTtk_RelievePadding\fR +adds an extra 2 pixels of padding to \fIpadding\fR +according to the specified \fIrelief\fR. +If \fIrelief\fR is \fBTK_RELIEF_SUNKEN\fR, +adds two pixels at the top and left +so the inner region is shifted down and to the left. +If it is \fBTK_RELIEF_RAISED\fR, adds two pixels +at the bottom and right so +the inner region is shifted up and to the right. +Otherwise, adds 1 pixel on all sides. +This is typically used in element geometry procedures to simulate +a "pressed-in" look for pushbuttons. + +.SH "CONVERSION ROUTINES" +\fBTtk_GetPaddingFromObj\fR converts the string in \fIobjPtr\fR +to a \fBTtk_Padding\fR structure. +The string representation is a list of +up to four length specifications +\fI"left top right bottom"\fR. +If fewer than four elements are specified, +\fIbottom\fR defaults to \fItop\fR, +\fIright\fR defaults to \fIleft\fR, and +\fItop\fR defaults to \fIleft\fR. +See \fBTk_GetPixelsFromObj(3)\fR for the syntax of length specifications. +.PP +\fBTtk_GetBorderFromObj\fR is the same as \fBTtk_GetPaddingFromObj\fP +except that the lengths are specified as integers +(i.e., resolution-dependant values like \fI3m\fP are not allowed). +.PP +\fBTtk_GetStickyFromObj\fR converts the string in \fIobjPtr\fR +to a \fIsticky\fR bitmask. The string contains zero or more +of the characters \fBn\fR, \fBs\fR, \fBe\fR, or \fBw\fR. + +.SH "SEE ALSO" +Tk_GetReliefFromObj(3), Tk_GetPixelsFromObj(3), Tk_GetAnchorFromObj(3) + +.SH "KEYWORDS" +geometry, padding, margins, box, region, sticky, relief diff --git a/doc/ttk_Theme.3 b/doc/ttk_Theme.3 new file mode 100644 index 0000000..fb16978 --- /dev/null +++ b/doc/ttk_Theme.3 @@ -0,0 +1,34 @@ +'\" +'\" Copyright (c) 2003 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_Theme.3,v 1.1 2006/10/31 01:42:25 hobbs Exp $ +'\" +.so man.macros +.TH Ttk_CreateTheme 3 8.5 Tk "Tk Themed Widget" +.BS +.SH NAME +Ttk_CreateTheme, Ttk_GetTheme, Ttk_GetDefaultTheme, Ttk_GetCurrentTheme \- create and use Tk themes. +.SH SYNOPSIS +.nf +Ttk_Theme Ttk_CreateTheme(\fIinterp\fR, \fIname\fR, \fIparentTheme\fR); +Ttk_Theme Ttk_GetTheme(\fIinterp\fR, \fIname\fR); +Ttk_Theme Ttk_GetDefaultTheme(\fIinterp\fR); +Ttk_Theme Ttk_GetCurrentTheme(\fIinterp\fR); +.fi +.SH ARGUMENTS +.AP "Tcl_Interp *" interp in +The Tcl interpreter in which to register/query available themes. +.AP "Ttk_Theme" parentTheme in +Fallback or parent theme from which the new theme will +inherit elements and layouts. +.AP "const char *" name in +The name of the theme. +.BE +.SH DESCRIPTION + +.SH "SEE ALSO" +Ttk_RegisterLayout, Ttk_BuildLayout +.\" .SH KEYWORDS diff --git a/doc/ttk_button.n b/doc/ttk_button.n new file mode 100644 index 0000000..b085d8b --- /dev/null +++ b/doc/ttk_button.n @@ -0,0 +1,75 @@ +'\" +'\" Copyright (c) 2004 Joe English +'\" +.so man.macros +.TH ttk_button n 8.5 Tk "Tk Themed Widget" +.BS +.SH NAME +ttk::button \- Widget that issues a command when pressed +.SH SYNOPSIS +\fBttk::button\fR \fIpathName \fR?\fIoptions\fR? +.BE +.SH DESCRIPTION +A \fBbutton\fP widget displays a textual label and/or image, +and evaluates a command when pressed. +.SO +\-class \-compound \-cursor \-image +\-state \-style \-takefocus \-text +\-textvariable \-underline \-width +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-command command Command +A script to evaluate when the widget is invoked. +.OP \-default default Default +May be set to one of \fBnormal\fP, \fBactive\fP, or \fBdisabled\fP. +In a dialog box, one button may be designated the "default" button +(meaning, roughly, "the one that gets invoked when the user presses <Enter>"). +\fBactive\fP indicates that this is currently the default button; +\fBnormal\fP means that it may become the default button, and +\fBdisabled\fP means that it is not defaultable. +The default is \fBnormal\fP. +.br +Depending on the theme, the default button may be displayed +with an extra highlight ring, or with a different border color. +See also: \fIkeynav(n)\fP. +.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. +Note that some themes may specify a non-zero \fB-width\fP +in the style. +'\" Not documented -- may go away +'\" .OP \-padding padding Padding +'\" .OP \-foreground foreground Foreground +'\" .OP \-font font Font +'\" .OP \-anchor anchor Anchor +'\" .OP \-padding padding Padding +'\" .OP \-relief relief Relief + +.SH "WIDGET COMMAND" +.TP +\fIpathName \fBinvoke\fR +Invokes the command associated with the button. +.TP +\fIpathName \fBcget\fR \fIoption\fR +.TP +\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +.TP +\fIpathName \fBinstate \fIstatespec\fR ?\fIscript\fR? +.TP +\fIpathName \fBstate\fR ?\fIstateSpec\fR? +See \fIwidget(n)\fP + +.SH "COMPATIBILITY OPTIONS" +.OP \-state state State +May be set to \fBnormal\fP or \fBdisabled\fP +to control the \fBdisabled\fP state bit. +This is a ``write-only'' option: setting it changes the +widget state, but the \fBstate\fP widget command does +not affect the state option. + +.SH "SEE ALSO" +widget(n), keynav(n) +.SH "KEYWORDS" +widget, button, default, command diff --git a/doc/ttk_checkbutton.n b/doc/ttk_checkbutton.n new file mode 100644 index 0000000..cd5ee64 --- /dev/null +++ b/doc/ttk_checkbutton.n @@ -0,0 +1,61 @@ +'\" +'\" Copyright (c) 2004 Joe English +'\" +.so man.macros +.TH ttk_checkbutton n 8.5 Tk "Tk Themed Widget" +.BS +.SH NAME +ttk::checkbutton \- On/off widget +.SH SYNOPSIS +\fBttk::checkbutton\fR \fIpathName \fR?\fIoptions\fR? +.BE +.SH DESCRIPTION +A \fBcheckbutton\fR widget is used to show or change a setting. +It has two states, selected and deselected. +The state of the checkbuton may be linked to a Tcl variable. +.SO +\-class \-compound \-cursor \-image +\-state \-style \-takefocus \-text +\-textvariable \-underline \-width +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-command command Command +A Tcl script to execute whenever the widget is invoked. +.OP \-offvalue offValue OffValue +The value to store in the associated \fI-variable\fR +when the widget is deselected. Defaults to \fB0\fR. +.OP \-onvalue onValue OnValue +The value to store in the associated \fI-variable\fR +when the widget is selected. Defaults to \fB1\fR. +.OP \-variable variable Variable +The name of a global variable whose value is linked to the widget. +Defaults to the widget pathname if not specified. +.SH "WIDGET COMMAND" +In addition to the standard +\fBcget\fR, \fBconfigure\fR, \fBinstate\fR, and \fBstate\fR +commands, checkbuttons support the following additional +widget commands: +.TP +\fIpathname\fR invoke +Toggles between the selected and deselected states +and evaluates the associated \fI-command\fR. +If the widget is currently selected, sets the \fI-variable\fR +to the \fI-offvalue\fR and deselects the widget; +otherwise, sets the \fI-variable\fR to the \fI-onvalue\fR +Returns the result of the \fI-command\fR. +.\" Missing: select, deselect, toggle +.\" Are these useful? They don't invoke the -command +.\" Missing: flash. This is definitely not useful. +.SH "WIDGET STATES" +The widget does not respond to user input if the \fBdisabled\fP state is set. +The widget sets the \fBselected\fP state whenever +the linked \fB-variable\fP is set to the widget's \fB-onvalue\fP, +and clears it otherwise. +The widget sets the \fBalternate\fP state whenever the +linked \fB-variable\fP is unset. +(The \fBalternate\fP state may be used to indicate a ``tri-state'' +or ``indeterminate'' selection.) +.SH "SEE ALSO" +widget(n), keynav(n), radiobutton(n) +.SH "KEYWORDS" +widget, button, toggle, check, option diff --git a/doc/ttk_combobox.n b/doc/ttk_combobox.n new file mode 100644 index 0000000..1e0664a --- /dev/null +++ b/doc/ttk_combobox.n @@ -0,0 +1,96 @@ +'\" +'\" Copyright (c) 2004 Joe English +'\" +.so man.macros +.TH ttk_combobox n 8.5 Tk "Tk Themed Widget" +.BS +.SH NAME +ttk::combobox \- text field with popdown selection list +.SH SYNOPSIS +\fBttk::combobox\fR \fIpathName \fR?\fIoptions\fR? +.SO +\-class \-cursor \-takefocus \-style +.SE +.\" ALSO: Other entry widget options +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-exportselection exportSelection ExportSelection +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\fP, \fBcenter\fP, or \fBright\fP. +.OP \-postcommand postCommand PostCommand +A Tcl script to evaluate immediately before displaying the listbox. +The \fB-postcommand\fP script may specify the \fB-values\fP to display. +.OP \-state state State +One of \fBnormal\fR, \fBreadonly\fR, or \fBdisabled\fP. +In the \fBreadonly\fP state, +the value may not be edited directly, and +the user can only select one of the \fB-values\fP from the +dropdown list. +In the \fBnormal\fP state, +the text field is directly editable. +In the \fBdisabled\fP 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. +.OP \-values values Values +Specifies the list of values to display in the drop-down listbox. +.OP \-width width Width +Specifies an integer value indicating the desired width of the entry window, +in average-size characters of the widget's font. +.BE +.SH DESCRIPTION +A combobox 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. +.SH "WIDGET COMMAND" +.TP +\fIpathName \fBcget\fR \fIoption\fR +Returns the current value of the specified \fIoption\fP. +See \fIwidget(n)\fP. +.TP +\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +Modify or query widget options. +See \fIwidget(n)\fP. +.TP +\fIpathName \fBcurrent\fR ?\fInewIndex\fR? +If \fInewIndex\fP 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\fP, \fIy\fP, +or the empty string if the coordinates are outside the window. +.TP +\fIpathName \fBinstate \fIstatespec\fR ?\fIscript\fR? +Test the widget state. +See \fIwidget(n)\fP. +.TP +\fIpathName \fBset\fR \fIvalue\fR +Sets the value of the combobox to \fIvalue\fP. +.TP +\fIpathName \fBstate\fR ?\fIstateSpec\fR? +Modify or query the widget state. +See \fIwidget(n)\fP. +.PP +The combobox widget also supports the following \fIentry\fP +widget commands (see \fIentry(n)\fP for details): +.DS +.ta 5.5c 11c +bbox delete icursor +index insert selection +xview +.DE +.SH "VIRTUAL EVENTS" +The combobox widget generates a \fB<<ComboboxSelected>>\fP 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" +widget(n), entry(n) diff --git a/doc/ttk_dialog.n b/doc/ttk_dialog.n new file mode 100644 index 0000000..3fdeb24 --- /dev/null +++ b/doc/ttk_dialog.n @@ -0,0 +1,120 @@ +'\" +'\" Copyright (c) 2005 Joe English +'\" +.so man.macros +.TH ttk_dialog n 8.5 Tk "Tk Themed Widget" +.SH "NAME" +ttk::dialog \- create a dialog box +.SH "SYNOPSIS" +\fBttk::dialog\fR \fIpathname\fR ?\fIoptions...\fR? +\fBttk::dialog::define\fR \fIdialogType\fR ?\fIoptions...\fR? +.SH "DESCRIPTION" +A dialog box is a transient top-level window +containing an icon, a short message, an optional, longer, detail message, +and a row of command buttons. +When the user presses any of the buttons, +a callback function is invoked +and then the dialog is destroyed. +.PP +Additional widgets may be added in the dialog \fIclient frame\fR. +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-title undefined undefined +Specifies a string to use as the window manager title. +.OP \-message undefined undefined +Specifies the message to display in this dialog. +.OP \-detail undefined undefined +Specifies a longer auxilliary message. +.OP \-command undefined undefined +Specifies a command prefix to be invoked when the user presses +one of the command buttons. +The symbolic name of the button is passed as an additional argument +to the command. +The dialog is dismissed after invoking the command. +.OP \-parent undefined undefined +Specifies a toplevel window for which the dialog is transient. +If omitted, the default is the nearest ancestor toplevel. +If set to the empty string, the dialog will not be a transient window. +.OP \-type undefined undefined +Specifies a built-in or user-defined dialog type. +See \fBPREDEFINED DIALOG TYPES\fP, below. +.OP \-icon undefined undefined +Specifies one of the stock dialog icons, +\fBinfo\fP, \fBquestion\fP, \fBwarning\fP, \fBerror\fP, +\fBauth\fP, or \fBbusy\fP. +If set to the empty string (the defalt), no icon is displayed. +.OP \-buttons undefined undefined +A list of symbolic button names. +.OP \-labels undefined undefined +A dictionary mapping symbolic button names to textual labels. +May be omitted if all the buttons are predefined. +.OP \-default undefined undefined +The symbolic name of the default button. +.OP \-cancel undefined undefined +The symbolic name of the "cancel" button. +The cancel button is invoked if the user presses the Escape key +and when the dialog is closed from the window manager. +If \fB-cancel\fP is not specified, +the dialog ignores window manager close commands (WM_DELETE_WINDOW). +.SH "WIDGET COMMANDS" +.TP +\fBttk::dialog::clientframe \fIdlg\fR +Returns the widget path of the client frame. +Other widgets may be added to the client frame. +The client frame appears between the detail message and the command buttons. +.SH "PREDEFINED DIALOG TYPES" +The \fB-type\fP option, if present, specifies default values +for other options. \fBttk::dialog::define \fItype options...\fR +specifies a new stock dialog \fItype\fP. +The following stock dialog types are predefined: +.CS +ttk::dialog::define ok \e + -icon info -buttons {ok} -default ok +ttk::dialog::define okcancel \e + -icon info -buttons {ok cancel} -default ok -cancel cancel +ttk::dialog::define yesno \e + -icon question -buttons {yes no} +ttk::dialog::define yesnocancel \e + -icon question -buttons {yes no cancel} -cancel cancel +ttk::dialog::define retrycancel \e + -icon question -buttons {retry cancel} -cancel cancel +.CE +.SH "STOCK BUTTONS" +The following ``stock'' symbolic button names have predefined labels: +\fByes\fP, \fBno\fP, \fBok\fP, \fBcancel\fP, and \fBretry\fP. +.PP +It is not necessary to list these in the \fB-labels\fP dictionary. +.\" .SH "DIFFERENCES FROM MESSAGE BOXES" +.\" The \fBttk::dialog\fR constructor is similar to +.\" the Tk library procedure \fBtk_messageBox\fP, +.\" but with the following notable differences: +.\" .IP \(bu +.\" The first argument to \fBttk::dialog\fP is the name of +.\" the widget to create; \fBtk_messageBox\fP has +.\" .IP \(bu +.\" Ttk dialog boxes are non-modal by default. +.\" .IP \(bu +.\" The \fBtk_messageBox\fP command is blocking: +.\" it does not return until the user presses one of the command buttons. +.\" \fBttk::dialog\fP returns immediately after creating the dialog box. +.SH EXAMPLE +.CS +proc saveFileComplete {button} { + switch -- $button { + yes { # save file ... } + no { exit } + cancel { # no-op } + } +} + +ttk::dialog .saveFileDialog \e + -title "Save file?" \e + -icon question \e + -message "Save file before closing?" \e + -detail "If you do not save the file, your work will be lost" \e + -buttons [list yes no cancel] \e + -labels [list yes "Save file" no "Don't save"] \e + -command saveFileComplete \e + ; +.CE +.SH "SEE ALSO" +\fBtk_messageBox(n)\fR, \fBwm(n)\fR, \fBtoplevel(n)\fP diff --git a/doc/ttk_entry.n b/doc/ttk_entry.n new file mode 100644 index 0000000..7b665eb --- /dev/null +++ b/doc/ttk_entry.n @@ -0,0 +1,438 @@ +'\" +'\" SOURCE: entry.n, r1.12 +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" Copyright (c) 1998-2000 Scriptics Corporation. +'\" 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. +'\" +.so man.macros +.TH ttk_entry n 8.5 Tk "Tk Themed Widget" +.BS +.SH NAME +ttk::entry \- Editable text field widget +.SH SYNOPSIS +\fBttk::entry\fR \fIpathName \fR?\fIoptions\fR? +.SH DESCRIPTION +.PP +An \fBentry\fP widget displays a one-line text string and +allows that string to be edited by the user. +The value of the string may be linked to a Tcl variable +with the \fB-textvariable\fP option. +Entry widgets support horizontal scrolling with the +standard \fB-xscrollcommand\fP option and \fBxview\fP widget command. +.SO +\-class \-cursor \-style \-takefocus +\-xscrollcommand +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-exportselection exportSelection ExportSelection +A boolean value specifying whether or not +a selection in the widget should be linked to the X selection. +If the selection is exported, then selecting in the widget deselects +the current X selection, selecting outside the widget deselects any +widget selection, and the widget will respond to selection retrieval +requests when it has a selection. +.\" MAYBE: .OP \-font font Font +.\" MAYBE: .OP \-foreground foreground Foreground +.\" MAYBE: .OP \-insertbackground insertBackground Foreground +.\" MAYBE: .OP \-insertwidth insertWidth InsertWidth +.OP \-invalidcommand invalidCommand InvalidCommand +A script template to evaluate whenever the \fBvalidateCommand\fR returns 0. +See \fBVALIDATION\fR below for more information. +.OP \-justify justify Justify +Specifies how the text is aligned within the entry widget. +One of \fBleft\fP, \fBcenter\fP, or \fBright\fP. +.\" MAYBE: .OP \-selectbackground selectBackground Foreground +.\" MAYBE: .OP \-selectborderwidth selectBorderWidth BorderWidth +.\" MAYBE: .OP \-selectforeground selectForeground Background +.OP \-show show Show +If this option is specified, then the true contents of the entry +are not displayed in the window. +Instead, each character in the entry's value will be displayed as +the first character in the value of this option, such as ``*''. +This is useful, for example, if the entry is to be used to enter +a password. +If characters in the entry are selected and copied elsewhere, the +information copied will be what is displayed, not the true contents +of the entry. +.OP \-state state State +Compatibility option; see \fBwidget(n)\fP for details. +Specifies one of three states for the entry, +\fBnormal\fR, \fBdisabled\fR, or \fBreadonly\fR. +See \fBWIDGET STATES\fP, below. +.OP \-textvariable textVariable Variable +Specifies the name of a variable whose value is linked +to the entry widget's contents. +Whenever the variable changes value, the widget's contents are updated, +and vice versa. +.OP \-validate validate Validate +Specifies the mode in which validation should operate: +\fBnone\fR, \fBfocus\fR, \fBfocusin\fR, \fBfocusout\fR, \fBkey\fR, or \fBall\fR. +Default is \fBnone\fR, meaning that validation is disabled. +See \fBVALIDATION\fR below. +.OP \-validatecommand validateCommand ValidateCommand +A script template to evaluate whenever validation is triggered. +If set to the empty string (the default), validation is disabled. +The script must return a boolean value. +See \fBVALIDATION\fR below. +.OP \-width width Width +Specifies an integer value indicating the desired width of the entry window, +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. +.BE +.SH NOTES +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 +selection; entry selections are available as type \fBSTRING\fR. +Entries also observe the standard Tk rules for dealing with the +input focus. When an entry has the input focus it displays an +\fIinsert cursor\fR to indicate where new characters will be +inserted. +.PP +Entries are capable of displaying strings that are too long to +fit entirely within the widget's window. In this case, only a +portion of the string will be displayed; commands described below +may be used to change the view in the window. Entries use +the standard \fBxScrollCommand\fR mechanism for interacting with +scrollbars (see the description of the \fBxScrollCommand\fR option +for details). +.SH "INDICES" +Many of the \fBentry\fP 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: +.IP \fInumber\fR +Specifies the character as a numerical index, where 0 corresponds +to the first character in the string. +.IP \fB@\fInumber\fR +In this form, \fInumber\fR is treated as an x-coordinate in the +entry's window; the character spanning that x-coordinate is used. +For example, ``\fB@0\fR'' indicates the left-most character in the +window. +.IP \fBend\fR +Indicates the character just after the last one in the entry's string. +This is equivalent to specifying a numerical index equal to the length +of the entry's string. +.IP \fBinsert\fR +Indicates the character adjacent to and immediately following the +insert cursor. +.IP \fBsel.first\fR +Indicates the first character in the selection. It is an error to +use this form if the selection isn't in the entry window. +.IP \fBsel.last\fR +Indicates the character just after the last one in the selection. +It is an error to use this form if the selection isn't in the +entry window. +.LP +Abbreviations may be used for any of the forms above, e.g. ``\fBe\fR'' +or ``\fBsel.f\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: +.TP +\fIpathName \fBbbox \fIindex\fR +Returns a list of four numbers describing the bounding box of the +character given by \fIindex\fR. +The first two elements of the list give the x and y coordinates of +the upper-left corner of the screen area covered by the character +(in pixels relative to the widget) and the last two elements give +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\fP. +See \fIwidget(n)\fP. +.TP +\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +Modify or query widget options. +See \fIwidget(n)\fP. +.TP +\fIpathName \fBdelete \fIfirst \fR?\fIlast\fR? +Delete one or more elements of the entry. +\fIFirst\fR is the index of the first character to delete, and +\fIlast\fR is the index of the character just after the last +one to delete. +If \fIlast\fR isn't specified it defaults to \fIfirst\fR+1, +i.e. a single character is deleted. +This command returns the empty string. +.TP +\fIpathName \fBget\fR +Returns the entry's string. +.TP +\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\fP, \fIy\fP, +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. +.TP +\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 \fIwidget(n)\fP. +.TP +\fIpathName \fBselection \fIoption arg\fR +This command is used to adjust the selection within an entry. It +has several forms, depending on \fIoption\fR: +.RS +.TP +\fIpathName \fBselection clear\fR +Clear the selection if it is currently in this widget. +If the selection isn't in this widget then the command has no effect. +Returns the empty string. +.TP +\fIpathName \fBselection present\fR +Returns 1 if there is are characters selected in the entry, +0 if nothing is selected. +.TP +\fIpathName \fBselection range \fIstart\fR \fIend\fR +Sets the selection to include the characters starting with +the one indexed by \fIstart\fR and ending with the one just +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 \fIwidget(n)\fP. +.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\fP state accordingly. +.TP +\fIpathName \fBxview \fIargs\fR +This command is used to query and change the horizontal position of the +text in the widget's window. It can take any of the following +forms: +.RS +.TP +\fIpathName \fBxview\fR +Returns a list containing two elements. +Each element is a real fraction between 0 and 1; together they describe +the horizontal span that is visible in the window. +For example, if the first element is .2 and the second element is .6, +20% of the entry's text is off-screen to the left, the middle 40% is visible +in the window, and 40% of the text is off-screen to the right. +These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR +option. +.TP +\fIpathName \fBxview\fR \fIindex\fR +Adjusts the view in the window so that the character given by \fIindex\fR +is displayed at the left edge of the window. +.TP +\fIpathName \fBxview moveto\fI fraction\fR +Adjusts the view in the window so that the character \fIfraction\fR of the +way through the text appears at the left edge of the window. +\fIFraction\fR must be a fraction between 0 and 1. +.TP +\fIpathName \fBxview scroll \fInumber what\fR +This command shifts the view in the window left or right according to +\fInumber\fR and \fIwhat\fR. +\fINumber\fR must be an integer. +\fIWhat\fR must be either \fBunits\fR or \fBpages\fR. +'\" or an abbreviation of one of these, but we don't document that. +If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by +\fInumber\fR average-width characters on the display; if it is +\fBpages\fR then the view adjusts by \fInumber\fR screenfuls. +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 +.SH VALIDATION +The \fB-validate\fP, \fB-validatecommand\fP, and \fB-invalidcommand\fP +options are used to enable entry widget validation. +.SS "VALIDATION MODES" +There are two main validation modes: \fIprevalidation\fP, +in which the \fB-validatecommand\fP is evaluated prior to each edit +and the return value is used to determine whether to accept +or reject the change; +and \fIrevalidation\fP, in which the \fB-validatecommand\fP is +evaluated to determine whether the current value is valid. +.PP +The \fB-validate\fP option determines when validation occurs; +it may be set to any of the following values: +.IP \fBnone\fR +Default. This means validation will only occur when +specifically requested by the \fBvalidate\fP widget command. +.IP \fBkey\fR +The entry will be prevalidated prior to each edit +(specifically, whenever the \fBinsert\fP or \fBdelete\fP +widget commands are called). +If prevalidation fails, the edit is rejected. +.IP \fBfocus\fR +The entry is revalidated when the entry receives or loses focus. +.IP \fBfocusin\fR +The entry is revalidated when the entry receives focus. +.IP \fBfocusout\fR +The entry is revalidated when the entry loses focus. +.IP \fBall\fR +Validation is performed for all above conditions. +.PP +The \fB-invalidcommand\fP is evaluated whenever +the \fB-validatecommand\fP returns a false value. +.PP +The \fB-validatecommand\fP and \fB-invalidcommand\fP +may modify the entry widget's value +via the widget \fBinsert\fP or \fBdelete\fP commands, +or by setting the linked \fB-textvariable\fP. +If either does so during prevalidation, +then the edit is rejected +regardless of the value returned by the \fB-validatecommand\fP. +.PP +If \fB-validatecommand\fP is empty (the default), +validation always succeeds. +.SS "VALIDATION SCRIPT SUBSTITUTIONS" +It is possible to perform percent substitutions on the +\fB-validatecommand\fR and \fBinvalidCommand\fR, +just as in a \fBbind\fR script. +The following substitutions are recognized: +.IP \fB%d\fR +Type of action: 1 for \fBinsert\fR prevalidation, +0 for \fBdelete\fR prevalidation, +or -1 for revalidation. +.IP \fB%i\fR +Index of character string to be inserted/deleted, if any, otherwise -1. +.IP \fB%P\fR +In prevalidation, the new value of the entry if the edit is accepted. +In revalidation, the current value of the entry. +.IP \fB%s\fR +The current value of entry prior to editing. +.IP \fB%S\fR +The text string being inserted/deleted, if any, {} otherwise. +.IP \fB%v\fR +The current value of the \fB-validate\fP option. +.IP \fB%V\fR +The validation condition that triggered the callback +(\fBkey\fP, \fBfocusin\fP, \fBfocusout\fP, or \fBforced\fP). +.IP \fB%W\fR +The name of the entry widget. +.SS "DIFFERENCES FROM TK ENTRY WIDGET VALIDATION" +.IP \(bu +The standard Tk entry widget automatically disables validation +(by setting \fB-validate\fP to \fBnone\fP) +if the \fB-validatecommand\fP or \fB-invalidcommand\fP modifies +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\fP +does not return a valid boolean value. +(Thus, it is not necessary to reenable validation after +modifying the entry value in a validation script). +.IP \(bu +The standard entry widget invokes validation whenever the linked +\fB-textvariable\fP is modified; the Tk themed entry widget does not. +.SH "DEFAULT BINDINGS" +The entry widget's default bindings enable the following behavior. +In the descriptions below, ``word'' refers to a contiguous group +of letters, digits, or ``_'' characters, or any single character +other than these. +.IP \(bu +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 +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 +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 +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 +Clicking mouse button 1 with the Control key down will position the +insert cursor in the entry without affecting the selection. +.IP \(bu +If any normal printing characters are typed in an entry, they are +inserted at the point of the insert cursor. +.IP \(bu +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 +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 +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 +cursor moves and the selection is extended to include the new character. +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 +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 +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 +Control-/ selects all the text in the entry. +.IP \(bu +Control-\e clears any selection in the entry. +.IP \(bu +The standard Tk <<Cut>>, <<Copy>>, <<Paste>>, and <<Clear>> +virtual events operate on the selection in the expected manner. +.IP \(bu +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 +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 +Control-d deletes the character to the right of the insert cursor. +.IP \(bu +Control-k deletes all the characters to the right of the insertion +cursor. +.SH "WIDGET STATES" +In the \fBdisabled\fP state, +the entry cannot be edited and the text cannot be selected. +In the \fBreadonly\fP state, +no insert cursor is displayed and +the entry cannot be edited +(specifically: the \fBinsert\fP and \fBdelete\fP commands have no effect). +The \fBdisabled\fP state is the same as \fBreadonly\fP, +and in addition text cannot be selected. +.PP +Note that changes to the linked \fB-textvariable\fP will +still be reflected in the entry, even if it is disabled or readonly. +.PP +Typically, the text is "grayed-out" in the \fBdisabled\fP state, +and a different background is used in the \fBreadonly\fP state. +.PP +The entry widget sets the \fBinvalid\fP state if revalidation fails, +and clears it whenever validation succeeds. +.SH KEYWORDS +entry, widget, text field diff --git a/doc/ttk_frame.n b/doc/ttk_frame.n new file mode 100644 index 0000000..da7a00a --- /dev/null +++ b/doc/ttk_frame.n @@ -0,0 +1,43 @@ +'\" Copyright (c) 2005 Joe English +.so man.macros +.TH ttk_frame n 8.5 Tk "Tk Themed Widget" +.BS +.SH NAME +ttk::frame \- Simple container widget +.SH SYNOPSIS +\fBttk::frame\fR \fIpathName \fR?\fIoptions\fR? +.BE +.SH DESCRIPTION +A \fBframe\fP widget is a container, used to group other widgets together. +.SO +\-class \-cursor \-takefocus \-style +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.OP -borderwidth borderWidth BorderWidth +The desired width of the widget border. Defaults to 0. +.OP -relief relief Relief +One of the standard Tk border styles: +\fBflat\fR, \fBgroove\fR, \fBraised\fR, \fBridge\fR, +\fBsolid\fR, or \fBsunken\fP. +Defaults to \fBflat\fP. +.OP -padding padding Padding +Additional padding to include inside the border. +.OP -width width Width +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" +Supports the standard widget commands +\fBconfigure\fP, \fBcget\fP, \fBinstate\fP, and \fBstate\fP; +see \fIwidget(n)\fP. +.SH "NOTES" +Note that if the \fBpack\fP, \fBgrid\fP, or other geometry managers +are used to manage the children of the \fBframe\fP, +by the GM's requested size will normally take precedence +over the \fBframe\fP widget's \fB-width\fP and \fB-height\fP options. +[\fBpack propagate\fP] and [\fBgrid propagate\fP] can be used +to change this. +.SH "SEE ALSO" +widget(n), labelframe(n) +.SH "KEYWORDS" +widget, frame, container diff --git a/doc/ttk_image.n b/doc/ttk_image.n new file mode 100644 index 0000000..87e2deb --- /dev/null +++ b/doc/ttk_image.n @@ -0,0 +1,73 @@ +'\" +'\" Copyright (c) 2004 Joe English +'\" $Id: ttk_image.n,v 1.1 2006/10/31 01:42:25 hobbs Exp $ +'\" +.so man.macros +.TH ttk_image n 8.5 Tk "Tk Themed Widget" +.BS +.SH NAME +ttk_image \- Define an element based on an image +.SH SYNOPSIS +\fBttk::style create element \fIname\fR \fBimage\fR \fIimageName\fR ?\fIoptions\fR? +.BE +.SH DESCRIPTION +The \fIimage\fP element factory creates a new element +in the current theme whose visual appearance is determined +by a Tk image. +.SH OPTIONS +Valid \fIoptions\fR are: +.TP +\fB-border\fP \fIpadding\fP +\fIpadding\fP is a list of up to four integers, specifying +the left, top, right, and bottom borders, respectively. +See \fBIMAGE STRETCHING\fP, below. +.TP +\fB-height \fIheight\fP +Specifies a minimum height for the element. +If less than zero, the base image's height is used as a default. +.TP +\fB-map { \fIstatespec\fP \fIimage\fP.. } +Specifies auxilliary images to use in different states. +Each \fIstatespec\fP is a list of state names optionally +prefixed by an exclamation point, as in \fBttk::style map\fP. +Each \fIimageName\fP is the name of a Tk image +defined with \fBimage create ...\fP. +When the element is displayed, each \fIstatespec\fP is +tested in order, and the \fIimage\fP corresponding to +the first matching \fIstatespec\fP is used. +If none match, the base \fIimageName\fP is used. +.TP +\fB-padding\fP \fIpadding\fP +Specifies the element's interior padding. Defaults to +\fI-border\fP if not specified. +.TP +\fB-sticky\fP \fIspec\fP +Specifies how the image is placed within the final parcel. +\fIspec\fP contains zero or more characters "n", "s", "w", or "e". +.TP +\fB-width \fIwidth\fP +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\fP option. +If the image needs to stretch horizontally (i.e., \fB-sticky ew\fP) +or vertically (\fB-sticky ns\fP), +subregions of the image are replicated to fill the parcel +based on the \fB-border\fP option. +The \fB-border\fP 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 +set button(normal) [image create photo -file button.png] +set button(pressed) [image create photo -file button-pressed.png] +ttk::style element create Button.button image $button(normal) \e + -border {2 4} -map [list pressed $button(pressed)] -sticky nswe +.CE +.SH "SEE ALSO" +image(n), photo(n) +.SH KEYWORDS +pixmap theme, image diff --git a/doc/ttk_intro.n b/doc/ttk_intro.n new file mode 100644 index 0000000..cbe49b4 --- /dev/null +++ b/doc/ttk_intro.n @@ -0,0 +1,160 @@ +'\" +'\" Copyright (c) 2004 Joe English +'\" +.so man.macros +.TH ttk_intro n 8.5 Tk "Tk Themed Widget" +.BS +.SH NAME +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 +.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: +.IP \(bu +Isolate platform differences (X11 vs. classic Windows vs. XP vs. Aqua ...) +.IP \(bu +Adapt to display limitations (low-color, grayscale, monochrome, tiny screens) +.IP \(bu +Accessibility (high contrast, large type) +.IP \(bu +Application suite "branding" +.IP \(bu +Blend in with the rest of the desktop (Gnome, KDE, Java) +.IP \(bu +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. +.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 +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: +.IP \(bu +A dynamic setting specified by \fBstyle map\fR and the current state; +.IP \(bu +An option of the same name and type in the widget containing the element; +.IP \(bu +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 +.CS +style layout Horizontal.TScrollbar { + Scrollbar.trough -children { + Scrollbar.leftarrow -side left -sticky w + Scrollbar.rightarrow -side right -sticky e + Scrollbar.thumb -side left -expand true -sticky ew + } +} +.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). + +.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. +.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 \fIwidget(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. +.PP +For example, the class bindings for the \fBtbutton\fR +widget are: +.CS +bind TButton <Enter> { %W state active } +bind TButton <Leave> { %W state !active } +bind TButton <ButtonPress-1> { %W state pressed } +bind TButton <Button1-Leave> { %W state !pressed } +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). +.PP +\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: +.CS +style default TButton \e + -background #d9d9d9 \e + -foreground black \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\fP command specifies dynamic resources +for a particular style: +.CS +style map TButton \e + -background [list disabled #d9d9d9 active #ececec] \e + -foreground [list disabled #a3a3a3] \e + -relief [list {pressed !disabled} sunken] \e + ; +.CE +.SH "SEE ALSO" +widget(n), style(n) diff --git a/doc/ttk_label.n b/doc/ttk_label.n new file mode 100644 index 0000000..77ac736 --- /dev/null +++ b/doc/ttk_label.n @@ -0,0 +1,75 @@ +'\" +'\" Copyright (c) 2004 Joe English +'\" +.so man.macros +.TH ttk_label n 8.5 Tk "Tk Themed Widget" +.BS +.SH NAME +ttk::label \- Display a text string and/or image +.SH SYNOPSIS +\fBttk::label\fR \fIpathName \fR?\fIoptions\fR? +.BE +.SH DESCRIPTION +A \fBlabel\fP widget displays a textual label and/or image. +The label may be linked to a Tcl variable +to automatically change the displayed text. +.SO +\-class \-compound \-cursor \-image +\-style \-takefocus \-text \-textvariable +\-underline \-width +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-anchor anchor Anchor +Specifies how the information in the widget is positioned +relative to the inner margins. Legal values are +\fBn\fR, \fBne\fR, \fBe\fR, \fBse\fR, +\fBs\fR, \fBsw\fR, \fBw\fR, \fBnw\fR, and \fBcenter\fR. +See also \fB-justify\fP. +.OP \-background frameColor FrameColor +The widget's background color. +If unspecified, the theme default is used. +.OP \-font font Font +Font to use for label text. +.OP \-foreground textColor TextColor +The widget's foreground color. +If unspecified, the theme default is used. +.OP \-justify justify Justify +If there are multiple lines of text, specifies how +the lines are laid out relative to one another. +One of \fBleft\fP, \fBcenter\fP, or \fBright\fP. +See also \fB-anchor\fP. +.OP \-padding padding Padding +Specifies the amount of extra space to allocate for the widget. +The padding is a list of up to four length specifications +\fIleft top right bottom\fR. +If fewer than four elements are specified, +\fIbottom\fR defaults to \fItop\fR, +\fIright\fR defaults to \fIleft\fR, and +\fItop\fR defaults to \fIleft\fR. +.OP \-relief relief Relief +.\" Rewrite this: +Specifies the 3-D effect desired for the widget border. +Valid values are +\fBflat\fR, \fBgroove\fR, \fBraised\fR, \fBridge\fR, \fBsolid\fR, +and \fBsunken\fR. +.OP \-text text Text +Specifies a text string to be displayed inside the widget +(unless overridden by \fB-textvariable\fR). +.OP \-wraplength wrapLength WrapLength +Specifies the maximum line length (in pixels). +If this option is less than or equal to zero, +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" +.TP +\fIpathName \fBcget\fR \fIoption\fR +.TP +\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +.TP +\fIpathName \fBinstate \fIstatespec\fR ?\fIscript\fR? +.TP +\fIpathName \fBstate\fR ?\fIstateSpec\fR? +See \fIwidget(n)\fP +.SH "SEE ALSO" +widget(n) diff --git a/doc/ttk_labelframe.n b/doc/ttk_labelframe.n new file mode 100644 index 0000000..1eabcf2 --- /dev/null +++ b/doc/ttk_labelframe.n @@ -0,0 +1,64 @@ +'\" Copyright (c) 2005 Joe English +.so man.macros +.TH ttk_labelframe n 8.5 Tk "Tk Themed Widget" +.BS +.SH NAME +ttk::labelframe \- Container widget with optional label +.SH SYNOPSIS +\fBttk::labelframe\fR \fIpathName \fR?\fIoptions\fR? +.BE +.SH DESCRIPTION +A \fBlabelframe\fP 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. +.SO +\-class \-cursor \-takefocus \-style +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +'\" XXX: Currently included, but may go away: +'\" XXX: .OP -borderwidth borderWidth BorderWidth +'\" XXX: The desired width of the widget border. Default is theme-dependent. +'\" XXX: .OP -relief relief Relief +'\" XXX: One of the standard Tk border styles: +'\" XXX: \fBflat\fR, \fBgroove\fR, \fBraised\fR, \fBridge\fR, +'\" XXX: \fBsolid\fR, or \fBsunken\fP. +'\" XXX: Default is theme-dependent. +.OP -labelanchor labelAnchor LabelAnchor +Specifies where to place the label. +Allowed values are (clockwise from the top upper left corner): +\fBnw\fR, \fBn\fR, \fBne\fR, \fBen\fR, \fBe\fR, \fBes\fR, +\fBse\fR, \fBs\fR,\fBsw\fR, \fBws\fR, \fBw\fR and \fBwn\fR. +The default value is theme-dependent. +'\" Alternate explanation: The first character must be one of n, s, e, or w +'\" and specifies which side the label should be placed on; +'\" the remaining characters specify how the label is aligned on that side. +'\" NOTE: Now allows other values as well; leave this undocumented for now +.OP -text text Text +Specifies the text of the label. +.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 +(see \fIkeynav(n)\fR). +Mnemonic activation for a \fBttk::labelframe\fP +sets the keyboard focus to the first child of the \fBttk::labelframe\fP widget. +.OP -padding padding Padding +Additional padding to include inside the border. +.OP -labelwidget labelWidget LabelWidget +The name of a widget to use for the label. +If set, overrides the \fB-text\fP option. +The \fB-labelwidget\fP must be a child of the \fBlabelframe\fP widget +or one of the \fBlabelframe\fP's ancestors, and must belong to the +same top-level widget as the \fBlabelframe\fP. +.OP -width width Width +If specified, the widget's requested width in pixels. +.OP -height height Height +If specified, the widget's requested height in pixels. +(See \fIttk::frame\fP for further notes on \fB-width\fP and \fB-height\fP). +.SH "WIDGET COMMAND" +Supports the standard widget commands +\fBconfigure\fP, \fBcget\fP, \fBinstate\fP, and \fBstate\fP; +see \fIwidget(n)\fP. +.SH "SEE ALSO" +widget(n), frame(n) +.SH "KEYWORDS" +widget, frame, container, label, groupbox diff --git a/doc/ttk_menubutton.n b/doc/ttk_menubutton.n new file mode 100644 index 0000000..cf3c576 --- /dev/null +++ b/doc/ttk_menubutton.n @@ -0,0 +1,41 @@ +'\" +'\" Copyright (c) 2004 Joe English +'\" +.so man.macros +.TH ttk_menubutton n 8.5 Tk "Tk Themed Widget" +.BS +.SH NAME +ttk::menubutton \- Widget that pops down a menu when pressed +.SH SYNOPSIS +\fBttk::menubutton\fR \fIpathName \fR?\fIoptions\fR? +.BE +.SH DESCRIPTION +A \fBmenubutton\fP widget displays a textual label and/or image, +and displays a menu when pressed. +.SO +\-class \-compound \-cursor \-image +\-state \-style \-takefocus \-text +\-textvariable \-underline \-width +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-direction direction Direction +Specifies where the menu is to be popped up relative +to the menubutton. +One of: \fIabove\fR, \fIbelow\fR, \fIleft\fR, \fIright\fR, +or \fIflush\fR. The default is \fIbelow\fR. +\fIflush\fR pops the menu up directly over the menubutton. +.OP \-menu menu Menu +Specifies the path name of the menu associated with the menubutton. +To be on the safe side, the menu ought to be a direct child of the +menubutton. +.\" not documented: may go away: +.\" .OP \-anchor anchor Anchor +.\" .OP \-padding padding Pad +.SH "WIDGET COMMAND" +Menubutton widgets support the standard +\fBcget\fR, \fBconfigure\fR, \fBinstate\fR, and \fBstate\fR +methods. No other widget methods are used. +.SH "SEE ALSO" +widget(n), keynav(n), menu(n) +.SH "KEYWORDS" +widget, button, menu diff --git a/doc/ttk_notebook.n b/doc/ttk_notebook.n new file mode 100644 index 0000000..e123077 --- /dev/null +++ b/doc/ttk_notebook.n @@ -0,0 +1,179 @@ +'\" +'\" Copyright (c) 2004 Joe English +'\" +.so man.macros +.TH ttk_notebook n 8.5 Tk "Tk Themed Widget" +.BS +.SH NAME +ttk::notebook \- Multi-paned container widget +.SH SYNOPSIS +\fBttk::notebook\fR \fIpathName \fR?\fIoptions\fR? +.br +\fIpathName \fBadd\fR \fIpathName\fR.\fIsubwindow\fR ?\fIoptions...\fR? +\fIpathName \fBinsert\fR \fIindex\fR \fIpathName\fR.\fIsubwindow\fR ?\fIoptions...\fR? +.BE +.SH DESCRIPTION +A \fBnotebook\fP widget manages a collection of subpanes +and displays a single one at a time. +Each pane is associated with a tab, which the user +may select to change the currently-displayed pane. +.SO +\-class \-cursor \-takefocus \-style +.SE +.SH "WIDGET OPTIONS" +.OP \-height height Height +If present and greater than zero, +specifies the desired height of the pane area +(not including internal padding or tabs). +Otherwise, the maximum height of all panes is used. +.OP \-padding padding Padding +Specifies the amount of extra space to add around the outside +of the notebook. +The padding is a list of up to four length specifications +\fIleft top right bottom\fR. +If fewer than four elements are specified, +\fIbottom\fR defaults to \fItop\fR, +\fIright\fR defaults to \fIleft\fR, and +\fItop\fR defaults to \fIleft\fR. +.OP \-width width Width +If present and greater than zero, +specifies the desired width of the pane area +(not including internal padding). +Otherwise, the maximum width of all panes is used. +.SH "TAB OPTIONS" +The following options may be specified for individual notebook panes: +.OP \-state state State +Either \fBnormal\fP, \fBdisabled\fP or \fBhidden\fP. +If \fBdisabled\fP, then the tab is not selectable. If \fBhidden\fP, +then the tab is not shown. +.OP \-sticky sticky Sticky +Specifies how the child pane is positioned within the pane area. +Value is a string containing zero or more of the characters +\fBn, s, e,\fR or \fBw\fR. +Each letter refers to a side (north, south, east, or west) +that the child window will "stick" to, +as per the \fBgrid\fR geometry manager. +.OP \-padding padding Padding +Specifies the amount of extra space to add between the notebook and this pane. +Syntax is the same as for the widget \fB-padding\fP option. +.OP \-text text Text +Specifies a string to be displayed in the tab. +.OP \-image image Image +Specifies an image to display in the tab, +which must have been created with the \fBimage create\fR command. +.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. +See \fIlabel(n)\fR for legal values. +.OP \-underline underline Underline +Specifies the integer index (0-based) of a character to underline +in the text string. +The underlined character is used for mnemonic activation +if \fBttk::notebook::enableTraversal\fR is called. +.SH "WIDGET COMMAND" +.TP +\fIpathname \fBadd \fIchild\fR ?\fIoptions...\fR? +Adds a new tab to the notebook. +When the tab is selected, the \fIchild\fR window +will be displayed. +\fIchild\fR must be a direct child of the notebook window. +See \fBTAB OPTIONS\fR for the list of available \fIoptions\fR. +.TP +\fIpathname \fBconfigure\fR ?\fIoptions\fR? +See \fIwidget(n)\fR. +.TP +\fIpathname \fBcget\fR \fIoption\fR +See \fIwidget(n)\fR. +.TP +\fIpathname \fBforget\fR \fItabid\fR +Removes the tab specified by \fItabid\fR, +unmaps and unmanages the associated child window. +.TP +\fIpathname \fBindex\fR \fItabid\fR +Returns the numeric index of the tab specified by \fItabid\fR, +or the total number of tabs if \fItabid\fR is the string "\fBend\fR". +.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 notebook, +moves it to the specified position. +See \fBTAB OPTIONS\fR for the list of available options. +.TP +\fIpathname \fBinstate\fR \fIstatespec \fR?\fIscript...\fR? +See \fIwidget(n)\fR. +.TP +\fIpathname \fBselect\fR ?\fItabid\fR? +Selects the specified tab. The associated child pane will be displayed, +and the previously-selected pane (if different) is unmapped. +If \fItabid\fR is omitted, returns the widget name of the +currently selected pane. +.TP +\fIpathname \fBstate\fR ?\fIstatespec\fR? +See \fIwidget(n)\fR. +.TP +\fIpathname \fBtab\fR \fItabid\fR ?\fI-options \fR?\fIvalue ...\fR +Query or modify the options of the specific tab. +If no \fI-option\fR is specified, returns a dictionary of the tab option values. +If one \fI-option\fP is specified, returns the value of that \fIoption\fR. +Otherwise, sets the \fI-option\fRs to the corresponding \fIvalue\fRs. +See \fBTAB OPTIONS\fR for the available options. +.TP +\fIpathname \fBtabs\fR +Returns a list of all windows managed by the widget. +.\" Perhaps "panes" is a better name for this command? +.SH "KEYBOARD TRAVERSAL" +To enable keyboard traversal for a toplevel window +containing a notebook widget \fI$nb\fR, call: +.CS +ttk::notebook::enableTraversal $nb +.CE +.PP +This will extend the bindings for the toplevel widget +containing the notebook as follows: +.IP \(bu +\fBControl-Tab\fR selects the tab following the currently selected one. +.IP \(bu +\fBShift-Control-Tab\fR selects the tab preceding the currently selected one. +.IP \(bu +\fBAlt-K\fP, where \fBK\fP is the mnemonic (underlined) character +of any tab, will select that tab. +.PP +Multiple notebooks in a single toplevel may be enabled for traversal, +including nested notebooks. +However, notebook traversal only works properly if all panes +are direct children of the notebook. +.SH "TAB IDENTIFIERS" +The \fItabid\fR argument to the above commands may take +any of the following forms: +.IP \(bu +An integer between zero and the number of tabs; +.IP \(bu +The name of a child pane window; +.IP \(bu +A positional specification of the form "@\fIx\fR,\fIy\fR", +which identifies the tab +.IP \(bu +The literal string "\fBcurrent\fR", +which identifies the currently-selected tab; or: +.IP \(bu +The literal string "\fBend\fR", +which returns the number of tabs +(only valid for "\fIpathname \fBindex\fR"). + +.SH "VIRTUAL EVENTS" +The notebook widget generates a \fB<<NotebookTabChanged>>\fP +virtual event after a new tab is selected. +.SH "EXAMPLE" +.CS +notebook .nb +\.nb add [frame .nb.f1] -text "First tab" +\.nb add [frame .nb.f2] -text "Second tab" +\.nb select .nb.f2 +ttk::notebook::enableTraversal .nb +.CE +.SH "SEE ALSO" +widget(n), grid(n) +.SH "KEYWORDS" +pane, tab diff --git a/doc/ttk_panedwindow.n b/doc/ttk_panedwindow.n new file mode 100644 index 0000000..d38a007 --- /dev/null +++ b/doc/ttk_panedwindow.n @@ -0,0 +1,78 @@ +'\" $Id: ttk_panedwindow.n,v 1.1 2006/10/31 01:42:25 hobbs Exp $ +'\" Copyright (c) 2005 Joe English +.so man.macros +.TH ttk_panedwindow n 8.5 Tk "Tk Themed Widget" +.BS +.SH "NAME" +ttk::panedwindow \- Multi-pane container window +.SH SYNOPSIS +.nf +\fBttk::panedwindow\fR \fIpathName \fR?\fIoptions\fR? +.br +\fIpathName \fBadd\fR \fIpathName.subwindow\fR ?\fIoptions...\fR? +\fIpathName \fBinsert\fR \fIindex\fR \fIpathName.subwindow\fR ?\fIoptions...\fR? +.fi +.BE +.SH "DESCRIPTION" +A paned 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 +\-class \-cursor \-takefocus \-style +.SE +.SH "WIDGET OPTIONS" +.OP \-orient orient Orient +Specifies the orientation of the window. +If \fBvertical\fP, subpanes are stacked top-to-bottom; +if \fBhorizontal\fP, subpanes are stacked left-to-right. +.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 subracted to each pane proportionally to its \fB-weight\fP. +.SH "WIDGET COMMAND" +Supports the standard \fBconfigure\fR, \fBcget\fR, \fBstate\fP, +and \fBinstate\fR commands; see \fIwidget(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. +.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. +.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. +.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\fP is specified, returns the value of that \fIoption\fR. +Otherwise, sets the \fI-option\fRs to the corresponding \fIvalue\fRs. +.SH "INTERNAL ROUTINES" +The following routines are used internally by the \fBpaned\fR widget +binding code. +.TP +\fIpathname\fR \fBsashpos\fR \fIindex\fR ?\fInewpos\fR? +If \fInewpos\fR is specified, sets the sash position +(subject to constraints). +Returns the position of sash number \fIindex\fR. +.TP +\fIpathname\fR \fBidentify\fR \fIx y\fR +Returns a list consisting of the sash index at point \fIx,y\fR +and the name of the sash subelement at that point. +Returns the empty list if \fIx,y\fR is not over a sash. +.SH "SEE ALSO" +\fIwidget(n)\fR, \fInotebook(n)\fR. diff --git a/doc/ttk_progressbar.n b/doc/ttk_progressbar.n new file mode 100644 index 0000000..15ac048 --- /dev/null +++ b/doc/ttk_progressbar.n @@ -0,0 +1,79 @@ +'\" +'\" Copyright (c) 2005 Joe English +'\" +.so man.macros +.TH ttk_progressbar n 8.5 Tk "Tk Themed Widget" +.BS +.SH NAME +ttk::progressbar \- Provide progress feedback +.SH SYNOPSIS +\fBttk::progressbar\fR \fIpathName \fR?\fIoptions\fR? +.SO +\-class \-cursor \-takefocus \-style +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-orient orient Orient +One of \fBhorizontal\fP or \fBvertical\fP. +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). +.OP \-mode mode Mode +One of \fBdeterminate\fP or \fBindeterminate\fP. +.OP \-maximum maximum Maximum +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\fP; +that is, the progress bar completes one "cycle" when +the \fB-value\fP increases by \fB-maximum\fP. +.OP \-variable variable Variable +The name of a Tcl variable which is linked to the \fB-value\fP. +If specified, the \fB-value\fP 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\fP 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. +.BE +.SH "DESCRIPTION" +A progress bar widget shows the status of a long-running operation. +They can operate in two modes: \fIdeterminate\fP 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. +.SH "WIDGET COMMAND" +.TP +\fIpathName \fBcget\fR \fIoption\fR +Returns the current value of the specified \fIoption\fP; see \fIwidget(n)\fP. +.TP +\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +Modify or query widget options; see \fIwidget(n)\fP. +.TP +\fIpathName \fBinstate \fIstatespec\fR ?\fIscript\fR? +Test the widget state; see \fIwidget(n)\fP. +.TP +\fIpathName \fBstart\fR ?\fIinterval\fR? +Begin autoincrement mode: +schedules a recurring timer event that calls \fBstep\fP +every \fIinterval\fP milliseconds. +If omitted, \fIinterval\fP defaults to 50 milliseconds (20 steps/second). +.TP +\fIpathName \fBstate\fR ?\fIstateSpec\fR? +Modify or query the widget state; see \fIwidget(n)\fP. +.TP +\fIpathName \fBstep\fR ?\fIamount\fR? +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. +.SH "SEE ALSO" +widget(n) diff --git a/doc/ttk_radiobutton.n b/doc/ttk_radiobutton.n new file mode 100644 index 0000000..134b4c6 --- /dev/null +++ b/doc/ttk_radiobutton.n @@ -0,0 +1,57 @@ +'\" +'\" Copyright (c) 2004 Joe English +'\" +.so man.macros +.TH ttk_radiobutton n 8.5 Tk "Tk Themed Widget" +.BS +.SH NAME +ttk::radiobutton \- Mutually exclusive option widget +.SH SYNOPSIS +\fBttk::radiobutton\fR \fIpathName \fR?\fIoptions\fR? +.BE +.SH DESCRIPTION +\fBradiobutton\fR widgets are used in groups to show or change +a set of mutually-exclusive options. +Radiobuttons are linked to a Tcl variable, +and have an associated value; when a radiobutton is clicked, +it sets the variable to its associated value. +.SO +\-class \-compound \-cursor \-image +\-state \-style \-takefocus \-text +\-textvariable \-underline \-width +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-command command Command +A Tcl script to evaluate whenever the widget is invoked. +.OP \-value Value Value +The value to store in the associated \fI-variable\fR +when the widget is selected. +.OP \-variable variable Variable +The name of a global variable whose value is linked to the widget. +Default value is \fB::selectedButton\fP. +.SH "WIDGET COMMAND" +In addition to the standard +\fBcget\fR, \fBconfigure\fR, \fBinstate\fR, and \fBstate\fR +commands, radiobuttons support the following additional +widget commands: +.TP +\fIpathname\fR invoke +Sets the \fI-variable\fR to the \fI-value\fR, selects the widget, +and evaluates the associated \fI-command\fR. +Returns the result of the \fI-command\fR, or the empty +string if no \fI-command\fR is specified. +.\" Missing: select, deselect. Useful? +.\" Missing: flash. This is definitely not useful. +.SH "WIDGET STATES" +The widget does not respond to user input if the \fBdisabled\fP state is set. +The widget sets the \fBselected\fP state whenever +the linked \fB-variable\fP is set to the widget's \fB-value\fP, +and clears it otherwise. +The widget sets the \fBalternate\fP state whenever the +linked \fB-variable\fP is unset. +(The \fBalternate\fP state may be used to indicate a ``tri-state'' +or ``indeterminate'' selection.) +.SH "SEE ALSO" +widget(n), keynav(n), checkbutton(n) +.SH "KEYWORDS" +widget, button, option diff --git a/doc/ttk_scrollbar.n b/doc/ttk_scrollbar.n new file mode 100644 index 0000000..4593140 --- /dev/null +++ b/doc/ttk_scrollbar.n @@ -0,0 +1,160 @@ +'\" +'\" SOURCE: tk/doc/scrollbar.n, r1.4 +'\" +'\" Copyright (c) 1990-1994 The Regents of the University of California. +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" 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. +'\" +'\" $Id: ttk_scrollbar.n,v 1.1 2006/10/31 01:42:25 hobbs Exp $ +'\" +.so man.macros +.TH ttk_scrollbar n 8.5 Tk "Tk Themed Widget" +.BS +.SH NAME +ttk::scrollbar \- Control the viewport of a scrollable widget +.SH SYNOPSIS +\fBttk::scrollbar\fR \fIpathName \fR?\fIoptions...\fR? +.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\fP 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\fP (for horizontal scrollbars) +or \fByview\fP (for vertical scrollbars). +.OP \-orient orient Orient +One of \fBhorizontal\fP or \fBvertical\fP. +Specifies the orientation of the scrollbar. +.BE + +.SH DESCRIPTION +Scrollbar 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. +.SH "WIDGET COMMAND" +.TP +\fIpathName \fBcget\fR \fIoption\fR +Returns the current value of the specified \fIoption\fP; see \fIwidget(n)\fP. +.TP +\fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +Modify or query widget options; see \fIwidget(n)\fP. +.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. +.TP +\fIpathName \fBinstate \fIstatespec\fR ?\fIscript\fR? +Test the widget state; see \fIwidget(n)\fP. +.TP +\fIpathName \fBset\fR \fIfirst last\fR +This command is normally invoked by the scrollbar's associated widget +from an \fB-xscrollcommand\fP or \fB-yscrollcommand\fP 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 \fIwidget(n)\fP. +.SH "INTERNAL COMMANDS" +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. +.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. +.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. +\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 +\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. +.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. +.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. +.SH "WIDGET STATES" +The scrollbar automatically sets the \fBdisabled\fP state bit. +when the entire range is visible (range is 0.0 to 1.0), +and clears it otherwise. +It also sets the \fBactive\fP and \fBpressed\fP 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] +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 +grid columnconfigure $f 0 -weight 1 +grid rowconfigure $f 0 -weight 1 +.CE +.SH KEYWORDS +scrollbar, widget diff --git a/doc/ttk_separator.n b/doc/ttk_separator.n new file mode 100644 index 0000000..4a6a3b4 --- /dev/null +++ b/doc/ttk_separator.n @@ -0,0 +1,30 @@ +'\" $Id: ttk_separator.n,v 1.1 2006/10/31 01:42:25 hobbs Exp $ +'\" +'\" Copyright (c) 2004 Joe English +'\" +.so man.macros +.TH ttk_separator n 8.5 Tk "Tk Themed Widget" +.BS +.SH NAME +ttk::separator \- Separator bar +.SH SYNOPSIS +\fBttk::separator\fR \fIpathName \fR?\fIoptions\fR? +.BE +.SH DESCRIPTION +A \fBseparator\fP widget displays a horizontal or vertical separator bar. +.SO +\-class \-cursor \-state \-style +\-takefocus +.SE +.SH "WIDGET-SPECIFIC OPTIONS" +.OP \-orient orient Orient +One of \fBhorizontal\fP or \fBvertical\fP. +Specifies the orientation of the separator. +.SH "WIDGET COMMAND" +Separator widgets support the standard +\fBcget\fR, \fBconfigure\fR, \fBinstate\fR, and \fBstate\fR +methods. No other widget methods are used. +.SH "SEE ALSO" +widget(n) +.SH "KEYWORDS" +widget, separator diff --git a/doc/ttk_sizegrip.n b/doc/ttk_sizegrip.n new file mode 100644 index 0000000..3735f11 --- /dev/null +++ b/doc/ttk_sizegrip.n @@ -0,0 +1,53 @@ +'\" $Id: ttk_sizegrip.n,v 1.1 2006/10/31 01:42:25 hobbs Exp $ +'\" +'\" Copyright (c) 2006 Joe English +'\" +.so man.macros +.TH ttk_sizegrip n 8.5 Tk "Tk Themed Widget" +.BS +.SH NAME +ttk::sizegrip \- A silly widget +.SH SYNOPSIS +\fBttk::sizegrip\fR \fIpathName \fR?\fIoptions\fR? +.BE +.SH DESCRIPTION +A \fBsizegrip\fP widget (also known as a \fIgrow box\fR) +allows the user to resize the containing toplevel window +by pressing and dragging the grip. +.SO +\-class \-cursor \-state \-style +\-takefocus +.SE +.SH "WIDGET COMMAND" +Sizegrip widgets support the standard +\fBcget\fR, \fBconfigure\fR, \fBinstate\fR, and \fBstate\fR +methods. No other widget methods are used. +.SH "PLATFORM-SPECIFIC NOTES" +On Mac OSX, toplevel windows automatically include a built-in +size grip by default. +Adding an \fBttk::sizegrip\fP there is harmless, since +the built-in grip will just mask the widget. +.SH EXAMPLES +.CS +# Using pack: +pack [ttk::frame $top.statusbar] -side bottom -fill x +pack [ttk::sizegrip $top.statusbar.grip -side right -anchor se] + +# Using grid: +grid [ttk::sizegrip $top.statusbar.grip] \ + -row $lastRow -column $lastColumn -sticky se +# ... optional: add vertical scrollbar in $lastColumn, +# ... optional: add horizontal scrollbar in $lastRow +.CE +.SH "BUGS" +If the containing toplevel's position was specified +relative to the right or bottom of the sceen +(e.g., \fB[wm geometry ... \fIw\fBx\fIh\fB-\fIx\fB-\fIy\fB]\fR +instead of \fB[wm geometry ... \fIw\fBx\fIh\fB+\fIx\fB+\fIy\fB]\fR), +the sizegrip widget will not resize the window. +.PP +ttk::sizegrip widgets only support "southeast" resizing. +.SH "SEE ALSO" +widget(n) +.SH "KEYWORDS" +widget, sizegrip, grow box diff --git a/doc/ttk_style.n b/doc/ttk_style.n new file mode 100644 index 0000000..9b57bf8 --- /dev/null +++ b/doc/ttk_style.n @@ -0,0 +1,121 @@ +'\" +'\" Copyright (c) 2004 Joe English +'\" $Id: ttk_style.n,v 1.1 2006/10/31 01:42:25 hobbs Exp $ +'\" +.so man.macros +.TH ttk_style n 8.5 Tk "Tk Themed Widget" +.BS +.SH NAME +ttk::style \- Control overall look and feel of widgets +.SH SYNOPSIS +\fBttk::style\fR \fIoption\fR ?\fIargs\fR? +.BE +.SH NOTES +.PP +This manpage has not been written yet. +Please see the Tcl'2004 conference presentation, +available at http://tktable.sourceforge.net/tile/tile-tcl2004.pdf + +.SH DEFINITIONS +.PP +Each widget is assigned a \fIstyle\fR, +which specifies the set of elements making up the widget +and how they are arranged, along with dynamic and default +settings for element resources. +By default, the style name is the same as the widget's class; +this may be overridden by the \fB-style\fP option. +.PP +A \fItheme\fR is a collection of elements and styles +which controls the overall look and feel of an application. +.SH DESCRIPTION +The \fBttk::style\fR command takes the following arguments: +.TP +\fBttk::style configure \fIstyle\fR ?\fI-option \fR?\fIvalue option value...\fR? ? +Sets the default value of the specified option(s) in \fIstyle\fR. +.TP +\fBttk::style map \fIstyle\fR ?\fI-option\fR { \fIstatespec value\fR } ... ? +Sets dynamic values of the specified option(s) in \fIstyle\fR. +Each \fIstatespec / value\fR pair is examined in order; +the value corresponding to the first matching \fIstatespec\fP +is used. +.TP +\fBttk::style lookup \fIstyle\fR \fI-option \fR?\fIstate \fR?\fIdefault\fR?? +Returns the value specified for \fI-option\fP in style \fIstyle\fP +in state \fIstate\fP, using the standard lookup rules for element options. +\fIstate\fR is a list of state names; if omitted, +it defaults to all bits off (the ``normal'' state). +If the \fIdefault\fP argument is present, it is used as a fallback +value in case no specification for \fI-option\fP is found. +.\" Otherwise -- signal error? return empty string? Leave unspecified for now. +.TP +\fBttk::style layout \fIstyle\fR ?\fIlayoutSpec\fR? +Define the widget layout for style \fIstyle\fR. +See "\fBLAYOUTS\fR" below for the format of \fIlayoutSpec\fR. +If \fIlayoutSpec\fR is omitted, return the layout specification +for style \fIstyle\fR. +.TP +\fBttk::style element create\fR \fIelementName\fR \fItype\fR ?\fIargs...\fR? +Creates a new element in the current theme of type \fItype\fR. +The only built-in element type is \fIimage\fR (see \fIimage(n)\fR), +although themes may define other element types +(see \fBTtk_RegisterElementFactory\fR). +.TP +\fBttk::style element names\fR +Returns the list of elements defined in the current theme. +.TP +\fBttk::style element options \fIelement\fR +Returns the list of \fIelement\fR's options. +.TP +\fBttk::style theme create\fR \fIthemeName\fR ?\fB-parent \fIbasedon\fR? ?\fB-settings \fIscript...\fR ? +Creates a new theme. It is an error if \fIthemeName\fR already exists. +If \fI-parent\fR is specified, the new theme will inherit +styles, elements, and layouts from the parent theme \fIbasedon\fB. +If \fI-settings\fR is present, \fIscript\fP is evaluated in the +context of the new theme as per \fBttk::style theme settings\fP. +.TP +\fBttk::style theme settings \fIthemeName\fP \fIscript\fP +Temporarily sets the current theme to \fIthemeName\fR, +evaluate \fIscript\fR, then restore the previous theme. +Typically \fIscript\fP simply defines styles and elements, +though arbitrary Tcl code may appear. +.TP +\fBttk::style theme names\fR +Returns a list of the available themes. +.TP +\fBttk::style theme use\fR \fIthemeName\fR +Sets the current theme to \fIthemeName\fR, and refreshes all widgets. + +.SH LAYOUTS +A \fIlayout\fP 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\fP +geometry manager: given an initial cavity, +each element is allocated a parcel. +Valid options are: +.TP +\fB-side \fIside\fR +Specifies which side of the cavity to place the element; +one of \fBleft\fP, \fBright\fP, \fBtop\fP, or \fBbottom\fP. +If omitted, the element occupies the entire cavity. +.TP +\fB-sticky \fI[nswe]\fR +Specifies where the element is placed inside its allocated parcel. +.TP +\fB-children \fI{ sublayout... }\fR +Specifies a list of elements to place inside the element. +.\" Also: -border, -unit, -expand: may go away. +.PP +For example: +.CS +ttk::style layout Horizontal.TScrollbar { + Scrollbar.trough -children { + Scrollbar.leftarrow -side left + Scrollbar.rightarrow -side right + Horizontal.Scrollbar.thumb -side left -sticky ew + } +} +.CE +.SH "SEE ALSO" +ttk_intro(n), ttk_widget(n), pixmap +.SH KEYWORDS +style, theme, appearance diff --git a/doc/ttk_treeview.n b/doc/ttk_treeview.n new file mode 100644 index 0000000..c24b7f8 --- /dev/null +++ b/doc/ttk_treeview.n @@ -0,0 +1,401 @@ +'\" +'\" Copyright (c) 2004 Joe English +'\" +.so man.macros +.TH ttk_treeview n 8.5 Tk "Tk Themed Widget" +.SH NAME +ttk::treeview \- hierarchical multicolumn data display widget +.SH SYNOPSIS +\fBttk::treeview\fR \fIpathname \fR?\fIoptions\fR? +.SH "DESCRIPTION" +The treeview 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. +.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. +.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. +.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. +.\" .PP +.\" @@@HERE: describe selection, focus item +.PP +Treeview widgets support vertical scrolling with the +standard \fB-yscrollcommand\fR option and \fByview\fR widget command. +They probably ought to support horizontal scrolling as well. +.SO +\-class \-cursor \-takefocus \-style +\-yscrollcommand +.SE +.SH "WIDGET OPTIONS" +.OP \-columns columns Columns +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. +.br +If empty (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. +.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. +.OP \-selectmode selectMode SelectMode +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. +.br +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. +.RS +.IP \fBtree\fR +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. +.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. +.TP +\fIpathname \fBcget\fR \fIoption\fR +Returns the current value of the specified \fIoption\fR; see \fIwidget(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. +.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: +.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-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 \fIwidget(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. +.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. +.TP +\fIpathname \fBexists \fIitem\fR +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. +.\" 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: +.RS +.TP +\fB-text \fItext\fR +The text to display in the column heading. +.TP +\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. +.TP +\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: +.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. +.PP +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. +.br +\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 \fIwidget(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. +.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 +\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. +.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 +\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. +.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 +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. +.TP +\fIpathname \fBstate\fR ?\fIstateSpec\fR? +Modify or query the widget state; see \fIwidget(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. +.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. +.br +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. +.RE +.TP +\fIpathName \fByview \fIargs\fR +Standard command for vertical scrolling; see \fIwidget(n)\fR. + +.PP +.SH "ITEM OPTIONS" +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 +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. +.OP \-open open Open +A boolean value indicating whether the items'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. +.SH "TAG OPTIONS" +The following options may be specified on tags: +.IP \-foreground +Specifies the text foreground color. +.IP \-background +Specifies the cell or item background color. +.IP \-font +Specifies the font to use when drawing text. +.\" ??? Maybe: .IP \-anchor +.\" ??? Maybe: .IP \-padding +.\" ??? Maybe: .IP \-text +.IP \-image +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. +.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. +.PP +\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. +.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. +.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. +.IP <<TreeviewClose>> +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. +.SH "SEE ALSO" +widget(n), listbox(n), image(n), bind(n) diff --git a/doc/ttk_widget.n b/doc/ttk_widget.n new file mode 100644 index 0000000..1d7de13 --- /dev/null +++ b/doc/ttk_widget.n @@ -0,0 +1,224 @@ +'\" +'\" Copyright (c) 2004 Joe English +'\" $Id: ttk_widget.n,v 1.1 2006/10/31 01:42:25 hobbs Exp $ +'\" +.so man.macros +.TH ttk_widget n 8.5 Tk "Tk Themed Widget" +.BS +.SH NAME +widget \- Standard options and commands supported by Tk themed widgets +.BE +.SH DESCRIPTION +This manual describes common widget options and commands. +.SH "STANDARD OPTIONS" +The following options are supported by all Tk themed widgets: +.OP \-class undefined undefined +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. +.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. +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)\fP 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. +.br +Typically the \fBxScrollCommand\fR option consists of the path name +of a \fBscrollbar\fP 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. +.OP \-yscrollcommand yScrollCommand ScrollCommand +A command prefix, used to communicate with vertical scrollbars. +See the description of \fB-xscrollcommand\fP above for details. +.SH "LABEL OPTIONS" +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). +.OP \-textvariable textVariable Variable +Specifies the name of variable whose value will be used +in place of the \fB-text\fP 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 +(see \fIkeynav(n)\fR). +.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. +.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: +.RS +.IP text +Display text only. +.IP image +Display image only. +.IP center +Display text centered on top of image. +.IP top +.IP bottom +.IP left +.IP right +Display image above, below, left of, or right of the text, respectively. +.IP none +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. + +.SH "COMPATIBILITY OPTIONS" +.OP \-state state State +May be set to \fBnormal\fP or \fBdisabled\fP +to control the \fBdisabled\fP state bit. +This is a ``write-only'' option: setting it changes the +widget state, but the \fBstate\fP 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. +.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. +.\" 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 \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 +.CS +if {[\fIpathName\fR instate \fIstateSpec\fR]} \fIscript\fR +.CE +.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: +.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. +.SH "WIDGET STATES" +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"). +.TP +\fBdisabled\fR +Widget is disabled under program control +(aka "unavailable", "inactive") +.TP +\fBfocus\fR +Widget has keyboard focus +.TP +\fBpressed\fR +Widget is being pressed (aka "armed" in Motif). +.TP +\fBselected\fR +"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\fP 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\fP. +.TP +\fBinvalid\fP +The widget's value is invalid. +(Potential uses: scale widget value out of bounds, +entry widget value failed validation.) +.PP +A \fIstate specification\fP or \fIstateSpec\fP 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 + +# Invoke the widget only if it is currently pressed and enabled: +$b instate {pressed !disabled} { .b invoke } + +# Reenable widget: +$b state !disabled +.CE +.SH "SEE ALSO" +ttk_intro(n), style(n) +.SH KEYWORDS +state, configure, option |