bibliothek.gui
Class DockController

java.lang.Object
  extended by bibliothek.gui.DockController
Direct Known Subclasses:
SecureDockController

public class DockController
extends java.lang.Object

A controller is needed to drag and drop dockables from one DockStation to another station.
In order to use a station, it must be added to a controller. Stations which are children of other stations will be added automatically. Dockables can only be dragged and dropped from stations with the same controller.
Note: if a controller is no longer in use, the method kill() should be called to free some resources.

Author:
Benjamin Sigg

Nested Class Summary
private  class DockController.TitleListener
          Observers this controller and registers listeners to all new titles.
 
Field Summary
private  MultiDockAcceptance acceptance
          behavior which dockable can be dropped over which station
private  java.util.List<ActionOffer> actionOffers
          A list of sources for a DockActionSource
private  ActionViewConverter actionViewConverter
          A converter used to transform actions into views
private  java.util.Map<DockTitle,Dockable> activeTitles
          mapping tells which titles are currently active
private  ActionOffer defaultActionOffer
          The default source for a DockActionSource
private  DockTitleManager dockTitles
          a source for DockTitle
private  Dockable focusedDockable
          the Dockable which has currently the focus, can be null
private  MouseFocusObserver focusObserver
          a special controller listening to AWT-events and changing the focused dockable
private  java.util.List<ActionGuard> guards
          A list of sources for DockActionSources
private  IconManager icons
          the set of icons used with this controller
private  java.util.List<DockControllerListener> listeners
          observer of this controller
private  boolean onFocusing
          true while the controller actively changes the focus
private  ActionPopupSuppressor popupSuppressor
          tells which popups are to be shown
private  DockProperties properties
          a set of properties
private  DockRegister register
          the known dockables and DockStations
private  DockRelocator relocator
          a manager handling drag and drop
private  SingleParentRemover remover
          remover of stations with none or one child
private  boolean singleParentRemove
          whether stations with none or one child will be removed
private  DockTheme theme
          a theme describing the look of the stations
private  DockController.TitleListener titleListener
          an observer of the DockTitle
 
Constructor Summary
  DockController()
          Creates a new controller.
protected DockController(boolean initiate)
          Creates a new controller but does not initiate the properties of this controller if not wished.
 
Method Summary
 void add(DockStation station)
          Adds a station to this controller.
 void addAcceptance(DockAcceptance acceptance)
          Adds a rule that decides which station can have which children.
 void addActionGuard(ActionGuard guard)
          Adds guard to this controller.
 void addActionOffer(ActionOffer offer)
          Adds a factory for a DockActionSource.
 void addDockControllerListener(DockControllerListener listener)
          Adds an observer to this controller.
protected  ActionViewConverter createActionViewConverter()
          Creates the converter that will transform actions into views.
protected  ActionOffer createDefaultActionOffer()
          Creates the default action offer.
protected  DockRegisterListener createFocusController()
          Creates a listener which will observe all stations to ensure that the focused Dockable is always visible.
protected  MouseFocusObserver createMouseFocusObserver()
          Creates the focus-controller of this controller.
protected  DockRegisterListener createPopupController()
          Creates a listener which will open a popup-menu for each title or dockable known to this controller.
protected  DockRegister createRegister()
          Creates a new register for this controller.
protected  DockRelocator createRelocator()
          Creates a new relocator for this controller.
protected  SingleParentRemover createSingleParentRemover()
          Creates a SingleParentRemover that will be used to remove some stations from this controller.
 void ensureFocusSet()
          Ensures that a title or a Component of the currently focused Dockable really has the focus.
protected  void firedockableFocused(Dockable dockable)
          Informs all listeners that dockable has gained the focus.
protected  void fireTitleBinded(DockTitle title, Dockable dockable)
          Informs all listeners that title has been binded to dockable.
protected  void fireTitleUnbinded(DockTitle title, Dockable dockable)
          Informs all listeners that title is no longer binded to dockable.
 MultiDockAcceptance getAcceptance()
          Gets the behavior that tells which stations can have which children.
 ActionViewConverter getActionViewConverter()
          Gets the current ActionViewConverter.
 ActionOffer getDefaultActionOffer()
          Gets the factory for a DockActionSource which is used if no other offer was interested in a Dockable.
 DockTitleManager getDockTitleManager()
          Gets the manager of all titles on this controller
 Dockable getFocusedDockable()
          Gets the Dockable which is currently focused.
 MouseFocusObserver getFocusObserver()
          Gets the current focus-controller
 IconManager getIcons()
          Gets the set of icons which are used by this controller.
 ActionPopupSuppressor getPopupSuppressor()
          Gets the guard which decides, which popups should be allowed.
 DockProperties getProperties()
          A set of properties that can be used at any place.
 DockRegister getRegister()
          Gets the set of Dockables and DockStations known to this controller.
 DockRelocator getRelocator()
          Gets the manager for handling drag and drop operations.
 DockStation getStation(int index)
          Gets the station at the specified position.
 int getStationCount()
          Gest the number of stations registered at this controller.
 DockTheme getTheme()
          Gets the current theme of this controller.
