Dockable (docking-frames-core 1.1.2p20a API)

All Superinterfaces:

DockComponentRoot, DockElement, DockElementRepresentative, PlaceholderListItem<Dockable>

All Known Implementing Classes:

AbstractDockable, AbstractDockableStation, DefaultDockable, FlapDockStation, SplitDockStation, StackDockStation
```
public interface Dockable
extends DockElement, DockElementRepresentative, PlaceholderListItem<Dockable>
```
A Dockable is a window which can be dragged around by the user. Dockables need to have a DockStation as parent, otherwise they are not visible.
Several properties are associated with a Dockable:
- A set of DockTitles is managed by the parent of this Dockable. The icon and the title-text of this Dockable might be painted on that title.
- A set of DockActions is stored in a DockActionSource. These actions are displayed on the title(s) and allow users to execute operations that belong to this Dockable
- A Component which represents the contents of this Dockable
This interface is not intended to be implemented by clients, although they can if some very special behavior is required. Normally clients are better of using the DefaultDockable or extending AbstractDockable.
Author:

Benjamin Sigg

Method Summary

All Methods Instance Methods Abstract Methods Deprecated Methods
Modifier and Type	Method and Description
`boolean`	`accept(DockStation station)` Tells whether `station` is an accepted parent for this `Dockable` or not.
`boolean`	`accept(DockStation base, Dockable neighbor)` 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`	`addDockableStateListener(DockableStateListener listener)` Adds `listener` to this `Dockable`.
`void`	`addDockHierarchyListener(DockHierarchyListener listener)` Adds a hierarchy-listener to this Dockable.
`void`	`addMouseInputListener(MouseInputListener listener)` Adds a `MouseInputListener` to the `component` of this `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.
`Component`	`getComponent()` Gets the `Component` which represents this `Dockable`.
`DockController`	`getController()` Gets the current controller, the argument of the last call of `setController(DockController)`.
`DockStation`	`getDockParent()` Gets the current parent, which is the latest argument of `setDockParent(DockStation)`.
`DockActionSource`	`getGlobalActionOffers()` Gets a list of all `DockAction`s which might be triggered while this `Dockable` is visible.
`DockActionSource`	`getLocalActionOffers()` Gets a list of `DockAction`s which should be triggerable if this `Dockable` is visible.
`Icon`	`getTitleIcon()` Gets the current icon of this `Dockable`.
`String`	`getTitleText()` Gets 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`	`isDockableShowing()` Tells whether this `Dockable` can be seen by the user.
`boolean`	`isDockableVisible()` Deprecated. replaced by `isDockableShowing()`, this method will be removed in a future release
`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`	`removeDockableStateListener(DockableStateListener listener)` Removes `listener` from this element.
`void`	`removeDockHierarchyListener(DockHierarchyListener listener)` Removes a hierarchy-listener from this Dockable.
`void`	`removeMouseInputListener(MouseInputListener listener)` Removes a listener that was earlier added to this `Dockable`.
`void`	`requestDisplayer(DisplayerRequest request)` Invoked to get `DockableDisplayer` for this `Dockable`.
`void`	`requestDockTitle(DockTitleRequest request)` Invoked to get a graphical representation of a title for this `Dockable`.
`void`	`setController(DockController controller)` Sets the controller in whose realm this Dockable is.
`void`	`setDockParent(DockStation station)` Sets the parent property.
`void`	`unbind(DockTitle title)` Clients should call this method if a `DockTitle` is no longer needed.

Methods inherited from interface bibliothek.gui.dock.DockElement
asDockable, asDockStation, getFactoryID

Methods inherited from interface bibliothek.gui.dock.component.DockComponentRoot
getComponentConfiguration, setComponentConfiguration

Methods inherited from interface bibliothek.gui.dock.DockElementRepresentative
getElement, getPopupLocation, isUsedAsTitle, shouldFocus, shouldTransfersFocus

Methods inherited from interface bibliothek.gui.dock.station.support.PlaceholderListItem
asDockable

- Method Detail
  - setDockParent
```
void setDockParent(DockStation station)
```
    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, it will automatically fire a DockHierarchyEvent if necessary.
    
    Parameters:
    
    station - the parent, may be null if this Dockable is not visible at all.
  - getDockParent
```
DockStation getDockParent()
```
    Gets the current parent, which is the latest argument of setDockParent(DockStation).
    
    Returns:
    
    the parent property, can be null
  - isDockableVisible
```
@Deprecated
 @Todo(compatibility=BREAK_MAJOR,
      priority=ENHANCEMENT,
      target=VERSION_1_1_3,
      description="remove this method")
