bibliothek.gui.dock.dockable
Class AbstractDockable

java.lang.Object
  bibliothek.gui.dock.dockable.AbstractDockable

All Implemented Interfaces:

DockElement, DockElementRepresentative, PlaceholderListItem<Dockable>, Dockable

Direct Known Subclasses:

AbstractDockableStation, DefaultDockable

public abstract class AbstractDockable
extends Object
implements Dockable

An implementation of Dockable which deals with the simple things.
Some of the capabilities of an AbstractDockable are:

• add or remove a DockableListener, and fire an event
• set the parent and the controller
• set the title and the icon
• store a list of DockActions

Author:

Benjamin Sigg

Constructor Summary

protected

AbstractDockable(PropertyKey<String> titleText, PropertyKey<String> titleTooltip) Creates a new dockable.

Method Summary

boolean	accept(DockStation station) Tells whether station is an accepted parent for this Dockable or not.
boolean	accept(DockStation base, Dockable neighbour) Tells whether base could be the parent of a combination between this Dockable and neighbor.
void	addDockableListener(DockableListener listener) Adds a listener to this Dockable.
void	addDockableStateListener(DockableStateListener listener) Adds listener to this Dockable.
void	addDockHierarchyListener(DockHierarchyListener listener) Adds a hierarchy-listener to this Dockable.
void	addKeyListener(KeyListener listener) Adds a KeyListener to this Dockable.
void	addMouseInputListener(MouseInputListener listener) Adds a listener to this representative, it is not defined what to do with that listener, but most subclasses would just add the listener to their component.
Dockable	asDockable() Returns this if this is an instance of Dockable.
void	bind(DockTitle title) Called by clients which want to show a title of this Dockable.
void	configureDisplayerHints(DockableDisplayerHints hints) Orders this Dockable to configure hints which will be used by the parent component of this element.
protected abstract DockIcon	createTitleIcon() Creates the DockIcon which represents this Dockable or this DockStation.
protected void	fireTitleBound(DockTitle title) Informs all dockableListeners that title was bound to this dockable.
protected void	fireTitleExchanged() Informs all DockableListeners that all bound titles and the null title are no longer considered good titles and should be replaced
protected void	fireTitleExchanged(DockTitle title) Informs all DockableListeners that title is no longer considered to be a good title and should be exchanged.
protected void	fireTitleIconChanged(Icon oldIcon, Icon newIcon) Calls the titleIconChanged method of all registered DockableListener.
protected void	fireTitleTextChanged(String oldTitle, String newTitle) Calls the titleTextChanged method of all registered DockableListeners.
protected void	fireTitleTooltipChanged(String oldTooltip, String newTooltip) Called the titleTooltipChanged method of all registered DockableListeners.
protected void	fireTitleUnbound(DockTitle title) Informs all dockableListeners that title was unbound from this dockable.
protected DockableDisplayerHints	getConfigurableDisplayerHints() Gets the last DockableDisplayerHints that were given to configureDisplayerHints(DockableDisplayerHints).
DockController	getController() Gets the controller that currently is associated with this DockElement.
protected DockableStateListenerManager	getDockableStateListeners() Gets the manager which is responsible for handling DockableStateListeners.
protected DockableStateListenerManager	getDockElementObserver() Access to the DockableStateListenerManager which can be used to fire DockableStateEvents.
DockStation	getDockParent() Gets the current parent, which is the latest argument of Dockable.setDockParent(DockStation).
DockElement	getElement() Gets the element which is represented by this.
DockActionSource	getGlobalActionOffers() Gets a list of all DockActions which might be triggered while this Dockable is visible.
DockActionSource	getLocalActionOffers() Gets a list of DockActions which should be triggerable if this Dockable is visible.
Point	getPopupLocation(Point click, boolean popupTrigger) Tells whether a popup menu should be opened when the user clicks at click with the mouse.
Icon	getTitleIcon() Gets the current icon of this Dockable.
IconHandling	getTitleIconHandling() Tells how a null title icon is handled.
String	getTitleText() Gets the current title-text of this Dockable.
String	getTitleToolTip() Gets a tooltip that is associated with this Dockable and that should be shown on any DockTitle.
boolean	isDockableShowing() Tells whether this Dockable can be seen by the user.
boolean	isDockableVisible() Deprecated.
boolean	isUsedAsTitle() Tells whether this DockElementRepresentative is used as title. Some modules grant more rights to titles than to non-titles, i.e.
DockTitle[]	listBoundTitles() Gets a list of all DockTitles which are currently bound to this Dockable.
void	removeDockableListener(DockableListener listener) Removes a listener from this Dockable.
void	removeDockableStateListener(DockableStateListener listener) Removes listener from this element.
void	removeDockHierarchyListener(DockHierarchyListener listener) Removes a hierarchy-listener from this Dockable. Note: when using a DockHierarchyObserver, forward the call directly to DockHierarchyObserver.removeDockHierarchyListener(DockHierarchyListener)
void	removeKeyListener(KeyListener listener) Removes listener from this element.
void	removeMouseInputListener(MouseInputListener listener) Removes a listener from this representative.
void	requestDisplayer(DisplayerRequest request) The default behavior of this method is to do nothing.
void	requestDockTitle(DockTitleRequest request) The default behavior of this method is to do nothing.
void	resetTitleIcon() Resets the icon of this Dockable, the default icon is shown again.
void	setActionOffers(DockActionSource source) Sets the action-source of this Dockable.
void	setController(DockController controller) Sets the controller in whose realm this Dockable is.
void	setDockParent(DockStation station) Sets the parent property.
void	setTitleIcon(Icon titleIcon) Sets the icon of this dockable.
void	setTitleIconHandling(IconHandling titleIconHandling) Sets the behavior of how the title icon is handled, whether it is replaced by the default icon if null or simply not shown. Calling this method does not have any effect, rather the behavior of setTitleIcon(Icon) is changed.
void	setTitleText(String titleText) Sets the title of this dockable.
void	setTitleToolTip(String titleToolTip) Sets the tooltip that will be shown on any title of this dockable.
boolean	shouldFocus() Tells whether a click onto this component should transfer the focus either to this component or to the Dockable.
boolean	shouldTransfersFocus() Tells whether a click onto this component should transfer the focus to the Dockable or not.
void	unbind(DockTitle title) Clients should call this method if a DockTitle is no longer needed.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface bibliothek.gui.Dockable

