bibliothek.gui
Class DockController

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

public class DockController
extends 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

Constructor Summary
DockController()
          Creates a new controller.
DockController(DockControllerFactory factory)
          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 addDockableFocusListener(DockableFocusListener listener)
          Adds a listener to this controller, the listener will be informed when the focused Dockable changes.
 void addDockTitleBindingListener(DockTitleBindingListener listener)
          Adds a listener to this controller, the listener will receive events when a DockTitle is bound or unbound.
 void addUIListener(UIListener listener)
          Adds an UIListener to this controller, the listener gets notified when the graphical user interface needs an update because the LookAndFeel changed.
protected  DockableFocusListener[] dockableFocusListeners()
          Gets an array of currently registered DockableFocusListeners.
protected  DockTitleBindingListener[] dockTitleBindingListeners()
          Gets an array of all DockTitleBindingListener that are currently registered at 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 fireDockableSelected(DockStation station, Dockable dockable)
          Informs all listeners that dockable has been selected by station.
protected  void fireTitleBound(DockTitle title, Dockable dockable)
          Informs all listeners that title has been bound to dockable.
protected  void fireTitleUnbound(DockTitle title, Dockable dockable)
          Informs all listeners that title is no longer bound to dockable.
 MultiDockAcceptance getAcceptance()
          Gets the behavior that tells which stations can have which children.
 ActionViewConverter getActionViewConverter()
          Gets the current ActionViewConverter.
 ColorManager getColors()
          Gets the map of colors which are used by this controller.
 ComponentHierarchyObserver getComponentHierarchyObserver()
          Gets a list of all Components which are used on the Dockables known to this controller.
 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
 DoubleClickController getDoubleClickController()
          Gets the manager for handling global double clicks of the mouse.
 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.
 KeyboardController getKeyboardController()
          Gets the manager that handles all global KeyEvents.
 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.
 SingleParentRemover getSingleParentRemover()
          Gets the handler used to remove stations with only one or none children.
 DockStation getStation(int index)
          Gets the station at the specified position.
 int getStationCount()
          Gets the number of stations registered at this controller.
 DockTheme getTheme()
          Gets the current theme of this controller.
protected  void initiate(DockControllerFactory factory, ControllerSetupCollection setup)
          Initializes all properties of this controller.
 boolean isBound(DockTitle title)
          Tells whether title is bound 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.
 void kill()
          Removes listeners and frees resources.
 DockActionSource listOffers(Dockable dockable)
          Creates a list of DockActions which can affect Dockable.
Clients might rather use Dockable.getGlobalActionOffers() to get a list of actions for a specific Dockable.
 void putRepresentative(Component component, DockElement element)
          Tells this controller that component somehow represents element, and that events on component belong to element.
 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 removeDockableFocusListener(DockableFocusListener listener)
          Removes a listener from this controller.
 void removeDockTitleBindingListener(DockTitleBindingListener listener)
          Removes the observer listener from this controller.
 void removeUIListener(UIListener listener)
          Removes a listener from this controller.
 DockElement searchElement(Component representative)
          Searches the element which is parent or equal to representative.
 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 setSingleParentRemover(SingleParentRemover remover)
          Exchanges the handler that removes stations with only one or none children.
 void setTheme(DockTheme theme)
          Sets the theme of this controller.
 void updateUI()
          Informs all registered UIListeners that the user interface needs an update because the LookAndFeel changed.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DockController

public DockController()
Creates a new controller.


DockController

public DockController(DockControllerFactory factory)
Creates a new controller but does not initiate the properties of this controller if not wished. Clients should call the method initiate(DockControllerFactory,ControllerSetupCollection) if they pass null to this constructor. Otherwise the behavior of this controller is unspecified.

Parameters:
factory - the factory creating elements of this controller or null if initiate(DockControllerFactory,ControllerSetupCollection) will be called later
Method Detail

initiate

protected final void initiate(DockControllerFactory factory,
                              ControllerSetupCollection setup)
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(DockControllerFactory) with an argument null.

