bibliothek.gui.dock.station
Class StackDockStation

java.lang.Object
  extended by bibliothek.gui.dock.AbstractDockable
      extended by bibliothek.gui.dock.station.AbstractDockableStation
          extended by bibliothek.gui.dock.station.StackDockStation
All Implemented Interfaces:
DockElement, Dockable, DockStation

public class StackDockStation
extends AbstractDockableStation

On this station, only one of many children is visible. The other children are hidden behind the visible child. There are some buttons where the user can choose which child is visible. This station behaves like a JTabbedPane.
This station tries to register a DockTitleFactory to its DockController with the key TITLE_ID.

Author:
Benjamin Sigg

Nested Class Summary
private  class StackDockStation.Background
          This panel is used as base of the station.
private  class StackDockStation.Insert
          The location of a gap between to tabs.
private  class StackDockStation.Listener
          This listener is added to the children of the station.
private  class StackDockStation.VisibleListener
          A listener for the parent of this station.
 
Field Summary
private  StackDockStation.Background background
          The graphical representation of this station
private  DisplayerFactoryWrapper displayerFactory
          A factory to create DockableDisplayer
private  DisplayerCollection displayers
          The set of displayers shown on this station
private  java.util.List<DockableDisplayer> dockables
          A list of all children
private  boolean draw
          Tells whether some lines have to be painted, or not
private  Dockable dropping
          The Dockable which is currently moved or dropped
private  StackDockStation.Insert insert
          The preferred location where dropping should be added
private  StackDockStation.Listener listener
          A listener observing the children for changes of their icon or titletext
private  java.util.List<javax.swing.event.MouseInputListener> mouseInputListeners
          A list of MouseInputListeners which are registered at this station.
private  StationPaintWrapper paint
          A paint to draw lines
private  javax.swing.JComponent panel
          The panel where components are added
private  MultiDockActionSource source
          The actions which are offered to the children
private  StackDockComponent stackComponent
          A Component which shows two or more children of this station
private  DockTitleVersion title
          The version of titles which should be used for this station
static java.lang.String TITLE_ID
          The id of the titlefactory which is used by this station
private  DockableVisibilityManager visibility
          A manager for firing events if a child changes its visibility-state
private  StackDockStation.VisibleListener visibleListener
          A listener added to the parent of this station.
 
Fields inherited from class bibliothek.gui.dock.station.AbstractDockableStation
listeners
 
Constructor Summary
StackDockStation()
          Constructs a new StackDockStation
StackDockStation(DockTheme theme)
          Constructs a new station and sets the theme.
 
Method Summary
 void add(Dockable dockable, int index)
          Adds a child to this station at the location index.
protected  void add(Dockable dockable, int index, boolean fire)
          Adds a child to this station at the location index.
 void addMouseInputListener(javax.swing.event.MouseInputListener listener)
          Adds a MouseInputListener to the component of this Dockable.
protected  void callDockUiUpdateTheme()
          Calls the method DockUI.DockUI.updateTheme(DockStation, DockFactory) with this as the first argument, and an appropriate factory as the second argument.
 boolean canDrag(Dockable dockable)
          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.
 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.
protected  StackDockComponent createStackDockComponent()
          Creates the StackDockComponent which will be shown on this station if the station has more then one child.
This method is called directly by the constructor.
 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.
The station should use the StationPaint of its theme to draw.
 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, StackDockProperty property)
          Adds a new child to this station, and tries to match the property as good as possible.
protected  StackDockStation.Insert exactTabIndexAt(int x, int y)
          Gets the gap which is selected when the mouse is at x/y.
 void forget()
          Tells this station that a possible drop or move on this station was canceled.
 MultiDockActionSource getActionOffers()
          Gets a list of actions which are added to all children of this station.
 java.awt.Component getComponent()
          Gets the Component which represents this Dockable.
 DisplayerFactoryWrapper getDisplayerFactory()
          Gets a DisplayerFactory which is used to create new DockableDisplayer for this station.
 DisplayerCollection getDisplayers()
          Gets the 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.
 java.lang.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.
 StationPaintWrapper getPaint()
          Gets a StationPaint which is used to paint some lines onto this station.
 StackDockComponent getStackComponent()
          Gets the currently used StackDockComponent
 int indexOf(Dockable dockable)
          Gets the index of a child.
<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.
 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.
 void read(java.util.Map<java.lang.Integer,Dockable> children, boolean ignore, java.io.DataInputStream in)
          Removes all children from this station and then reads its new layout from in.
 void remove(int index)
          Removes the child of location index.
