org.pietschy.command

Class Command

Known Direct 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 EventListenerList
listenerList
protected SwingPropertyChangeSupport
pcs

Constructor Summary

Command(CommandManager commandManager)
Creates a new anonymous command.
Command(CommandManager commandManager, 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(String faceName)
void
addNotify(CommandGroup parent)
Invoked whenever a command is added to a group.
void
addPropertyChangeListener(PropertyChangeListener l)
Adds a property change listener to this command.
void
addPropertyChangeListener(String propertyName, PropertyChangeListener l)
Adds a property change listener to this command.
void
attach(AbstractButton button, String faceName)
Attaches this command to the specified button.
protected Iterator
buttonIterator()
Creates and returns an iterator over the buttons.
protected void
configureButtonAppearance(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(AbstractButton button)
This method is called to configureMenu newly created buttons.
AbstractButton
createButton()
Creates a new button that is attached to the command.
AbstractButton
createButton(String faceId)
Creates a new button that is attached to the command using the specified face.
AbstractButton
createButton(ButtonFactory factory)
Create a new button for this command using the specified ButtonFactory.
AbstractButton
createButton(ButtonFactory factory, String faceId)
Create a new button for this command using the specified ButtonFactory and Face .
JMenuItem
createMenuItem()
Creates a new menu item for this command.
JMenuItem
createMenuItem(String faceId)
Creates a new menu item for this command using the specifed Face name and the currently configured MenuFactory.
JMenuItem
createMenuItem(MenuFactory factory)
Creates a new menu item for this command using Face.MENU and the specified MenuFactory.
JMenuItem
createMenuItem(MenuFactory factory, String faceId)
Creates a new menu item for this command using the specified Face and the specified MenuFactory.
void
detach(AbstractButton button)
Detaches this command from the specified button.
Command
export()
Registers this command with its CommandManager.
boolean
faceExists(String faceName)
protected void
fireHoverEnded(Face face, Component source)
protected void
fireHoverStarted(Face face, Component source)
KeyStroke
getAccelerator()
Deprecated. use getDefaultFace instead.
String[]
getAlternativeFaceNames(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.
AbstractButton
getButtonIn(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.
String
getDescription()
Deprecated. use getDefaultFace instead.
Face
getFace(String faceName)
Gets the best matching face for the specified name.
Face
getFace(String faceName, boolean createIfMissing)
Gets the face with the specified name.
Icon
getIcon()
Deprecated. use getDefaultFace instead.
String
getId()
Gets this commands identifier.
String
getLongDescription()
Deprecated. use getDefaultFace instead.
MenuFactory
getMenuFactory()
Gets the MenuFactory to use for this command when creating menu items.
Integer
getMnemonic()
Deprecated. use getDefaultFace instead.
Integer
getMnemonicIndex()
Deprecated. use getDefaultFace instead.
String
getProperty(String name)
String
getProperty(String name, String defaultValue)
String[]
getPropertyNames()
Icon
getSelectedIcon()
Deprecated. use getDefaultFace instead.
String
getText()
Deprecated. use getDefaultFace instead.
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(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(String name, 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(PropertyChangeListener l)
Removes the listener from this command
void
removePropertyChangeListener(String propertyName, PropertyChangeListener l)
Removes the listener from this command
void
requestFocusIn(Container container)
This method will find the first button from this command in the specified container and call javax.swing.JComponent.requestFocus followed by Container.repaint.
void
setAccelerator(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(String shortDescription)
Deprecated. use getDefaultFace instead.
void
setEnabled(boolean enabled)
Updates the enabled state of this command and any attached buttons.
void
setIcon(Icon icon)
Deprecated. use getDefaultFace instead.
void
setLongDescription(String longDescription)
Deprecated. use getDefaultFace instead.
void
setMenuFactory(MenuFactory factory)
Sets the MenuFactory to use for menus created by this command.
void
setMnemonic(Integer mnemonic)
Deprecated. use getDefaultFace instead.
void
setMnemonicIndex(Integer mnemonicIndex)
Deprecated. use getDefaultFace instead.
void
setSelectedIcon(Icon newSelectedIcon)
Deprecated. use getDefaultFace instead.
void
setText(String text)
Deprecated. use getDefaultFace instead.
void
setTextPosition(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.
String
toString()
Returns a string representation of the object.

Field Details

internalLog

protected Logger internalLog

listenerList

protected EventListenerList listenerList

pcs

protected SwingPropertyChangeSupport pcs

Constructor Details

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,
                  String id)
Constructs a new Command object with the specified Id.
Parameters:
commandManager -
id - the identifier of this command.

Method Details

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.

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

addNewFace

public Face addNewFace(String faceName)

Deprecated.

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.

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.

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener l)
Adds a property change listener to this command.
Parameters:
l - the listener

addPropertyChangeListener

public void addPropertyChangeListener(String propertyName,
                                      PropertyChangeListener l)
Adds a property change listener to this command.
Parameters:
propertyName - the property to listen to.
l - the listener

attach

public void attach(AbstractButton button,
                   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.

buttonIterator

protected Iterator buttonIterator()
Creates and returns an iterator over the buttons.
Returns:
an Iterator over the attached buttons

configureButtonAppearance

protected void configureButtonAppearance(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.

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.

configureButtonStates

protected void configureButtonStates(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.

createButton

public AbstractButton createButton()
Creates a new button that is attached to the command.
Returns:
the newly created button

createButton

public AbstractButton createButton(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 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 AbstractButton createButton(ButtonFactory factory,
                                   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 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(MenuFactory)

createMenuItem

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

createMenuItem

public 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 JMenuItem createMenuItem(MenuFactory factory,
                                String faceId)
Creates a new menu item for this command using the specified Face and the specified MenuFactory.
Returns:
a new JMenuItem.

detach

public void detach(AbstractButton button)
Detaches this command from the specified button.
Parameters:
button - the button from which this command is to be detached.

export

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

faceExists

public boolean faceExists(String faceName)

fireHoverEnded

protected void fireHoverEnded(Face face,
                              Component source)

fireHoverStarted

protected void fireHoverStarted(Face face,
                                Component source)

getAccelerator

public KeyStroke getAccelerator()

Deprecated. use getDefaultFace instead.


getAlternativeFaceNames

public String[] getAlternativeFaceNames(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.

getButtonFactory

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

getButtonIn

public AbstractButton getButtonIn(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.

getCommandManager

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

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.

getDescription

public String getDescription()

Deprecated. use getDefaultFace instead.


getFace

public Face getFace(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(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(String).

getFace

public Face getFace(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(String).

getIcon

public Icon getIcon()

Deprecated. use getDefaultFace instead.


getId

public String getId()
Gets this commands identifier.
Returns:
the identifier of this command.

getLongDescription

public String getLongDescription()

Deprecated. use getDefaultFace instead.


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(MenuFactory) then the value provided by CommandManager.getMenuFactory() is used.
Returns:
the MenuFactory to use.

getMnemonic

public Integer getMnemonic()

Deprecated. use getDefaultFace instead.


getMnemonicIndex

public Integer getMnemonicIndex()

Deprecated. use getDefaultFace instead.


getProperty

public String getProperty(String name)

getProperty

public String getProperty(String name,
                          String defaultValue)

getPropertyNames

public String[] getPropertyNames()

getSelectedIcon

public Icon getSelectedIcon()

Deprecated. use getDefaultFace instead.


getText

public String getText()

Deprecated. use getDefaultFace instead.


getTextPosition

public Integer getTextPosition()

Deprecated. use getDefaultFace instead.


getToolbarFactory

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

initCommandManager

protected void initCommandManager(CommandManager commandManager)

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.

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.

isAttachedTo

public boolean isAttachedTo(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.

isEnabled

public boolean isEnabled()
Checks the enabled state of this action and it's attached buttons.
Returns:
true if the command is enabled.

isVisible

public boolean isVisible()
Checks if the buttons of this command are visible.
Returns:
true if the command is visible, false otherwise.

putProperty

public void putProperty(String name,
                        String value)

removeHoverListener

public void removeHoverListener(HoverListener l)
Removes the HoverListener from the command manager.
Parameters:
l - the hover listener

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.

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener l)
Removes the listener from this command
Parameters:
l - the listener

removePropertyChangeListener

public void removePropertyChangeListener(String propertyName,
                                         PropertyChangeListener l)
Removes the listener from this command
Parameters:
propertyName - the property to stop listening to.
l - the listener

requestFocusIn

public void requestFocusIn(Container container)
This method will find the first button from this command in the specified container and call javax.swing.JComponent.requestFocus followed by Container.repaint.
Parameters:
container - the container that holds a button from this command.

setAccelerator

public void setAccelerator(KeyStroke accelerator)

Deprecated. use getDefaultFace instead.


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.

setDescription

public void setDescription(String shortDescription)

Deprecated. use getDefaultFace instead.


setEnabled

public void setEnabled(boolean enabled)
Updates the enabled state of this command and any attached buttons.
Parameters:
enabled - true to enable the command.

setIcon

public void setIcon(Icon icon)

Deprecated. use getDefaultFace instead.


setLongDescription

public void setLongDescription(String longDescription)

Deprecated. use getDefaultFace instead.


setMenuFactory

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

setMnemonic

public void setMnemonic(Integer mnemonic)

Deprecated. use getDefaultFace instead.


setMnemonicIndex

public void setMnemonicIndex(Integer mnemonicIndex)

Deprecated. use getDefaultFace instead.


setSelectedIcon

public void setSelectedIcon(Icon newSelectedIcon)

Deprecated. use getDefaultFace instead.


setText

public void setText(String text)

Deprecated. use getDefaultFace instead.


setTextPosition

public void setTextPosition(Integer textPosition)

Deprecated. use getDefaultFace instead.


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.

setVisible

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

toString

public 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())
 
Returns:
a string representation of the object.