org.pietschy.command
Class Command

java.lang.Object
  extended by org.pietschy.command.Command
Direct Known Subclasses:
ActionCommand, CommandGroup

public abstract class Command
extends java.lang.Object

This is the base class for all Commands. It provides all code for creating initialising and managing the attachements (buttons/menus) of the command. The two main subclasses are ActionCommand and CommandGroup.

See Also:
ActionCommand, CommandGroup, Face

Field Summary
protected  Logger internalLog
           
protected  javax.swing.event.EventListenerList listenerList
           
protected  javax.swing.event.SwingPropertyChangeSupport pcs
           
 
Constructor Summary
protected Command(CommandManager commandManager)
          Creates a new anonymous command.
protected Command(CommandManager commandManager, java.lang.String id)
          Constructs a new Command object with the specified Id.
 
Method Summary
 void addFace(Face face)
          Deprecated. use getFace(String, boolean) or getDefaultFace(boolean) instead.
 void addHoverListener(HoverListener l)
          Adds a HoverListener to the command manager.
 Face addNewFace(java.lang.String faceName)
          Deprecated. @deprecated use getFace(String, boolean) or getDefaultFace(boolean) instead.
 void addNotify(CommandGroup parent)
          Invoked whenever a command is added to a group.
 void addPropertyChangeListener(java.beans.PropertyChangeListener l)
          Adds a property change listener to this command.
 void addPropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener l)
          Adds a property change listener to this command.
 void attach(javax.swing.AbstractButton button, java.lang.String faceName)
          Attaches this command to the specified button.
protected  java.util.Iterator buttonIterator()
          Creates and returns an iterator over the buttons.
protected  void configureButtonAppearance(javax.swing.AbstractButton button)
          Configures the appearance of the specified button.
protected  void configureButtonAppearances()
          Reconfigures the appearances of all buttons bound to this command.
protected  void configureButtonAppearances(Face face)
          Reconfigures all the buttons attached to this command that have the specified face.
protected  void configureButtonStates(javax.swing.AbstractButton button)
          This method is called to configureMenu newly created buttons.
 javax.swing.AbstractButton createButton()
          Creates a new button that is attached to the command.
 javax.swing.AbstractButton createButton(ButtonFactory factory)
          Create a new button for this command using the specified ButtonFactory.
 javax.swing.AbstractButton createButton(ButtonFactory factory, java.lang.String faceId)
          Create a new button for this command using the specified ButtonFactory and Face .
 javax.swing.AbstractButton createButton(java.lang.String faceId)
          Creates a new button that is attached to the command using the specified face.
 javax.swing.JMenuItem createMenuItem()
          Creates a new menu item for this command.
 javax.swing.JMenuItem createMenuItem(MenuFactory factory)
          Creates a new menu item for this command using Face.MENU and the specified MenuFactory.
 javax.swing.JMenuItem createMenuItem(MenuFactory factory, java.lang.String faceId)
          Creates a new menu item for this command using the specified Face and the specified MenuFactory.
 javax.swing.JMenuItem createMenuItem(java.lang.String faceId)
          Creates a new menu item for this command using the specifed Face name and the currently configured MenuFactory.
 void detach(javax.swing.AbstractButton button)
          Detaches this command from the specified button.
 Command export()
          Registers this command with its CommandManager.
 boolean faceExists(java.lang.String faceName)
           
protected  void fireHoverEnded(Face face, java.awt.Component source)
           
protected  void fireHoverStarted(Face face, java.awt.Component source)
           
 javax.swing.KeyStroke getAccelerator()
          Deprecated. use getDefaultFace() instead.
 java.lang.String[] getAlternativeFaceNames(java.lang.String face)
          Gets a list of face names that can be used in place of the specified name if it hasn't been registered with the command.
 ButtonFactory getButtonFactory()
          Gets the button factory to use for this command.
 javax.swing.AbstractButton getButtonIn(java.awt.Container container)
          This method will find the first button from this command in the specified container.
 CommandManager getCommandManager()
          Gets the CommandManager this command belongs to.
 Face getDefaultFace()
          Gets this commands default face.
 Face getDefaultFace(boolean createIfMissing)
          Gets this commands default face.
 java.lang.String getDescription()
          Deprecated. use getDefaultFace() instead.
 Face getFace(java.lang.String faceName)
          Gets the best matching face for the specified name.
 Face getFace(java.lang.String faceName, boolean createIfMissing)
          Gets the face with the specified name.
 javax.swing.Icon getIcon()
          Deprecated. use getDefaultFace() instead.
 java.lang.String getId()
          Gets this commands identifier.
 java.lang.String getLongDescription()
          Deprecated. use getDefaultFace() instead.
 MenuFactory getMenuFactory()
          Gets the MenuFactory to use for this command when creating menu items.
 java.lang.Integer getMnemonic()
          Deprecated. use getDefaultFace() instead.
 java.lang.Integer getMnemonicIndex()
          Deprecated. use getDefaultFace() instead.
 java.lang.String getProperty(java.lang.String name)
           
 java.lang.String getProperty(java.lang.String name, java.lang.String defaultValue)
           
 java.lang.String[] getPropertyNames()
           
 javax.swing.Icon getSelectedIcon()
          Deprecated. use getDefaultFace() instead.
 java.lang.String getText()
          Deprecated. use getDefaultFace() instead.
 java.lang.Integer getTextPosition()
          Deprecated. use getDefaultFace() instead.
 ToolbarFactory getToolbarFactory()
          Gets the toolbar factory to use for this command.