getComponent

Methods inherited from interface bibliothek.gui.dock.DockElement

asDockStation, getFactoryID

Constructor Detail

AbstractDockable

protected AbstractDockable(PropertyKey<String> titleText,
                           PropertyKey<String> titleTooltip)

Creates a new dockable.

Parameters:

titleText - the key of the title, used to read in DockProperties

titleTooltip - the key of the tooltip, used to read in DockProperties

Method Detail

createTitleIcon

protected abstract DockIcon createTitleIcon()

Creates the DockIcon which represents this Dockable or this DockStation. The icon must call fireTitleIconChanged(Icon, Icon) if the icon changes.

Returns:

the default icon for this element

setDockParent

public void setDockParent(DockStation station)

Description copied from interface: Dockable

Sets the parent property. This Dockable is shown as direct child of station.
Note: this method has to fire a DockHierarchyEvent.
Note: when using a DockHierarchyObserver, invoke DockHierarchyObserver.update() after the property has changed, it will automatically fire a DockHierarchyEvent if necessary.

Specified by:

setDockParent in interface Dockable

Parameters:

station - the parent, may be null if this Dockable is not visible at all.

getDockParent

public DockStation getDockParent()

Description copied from interface: Dockable

Gets the current parent, which is the latest argument of Dockable.setDockParent(DockStation).

Specified by:

getDockParent in interface Dockable