protected  void initiate()
          Initializes all properties of this controller.
 boolean isBinded(DockTitle title)
          Tells whether title is binded to its dockable or not.
 boolean isFocused(Dockable dockable)
          Tells whether dockable or one of its children has currently the focus.
 boolean isOnFocusing()
          Tells whether one of the methods which change the focus is currently running, or not.
 boolean isSingleParentRemove()
          Tells whether stations with only one child are removed or not.
 void kill()
          Removes listeners and frees resources.
protected  DockControllerListener[] listDockControllerListener()
          Lists all DockControllerListener of this station.
 DockActionSource listOffers(Dockable dockable)
          Creates a list of DockActions which can affect Dockable.
 void rebindTitles(Dockable dockable, java.util.Set<DockTitle> check)
          Checks all titles of dockable and its children.
 void remove(DockStation station)
          Removes a station which was managed by this controller.
 void removeAcceptance(DockAcceptance acceptance)
          Removes a that decided which station could have which children.
 void removeActionGuard(ActionGuard guard)
          Removes guard from this controller.
 void removeActionOffer(ActionOffer offer)
          Removes an earlier added offer.
 void removeDockControllerListener(DockControllerListener listener)
          Removes an observer from this controller.
 void setAtLeastFocusedDockable(Dockable focusedDockable)
          Sets the focused Dockable.
 void setDefaultActionOffer(ActionOffer defaultActionOffer)
          Sets the factory for a DockActionSource which is used if no other offer was interested in a Dockable.
 void setFocusedDockable(Dockable focusedDockable, boolean force)
          Sets the Dockable which should have the focus.
 void setFocusedDockable(Dockable focusedDockable, boolean force, boolean ensureFocusSet)
          Sets the Dockable which should have the focus.
 void setPopupSuppressor(ActionPopupSuppressor popupSuppressor)
          Sets the guard which decides, which popups with DockActions are allowed to show up, and which popups will be suppressed.
 void setSingleParentRemove(boolean remove)
          Sets whether stations with one or none child are removed automatically or not.
 void setTheme(DockTheme theme)
          Sets the theme of this controller.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

register

private DockRegister register
the known dockables and DockStations


relocator

private DockRelocator relocator
a manager handling drag and drop


focusedDockable

private Dockable focusedDockable
the Dockable which has currently the focus, can be null


listeners

private java.util.List<DockControllerListener> listeners
observer of this controller


onFocusing

private boolean onFocusing
true while the controller actively changes the focus


focusObserver

private MouseFocusObserver focusObserver
a special controller listening to AWT-events and changing the focused dockable


titleListener

private DockController.TitleListener titleListener
an observer of the DockTitle


activeTitles

private java.util.Map<DockTitle,Dockable> activeTitles
mapping tells which titles are currently active


dockTitles

private DockTitleManager dockTitles
a source for DockTitle


icons

private IconManager icons
the set of icons used with this controller


actionOffers

private java.util.List<ActionOffer> actionOffers
A list of sources for a DockActionSource


guards

private java.util.List<ActionGuard> guards
A list of sources for DockActionSources


defaultActionOffer

private ActionOffer defaultActionOffer
The default source for a DockActionSource


actionViewConverter

private ActionViewConverter actionViewConverter
A converter used to transform actions into views


acceptance

private MultiDockAcceptance acceptance
behavior which dockable can be dropped over which station


popupSuppressor

private ActionPopupSuppressor popupSuppressor
tells which popups are to be shown


singleParentRemove

private boolean singleParentRemove
whether stations with none or one child will be removed


remover

private SingleParentRemover remover
remover of stations with none or one child


theme

private DockTheme theme
a theme describing the look of the stations


properties

private DockProperties properties
a set of properties

Constructor Detail

DockController

public DockController()
Creates a new controller.


DockController

protected DockController(boolean initiate)
Creates a new controller but does not initiate the properties of this controller if not wished. Clients should call the method initiate() if the pass false to this constructor. Otherwise the behavior of this controller is unspecified.

Parameters:
initiate - true if all properties should be initiated
Method Detail

initiate

protected final void initiate()
Initializes all properties of this controller. This method should be called only once. This method can be called by a subclass if the subclass used DockController(boolean) with an argument false.

See Also:
createRegister(), createRelocator(), createDefaultActionOffer(), createMouseFocusObserver(), createActionViewConverter(), createFocusController(), createPopupController()