protected  void initCommandManager(CommandManager commandManager)
           
protected  void installFace(Face face)
          Adds a the specified face to the command.
 boolean isAnonymous()
          Checks if this is an anonymous command.
 boolean isAttachedTo(javax.swing.JComponent b)
          Tests if this command is attached to the specified button.
 boolean isEnabled()
          Checks the enabled state of this action and it's attached buttons.
 boolean isVisible()
          Checks if the buttons of this command are visible.
 void putProperty(java.lang.String name, java.lang.String value)
           
 void removeHoverListener(HoverListener l)
          Removes the HoverListener from the command manager.
 void removeNotify(CommandGroup parent)
          Invoked whenever a command is remvoved from a group.
 void removePropertyChangeListener(java.beans.PropertyChangeListener l)
          Removes the listener from this command
 void removePropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener l)
          Removes the listener from this command
 void requestFocusIn(java.awt.Container container)
          This method will find the first button from this command in the specified container and call JComponent.requestFocus() followed by Component.repaint().
 void setAccelerator(javax.swing.KeyStroke accelerator)
          Deprecated. use getDefaultFace() instead.
 void setButtonFactory(ButtonFactory factory)
          Sets the ButtonFactory for this command to use for default when creating buttons.
 void setDescription(java.lang.String shortDescription)
          Deprecated. use getDefaultFace() instead.
 void setEnabled(boolean enabled)
          Updates the enabled state of this command and any attached buttons.
 void setIcon(javax.swing.Icon icon)
          Deprecated. use getDefaultFace() instead.
 void setLongDescription(java.lang.String longDescription)
          Deprecated. use getDefaultFace() instead.
 void setMenuFactory(MenuFactory factory)
          Sets the MenuFactory to use for menus created by this command.
 void setMnemonic(java.lang.Integer mnemonic)
          Deprecated. use getDefaultFace() instead.
 void setMnemonicIndex(java.lang.Integer mnemonicIndex)
          Deprecated. use getDefaultFace() instead.
 void setSelectedIcon(javax.swing.Icon newSelectedIcon)
          Deprecated. use getDefaultFace() instead.
 void setText(java.lang.String text)
          Deprecated. use getDefaultFace() instead.
 void setTextPosition(java.lang.Integer textPosition)
          Deprecated. use getDefaultFace() instead.
 void setToolbarFactory(ToolbarFactory factory)
          Sets the ToolbarFactory for this command to use for default when creating buttons on toolbars.
 void setVisible(boolean value)
          Sets the command and all it's buttons to be visible or not.
 java.lang.String toString()
          Returns a string representation of the object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

listenerList

protected javax.swing.event.EventListenerList listenerList

pcs

protected javax.swing.event.SwingPropertyChangeSupport pcs

internalLog

protected Logger internalLog
Constructor Detail

Command

protected Command(CommandManager commandManager)
Creates a new anonymous command. Anonymous commands can't must be fully programatically generated and can't be exported to command containers.


Command

protected Command(CommandManager commandManager,
                  java.lang.String id)
Constructs a new Command object with the specified Id.

Parameters:
commandManager -
id - the identifier of this command.
Method Detail

initCommandManager

protected void initCommandManager(CommandManager commandManager)

getId

public java.lang.String getId()
Gets this commands identifier.

Returns:
the identifier of this command.

isAnonymous

public boolean isAnonymous()
Checks if this is an anonymous command. Anonymous commands have no identifier, and can't be exported or configured by the CommandManager. They are useful when you need to programatically create a command.

All commands created without an identifier are anonymous.

Returns:
true if this command is anonymous, false otherwise.

