bibliothek.gui.dock.dockable
Class AbstractDockable

java.lang.Object
  extended by bibliothek.gui.dock.dockable.AbstractDockable
All Implemented Interfaces:
DockElement, DockElementRepresentative, PlaceholderListItem, Dockable
Direct Known Subclasses:
AbstractDockableStation, DefaultDockable

public abstract class AbstractDockable
extends Object
implements Dockable

An implementation of Dockable which deals with the simple things.
Some of the capabilities of an AbstractDockable are:

  • Author:
    Benjamin Sigg

    Constructor Summary
    protected AbstractDockable(PropertyKey<Icon> titleIcon, PropertyKey<String> titleText, PropertyKey<String> titleTooltip)
              Creates a new dockable.
     
    Method Summary
     boolean accept(DockStation station)
              Tells whether station is an accepted parent for this Dockable or not.
     boolean accept(DockStation base, Dockable neighbour)
              Tells whether base could be the parent of a combination between this Dockable and neighbor.
     void addDockableListener(DockableListener listener)
              Adds a listener to this Dockable.
     void addDockHierarchyListener(DockHierarchyListener listener)
              Adds a hierarchy-listener to this Dockable.
     void addKeyListener(KeyListener listener)
              Adds a KeyListener to this Dockable.
     void addMouseInputListener(MouseInputListener listener)
              Adds a MouseInputListener to the component of this Dockable.
     Dockable asDockable()
              Returns this if this is an instance of Dockable.
     void bind(DockTitle title)
              Called by clients which want to show a title of this Dockable.
     void configureDisplayerHints(DockableDisplayerHints hints)
              Orders this Dockable to configure hints which will be used by the parent component of this element.
    protected  void fireTitleBound(DockTitle title)
              Informs all dockableListeners that title was bound to this dockable.
    protected  void fireTitleExchanged()
              Informs all DockableListeners that all bound titles and the null title are no longer considered good titles and should be replaced
    protected  void fireTitleExchanged(DockTitle title)
              Informs all DockableListeners that title is no longer considered to be a good title and should be exchanged.
    protected  void fireTitleIconChanged(Icon oldIcon, Icon newIcon)
              Calls the titleIconChanged method of all registered DockableListener.
    protected  void fireTitleTextChanged(String oldTitle, String newTitle)
              Calls the titleTextChanged method of all registered DockableListeners.
    protected  void fireTitleTooltipChanged(String oldTooltip, String newTooltip)
              Called the titleTooltipChanged method of all registered DockableListeners.
    protected  void fireTitleUnbound(DockTitle title)
              Informs all dockableListeners that title was unbound from this dockable.
    protected  DockableDisplayerHints getConfigurableDisplayerHints()
              Gets the last DockableDisplayerHints that were given to configureDisplayerHints(DockableDisplayerHints).
     DockController getController()
              Gets the current controller, the argument of the last call of Dockable.setController(DockController).
     DockStation getDockParent()
              Gets the current parent, which is the last argument of Dockable.setDockParent(DockStation).
     DockElement getElement()
              Gets the element which is represented by this.
     DockActionSource getGlobalActionOffers()
              Gets a list of all DockActions which might be triggered while this Dockable is visible.
     DockActionSource getLocalActionOffers()
              Gets a list of DockActions which should be triggerable if this Dockable is visible.
     Point getPopupLocation(Point click, boolean popupTrigger)
              Tells whether a popup menu should be opened when the user clicks at click with the mouse.
     Icon getTitleIcon()
              Gets the current icon of this Dockable.
     String getTitleText()
              Gest the current title-text of this Dockable.
     String getTitleToolTip()
              Gets a tooltip that is associated with this Dockable and that should be shown on any DockTitle.
     boolean isUsedAsTitle()
              Tells whether this DockElementRepresentative is used as title.
     DockTitle[] listBoundTitles()
              Gets a list of all DockTitles which are currently bound to this Dockable.
     void removeDockableListener(DockableListener listener)
              Removes a listener from this Dockable.
     void removeDockHierarchyListener(DockHierarchyListener listener)
              Removes a hierarchy-listener from this Dockable.
     void removeKeyListener(KeyListener listener)
              Removes listener from this element.
     void removeMouseInputListener(MouseInputListener listener)
              Removes a listener that was earlier added to this Dockable.
     void requestDockTitle(DockTitleRequest request)
              The default behavior of this method is todo nothing.
     void setActionOffers(DockActionSource source)
              Sets the action-source of this Dockable.
     void setController(DockController controller)
              Sets the controller in whose realm this Dockable is.
     void setDockParent(DockStation station)
              Sets the parent property.
     void setTitleIcon(Icon titleIcon)
              Sets the icon of this dockable.
     void setTitleText(String titleText)
              Sets the title of this dockable.
     void setTitleToolTip(String titleToolTip)
              Sets the tooltip that will be shown on any title of this dockable.
     void unbind(DockTitle title)
              Clients should call this method if a DockTitle is no longer needed.
     
    Methods inherited from class java.lang.Object
    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
     
    Methods inherited from interface bibliothek.gui.Dockable
    getComponent
     
    Methods inherited from interface bibliothek.gui.dock.DockElement
    asDockStation, getFactoryID
     

    Constructor Detail

    AbstractDockable

    protected AbstractDockable(PropertyKey<Icon> titleIcon,
                               PropertyKey<String> titleText,
                               PropertyKey<String> titleTooltip)
    Creates a new dockable.

    Parameters:
    titleIcon - the key of the icon, used to read in DockProperties
    titleText - the key of the title, used to read in DockProperties
    titleTooltip - the key of the tooltip, used to read in DockProperties
    Method Detail

    setDockParent

    public void setDockParent(DockStation station)
    Description copied from interface: Dockable
    Sets the parent property. This Dockable is shown as direct child of station.
    Note: this method has to fire a DockHierarchyEvent.
    Note: when using a DockHierarchyObserver, invoke DockHierarchyObserver.update() after the property has changed, and do not fire a DockHierarchyEvent here.

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

    getDockParent

    public DockStation getDockParent()
    Description copied from interface: Dockable
    Gets the current parent, which is the last argument of Dockable.setDockParent(DockStation).

    Specified by:
    getDockParent in interface Dockable
    Returns:
    the parent property, can be null

    asDockable

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

    Specified by:
    asDockable in interface DockElement
    Specified by:
    asDockable in interface PlaceholderListItem
    Returns:
    this or null

    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.
    Note: this method has to inform all DockHierarchyListeners about the change.
    Note: when using a DockHierarchyObserver, invoke DockHierarchyObserver.controllerChanged(DockController)

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

    getController

    public DockController getController()
    Description copied from interface: Dockable
    Gets the current controller, the argument of the last call of Dockable.setController(DockController).

    Specified by:
    getController in interface DockElement
    Specified by:
    getController in interface Dockable
    Returns:
    the controller, can be null

    addDockableListener

    public void addDockableListener(DockableListener listener)
    Description copied from interface: Dockable
    Adds a listener to this Dockable. The listener has to be informed if a property of this Dockable changes.

    Specified by:
    addDockableListener in interface Dockable
    Parameters:
    listener - the new listener

    removeDockableListener

    public void removeDockableListener(DockableListener listener)
    Description copied from interface: Dockable
    Removes a listener from this Dockable.

    Specified by:
    removeDockableListener in interface Dockable
    Parameters:
    listener - the listener to remove

    addDockHierarchyListener

    public void addDockHierarchyListener(DockHierarchyListener listener)
    Description copied from interface: Dockable
    Adds a hierarchy-listener to this Dockable. The listener has to be informed whenever the path to this Dockable has been changed.
    Subclasses might use the DockHierarchyObserver to implement this feature in an easy way. Subclasses then only have to call DockHierarchyObserver.update() whenever the parent of this Dockable changes.
    Note: when using a DockHierarchyObserver, forward the call directly to DockHierarchyObserver.addDockHierarchyListener(DockHierarchyListener)

    Specified by:
    addDockHierarchyListener in interface Dockable
    Parameters:
    listener - the new listener

    removeDockHierarchyListener

    public void removeDockHierarchyListener(DockHierarchyListener listener)
    Description copied from interface: Dockable
    Removes a hierarchy-listener from this Dockable.
    Note: when using a DockHierarchyObserver, forward the call directly to DockHierarchyObserver.removeDockHierarchyListener(DockHierarchyListener)

    Specified by:
    removeDockHierarchyListener in interface Dockable
    Parameters:
    listener - the listener to remove
    See Also:
    Dockable.addDockableListener(DockableListener)

    addMouseInputListener

    public void addMouseInputListener(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 DockElementRepresentative
    Specified by:
    addMouseInputListener in interface Dockable
    Parameters:
    listener - the mouse listener

    removeMouseInputListener

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

    Specified by:
    removeMouseInputListener in interface DockElementRepresentative
    Specified by:
    removeMouseInputListener in interface Dockable
    Parameters:
    listener - The listener to remove

    addKeyListener

    public void addKeyListener(KeyListener listener)
    Adds a KeyListener to this Dockable. The listener will be informed about any un-consumed KeyEvent that is related to this Dockable, e.g. an event that is dispatched on a DockTitle.

    Parameters:
    listener - the new listener

    removeKeyListener

    public void removeKeyListener(KeyListener listener)
    Removes listener from this element.

    Parameters:
    listener - the listener to remove

    getElement

    public DockElement getElement()
    Description copied from interface: DockElementRepresentative
    Gets the element which is represented by this. The result of this method must not change.

    Specified by:
    getElement in interface DockElementRepresentative
    Returns:
    the element, never null

    isUsedAsTitle

    public boolean isUsedAsTitle()
    Description copied from interface: DockElementRepresentative
    Tells whether this DockElementRepresentative is used as title.
    Some modules grant more rights to titles than to non-titles, i.e. a DockRelocator can allow drag & drop only for titles.
    Normally a Dockable should have only one element that is a title, so if in doubt return false.

    Specified by:
    isUsedAsTitle in interface DockElementRepresentative
    Returns:
    true if this representative should be seen as title

    accept

    public boolean accept(DockStation station)
    Description copied from interface: Dockable
    Tells whether station is an accepted parent for this Dockable or not. The user is not able to drag a Dockable to a station which is not accepted.

    Specified by:
    accept in interface Dockable
    Parameters:
    station - a possible parent
    Returns:
    whether station could be a parent or not

    accept

    public boolean accept(DockStation base,
                          Dockable neighbour)
    Description copied from interface: Dockable
    Tells whether base could be the parent of a combination between this Dockable and neighbor. The user is not able to make a combination between this Dockable and neighbor if this method does not accept the operation.

    Specified by:
    accept in interface Dockable
    Parameters:
    base - the future parent of the combination
    neighbour - a Dockable whose parent will be the same parent as the parent of this Dockable
    Returns:
    true if the combination is allowed, false otherwise

    getTitleText

    public String getTitleText()
    Description copied from interface: Dockable
    Gest the current title-text of this Dockable.

    Specified by:
    getTitleText in interface Dockable
    Returns:
    the text

    setTitleText

    public void setTitleText(String titleText)
    Sets the title of this dockable. All dockableListeners are informed about the change.

    Parameters:
    titleText - the title, null is replaced by the empty string

    getTitleIcon

    public Icon getTitleIcon()
    Description copied from interface: Dockable
    Gets the current icon of this Dockable.

    Specified by:
    getTitleIcon in interface Dockable
    Returns:
    the icon, may be null

    setTitleToolTip

    public void setTitleToolTip(String titleToolTip)
    Sets the tooltip that will be shown on any title of this dockable.

    Parameters:
    titleToolTip - the new tooltip, can be null

    getTitleToolTip

    public String getTitleToolTip()
    Description copied from interface: Dockable
    Gets a tooltip that is associated with this Dockable and that should be shown on any DockTitle.

    Specified by:
    getTitleToolTip in interface Dockable
    Returns:
    the tooltip, can be null

    getPopupLocation

    public Point getPopupLocation(Point click,
                                  boolean popupTrigger)
    Description copied from interface: DockElementRepresentative
    Tells whether a popup menu should be opened when the user clicks at click with the mouse. If yes, then the top left edge of the popup should be returned, otherwise null should be returned.

    Specified by:
    getPopupLocation in interface DockElementRepresentative
    Parameters:
    click - the location where the user clicked with the mouse
    popupTrigger - whether the invocation is the systems popup trigger or not. Many implementations of this method will return click in case of true, and null in case of false
    Returns:
    the preferred location of a popup or null if no popup-menu should be opened

    setTitleIcon

    public void setTitleIcon(Icon titleIcon)
    Sets the icon of this dockable. All dockableListeners are informed about the change.

    Parameters:
    titleIcon - the new icon, may be null

    requestDockTitle

    public void requestDockTitle(DockTitleRequest request)
    The default behavior of this method is todo nothing.

    Specified by:
    requestDockTitle in interface Dockable
    Parameters:
    request - which title is required. If this Dockable does not have a special rule for the given request it just ignores the call

    bind

    public void bind(DockTitle title)
    Description copied from interface: Dockable
    Called by clients which want to show a title of this Dockable. The method DockTitle.bind() will be called automatically by the controller.
    This method must at least inform all listeners, that title was bound. However, the method DockTitle.bind() must not be invoked by this method.
    title must be returned by Dockable.listBoundTitles() unless Dockable.unbind(DockTitle) is called.

    Specified by:
    bind in interface Dockable
    Parameters:
    title - the title which will be show some things of this Dockable
    See Also:
    Dockable.unbind(DockTitle)

    unbind

    public void unbind(DockTitle title)
    Description copied from interface: Dockable
    Clients should call this method if a DockTitle is no longer needed. The controller will call DockTitle.unbind() at an appropriate time.
    This method must inform all listeners that title is no longer bound. However, this method must not call DockTitle.unbind().
    title must no longer be returned when calling Dockable.listBoundTitles()

    Specified by:
    unbind in interface Dockable
    Parameters:
    title - the title which will be no longer connected to this Dockable
    See Also:
    Dockable.bind(DockTitle)

    listBoundTitles

    public DockTitle[] listBoundTitles()
    Description copied from interface: Dockable
    Gets a list of all DockTitles which are currently bound to this Dockable. That are titles for which Dockable.bind(DockTitle) was called, but not yet Dockable.unbind(DockTitle).

    Specified by:
    listBoundTitles in interface Dockable
    Returns:
    the list of titles

    getLocalActionOffers

    public DockActionSource getLocalActionOffers()
    Description copied from interface: Dockable
    Gets a list of DockActions which should be triggerable if this Dockable is visible. The list contains only actions which are directly bound to this Dockable (the actions which are not changed when the parent-station of this Dockable is exchanged). The list can be modified by this Dockable at every time, clients have to react on these changes by adding a DockActionSourceListener to the result.

    Specified by:
    getLocalActionOffers in interface Dockable
    Returns:
    the source of actions, can be null if no actions are available

    getGlobalActionOffers

    public DockActionSource getGlobalActionOffers()
    Description copied from interface: Dockable
    Gets a list of all DockActions which might be triggered while this Dockable is visible. The list must contain all actions which are related in any way to this Dockable. Subclasses might use a HierarchyDockActionSource or the method DockController.listOffers(Dockable) to get this functionality

    Specified by:
    getGlobalActionOffers in interface Dockable
    Returns:
    the source containing all actions, never null

    setActionOffers

    public void setActionOffers(DockActionSource source)
    Sets the action-source of this Dockable. Other elements which used getGlobalActionOffers() will be informed about this change.

    Parameters:
    source - The new source, may be null

    fireTitleTextChanged

    protected void fireTitleTextChanged(String oldTitle,
                                        String newTitle)
    Calls the titleTextChanged method of all registered DockableListeners.

    Parameters:
    oldTitle - the old title
    newTitle - the new title

    fireTitleTooltipChanged

    protected void fireTitleTooltipChanged(String oldTooltip,
                                           String newTooltip)
    Called the titleTooltipChanged method of all registered DockableListeners.

    Parameters:
    oldTooltip - the old value
    newTooltip - the new value

    fireTitleIconChanged

    protected void fireTitleIconChanged(Icon oldIcon,
                                        Icon newIcon)
    Calls the titleIconChanged method of all registered DockableListener.

    Parameters:
    oldIcon - the old icon
    newIcon - the new icon

    fireTitleBound

    protected void fireTitleBound(DockTitle title)
    Informs all dockableListeners that title was bound to this dockable.

    Parameters:
    title - the title which was bound

    fireTitleUnbound

    protected void fireTitleUnbound(DockTitle title)
    Informs all dockableListeners that title was unbound from this dockable.

    Parameters:
    title - the title which was unbound

    fireTitleExchanged

    protected void fireTitleExchanged(DockTitle title)
    Informs all DockableListeners that title is no longer considered to be a good title and should be exchanged.

    Parameters:
    title - a title, can be null

    fireTitleExchanged

    protected void fireTitleExchanged()
    Informs all DockableListeners that all bound titles and the null title are no longer considered good titles and should be replaced


    configureDisplayerHints

    public void configureDisplayerHints(DockableDisplayerHints hints)
    Description copied from interface: Dockable
    Orders this Dockable to configure hints which will be used by the parent component of this element. This Dockable can store a reference to hints and use it to change the hints whenever it is appropriate. This method will be called with null if the link should be broken.

    Specified by:
    configureDisplayerHints in interface Dockable
    Parameters:
    hints - the hints to configure or null if the last hints should no longer be configured by this element

    getConfigurableDisplayerHints

    protected DockableDisplayerHints getConfigurableDisplayerHints()
    Gets the last DockableDisplayerHints that were given to configureDisplayerHints(DockableDisplayerHints).

    Returns:
    the current configurable hints, can be null