bibliothek.gui.dock.station
Class ScreenDockStation

java.lang.Object
  extended by bibliothek.gui.dock.station.AbstractDockStation
      extended by bibliothek.gui.dock.station.ScreenDockStation
All Implemented Interfaces:
DockElement, DockStation
Direct Known Subclasses:
SecureScreenDockStation

public class ScreenDockStation
extends AbstractDockStation

A DockStation which is the whole screen. Every child of this station is a non modal dialog. These dialogs do not have a border or a title (except a DockTitle), but they can be moved and resized by the user.
This station tries to register a DockTitleVersion with the key TITLE_ID.

Author:
Benjamin Sigg

Field Summary
static String TITLE_ID
          The key for the DockTitleVersion of this station
 
Fields inherited from class bibliothek.gui.dock.station.AbstractDockStation
listeners
 
Constructor Summary
ScreenDockStation(Window owner)
          Constructs a new ScreenDockStation.
 
Method Summary
 void addDockable(Dockable dockable, Rectangle bounds)
          Adds a Dockable on a newly created ScreenDockDialog to the station.
 void addDockable(Dockable dockable, Rectangle bounds, boolean boundsIncludeTitle)
          Adds a Dockable on a newly created ScreenDockDialog to the station.
 Dockable asDockable()
          Returns this if this is an instance of Dockable.
 DockStation asDockStation()
          Returns this if this is an instance of DockStation.
protected  void callDockUiUpdateTheme()
          Calls the method DockUI.
 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 combine(Dockable lower, Dockable upper)
          Combines the lower and the upper Dockable to one Dockable, and replaces the lower with this new Dockable.
 int compare(DockStation station)
          Compares this station with station.
 ScreenDockDialog createDialog()
          Creates a new dialog which is associated with this station.
protected  void deregister(ScreenDockDialog dialog)
          Invoked when a ScreenDockDialog is no longer needed.
 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.
 boolean drop(Dockable dockable, ScreenDockProperty property)
          Tries to add the dockable to this station, and uses the property to determine its location.
 void forget()
          Tells this station that a possible drop or move on this station was canceled.
 CombinerWrapper getCombiner()
          Gets the Combiner that is used to merge two Dockables on this station.
 ScreenDockDialog getDialog(Dockable dockable)
          Searches the ScreenDockDialog which displays the dockable.
 ScreenDockDialog getDialog(int index)
          Get's the index'th dialog of this station.
 DefaultDockActionSource getDirectActionOffers(Dockable dockable)
          Gets a list of actions which should be available for the user and affect the child dockable.
 DisplayerFactoryWrapper getDisplayerFactory()
          Gets the DisplayerFactory that is used by this station to create an underground for its children.
 DisplayerCollection getDisplayers()
          Gets the current set of displayers used on this station.
 Dockable getDockable(int index)
          Gets the index'th child of this station.
 int getDockableCount()
          Gets the number of children.
 DockableProperty getDockableProperty(Dockable dockable)
          Gets precise information about the location of a child of this station.
 String getFactoryID()
          Gets the unique name of the DockFactory which can read and write elements of this type.
 Dockable getFrontDockable()
          Gets the favorite child of this station.
 DefaultDockActionSource getIndirectActionOffers(Dockable dockable)
          Gets a list of actions which should be available for the user and affect dockable.
 Window getOwner()
          Gets the owner of this station.
 StationPaintWrapper getPaint()
          Gets the StationPaint for this station.
 Rectangle getStationBounds()
          Gets a rectangle in which all points of the station are.
 int indexOf(Dockable dockable)
          Gets the index of a Dockable that is shown on 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 isShowing()
          Tells whether this station shows its children or not.
 void move()
          Moves a child of this station to a new location according to the information gathered by prepareMove.
 boolean prepare(int x, int y, int titleX, int titleY, Dockable dockable, boolean drop)
           
 boolean prepareDrop(int x, int y, int titleX, int titleY, Dockable dockable)
          Prepares this station to get the new child dockable.
 boolean prepareMove(int x, int y, int titleX, int titleY, Dockable dockable)
          Prepares the station that one of its children is moved from one location to another location.
