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:

• Each Dockable should be child of a DockableDisplayer. The displayer will paint border and title of the item.
• This station should be aware of the current DockTheme and use its factories and delegates whenever possible.
• Drag and drop is handled by the DockController. Methods like canDrag(Dockable), drag(Dockable), prepareDrop(StationDropItem) need to be implemented for this. Also accept(Dockable), Dockable.accept(DockStation), Dockable.accept(DockStation, Dockable) and the DockAcceptance of the current DockController should be checked before allowing a drag and drop operation.
• For each child there should be at least one DockTitle. This station needs to derive a DockTitleVersion from its controller using the DockTitleManager and its factory method. With the DockTitleVersion-object one DockTitleRequest for each required DockTitle can be created.
• One child can be focused. If this station changes the focus it should use DockController.setAtLeastFocusedDockable(Dockable, Component).
• This station should support placeholders. The current PlaceholderStrategy can be used to convert Dockables to placeholders. A PlaceholderList is a good datastructure to store Dockables and placeholders at the same time.
• Additional points where the user can start drag and drop operations can be installed by implementing a DockElementRepresentative. It has to be installed using DockController.addRepresentative(DockElementRepresentative).
• And a new DockFactory will be required to persistently store the layout of this station.

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:

• This method should use accept(Dockable) and Dockable.accept(DockStation) or Dockable.accept(DockStation, Dockable) to ensure that the desired drop-location is valid.
• The method should use the DockAcceptance of its controller (see DockController.getAcceptance()) to ensure that the drop/location is valid.

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