kill

public void kill()
Removes listeners and frees resources. This method should be called if this controller is no longer needed.


createRegister

protected DockRegister createRegister()
Creates a new register for this controller.

Returns:
the new register

createRelocator

protected DockRelocator createRelocator()
Creates a new relocator for this controller.

Returns:
the relocator

createFocusController

protected DockRegisterListener createFocusController()
Creates a listener which will observe all stations to ensure that the focused Dockable is always visible.

Returns:
the listener or null

createPopupController

protected DockRegisterListener createPopupController()
Creates a listener which will open a popup-menu for each title or dockable known to this controller.

Returns:
the new listener or null

createMouseFocusObserver

protected MouseFocusObserver createMouseFocusObserver()
Creates the focus-controller of this controller.

Returns:
the controller, not null

getFocusObserver

public MouseFocusObserver getFocusObserver()
Gets the current focus-controller

Returns:
the controller

getRegister

public DockRegister getRegister()
Gets the set of Dockables and DockStations known to this controller.

Returns:
the set of elements

getRelocator

public DockRelocator getRelocator()
Gets the manager for handling drag and drop operations.

Returns:
the manager

createActionViewConverter

protected ActionViewConverter createActionViewConverter()
Creates the converter that will transform actions into views.

Returns:
the new converter.

getActionViewConverter

public ActionViewConverter getActionViewConverter()
Gets the current ActionViewConverter.

Returns:
the converter

createDefaultActionOffer

protected ActionOffer createDefaultActionOffer()
Creates the default action offer. This ActionOffer will be used if no other offer was interested in a Dockable.

Returns:
the offer, must not be null

isSingleParentRemove

public boolean isSingleParentRemove()
Tells whether stations with only one child are removed or not.

Returns:
true if stations with one or less children are removed automatically
See Also:
setSingleParentRemove(boolean)

setSingleParentRemove

public void setSingleParentRemove(boolean remove)
Sets whether stations with one or none child are removed automatically or not. This property has a great effect on some stations, clients shouldn't change the value once the first station is added.

Parameters:
remove - true if stations with one or less children are removed
See Also:
createSingleParentRemover()

createSingleParentRemover

protected SingleParentRemover createSingleParentRemover()
Creates a SingleParentRemover that will be used to remove some stations from this controller.

Returns:
The remover
See Also:
setSingleParentRemove(boolean)

getAcceptance

public MultiDockAcceptance getAcceptance()
Gets the behavior that tells which stations can have which children.

Returns:
the behavior
See Also:
addAcceptance(DockAcceptance), removeAcceptance(DockAcceptance)

addAcceptance

public void addAcceptance(DockAcceptance acceptance)
Adds a rule that decides which station can have which children. The acceptance does not override the accept-methods of Dockable and DockStation.

Parameters:
acceptance - the additional rule

removeAcceptance

public void removeAcceptance(DockAcceptance acceptance)
Removes a that decided which station could have which children.

Parameters:
acceptance - the rule to remove

getPopupSuppressor

public ActionPopupSuppressor getPopupSuppressor()
Gets the guard which decides, which popups should be allowed.

Returns:
the guard
See Also:
setPopupSuppressor(ActionPopupSuppressor)

setPopupSuppressor

public void setPopupSuppressor(ActionPopupSuppressor popupSuppressor)
Sets the guard which decides, which popups with DockActions are allowed to show up, and which popups will be suppressed.

Parameters:
popupSuppressor - the guard

getDefaultActionOffer

public ActionOffer getDefaultActionOffer()
Gets the factory for a DockActionSource which is used if no other offer was interested in a Dockable.

Returns:
the default offer

setDefaultActionOffer

public void setDefaultActionOffer(ActionOffer defaultActionOffer)
Sets the factory for a DockActionSource which is used if no other offer was interested in a Dockable.

Parameters:
defaultActionOffer - the offer, not null

addActionOffer

public void addActionOffer(ActionOffer offer)
Adds a factory for a DockActionSource. The factory will create a source if it is the first offer which is interested in a Dockable.

Parameters:
offer - the algorithm

removeActionOffer

public void removeActionOffer(ActionOffer offer)
Removes an earlier added offer.

Parameters:
offer - the factory to remove

setTheme

public void setTheme(DockTheme theme)
Sets the theme of this controller. This method ensures that all registered stations know also the new theme.

Parameters:
theme - the new theme

getTheme

public DockTheme getTheme()
Gets the current theme of this controller.

Returns:
the theme

getProperties

public DockProperties getProperties()
A set of properties that can be used at any place.

Returns:
the set of properties

add

