Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | # Copyright (c) 1990-1994 The Regents of the University of California. |
2 | # Copyright (c) 1994-1996 Sun Microsystems, Inc. | |
3 | # See the file "license.terms" for information on usage and redistribution | |
4 | # of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
5 | # | |
6 | # | |
7 | ||
8 | =head1 NAME | |
9 | ||
10 | Tk::Button - Create and manipulate Button widgets | |
11 | ||
12 | =for category Tk Widget Classes | |
13 | ||
14 | =head1 SYNOPSIS | |
15 | ||
16 | I<$button> = I<$parent>-E<gt>B<Button>(?I<options>?); | |
17 | ||
18 | =head1 STANDARD OPTIONS | |
19 | ||
20 | B<-activebackground> B<-cursor> B<-highlightthickness> B<-takefocus> | |
21 | B<-activeforeground> B<-disabledforeground> B<-image> B<-text> | |
22 | B<-anchor> B<-font> B<-justify> B<-textvariable> | |
23 | B<-background> B<-foreground> B<-padx> B<-underline> | |
24 | B<-bitmap> B<-highlightbackground> B<-pady> B<-wraplength> | |
25 | B<-borderwidth> B<-highlightcolor> B<-relief> | |
26 | ||
27 | See L<Tk::options> for details of the standard options. | |
28 | ||
29 | =head1 WIDGET-SPECIFIC OPTIONS | |
30 | ||
31 | =over 4 | |
32 | ||
33 | =item Name: B<command> | |
34 | ||
35 | =item Class: B<Command> | |
36 | ||
37 | =item Switch: B<-command> | |
38 | ||
39 | Specifies a L<perl/Tk callback|Tk::callbacks> to associate with the button. This command | |
40 | is typically invoked when mouse button 1 is released over the button | |
41 | window. | |
42 | ||
43 | =item Name: B<default> | |
44 | ||
45 | =item Class: B<Default> | |
46 | ||
47 | =item Switch: B<-default> | |
48 | ||
49 | Specifies one of three states for the default ring: B<normal>, | |
50 | B<active>, or B<disabled>. In active state, the button is drawn | |
51 | with the platform specific appearance for a default button. In normal | |
52 | state, the button is drawn with the platform specific appearance for a | |
53 | non-default button, leaving enough space to draw the default button | |
54 | appearance. The normal and active states will result in buttons of | |
55 | the same size. In disabled state, the button is drawn with the | |
56 | non-default button appearance without leaving space for the default | |
57 | appearance. The disabled state may result in a smaller button than | |
58 | the active state. | |
59 | ring. | |
60 | ||
61 | =item Name: B<height> | |
62 | ||
63 | =item Class: B<Height> | |
64 | ||
65 | =item Switch: B<-height> | |
66 | ||
67 | Specifies a desired height for the button. | |
68 | If an image or bitmap is being displayed in the button then the value is in | |
69 | screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>); | |
70 | for text it is in lines of text. | |
71 | If this option isn't specified, the button's desired height is computed | |
72 | from the size of the image or bitmap or text being displayed in it. | |
73 | ||
74 | =item Name: B<state> | |
75 | ||
76 | =item Class: B<State> | |
77 | ||
78 | =item Switch: B<-state> | |
79 | ||
80 | Specifies one of three states for the button: B<normal>, B<active>, | |
81 | or B<disabled>. In normal state the button is displayed using the | |
82 | B<foreground> and B<background> options. The active state is | |
83 | typically used when the pointer is over the button. In active state | |
84 | the button is displayed using the B<activeForeground> and | |
85 | B<activeBackground> options. Disabled state means that the button | |
86 | should be insensitive: the default bindings will refuse to activate | |
87 | the widget and will ignore mouse button presses. | |
88 | In this state the B<disabledForeground> and | |
89 | B<background> options determine how the button is displayed. | |
90 | ||
91 | =item Name: B<width> | |
92 | ||
93 | =item Class: B<Width> | |
94 | ||
95 | =item Switch: B<-width> | |
96 | ||
97 | Specifies a desired width for the button. | |
98 | If an image or bitmap is being displayed in the button then the value is in | |
99 | screen units (i.e. any of the forms acceptable to B<Tk_GetPixels>); | |
100 | for text it is in characters. | |
101 | If this option isn't specified, the button's desired width is computed | |
102 | from the size of the image or bitmap or text being displayed in it. | |
103 | ||
104 | =back | |
105 | ||
106 | =head1 DESCRIPTION | |
107 | ||
108 | The B<Button> method creates a new window (given by the | |
109 | $widget argument) and makes it into a button widget. | |
110 | Additional | |
111 | options, described above, may be specified on the command line | |
112 | or in the option database | |
113 | to configure aspects of the button such as its colors, font, | |
114 | text, and initial relief. The B<button> command returns its | |
115 | $widget argument. At the time this command is invoked, | |
116 | there must not exist a window named $widget, but | |
117 | $widget's parent must exist. | |
118 | ||
119 | A button is a widget that displays a textual string, bitmap or image. | |
120 | If text is displayed, it must all be in a single font, but it | |
121 | can occupy multiple lines on the screen (if it contains newlines | |
122 | or if wrapping occurs because of the B<-wraplength> option) and | |
123 | one of the characters may optionally be underlined using the | |
124 | B<-underline> option. | |
125 | It can display itself in either of three different ways, according | |
126 | to | |
127 | the B<-state> option; | |
128 | it can be made to appear raised, sunken, or flat; | |
129 | and it can be made to flash. When a user invokes the | |
130 | button (by pressing mouse button 1 with the cursor over the | |
131 | button), then the L<perl/Tk callback|Tk::callbacks> specified in the B<-command> | |
132 | option is invoked. | |
133 | ||
134 | =head1 WIDGET METHODS | |
135 | ||
136 | The B<Button> method creates a widget object. | |
137 | This object supports the B<configure> and B<cget> methods | |
138 | described in L<Tk::options> which can be used to enquire and | |
139 | modify the options described above. | |
140 | The widget also inherits all the methods provided by the generic | |
141 | L<Tk::Widget|Tk::Widget> class. | |
142 | ||
143 | The following additional methods are available for button widgets: | |
144 | ||
145 | =over 4 | |
146 | ||
147 | =item I<$button>-E<gt>B<flash> | |
148 | ||
149 | Flash the button. This is accomplished by redisplaying the button | |
150 | several times, alternating between active and normal colors. At | |
151 | the end of the flash the button is left in the same normal/active | |
152 | state as when the command was invoked. | |
153 | This command is ignored if the button's state is B<disabled>. | |
154 | ||
155 | =item I<$button>-E<gt>B<invoke> | |
156 | ||
157 | Invoke the L<callback|Tk::callbacks> associated with the buttons | |
158 | B<-command> option, if there is one. | |
159 | The return value is the return value from the callback, or the | |
160 | undefined value if there is no callback associated with the button. | |
161 | This command is ignored if the button's state is B<disabled>. | |
162 | ||
163 | =back | |
164 | ||
165 | =head1 DEFAULT BINDINGS | |
166 | ||
167 | Tk automatically creates class bindings for buttons that give them | |
168 | default behavior: | |
169 | ||
170 | =over 4 | |
171 | ||
172 | =item [1] | |
173 | ||
174 | A button activates whenever the mouse passes over it and deactivates | |
175 | whenever the mouse leaves the button. | |
176 | Under Windows, this binding is only active when mouse button 1 has | |
177 | been pressed over the button. | |
178 | ||
179 | =item [2] | |
180 | ||
181 | A button's relief is changed to sunken whenever mouse button 1 is | |
182 | pressed over the button, and the relief is restored to its original | |
183 | value when button 1 is later released. | |
184 | ||
185 | =item [3] | |
186 | ||
187 | If mouse button 1 is pressed over a button and later released over | |
188 | the button, the button is invoked. However, if the mouse is not | |
189 | over the button when button 1 is released, then no invocation occurs. | |
190 | ||
191 | =item [4] | |
192 | ||
193 | When a button has the input focus, the space key causes the button | |
194 | to be invoked. | |
195 | ||
196 | If the button's state is B<disabled> then none of the above | |
197 | actions occur: the button is completely non-responsive. | |
198 | ||
199 | The behavior of buttons can be changed by defining new bindings for | |
200 | individual widgets or by redefining the class bindings. | |
201 | ||
202 | =back | |
203 | ||
204 | =head1 KEYWORDS | |
205 | ||
206 | button, widget | |
207 | ||
208 | =cut | |
209 |