private  void remove(int index, boolean fire)
          Removes the child of location index.
 void removeMouseInputListener(javax.swing.event.MouseInputListener listener)
          Removes a listener that was earlier added to this Dockable.
 void replace(Dockable old, Dockable next)
          Replaces the child old by next which is not yet a child of this station.
 void setController(DockController controller)
          Sets the controller in whose realm this Dockable is.
 void setDockParent(DockStation station)
          Sets the parent property.
 void setFrontDockable(Dockable dockable)
          Sets the most important child.
 void setStackComponent(StackDockComponent stackComponent)
          Sets the StackDockComponent which should be used by this station.
protected  StackDockStation.Insert tabIndexAt(int x, int y)
          Tells which gap (between tabs) is chosen if the mouse has the coordinates x/y.
 void write(java.util.Map<Dockable,java.lang.Integer> children, java.io.DataOutputStream out)
          Writes the layout of this station into out.
 
Methods inherited from class bibliothek.gui.dock.station.AbstractDockableStation
accept, addDockStationListener, asDockStation, canCompare, changed, compare, getDirectActionOffers, getDockTitle, getIndirectActionOffers, getStationBounds, getTheme, removeDockStationListener, updateTheme
 
Methods inherited from class bibliothek.gui.dock.AbstractDockable
accept, accept, addDockableListener, asDockable, bind, fireTitleBinded, fireTitleIconChanged, fireTitleTextChanged, fireTitleUnbinded, getController, getDockParent, getTitleIcon, getTitleText, listBindedTitles, removeDockableListener, setActionOffers, setTitleIcon, setTitleText, unbind
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface bibliothek.gui.DockStation
getController
 
Methods inherited from interface bibliothek.gui.dock.DockElement
asDockable
 

Field Detail

TITLE_ID

public static final java.lang.String TITLE_ID
The id of the titlefactory which is used by this station

See Also:
Constant Field Values

dockables

private java.util.List<DockableDisplayer> dockables
A list of all children


mouseInputListeners

private java.util.List<javax.swing.event.MouseInputListener> mouseInputListeners
A list of MouseInputListeners which are registered at this station.


visibility

private DockableVisibilityManager visibility
A manager for firing events if a child changes its visibility-state


paint

private StationPaintWrapper paint
A paint to draw lines


displayerFactory

private DisplayerFactoryWrapper displayerFactory
A factory to create DockableDisplayer


displayers

private DisplayerCollection displayers
The set of displayers shown on this station


dropping

private Dockable dropping
The Dockable which is currently moved or dropped


draw

private boolean draw
Tells whether some lines have to be painted, or not


insert

private StackDockStation.Insert insert
The preferred location where dropping should be added


background

private StackDockStation.Background background
The graphical representation of this station


panel

private javax.swing.JComponent panel
The panel where components are added


stackComponent

private StackDockComponent stackComponent
A Component which shows two or more children of this station


title

private DockTitleVersion title
The version of titles which should be used for this station


listener

private StackDockStation.Listener listener
A listener observing the children for changes of their icon or titletext


source

private MultiDockActionSource source
The actions which are offered to the children


visibleListener

private StackDockStation.VisibleListener visibleListener
A listener added to the parent of this station. The listener ensures that the visibility-state is always correct.

Constructor Detail

StackDockStation

public StackDockStation()
Constructs a new StackDockStation


StackDockStation

public StackDockStation(DockTheme theme)
Constructs a new station and sets the theme.

Parameters:
theme - the theme of the station, may be null
Method Detail

createStackDockComponent

protected StackDockComponent createStackDockComponent()
Creates the StackDockComponent which will be shown on this station if the station has more then one child.
This method is called directly by the constructor.

Returns:
the new component

setStackComponent

public void setStackComponent(StackDockComponent stackComponent)
Sets the StackDockComponent which should be used by this station. The component is shown when this station has more then one child.

Parameters:
stackComponent - the new component
Throws:
java.lang.IllegalArgumentException - if stackComponent is null

getStackComponent

public StackDockComponent getStackComponent()
Gets the currently used StackDockComponent

Returns:
the component
See Also:
setStackComponent(StackDockComponent)

callDockUiUpdateTheme

protected void callDockUiUpdateTheme()
                              throws java.io.IOException
Description copied from class: AbstractDockableStation
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 AbstractDockableStation
Throws:
java.io.IOException - if the DockUI throws an exception

setDockParent

public void setDockParent(DockStation station)
Description copied from interface: Dockable
Sets the parent property. This Dockable is shown as direct child of station.

Specified by:
setDockParent in interface Dockable
Overrides:
setDockParent in class AbstractDockable
Parameters:
station - the parent, may be null if this Dockable is not visible at all.

setController

public void setController(DockController controller)
Description copied from interface: Dockable
Sets the controller in whose realm this Dockable is. A value of null means that this Dockable is not managed by a controller.

Specified by:
setController in interface Dockable
Specified by:
setController in interface DockStation
Overrides:
setController in class AbstractDockable
Parameters:
controller - the owner, may be null

getPaint

