bibliothek.gui
Interface Dockable

All Superinterfaces:
DockElement
All Known Implementing Classes:
AbstractDockable, AbstractDockableStation, DefaultDockable, FlapDockStation, SecureFlapDockStation, SplitDockStation, StackDockStation

public interface Dockable
extends DockElement

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 addMouseInputListener(javax.swing.event.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.
 DockActionSource getActionOffers()
          Gets a list of DockAction which should be triggerable if this Dockable is visible.
 java.awt.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 binded 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.
 javax.swing.Icon getTitleIcon()
          Gets the current icon of this Dockable.
 java.lang.String getTitleText()
          Gest the current title-text of this Dockable.
 DockTitle[] listBindedTitles()
          Gets a list of all DockTitles which are currently binded to this Dockable.
 void removeDockableListener(DockableListener listener)
          Removes a listener from this Dockable.
 void removeMouseInputListener(javax.swing.event.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
 

Method Detail

setDockParent

void setDockParent(DockStation station)
Sets the parent property. This Dockable is shown as direct child of station.

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.

Parameters:
controller - the owner, may be null

getController

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

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

addMouseInputListener

void addMouseInputListener(javax.swing.event.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.

Parameters:
listener - the mouse listener

removeMouseInputListener

void removeMouseInputListener(javax.swing.event.MouseInputListener listener)
Removes a listener that was earlier added to this Dockable.

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

java.awt.Component getComponent()
Gets the Component which represents this Dockable. Note that the component should be a focus cycle root

Returns:
the visible representation

getTitleText

java.lang.String getTitleText()
Gest the current title-text of this Dockable.

Returns:
the text

getTitleIcon

javax.swing.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 binded. However, the method DockTitle.bind() must not be invoked by this method.
title must be returned by listBindedTitles() unless unbind(DockTitle) is called.

Parameters:
title - the title which will be show some things of this Dockable
Throws:
java.lang.IllegalArgumentException - if the title is already binded
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 binded. However, this method must not call DockTitle.unbind().
title must no longer be returned when calling listBindedTitles()

Parameters:
title - the title which will be no longer connected to this Dockable
Throws:
java.lang.IllegalArgumentException - if the title is not known to this dockable
See Also:
bind(DockTitle)

listBindedTitles

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

Returns:
the list of titles

getActionOffers

DockActionSource getActionOffers()
Gets a list of DockAction which should be triggerable if this Dockable is visible. 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