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 Command-Line Name:-class
19 Database Name: undefined
20 Database Class: undefined
21 Specifies the window class. The class is used when querying the
23 option database for the window's other options, to determine the
24 default bindtags for the window, and to select the widget's
25 default layout and style. This is a read-only option: it may
26 only be specified when the window is created, and may not be
27 changed with the configure widget command.
28 Command-Line Name:-cursor
30 Database Name: cursor
31 Database Class: Cursor
32 Specifies the mouse cursor to be used for the widget. See
34 Tk_GetCursor and cursors(n) in the Tk reference manual for the
35 legal values. If set to the empty string (the default), the
36 cursor is inherited from the parent widget.
37 Command-Line Name:-takefocus
39 Database Name: takeFocus
40 Database Class: TakeFocus
41 Determines whether the window accepts the focus during keyboard
43 traversal. Either 0, 1, a command prefix (to which the widget
44 path is appended, and which should return 0 or 1), or the empty
45 string. See options(n) in the Tk reference manual for the full
46 description.
47 Command-Line Name:-style
49 Database Name: style
50 Database Class: Style
51 May be used to specify a custom widget style.
53
55 The following options are supported by widgets that are controllable by
56 a scrollbar. See scrollbar(n) for more information
57 Command-Line Name:-xscrollcommand
59 Database Name: xScrollCommand
60 Database Class: ScrollCommand
61 A command prefix, used to communicate with horizontal scroll‐
63 bars.
64 When the view in the widget's window changes, the widget will
65 generate a Tcl command by concatenating the scroll command and
66 two numbers. Each of the numbers is a fraction between 0 and 1
67 indicating a position in the document; 0 indicates the begin‐
68 ning, and 1 indicates the end. The first fraction indicates the
69 first information in the widget that is visible in the window,
70 and the second fraction indicates the information just after the
71 last portion that is visible.
72 Typically the -xscrollcommand option consists of the path name
74 of a scrollbar widget followed by “set”, e.g. “.x.scrollbar
75 set”. This will cause the scrollbar to be updated whenever the
76 view in the window changes.
77 If this option is set to the empty string (the default), then no
79 command will be executed.
80 Command-Line Name:-yscrollcommand
82 Database Name: yScrollCommand
83 Database Class: ScrollCommand
84 A command prefix, used to communicate with vertical scrollbars.
86 See the description of -xscrollcommand above for details.
87
89 The following options are supported by labels, buttons, and other but‐
90 ton-like widgets:
91 Command-Line Name:-compound
93 Database Name: compound
94 Database Class: Compound
95 Specifies how to display the image relative to the text, in the
97 case both -text and -image are present. Valid values are:
98 text Display text only.
100 image Display image only.
102 center Display text centered on top of image.
104 top
106 bottom
108 left
110 right Display image above, below, left of, or right of the
112 text, respectively.
113 none The default; display the image if present, otherwise the
115 text.
116 Command-Line Name:-image
118 Database Name: image
119 Database Class: Image
120 Specifies an image to display. This is a list of 1 or more ele‐
122 ments. The first element is the default image name. The rest
123 of the list is a sequence of statespec / value pairs as per
124 style map, specifying different images to use when the widget is
125 in a particular state or combination of states. All images in
126 the list should have the same size.
127 Command-Line Name:-padding
129 Database Name: padding
130 Database Class: Padding
131 Specifies the internal padding for the widget. The padding is a
133 list of up to four length specifications left top right bottom.
134 If fewer than four elements are specified, bottom defaults to
135 top, right defaults to left, and top defaults to left. In other
136 words, a list of three numbers specify the left, vertical, and
137 right padding; a list of two numbers specify the horizontal and
138 the vertical padding; a single number specifies the same padding
139 all the way around the widget.
140 Command-Line Name:-text
142 Database Name: text
143 Database Class: Text
144 Specifies a text string to be displayed inside the widget
146 (unless overridden by -textvariable).
147 Command-Line Name:-textvariable
149 Database Name: textVariable
150 Database Class: Variable
151 Specifies the name of a global variable whose value will be used
153 in place of the -text resource.
154 Command-Line Name:-underline
156 Database Name: underline
157 Database Class: Underline
158 If set, specifies the integer index (0-based) of a character to
160 underline in the text string. The underlined character is used
161 for mnemonic activation.
162 Command-Line Name:-width
164 Database Name: width
165 Database Class: Width
166 If greater than zero, specifies how much space, in character
168 widths, to allocate for the text label. If less than zero,
169 specifies a minimum width. If zero or unspecified, the natural
170 width of the text label is used.
171
173 This option is only available for themed widgets that have “correspond‐
174 ing” traditional Tk widgets.
175 Command-Line Name:-state
177 Database Name: state
178 Database Class: State
179 May be set to normal or disabled to control the disabled state
181 bit. This is a write-only option: setting it changes the widget
182 state, but the state widget command does not affect the -state
183 option.
184
186 pathName cget option
187 Returns the current value of the configuration option given by
188 option.
189 pathName configure ?option? ?value option value ...?
191 Query or modify the configuration options of the widget. If one
192 or more option-value pairs are specified, then the command modi‐
193 fies the given widget option(s) to have the given value(s); in
194 this case the command returns an empty string. If option is
195 specified with no value, then the command returns a list
196 describing the named option: the elements of the list are the
197 option name, database name, database class, default value, and
198 current value. If no option is specified, returns a list
199 describing all of the available options for pathName.
200 pathName identify element x y
202 Returns the name of the element under the point given by x and
203 y, or an empty string if the point does not lie within any ele‐
204 ment. x and y are pixel coordinates relative to the widget.
205 Some widgets accept other identify subcommands.
206 pathName instate statespec ?script?
208 Test the widget's state. If script is not specified, returns 1
209 if the widget state matches statespec and 0 otherwise. If
210 script is specified, equivalent to
211 if {[pathName instate stateSpec]} script
212 pathName state ?stateSpec?
214 Modify or inquire widget state. If stateSpec is present, sets
215 the widget state: for each flag in stateSpec, sets the corre‐
216 sponding flag or clears it if prefixed by an exclamation point.
217 Returns a new state spec indicating which flags were changed:
218 set changes [pathName state spec]
219 pathName state $changes
220 will restore pathName to the original state. If stateSpec is
221 not specified, returns a list of the currently-enabled state
222 flags.
223 pathName xview args
225 This command is used to query and change the horizontal position
226 of the content in the widget's window. It can take any of the
227 following forms:
228 pathName xview
230 Returns a list containing two elements. Each element is
231 a real fraction between 0 and 1; together they describe
232 the horizontal span that is visible in the window. For
233 example, if the first element is .2 and the second ele‐
234 ment is .6, 20% of the widget's content is off-screen to
235 the left, the middle 40% is visible in the window, and
236 40% of the content is off-screen to the right. These are
237 the same values passed to scrollbars via the -xscrollcom‐
238 mand option.
239 pathName xview index
241 Adjusts the view in the window so that the content given
242 by index is displayed at the left edge of the window.
243 pathName xview moveto fraction
245 Adjusts the view in the window so that the character
246 fraction of the way through the content appears at the
247 left edge of the window. Fraction must be a fraction
248 between 0 and 1.
249 pathName xview scroll number what
251 This command shifts the view in the window left or right
252 according to number and what. Number must be an integer.
253 What must be either units or pages. If what is units,
254 the view adjusts left or right by number average-width
255 characters on the display; if it is pages then the view
256 adjusts by number screenfuls. If number is negative then
257 characters farther to the left become visible; if it is
258 positive then characters farther to the right become vis‐
259 ible.
260 pathName yview args
262 This command is used to query and change the vertical position
263 of the content in the widget's window. It can take any of the
264 following forms:
265 pathName yview
267 Returns a list containing two elements. Each element is
268 a real fraction between 0 and 1; together they describe
269 the vertical span that is visible in the window. For
270 example, if the first element is .2 and the second ele‐
271 ment is .6, 20% of the widget's content is off-screen to
272 the top, the middle 40% is visible in the window, and 40%
273 of the content is off-screen to the bottom. These are
274 the same values passed to scrollbars via the -yscrollcom‐
275 mand option.
276 pathName yview index
278 Adjusts the view in the window so that the content given
279 by index is displayed at the top edge of the window.
280 pathName yview moveto fraction
282 Adjusts the view in the window so that the item fraction
283 of the way through the content appears at the top edge of
284 the window. Fraction must be a fraction between 0 and 1.
285 pathName yview scroll number what
287 This command shifts the view in the window up or down
288 according to number and what. Number must be an integer.
289 What must be either units or pages. If what is units,
290 the view adjusts up or down by number average-width char‐
291 acters on the display; if it is pages then the view
292 adjusts by number screenfuls. If number is negative then
293 items farther to the top become visible; if it is posi‐
294 tive then items farther to the bottom become visible.
295
297 The widget state is a bitmap of independent state flags. Widget state
298 flags include:
299 active The mouse cursor is over the widget and pressing a mouse button
301 will cause some action to occur. (aka “prelight” (Gnome), “hot”
302 (Windows), “hover”).
303 disabled
305 Widget is disabled under program control (aka “unavailable”,
306 “inactive”).
307 focus Widget has keyboard focus.
309 pressed
311 Widget is being pressed (aka “armed” in Motif).
312 selected
314 “On”, “true”, or “current” for things like checkbuttons and
315 radiobuttons.
316 background
318 Windows and the Mac have a notion of an “active” or foreground
319 window. The background state is set for widgets in a background
320 window, and cleared for those in the foreground window.
321 readonly
323 Widget should not allow user modification.
324 alternate
326 A widget-specific alternate display format. For example, used
327 for checkbuttons and radiobuttons in the “tristate” or “mixed”
328 state, and for buttons with -default active.
329 invalid
331 The widget's value is invalid. (Potential uses: scale widget
332 value out of bounds, entry widget value failed validation.)
333 hover The mouse cursor is within the widget. This is similar to the
335 active state; it is used in some themes for widgets that provide
336 distinct visual feedback for the active widget in addition to
337 the active element within the widget.
338 A state specification or stateSpec is a list of state names, optionally
340 prefixed with an exclamation point (!) indicating that the bit is off.
341
343 set b [ttk::button .b]
344 # Disable the widget:
346 $b state disabled
347 # Invoke the widget only if it is currently pressed and enabled:
349 $b instate {pressed !disabled} { .b invoke }
350 # Reenable widget:
352 $b state !disabled
353
355 ttk::intro(n), ttk::style(n)
356
358 state, configure, option
359Tk 8.5 ttk::widget(n)