DockStation (docking-frames-core 1.1.2-P19c API)

All Superinterfaces:

DockComponentRoot, DockElement

All Known Implementing Classes:

AbstractDockableStation, AbstractDockStation, FlapDockStation, ScreenDockStation, SplitDockStation, StackDockStation
```
public interface DockStation
extends DockElement
```
A DockStation is some area (e.g. a Component) showing a set of Dockables called "children". The station is free to decide how and if to show its children.
Although a station can take any form, there are some (optional) practices to follow:
- Each Dockable should be child of a DockableDisplayer. The displayer will paint border and title of the item.
- This station should be aware of the current DockTheme and use its factories and delegates whenever possible.
- Drag and drop is handled by the DockController. Methods like canDrag(Dockable), drag(Dockable), prepareDrop(StationDropItem) need to be implemented for this. Also accept(Dockable), Dockable.accept(DockStation), Dockable.accept(DockStation, Dockable) and the DockAcceptance of the current DockController should be checked before allowing a drag and drop operation.
- For each child there should be at least one DockTitle. This station needs to derive a DockTitleVersion from its controller using the DockTitleManager and its factory method. With the DockTitleVersion-object one DockTitleRequest for each required DockTitle can be created.
- One child can be focused. If this station changes the focus it should use DockController.setAtLeastFocusedDockable(Dockable, Component).
- This station should support placeholders. The current PlaceholderStrategy can be used to convert Dockables to placeholders. A PlaceholderList is a good data structure to store Dockables and placeholders at the same time.
- Additional points where the user can start drag and drop operations can be installed by implementing a DockElementRepresentative. It has to be installed using DockController.addRepresentative(DockElementRepresentative).
- And a new DockFactory will be required to persistently store the layout of this station.
Author:

Benjamin Sigg

Method Summary