Returns:

the parent property, can be null

asDockable

public Dockable asDockable()

Description copied from interface: DockElement

Returns this if this is an instance of Dockable. Otherwise null is returned.

Specified by:

asDockable in interface DockElement

Specified by:

asDockable in interface PlaceholderListItem<Dockable>

Returns:

this or null. Must not return null if DockElement.asDockable() already returns null.

setController

public void setController(DockController controller)

Description copied from interface: Dockable

Sets the controller in whose realm this Dockable is. A value of null means that this Dockable is not managed by a controller.
Note: this method has to inform all DockHierarchyListeners about the change.
Note: when using a DockHierarchyObserver, invoke DockHierarchyObserver.controllerChanged(DockController)

Specified by:

setController in interface Dockable

Parameters:

controller - the owner, may be null

getController

public DockController getController()

Description copied from interface: DockElement

Gets the controller that currently is associated with this DockElement.

Specified by:

getController in interface DockElement

Specified by:

getController in interface Dockable

Returns:

the controller or null

isDockableShowing

public boolean isDockableShowing()

Description copied from interface: Dockable

Tells whether this Dockable can be seen by the user. A Dockable at least needs to be registered as root-station on a DockController, or be a child of a root-station to be visible.
Implementations will assume that Components which are displayable are are visible to the user.

Specified by:

isDockableShowing in interface Dockable

Returns:

true if the user can actually see this dockable, false otherwise

isDockableVisible

@Deprecated
@Todo(compatibility=BREAK_MAJOR,
      priority=ENHANCEMENT,
      target=VERSION_1_1_3,
      description="remove this method")
public boolean isDockableVisible()

Deprecated.

Description copied from interface: Dockable

Tells whether this Dockable can be seen by the user. A Dockable at least needs to be registered as root-station on a DockController, or be a child of a root-station to be visible.
Implementations will assume that Components which are displayable are are visible to the user.

Specified by:

isDockableVisible in interface Dockable

Returns:

true if the user can actually see this dockable, false otherwise

addDockableListener

public void addDockableListener(DockableListener listener)

Description copied from interface: Dockable

Adds a listener to this Dockable. The listener has to be informed if a property of this Dockable changes.

Specified by:

addDockableListener in interface Dockable

Parameters:

listener - the new listener

removeDockableListener

public void removeDockableListener(DockableListener listener)

Description copied from interface: Dockable

Removes a listener from this Dockable.

Specified by:

removeDockableListener in interface Dockable

Parameters:

listener - the listener to remove

addDockHierarchyListener

public void addDockHierarchyListener(DockHierarchyListener listener)

Description copied from interface: Dockable

Adds a hierarchy-listener to this Dockable. The listener has to be informed whenever the path to this Dockable has been changed.
Subclasses might use the DockHierarchyObserver to implement this feature in an easy way. Subclasses then only have to call DockHierarchyObserver.update() whenever the parent of this Dockable changes.
Note: when using a DockHierarchyObserver, forward the call directly to DockHierarchyObserver.addDockHierarchyListener(DockHierarchyListener)

Specified by:

addDockHierarchyListener in interface Dockable

Parameters:

listener - the new listener

removeDockHierarchyListener

public void removeDockHierarchyListener(DockHierarchyListener listener)

Description copied from interface: Dockable

Removes a hierarchy-listener from this Dockable.
Note: when using a DockHierarchyObserver, forward the call directly to DockHierarchyObserver.removeDockHierarchyListener(DockHierarchyListener)

Specified by:

removeDockHierarchyListener in interface Dockable

Parameters:

listener - the listener to remove

See Also:

Dockable.addDockableListener(DockableListener)

addDockableStateListener

public void addDockableStateListener(DockableStateListener listener)

Description copied from interface: Dockable

Adds listener to this Dockable. The listener will be informed about various events concerning the position and visibility of this dockable.

Specified by:

addDockableStateListener in interface Dockable

Parameters:

listener - the new listener, not null

removeDockableStateListener

public void removeDockableStateListener(DockableStateListener listener)

Description copied from interface: Dockable

Removes listener from this element.

Specified by:

removeDockableStateListener in interface Dockable

Parameters:

listener - the listener to remove

getDockableStateListeners

protected DockableStateListenerManager getDockableStateListeners()

Gets the manager which is responsible for handling DockableStateListeners.

Returns:

the manager, not null

getDockElementObserver

protected DockableStateListenerManager getDockElementObserver()

Access to the DockableStateListenerManager which can be used to fire DockableStateEvents. This method is intended to be used by subclasses that implement DockStation.

Returns:

the listeners

addMouseInputListener

public void addMouseInputListener(MouseInputListener listener)

Description copied from interface: DockElementRepresentative

Adds a listener to this representative, it is not defined what to do with that listener, but most subclasses would just add the listener to their component. It is valid to do nothing.

Specified by:

addMouseInputListener in interface DockElementRepresentative

Specified by:

addMouseInputListener in interface Dockable

Parameters:

listener - the new listener

removeMouseInputListener

public void removeMouseInputListener(MouseInputListener listener)

Description copied from interface: DockElementRepresentative

Removes a listener from this representative.

Specified by:

removeMouseInputListener in interface DockElementRepresentative

Specified by:

removeMouseInputListener in interface Dockable

Parameters:

listener - the listener to remove

addKeyListener

public void addKeyListener(KeyListener listener)

Adds a KeyListener to this Dockable. The listener will be informed about any un-consumed KeyEvent that is related to this Dockable, e.g. an event that is dispatched on a DockTitle.

Parameters:

listener - the new listener

removeKeyListener

public void removeKeyListener(KeyListener listener)

Removes listener from this element.

Parameters:

listener - the listener to remove

getElement

public DockElement getElement()

Description copied from interface: DockElementRepresentative

Gets the element which is represented by this. The result of this method must not change.

Specified by:

getElement in interface DockElementRepresentative

Returns:

the element, never null

isUsedAsTitle

public boolean isUsedAsTitle()

Description copied from interface: DockElementRepresentative

Tells whether this DockElementRepresentative is used as title.
Some modules grant more rights to titles than to non-titles, i.e. a DockRelocator can allow drag & drop only for titles.
Normally a Dockable should have only one element that is a title, so if in doubt return false.

Specified by:

isUsedAsTitle in interface DockElementRepresentative

Returns:

true if this representative should be seen as title

shouldFocus

public boolean shouldFocus()

Description copied from interface: DockElementRepresentative

Tells whether a click onto this component should transfer the focus either to this component or to the Dockable.

Specified by:

shouldFocus in interface DockElementRepresentative

Returns:

true if clicking this component should influence focus

shouldTransfersFocus

public boolean shouldTransfersFocus()

Description copied from interface: DockElementRepresentative

Tells whether a click onto this component should transfer the focus to the Dockable or not. If this object is a Dockable, then a result of true might change the currently focused item of itself. This property is ignored if DockElementRepresentative.shouldFocus() returns false.

Specified by:

shouldTransfersFocus in interface DockElementRepresentative

Returns:

whether to change the focused component or not

accept

public boolean accept(DockStation station)

Description copied from interface: Dockable

Tells whether station is an accepted parent for this Dockable or not. The user is not able to drag a Dockable to a station which is not accepted.

Specified by:

accept in interface Dockable

Parameters:

station - a possible parent

Returns:

whether station could be a parent or not

accept

public boolean accept(DockStation base,
                      Dockable neighbour)

Description copied from interface: Dockable

Tells whether base could be the parent of a combination between this Dockable and neighbor. The user is not able to make a combination between this Dockable and neighbor if this method does not accept the operation.

Specified by:

accept in interface Dockable

Parameters:

base - the future parent of the combination

neighbour - a Dockable whose parent will be the same parent as the parent of this Dockable

