bibliothek.gui.dock.action.actions

Class GroupedDockAction<K,D extends SimpleDockAction>

java.lang.Object

bibliothek.gui.dock.action.actions.AbstractStandardDockAction

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

Constructors

Constructor and Description
GroupedDockAction(GroupKeyGenerator<? extends K> generator) Creates a new action.

Method Summary

Modifier and Type	Method and Description
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 DockAction, 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 DockAction, 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 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 transferred 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 DockAction, 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 DockAction, 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 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.