bibliothek.gui
Interface DockStation

All Superinterfaces:
DockElement
All Known Subinterfaces:
CommonDockStation<S,C>
All Known Implementing Classes:
AbstractDockableStation, AbstractDockStation, CFlapDockStation, CScreenDockStation, CSplitDockStation, FlapDockStation, ScreenDockStation, SplitDockStation, StackDockStation

public interface DockStation
extends DockElement

A DockStation is some area (e.g. a Component) showing a set of Dockables called "children". The station is free to decide how and if to show its children.
Although a station can take any form, there are some (optional) practices to follow:

Author:
Benjamin Sigg

Method Summary
 boolean accept(Dockable child)
          Tells whether this station accepts child as a new child, or refuses child.
 void addDockStationListener(DockStationListener listener)
          Adds a listener to this station.
 boolean canDrag(Dockable dockable)
          Tells whether dockable can be removed from this station or not.
 boolean canReplace(Dockable old, Dockable next)
          Tells whether its possible to replace the child old with next where next is not a child of this station.
 void changed(Dockable dockable, DockTitle title, boolean active)
          Called by the DockController of this station to indicate that the active-state of title has been changed.
 void drag(Dockable dockable)
          Removes a child from this station.
 void drop(Dockable dockable)
          Adds dockable to this station.
 boolean drop(Dockable dockable, DockableProperty property)
          Tries to add dockable to this station such that the location given by property is matched.
 DockController getController()
          Gets the controller of this station.
 DockActionSource getDirectActionOffers(Dockable dockable)
          Gets a list of actions which should be available for the user and affect the child dockable.
 Dockable getDockable(int index)
          Gets the index'th child of this station.
 int getDockableCount()
          Gets the number of children.
 DockableProperty getDockableProperty(Dockable child, Dockable target)
          Gets precise information about the location of a child of this station.
 Dockable getFrontDockable()
          Gets the favorite child of this station.
 DockActionSource getIndirectActionOffers(Dockable dockable)
          Gets a list of actions which should be available for the user and affect dockable.
 DockStationDropLayer[] getLayers()
          Gets a description of all the areas of the screen where this DockStation can handle a drop event.
Everytime the mouse is moved or released during a drag & drop operation, this method is called for all DockStations.
 PlaceholderMap getPlaceholders()
          Gets a snapshot of all placeholders that are currently stored in this DockStation.
 DockTheme getTheme()
          Gets the current theme of this station.
 boolean isChildShowing(Dockable dockable)
          Tells whether the child dockable is visible or not.
 boolean isStationShowing()
          Tells whether this station is visible or not.
 boolean isStationVisible()
          Deprecated. use isStationShowing() instead, this method will be removed in a future release
 boolean isVisible(Dockable dockable)
          Deprecated. use isChildShowing(Dockable) instead, this method will be removed in a future release
 void move(Dockable dockable, DockableProperty property)
          Tries to move the child dockable in such a way, that getDockableProperty(Dockable, Dockable) would return a DockableProperty that equals property.
There is no need to give a guarantee that the move successes, and clients should always be prepared for the possibility that this DockStation does nothing at all.
 StationDragOperation prepareDrag(Dockable dockable)
          Informs this station that a drag and drop operation is in progress and that dockable might be removed from this station.
 StationDropOperation prepareDrop(StationDropItem dockable)
          Prepares this station to get the new child dockable or to move around the known child dockable.
 void removeDockStationListener(DockStationListener listener)
          Removes a listener from this station.
 void replace(Dockable old, Dockable next)
          Replaces the child old by next which is not yet a child of this station.
 void replace(DockStation old, Dockable next)
          Replaces the child old by next which is not yet a child of this station.
 void requestChildDisplayer(DisplayerRequest request)
          Provides a DockableDisplayer for a child of this station.
 void requestChildDockTitle(DockTitleRequest request)
          Provides a DockTitle for a child of this station.
 void setController(DockController controller)
          Sets the controller of this station.
 void setFrontDockable(Dockable dockable)
          Sets the most important child.
 void setPlaceholders(PlaceholderMap placeholders)
          Sets an earlier snapshot of the placeholders of this station.
 void updateTheme()
          Updates the DockTheme of this station.
 
Methods inherited from interface bibliothek.gui.dock.DockElement
asDockable, asDockStation, getFactoryID
 

Method Detail

setController

void setController(DockController controller)
Sets the controller of this station. If the station wants to show any DockTitle, then the titles have to be replaced by new instances (assuming the controller is really new). The title has to get new DockTitleVersions through the DockTitleManager of controller.
An argument of null means that this station is currently not shown.

Parameters:
controller - the owner of this station, can be null

getController

DockController getController()
Gets the controller of this station.

Specified by:
getController in interface DockElement
Returns:
the controller or null if no controller is set
See Also:
setController(DockController)

updateTheme

void updateTheme()
Updates the DockTheme of this station. The new theme has to be read from the controller of this station. If the controller is null, this method should return immediately.
You may use DockUI.updateTheme(DockStation, DockFactory) to implement this method.


