| 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 | |