public StationPaintWrapper getPaint()
Gets a StationPaint which is used to paint some lines onto this station. Use a delegate to exchange the paint.

Returns:
the paint

getDisplayerFactory

public DisplayerFactoryWrapper getDisplayerFactory()
Gets a DisplayerFactory which is used to create new DockableDisplayer for this station. Use a delegate to exchange the factory.

Returns:
the factory

getDisplayers

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

Returns:
the set of displayers

isStationVisible

public boolean isStationVisible()
Description copied from interface: DockStation
Tells whether this station is visible or not. For example a station on a JFrame is not visible if the frame is minimized.

Specified by:
isStationVisible in interface DockStation
Overrides:
isStationVisible in class AbstractDockableStation
Returns:
whether this station is visible

isVisible

public boolean isVisible(Dockable dockable)
Description copied from interface: DockStation
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 method is not visible.

Specified by:
isVisible in interface DockStation
Overrides:
isVisible in class AbstractDockableStation
Parameters:
dockable - the child whose visibility-state is questioned
Returns:
whether dockable is visible or not
See Also:
DockStation.isStationVisible()

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

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)

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.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()

getActionOffers

public MultiDockActionSource getActionOffers()
Gets a list of actions which are added to all children of this station. The station never changes this source, so it's possible to add some DockActions to the result of this method, and these actions will be added to all children.

Specified by:
getActionOffers in interface Dockable
Overrides:
getActionOffers in class AbstractDockable
Returns:
a source which is changeable by the client

indexOf

public int indexOf(Dockable dockable)
Gets the index of a child.

Parameters:
dockable - the child which is searched
Returns:
the index of dockable or -1 if it was not found

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.

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

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,
                    StackDockProperty property)
Adds a new child to this station, and tries to match the property as good as possible.

Parameters:
dockable - the new child
property - the preferred location of the child
Returns:
true if the child could be added, false if the child couldn't be added

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.


tabIndexAt

protected StackDockStation.Insert tabIndexAt(int x,
                                             int y)
Tells which gap (between tabs) is chosen if the mouse has the coordinates x/y. If there is no tab at this location, a default-tab is chosen.

Parameters:
x - x-coordinate in the system of this station
y - y-coordinate in the system of this station
Returns:
the location of a tab

exactTabIndexAt

protected StackDockStation.Insert exactTabIndexAt(int x,
                                                  int y)
Gets the gap which is selected when the mouse is at x/y.

Parameters:
x - x-coordinate in the system of this station
y - y-coordinate in the system of this station
Returns:
the location of a tab or null if no tab is under x/y

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

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 old,
                    Dockable next)
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:
old - a child
next - the replacement of next

add

public void add(Dockable dockable,
                int index)
Adds a child to this station at the location index.

Parameters:
dockable - the new child
index - the preferred location of the new child

add

protected void add(Dockable dockable,
                   int index,
                   boolean fire)
Adds a child to this station at the location index.

Parameters:
dockable - the new child
index - the preferred location of the new child
fire - if true the method will fire some events, otherwise the method will run silent

remove

public void remove(int index)
Removes the child of location index.

Parameters:
index - the location of the child which will be removed

remove

private void remove(int index,
                    boolean fire)
Removes the child of location index.

Parameters:
index - the location of the child which will be removed
fire - true if the method should fire some events, false if the method should run silently

getComponent

public java.awt.Component getComponent()
Description copied from interface: Dockable
Gets the Component which represents this Dockable. Note that the component should be a focus cycle root

Returns:
the visible representation

addMouseInputListener

public void addMouseInputListener(javax.swing.event.MouseInputListener listener)
Description copied from interface: Dockable
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.

Specified by:
addMouseInputListener in interface Dockable
Overrides:
addMouseInputListener in class AbstractDockable
Parameters:
listener - the mouse listener

removeMouseInputListener

public void removeMouseInputListener(javax.swing.event.MouseInputListener listener)
Description copied from interface: Dockable
Removes a listener that was earlier added to this Dockable.

Specified by:
removeMouseInputListener in interface Dockable
Overrides:
removeMouseInputListener in class AbstractDockable
Parameters:
listener - The listener to remove

getFactoryID

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

write

public void write(java.util.Map<Dockable,java.lang.Integer> children,
                  java.io.DataOutputStream out)
           throws java.io.IOException
Writes the layout of this station into out.

Parameters:
children - A map that tells for every child of this station a unique id.
out - The sink of the information
Throws:
java.io.IOException - if out throws an exception

read

public void read(java.util.Map<java.lang.Integer,Dockable> children,
                 boolean ignore,
                 java.io.DataInputStream in)
          throws java.io.IOException
Removes all children from this station and then reads its new layout from in.

Parameters:
children - A map that tells for some ids which Dockable should be added
ignore - true if the children on this station should not be changed
in - The source of all information
Throws:
java.io.IOException - if in throws an exception