public void add(DockStation station)
Adds a station to this controller. The controller allows the user to drag and drop children from and to station. If the children of station are stations itself, then they will be added automatically

Parameters:
station - the new station

remove

public void remove(DockStation station)
Removes a station which was managed by this controller.

Parameters:
station - the station to remove

getStationCount

public int getStationCount()
Gest the number of stations registered at this controller.

Returns:
the number of stations
See Also:
add(DockStation)

getStation

public DockStation getStation(int index)
Gets the station at the specified position.

Parameters:
index - the location
Returns:
the station

rebindTitles

public void rebindTitles(Dockable dockable,
                         java.util.Set<DockTitle> check)
Checks all titles of dockable and its children. If a title is also in the set check, than its unbind and bind-methods are called.
This action ensures that the titles have the correct DockActionSource. This method must only be called if the normal register/unregister mechanism is disabled. This case happens only if a Dockable is dragged.

Parameters:
dockable - the Dockable whose titles and whose children's titles will be rebinded
check - the set of titles which might be rebinded

isOnFocusing

public boolean isOnFocusing()
Tells whether one of the methods which change the focus is currently running, or not. If the result is true, none should change the focus.

Returns:
true if the focus is currently changing

setAtLeastFocusedDockable

public void setAtLeastFocusedDockable(Dockable focusedDockable)
Sets the focused Dockable. If focusedDockable is a station and one of its children has the focus, then nothing will happen.

Parameters:
focusedDockable - the element which should have the focus
See Also:
isOnFocusing()

setFocusedDockable

public void setFocusedDockable(Dockable focusedDockable,
                               boolean force)
Sets the Dockable which should have the focus.

Parameters:
focusedDockable - the element with the focus or null
force - true if this controller must ensure that all properties are correct, false if some optimations are allowed. Clients normally can set this argument to false.

setFocusedDockable

public void setFocusedDockable(Dockable focusedDockable,
                               boolean force,
                               boolean ensureFocusSet)
Sets the Dockable which should have the focus.

Parameters:
focusedDockable - the element with the focus or null
force - true if this controller must ensure that all properties are correct, false if some optimations are allowed. Clients normally can set this argument to false.
ensureFocusSet - whether to ensure that the focus is set correctly or not.

isFocused

public boolean isFocused(Dockable dockable)
Tells whether dockable or one of its children has currently the focus.

Parameters:
dockable - the element which may have the focus
Returns:
true if dockable or one of its children is focused

isBinded

public boolean isBinded(DockTitle title)
Tells whether title is binded to its dockable or not. The behavior is unspecified if the dockable of title is unknown to this controller.

Parameters:
title - the title which might be binded
Returns:
true if the title is binded

ensureFocusSet

public void ensureFocusSet()
Ensures that a title or a Component of the currently focused Dockable really has the focus.


getFocusedDockable

public Dockable getFocusedDockable()
Gets the Dockable which is currently focused.

Returns:
the focused element or null

getDockTitleManager

public DockTitleManager getDockTitleManager()
Gets the manager of all titles on this controller

Returns:
the manager

getIcons

public IconManager getIcons()
Gets the set of icons which are used by this controller.

Returns:
the set of icons

addActionGuard

public void addActionGuard(ActionGuard guard)
Adds guard to this controller. The new ActionGuard has no influence on DockActionSources which are already created.

Parameters:
guard - the new guard

removeActionGuard

public void removeActionGuard(ActionGuard guard)
Removes guard from this controller.

Parameters:
guard - the element to remove

listOffers

public DockActionSource listOffers(Dockable dockable)
Creates a list of DockActions which can affect Dockable.

Parameters:
dockable - a Dockable whose actions are demanded
Returns:
a list of actions

addDockControllerListener

public void addDockControllerListener(DockControllerListener listener)
Adds an observer to this controller.

Parameters:
listener - the observer

removeDockControllerListener

public void removeDockControllerListener(DockControllerListener listener)
Removes an observer from this controller.

Parameters:
listener - the observer to remove

listDockControllerListener

protected DockControllerListener[] listDockControllerListener()
Lists all DockControllerListener of this station. The list is independent from the original list.

Returns:
the list of listeners

fireTitleBinded

protected void fireTitleBinded(DockTitle title,
                               Dockable dockable)
Informs all listeners that title has been binded to dockable.

Parameters:
title - the binded title
dockable - the owner of title

fireTitleUnbinded

protected void fireTitleUnbinded(DockTitle title,
                                 Dockable dockable)
Informs all listeners that title is no longer binded to dockable.

Parameters:
title - the unbinded title
dockable - the former owner of title

firedockableFocused

protected void firedockableFocused(Dockable dockable)
Informs all listeners that dockable has gained the focus.

Parameters:
dockable - the owner of the focus, may be null