bibliothek.gui.dock.action.actions
Class GroupedDockAction<K,D extends SimpleDockAction>

java.lang.Object
  extended by bibliothek.gui.dock.action.actions.AbstractStandardDockAction
      extended by bibliothek.gui.dock.action.actions.GroupedDockAction<K,D>
Type Parameters:
K - the type of the key used to distinguish between groups
D - the internal representation of one group
All Implemented Interfaces:
DockAction, StandardDockAction
Direct Known Subclasses:
GroupedDropDownItemAction

public abstract class GroupedDockAction<K,D extends SimpleDockAction>
extends AbstractStandardDockAction

A DockAction which classifies its Dockables in groups. Every Dockable must be in one group. The groups itself are completely independent, except that they all must have the same ActionType.
A Dockable may change its group at any time. The method setGroup is used for that.
If a new Dockable is bound to this action, the createGroupKey-method determines the group where the Dockable will be added.
When a group is completely empty, it is removed. This behavior can be changed by the method setRemoveEmptyGroups.

Author:
Benjamin Sigg
See Also:
createGroupKey(Dockable), setRemoveEmptyGroups(boolean)

Field Summary
 
Fields inherited from class bibliothek.gui.dock.action.actions.AbstractStandardDockAction
listeners
 
Fields inherited from interface bibliothek.gui.dock.action.DockAction
BUTTON_CONTENT_FILTER
 
Constructor Summary
GroupedDockAction(GroupKeyGenerator<? extends K> generator)
          Creates a new action.
 
Method Summary
 void bound(Dockable dockable)
          Invoked by this AbstractStandardDockAction when a Dockable was bound to this action the first time.
protected abstract  D createGroup(K key)
          Creates a new group.
protected  K createGroupKey(Dockable dockable)
          Calculates the name of the group to which the dockable should be added.
Every Dockable is member of one group.
protected  D ensureGroup(K key)
          Ensures that there exist a group with the name key.
 KeyStroke getAccelerator(K key)
          Gets the type of KeyEvent that will trigger an action.
 Icon getDisabledIcon(Dockable dockable)
           
 Icon getDisabledIcon(Object key)
          Gets the icon that is shown, when the group key is disabled.
 Dockable getDockableRepresentation(Dockable dockable)
          Tells whether this DockAction represents a Dockable.
 Dockable getDockableRepresentation(K key)
          Gets the Dockable which is represented by this DockAction.
 GroupKeyGenerator<? extends K> getGenerator()
          Gets the generator that is used to create keys for unknown Dockables.
protected  D getGroup(Dockable dockable)
          Gets the group in which dockable is.
protected  D getGroup(Object key)
          Gets the group with the given key.
 Icon getIcon(Dockable dockable, ActionContentModifier modifier)
          Gets the Icon of this DockAction, when this DockAction is shown together with dockable.
 Icon getIcon(Object key)
          Gets the icon of the group named key.
 Icon getIcon(Object key, ActionContentModifier modifier)
          Gets the icon of the group named key.
 ActionContentModifier[] getIconContexts(Dockable dockable)
          Gets all the ActionContentModifiers for which StandardDockAction.getIcon(Dockable, ActionContentModifier) would return a value other than null.
 String getText(Dockable dockable)
          Gets the text of this DockActon, when this DockAction is shown together with dockable.
 String getText(Object key)
          Gets the text of the the group key.
 String getTooltip(Object key)
          Gets the tooltip of the group key.
 String getTooltipText(Dockable dockable)
          Gets a tooltip for this DockActon, when this DockAction is shown together with dockable.
 String getTooltipText(Object key)
          Gets the tooltip text of the group key.
 boolean groupExists(Object key)
          Returns true if a group with the name of key exists, return false otherwise.
 boolean isEnabled(Dockable dockable)
          This method chooses the result according to the current DisablingStrategy.
 boolean isEnabled(Object key)
          Gets the enabled-state of the group key.
 boolean isKnown(Dockable dockable)
          Tells whether the dockable is bound to this action, or not.
 boolean isRemoveEmptyGroups()
          If true, groups with no Dockable associated to, will be deleted automatically.
 boolean removeGroup(Object key)
          Removes a group but only if the group is empty (no Dockables are registered in that group).
 void setAccelerator(K key, KeyStroke accelerator)
          Set the type of KeyEvent that will trigger an action.
 void setDisabledIcon(K key, Icon icon)
          Sets the icon which will be shown, when the group named key is disabled.
 void setDockableRepresentation(K key, Dockable dockable)
          Sets the Dockable that is represented by this group.
 void setEnabled(K key, boolean enabled)
          Sets the enabled-state of the group key.
 void setGenerator(GroupKeyGenerator<? extends K> generator)
          Sets the generator that is used to create keys for unknown Dockables.
 void setGroup(K key, Dockable dockable)
          Assigns the dockable/code> to the group with the given key.
 void setIcon(K key, ActionContentModifier modifier, Icon icon)
          Sets the icon of the group named key.
 void setIcon(K key, Icon icon)
          Sets the icon of the group named key.
 void setRemoveEmptyGroups(boolean removeEmptyGroups)
          Sets whether empty groups should be removed automatically.