export

public Command export()
Registers this command with its CommandManager. Once exported the command will be available for use in groups.

Throws:
java.lang.IllegalStateException - if this command is anonymous.

getCommandManager

public CommandManager getCommandManager()
Gets the CommandManager this command belongs to.

Returns:
the commands CommandManager.

putProperty

public void putProperty(java.lang.String name,
                        java.lang.String value)

getProperty

public java.lang.String getProperty(java.lang.String name)

getProperty

public java.lang.String getProperty(java.lang.String name,
                                    java.lang.String defaultValue)

getPropertyNames

public java.lang.String[] getPropertyNames()

addNotify

public void addNotify(CommandGroup parent)
Invoked whenever a command is added to a group. Please note that 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 as required.

Parameters:
parent - the parent to which the command was added.

removeNotify

public void removeNotify(CommandGroup parent)
Invoked whenever a command is remvoved from a group. Please note that 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 as required.

Parameters:
parent - the parent from which the command was removed.

attach

public void attach(javax.swing.AbstractButton button,
                   java.lang.String faceName)
Attaches this command to the specified button. If the specified face doesn't exist, then the default face is used.

Parameters:
button - the button to which this command should be attached.

detach

public void detach(javax.swing.AbstractButton button)
Detaches this command from the specified button.

Parameters:
button - the button from which this command is to be detached.

isAttachedTo

public boolean isAttachedTo(javax.swing.JComponent b)
Tests if this command is attached to the specified button.

Parameters:
b - the button to check
Returns:
true if this command is attached to the button, false otherwise.

configureButtonStates

protected void configureButtonStates(javax.swing.AbstractButton button)
This method is called to configureMenu newly created buttons. Subclasses may override this method to perform special configuration if required.

Parameters:
button - the button to configureMenu.

getButtonFactory

public ButtonFactory getButtonFactory()
Gets the button factory to use for this command. If the button factory hasn't been configured by calling setButtonFactory(org.pietschy.command.ButtonFactory), then the default factory specified by CommandManager.setButtonFactory(org.pietschy.command.ButtonFactory).

Returns:
this commands ButtonFactory.
See Also:
setButtonFactory(org.pietschy.command.ButtonFactory), CommandManager.setButtonFactory(org.pietschy.command.ButtonFactory)

setButtonFactory

public void setButtonFactory(ButtonFactory factory)
Sets the ButtonFactory for this command to use for default when creating buttons.

Parameters:
factory - the ButtonFactory to use.

getToolbarFactory

public ToolbarFactory getToolbarFactory()
Gets the toolbar factory to use for this command. If the factory hasn't been configured by calling setToolbarFactory(org.pietschy.command.ToolbarFactory), then the default factory specified by CommandManager.setToolbarFactory(org.pietschy.command.ToolbarFactory) is used.

Returns:
this commands ButtonFactory.
See Also:
setToolbarFactory(org.pietschy.command.ToolbarFactory), CommandManager.setToolbarFactory(org.pietschy.command.ToolbarFactory)

setToolbarFactory

public void setToolbarFactory(ToolbarFactory factory)
Sets the ToolbarFactory for this command to use for default when creating buttons on toolbars.

Parameters:
factory - the ButtonFactory to use.

getMenuFactory

public MenuFactory getMenuFactory()
Gets the MenuFactory to use for this command when creating menu items. If the factory hasn't been configured by calling setMenuFactory(org.pietschy.command.MenuFactory) then the value provided by CommandManager.getMenuFactory() is used.

Returns:
the MenuFactory to use.

setMenuFactory

public void setMenuFactory(MenuFactory factory)
Sets the MenuFactory to use for menus created by this command.

Parameters:
factory - the MenuFactory to use.

setEnabled

public void setEnabled(boolean enabled)
Updates the enabled state of this command and any attached buttons.

Parameters:
enabled - true to enable the command.

isEnabled

public boolean isEnabled()
Checks the enabled state of this action and it's attached buttons.

Returns:
true if the command is enabled.

setVisible

public void setVisible(boolean value)
Sets the command and all it's buttons to be visible or not.

Parameters:
value -

isVisible

public boolean isVisible()
Checks if the buttons of this command are visible.

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

getText

public java.lang.String getText()
Deprecated. use getDefaultFace() instead.


setText

public void setText(java.lang.String text)
Deprecated. use getDefaultFace() instead.


getAccelerator

public javax.swing.KeyStroke getAccelerator()
Deprecated. use getDefaultFace() instead.


setAccelerator

public void setAccelerator(javax.swing.KeyStroke accelerator)
Deprecated. use getDefaultFace() instead.


