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      */
isArmed()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      */
isSelected()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      */
isEnabled()103     boolean isEnabled();
104 
105     /**
106      * Indicates if the button is pressed.
107      *
108      * @return <code>true</code> if the button is pressed
109      */
isPressed()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      */
isRollover()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      */
setArmed(boolean b)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      */
setSelected(boolean b)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      */
setEnabled(boolean b)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      */
setPressed(boolean b)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      */
setRollover(boolean b)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      */
setMnemonic(int key)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      */
getMnemonic()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      */
setActionCommand(String s)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      */
getActionCommand()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      */
setGroup(ButtonGroup group)199     public void setGroup(ButtonGroup group);
200 
201     /**
202      * Returns the group that the button belongs to.
203      * Normally used with radio buttons, which are mutually
204      * exclusive within their group.
205      *
206      * @implSpec The default implementation of this method returns {@code null}.
207      * Subclasses should return the group set by setGroup().
208      *
209      * @return the <code>ButtonGroup</code> that the button belongs to
210      * @since 10
211      */
getGroup()212     default ButtonGroup getGroup() {
213         return null;
214     }
215 
216     /**
217      * Adds an <code>ActionListener</code> to the model.
218      *
219      * @param l the listener to add
220      */
addActionListener(ActionListener l)221     void addActionListener(ActionListener l);
222 
223     /**
224      * Removes an <code>ActionListener</code> from the model.
225      *
226      * @param l the listener to remove
227      */
removeActionListener(ActionListener l)228     void removeActionListener(ActionListener l);
229 
230     /**
231      * Adds an <code>ItemListener</code> to the model.
232      *
233      * @param l the listener to add
234      */
addItemListener(ItemListener l)235     void addItemListener(ItemListener l);
236 
237     /**
238      * Removes an <code>ItemListener</code> from the model.
239      *
240      * @param l the listener to remove
241      */
removeItemListener(ItemListener l)242     void removeItemListener(ItemListener l);
243 
244     /**
245      * Adds a <code>ChangeListener</code> to the model.
246      *
247      * @param l the listener to add
248      */
addChangeListener(ChangeListener l)249     void addChangeListener(ChangeListener l);
250 
251     /**
252      * Removes a <code>ChangeListener</code> from the model.
253      *
254      * @param l the listener to remove
255      */
removeChangeListener(ChangeListener l)256     void removeChangeListener(ChangeListener l);
257 
258 }
259