A group is a set of Dockables.
 void setText(K key, String text)
          Sets the text for group key.
 void setTooltip(K key, String text)
          Sets the tooltip of the group key.
 boolean trigger(Dockable dockable)
          Does the appropriate action that can be done respecting the current state of this action.
 void unbound(Dockable dockable)
          Called by this AbstractStandardDockAction when the Dockable dockable will not be used in any means by this action.
 
Methods inherited from class bibliothek.gui.dock.action.actions.AbstractStandardDockAction
addDockActionListener, bind, fireActionEnabledChanged, fireActionIconChanged, fireActionRepresentativeChanged, fireActionTextChanged, fireActionTooltipTextChanged, getBoundDockables, isBound, removeDockActionListener, unbind
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface bibliothek.gui.dock.action.DockAction
createView
 

Constructor Detail

GroupedDockAction

public GroupedDockAction(GroupKeyGenerator<? extends K> generator)
Creates a new action.

Parameters:
generator - the generator that will be used to get a key for Dockables which do not yet have a key. The generator can be null and set later through the method setGenerator(GroupKeyGenerator)
Method Detail

setGenerator

public void setGenerator(GroupKeyGenerator<? extends K> generator)
Sets the generator that is used to create keys for unknown Dockables.

Parameters:
generator - the generator
See Also:
createGroupKey(Dockable)

getGenerator

public GroupKeyGenerator<? extends K> getGenerator()
Gets the generator that is used to create keys for unknown Dockables.

Returns:
the generator
See Also:
createGroupKey(Dockable)

isRemoveEmptyGroups

public boolean isRemoveEmptyGroups()
If true, groups with no Dockable associated to, will be deleted automatically.

Returns:
true if empty groups are deleted

setRemoveEmptyGroups

public void setRemoveEmptyGroups(boolean removeEmptyGroups)
Sets whether empty groups should be removed automatically.
A group is a set of Dockables. A group can become empty if all it's Dockables are transfered to another group, or removed through an unbound.

Parameters:
removeEmptyGroups - true if empty groups should be deleted, false if the should remain in memory and be used again.

getIcon

public Icon getIcon(Dockable dockable,
                    ActionContentModifier modifier)
Description copied from interface: StandardDockAction
Gets the Icon of this DockAction, when this DockAction is shown together with dockable. This method must ignore the backup property of modifier.

Parameters:
dockable - The Dockable for which the action-icon should be chosen.
modifier - how the icon will be used
Returns:
The icon to show for this action when the action is associated with dockable, or null.

getIconContexts

public ActionContentModifier[] getIconContexts(Dockable dockable)
Description copied from interface: StandardDockAction
Gets all the ActionContentModifiers for which StandardDockAction.getIcon(Dockable, ActionContentModifier) would return a value other than null.

Parameters:
dockable - the Dockable for which the action-icons may be chosen.
Returns:
the contexts in which an icon is present

getText

public String getText(Dockable dockable)
Description copied from interface: StandardDockAction
Gets the text of this DockActon, when this DockAction is shown together with dockable.

Parameters:
dockable - The Dockable for which the action-text should be chosen.
Returns:
The text to show for this action when the action is associated with dockable, or null.

getTooltipText

public String getTooltipText(Dockable dockable)
Description copied from interface: StandardDockAction
Gets a tooltip for this DockActon, when this DockAction is shown together with dockable.