setMnemonic

public void setMnemonic(java.lang.Integer mnemonic)
Deprecated. use getDefaultFace() instead.


setLongDescription

public void setLongDescription(java.lang.String longDescription)
Deprecated. use getDefaultFace() instead.


setIcon

public void setIcon(javax.swing.Icon icon)
Deprecated. use getDefaultFace() instead.


setSelectedIcon

public void setSelectedIcon(javax.swing.Icon newSelectedIcon)
Deprecated. use getDefaultFace() instead.


setMnemonicIndex

public void setMnemonicIndex(java.lang.Integer mnemonicIndex)
Deprecated. use getDefaultFace() instead.


setDescription

public void setDescription(java.lang.String shortDescription)
Deprecated. use getDefaultFace() instead.


setTextPosition

public void setTextPosition(java.lang.Integer textPosition)
Deprecated. use getDefaultFace() instead.


getTextPosition

public java.lang.Integer getTextPosition()
Deprecated. use getDefaultFace() instead.


getMnemonic

public java.lang.Integer getMnemonic()
Deprecated. use getDefaultFace() instead.


getIcon

public javax.swing.Icon getIcon()
Deprecated. use getDefaultFace() instead.


getSelectedIcon

public javax.swing.Icon getSelectedIcon()
Deprecated. use getDefaultFace() instead.


getMnemonicIndex

public java.lang.Integer getMnemonicIndex()
Deprecated. use getDefaultFace() instead.


getDescription

public java.lang.String getDescription()
Deprecated. use getDefaultFace() instead.


getLongDescription

public java.lang.String getLongDescription()
Deprecated. use getDefaultFace() instead.


addFace

public void addFace(Face face)
Deprecated. use getFace(String, boolean) or getDefaultFace(boolean) instead.

Adds a the specified face to the command.

If a face with the same name already exists in the command, it is replaced with the specified face and all affected buttons are updated.

Parameters:
face - the new Face to installFace.

installFace

protected void installFace(Face face)
Adds a the specified face to the command.

If a face with the same name already exists in the command, it is replaced with the specified face and all affected buttons are updated.

Parameters:
face - the new Face to installFace.

addNewFace

public Face addNewFace(java.lang.String faceName)
Deprecated. @deprecated use getFace(String, boolean) or getDefaultFace(boolean) instead.

Creates and adds a new empty face with the specified name.

Parameters:
faceName - the name of the face, "button" for example.
Returns:
the newly created face.

buttonIterator

protected java.util.Iterator buttonIterator()
Creates and returns an iterator over the buttons.

Returns:
an Iterator over the attached buttons

getDefaultFace

public Face getDefaultFace()
Gets this commands default face. This is either the face with the name Face.DEFAULT. If no face exists with this name, then the first registered face is returned.

Returns:
this commands default face.

getDefaultFace

public Face getDefaultFace(boolean createIfMissing)
Gets this commands default face. This is either the face with the name Face.DEFAULT. If no face exists with this name, then the first registered face is returned.

Parameters:
createIfMissing - true to create the face if it doesn't exist, false to return null if it doesn't exists.
Returns:
this commands default face.

getFace

public Face getFace(java.lang.String faceName)
Gets the best matching face for the specified name. This method first attempts to get the exact face, if that fails it iterates over the face names returned by getAlternativeFaceNames(java.lang.String). If non of these faces exist, then the default face is returned.

Parameters:
faceName - the name of the face to retrieved. Face.BUTTON for example.
Returns:
the specified face, or the next best face according to getAlternativeFaceNames(java.lang.String).

getFace

public Face getFace(java.lang.String faceName,
                    boolean createIfMissing)
Gets the face with the specified name.

Parameters:
faceName - the name of the face to retrieved. Face.BUTTON for example.
createIfMissing - true to create the face if it doesn't exist, false to return the best matching face as determined by getAlternativeFaceNames(String).
Returns:
the specified face, or the next best face according to getAlternativeFaceNames(java.lang.String).

faceExists

public boolean faceExists(java.lang.String faceName)

getAlternativeFaceNames

public java.lang.String[] getAlternativeFaceNames(java.lang.String face)
Gets a list of face names that can be used in place of the specified name if it hasn't been registered with the command. This method doesn't need to return the default face in the list of options.

Parameters:
face - the face name
Returns:
a list of alternative faces with the best alternative at index 0.

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener l)
Adds a property change listener to this command.

Parameters:
l - the listener

addPropertyChangeListener

public void addPropertyChangeListener(java.lang.String propertyName,
                                      java.beans.PropertyChangeListener l)
