com.pietschy.command.toggle
Class ToggleCommand

java.lang.Object
  extended by com.pietschy.command.Command
      extended by com.pietschy.command.ActionCommand
          extended by com.pietschy.command.toggle.ToggleCommand
All Implemented Interfaces:
ActionCommandExecutor, Bindable, Identifiable

public abstract class ToggleCommand
extends ActionCommand

An ActionCommand that models selection. Each invocation of the command toggles the selection state. Subclasses must override the handleSelection(boolean) method.

ToggleCommands can also be included in ToggleGroups to support the notion of exclusive selection similar to ButtonGroups.


Field Summary
static java.lang.String PROPERTY_SELECTED
           
 
Fields inherited from class com.pietschy.command.ActionCommand
PARAMETER_ACTION_EVENT, PARAMETER_INVOKER, PARAMETER_INVOKER_WINDOW, PARAMETER_MODIFIERS
 
Fields inherited from class com.pietschy.command.Command
internalLog, PROPERTY_ENABLED, PROPERTY_VISIBLE
 
Constructor Summary
ToggleCommand()
          Creates a new anonymous instance.
ToggleCommand(java.lang.String commandId)
          Creates a new instance with the specified id.
 
Method Summary
 void addNotify(CommandGroup parent)
          Invoked whenever a command is added to a group.
protected  void applySelection(boolean selected)
          Applies the selected state to the toggle and updates all its buttons.
protected  void attemptSelection(boolean selected)
          Attempts to set the selected state of the command.
protected  void configureButtonStates(javax.swing.AbstractButton button)
          Overrides the default Command.configureButtonStates() to include the configuration of the buttons selected state.
 javax.swing.AbstractButton createButton(ButtonFactory factory, java.lang.String context)
          Creates a toggle button for this command using the specified ButtonFactory and Face.
 javax.swing.AbstractButton createCheckBox()
          Creates a checkbox for this command using the default button factory and the button face.
 javax.swing.AbstractButton createCheckBox(ButtonFactory factory)
          Creates a checkbox for this command using the specifed button factory and the button face.
 javax.swing.AbstractButton createCheckBox(ButtonFactory factory, java.lang.String context)
          Creates a checkbox for this command using the specified ButtonFactory and Face.
 javax.swing.AbstractButton createCheckBox(java.lang.String context)
          Creates a checkbox for this command using the default button factory and the specified face.
 javax.swing.JMenuItem createMenuItem(MenuFactory factory, java.lang.String context)
          Creates a new JCheckBoxMenuItem that is bound to this command.
protected  void handleExecute()
          This method is called whenever the Command is executed.
protected abstract  void handleSelection(boolean selected)
          Entry for subclasses to handle the selection process.
 boolean isSelected()
          Checks if this command is currently selected.
 void removeNotify(CommandGroup parent)
          Invoked whenever a command is remvoved from a group.
 void requestDefaultIn(javax.swing.RootPaneContainer container)
          Warning this method throws an UnsupportedOperationException as toggle commands are implmented using JToggleButtons and default buttons must be instances of JButton.
 void setSelected(boolean selected)
          Attempts to set the selected state of the command.
 
Methods inherited from class com.pietschy.command.ActionCommand
addActionCommandListener, addInterceptor, bindToContainer, createButton, createButton, createButton, createButton, createMenuItem, createMenuItem, createMenuItem, createMenuItem, doButtonAttachments, doButtonDetachments, execute, execute, getActionAdapter, getActionAdapter, getActionEvent, getInvoker, getInvokerWindow, getModifiers, getParameter, getParameter, getParameters, installShortCut, installShortCut, postExecute, preExecute, putParameter, putParameters, removeActionCommandListener, removeInterceptor, unbindFromContainer, uninstallShortCut, uninstallShortCut
 
Methods inherited from class com.pietschy.command.Command
addContainerPropertyListener, addFace, addHoverListener, addPropertyChangeListener, addPropertyChangeListener, attach, bind, bind, bind, buttonIterator, configureAppearance, configureAppearances, configureButtonAppearances, configureButtonStates, createButton, createButton, createButton, createComponent, createMenuItem, createMenuItem, createMenuItem, detach, faceExists, findBestFace, fireHoverEnded, fireHoverStarted, fireIndexedPropertyChange, fireIndexedPropertyChange, fireIndexedPropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getAlternativeFaceContexts, getButtonFactory, getButtonIn, getCommandContainer, getContainerProperty, getDefaultFace, getDefaultFace, getFace, getFace, getId, getMenuFactory, getProperty, getProperty, getPropertyNames, getToolbarFactory, isAnonymous, isAttachedTo, isBound, isEnabled, isVisible, loadConfiguration, notifyCommandContainerHierarchyChanged, putProperties, putProperty, rebind, removeContainerPropertyListener, removeHoverListener, removePropertyChangeListener, removePropertyChangeListener, requestFocusIn, setButtonFactory, setEnabled, setMenuFactory, setToolbarFactory, setVisible, toString, unbind, validateId
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface com.pietschy.command.ActionCommandExecutor
addPropertyChangeListener, addPropertyChangeListener, isEnabled, removePropertyChangeListener, removePropertyChangeListener
 
Methods inherited from interface com.pietschy.command.Identifiable
getId
 

Field Detail

PROPERTY_SELECTED

public static final java.lang.String PROPERTY_SELECTED
See Also:
Constant Field Values
Constructor Detail