Parameters:
factory - a factory used to create various sub-controls
setup - the collection of ControllerSetupListeners that will be invoked when setup is finished. If this parameter is set, then all ControllerSetupListeners will be added to setup. If this parameter is null, then a new collection will be created, and the event will be fired as soon as this method is finished.

kill

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


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

getComponentHierarchyObserver

public ComponentHierarchyObserver getComponentHierarchyObserver()
Gets a list of all Components which are used on the Dockables known to this controller.

Returns:
the list of Components.

getRelocator

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

Returns:
the manager

getDoubleClickController

public DoubleClickController getDoubleClickController()
Gets the manager for handling global double clicks of the mouse.

Returns:
the manager

getKeyboardController

public KeyboardController getKeyboardController()
Gets the manager that handles all global KeyEvents.

Returns:
the handler

getActionViewConverter

public ActionViewConverter getActionViewConverter()
Gets the current ActionViewConverter.

Returns:
the converter

getSingleParentRemover

public SingleParentRemover getSingleParentRemover()
Gets the handler used to remove stations with only one or none children.

Returns:
the handler or null.
See Also:
setSingleParentRemover(SingleParentRemover)

setSingleParentRemover

public void setSingleParentRemover(SingleParentRemover remover)
Exchanges the handler that removes stations with only one or none children.

Parameters:
remover - the new handler, can be null to disable the feature.

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

putRepresentative

public void putRepresentative(Component component,
                              DockElement element)
Tells this controller that component somehow represents element, and that events on component belong to element.

Parameters:
component - the representative
element - some element or null

searchElement

public DockElement searchElement(Component representative)
Searches the element which is parent or equal to representative. This method also searches all DockTitles and all Components given by putRepresentative(Component, DockElement).

Parameters:
representative - some component
Returns:
the parent or null

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

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

isBound

public boolean isBound(DockTitle title)
Tells whether title is bound 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 bound
Returns:
true if the title is bound

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

getColors

public ColorManager getColors()
Gets the map of colors which are used by this controller.

Returns:
the map of colors

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.
Clients might rather use Dockable.getGlobalActionOffers() to get a list of actions for a specific Dockable. This method only uses the local information to compute a new source.

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

addDockTitleBindingListener

public void addDockTitleBindingListener(DockTitleBindingListener listener)
Adds a listener to this controller, the listener will receive events when a DockTitle is bound or unbound.

Parameters:
listener - the new listener

removeDockTitleBindingListener

public void removeDockTitleBindingListener(DockTitleBindingListener listener)
Removes the observer listener from this controller.

Parameters:
listener - the listener to remove

dockTitleBindingListeners

protected DockTitleBindingListener[] dockTitleBindingListeners()
Gets an array of all DockTitleBindingListener that are currently registered at this controller.

Returns:
the modifiable array

addDockableFocusListener

public void addDockableFocusListener(DockableFocusListener listener)
Adds a listener to this controller, the listener will be informed when the focused Dockable changes.

Parameters:
listener - the new listener

removeDockableFocusListener

public void removeDockableFocusListener(DockableFocusListener listener)
Removes a listener from this controller.

Parameters:
listener - the listener to remove

dockableFocusListeners

protected DockableFocusListener[] dockableFocusListeners()
Gets an array of currently registered DockableFocusListeners.

Returns:
the modifiable array

fireTitleBound

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

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

fireTitleUnbound

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

Parameters:
title - the unbound 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

fireDockableSelected

protected void fireDockableSelected(DockStation station,
                                    Dockable dockable)
Informs all listeners that dockable has been selected by station.

Parameters:
station - some DockStation
dockable - the selected element of station

addUIListener

public void addUIListener(UIListener listener)
Adds an UIListener to this controller, the listener gets notified when the graphical user interface needs an update because the LookAndFeel changed.

Parameters:
listener - the new listener

removeUIListener

public void removeUIListener(UIListener listener)
Removes a listener from this controller.

Parameters:
listener - the listener to remove

updateUI

public void updateUI()
Informs all registered UIListeners that the user interface needs an update because the LookAndFeel changed.

See Also:
addUIListener(UIListener), removeUIListener(UIListener)