protected  void register(ScreenDockDialog dialog)
          Invoked after a new ScreenDockDialog has been created.
 void removeDockable(Dockable dockable)
          Removes the dockable from this station.
 void removeDockable(int index)
          Removes the index'th Dockable of this station.
 void replace(Dockable current, Dockable other)
          Replaces the child old by next which is not yet a child of this station.
protected  ScreenDockDialog searchCombineDockable(int x, int y, Dockable drop)
          Searches a dialog on the coordinates x/y which can be used to create a combination with drop.
 void setController(DockController controller)
          Sets the controller of this station.
 void setFrontDockable(Dockable dockable)
          Sets the most important child.
 void setShowing(boolean showing)
          Sets the visibility of all dialogs of this station.
 boolean shouldDraw(ScreenDockDialog dialog)
          Tells whether there should be a "selection-rectangle" painted on the dialog or not.
 
Methods inherited from class bibliothek.gui.dock.station.AbstractDockStation
accept, addDockStationListener, changed, getController, getTheme, isStationVisible, isVisible, removeDockStationListener, updateTheme
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

TITLE_ID

public static final String TITLE_ID
The key for the DockTitleVersion of this station

See Also:
Constant Field Values
Constructor Detail

ScreenDockStation

public ScreenDockStation(Window owner)
Constructs a new ScreenDockStation.

Parameters:
owner - the window which will be used as parent for the dialogs of this station
Method Detail

getDisplayerFactory

public DisplayerFactoryWrapper getDisplayerFactory()
Gets the DisplayerFactory that is used by this station to create an underground for its children.

Returns:
the factory
See Also:
DisplayerFactoryWrapper.setDelegate(DisplayerFactory)

getDisplayers

public DisplayerCollection getDisplayers()
Gets the current set of displayers used on this station.

Returns:
the set of displayers

getCombiner

public CombinerWrapper getCombiner()
Gets the Combiner that is used to merge two Dockables on this station.

Returns:
the combiner
See Also:
CombinerWrapper.setDelegate(Combiner)

getPaint

public StationPaintWrapper getPaint()
Gets the StationPaint for this station. The paint is needed to paint information on this station, when a Dockable is dragged or moved.

Returns:
the paint
See Also:
StationPaintWrapper.setDelegate(StationPaint)

callDockUiUpdateTheme

protected void callDockUiUpdateTheme()
                              throws IOException
Description copied from class: AbstractDockStation
Calls the method DockUI.DockUI.updateTheme(DockStation, DockFactory) with this as the first argument, and an appropriate factory as the second argument.

Specified by:
callDockUiUpdateTheme in class AbstractDockStation
Throws:
IOException - if the DockUI throws an exception

setController

public void setController(DockController controller)
Description copied from interface: DockStation
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.

Specified by:
setController in interface DockStation
Overrides:
setController in class AbstractDockStation
Parameters:
controller - the owner of this station, can be null

getDirectActionOffers

public DefaultDockActionSource getDirectActionOffers(Dockable dockable)
Description copied from interface: DockStation
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

public DefaultDockActionSource getIndirectActionOffers(Dockable dockable)
Description copied from interface: DockStation
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

getDockableCount

public int getDockableCount()
Description copied from interface: DockStation
Gets the number of children.

Returns:
the number of children on this station

getDockable

public Dockable getDockable(int index)
Description copied from interface: DockStation
Gets the index'th child of this station.

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

indexOf

public int indexOf(Dockable dockable)
Gets the index of a Dockable that is shown on this station. A call to getDockable(int) with the result of this method would return dockable, if dockable is on this station.

Parameters:
dockable - the item to search
Returns:
the index of the item or -1 if not found

getFrontDockable

public Dockable getFrontDockable()
Description copied from interface: DockStation
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 DockStation.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

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

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

prepareDrop

public boolean prepareDrop(int x,
                           int y,
                           int titleX,
                           int titleY,
                           Dockable dockable)