All Methods Instance Methods Abstract Methods Deprecated Methods
Modifier and Type	Method and Description
`boolean`	`accept(Dockable child)` Tells whether this station accepts `child` as a new child, or refuses `child`.
`void`	`addDockStationListener(DockStationListener listener)` Adds a listener to this station.
`void`	`aside(AsideRequest request)` Requests this `DockStation` to find a `DockableProperty` that is "aside" another property.
`boolean`	`canDrag(Dockable dockable)` Tells whether `dockable` can be removed from this station or not.
`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.
`void`	`changed(Dockable dockable, DockTitle title, boolean active)` Called by the `DockController` of this station to indicate that the active-state of `title` has been changed.
`void`	`drag(Dockable dockable)` Removes a child from 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.
`DockController`	`getController()` Gets the controller of this station.
`DockActionSource`	`getDirectActionOffers(Dockable dockable)` Gets a list of actions which should be available for the user and affect the child `dockable`.
`Dockable`	`getDockable(int index)` Gets the index'th child of this station.
`int`	`getDockableCount()` Gets the number of children.
`DockableProperty`	`getDockableProperty(Dockable child, Dockable target)` Gets precise information about the location of a child of this station.
`Dockable`	`getFrontDockable()` Gets the favorite child of this station.
`DockActionSource`	`getIndirectActionOffers(Dockable dockable)` Gets a list of actions which should be available for the user and affect `dockable`.
`DockStationDropLayer[]`	`getLayers()` Gets a description of all the areas of the screen where this `DockStation` can handle a drop event. Every time the mouse is moved or released during a drag & drop operation, this method is called for all `DockStation`s.
`PlaceholderMapping`	`getPlaceholderMapping()` Allows access to the placeholders that are stored on this station.
`PlaceholderMap`	`getPlaceholders()` Gets a snapshot of all placeholders that are currently stored in this `DockStation`.
`DockTheme`	`getTheme()` Gets the current theme of this station.
`boolean`	`isChildShowing(Dockable dockable)` Tells whether the child `dockable` is visible or not.
`boolean`	`isStationShowing()` Tells whether this station is visible or not.
`boolean`	`isStationVisible()` Deprecated. use `isStationShowing()` instead, this method will be removed in a future release
`boolean`	`isVisible(Dockable dockable)` Deprecated. use `isChildShowing(Dockable)` instead, this method will be removed in a future release
`void`	`move(Dockable dockable, DockableProperty property)` Tries to move the child `dockable` in such a way, that `getDockableProperty(Dockable, Dockable)` would return a `DockableProperty` that equals `property`. There is no need to give a guarantee that the move successes, and clients should always be prepared for the possibility that this `DockStation` does nothing at all.
`StationDragOperation`	`prepareDrag(Dockable dockable)` Informs this station that a drag and drop operation is in progress and that `dockable` might be removed from this station.
`StationDropOperation`	`prepareDrop(StationDropItem dockable)` Prepares this station to get the new child `dockable` or to move around the known child `dockable`.
`void`	`removeDockStationListener(DockStationListener listener)` Removes a listener from this station.
`void`	`replace(Dockable old, Dockable next)` Replaces the child `old` by `next` which is not yet a child of this station.
`void`	`replace(DockStation old, Dockable next)` Replaces the child `old` by `next` which is not yet a child of this station.
`void`	`requestChildDisplayer(DisplayerRequest request)` Provides a `DockableDisplayer` for a child of this station.
`void`	`requestChildDockTitle(DockTitleRequest request)` Provides a `DockTitle` for a child of this station.
`void`	`setController(DockController controller)` Sets the controller of this station.
`void`	`setFrontDockable(Dockable dockable)` Sets the most important child.
`void`	`setPlaceholders(PlaceholderMap placeholders)` Sets an earlier snapshot of the placeholders of this station.
`void`	`updateTheme()` Updates the `DockTheme` of this station.

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

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

- Method Detail
  - setController
```
void setController(DockController controller)
```
    Sets the controller of this station. If the station wants to show any DockTitle, then the titles have to be replaced by new instances (assuming the controller is really new). The title has to get new DockTitleVersions through the DockTitleManager of controller.
    An argument of null means that this station is currently not shown.
    
    Parameters:
    
    controller - the owner of this station, can be null
  - getController
```
DockController getController()
```
    Gets the controller of this station.
    
    Specified by:
    
    getController in interface DockElement
    
    Returns:
    
    the controller or null if no controller is set
    
    See Also:
    
    setController(DockController)
  - updateTheme
```
void updateTheme()
```
    Updates the DockTheme of this station. The new theme has to be read from the controller of this station. If the controller is null, this method should return immediately.
    You may use DockUI.updateTheme(DockStation, DockFactory) to implement this method.
  - getTheme
```
DockTheme getTheme()
```
    Gets the current theme of this station. The theme can be null, but that means that the station is not fully initialized, and might not work correct.
    
    Returns:
    
    the theme of this station or null.
  - getDirectActionOffers
```
DockActionSource getDirectActionOffers(Dockable dockable)
```
    Gets a list of actions which should be available for the user and affect the child dockable.
    
    Parameters:
    
    dockable - a child of this station
    
    Returns:
    
    actions for dockable, can be null
  - getIndirectActionOffers
```
DockActionSource getIndirectActionOffers(Dockable dockable)
```
    Gets a list of actions which should be available for the user and affect dockable. The argument dockable can be a child of this station, or a child of any station which is below this station.
    
    Parameters:
    
    dockable - a child of this station or a child of another station which is below this station
    
    Returns:
    
    actions for dockable or null
  - addDockStationListener
```
void addDockStationListener(DockStationListener listener)
```
    Adds a listener to this station. The station has to invoke the methods of the listener such that its requirements are full filled.
    
    Parameters:
    
    listener - the listener to add
  - removeDockStationListener
```
void removeDockStationListener(DockStationListener listener)
```
    Removes a listener from this station.
    
    Parameters:
    
    listener - the listener to remove
  - isVisible
```
@Todo(compatibility=BREAK_MAJOR,
      priority=ENHANCEMENT,
      target=VERSION_1_1_3,
      description="remove this method")
 @Deprecated
boolean isVisible(Dockable dockable)
```
    Deprecated. use isChildShowing(Dockable) instead, this method will be removed in a future release
    
    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 station is not visible.
    
    Parameters:
    
    dockable - the child whose visibility-state is questioned
    
    Returns:
    
    whether dockable is visible or not
    
    See Also:
    
    isStationVisible()
  - isChildShowing
```
boolean isChildShowing(Dockable dockable)
```
    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 station is not visible.
    
    Parameters:
    
    dockable - the child whose visibility-state is questioned
    
    Returns:
    
    whether dockable is visible or not
    
    See Also:
    
    isStationVisible()
  - isStationVisible
```
@Deprecated
 @Todo(compatibility=BREAK_MAJOR,
      priority=ENHANCEMENT,
      target=VERSION_1_1_3,
      description="remove this method")