Returns:

true if the combination is allowed, false otherwise

getTitleText

public String getTitleText()

Description copied from interface: Dockable

Gets the current title-text of this Dockable.

Specified by:

getTitleText in interface Dockable

Returns:

the text

setTitleText

public void setTitleText(String titleText)

Sets the title of this dockable. All dockableListeners are informed about the change.

Parameters:

titleText - the title, null is replaced by the empty string

getTitleIcon

public Icon getTitleIcon()

Description copied from interface: Dockable

Gets the current icon of this Dockable.

Specified by:

getTitleIcon in interface Dockable

Returns:

the icon, may be null

setTitleToolTip

public void setTitleToolTip(String titleToolTip)

Sets the tooltip that will be shown on any title of this dockable.

Parameters:

titleToolTip - the new tooltip, can be null

getTitleToolTip

public String getTitleToolTip()

Description copied from interface: Dockable

Gets a tooltip that is associated with this Dockable and that should be shown on any DockTitle.

Specified by:

getTitleToolTip in interface Dockable

Returns:

the tooltip, can be null

getPopupLocation

public Point getPopupLocation(Point click,
                              boolean popupTrigger)

Description copied from interface: DockElementRepresentative

Tells whether a popup menu should be opened when the user clicks at click with the mouse. If yes, then the top left edge of the popup should be returned, otherwise null should be returned.

Specified by:

getPopupLocation in interface DockElementRepresentative

Parameters:

click - the location where the user clicked with the mouse

popupTrigger - whether the invocation is the systems popup trigger or not. Many implementations of this method will return click in case of true, and null in case of false

Returns:

the preferred location of a popup or null if no popup-menu should be opened

setTitleIconHandling

public void setTitleIconHandling(IconHandling titleIconHandling)

Sets the behavior of how the title icon is handled, whether it is replaced by the default icon if null or simply not shown.
Calling this method does not have any effect, rather the behavior of setTitleIcon(Icon) is changed.

Parameters:

titleIconHandling - the new bheavior, not null

getTitleIconHandling

public IconHandling getTitleIconHandling()

Tells how a null title icon is handled.

Returns:

the behavior

See Also:

setTitleIconHandling(IconHandling)

setTitleIcon

public void setTitleIcon(Icon titleIcon)

Sets the icon of this dockable. All dockableListeners are informed about the change.
If titleIcon is null, then the exact behavior of this method depends on the result of getTitleIconHandling(). The method may either replace the null Icon by the default icon, or simply not show any icon.

Parameters:

titleIcon - the new icon, may be null

resetTitleIcon

public void resetTitleIcon()

Resets the icon of this Dockable, the default icon is shown again.

requestDockTitle

public void requestDockTitle(DockTitleRequest request)

The default behavior of this method is to do nothing.

Specified by:

requestDockTitle in interface Dockable

Parameters:

request - which title is required. If this Dockable does not have a special rule for the given request it just ignores the call

requestDisplayer

public void requestDisplayer(DisplayerRequest request)

The default behavior of this method is to do nothing.

Specified by:

requestDisplayer in interface Dockable

Parameters:

request - callback used to set a new DockableDisplayer

bind

public void bind(DockTitle title)

Description copied from interface: Dockable

Called by clients which want to show a title of this Dockable. The method DockTitle.bind() will be called automatically by the controller.
This method must at least inform all listeners, that title was bound. However, the method DockTitle.bind() must not be invoked by this method.
title must be returned by Dockable.listBoundTitles() unless Dockable.unbind(DockTitle) is called.

Specified by:

bind in interface Dockable

Parameters:

title - the title which will be show some things of this Dockable

See Also:

Dockable.unbind(DockTitle)

unbind

public void unbind(DockTitle title)

Description copied from interface: Dockable

