bibliothek.gui
Interface DockStation

All Superinterfaces:

DockElement

All Known Subinterfaces:

CommonDockStation<S,C>

All Known Implementing Classes:

AbstractDockableStation, AbstractDockStation, CFlapDockStation, CScreenDockStation, CSplitDockStation, FlapDockStation, ScreenDockStation, SecureCSplitDockStation, SecureFlapDockStation, SecureScreenDockStation, SecureSplitDockStation, SecureStackDockStation, 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), drop() or move() 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	canCompare(DockStation station) Tells whether this station knows a rule how to compare itself with 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.
int	compare(DockStation station) Compares this station with station.
void	drag(Dockable dockable) Removes a child from this station.
void	draw() Informs this station that the information gathered by prepareDrop or prepareMove should be painted somehow onto this station.
void	drop() Adds the Dockable of the last run of prepareDrop to 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.
void	forget() Tells this station that a possible drop or move on this station was canceled.
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.
PlaceholderMap	getPlaceholders() Gets a snapshot of all placeholders that are currently stored in this DockStation.
java.awt.Rectangle	getStationBounds() Gets a rectangle in which all points of the station are.
DockTheme	getTheme() Gets the current theme of this station.
<D extends Dockable & DockStation> boolean	isInOverrideZone(int x, int y, D invoker, Dockable drop) If the controller asks a station if a child could be dropped or moved, the controller assumes that no other station has interest in this event.
boolean	isStationVisible() Tells whether this station is visible or not.
boolean	isVisible(Dockable dockable) Tells whether the child dockable is visible or not.
void	move() Moves a child of this station to a new location according to the information gathered by prepareMove.
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.
boolean	prepareDrop(int mouseX, int mouseY, int titleX, int titleY, boolean checkOverrideZone, Dockable dockable) Prepares this station to get the new child dockable.
boolean	prepareMove(int mouseX, int mouseY, int titleX, int titleY, boolean checkOverrideZone, Dockable dockable) Prepares the station that one of its children is moved from one location to another location.
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	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

boolean isVisible(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

boolean isStationVisible()

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:

java.lang.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

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

boolean prepareDrop(int mouseX,
                    int mouseY,
                    int titleX,
                    int titleY,
                    boolean checkOverrideZone,
                    Dockable dockable)

Prepares this station to get the new child dockable. The station has to store a possible location of the child, and should draw some indicators where the child will be put. The station can refuse dockable, in this case nothing has to be painted and this method returns false.
There are some constraints:

• The result should be false if this station is dockable, checkOverrideZone is true and the mouse is in the override-zone. of the parent. However, that condition is just "good manners" and may be broken.
• 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.

This method gets two points: mouseX/mouseY is the location of the mouse, titleX/titleY is the location of the dragged title. The second point may be interesting if the title of a dropped child should have the same coordinates as the image of the dragged title.
This method is never called if dockable is a child of this station. In such a case prepareMove is invoked.

Parameters:

mouseX - the x-coordinate of the mouse on the screen

mouseY - the y-coordinate of the mouse on the screen

titleX - the x-location of the dragged title or mouseX if no title is dragged

titleY - the y-location of the dragged title or mouseY if no title is dragged

checkOverrideZone - whether this station has to check if the mouse is in the override-zone of its parent

dockable - the element which will be dropped

Returns:

true if dockable can be added at the current location, false otherwise.

drop

void drop()

Adds the Dockable of the last run of prepareDrop to this station. This method is only called if the new child and this station accepted each other, prepareDrop returned true and the new child is not yet a child of this station.

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.

prepareMove

boolean prepareMove(int mouseX,
                    int mouseY,
                    int titleX,
                    int titleY,
                    boolean checkOverrideZone,
                    Dockable dockable)

Prepares the station that one of its children is moved from one location to another location. See prepareDrop for detailed information about the behavior of this method. The only difference between this method and prepareDrop is, that dockable is a child of this station.

Parameters:

mouseX - the x-coordinate of the mouse on the screen

mouseY - the y-coordinate of the mouse on the screen

titleX - the x-location of the dragged title or mouseX if no title is dragged

titleY - the y-location of the dragged title or mouseY if no title is dragged

checkOverrideZone - whether this station has to check if the mouse is in the override-zone of its parent

dockable - the element which will be moved

Returns:

true if dockable can be added at the current location, false otherwise.

move

void move()

Moves a child of this station to a new location according to the information gathered by prepareMove.

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

draw

void draw()

Informs this station that the information gathered by prepareDrop or prepareMove should be painted somehow onto this station.
The station should use the StationPaint of its theme to draw.

forget

void forget()

Tells this station that a possible drop or move on this station was canceled. The station can throw away any information gathered by the last call prepareDrop or prepareMove
If the station is drawing some markings because of a call to draw(), than the station can throw away these markings too.

isInOverrideZone

<D extends Dockable & DockStation> boolean isInOverrideZone(int x,
                                                           int y,
                                                           D invoker,
                                                           Dockable drop)

If the controller asks a station if a child could be dropped or moved, the controller assumes that no other station has interest in this event. However if this station is a dockable, and has a parent, the parent might be interested in the new child. This dockable station has to ask the parent if the current location of the mouse is in the override-zone. This station should not accept a child if the parent returns true.
On the other hand, this station could be asked by a child whether the mouse is in the override-zone. If the mouse hits a point of special interest, then the method should return true.
Note: if this station is asked and is a dockable station itself, then this method should ask the parent for his override-zone too.

Type Parameters:

D - the type of invoker

Parameters:

x - the x-coordinate of the mouse on the screen

y - the y-coordinate of the mouse on the screen

invoker - a child of this station which invoked the method

drop - a Dockable which might become a child

Returns:

true if the location of the mouse is of special interest

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:

java.lang.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:

java.lang.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:

java.lang.IllegalArgumentException - if next is a child of this station, if old is not a child or if old is not a Dockable

getStationBounds

java.awt.Rectangle getStationBounds()

Gets a rectangle in which all points of the station are. The user is only able to move a Dockable into this area onto this station.

Returns:

the bounds, relative to the screen, null to indicate that this station has not any bounds

canCompare

boolean canCompare(DockStation station)

Tells whether this station knows a rule how to compare itself with station. See compare(DockStation) for more details.

Parameters:

station - another station

Returns:

true if a call to compare will not end in an exception and return another value than 0

compare

int compare(DockStation station)

Compares this station with station. The comparison is needed if the stations bounds of the two station have common points. On a drag-event, the controller needs a way to decide which station is more important (and receives the opportunity to get a new child first). The controller will use the method compare to do this. This method works like Comparable.compareTo(Object).

Parameters:

station - another station

Returns:

a number less/equal/higher than zero, if this station has higher/equal/lesser priority than station.