bibliothek.gui
Interface Dockable

All Superinterfaces:
DockElement, DockElementRepresentative
All Known Subinterfaces:
CommonDockable
All Known Implementing Classes:
AbstractDockable, AbstractDockableStation, DefaultCommonDockable, DefaultDockable, FlapDockStation, SecureFlapDockStation, SecureSplitDockStation, SecureStackDockStation, SplitDockStation, StackDockStation

public interface Dockable
extends DockElement, DockElementRepresentative

A Dockable is a window which is put onto a DockStation. The user can grab a Dockable and drag it to another station.
A Dockable has some properties:

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 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 last argument of setDockParent(DockStation).
 DockTitle getDockTitle(DockTitleVersion version)
          Invoked to get a graphical representation of a title for this Dockable.
There are several requirements to the title and the caller: The owner of the title must be this Dockable. The origin of the title must be version. The title must not be bound The result should be independent of the current state of this Dockable. The method should not change any attribute of this Dockable The client must call the bind(DockTitle)-method of this Dockable before using the title.
 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()
          Gest 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.
 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 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 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
 

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, and do not fire a DockHierarchyEvent here.

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 last argument of setDockParent(DockStation).

Returns:
the parent property, can be null

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)

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

getDockTitle

DockTitle getDockTitle(DockTitleVersion version)
Invoked to get a graphical representation of a title for this Dockable.
There are several requirements to the title and the caller:

Parameters:
version - which title is required. If this Dockable does not have a special rule for the given version, it can return the result of DockTitleVersion.createDockable(Dockable).
Returns:
The title, can be null if no title should be shown. Note that not all clients can handle a null-title, if in doubt, return a title.

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 get 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