Description copied from interface: DockStation
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.
This method will not be invoked if the result of DockStation.accept(Dockable) is false.
The result should be false if this station is dockable, and the mouse is in the override-zone of the parent. However, that condition is just "good manners" and may be broken.
If the operation introduces a new DockStation (because the child will be combined with another child), the method should use the DockAcceptance of its controller (see DockController.getAcceptance()) to ensure that the combination 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:
x - the x-coordinate of the mouse on the screen
y - 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
dockable - the element which will be dropped
Returns:
true if dockable can be added at the current location, false otherwise.

prepare

public boolean prepare(int x,
                       int y,
                       int titleX,
                       int titleY,
                       Dockable dockable,
                       boolean drop)

searchCombineDockable

protected ScreenDockDialog searchCombineDockable(int x,
                                                 int y,
                                                 Dockable drop)
Searches a dialog on the coordinates x/y which can be used to create a combination with drop.

Parameters:
x - the x-coordinate on the screen
y - die y-coordinate on the screen
drop - the Dockable which might be combined with a dialog
Returns:
the dialog which might become the parent of drop.

shouldDraw

public boolean shouldDraw(ScreenDockDialog dialog)
Tells whether there should be a "selection-rectangle" painted on the dialog or not. This is needed while a Dockable is dragged around.

Parameters:
dialog - the asking dialog
Returns:
true if something should be painted, false otherwise

drop

public void drop()
Description copied from interface: DockStation
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

public void drop(Dockable dockable)
Description copied from interface: DockStation
Adds dockable to this station. The station can decide by its own where to put dockable.

Parameters:
dockable - a new child

getDockableProperty

public DockableProperty getDockableProperty(Dockable dockable)
Description copied from interface: DockStation
Gets precise information about the location of a child of this station. The result of this method could later be used to invoke DockStation.drop(Dockable, DockableProperty).

Parameters:
dockable - the child whose location is demanded
Returns:
the location
See Also:
DockUtilities.getPropertyChain(DockStation, Dockable)

getDialog

public ScreenDockDialog getDialog(Dockable dockable)
Searches the ScreenDockDialog which displays the dockable.
Note: don't change the DockableDisplayer or the Dockable of the dialog.

Parameters:
dockable - the Dockable to search
Returns:
the dialog or null

getDialog

public ScreenDockDialog getDialog(int index)
Get's the index'th dialog of this station. The number of dialogs is identical to the number of Dockables.

Parameters:
index - the index of the dialog
Returns:
the dialog which shows the index'th Dockable.

prepareMove

public boolean prepareMove(int x,
                           int y,
                           int titleX,
                           int titleY,
                           Dockable dockable)
Description copied from interface: DockStation
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:
x - the x-coordinate of the mouse on the screen
y - 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
dockable - the element which will be moved
Returns:
true if dockable can be added at the current location, false otherwise.

move

public void move()
Description copied from interface: DockStation
Moves a child of this station to a new location according to the information gathered by prepareMove.


draw

public void draw()
Description copied from interface: DockStation
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

public void forget()
Description copied from interface: DockStation
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 DockStation.draw(), than the station can throw away these markings too.


isInOverrideZone

public <D extends Dockable & DockStation> boolean isInOverrideZone(int x,
                                                                  int y,
                                                                  D invoker,
                                                                  Dockable drop)
Description copied from interface: DockStation
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

public boolean canDrag(Dockable dockable)
Description copied from interface: DockStation
Tells whether dockable can be removed from this station or not.
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

public void drag(Dockable dockable)
Description copied from interface: DockStation
Removes a child from this station. This method may be called even if DockStation.canDrag(Dockable) returned false.

Parameters:
dockable - the child to remove

addDockable

public void addDockable(Dockable dockable,
                        Rectangle bounds)
Adds a Dockable on a newly created ScreenDockDialog to the station. If the station is visible, the dialog will be made visible too.

Parameters:
dockable - the Dockable to show
bounds - the bounds that the dialog will have

addDockable

public void addDockable(Dockable dockable,
                        Rectangle bounds,
                        boolean boundsIncludeTitle)
Adds a Dockable on a newly created ScreenDockDialog to the station. If the station is visible, the dialog will be made visible too.