getTheme

DockTheme getTheme()
Gets the current theme of this station. The theme can be null, but that means that the station is not fully initialized, and might not work correct.

Returns:
the theme of this station or null.

getDirectActionOffers

DockActionSource getDirectActionOffers(Dockable dockable)
Gets a list of actions which should be available for the user and affect the child dockable.

Parameters:
dockable - a child of this station
Returns:
actions for dockable, can be null

getIndirectActionOffers

DockActionSource getIndirectActionOffers(Dockable dockable)
Gets a list of actions which should be available for the user and affect dockable. The argument dockable can be a child of this station, or a child of any station which is below this station.

Parameters:
dockable - a child of this station or a child of another station which is below this station
Returns:
actions for dockable or null

addDockStationListener

void addDockStationListener(DockStationListener listener)
Adds a listener to this station. The station has to invoke the methods of the listener such that its requirements are full filled.

Parameters:
listener - the listener to add

removeDockStationListener

void removeDockStationListener(DockStationListener listener)
Removes a listener from this station.

Parameters:
listener - the listener to remove

isVisible

@Todo(compatibility=BREAK_MAJOR,
      priority=ENHANCEMENT,
      target=VERSION_1_1_3,
      description="remove this method")
@Deprecated
boolean isVisible(Dockable dockable)
Deprecated. use isChildShowing(Dockable) instead, this method will be removed in a future release

Tells whether the child dockable is visible or not. Visible means that the component of dockable can be seen by the user. The result must be false if this station is not visible.

Parameters:
dockable - the child whose visibility-state is questioned
Returns:
whether dockable is visible or not
See Also:
isStationVisible()

isChildShowing

boolean isChildShowing(Dockable dockable)
Tells whether the child dockable is visible or not. Visible means that the component of dockable can be seen by the user. The result must be false if this station is not visible.

Parameters:
dockable - the child whose visibility-state is questioned
Returns:
whether dockable is visible or not
See Also:
isStationVisible()

isStationVisible

@Deprecated
@Todo(compatibility=BREAK_MAJOR,
      priority=ENHANCEMENT,
      target=VERSION_1_1_3,
      description="remove this method")
boolean isStationVisible()
Deprecated. use isStationShowing() instead, this method will be removed in a future release

Tells whether this station is visible or not. For example a station on a JFrame is not visible if the frame is minimized.

Returns:
whether this station is visible

isStationShowing

boolean isStationShowing()
Tells whether this station is visible or not. For example a station on a JFrame is not visible if the frame is minimized.

Returns:
whether this station is visible

getDockableCount

int getDockableCount()
Gets the number of children.

Returns:
the number of children on this station

getDockable

Dockable getDockable(int index)
Gets the index'th child of this station.

Parameters:
index - a value between 0 (incl.) and getDockableCount() (excl.).
Returns:
a child of this station

getFrontDockable

Dockable getFrontDockable()
Gets the favorite child of this station. The favorite child is the one child which is specially designated for the user. An example: if the station behaves like a stack, and only the top child is visible, then the favorite child could the the top.
A result of null indicates that there are no children at all, or that there is no favorite child (all children are equal important).
Stations should not change this property directly, they should call DockController.setFocusedDockable(Dockable, boolean) which will then call setFrontDockable(Dockable). Note that the DockController itself listens to the DockTitles, and maybe the station doesn't need a logic to decide which child is important.

Returns:
the most important child or null

setFrontDockable

void setFrontDockable(Dockable dockable)
Sets the most important child. The station should ensure that this child is visible (assuming the station itself is visible). Read the comment on getFrontDockable() how stations can change this property.

Parameters:
dockable - the new favorite child, can be null
See Also:
getFrontDockable()

getPlaceholders

PlaceholderMap getPlaceholders()
Gets a snapshot of all placeholders that are currently stored in this DockStation. A DockStation is free in the format it chooses to fill the map. The map is to be created with the assumptions that getDockableCount() is 0, meaning any existing Dockable gets replaced by its placeholder. The current PlaceholderStrategy should be used to convert Dockables to placeholders.

Returns:
the map of placeholders or null if this station does not support placeholders

setPlaceholders

void setPlaceholders(PlaceholderMap placeholders)
Sets an earlier snapshot of the placeholders of this station. This station can assume that it currently does not have any children (that getDockableCount() is 0).
This method does nothing if it cannot handle the format or the version of placeholders.

Parameters:
placeholders - some set of placeholders
Throws:
IllegalStateException - if getDockableCount() is not equal to 0

changed

void changed(Dockable dockable,
             DockTitle title,
             boolean active)
Called by the DockController of this station to indicate that the active-state of title has been changed. This station should call the method title.changed with an appropriate event. The station may add some additional information to this call.

Parameters:
dockable - the child whose title is changed
title - the changed title, may not be bound
active - the new state of the title

requestChildDockTitle

