bibliothek.gui
Interface Dockable

All Superinterfaces:

DockElement, DockElementRepresentative, PlaceholderListItem<Dockable>

All Known Subinterfaces:

CommonDockable

All Known Implementing Classes:

AbstractDockable, AbstractDockableStation, CFlapDockStation, CSplitDockStation, DefaultCommonDockable, DefaultDockable, FlapDockStation, SplitDockStation, StackDockStation

public interface Dockable
extends DockElement, DockElementRepresentative, PlaceholderListItem<Dockable>

A Dockable is a window which can be dragged around by the user. Dockables need to have a DockStation as parent, otherwise they are not visible.
Several properties are associated with a Dockable:

• A set of DockTitles is managed by the parent of this Dockable. The icon and the title-text of this Dockable might be painted on that title.
• A set of DockActions is stored in a DockActionSource. These actions are displayed on the title(s) and allow users to execute operations that belong to this Dockable
• A Component which represents the contents of this Dockable

This interface is not intended to be implemented by clients, although they can if some very special behavior is required. Normally clients are better of using the DefaultDockable or extending AbstractDockable.

Author:

Benjamin Sigg

Method Summary

boolean	accept(DockStation station) Tells whether station is an accepted parent for this Dockable or not.
boolean	accept(DockStation base, Dockable neighbor) 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	addMouseInputListener(MouseInputListener listener) Adds a MouseInputListener to the component of this 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.
Component	getComponent() Gets the Component which represents this Dockable.
DockController	getController() Gets the current controller, the argument of the last call of setController(DockController).
DockStation	getDockParent() Gets the current parent, which is the latest argument of setDockParent(DockStation).
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.
Icon	getTitleIcon() Gets the current icon of this Dockable.
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. replaced by isDockableShowing(), this method will be removed in a future release
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	removeMouseInputListener(MouseInputListener listener) Removes a listener that was earlier added to this Dockable.
void	requestDisplayer(DisplayerRequest request) Invoked to get DockableDisplayer for this Dockable.
void	requestDockTitle(DockTitleRequest request) Invoked to get a graphical representation of a title for this Dockable.
void	setController(DockController controller) Sets the controller in whose realm this Dockable is.
void	setDockParent(DockStation station) Sets the parent property.
void	unbind(DockTitle title) Clients should call this method if a DockTitle is no longer needed.

Methods inherited from interface bibliothek.gui.dock.DockElement

asDockable, asDockStation, getFactoryID

Methods inherited from interface bibliothek.gui.dock.DockElementRepresentative

getElement, getPopupLocation, isUsedAsTitle, shouldFocus, shouldTransfersFocus

Methods inherited from interface bibliothek.gui.dock.station.support.PlaceholderListItem

asDockable

Method Detail

setDockParent

void setDockParent(DockStation station)

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.

Parameters:

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

getDockParent

DockStation getDockParent()

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

Returns:

the parent property, can be null

isDockableVisible

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

Deprecated. replaced by isDockableShowing(), this method will be removed in a future release

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.

Returns:

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

isDockableShowing

boolean isDockableShowing()

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.

Returns:

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

setController

void setController(DockController controller)

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)

Parameters:

controller - the owner, may be null

getController

DockController getController()

Gets the current controller, the argument of the last call of setController(DockController).

Specified by:

getController in interface DockElement

Returns:

the controller, can be null

addDockableListener

void addDockableListener(DockableListener listener)

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

Parameters:

listener - the new listener

removeDockableListener

void removeDockableListener(DockableListener listener)

Removes a listener from this Dockable.

Parameters:

listener - the listener to remove

addDockHierarchyListener

void addDockHierarchyListener(DockHierarchyListener listener)

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)

Parameters:

listener - the new listener

removeDockHierarchyListener

void removeDockHierarchyListener(DockHierarchyListener listener)

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

Parameters:

listener - the listener to remove

See Also:

addDockableListener(DockableListener)

addDockableStateListener

void addDockableStateListener(DockableStateListener listener)

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

Parameters:

listener - the new listener, not null

removeDockableStateListener

void removeDockableStateListener(DockableStateListener listener)

Removes listener from this element.

Parameters:

listener - the listener to remove

addMouseInputListener

void addMouseInputListener(MouseInputListener listener)

Adds a MouseInputListener to the component of this Dockable. A Dockable has to decide by itself which Components should be observer, but generally all free areas should be covered. It's also possible just to ignore the listener, but that's not the preferred behavior.

Specified by:

addMouseInputListener in interface DockElementRepresentative

Parameters:

listener - the mouse listener

removeMouseInputListener

void removeMouseInputListener(MouseInputListener listener)

Removes a listener that was earlier added to this Dockable.

Specified by:

removeMouseInputListener in interface DockElementRepresentative

Parameters:

listener - The listener to remove

accept

boolean accept(DockStation station)

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.

Parameters:

station - a possible parent

Returns:

whether station could be a parent or not

accept

boolean accept(DockStation base,
               Dockable neighbor)

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.

Parameters:

base - the future parent of the combination

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

Returns:

true if the combination is allowed, false otherwise

getComponent

Component getComponent()

Gets the Component which represents this Dockable. Note that the component should be a focus cycle root

Specified by:

getComponent in interface DockElementRepresentative

Returns:

the visible representation

getTitleText

String getTitleText()

Gets the current title-text of this Dockable.

Returns:

the text

getTitleToolTip

String getTitleToolTip()

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

Returns:

the tooltip, can be null

getTitleIcon

Icon getTitleIcon()

Gets the current icon of this Dockable.

Returns:

the icon, may be null

requestDockTitle

void requestDockTitle(DockTitleRequest request)

Invoked to get a graphical representation of a title for this Dockable. This method is called either when a title first is required, or when this Dockable invoked the DockableListener.titleExchanged(Dockable, DockTitle) method of its current observers.
This Dockable might decide to answer the request by calling DockTitleRequest.answer(DockTitle), any title, including null are valid answers. If this Dockable does not answer the request the associated DockTitleFactory (as described by DockTitleVersion.getFactory()) is asked to answer the request.
The requests target must be this Dockable.
The normal behavior of this method is to do nothing.

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

void requestDisplayer(DisplayerRequest request)

Invoked to get DockableDisplayer for this Dockable. This method may be called when this Dockable is dropped onto a new DockStation, a theme was exchanged, or an existing DockableDisplayer was discarded.
The usual behavior of this method should be to do nothing.

Parameters:

request - callback used to set a new DockableDisplayer

bind

void bind(DockTitle title)

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 listBoundTitles() unless unbind(DockTitle) is called.

Parameters:

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

Throws:

IllegalArgumentException - if the title is already bound

See Also:

unbind(DockTitle)

unbind

void unbind(DockTitle title)

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 listBoundTitles()

Parameters:

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

Throws:

IllegalArgumentException - if the title is not known to this Dockable

See Also:

bind(DockTitle)

listBoundTitles

DockTitle[] listBoundTitles()

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

Returns:

the list of titles

getLocalActionOffers

DockActionSource getLocalActionOffers()

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.

Returns:

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

getGlobalActionOffers

DockActionSource getGlobalActionOffers()

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

Returns:

the source containing all actions, never null

configureDisplayerHints

void configureDisplayerHints(DockableDisplayerHints hints)

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.

Parameters:

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