Parameters:
dockable - the Dockable to show
bounds - the bounds that the dialog will have
boundsIncludeTitle - if true, the bounds describe the size of the resulting window. Otherwise the size of the window will be a bit larger such that the title can be shown in the new space

drop

public boolean drop(Dockable dockable,
                    DockableProperty property)
Description copied from interface: DockStation
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.

drop

public boolean drop(Dockable dockable,
                    ScreenDockProperty property)
Tries to add the dockable to this station, and uses the property to determine its location. If the preferred location overlaps an existing dialog, then the Dockable may be added to a child-station of this station.

Parameters:
dockable - the new Dockable
property - the preferred location of the dockable
Returns:
true if the dockable could be added, false otherwise.

combine

public void combine(Dockable lower,
                    Dockable upper)
Combines the lower and the upper Dockable to one Dockable, and replaces the lower with this new Dockable. There are no checks whether this station {accepts the new child or the children can be combined. The creation of the new Dockable is done by the combiner.

Parameters:
lower - a Dockable which must be child of this station
upper - a Dockable which may be child of this station

canReplace

public boolean canReplace(Dockable old,
                          Dockable next)
Description copied from interface: DockStation
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

replace

public void replace(Dockable current,
                    Dockable other)
Description copied from interface: DockStation
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:
current - a child
other - the replacement of next

removeDockable

public void removeDockable(Dockable dockable)
Removes the dockable from this station.

Parameters:
dockable - the Dockable to remove

removeDockable

public void removeDockable(int index)
Removes the index'th Dockable of this station.

Parameters:
index - the index of the Dockable to remove

register

protected void register(ScreenDockDialog dialog)
Invoked after a new ScreenDockDialog has been created. This method adds some listeners to the dialog. If the method is overridden, it should be called from the subclass to ensure the correct function of this station.

Parameters:
dialog - the dialog which was newly created

deregister

protected void deregister(ScreenDockDialog dialog)
Invoked when a ScreenDockDialog is no longer needed. This method removes some listeners from the dialog. If overridden by a subclass, the subclass should ensure that this implementation is invoked too.

Parameters:
dialog - the old dialog

createDialog

public ScreenDockDialog createDialog()
Creates a new dialog which is associated with this station.

Returns:
the new dialog
Throws:
IllegalStateException - if the {owner of this station is neither a Dialog nor a Frame.

getOwner

public Window getOwner()
Gets the owner of this station. The owner is forwarded to some dialogs as their owner. So the dialogs will always remain in the foreground.

Returns:
the owner

isShowing

public boolean isShowing()
Tells whether this station shows its children or not.

Returns:
true if the dialogs are visible, false otherwise
See Also:
setShowing(boolean)

setShowing

public void setShowing(boolean showing)
Sets the visibility of all dialogs of this station.

Parameters:
showing - true if all dialogs should be visible, false otherwise.

getStationBounds

public Rectangle getStationBounds()
Description copied from interface: DockStation
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

asDockable

public Dockable asDockable()
Description copied from interface: DockElement
Returns this if this is an instance of Dockable. Otherwise null is returned.

Returns:
this or null

asDockStation

public DockStation asDockStation()
Description copied from interface: DockElement
Returns this if this is an instance of DockStation. Otherwise null is returned.

Returns:
this or null

getFactoryID

public String getFactoryID()
Description copied from interface: DockElement
Gets the unique name of the DockFactory which can read and write elements of this type.

Returns:
the id of the factory

canCompare

public boolean canCompare(DockStation station)
Description copied from interface: DockStation
Tells whether this station knows a rule how to compare itself with station. See DockStation.compare(DockStation) for more details.

Specified by:
canCompare in interface DockStation
Overrides:
canCompare in class AbstractDockStation
Parameters:
station - another station
Returns:
true if a call to compare will not end in an exception and return another value than 0

compare

public int compare(DockStation station)
Description copied from interface: DockStation
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).

Specified by:
compare in interface DockStation
Overrides:
compare in class AbstractDockStation
Parameters:
station - another station
Returns:
a number less/equal/higher than zero, if this station higher/equal/lesser priority than station.