Parameters:
dockable - The Dockable for which the action-tooltip should be chosen.
Returns:
The tooltip to show for this action when the action is associated with dockable, or null.

isEnabled

public boolean isEnabled(Dockable dockable)
Description copied from class: AbstractStandardDockAction
This method chooses the result according to the current DisablingStrategy.

Specified by:
isEnabled in interface StandardDockAction
Overrides:
isEnabled in class AbstractStandardDockAction
Parameters:
dockable - The Dockable for which this action maybe triggered.
Returns:
true if the user should be able to trigger this action, false otherwise

bound

public void bound(Dockable dockable)
Description copied from class: AbstractStandardDockAction
Invoked by this AbstractStandardDockAction when a Dockable was bound to this action the first time.

Overrides:
bound in class AbstractStandardDockAction
Parameters:
dockable - The Dockable that was not known to this action before the method was invoked

unbound

public void unbound(Dockable dockable)
Description copied from class: AbstractStandardDockAction
Called by this AbstractStandardDockAction when the Dockable dockable will not be used in any means by this action. Note that the AbstractStandardDockAction.bound(Dockable)-method can be invoked again with the dockable.

Overrides:
unbound in class AbstractStandardDockAction
Parameters:
dockable - The Dockable which will not by used in any way.

setIcon

public void setIcon(K key,
                    Icon icon)
Sets the icon of the group named key. If this group does not exist, it will be created.

Parameters:
key - the name of the group
icon - the new icon of the group, may be null

getIcon

public Icon getIcon(Object key)
Gets the icon of the group named key.

Parameters:
key - The name of the group
Returns:
The icon of the group, may be null
Throws:
IllegalArgumentException - If the group does not exist
See Also:
setIcon(Object, Icon)

setIcon

public void setIcon(K key,
                    ActionContentModifier modifier,
                    Icon icon)
Sets the icon of the group named key. If this group does not exist, it will be created.

Parameters:
key - the name of the group
modifier - tells in which context the icon is used
icon - the new icon of the group, may be null

getIcon

public Icon getIcon(Object key,
                    ActionContentModifier modifier)
Gets the icon of the group named key.

Parameters:
key - The name of the group
modifier - tells in which context the icon is used
Returns:
The icon of the group, may be null
Throws:
IllegalArgumentException - If the group does not exist
See Also:
setIcon(Object, Icon)

setDisabledIcon

public void setDisabledIcon(K key,
                            Icon icon)
Sets the icon which will be shown, when the group named key is disabled. If the group key does not exist, it will be created.

Parameters:
key - The name of the group
icon - The new icon for the disabled-state of the group, may be null

getDisabledIcon

public Icon getDisabledIcon(Dockable dockable)

getDisabledIcon

public Icon getDisabledIcon(Object key)
Gets the icon that is shown, when the group key is disabled.

Parameters:
key - The name of the group
Returns:
The disabled-icon, may be null
Throws:
IllegalArgumentException - If the group does not exist
See Also:
setDisabledIcon(Object, Icon)

setText

public void setText(K key,
                    String text)
Sets the text for group key. If the group does not exist, it will be created.

Parameters:
key - The name of the group
text - The text of the group

getText

public String getText(Object key)
Gets the text of the the group key.

Parameters:
key - the key of the group
Returns:
the text of the group
Throws:
IllegalArgumentException - if the group does not exist
See Also:
setText(Object, String)

setTooltip

public void setTooltip(K key,
                       String text)
Sets the tooltip of the group key. If the group does not exist, it will be created. The tooltip is the first part of the tooltip text. The whole tooltip text may contain additional information like the accelerator.

Parameters:
key - The name of the group
text - The tooltip of the group

getTooltipText

public String getTooltipText(Object key)
Gets the tooltip text of the group key. The tooltip text is the text which is really shown on the tooltip.

Parameters:
key - The name of the group
Returns:
The tooltip
Throws:
IllegalArgumentException - If the group does not exist
See Also:
setTooltip(Object, String), getTooltip(Object)

getTooltip

public String getTooltip(Object key)
Gets the tooltip of the group key. The tooltip if the first part of the tooltip text.

Parameters:
key - The name of the group
Returns:
The tooltip
Throws:
IllegalArgumentException - If the group does not exist
See Also:
setTooltip(Object, String)

setEnabled