Clients should call this method if a DockTitle is no longer needed. The controller will call DockTitle.unbind() at an appropriate time.
This method must inform all listeners that title is no longer bound. However, this method must not call DockTitle.unbind().
title must no longer be returned when calling Dockable.listBoundTitles()

Specified by:

unbind in interface Dockable

Parameters:

title - the title which will be no longer connected to this Dockable

See Also:

Dockable.bind(DockTitle)

listBoundTitles

public DockTitle[] listBoundTitles()

Description copied from interface: Dockable

Gets a list of all DockTitles which are currently bound to this Dockable. That are titles for which Dockable.bind(DockTitle) was called, but not yet Dockable.unbind(DockTitle).

Specified by:

listBoundTitles in interface Dockable

Returns:

the list of titles

getLocalActionOffers

public DockActionSource getLocalActionOffers()

Description copied from interface: Dockable

Gets a list of DockActions which should be triggerable if this Dockable is visible. The list contains only actions which are directly bound to this Dockable (the actions which are not changed when the parent-station of this Dockable is exchanged). The list can be modified by this Dockable at every time, clients have to react on these changes by adding a DockActionSourceListener to the result.

Specified by:

getLocalActionOffers in interface Dockable

Returns:

the source of actions, can be null if no actions are available

getGlobalActionOffers

public DockActionSource getGlobalActionOffers()

Description copied from interface: Dockable

Gets a list of all DockActions which might be triggered while this Dockable is visible. The list must contain all actions which are related in any way to this Dockable. Subclasses might use a HierarchyDockActionSource or the method DockController.listOffers(Dockable) to implement this functionality

Specified by:

getGlobalActionOffers in interface Dockable

Returns:

the source containing all actions, never null

setActionOffers

public void setActionOffers(DockActionSource source)

Sets the action-source of this Dockable. Other elements which used getGlobalActionOffers() will be informed about this change.

Parameters:

source - The new source, may be null

fireTitleTextChanged

protected void fireTitleTextChanged(String oldTitle,
                                    String newTitle)

Calls the titleTextChanged method of all registered DockableListeners.

Parameters:

oldTitle - the old title

newTitle - the new title

fireTitleTooltipChanged

protected void fireTitleTooltipChanged(String oldTooltip,
                                       String newTooltip)

Called the titleTooltipChanged method of all registered DockableListeners.

Parameters:

oldTooltip - the old value

newTooltip - the new value

fireTitleIconChanged

protected void fireTitleIconChanged(Icon oldIcon,
                                    Icon newIcon)

Calls the titleIconChanged method of all registered DockableListener.

Parameters:

oldIcon - the old icon

newIcon - the new icon

fireTitleBound

protected void fireTitleBound(DockTitle title)

Informs all dockableListeners that title was bound to this dockable.

Parameters:

title - the title which was bound

fireTitleUnbound

protected void fireTitleUnbound(DockTitle title)

Informs all dockableListeners that title was unbound from this dockable.

Parameters:

title - the title which was unbound

fireTitleExchanged

protected void fireTitleExchanged(DockTitle title)

Informs all DockableListeners that title is no longer considered to be a good title and should be exchanged.

Parameters:

title - a title, can be null

fireTitleExchanged

protected void fireTitleExchanged()

Informs all DockableListeners that all bound titles and the null title are no longer considered good titles and should be replaced

configureDisplayerHints

public void configureDisplayerHints(DockableDisplayerHints hints)

Description copied from interface: Dockable

Orders this Dockable to configure hints which will be used by the parent component of this element. This Dockable can store a reference to hints and use it to change the hints whenever it is appropriate. This method will be called with null if the link should be broken.

Specified by:

configureDisplayerHints in interface Dockable

Parameters:

hints - the hints to configure or null if the last hints should no longer be configured by this element

getConfigurableDisplayerHints

protected DockableDisplayerHints getConfigurableDisplayerHints()

Gets the last DockableDisplayerHints that were given to configureDisplayerHints(DockableDisplayerHints).

Returns:

the current configurable hints, can be null