boolean isDockableVisible()
```
    Deprecated. replaced by isDockableShowing(), this method will be removed in a future release
    
    Tells whether this Dockable can be seen by the user. A Dockable at least needs to be registered as root-station on a DockController, or be a child of a root-station to be visible.
    Implementations will assume that Components which are displayable are are visible to the user.
    
    Returns:
    
    true if the user can actually see this dockable, false otherwise
  - isDockableShowing
```
boolean isDockableShowing()
```
    Tells whether this Dockable can be seen by the user. A Dockable at least needs to be registered as root-station on a DockController, or be a child of a root-station to be visible.
    Implementations will assume that Components which are displayable are are visible to the user.
    
    Returns:
    
    true if the user can actually see this dockable, false otherwise
  - setController
```
void setController(DockController controller)
```
    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)
    
    Parameters:
    
    controller - the owner, may be null
  - getController
```
DockController getController()
```
    Gets the current controller, the argument of the last call of setController(DockController).
    
    Specified by:
    
    getController in interface DockElement
    
    Returns:
    
    the controller, can be null
  - addDockableListener
```
void addDockableListener(DockableListener listener)
```
    Adds a listener to this Dockable. The listener has to be informed if a property of this Dockable changes.
    
    Parameters:
    
    listener - the new listener
  - removeDockableListener
```
void removeDockableListener(DockableListener listener)
```
    Removes a listener from this Dockable.
    
    Parameters:
    
    listener - the listener to remove
  - addDockHierarchyListener
```
void addDockHierarchyListener(DockHierarchyListener listener)
```
    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)
    
    Parameters:
    
    listener - the new listener
  - removeDockHierarchyListener
```
void removeDockHierarchyListener(DockHierarchyListener listener)
```
    Removes a hierarchy-listener from this Dockable.
    Note: when using a DockHierarchyObserver, forward the call directly to DockHierarchyObserver.removeDockHierarchyListener(DockHierarchyListener)
    
    Parameters:
    
    listener - the listener to remove
    
    See Also:
    
    addDockableListener(DockableListener)
  - addDockableStateListener
```
void addDockableStateListener(DockableStateListener listener)
```
    Adds listener to this Dockable. The listener will be informed about various events concerning the position and visibility of this dockable.
    
    Parameters:
    
    listener - the new listener, not null
  - removeDockableStateListener
```
void removeDockableStateListener(DockableStateListener listener)
```
    Removes listener from this element.
    
    Parameters:
    
    listener - the listener to remove
  - addMouseInputListener
```
void addMouseInputListener(MouseInputListener listener)
```
    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
    
    Parameters:
    
    listener - the mouse listener
  - removeMouseInputListener
```
void removeMouseInputListener(MouseInputListener listener)
```
    Removes a listener that was earlier added to this Dockable.
    
    Specified by:
    
    removeMouseInputListener in interface DockElementRepresentative
    
    Parameters:
    
    listener - The listener to remove
  - accept
```
boolean accept(DockStation station)
```
    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.
    
    Parameters:
    
    station - a possible parent
    
    Returns:
    
    whether station could be a parent or not
  - accept
```
boolean accept(DockStation base,
               Dockable neighbor)
