1 /* 2 * Copyright (c) 1997, 2006, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 package javax.swing; 26 27 28 import java.awt.event.*; 29 import java.awt.*; 30 import javax.swing.event.*; 31 32 /** 33 * State model for buttons. 34 * <p> 35 * This model is used for regular buttons, as well as check boxes 36 * and radio buttons, which are special kinds of buttons. In practice, 37 * a button's UI takes the responsibility of calling methods on its 38 * model to manage the state, as detailed below: 39 * <p> 40 * In simple terms, pressing and releasing the mouse over a regular 41 * button triggers the button and causes and <code>ActionEvent</code> 42 * to be fired. The same behavior can be produced via a keyboard key 43 * defined by the look and feel of the button (typically the SPACE BAR). 44 * Pressing and releasing this key while the button has 45 * focus will give the same results. For check boxes and radio buttons, the 46 * mouse or keyboard equivalent sequence just described causes the button 47 * to become selected. 48 * <p> 49 * In details, the state model for buttons works as follows 50 * when used with the mouse: 51 * <br> 52 * Pressing the mouse on top of a button makes the model both 53 * armed and pressed. As long as the mouse remains down, 54 * the model remains pressed, even if the mouse moves 55 * outside the button. On the contrary, the model is only 56 * armed while the mouse remains pressed within the bounds of 57 * the button (it can move in or out of the button, but the model 58 * is only armed during the portion of time spent within the button). 59 * A button is triggered, and an <code>ActionEvent</code> is fired, 60 * when the mouse is released while the model is armed 61 * - meaning when it is released over top of the button after the mouse 62 * has previously been pressed on that button (and not already released). 63 * Upon mouse release, the model becomes unarmed and unpressed. 64 * <p> 65 * In details, the state model for buttons works as follows 66 * when used with the keyboard: 67 * <br> 68 * Pressing the look and feel defined keyboard key while the button 69 * has focus makes the model both armed and pressed. As long as this key 70 * remains down, the model remains in this state. Releasing the key sets 71 * the model to unarmed and unpressed, triggers the button, and causes an 72 * <code>ActionEvent</code> to be fired. 73 * 74 * @author Jeff Dinkins 75 * @since 1.2 76 */ 77 public interface ButtonModel extends ItemSelectable { 78 79 /** 80 * Indicates partial commitment towards triggering the 81 * button. 82 * 83 * @return <code>true</code> if the button is armed, 84 * and ready to be triggered 85 * @see #setArmed 86 */ 87 boolean isArmed(); 88 89 /** 90 * Indicates if the button has been selected. Only needed for 91 * certain types of buttons - such as radio buttons and check boxes. 92 * 93 * @return <code>true</code> if the button is selected 94 */ 95 boolean isSelected(); 96 97 /** 98 * Indicates if the button can be selected or triggered by 99 * an input device, such as a mouse pointer. 100 * 101 * @return <code>true</code> if the button is enabled 102 */ 103 boolean isEnabled(); 104 105 /** 106 * Indicates if the button is pressed. 107 * 108 * @return <code>true</code> if the button is pressed 109 */ 110 boolean isPressed(); 111 112 /** 113 * Indicates that the mouse is over the button. 114 * 115 * @return <code>true</code> if the mouse is over the button 116 */ 117 boolean isRollover(); 118 119 /** 120 * Marks the button as armed or unarmed. 121 * 122 * @param b whether or not the button should be armed 123 */ 124 public void setArmed(boolean b); 125 126 /** 127 * Selects or deselects the button. 128 * 129 * @param b <code>true</code> selects the button, 130 * <code>false</code> deselects the button 131 */ 132 public void setSelected(boolean b); 133 134 /** 135 * Enables or disables the button. 136 * 137 * @param b whether or not the button should be enabled 138 * @see #isEnabled 139 */ 140 public void setEnabled(boolean b); 141 142 /** 143 * Sets the button to pressed or unpressed. 144 * 145 * @param b whether or not the button should be pressed 146 * @see #isPressed 147 */ 148 public void setPressed(boolean b); 149 150 /** 151 * Sets or clears the button's rollover state 152 * 153 * @param b whether or not the button is in the rollover state 154 * @see #isRollover 155 */ 156 public void setRollover(boolean b); 157 158 /** 159 * Sets the keyboard mnemonic (shortcut key or 160 * accelerator key) for the button. 161 * 162 * @param key an int specifying the accelerator key 163 */ 164 public void setMnemonic(int key); 165 166 /** 167 * Gets the keyboard mnemonic for the button. 168 * 169 * @return an int specifying the accelerator key 170 * @see #setMnemonic 171 */ 172 public int getMnemonic(); 173 174 /** 175 * Sets the action command string that gets sent as part of the 176 * <code>ActionEvent</code> when the button is triggered. 177 * 178 * @param s the <code>String</code> that identifies the generated event 179 * @see #getActionCommand 180 * @see java.awt.event.ActionEvent#getActionCommand 181 */ 182 public void setActionCommand(String s); 183 184 /** 185 * Returns the action command string for the button. 186 * 187 * @return the <code>String</code> that identifies the generated event 188 * @see #setActionCommand 189 */ 190 public String getActionCommand(); 191 192 /** 193 * Identifies the group the button belongs to -- 194 * needed for radio buttons, which are mutually 195 * exclusive within their group. 196 * 197 * @param group the <code>ButtonGroup</code> the button belongs to 198 */ 199 public void setGroup(ButtonGroup group); 200 201 /** 202 * Adds an <code>ActionListener</code> to the model. 203 * 204 * @param l the listener to add 205 */ 206 void addActionListener(ActionListener l); 207 208 /** 209 * Removes an <code>ActionListener</code> from the model. 210 * 211 * @param l the listener to remove 212 */ 213 void removeActionListener(ActionListener l); 214 215 /** 216 * Adds an <code>ItemListener</code> to the model. 217 * 218 * @param l the listener to add 219 */ 220 void addItemListener(ItemListener l); 221 222 /** 223 * Removes an <code>ItemListener</code> from the model. 224 * 225 * @param l the listener to remove 226 */ 227 void removeItemListener(ItemListener l); 228 229 /** 230 * Adds a <code>ChangeListener</code> to the model. 231 * 232 * @param l the listener to add 233 */ 234 void addChangeListener(ChangeListener l); 235 236 /** 237 * Removes a <code>ChangeListener</code> from the model. 238 * 239 * @param l the listener to remove 240 */ 241 void removeChangeListener(ChangeListener l); 242 243 }