void requestChildDockTitle(DockTitleRequest request)
Provides a DockTitle for a child of this station. This method must call DockTitleRequest.answer(DockTitle) to set the result.
Most DockStations won't have the need to implement this method, leaving it empty will advice the framework to use another source for new DockTitles.

Parameters:
request - the request to answer, not null

requestChildDisplayer

void requestChildDisplayer(DisplayerRequest request)
Provides a DockableDisplayer for a child of this station. This method must call DisplayerRequest.answer(DockableDisplayer) to set the result.
The usual implementation should be to do nothing.

Parameters:
request - the request to answer, not null

accept

boolean accept(Dockable child)
Tells whether this station accepts child as a new child, or refuses child. The user will not be able to drop a Dockable onto this station if this method returns false.

Parameters:
child - a Dockable which may become a child
Returns:
true if child is accepted

getDockableProperty

DockableProperty getDockableProperty(Dockable child,
                                     Dockable target)
Gets precise information about the location of a child of this station. The result of this method could later be used to invoke drop(Dockable, DockableProperty).

Parameters:
child - a child of this station, this childs location is asked
target - an optional hint telling for which dockable the location information will be used, can be null. This hint can be used to find a placeholder that should be part of the result.
Returns:
the location
See Also:
DockUtilities.getPropertyChain(DockStation, Dockable)

prepareDrop

StationDropOperation prepareDrop(StationDropItem dockable)
Prepares this station to get the new child dockable or to move around the known child dockable. The station can refuse dockable, in this case this method just returns null. There are some constraints:

Parameters:
dockable - information about the dockable that is going to be dropped
Returns:
an object describing where the Dockable can be dropped or null if no drop operation is possible

prepareDrag

StationDragOperation prepareDrag(Dockable dockable)
Informs this station that a drag and drop operation is in progress and that dockable might be removed from this station.

Parameters:
dockable - the child that might be removed in the near future
Returns:
a callback that will be informed when the dockable was removed or the operation canceleled, can be null

drop

void drop(Dockable dockable)
Adds dockable to this station. The station can decide by its own where to put dockable.

Parameters:
dockable - a new child

drop

boolean drop(Dockable dockable,
             DockableProperty property)
Tries to add dockable to this station such that the location given by property is matched. If property has a successor and points to another station, just call the drop-method of this child-station. Note that property can be of any type and contain invalid information.

Parameters:
dockable - the new child
property - the location of the child, may be invalid data
Returns:
true if property could be read and dockable was dropped, false otherwise.

move

void move(Dockable dockable,
          DockableProperty property)
Tries to move the child dockable in such a way, that getDockableProperty(Dockable, Dockable) would return a DockableProperty that equals property.
There is no need to give a guarantee that the move successes, and clients should always be prepared for the possibility that this DockStation does nothing at all.

Parameters:
dockable - a child of this station
property - the preferred position of dockable

getLayers

DockStationDropLayer[] getLayers()
Gets a description of all the areas of the screen where this DockStation can handle a drop event.
Everytime the mouse is moved or released during a drag & drop operation, this method is called for all DockStations. The returned DockStationDropLayers are then filtered and ordered, the resulting order defines the order in which the method prepareDrop(StationDropItem) is called.

Returns:
all the layers of this station, must not be null, must not contain null, must not contain the same entry twice. The array or the DockStationDropLayers may be modified, hence this method should always create new objects.

canDrag

boolean canDrag(Dockable dockable)
Tells whether dockable can be removed from this station or not. This method assumes that dockable is a child of this station, if not, then the behavior of this method is unspecified.
Note that the result of this method may not be respected every time, it's more a hint for the controller how to act.

Parameters:
dockable - a child of this station
Returns:
true if dockable can be dragged

drag

void drag(Dockable dockable)
Removes a child from this station. This method may be called even if canDrag(Dockable) returned false.
Note: clients may need to invoke DockController.freezeLayout() and DockController.meltLayout() to ensure noone else adds or removes Dockables.

Parameters:
dockable - the child to remove

canReplace

boolean canReplace(Dockable old,
                   Dockable next)
Tells whether its possible to replace the child old with next where next is not a child of this station.

Parameters:
old - a child of this station
next - the replacement of next.
Returns:
true if the replacement is possible
Throws:
IllegalArgumentException - if next is a child of this station

replace

void replace(Dockable old,
             Dockable next)
Replaces the child old by next which is not yet a child of this station. This method should not be called if canReplace returned false.

Parameters:
old - a child
next - the replacement of old
Throws:
IllegalArgumentException - if next is a child of this station or if old is not a child

replace

void replace(DockStation old,
             Dockable next)
Replaces the child old by next which is not yet a child of this station. This method should not be called if canReplace returned false. This method can assume that next was a child of old but no longer is.

Parameters:
old - a dockable station that is a child of this station
next - the replacement of old
Throws:
IllegalArgumentException - if next is a child of this station, if old is not a child or if old is not a Dockable