| AbstractButton is an abstract base class for all button components (JButton, JToggleButton, JCheckBox, JRadioButton, and JMenuItem and its subclasses). Since it provides functionality common to all types of buttons, we'll cover it here before getting to the concrete button classes. AbstractButton provides much of the functionality associated with the interaction between the various concrete button classes and their ButtonModel objects. As we mentioned earlier, buttons in Swing can be made up of an image (Icon ), text, or both. The relative positions of the text and icon are specified exactly as they are with the JLabel class. Image buttons may specify as many as seven different images, allowing the button to be displayed differently depending on its current state. The seven icons are described in Table 5-5, with the other properties defined by AbstractButton. 5.3.1 Properties The AbstractButton class defines the properties shown in Table 5-5. Table 5-5. AbstractButton properties | Property | Data type | get | is | set | Default value | | action1.3 | Action | · | | · | null | | actionCommand | String | · | | · | null | | borderPaintedb | boolean | | · | · | true | | contentAreaFilledb | boolean | | · | · | true | | disabledIconb | Icon | · | | · | null | | disabledSelectedIconb | Icon | · | | · | null | | displayedMnemonicIndex1.4 | int | · | | · | -1 | | enabledo | boolean | | · | · | true | | focusPaintedb | boolean | | · | · | true | | horizontalAlignmentb | int | · | | · | CENTER | | horizontalTextPositionb | int | · | | · | TRAILING1.4 | | iconb | Icon | · | | · | null | | iconTextGap1.4 | int | · | | · | 4 | | labeld | String | · | | · | Same as text | | marginb | Insets | · | | · | null | | mnemonicb | int | · | | · | KeyEvent.VK_UNDEFINED | | modelb | ButtonModel | · | | · | null | | multiClickThreshhold1.4 | long | · | | · | 0 | | pressedIconb | Icon | · | | · | null | | rolloverEnabledb | boolean | | · | · | false | | rolloverIcon | Icon | · | | · | null | | rolloverSelectedIconb | Icon | · | | · | null | | selected | boolean | | · | · | false | | selectedIconb | Icon | · | | · | null | | selectedObjects | Object[] | · | | | null | | textb | String | · | | · | "" | | UIb | ButtonUI | · | | · | From L&F | | verticalAlignmentb | int | · | | · | CENTER | | verticalTextPositionb | int | · | | · | CENTER | | 1.3since 1.3, 1.4since 1.4, bbound, ddeprecated, ooverridden See also properties from the JComponent class (Table 3-6). | There are seven different icons available for a button. Each is shown when the button is in a certain state:[2] [2] Prior to SDK 1.4, disabledSelectedIcon and rolloverSelectedIcon were ignored by the Swing L&Fs.
- icon
-
The default icon for the button, or null for no icon. - disabledIcon
-
The icon shown when the button is disabled. If none is specified, a grayscale version of the default icon is generated automatically. - selectedIcon
-
The icon shown when the button is selected. - disabledSelectedIcon
-
The icon shown when the button is selected and also disabled. If none is specified, a grayscale version of the selected icon is generated. If no selected icon is set, it uses the value returned by getDisabledIcon( ). - pressedIcon
-
The icon shown while the button is being pressed. - rolloverIcon
-
The icon shown (if rolloverEnabled is true) when the cursor is moved over the unselected button. - rolloverSelectedIcon
-
The icon shown (if rolloverEnabled is true) when the cursor is moved over the selected button. The text property contains the text, if any, displayed on the button (note that this property replaces the deprecated label property). The model property is the ButtonModel containing the state information for the button. Setting the action property does a lot of work in one step. The newly attached Action receives any ActionEvents fired by the button, and the previous Action (if any) is deregistered. The button almost completely resets its properties based on the Action (see the configurePropertiesFromAction( ) method and Table 5-8). Furthermore, the button registers a PropertyChangeListener on the Action so it can automatically update itself when changes are made to the Action in the future. The horizontalAlignment and verticalAlignment properties specify where the button's content (text, icon, or both) should be drawn within the button's borders. These properties are significant only when the button is larger than the default size. horizontalTextPosition and verticalTextPosition specify the location of the text relative to the icon, and iconTextGap specifies the amount of space (in pixels) separating the text and the icon. These are meaningful only if both an icon and text have been specified.[3] [3] See Section 4.1 in Chapter 4 for an example of the alignment and text position properties.
The multiClickThreshhold property is the length of time (in milliseconds) during which multiple mouse clicks are coalesced into a single ActionEvent. A value of 0 (the default) indicates that each click generates an ActionEvent no matter how quickly it follows its predecessor. The margin property specifies the distance between the button's borders and its contents (text, icon, or both). However, it's up to the border implementation to take advantage of the value of this property. The Swing L&Fs define borders that take the value of margin into account, but if you replace a button's border with one of your own, be aware that the margin space is not used unless you access it explicitly in your border code. borderPainted indicates whether a border (recall from Chapter 3 that border is inherited from JComponent) should be painted around the button. This property is meaningful only if the button actually has a border (it does by default). The contentAreaFilled property indicates whether the rectangular content area of the button should be filled. This should be set to false if you want to define an image-only button. Note that this is preferable to calling setOpaque(false) because the value of the opaque property for buttons is set by the L&F. focusPainted indicates whether something special (such as a dashed line inside the button's border) should be painted to show that the button has focus. Finally, the rolloverEnabled property indicates whether moving the cursor over the button should cause the rolloverIcon or rolloverSelectedIcon to be displayed. Calling setRolloverIcon( ) causes this property to be set to true. The actionCommand , mnemonic, and selected properties are taken directly from the AbstractButton's ButtonModel object. The displayedMnemonicIndex property behaves the same way it does in JLabel (see Section 4.1Section 4.1). AbstractButton adds its own implementation of setEnabled( ), inherited from java.awt.Component, which updates the enabled property of its ButtonModel. UI holds the ButtonUI used to render the button. 5.3.2 Events AbstractButton fires the events required by the ButtonModel interface (see Table 5-6). An ActionEvent is fired when the button is pressed, an ItemEvent is fired when the button's state is changed, and a ChangeEvent is fired when a change has occurred to the button's properties. Table 5-6. AbstractButton events | Event | Description | | ActionEvent | The button is pressed. | | ChangeEvent | A change has occurred in one or more properties of the button's model. | | ItemEvent | The button is toggled on or off. | All of these events are generated by the button's model. AbstractButton registers with the model as a listener for each type of event and refires any events fired by the model to any registered listeners. The following standard listener management methods are implemented in this class: - public void addActionListener(ActionListener l)
- public void removeActionListener(ActionListener l)
- public ActionListener[] getActionListeners( ) (Added in SDK 1.4)
- public void addItemListener(ItemListener l)
- public void removeItemListener(ItemListener l)
- public ItemListener[] getItemListeners( ) (Added in SDK 1.4)
- public void addChangeListener(ChangeListener l)
- public void removeChangeListener(ChangeListener l)
- public ChangeListener[] getChangeListeners( ) (Added in SDK 1.4)
5.3.3 Constants The constants shown in Table 5-7 are defined by AbstractButton for use in PropertyChangeEvents. Some PropertyChangeEvents generated by AbstractButton use strings other than these. There's no constant defined to indicate that the action property has changed, so the setAction( ) method fires a PropertyChangeEvent with the string "action". Accessibility-related change events use strings defined in the AccessibleContext class. Table 5-7. AbstractButton constants | Constant | Type | Description | | BORDER_PAINTED_CHANGED_PROPERTY | String | borderPainted property has changed | | CONTENT_AREA_FILLED_CHANGED_PROPERTY | String | contentAreaFilled property has changed | | DISABLED_ICON_CHANGED_PROPERTY | String | disabledIcon property has changed | | DISABLED_SELECTED_ICON_CHANGED_PROPERTY | String | disabledSelectedIcon property has changed | | FOCUS_PAINTED_CHANGED_PROPERTY | String | focusPainted property has changed | | HORIZONTAL_ALIGNMENT_CHANGED_PROPERTY | String | horizontalAlignment property has changed | | HORIZONTAL_TEXT_POSITION_CHANGED_PROPERTY | String | horizontalTextPosition property has changed | | ICON_CHANGED_PROPERTY | String | icon property has changed | | MARGIN_CHANGED_PROPERTY | String | margin property has changed | | MNEMONIC_CHANGED_PROPERTY | String | mnemonic property has changed | | MODEL_CHANGED_PROPERTY | String | model property has changed | | PRESSED_ICON_CHANGED_PROPERTY | String | pressedIcon property has changed | | ROLLOVER_ENABLED_CHANGED_PROPERTY | String | rolloverEnabled property has changed | | ROLLOVER_ICON_CHANGED_PROPERTY | String | rolloverIcon property has changed | | ROLLOVER_SELECTED_ICON_CHANGED_PROPERTY | String | rolloverSelectedIcon property has changed | | SELECTED_ICON_CHANGED_PROPERTY | String | selectedIcon property has changed | | TEXT_CHANGED_PROPERTY | String | text property has changed | | VERTICAL_ALIGNMENT_CHANGED_PROPERTY | String | verticalAlignment property has changed | | VERTICAL_TEXT_POSITION_CHANGED_PROPERTY | String | verticalTextPosition property has changed | 5.3.4 Public Methods - public void doClick(int pressTime)
-
Programmatically simulate a user pressing the button for a specified number of milliseconds. Calling this method has the same effect as pressing the button the button even appears to be pressed. - public void doClick( )
-
This version of doClick( ) calls the first version with a value of 68 milliseconds. - public void setMnemonic(char mnemonic)
-
This method provides a convenient way to set the mnemonic property by passing in a char (as opposed to the property's actual type, int). The character is converted to the equivalent integer "virtual keycode" (defined in the java.awt.KeyEvent class) and passed to the other setMnemonic( ) method.
5.3.5 Action Configuration Methods These protected methods do most of the work to support Actions. Subclasses that wish to alter the way they behave with Actions should override these methods. (These methods were added in SDK 1.3.) - protected PropertyChangeListener createActionPropertyChangeListener(Action a)
-
Return a PropertyChangeListener that will be responsible for reconfiguring the button in response to changes in the button's action. - protected void configurePropertiesFromAction(Action a)
-
The values of several properties are pulled from the given Action and applied to this button. The specific properties are listed in Table 5-8, though the concrete subclasses of AbstractButton can and do add and remove from this list. Table 5-8. Properties set by configurePropertiesFromAction( ) | Button property | Value taken from Action | Value if Action is null | | text | a.getValue(NAME) | null | | icon | a.getValue(SMALL_ICON) | null | | mnemonic | a.getValue(MNEMONIC_KEY) | KeyEvent.VK_UNDEFINED | | toolTipText | a.getValue(SHORT_DESCRIPTION) | null | | actionCommand | a.getValue(ACTION_COMMAND_KEY) | null | | enabled | a.isEnabled( ) | true | | 