public void setEnabled(K key,
                       boolean enabled)
Sets the enabled-state of the group key. This action can only be triggered, if the associated Dockable is in a group with true enable-state. If the group does not exist, it will be created.

Parameters:
key - The name of the group
enabled - The state of the group

isEnabled

public boolean isEnabled(Object key)
Gets the enabled-state of the group key.

Parameters:
key - The name of the group
Returns:
The enabled-state
Throws:
IllegalArgumentException - If the group does not exist
See Also:
setEnabled(Object, boolean)

getDockableRepresentation

public Dockable getDockableRepresentation(Dockable dockable)
Description copied from interface: StandardDockAction
Tells whether this DockAction represents a Dockable. If so, the framework may register views for this action as DockElementRepresentative.

Parameters:
dockable - The Dockable for which this action may be triggered
Returns:
the Dockable which is represented by this action, can be null. Normally dockable should not be the result.

getDockableRepresentation

public Dockable getDockableRepresentation(K key)
Gets the Dockable which is represented by this DockAction.

Parameters:
key - the name of the group
Returns:
the element, can be null
Throws:
IllegalArgumentException - if the group does not exist

setDockableRepresentation

public void setDockableRepresentation(K key,
                                      Dockable dockable)
Sets the Dockable that is represented by this group.

Parameters:
key - the name of the group
dockable - the new represented Dockable, can be null

setAccelerator

public void setAccelerator(K key,
                           KeyStroke accelerator)
Set the type of KeyEvent that will trigger an action.

Parameters:
key - the group of actions whose trigger might be affected
accelerator - the new key-trigger or null

getAccelerator

public KeyStroke getAccelerator(K key)
Gets the type of KeyEvent that will trigger an action.

Parameters:
key - the affected group
Returns:
the type of event or null
Throws:
IllegalArgumentException - if key is unknown

ensureGroup

protected D ensureGroup(K key)
Ensures that there exist a group with the name key.

Parameters:
key - The name of the group
Returns:
The group with the name key. This may be a newly created group, or a group that already existed.

getGroup

protected D getGroup(Dockable dockable)
Gets the group in which dockable is.

Parameters:
dockable - the Dockable whose group is searched
Returns:
the group or null

getGroup

protected D getGroup(Object key)
Gets the group with the given key.

Parameters:
key - the key of the group
Returns:
the group or null

createGroup

protected abstract D createGroup(K key)
Creates a new group.

Parameters:
key - the key of the new group
Returns:
the new group

groupExists

public boolean groupExists(Object key)
Returns true if a group with the name of key exists, return false otherwise.

Parameters:
key - The group that is searched
Returns:
true if key was found, false otherwise

removeGroup

public boolean removeGroup(Object key)
Removes a group but only if the group is empty (no Dockables are registered in that group).

Parameters:
key - The name of the group
Returns:
true if there is no longer a group with name key (also true if there never existed a group with that name), or false if the group was not deleted because it was not empty.

createGroupKey

protected K createGroupKey(Dockable dockable)
Calculates the name of the group to which the dockable should be added.
Every Dockable is member of one group. The membership determines text, icon, etc. for the dockable. Whenever a dockable is bound to this action, the group will be determined by this method. Later on, the group can be changed by the method setGroup.
The default implementation uses the generator of this action.

Parameters:
dockable - The Dockable whose group has to be found
Returns:
the name of the dockable's group. That can be an existing or a non existing group. null is not a valid result.

setGroup

public void setGroup(K key,
                     Dockable dockable)
Assigns the dockable/code> to the group with the given key.

Parameters:
key - The name of the new group
dockable - The Dockable whose membership will be changed. The dockable must already be in a group of this action.
Throws:
IllegalArgumentException - if the Dockable is not in a group, or if key is null
See Also:
createGroupKey(Dockable)

isKnown

public boolean isKnown(Dockable dockable)
Tells whether the dockable is bound to this action, or not. If the dockable was unbound, then this method will return false.

Parameters:
dockable - the Dockable to search
Returns:
true if the Dockable is bound

trigger

public boolean trigger(Dockable dockable)
Description copied from interface: DockAction
Does the appropriate action that can be done respecting the current state of this action.

Parameters:
dockable - the element for which this action is called
Returns:
true if this action could do anything, false if this action was not able to react in any way to the event.