81 * <code>Action</code>. 82 * <li>The component installs a <code>PropertyChangeListener</code> on the 83 * <code>Action</code> so that the component can change its properties 84 * to reflect changes in the <code>Action</code>'s properties. 85 * </ul> 86 * <p> 87 * The following table describes the properties used by 88 * <code>Swing</code> components that support <code>Actions</code>. 89 * In the table, <em>button</em> refers to any 90 * <code>AbstractButton</code> subclass, which includes not only 91 * <code>JButton</code> but also classes such as 92 * <code>JMenuItem</code>. Unless otherwise stated, a 93 * <code>null</code> property value in an <code>Action</code> (or a 94 * <code>Action</code> that is <code>null</code>) results in the 95 * button's corresponding property being set to <code>null</code>. 96 * 97 * <table class="striped"> 98 * <caption>Supported Action properties</caption> 99 * <thead> 100 * <tr> 101 * <th>Component Property 102 * <th>Components 103 * <th>Action Key 104 * <th>Notes 105 * </thead> 106 * <tbody> 107 * <tr valign="top" style="text-align:left"> 108 * <td><b><code>enabled</code></b> 109 * <td>All 110 * <td>The <code>isEnabled</code> method 111 * <td> 112 * <tr valign="top" style="text-align:left"> 113 * <td><b><code>toolTipText</code></b> 114 * <td>All 115 * <td><code>SHORT_DESCRIPTION</code> 116 * <td> 117 * <tr valign="top" style="text-align:left"> 118 * <td><b><code>actionCommand</code></b> 119 * <td>All 120 * <td><code>ACTION_COMMAND_KEY</code> 121 * <td> 122 * <tr valign="top" style="text-align:left"> 123 * <td><b><code>mnemonic</code></b> 124 * <td>All buttons 125 * <td><code>MNEMONIC_KEY</code> 126 * <td>A <code>null</code> value or <code>Action</code> results in the 127 * button's <code>mnemonic</code> property being set to 128 * <code>'\0'</code>. 129 * <tr valign="top" style="text-align:left"> 130 * <td><b><code>text</code></b> 131 * <td>All buttons 132 * <td><code>NAME</code> 133 * <td>If you do not want the text of the button to mirror that 134 * of the <code>Action</code>, set the property 135 * <code>hideActionText</code> to <code>true</code>. If 136 * <code>hideActionText</code> is <code>true</code>, setting the 137 * <code>Action</code> changes the text of the button to 138 * <code>null</code> and any changes to <code>NAME</code> 139 * are ignored. <code>hideActionText</code> is useful for 140 * tool bar buttons that typically only show an <code>Icon</code>. 141 * <code>JToolBar.add(Action)</code> sets the property to 142 * <code>true</code> if the <code>Action</code> has a 143 * non-<code>null</code> value for <code>LARGE_ICON_KEY</code> or 144 * <code>SMALL_ICON</code>. 145 * <tr valign="top" style="text-align:left"> 146 * <td><b><code>displayedMnemonicIndex</code></b> 147 * <td>All buttons 148 * <td><code>DISPLAYED_MNEMONIC_INDEX_KEY</code> 149 * <td>If the value of <code>DISPLAYED_MNEMONIC_INDEX_KEY</code> is 150 * beyond the bounds of the text, it is ignored. When 151 * <code>setAction</code> is called, if the value from the 152 * <code>Action</code> is <code>null</code>, the displayed 153 * mnemonic index is not updated. In any subsequent changes to 154 * <code>DISPLAYED_MNEMONIC_INDEX_KEY</code>, <code>null</code> 155 * is treated as -1. 156 * <tr valign="top" style="text-align:left"> 157 * <td><b><code>icon</code></b> 158 * <td>All buttons except of <code>JCheckBox</code>, 159 * <code>JToggleButton</code> and <code>JRadioButton</code>. 160 * <td>either <code>LARGE_ICON_KEY</code> or 161 * <code>SMALL_ICON</code> 162 * <td>The <code>JMenuItem</code> subclasses only use 163 * <code>SMALL_ICON</code>. All other buttons will use 164 * <code>LARGE_ICON_KEY</code>; if the value is <code>null</code> they 165 * use <code>SMALL_ICON</code>. 166 * <tr valign="top" style="text-align:left"> 167 * <td><b><code>accelerator</code></b> 168 * <td>All <code>JMenuItem</code> subclasses, with the exception of 169 * <code>JMenu</code>. 170 * <td><code>ACCELERATOR_KEY</code> 171 * <td> 172 * <tr valign="top" style="text-align:left"> 173 * <td><b><code>selected</code></b> 174 * <td><code>JToggleButton</code>, <code>JCheckBox</code>, 175 * <code>JRadioButton</code>, <code>JCheckBoxMenuItem</code> and 176 * <code>JRadioButtonMenuItem</code> 177 * <td><code>SELECTED_KEY</code> 178 * <td>Components that honor this property only use 179 * the value if it is {@code non-null}. For example, if 180 * you set an {@code Action} that has a {@code null} 181 * value for {@code SELECTED_KEY} on a {@code JToggleButton}, the 182 * {@code JToggleButton} will not update it's selected state in 183 * any way. Similarly, any time the {@code JToggleButton}'s 184 * selected state changes it will only set the value back on 185 * the {@code Action} if the {@code Action} has a {@code non-null} 186 * value for {@code SELECTED_KEY}. 187 * <br> 188 * Components that honor this property keep their selected state 189 * in sync with this property. When the same {@code Action} is used 190 * with multiple components, all the components keep their selected 191 * state in sync with this property. Mutually exclusive 192 * buttons, such as {@code JToggleButton}s in a {@code ButtonGroup}, 193 * force only one of the buttons to be selected. As such, do not 194 * use the same {@code Action} that defines a value for the 195 * {@code SELECTED_KEY} property with multiple mutually 196 * exclusive buttons. 197 * </tbody> 198 * </table> 199 * <p> 200 * <code>JPopupMenu</code>, <code>JToolBar</code> and <code>JMenu</code> 201 * all provide convenience methods for creating a component and setting the 202 * <code>Action</code> on the corresponding component. Refer to each of 203 * these classes for more information. 204 * <p> 205 * <code>Action</code> uses <code>PropertyChangeListener</code> to 206 * inform listeners the <code>Action</code> has changed. The beans 207 * specification indicates that a <code>null</code> property name can 208 * be used to indicate multiple values have changed. By default Swing 209 * components that take an <code>Action</code> do not handle such a 210 * change. To indicate that Swing should treat <code>null</code> 211 * according to the beans specification set the system property 212 * <code>swing.actions.reconfigureOnNull</code> to the <code>String</code> 213 * value <code>true</code>. 214 * 215 * @author Georges Saab 216 * @see AbstractAction | 81 * <code>Action</code>. 82 * <li>The component installs a <code>PropertyChangeListener</code> on the 83 * <code>Action</code> so that the component can change its properties 84 * to reflect changes in the <code>Action</code>'s properties. 85 * </ul> 86 * <p> 87 * The following table describes the properties used by 88 * <code>Swing</code> components that support <code>Actions</code>. 89 * In the table, <em>button</em> refers to any 90 * <code>AbstractButton</code> subclass, which includes not only 91 * <code>JButton</code> but also classes such as 92 * <code>JMenuItem</code>. Unless otherwise stated, a 93 * <code>null</code> property value in an <code>Action</code> (or a 94 * <code>Action</code> that is <code>null</code>) results in the 95 * button's corresponding property being set to <code>null</code>. 96 * 97 * <table class="striped"> 98 * <caption>Supported Action properties</caption> 99 * <thead> 100 * <tr> 101 * <th scope="col">Component Property 102 * <th scope="col">Components 103 * <th scope="col">Action Key 104 * <th scope="col">Notes 105 * </thead> 106 * <tbody> 107 * <tr> 108 * <th scope="row"><b>{@code enabled}</b> 109 * <td>All 110 * <td>The {@code isEnabled} method 111 * <td> 112 * <tr> 113 * <th scope="row"><b>{@code toolTipText}</b> 114 * <td>All 115 * <td>{@code SHORT_DESCRIPTION} 116 * <td> 117 * <tr> 118 * <th scope="row"><b>{@code actionCommand}</b> 119 * <td>All 120 * <td>{@code ACTION_COMMAND_KEY} 121 * <td> 122 * <tr> 123 * <th scope="row"><b>{@code mnemonic}</b> 124 * <td>All buttons 125 * <td>{@code MNEMONIC_KEY} 126 * <td>A {@code null} value or {@code Action} results in the button's 127 * {@code mnemonic} property being set to {@code '\0'}. 128 * <tr> 129 * <th scope="row"><b>{@code text}</b> 130 * <td>All buttons 131 * <td>{@code NAME} 132 * <td>If you do not want the text of the button to mirror that of the 133 * {@code Action}, set the property {@code hideActionText} to {@code true}. 134 * If {@code hideActionText} is {@code true}, setting the {@code Action} 135 * changes the text of the button to {@code null} and any changes to 136 * {@code NAME} are ignored. {@code hideActionText} is useful for tool bar 137 * buttons that typically only show an {@code Icon}. 138 * {@code JToolBar.add(Action)} sets the property to {@code true} if the 139 * {@code Action} has a non-{@code null} value for {@code LARGE_ICON_KEY} or 140 * {@code SMALL_ICON}. 141 * <tr> 142 * <th scope="row"><b>{@code displayedMnemonicIndex}</b> 143 * <td>All buttons 144 * <td>{@code DISPLAYED_MNEMONIC_INDEX_KEY} 145 * <td>If the value of {@code DISPLAYED_MNEMONIC_INDEX_KEY} is beyond the 146 * bounds of the text, it is ignored. When {@code setAction} is called, if 147 * the value from the {@code Action} is {@code null}, the displayed mnemonic 148 * index is not updated. In any subsequent changes to 149 * {@code DISPLAYED_MNEMONIC_INDEX_KEY}, {@code null} is treated as -1. 150 * <tr> 151 * <th scope="row"><b>{@code icon}</b> 152 * <td>All buttons except of {@code JCheckBox}, {@code JToggleButton} and 153 * {@code JRadioButton}. 154 * <td>either {@code LARGE_ICON_KEY} or {@code SMALL_ICON} 155 * <td>The {@code JMenuItem} subclasses only use {@code SMALL_ICON}. All 156 * other buttons will use {@code LARGE_ICON_KEY}; if the value is 157 * {@code null} they use {@code SMALL_ICON}. 158 * <tr> 159 * <th scope="row"><b>{@code accelerator}</b> 160 * <td>All {@code JMenuItem} subclasses, with the exception of {@code JMenu}. 161 * <td>{@code ACCELERATOR_KEY} 162 * <td> 163 * <tr> 164 * <th scope="row"><b>{@code selected}</b> 165 * <td>{@code JToggleButton}, {@code JCheckBox}, {@code JRadioButton}, 166 * {@code JCheckBoxMenuItem} and {@code JRadioButtonMenuItem} 167 * <td>{@code SELECTED_KEY} 168 * <td>Components that honor this property only use the value if it is 169 * {@code non-null}. For example, if you set an {@code Action} that has a 170 * {@code null} value for {@code SELECTED_KEY} on a {@code JToggleButton}, 171 * the {@code JToggleButton} will not update it's selected state in any way. 172 * Similarly, any time the {@code JToggleButton}'s selected state changes it 173 * will only set the value back on the {@code Action} if the {@code Action} 174 * has a {@code non-null} value for {@code SELECTED_KEY}. 175 * <br> 176 * Components that honor this property keep their selected state in sync with 177 * this property. When the same {@code Action} is used with multiple 178 * components, all the components keep their selected state in sync with this 179 * property. Mutually exclusive buttons, such as {@code JToggleButton}s in a 180 * {@code ButtonGroup}, force only one of the buttons to be selected. As 181 * such, do not use the same {@code Action} that defines a value for the 182 * {@code SELECTED_KEY} property with multiple mutually exclusive buttons. 183 * </tbody> 184 * </table> 185 * <p> 186 * <code>JPopupMenu</code>, <code>JToolBar</code> and <code>JMenu</code> 187 * all provide convenience methods for creating a component and setting the 188 * <code>Action</code> on the corresponding component. Refer to each of 189 * these classes for more information. 190 * <p> 191 * <code>Action</code> uses <code>PropertyChangeListener</code> to 192 * inform listeners the <code>Action</code> has changed. The beans 193 * specification indicates that a <code>null</code> property name can 194 * be used to indicate multiple values have changed. By default Swing 195 * components that take an <code>Action</code> do not handle such a 196 * change. To indicate that Swing should treat <code>null</code> 197 * according to the beans specification set the system property 198 * <code>swing.actions.reconfigureOnNull</code> to the <code>String</code> 199 * value <code>true</code>. 200 * 201 * @author Georges Saab 202 * @see AbstractAction |