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 de‐
25 fault layout and style. This is a read-only option: it may only
26 be specified when the window is created, and may not be changed
27 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. If set to the empty
98 string (the default), the rules described in the "Elements" sec‐
99 tion of ttk::intro(n) explain which value is actually used.
100 Valid values are:
101 text Display text only.
103 image Display image only.
105 center Display text centered on top of image.
107 top
109 bottom
111 left
113 right Display image above, below, left of, or right of the
115 text, respectively.
116 none Display the image if present, otherwise the text.
118 Command-Line Name:-font
120 Database Name: font
121 Database Class: Font
122 Font to use for the text displayed by the widget.
124 Command-Line Name:-foreground
126 Database Name: textColor
127 Database Class: TextColor
128 The widget's foreground color. If unspecified, the theme de‐
130 fault is used.
131 Command-Line Name:-image
133 Database Name: image
134 Database Class: Image
135 Specifies an image to display. This is a list of 1 or more ele‐
137 ments. The first element is the default image name. The rest
138 of the list is a sequence of statespec / value pairs as per
139 style map, specifying different images to use when the widget is
140 in a particular state or combination of states. All images in
141 the list should have the same size.
142 Command-Line Name:-padding
144 Database Name: padding
145 Database Class: Padding
146 Specifies the internal padding for the widget. The padding is a
148 list of up to four length specifications left top right bottom.
149 If fewer than four elements are specified, bottom defaults to
150 top, right defaults to left, and top defaults to left. In other
151 words, a list of three numbers specify the left, vertical, and
152 right padding; a list of two numbers specify the horizontal and
153 the vertical padding; a single number specifies the same padding
154 all the way around the widget.
155 Command-Line Name:-text
157 Database Name: text
158 Database Class: Text
159 Specifies a text string to be displayed inside the widget (un‐
161 less overridden by -textvariable).
162 Command-Line Name:-textvariable
164 Database Name: textVariable
165 Database Class: Variable
166 Specifies the name of a global variable whose value will be used
168 in place of the -text resource.
169 Command-Line Name:-underline
171 Database Name: underline
172 Database Class: Underline
173 If set, specifies the integer index (0-based) of a character to
175 underline in the text string. The underlined character is used
176 for mnemonic activation.
177 Command-Line Name:-width
179 Database Name: width
180 Database Class: Width
181 If greater than zero, specifies how much space, in character
183 widths, to allocate for the text label. If less than zero,
184 specifies a minimum width. If zero or unspecified, the natural
185 width of the text label is used.
186
188 This option is only available for themed widgets that have “correspond‐
189 ing” traditional Tk widgets.
190 Command-Line Name:-state
192 Database Name: state
193 Database Class: State
194 May be set to normal or disabled to control the disabled state
196 bit. This is a write-only option: setting it changes the widget
197 state, but the state widget command does not affect the -state
198 option.
199
201 pathName cget option
202 Returns the current value of the configuration option given by
203 option.
204 pathName configure ?option? ?value option value ...?
206 Query or modify the configuration options of the widget. If one
207 or more option-value pairs are specified, then the command modi‐
208 fies the given widget option(s) to have the given value(s); in
209 this case the command returns an empty string. If option is
210 specified with no value, then the command returns a list de‐
211 scribing the named option: the elements of the list are the op‐
212 tion name, database name, database class, default value, and
213 current value. If no option is specified, returns a list de‐
214 scribing all of the available options for pathName.
215 pathName identify element x y
217 Returns the name of the element under the point given by x and
218 y, or an empty string if the point does not lie within any ele‐
219 ment. x and y are pixel coordinates relative to the widget.
220 Some widgets accept other identify subcommands.
221 pathName instate statespec ?script?
223 Test the widget's state. If script is not specified, returns 1
224 if the widget state matches statespec and 0 otherwise. If
225 script is specified, equivalent to
226 if {[pathName instate stateSpec]} script
227 pathName state ?stateSpec?
229 Modify or inquire widget state. If stateSpec is present, sets
230 the widget state: for each flag in stateSpec, sets the corre‐
231 sponding flag or clears it if prefixed by an exclamation point.
232 Returns a new state spec indicating which flags were changed:
233 set changes [pathName state spec]
234 pathName state $changes
235 will restore pathName to the original state. If stateSpec is
236 not specified, returns a list of the currently-enabled state
237 flags.
238 pathName xview args
240 This command is used to query and change the horizontal position
241 of the content in the widget's window. It can take any of the
242 following forms:
243 pathName xview
245 Returns a list containing two elements. Each element is
246 a real fraction between 0 and 1; together they describe
247 the horizontal span that is visible in the window. For
248 example, if the first element is .2 and the second ele‐
249 ment is .6, 20% of the widget's content is off-screen to
250 the left, the middle 40% is visible in the window, and
251 40% of the content is off-screen to the right. These are
252 the same values passed to scrollbars via the -xscrollcom‐
253 mand option.
254 pathName xview index
256 Adjusts the view in the window so that the content given
257 by index is displayed at the left edge of the window.
258 pathName xview moveto fraction
260 Adjusts the view in the window so that the character
261 fraction of the way through the content appears at the
262 left edge of the window. Fraction must be a fraction be‐
263 tween 0 and 1.
264 pathName xview scroll number what
266 This command shifts the view in the window left or right
267 according to number and what. Number must be an integer.
268 What must be either units or pages. If what is units,
269 the view adjusts left or right by number average-width
270 characters on the display; if it is pages then the view
271 adjusts by number screenfuls. If number is negative then
272 characters farther to the left become visible; if it is
273 positive then characters farther to the right become vis‐
274 ible.
275 pathName yview args
277 This command is used to query and change the vertical position
278 of the content in the widget's window. It can take any of the
279 following forms:
280 pathName yview
282 Returns a list containing two elements. Each element is
283 a real fraction between 0 and 1; together they describe
284 the vertical span that is visible in the window. For ex‐
285 ample, if the first element is .2 and the second element
286 is .6, 20% of the widget's content is off-screen to the
287 top, the middle 40% is visible in the window, and 40% of
288 the content is off-screen to the bottom. These are the
289 same values passed to scrollbars via the -yscrollcommand
290 option.
291 pathName yview index
293 Adjusts the view in the window so that the content given
294 by index is displayed at the top edge of the window.
295 pathName yview moveto fraction
297 Adjusts the view in the window so that the item fraction
298 of the way through the content appears at the top edge of
299 the window. Fraction must be a fraction between 0 and 1.
300 pathName yview scroll number what
302 This command shifts the view in the window up or down ac‐
303 cording to number and what. Number must be an integer.
304 What must be either units or pages. If what is units,
305 the view adjusts up or down by number average-width char‐
306 acters on the display; if it is pages then the view ad‐
307 justs by number screenfuls. If number is negative then
308 items farther to the top become visible; if it is posi‐
309 tive then items farther to the bottom become visible.
310
312 The widget state is a bitmap of independent state flags. Widget state
313 flags include:
314 active The mouse cursor is over the widget and pressing a mouse button
316 will cause some action to occur. (aka “prelight” (Gnome), “hot”
317 (Windows), “hover”).
318 disabled
320 Widget is disabled under program control (aka “unavailable”,
321 “inactive”).
322 focus Widget has keyboard focus.
324 pressed
326 Widget is being pressed (aka “armed” in Motif).
327 selected
329 “On”, “true”, or “current” for things like checkbuttons and ra‐
330 diobuttons.
331 background
333 Windows and the Mac have a notion of an “active” or foreground
334 window. The background state is set for widgets in a background
335 window, and cleared for those in the foreground window.
336 readonly
338 Widget should not allow user modification.
339 alternate
341 A widget-specific alternate display format. For example, used
342 for checkbuttons and radiobuttons in the “tristate” or “mixed”
343 state, and for buttons with -default active.
344 invalid
346 The widget's value is invalid. (Potential uses: scale widget
347 value out of bounds, entry widget value failed validation.)
348 hover The mouse cursor is within the widget. This is similar to the
350 active state; it is used in some themes for widgets that provide
351 distinct visual feedback for the active widget in addition to
352 the active element within the widget.
353 A state specification or stateSpec is a list of state names, optionally
355 prefixed with an exclamation point (!) indicating that the bit is off.
356
358 set b [ttk::button .b]
359 # Disable the widget:
361 $b state disabled
362 # Invoke the widget only if it is currently pressed and enabled:
364 $b instate {pressed !disabled} { .b invoke }
365 # Reenable widget:
367 $b state !disabled
368
370 ttk::intro(n), ttk::style(n)
371
373 state, configure, option
374Tk 8.5 ttk::widget(n)