1ttk::widget(n) Tk Themed Widget ttk::widget(n)
2______________________________________________________________________________
6
8 ttk::widget - Standard options and commands supported by Tk themed wid‐
9 gets
10_________________________________________________________________
11
13 This manual describes common widget options and commands.
14
16 The following options are supported by all Tk themed widgets:
17 [-class undefined] Specifies the window class. The class is used when
18 querying the option database for the window's other options, to deter‐
19 mine the default bindtags for the window, and to select the widget's
20 default layout and style. This is a read-only option: it may only be
21 specified when the window is created, and may not be changed with the
22 configure widget command. [-cursor cursor] Specifies the mouse cursor
23 to be used for the widget. See Tk_GetCursor and cursors(n) in the Tk
24 reference manual for the legal values. If set to the empty string (the
25 default), the cursor is inherited from the parent widget. [-takefo‐
26 cus takeFocus] Determines whether the window accepts the focus during
27 keyboard traversal. Either 0, 1, a command prefix (to which the widget
28 path is appended, and which should return 0 or 1), or the empty string.
29 See options(n) in the Tk reference manual for the full description.
30 [-style style] May be used to specify a custom widget style.
31
33 The following options are supported by widgets that are controllable by
34 a scrollbar. See scrollbar(n) for more information [-xscrollcom‐
35 mand xScrollCommand] A command prefix, used to communicate with hori‐
36 zontal scrollbars.
37 When the view in the widget's window changes, the widget will
38 generate a Tcl command by concatenating the scroll command and
39 two numbers. Each of the numbers is a fraction between 0 and 1
40 indicating a position in the document; 0 indicates the begin‐
41 ning, and 1 indicates the end. The first fraction indicates the
42 first information in the widget that is visible in the window,
43 and the second fraction indicates the information just after the
44 last portion that is visible.
45 Typically the xScrollCommand option consists of the path name of
47 a scrollbar widget followed by “set”, e.g. “.x.scrollbar set”.
48 This will cause the scrollbar to be updated whenever the view in
49 the window changes.
50 If this option is set to the empty string (the default), then no
52 command will be executed.
53 [-yscrollcommand yScrollCommand] A command prefix, used to communicate
54 with vertical scrollbars. See the description of -xscrollcommand above
55 for details.
56
58 The following options are supported by labels, buttons, and other but‐
59 ton-like widgets: [-text text] Specifies a text string to be displayed
60 inside the widget (unless overridden by -textvariable). [-textvari‐
61 able textVariable] Specifies the name of a global variable whose value
62 will be used in place of the -text resource. [-underline underline] If
63 set, specifies the integer index (0-based) of a character to underline
64 in the text string. The underlined character is used for mnemonic
65 activation. [-image image] Specifies an image to display. This is a
66 list of 1 or more elements. The first element is the default image
67 name. The rest of the list is a sequence of statespec / value pairs as
68 per style map, specifying different images to use when the widget is in
69 a particular state or combination of states. All images in the list
70 should have the same size. [-compound compound] Specifies how to dis‐
71 play the image relative to the text, in the case both -text and -image
72 are present. Valid values are:
73 text Display text only.
75 image Display image only.
77 center Display text centered on top of image.
79 top
81 bottom
83 left
85 right Display image above, below, left of, or right of the
87 text, respectively.
88 none The default; display the image if present, otherwise the
90 text.
91 [-width width] If greater than zero, specifies how much space, in char‐
92 acter widths, to allocate for the text label. If less than zero, spec‐
93 ifies a minimum width. If zero or unspecified, the natural width of
94 the text label is used.
95
97 [-state state] May be set to normal or disabled to control the disabled
98 state bit. This is a write-only option: setting it changes the widget
99 state, but the state widget command does not affect the -state option.
100
102 pathName cget option
103 Returns the current value of the configuration option given by
104 option.
105 pathName configure ?option? ?value option value ...?
107 Query or modify the configuration options of the widget. If one
108 or more option-value pairs are specified, then the command modi‐
109 fies the given widget option(s) to have the given value(s); in
110 this case the command returns an empty string. If option is
111 specified with no value, then the command returns a list
112 describing the named option: the elements of the list are the
113 option name, database name, database class, default value, and
114 current value. If no option is specified, returns a list
115 describing all of the available options for pathName.
116 pathName identify element x y
118 Returns the name of the element under the point given by x and
119 y, or an empty string if the point does not lie within any ele‐
120 ment. x and y are pixel coordinates relative to the widget.
121 Some widgets accept other identify subcommands.
122 pathName instate statespec ?script?
124 Test the widget's state. If script is not specified, returns 1
125 if the widget state matches statespec and 0 otherwise. If
126 script is specified, equivalent to
127 if {[pathName instate stateSpec]} script
128 pathName state ?stateSpec?
130 Modify or inquire widget state. If stateSpec is present, sets
131 the widget state: for each flag in stateSpec, sets the corre‐
132 sponding flag or clears it if prefixed by an exclamation point.
133 Returns a new state spec indicating which flags were changed:
134 set changes [pathName state spec]
135 pathName state $changes
136 will restore pathName to the original state. If stateSpec is
137 not specified, returns a list of the currently-enabled state
138 flags.
139
141 The widget state is a bitmap of independent state flags. Widget state
142 flags include:
143 active The mouse cursor is over the widget and pressing a mouse button
145 will cause some action to occur. (aka “prelight” (Gnome), “hot”
146 (Windows), “hover”).
147 disabled
149 Widget is disabled under program control (aka “unavailable”,
150 “inactive”)
151 focus Widget has keyboard focus
153 pressed
155 Widget is being pressed (aka “armed” in Motif).
156 selected
158 “On”, “true”, or “current” for things like checkbuttons and
159 radiobuttons.
160 background
162 Windows and the Mac have a notion of an “active” or foreground
163 window. The background state is set for widgets in a background
164 window, and cleared for those in the foreground window.
165 readonly
167 Widget should not allow user modification.
168 alternate
170 A widget-specific alternate display format. For example, used
171 for checkbuttons and radiobuttons in the “tristate” or “mixed”
172 state, and for buttons with -default active.
173 invalid
175 The widget's value is invalid. (Potential uses: scale widget
176 value out of bounds, entry widget value failed validation.)
177 hover The mouse cursor is within the widget. This is similar to the
179 active state; it is used in some themes for widgets that provide
180 distinct visual feedback for the active widget in addition to
181 the active element within the widget.
182 A state specification or stateSpec is a list of state names, optionally
184 prefixed with an exclamation point (!) indicating that the bit is off.
185
187 set b [ttk::button .b]
188 # Disable the widget:
190 $b state disabled
191 # Invoke the widget only if it is currently pressed and enabled:
193 $b instate {pressed !disabled} { .b invoke }
194 # Reenable widget:
196 $b state !disabled
197
199 ttk::intro(n), ttk::style(n)
200
202 state, configure, option
203Tk 8.5.9 ttk::widget(n)