1button(n) Tk Built-In Commands button(n)
2______________________________________________________________________________
6
8 button - Create and manipulate 'button' action widgets
9
11 button pathName ?options?
12
14 -activebackground -font -relief
15 -activeforeground -foreground -repeatdelay
16 -anchor -highlightbackground -repeatinterval
17 -background -highlightcolor -takefocus
18 -bitmap -highlightthickness -text
19 -borderwidth -image -textvariable
20 -compound -justify -underline
21 -cursor -padx -wraplength
22 -disabledforeground -pady
23 See the options manual entry for details on the standard options.
25
27 Command-Line Name:-command
28 Database Name: command
29 Database Class: Command
30 Specifies a Tcl command to associate with the button. This com‐
32 mand is typically invoked when mouse button 1 is released over
33 the button window.
34 Command-Line Name:-default
36 Database Name: default
37 Database Class: Default
38 Specifies one of three states for the default ring: normal,
40 active, or disabled. In active state, the button is drawn with
41 the platform specific appearance for a default button. In nor‐
42 mal state, the button is drawn with the platform specific
43 appearance for a non-default button, leaving enough space to
44 draw the default button appearance. The normal and active
45 states will result in buttons of the same size. In disabled
46 state, the button is drawn with the non-default button appear‐
47 ance without leaving space for the default appearance. The dis‐
48 abled state may result in a smaller button than the active
49 state.
50 Command-Line Name:-height
52 Database Name: height
53 Database Class: Height
54 Specifies a desired height for the button. If an image or bit‐
56 map is being displayed in the button then the value is in screen
57 units (i.e. any of the forms acceptable to Tk_GetPixels); for
58 text it is in lines of text. If this option is not specified,
59 the button's desired height is computed from the size of the
60 image or bitmap or text being displayed in it.
61 Command-Line Name:-overrelief
63 Database Name: overRelief
64 Database Class: OverRelief
65 Specifies an alternative relief for the button, to be used when
67 the mouse cursor is over the widget. This option can be used to
68 make toolbar buttons, by configuring -relief flat -overrelief
69 raised. If the value of this option is the empty string, then
70 no alternative relief is used when the mouse cursor is over the
71 button. The empty string is the default value.
72 Command-Line Name:-state
74 Database Name: state
75 Database Class: State
76 Specifies one of three states for the button: normal, active,
78 or disabled. In normal state the button is displayed using the
79 -foreground and -background options. The active state is typi‐
80 cally used when the pointer is over the button. In active state
81 the button is displayed using the -activeforeground and -active‐
82 background options. Disabled state means that the button should
83 be insensitive: the default bindings will refuse to activate
84 the widget and will ignore mouse button presses. In this state
85 the -disabledforeground and -background options determine how
86 the button is displayed.
87 Command-Line Name:-width
89 Database Name: width
90 Database Class: Width
91 Specifies a desired width for the button. If an image or bitmap
93 is being displayed in the button then the value is in screen
94 units (i.e. any of the forms acceptable to Tk_GetPixels). For a
95 text button (no image or with -compound none) then the width
96 specifies how much space in characters to allocate for the text
97 label. If the width is negative then this specifies a minimum
98 width. If this option is not specified, the button's desired
99 width is computed from the size of the image or bitmap or text
100 being displayed in it.
101______________________________________________________________________________
102
104 The button command creates a new window (given by the pathName argu‐
105 ment) and makes it into a button widget. Additional options, described
106 above, may be specified on the command line or in the option database
107 to configure aspects of the button such as its colors, font, text, and
108 initial relief. The button command returns its pathName argument. At
109 the time this command is invoked, there must not exist a window named
110 pathName, but pathName's parent must exist.
111 A button is a widget that displays a textual string, bitmap or image.
113 If text is displayed, it must all be in a single font, but it can
114 occupy multiple lines on the screen (if it contains newlines or if
115 wrapping occurs because of the -wraplength option) and one of the char‐
116 acters may optionally be underlined using the -underline option. It
117 can display itself in either of three different ways, according to the
118 -state option; it can be made to appear raised, sunken, or flat; and it
119 can be made to flash. When a user invokes the button (by pressing
120 mouse button 1 with the cursor over the button), then the Tcl command
121 specified in the -command option is invoked.
122
124 The button command creates a new Tcl command whose name is pathName.
125 This command may be used to invoke various operations on the widget.
126 It has the following general form:
127 pathName option ?arg arg ...?
128 Option and the args determine the exact behavior of the command. The
129 following commands are possible for button widgets:
130 pathName cget option
132 Returns the current value of the configuration option given by
133 option. Option may have any of the values accepted by the but‐
134 ton command.
135 pathName configure ?option? ?value option value ...?
137 Query or modify the configuration options of the widget. If no
138 option is specified, returns a list describing all of the avail‐
139 able options for pathName (see Tk_ConfigureInfo for information
140 on the format of this list). If option is specified with no
141 value, then the command returns a list describing the one named
142 option (this list will be identical to the corresponding sublist
143 of the value returned if no option is specified). If one or
144 more option-value pairs are specified, then the command modifies
145 the given widget option(s) to have the given value(s); in this
146 case the command returns an empty string. Option may have any
147 of the values accepted by the button command.
148 pathName flash
150 Flash the button. This is accomplished by redisplaying the but‐
151 ton several times, alternating between the configured active‐
152 background and background colors. At the end of the flash the
153 button is left in the same normal/active state as when the com‐
154 mand was invoked. This command is ignored if the button's state
155 is disabled.
156 pathName invoke
158 Invoke the Tcl command associated with the button, if there is
159 one. The return value is the return value from the Tcl command,
160 or an empty string if there is no command associated with the
161 button. This command is ignored if the button's state is dis‐
162 abled.
163
165 Tk automatically creates class bindings for buttons that give them
166 default behavior:
167 [1] A button activates whenever the mouse passes over it and deacti‐
169 vates whenever the mouse leaves the button. Under Windows, this
170 binding is only active when mouse button 1 has been pressed over
171 the button.
172 [2] A button's relief is changed to sunken whenever mouse button 1
174 is pressed over the button, and the relief is restored to its
175 original value when button 1 is later released.
176 [3] If mouse button 1 is pressed over a button and later released
178 over the button, the button is invoked. However, if the mouse
179 is not over the button when button 1 is released, then no invo‐
180 cation occurs.
181 [4] When a button has the input focus, the space key causes the but‐
183 ton to be invoked.
184 If the button's state is disabled then none of the above actions occur:
186 the button is completely non-responsive.
187 The behavior of buttons can be changed by defining new bindings for
189 individual widgets or by redefining the class bindings.
190
192 On Aqua/Mac OS X, some configuration options are ignored for the pur‐
193 pose of drawing of the widget because they would otherwise conflict
194 with platform guidelines. The configure and cget subcommands can still
195 manipulate the values, but do not cause any variation to the look of
196 the widget. The options affected notably include -background and
197 -relief.
198
200 This is the classic Tk “Hello, World!” demonstration:
201 button .b -text "Hello, World!" -command exit
203 pack .b
204 This example demonstrates how to handle button accelerators:
206 button .b1 -text Hello -underline 0
208 button .b2 -text World -underline 0
209 bind . <Key-h> {.b1 flash; .b1 invoke}
210 bind . <Key-w> {.b2 flash; .b2 invoke}
211 pack .b1 .b2
212
214 ttk::button(n)
215
217 button, widget
218Tk 4.4 button(n)