diff options
Diffstat (limited to 'doc/ttk_widget.n')
| -rw-r--r-- | doc/ttk_widget.n | 262 |
1 files changed, 262 insertions, 0 deletions
diff --git a/doc/ttk_widget.n b/doc/ttk_widget.n new file mode 100644 index 0000000..98968ad --- /dev/null +++ b/doc/ttk_widget.n @@ -0,0 +1,262 @@ +'\" +'\" 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::widget n 8.5.9 Tk "Tk Themed Widget" +.BS +.SH NAME +ttk::widget \- Standard options and commands supported by Tk themed widgets +.BE +.SH DESCRIPTION +This manual describes common widget options and commands. +.SH "STANDARD OPTIONS" +The following options are supported by all Tk themed widgets: +.OP \-class undefined undefined +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" +The following options are supported by widgets that +are controllable by a scrollbar. +See \fIscrollbar(n)\fR for more information +.OP \-xscrollcommand xScrollCommand ScrollCommand +A command prefix, used to communicate with horizontal scrollbars. +.RS +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. +.PP +Typically the \fBxScrollCommand\fR option consists of the path name +of a \fBscrollbar\fR widget followed by +.QW set , +e.g. +.QW ".x.scrollbar set" . +This will cause the scrollbar to be updated whenever the view in the +window changes. +.PP +If this option is set to the empty string (the default), +then no command will be executed. +.RE +.OP \-yscrollcommand yScrollCommand ScrollCommand +A command prefix, used to communicate with vertical scrollbars. +See the description of \fB\-xscrollcommand\fR above for details. +.SH "LABEL OPTIONS" +The following options are supported by labels, buttons, +and other button-like widgets: +.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 a global variable whose value will be used +in place of the \fB\-text\fR resource. +.OP \-underline underline Underline +If set, specifies the integer index (0-based) of a character to underline +in the text string. +The underlined character is used for mnemonic activation. +.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\fR or \fBdisabled\fR +to control the \fBdisabled\fR state bit. +This is a write-only option: +setting it changes the widget state, +but the \fBstate\fR widget command +does not affect the \fB\-state\fR 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 \fBidentify\fR \fBelement\fR \fIx y\fR +Returns the name of the element under the point given +by \fIx\fR and \fIy\fR, or an empty string if the point does +not lie within any element. +\fIx\fR and \fIy\fR are pixel coordinates relative to the widget. +Some widgets accept other \fBidentify\fR subcommands. +.TP +\fIpathName \fBinstate\fR \fIstatespec\fR ?\fIscript\fR? +Test the widget's state. +If \fIscript\fR is not specified, returns 1 if +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. +.RS +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. +.RE +.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 +.QW prelight +(Gnome), +.QW hot +(Windows), +.QW hover ). +.TP +\fBdisabled\fR +Widget is disabled under program control (aka +.QW unavailable , +.QW inactive ) +.TP +\fBfocus\fR +Widget has keyboard focus +.TP +\fBpressed\fR +Widget is being pressed (aka +.QW armed +in Motif). +.TP +\fBselected\fR +.QW On , +.QW true , +or +.QW current +for things like checkbuttons and radiobuttons. +.TP +\fBbackground\fR +Windows and the Mac have a notion of an +.QW active +or foreground window. +The \fBbackground\fR state is set for widgets in a background window, +and cleared for those in the foreground window. +.TP +\fBreadonly\fR +Widget should not allow user modification. +.TP +\fBalternate\fR +A widget-specific alternate display format. +For example, used for checkbuttons and radiobuttons in the +.QW tristate +or +.QW mixed +state, and for buttons with \fB\-default active\fR. +.TP +\fBinvalid\fR +The widget's value is invalid. +(Potential uses: scale widget value out of bounds, +entry widget value failed validation.) +.TP +\fBhover\fR +The mouse cursor is within the widget. +This is similar to the \fBactive\fP state; +it is used in some themes for widgets that +provide distinct visual feedback for +the active widget in addition to the active element +within the widget. +.PP +A \fIstate specification\fR or \fIstateSpec\fR is a list +of state names, optionally prefixed with an exclamation point (!) +indicating that the bit is off. +.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), ttk::style(n) +.SH KEYWORDS +state, configure, option +'\" Local Variables: +'\" mode: nroff +'\" End: |