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
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
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.  Valid values are:
98
99              text   Display text only.
100
101              image  Display image only.
102
103              center Display text centered on top of image.
104
105              top
106
107              bottom
108
109              left
110
111              right  Display image above, below, left  of,  or  right  of  the
112                     text, respectively.
113
114              none   The  default; display the image if present, otherwise the
115                     text.
116
117       Command-Line Name:-image
118       Database Name:  image
119       Database Class: Image
120
121              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
128       Command-Line Name:-padding
129       Database Name:  padding
130       Database Class: Padding
131
132              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
141       Command-Line Name:-text
142       Database Name:  text
143       Database Class: Text
144
145              Specifies a text  string  to  be  displayed  inside  the  widget
146              (unless overridden by -textvariable).
147
148       Command-Line Name:-textvariable
149       Database Name:  textVariable
150       Database Class: Variable
151
152              Specifies the name of a global variable whose value will be used
153              in place of the -text resource.
154
155       Command-Line Name:-underline
156       Database Name:  underline
157       Database Class: Underline
158
159              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
163       Command-Line Name:-width
164       Database Name:  width
165       Database Class: Width
166
167              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

COMPATIBILITY OPTIONS

173       This option is only available for themed widgets that have “correspond‐
174       ing” traditional Tk widgets.
175
176       Command-Line Name:-state
177       Database Name:  state
178       Database Class: State
179
180              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

COMMANDS

186       pathName cget option
187              Returns  the  current value of the configuration option given by
188              option.
189
190       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
201       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
207       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
213       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
224       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
229              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
240              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
244              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
250              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
261       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
266              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
277              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
281              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
286              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

WIDGET STATES

297       The  widget state is a bitmap of independent state flags.  Widget state
298       flags include:
299
300       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
304       disabled
305              Widget is disabled under  program  control  (aka  “unavailable”,
306              “inactive”).
307
308       focus  Widget has keyboard focus.
309
310       pressed
311              Widget is being pressed (aka “armed” in Motif).
312
313       selected
314              “On”,  “true”,  or  “current”  for  things like checkbuttons and
315              radiobuttons.
316
317       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
322       readonly
323              Widget should not allow user modification.
324
325       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
330       invalid
331              The widget's value is invalid.  (Potential  uses:  scale  widget
332              value out of bounds, entry widget value failed validation.)
333
334       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
339       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

EXAMPLES

343              set b [ttk::button .b]
344
345              # Disable the widget:
346              $b state disabled
347
348              # Invoke the widget only if it is currently pressed and enabled:
349              $b instate {pressed !disabled} { .b invoke }
350
351              # Reenable widget:
352              $b state !disabled
353

SEE ALSO

355       ttk::intro(n), ttk::style(n)
356

KEYWORDS

358       state, configure, option
359
360
361
362Tk                                    8.5                       ttk::widget(n)
Impressum