ToggleCommand

public ToggleCommand()
Creates a new anonymous instance.


ToggleCommand

public ToggleCommand(java.lang.String commandId)
Creates a new instance with the specified id.

Parameters:
commandId - the id of the command.
Method Detail

configureButtonStates

protected void configureButtonStates(javax.swing.AbstractButton button)
Overrides the default Command.configureButtonStates() to include the configuration of the buttons selected state.

Overrides:
configureButtonStates in class Command
Parameters:
button - the button to initialize.

setSelected

public final void setSelected(boolean selected)
Attempts to set the selected state of the command. This method delegats the selection request to handleSelection(boolean) and configures all attachements appropriately based on the return value.

It isn't guarenteed that the final state of the command will be the value specified. The actual final state will be determined by handleSelection(boolean).

This property is bound and a property changed event will be fired if the selection state changes.

Parameters:
selected - true if the command is being selected, false if it is being deselected.

attemptSelection

protected final void attemptSelection(boolean selected)
                               throws ToggleVetoException
Attempts to set the selected state of the command. This method delegats the selection request to handleSelection(boolean) and on return configures all attachements appropriately.

Parameters:
selected - the desired selection state of the command.
Throws:
ToggleVetoException - if a ToggleVetoException is thrown by handleSelection(boolean).

applySelection

protected void applySelection(boolean selected)
Applies the selected state to the toggle and updates all its buttons. This method also fires a property change event if the new selection has changed from the previous state.

This method should only be called by subclasses if the wish to by-pass all of the normal behaviour and explicitly set the state of this toggle (such as when reverting state after an undo request). This method completely ignores any exclusive group membership and will not update the state of any other toggles which may share membership with the command.

Parameters:
selected - the desired selection state of the command.

isSelected

public boolean isSelected()
Checks if this command is currently selected. This property is bound.

Returns:
true if the command is selected, false otherwise.

handleExecute

protected void handleExecute()
This method is called whenever the Command is executed. If this command is a member of and exclusive group, then the selection request is delegated to the group by calling ToggleGroupController.handleSelectionRequest(com.pietschy.command.toggle.ToggleCommand, boolean), otherwise setSelected(boolean) is called with the value of !isSelected().

Specified by:
handleExecute in class ActionCommand

handleSelection

protected abstract void handleSelection(boolean selected)
                                 throws ToggleVetoException
Entry for subclasses to handle the selection process. When a request to change the selection is made, this method will be called.

To deny the selection request, subclassed must throw a ToggleVetoException.

Please note that the current state of isSelected() will not be updated until after this method has been called and so should not be used in this method.

Parameters:
selected - the requested selection state.
Throws:
ToggleVetoException

createMenuItem

public javax.swing.JMenuItem createMenuItem(MenuFactory factory,
                                            java.lang.String context)
Creates a new JCheckBoxMenuItem that is bound to this command.

Overrides:
createMenuItem in class Command
Parameters:
factory - the factory to use when creating the button.
context - the face context to use when creating the button.
Returns:
a new JCheckBoxMenuItem for this command.

createButton

public javax.swing.AbstractButton createButton(ButtonFactory factory,
                                               java.lang.String context)
Creates a toggle button for this command using the specified ButtonFactory and Face.

Overrides:
createButton in class Command
Parameters:
factory - the factory to use when creating the button.
context - the face context to use when creating the button.
Returns:
a new JToggleButton for this command.

createCheckBox

public javax.swing.AbstractButton createCheckBox()
Creates a checkbox for this command using the default button factory and the button face.

Returns:
a new JCheckBox for this command.

createCheckBox

public javax.swing.AbstractButton createCheckBox(java.lang.String context)
Creates a checkbox for this command using the default button factory and the specified face.

Parameters:
context - the face context to use when creating the button.
Returns:
a new JCheckBox for this command.

createCheckBox

public javax.swing.AbstractButton createCheckBox(ButtonFactory factory)
Creates a checkbox for this command using the specifed button factory and the button face.

Parameters:
factory - the factory to use when creating the button.
Returns:
a new JCheckBox for this command.

createCheckBox

public javax.swing.AbstractButton createCheckBox(ButtonFactory factory,
                                                 java.lang.String context)
Creates a checkbox for this command using the specified ButtonFactory and Face.

Parameters:
factory - the factory to use when creating the button.
context - the face context to use when creating the button.
Returns:
a new JCheckBox for this command.

requestDefaultIn

public void requestDefaultIn(javax.swing.RootPaneContainer container)
Warning this method throws an UnsupportedOperationException as toggle commands are implmented using JToggleButtons and default buttons must be instances of JButton.

Overrides:
requestDefaultIn in class ActionCommand
Parameters:
container - the root pane container to check.

addNotify

public void addNotify(CommandGroup parent)
Description copied from class: Command
Invoked whenever a command is added to a group. Commands may belong to more than one group at any given time. This method does nothing by default, subclasses may override to perform special configuration if needed.

Overrides:
addNotify in class Command
Parameters:
parent - the parent group to which the command was added.

removeNotify

public void removeNotify(CommandGroup parent)
Description copied from class: Command
Invoked whenever a command is remvoved from a group. Commands may belong to more than one group at any given time. This method does nothing by default, subclasses may override to perform special configuration if needed.

Overrides:
removeNotify in class Command
Parameters:
parent - the parent from which the command was removed.


Copyright © 2006 - 2007 Andrew Pietsch