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 Command-Line Name:-state
174 Database Name: state
175 Database Class: State
176 May be set to normal or disabled to control the disabled state
178 bit. This is a write-only option: setting it changes the widget
179 state, but the state widget command does not affect the -state
180 option.
181
183 pathName cget option
184 Returns the current value of the configuration option given by
185 option.
186 pathName configure ?option? ?value option value ...?
188 Query or modify the configuration options of the widget. If one
189 or more option-value pairs are specified, then the command modi‐
190 fies the given widget option(s) to have the given value(s); in
191 this case the command returns an empty string. If option is
192 specified with no value, then the command returns a list
193 describing the named option: the elements of the list are the
194 option name, database name, database class, default value, and
195 current value. If no option is specified, returns a list
196 describing all of the available options for pathName.
197 pathName identify element x y
199 Returns the name of the element under the point given by x and
200 y, or an empty string if the point does not lie within any ele‐
201 ment. x and y are pixel coordinates relative to the widget.
202 Some widgets accept other identify subcommands.
203 pathName instate statespec ?script?
205 Test the widget's state. If script is not specified, returns 1
206 if the widget state matches statespec and 0 otherwise. If
207 script is specified, equivalent to
208 if {[pathName instate stateSpec]} script
209 pathName state ?stateSpec?
211 Modify or inquire widget state. If stateSpec is present, sets
212 the widget state: for each flag in stateSpec, sets the corre‐
213 sponding flag or clears it if prefixed by an exclamation point.
214 Returns a new state spec indicating which flags were changed:
215 set changes [pathName state spec]
216 pathName state $changes
217 will restore pathName to the original state. If stateSpec is
218 not specified, returns a list of the currently-enabled state
219 flags.
220
222 The widget state is a bitmap of independent state flags. Widget state
223 flags include:
224 active The mouse cursor is over the widget and pressing a mouse button
226 will cause some action to occur. (aka “prelight” (Gnome), “hot”
227 (Windows), “hover”).
228 disabled
230 Widget is disabled under program control (aka “unavailable”,
231 “inactive”).
232 focus Widget has keyboard focus.
234 pressed
236 Widget is being pressed (aka “armed” in Motif).
237 selected
239 “On”, “true”, or “current” for things like checkbuttons and
240 radiobuttons.
241 background
243 Windows and the Mac have a notion of an “active” or foreground
244 window. The background state is set for widgets in a background
245 window, and cleared for those in the foreground window.
246 readonly
248 Widget should not allow user modification.
249 alternate
251 A widget-specific alternate display format. For example, used
252 for checkbuttons and radiobuttons in the “tristate” or “mixed”
253 state, and for buttons with -default active.
254 invalid
256 The widget's value is invalid. (Potential uses: scale widget
257 value out of bounds, entry widget value failed validation.)
258 hover The mouse cursor is within the widget. This is similar to the
260 active state; it is used in some themes for widgets that provide
261 distinct visual feedback for the active widget in addition to
262 the active element within the widget.
263 A state specification or stateSpec is a list of state names, optionally
265 prefixed with an exclamation point (!) indicating that the bit is off.
266
268 set b [ttk::button .b]
269 # Disable the widget:
271 $b state disabled
272 # Invoke the widget only if it is currently pressed and enabled:
274 $b instate {pressed !disabled} { .b invoke }
275 # Reenable widget:
277 $b state !disabled
278
280 ttk::intro(n), ttk::style(n)
281
283 state, configure, option
284Tk 8.5 ttk::widget(n)