```
    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.
    
    Parameters:
    
    base - the future parent of the combination
    
    neighbor - a Dockable whose parent will be the same parent as the parent of this Dockable
    
    Returns:
    
    true if the combination is allowed, false otherwise
  - getComponent
```
Component getComponent()
```
    Gets the Component which represents this Dockable. Note that the component should be a focus cycle root
    
    Specified by:
    
    getComponent in interface DockElementRepresentative
    
    Returns:
    
    the visible representation
  - getTitleText
```
String getTitleText()
```
    Gets the current title-text of this Dockable.
    
    Returns:
    
    the text
  - getTitleToolTip
```
String getTitleToolTip()
```
    Gets a tooltip that is associated with this Dockable and that should be shown on any DockTitle.
    
    Returns:
    
    the tooltip, can be null
  - getTitleIcon
```
Icon getTitleIcon()
```
    Gets the current icon of this Dockable.
    
    Returns:
    
    the icon, may be null
  - requestDockTitle
```
void requestDockTitle(DockTitleRequest request)
```
    Invoked to get a graphical representation of a title for this Dockable. This method is called either when a title first is required, or when this Dockable invoked the DockableListener.titleExchanged(Dockable, DockTitle) method of its current observers.
    This Dockable might decide to answer the request by calling DockTitleRequest.answer(DockTitle), any title, including null are valid answers. If this Dockable does not answer the request the associated DockTitleFactory (as described by DockTitleVersion.getFactory()) is asked to answer the request.
    The requests target must be this Dockable.
    The normal behavior of this method is to do nothing.
    
    Parameters:
    
    request - which title is required. If this Dockable does not have a special rule for the given request it just ignores the call
  - requestDisplayer
```
void requestDisplayer(DisplayerRequest request)
```
    Invoked to get DockableDisplayer for this Dockable. This method may be called when this Dockable is dropped onto a new DockStation, a theme was exchanged, or an existing DockableDisplayer was discarded.
    The usual behavior of this method should be to do nothing.
    
    Parameters:
    
    request - callback used to set a new DockableDisplayer
  - bind
```
void bind(DockTitle title)
```
    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 listBoundTitles() unless unbind(DockTitle) is called.
    
    Parameters:
    
    title - the title which will be show some things of this Dockable
    
    Throws:
    
    IllegalArgumentException - if the title is already bound
    
    See Also:
    
    unbind(DockTitle)
  - unbind
```
void unbind(DockTitle title)
```
    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 listBoundTitles()
    
    Parameters:
    
    title - the title which will be no longer connected to this Dockable
    
    Throws:
    
    IllegalArgumentException - if the title is not known to this Dockable
    
    See Also:
    
    bind(DockTitle)
  - listBoundTitles
```
DockTitle[] listBoundTitles()
```
    Gets a list of all DockTitles which are currently bound to this Dockable. That are titles for which bind(DockTitle) was called, but not yet unbind(DockTitle).
    
    Returns:
    
    the list of titles
  - getLocalActionOffers
```
DockActionSource getLocalActionOffers()
```
    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.
    
    Returns:
    
    the source of actions, can be null if no actions are available
  - getGlobalActionOffers
```
DockActionSource getGlobalActionOffers()
```
    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 implement this functionality
    
    Returns:
    
    the source containing all actions, never null
  - configureDisplayerHints
```
void configureDisplayerHints(DockableDisplayerHints hints)
```
    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.
    
    Parameters:
    
    hints - the hints to configure or null if the last hints should no longer be configured by this element

Interface Dockable

Method Summary

Methods inherited from interface bibliothek.gui.dock.DockElement

Methods inherited from interface bibliothek.gui.dock.component.DockComponentRoot

Methods inherited from interface bibliothek.gui.dock.DockElementRepresentative

Methods inherited from interface bibliothek.gui.dock.station.support.PlaceholderListItem

Method Detail

setDockParent

getDockParent

isDockableVisible

isDockableShowing

setController

getController

addDockableListener

removeDockableListener

addDockHierarchyListener

removeDockHierarchyListener

addDockableStateListener

removeDockableStateListener

addMouseInputListener

removeMouseInputListener

accept

accept

getComponent

getTitleText

getTitleToolTip

getTitleIcon

requestDockTitle

requestDisplayer

bind

unbind

listBoundTitles

getLocalActionOffers

getGlobalActionOffers

configureDisplayerHints