1ttk::widget(n)                 Tk Themed Widget                 ttk::widget(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       ttk::widget - Standard options and commands supported by Tk themed wid‐
9       gets
10______________________________________________________________________________
11

DESCRIPTION

13       This manual describes common widget options and commands.
14

STANDARD OPTIONS

16       The following options are supported by all Tk themed widgets:
17
18       Command-Line Name:-class
19       Database Name:  undefined
20       Database Class: undefined
21
22              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
29       Command-Line Name:-cursor
30       Database Name:  cursor
31       Database Class: Cursor
32
33              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
38       Command-Line Name:-takefocus
39       Database Name:  takeFocus
40       Database Class: TakeFocus
41
42              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
48       Command-Line Name:-style
49       Database Name:  style
50       Database Class: Style
51
52              May be used to specify a custom widget style.
53

SCROLLABLE WIDGET OPTIONS

55       The following options are supported by widgets that are controllable by
56       a scrollbar.  See scrollbar(n) for more information
57
58       Command-Line Name:-xscrollcommand
59       Database Name:  xScrollCommand
60       Database Class: ScrollCommand
61
62              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
73              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
78              If this option is set to the empty string (the default), then no
79              command will be executed.
80
81       Command-Line Name:-yscrollcommand
82       Database Name:  yScrollCommand
83       Database Class: ScrollCommand
84
85              A  command prefix, used to communicate with vertical scrollbars.
86              See the description of -xscrollcommand above for details.
87

LABEL OPTIONS

89       The following options are supported by labels, buttons, and other  but‐
90       ton-like widgets:
91
92       Command-Line Name:-compound
93       Database Name:  compound
94       Database Class: Compound
95
96              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
102              text   Display text only.
103
104              image  Display image only.
105
106              center Display text centered on top of image.
107
108              top
109
110              bottom
111
112              left
113
114              right  Display  image  above,  below,  left  of, or right of the
115                     text, respectively.
116
117              none   Display the image if present, otherwise the text.
118
119       Command-Line Name:-font
120       Database Name:  font
121       Database Class: Font
122
123              Font to use for the text displayed by the widget.
124
125       Command-Line Name:-foreground
126       Database Name:  textColor
127       Database Class: TextColor
128
129              The widget's foreground color.  If unspecified,  the  theme  de‐
130              fault is used.
131
132       Command-Line Name:-image
133       Database Name:  image
134       Database Class: Image
135
136              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
143       Command-Line Name:-padding
144       Database Name:  padding
145       Database Class: Padding
146
147              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
156       Command-Line Name:-text
157       Database Name:  text
158       Database Class: Text
159
160              Specifies  a  text string to be displayed inside the widget (un‐
161              less overridden by -textvariable).
162
163       Command-Line Name:-textvariable
164       Database Name:  textVariable
165       Database Class: Variable
166
167              Specifies the name of a global variable whose value will be used
168              in place of the -text resource.
169
170       Command-Line Name:-underline
171       Database Name:  underline
172       Database Class: Underline
173
174              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
178       Command-Line Name:-width
179       Database Name:  width
180       Database Class: Width
181
182              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

COMPATIBILITY OPTIONS

188       This option is only available for themed widgets that have “correspond‐
189       ing” traditional Tk widgets.
190
191       Command-Line Name:-state
192       Database Name:  state
193       Database Class: State
194
195              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

COMMANDS

201       pathName cget option
202              Returns the current value of the configuration option  given  by
203              option.
204
205       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
216       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
222       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
228       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
239       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
244              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
255              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
259              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
265              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
276       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
281              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
292              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
296              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
301              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

WIDGET STATES

312       The widget state is a bitmap of independent state flags.  Widget  state
313       flags include:
314
315       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
319       disabled
320              Widget  is  disabled  under  program control (aka “unavailable”,
321              “inactive”).
322
323       focus  Widget has keyboard focus.
324
325       pressed
326              Widget is being pressed (aka “armed” in Motif).
327
328       selected
329              “On”, “true”, or “current” for things like checkbuttons and  ra‐
330              diobuttons.
331
332       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
337       readonly
338              Widget should not allow user modification.
339
340       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
345       invalid
346              The  widget's  value  is invalid.  (Potential uses: scale widget
347              value out of bounds, entry widget value failed validation.)
348
349       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
354       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

EXAMPLES

358              set b [ttk::button .b]
359
360              # Disable the widget:
361              $b state disabled
362
363              # Invoke the widget only if it is currently pressed and enabled:
364              $b instate {pressed !disabled} { .b invoke }
365
366              # Reenable widget:
367              $b state !disabled
368

SEE ALSO

370       ttk::intro(n), ttk::style(n)
371

KEYWORDS

373       state, configure, option
374
375
376
377Tk                                    8.5                       ttk::widget(n)
Impressum