Adds a property change listener to this command.

Parameters:
propertyName - the property to listen to.
l - the listener

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener l)
Removes the listener from this command

Parameters:
l - the listener

removePropertyChangeListener

public void removePropertyChangeListener(java.lang.String propertyName,
                                         java.beans.PropertyChangeListener l)
Removes the listener from this command

Parameters:
propertyName - the property to stop listening to.
l - the listener

addHoverListener

public void addHoverListener(HoverListener l)
Adds a HoverListener to the command manager. The listener will be notified when ever the mouse hovers over a command.

Parameters:
l - the hover listener
See Also:
HoverListener, removeHoverListener(org.pietschy.command.HoverListener)

removeHoverListener

public void removeHoverListener(HoverListener l)
Removes the HoverListener from the command manager.

Parameters:
l - the hover listener
See Also:
HoverListener, addHoverListener(org.pietschy.command.HoverListener)

fireHoverStarted

protected void fireHoverStarted(Face face,
                                java.awt.Component source)

fireHoverEnded

protected void fireHoverEnded(Face face,
                              java.awt.Component source)

requestFocusIn

public void requestFocusIn(java.awt.Container container)
This method will find the first button from this command in the specified container and call JComponent.requestFocus() followed by Component.repaint().

Parameters:
container - the container that holds a button from this command.

getButtonIn

public javax.swing.AbstractButton getButtonIn(java.awt.Container container)
This method will find the first button from this command in the specified container.

Parameters:
container - the container that holds a button from this command.

createButton

public javax.swing.AbstractButton createButton()
Creates a new button that is attached to the command.

Returns:
the newly created button

createButton

public javax.swing.AbstractButton createButton(java.lang.String faceId)
Creates a new button that is attached to the command using the specified face. If the face doesn't exist, the default face is used.

Returns:
the newly created button

createButton

public javax.swing.AbstractButton createButton(ButtonFactory factory)
Create a new button for this command using the specified ButtonFactory. The default Face.BUTTON is used, it it hasn't been defined, the Face.DEFAULT is used.

Returns:
a new JButton that will execute this command.
See Also:
ButtonFactory

createButton

public javax.swing.AbstractButton createButton(ButtonFactory factory,
                                               java.lang.String faceId)
Create a new button for this command using the specified ButtonFactory and Face . If the Face is null the default face Face.DEFAULT for this command is used.

Returns:
a new JButton

createMenuItem

public javax.swing.JMenuItem createMenuItem()
Creates a new menu item for this command. This command uses Face.MENU and the currently configured MenuFactory. If Face.MENU hasn't been configured then the default face is used.

Returns:
a new JMenuItem.
See Also:
createMenuItem(java.lang.String), createMenuItem(org.pietschy.command.MenuFactory, java.lang.String), createMenuItem(org.pietschy.command.MenuFactory)

createMenuItem

public javax.swing.JMenuItem createMenuItem(java.lang.String faceId)
Creates a new menu item for this command using the specifed Face name and the currently configured MenuFactory.

Returns:
a new JMenuItem.
See Also:
createMenuItem(org.pietschy.command.MenuFactory, java.lang.String), createMenuItem(org.pietschy.command.MenuFactory)

createMenuItem

public javax.swing.JMenuItem createMenuItem(MenuFactory factory)
Creates a new menu item for this command using Face.MENU and the specified MenuFactory. If Face.MENU hasn't been specified, then the default is used.

Returns:
a new JMenuItem
See Also:
createMenuItem(org.pietschy.command.MenuFactory, java.lang.String)

createMenuItem

public javax.swing.JMenuItem createMenuItem(MenuFactory factory,
                                            java.lang.String faceId)
Creates a new menu item for this command using the specified Face and the specified MenuFactory.

Returns:
a new JMenuItem.

configureButtonAppearances

protected void configureButtonAppearances()
Reconfigures the appearances of all buttons bound to this command.


configureButtonAppearances

protected void configureButtonAppearances(Face face)
Reconfigures all the buttons attached to this command that have the specified face. This method will be automatically called whenever the property of a face is modified.

Parameters:
face - the face whose buttons are to be reconfigured.

configureButtonAppearance

protected void configureButtonAppearance(javax.swing.AbstractButton button)
Configures the appearance of the specified button. This method simply delegates to RenderManager.renderButton(javax.swing.AbstractButton).

Parameters:
button - the button to configure.

toString

public java.lang.String toString()
Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character '@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())
 

Overrides:
toString in class java.lang.Object
Returns:
a string representation of the object.