boolean isStationVisible()
```
    Deprecated. use isStationShowing() instead, this method will be removed in a future release
    
    Tells whether this station is visible or not. For example a station on a JFrame is not visible if the frame is minimized.
    
    Returns:
    
    whether this station is visible
  - isStationShowing
```
boolean isStationShowing()
```
    Tells whether this station is visible or not. For example a station on a JFrame is not visible if the frame is minimized.
    
    Returns:
    
    whether this station is visible
  - getDockableCount
```
int getDockableCount()
```
    Gets the number of children.
    
    Returns:
    
    the number of children on this station
  - getDockable
```
Dockable getDockable(int index)
```
    Gets the index'th child of this station.
    
    Parameters:
    
    index - a value between 0 (incl.) and getDockableCount() (excl.).
    
    Returns:
    
    a child of this station
  - getFrontDockable
```
Dockable getFrontDockable()
```
    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.setFocusedDockable(Dockable, boolean) which will then call 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
```
void setFrontDockable(Dockable dockable)
```
    Sets the most important child. The station should ensure that this child is visible (assuming the station itself is visible). Read the comment on getFrontDockable() how stations can change this property.
    
    Parameters:
    
    dockable - the new favorite child, can be null
    
    See Also:
    
    getFrontDockable()
  - getPlaceholderMapping
```
PlaceholderMapping getPlaceholderMapping()
```
    Allows access to the placeholders that are stored on this station. Clients may use the PlaceholderMapping to add or remove placeholders from the station.
    Not all stations support placeholders, and these station may return a mapping that performs no actions.
    
    Returns:
    
    access to the placeholders
  - getPlaceholders
```
PlaceholderMap getPlaceholders()
```
    Gets a snapshot of all placeholders that are currently stored in this DockStation. A DockStation is free in the format it chooses to fill the map. The map is to be created with the assumptions that getDockableCount() is 0, meaning any existing Dockable gets replaced by its placeholder. The current PlaceholderStrategy should be used to convert Dockables to placeholders.
    Clients interested in modifying the placeholders of this station should call getPlaceholderMapping().
    
    Returns:
    
    the map of placeholders or null if this station does not support placeholders
  - setPlaceholders
```
void setPlaceholders(PlaceholderMap placeholders)
```
    Sets an earlier snapshot of the placeholders of this station. This station can assume that it currently does not have any children (that getDockableCount() is 0).
    This method does nothing if it cannot handle the format or the version of placeholders.
    
    Parameters:
    
    placeholders - some set of placeholders
    
    Throws:
    
    IllegalStateException - if getDockableCount() is not equal to 0
  - changed
```
void changed(Dockable dockable,
             DockTitle title,
             boolean active)
```
    Called by the DockController of this station to indicate that the active-state of title has been changed. This station should call the method title.changed with an appropriate event. The station may add some additional information to this call.
    
    Parameters:
    
    dockable - the child whose title is changed
    
    title - the changed title, may not be bound
    
    active - the new state of the title
  - requestChildDockTitle
```
void requestChildDockTitle(DockTitleRequest request)
```
    Provides a DockTitle for a child of this station. This method must call DockTitleRequest.answer(DockTitle) to set the result.
    Most DockStations won't have the need to implement this method, leaving it empty will advice the framework to use another source for new DockTitles.
    
    Parameters:
    
    request - the request to answer, not null
  - requestChildDisplayer
```
void requestChildDisplayer(DisplayerRequest request)
```
    Provides a DockableDisplayer for a child of this station. This method must call DisplayerRequest.answer(DockableDisplayer) to set the result.
    The usual implementation should be to do nothing.
    
    Parameters:
    
    request - the request to answer, not null
  - accept
```
boolean accept(Dockable child)
```
    Tells whether this station accepts child as a new child, or refuses child. The user will not be able to drop a Dockable onto this station if this method returns false.
    
    Parameters:
    
    child - a Dockable which may become a child
    
    Returns:
    
    true if child is accepted
  - getDockableProperty
```
DockableProperty getDockableProperty(Dockable child,
                                     Dockable target)
```
    Gets precise information about the location of a child of this station. The result of this method could later be used to invoke drop(Dockable, DockableProperty).
    
    Parameters:
    
    child - a child of this station, this child's location is asked
    
    target - an optional hint telling for which dockable the location information will be used, can be null. This hint can be used to find a placeholder that should be part of the result.
    
    Returns:
    
    the location
    
    See Also:
    
    DockUtilities.getPropertyChain(DockStation, Dockable)
  - aside
```
void aside(AsideRequest request)
```
    Requests this DockStation to find a DockableProperty that is "aside" another property. What exactly the meaning of "aside" is, is left to the implementation. Usually "aside" means on the same "stack" but with the next higher index.
    The request object contains information about the location whose neighbor is searched, about a placeholder that should be used for the new location, and offers methods to forward the call to the next DockStation or Combiner if there is a successor.
    This method should call the answer methods of request with every kind of information it finds.
    If this method cannot handle request, then it just has to return without calling any of the answer methods.
    
    Parameters:
    
    request - information about a location and methods to create the neighbor location
    
    See Also:
    
    Combiner.aside(AsideRequest)
  - prepareDrop
```
StationDropOperation prepareDrop(StationDropItem dockable)
```
    Prepares this station to get the new child dockable or to move around the known child dockable. The station can refuse dockable, in this case this method just returns null. There are some constraints:
    - This method should use accept(Dockable) and Dockable.accept(DockStation) or Dockable.accept(DockStation, Dockable) to ensure that the desired drop-location is valid.
    - The method should use the DockAcceptance of its controller (see DockController.getAcceptance()) to ensure that the drop/location is valid.
    Parameters:
    
    dockable - information about the dockable that is going to be dropped
    
    Returns:
    
    an object describing where the Dockable can be dropped or null if no drop operation is possible
  - prepareDrag
```
StationDragOperation prepareDrag(Dockable dockable)
```
    Informs this station that a drag and drop operation is in progress and that dockable might be removed from this station.
    
    Parameters:
    
    dockable - the child that might be removed in the near future
    
    Returns:
    
    a callback that will be informed when the dockable was removed or the operation canceled, can be null
  - drop
```
void drop(Dockable dockable)
```
    Adds dockable to this station. The station can decide by its own where to put dockable.
    
    Parameters:
    
    dockable - a new child
  - drop
```
boolean drop(Dockable dockable,
             DockableProperty property)
```
    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.
  - move
```
void move(Dockable dockable,
          DockableProperty property)
```
    Tries to move the child dockable in such a way, that getDockableProperty(Dockable, Dockable) would return a DockableProperty that equals property.
    There is no need to give a guarantee that the move successes, and clients should always be prepared for the possibility that this DockStation does nothing at all.
    
    Parameters:
    
    dockable - a child of this station
    
    property - the preferred position of dockable
  - getLayers
```
DockStationDropLayer[] getLayers()
```
    Gets a description of all the areas of the screen where this DockStation can handle a drop event.
    Every time the mouse is moved or released during a drag & drop operation, this method is called for all DockStations. The returned DockStationDropLayers are then filtered and ordered, the resulting order defines the order in which the method prepareDrop(StationDropItem) is called.
    
    Returns:
    
    all the layers of this station, must not be null, must not contain null, must not contain the same entry twice. The array or the DockStationDropLayers may be modified, hence this method should always create new objects.
    
    See Also:
    
    DockStationDropLayerFactory
  - canDrag
```
boolean canDrag(Dockable dockable)
```
    Tells whether dockable can be removed from this station or not. This method assumes that dockable is a child of this station, if not, then the behavior of this method is unspecified.
    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
```
void drag(Dockable dockable)
```
    Removes a child from this station. This method may be called even if canDrag(Dockable) returned false.
    Note: clients may need to invoke DockController.freezeLayout() and DockController.meltLayout() to ensure no-one else adds or removes Dockables.
    
    Parameters:
    
    dockable - the child to remove
  - canReplace
```
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.
    
    Parameters:
    
    old - a child of this station
    
    next - the replacement of next.
    
    Returns:
    
    true if the replacement is possible
    
    Throws:
    
    IllegalArgumentException - if next is a child of this station
  - replace
```
void replace(Dockable old,
             Dockable next)
```
    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 old
    
    Throws:
    
    IllegalArgumentException - if next is a child of this station or if old is not a child
  - replace
```
void replace(DockStation old,
             Dockable next)
```
    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. This method can assume that next was a child of old but no longer is.
    
    Parameters:
    
    old - a dockable station that is a child of this station
    
    next - the replacement of old
    
    Throws:
    
    IllegalArgumentException - if next is a child of this station, if old is not a child or if old is not a Dockable

Interface DockStation

Method Summary

Methods inherited from interface bibliothek.gui.dock.DockElement

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

Method Detail

setController

getController

updateTheme

getTheme

getDirectActionOffers

getIndirectActionOffers

addDockStationListener

removeDockStationListener

isVisible

isChildShowing

isStationVisible

isStationShowing

getDockableCount

getDockable

getFrontDockable

setFrontDockable

getPlaceholderMapping

getPlaceholders

setPlaceholders

changed

requestChildDockTitle

requestChildDisplayer

accept

getDockableProperty

aside

prepareDrop

prepareDrag

drop

drop

move

getLayers

canDrag

drag

canReplace

replace

replace