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

java.lang.Object
- bibliothek.gui.dock.station.support.PlaceholderList<D,S,P>

Type Parameters:

D - the kind of object that should be treated as Dockable

S - the kind of object that should be treated as DockStation

P - the type of item which represents a Dockable

Direct Known Subclasses:

DockablePlaceholderList, PerspectivePlaceholderList
```
public abstract class PlaceholderList<D,S,P extends PlaceholderListItem<D>>
extends Object
```
A list consisting of Dockables and sets of Paths as placeholder. Uses a PlaceholderStrategy to automatically create and dispose of placeholders.
Clients should call bind() and unbind() to manage the lifecycle of this list.
A PlaceholderList is not thread-safe.

Author:

Benjamin Sigg

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static interface`	`PlaceholderList.Filter<M>` A sublist of a `PlaceholderList`, the elements in this list are filtered by a strategy that is defined by the `PlaceholderList`.
`class`	`PlaceholderList.Item` A single item in a `PlaceholderList`
`static class`	`PlaceholderList.Level` identifiers for the various sublists this list consists of

Field Summary

Fields
Modifier and Type Field and Description

static Path PLACEHOLDER_MAP_FORMAT
The format of the PlaceholderMaps that are created by this class.

Fields
Modifier and Type	Field and Description
`static Path`	`PLACEHOLDER_MAP_FORMAT` The `format` of the `PlaceholderMap`s that are created by this class.

Constructor Summary

Constructors
Constructor and Description
`PlaceholderList()` Creates a new and empty list.
`PlaceholderList(PlaceholderMap map, PlaceholderListItemConverter<D,P> converter)` Creates a new list reading all the data that is stored in `map`.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addPlaceholder(D dockable, Path placeholder)` Adds `placeholder` at the location of `dockable`.
`int`	`baseToLevel(int index, PlaceholderList.Level level)` Searches the base entry at `index` and returns its location in sublist `level`.
`void`	`bind()` Connects this list with its strategy.
`void`	`clear()` Clears this list, all entries are removed
`PlaceholderList.Filter<P>`	`dockables()` Gets a mutable view of all `Dockable`s of this list.
`protected abstract D[]`	`getChildren(S station)` Gets all the children of `station`.
`P`	`getDockableAt(Path placeholder)` Searches the first occurrence of `placeholder` and returns the `Dockable` that is stored at that location.
`int`	`getDockableIndex(Path placeholder)` Emulates the insertion of a `Dockable` at location `placeholder` and returns the index that the inserted dockable would have in the dockable-list.
`PlaceholderList.Item`	`getItem(D dockable)` Searches for the one `PlaceholderList.Item` in the `dockables` list that contains `dockable`.
`PlaceholderList.Item`	`getItem(Path placeholder)` Searches for the one `PlaceholderList.Item` in the `dockables` list that contains `placeholder`.
`int`	`getListIndex(int index, Path placeholder)` Searches for an index in `list()` described by `placeholder` or `index`. This method calls `insertAllPlaceholders()` if `placeholder` cannot be found.
`int`	`getListIndex(Path placeholder)` Searches the first occurrence of `placeholder` in a placeholder-set and returns the index of that entry on the `BASE level`.
`PlaceholderMap`	`getMap(Path placeholder)` Gets the `PlaceholderMap` that was used for a station at location `placeholder`.
`PlaceholderMetaMap`	`getMetaMap(Path placeholder)` Gets the meta-map that is associated with the set of placeholders that include `placeholder`.
`int`	`getNextListIndex(int index, Path placeholder)` Searches for an index in `list()` that follows the item described by `placeholder` or `index`. This method calls `insertAllPlaceholders()` if `placeholder` cannot be found.
`protected abstract Path`	`getPlaceholder(D dockable)` Gets the placeholder which matches `dockable`.
`protected abstract PlaceholderMap`	`getPlaceholders(S station)` Gets all the placeholders that are used by `station`.
`PlaceholderStrategy`	`getStrategy()` Gets the current strategy of this list.
`boolean`	`hasPlaceholder(Path placeholder)` Tells whether this list contains a reference to `placeholder`.
`void`	`insertAllPlaceholders()` Inserts a placeholder for all `Dockable`s that are stored in this list.
`int`	`levelToBase(int index, PlaceholderList.Level level)` Searches the base entry at `index` in the sublist `level` and returns its location in the base list.
`PlaceholderList.Filter<PlaceholderList.Item>`	`list()` Gets a mutable view of all elements of this list.
`PlaceholderList.Filter<Set<Path>>`	`listPlaceholders()` Gets a mutable view of all elements of this list.
`PlaceholderList.Filter<Set<Path>>`	`purePlaceholders()` Gets a mutable view of all pure placeholders of this list.
`int`	`put(Path placeholder, P dockable)` Searches for the first occurrence of `placeholder` and replaces it with `dockable`.
`boolean`	`put(P dockable, Path placeholder)` Searches for the entry containing `dockable` and adds `placeholder` to the placeholder set.
`void`	`read(PlaceholderMap map, PlaceholderListItemConverter<D,P> converter)` Reads the contents of `map` and adds them at the end of this list.
`protected void`	`read(PlaceholderMap map, PlaceholderListItemConverter<D,P> converter, boolean simulate)` Reads the contents of `map`.
`Path`	`remove(int index)` Removes the `index`'th `Dockable` from this list were `index` is an index used in `dockables()`.
`Path`	`remove(P dockable)` Searches for `dockable` and replaces it by a placeholder.
`void`	`removeAll(Path placeholder)` Checks all entries of this list and removes all occurrences of all `placeholder`.
`void`	`removeAll(Set<Path> placeholders)` Checks all entries of this list and removes all occurrences of all paths stored in `placeholders`.
`protected abstract void`	`setPlaceholders(S station, PlaceholderMap map)` Sets all the placeholders that should be used by `station`.
`void`	`setStrategy(PlaceholderStrategy strategy)` Sets the new strategy of this list.
`int`	`size(PlaceholderList.Level level)` Gets the number of entries in the level `level`.
`PlaceholderMap`	`toMap(PlaceholderListItemConverter<?,? super P> converter)` Converts this list into a `PlaceholderMap`, any remaining `Dockable` or `DockStation` will be converted using `converter`.
`protected abstract S`	`toStation(D dockable)` Converts `dockable` to the representation of a `DockStation`.
`String`	`toString()`
`protected abstract String`	`toString(D dockable)` Gets a representation of `dockable` as string.
`void`	`unbind()` Disconnects this list from its strategy.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - PLACEHOLDER_MAP_FORMAT
```
public static final Path PLACEHOLDER_MAP_FORMAT
```
    The format of the PlaceholderMaps that are created by this class.
- Constructor Detail
  - PlaceholderList
```
public PlaceholderList()
```
    Creates a new and empty list.
  - PlaceholderList
```
public PlaceholderList(PlaceholderMap map,
                       PlaceholderListItemConverter<D,P> converter)
```
    Creates a new list reading all the data that is stored in map. This constructor stores all placeholders that are described in map, obsolete placeholders may be deleted as soon as a PlaceholderStrategy is set.
    
    Parameters:
    
    map - the map to read, not null
    
    converter - used to convert items back to dockables, not null
    
    Throws:
    
    IllegalArgumentException - if map was not written by a PlaceholderList
- Method Detail
  - getPlaceholder
```
protected abstract Path getPlaceholder(D dockable)
```
    Gets the placeholder which matches dockable.
    
    Parameters:
    
    dockable - some random dockable
    
    Returns:
    
    the placeholder for dockable, can be null
  - toString
```
protected abstract String toString(D dockable)
```
    Gets a representation of dockable as string.
    
    Parameters:
    
    dockable - some random dockable, not null
    
    Returns:
    
    the text
  - toStation
```
protected abstract S toStation(D dockable)
```
    Converts dockable to the representation of a DockStation.
    
    Parameters:
    
    dockable - some random dockable
    
    Returns:
    
    dockable as station, can be null
  - getPlaceholders
```
protected abstract PlaceholderMap getPlaceholders(S station)
```
    Gets all the placeholders that are used by station.
    
    Parameters:
    
    station - some random representation of a DockStation
    
    Returns:
    
    the placeholders, can be null
  - setPlaceholders
```
protected abstract void setPlaceholders(S station,
                                        PlaceholderMap map)
```
    Sets all the placeholders that should be used by station.
    
    Parameters:
    
    station - a representation of a DockStation
    
    map - the map of placeholders, not null
  - getChildren
```
protected abstract D[] getChildren(S station)
```
    Gets all the children of station.
    
    Parameters:
    
    station - some station whose children are searched
    
    Returns:
    
    the children
  - read
```
public void read(PlaceholderMap map,
                 PlaceholderListItemConverter<D,P> converter)
```
    Reads the contents of map and adds them at the end of this list.
    
    Parameters:
    
    map - the map to read
    
    converter - used to convert items back to dockables, not null
    
    Throws:
    
    IllegalArgumentException - if the map is in the wrong format
  - read
```
protected void read(PlaceholderMap map,
                    PlaceholderListItemConverter<D,P> converter,
                    boolean simulate)
```
    Reads the contents of map. This method can either add the contents at the end of this list, or just simulate a read. If a read is simulated, then the methods of converter are called just as if this would be an actual read, but in reality no data is changed in this list.
    
    Parameters:
    
    map - the data to read
    
    converter - used to convert items back to dockables, not null
    
    simulate - whether this list should actually be changed or not
    
    Throws:
    
    IllegalArgumentException - if the map is in the wrong format
  - toMap
```
public PlaceholderMap toMap(PlaceholderListItemConverter<?,? super P> converter)
```
    Converts this list into a PlaceholderMap, any remaining Dockable or DockStation will be converted using converter.
    
    Parameters:
    
    converter - converter to translate dockables into persistent data, not null
    
    Returns:
    
    the new map, not null
  - bind
```
public void bind()
```
    Connects this list with its strategy.
  - unbind
```
public void unbind()
```
    Disconnects this list from its strategy.
  - getStrategy
```
public PlaceholderStrategy getStrategy()
```
    Gets the current strategy of this list.
    
    Returns:
    
    the current strategy
  - setStrategy
```
public void setStrategy(PlaceholderStrategy strategy)
```
    Sets the new strategy of this list. If the strategy is not null, then all current placeholders are checked and the invalid placeholders are removed.
    
    Parameters:
    
    strategy - the new strategy
  - insertAllPlaceholders
```
public void insertAllPlaceholders()
```
    Inserts a placeholder for all Dockables that are stored in this list.
  - dockables
```
public PlaceholderList.Filter<P> dockables()
```
    Gets a mutable view of all Dockables of this list.
    
    Returns:
    
    the dockables
  - purePlaceholders
```
public PlaceholderList.Filter<Set<Path>> purePlaceholders()
```
    Gets a mutable view of all pure placeholders of this list. A pure placeholder is an entry in this list with the dockable set to null.
    
    Returns:
    
    the placeholders
  - list
```
public PlaceholderList.Filter<PlaceholderList.Item> list()
```
    Gets a mutable view of all elements of this list.
    
    Returns:
    
    the elements
  - listPlaceholders
```
public PlaceholderList.Filter<Set<Path>> listPlaceholders()
```
    Gets a mutable view of all elements of this list.
    
    Returns:
    
    the elements, viewed as placeholders
  - removeAll
```
public void removeAll(Set<Path> placeholders)
```
    Checks all entries of this list and removes all occurrences of all paths stored in placeholders. If an entry remains with 0 placeholders and no Dockable it is removed.
    
    Parameters:
    
    placeholders - the placeholders to remove
  - removeAll
```
public void removeAll(Path placeholder)
```
    Checks all entries of this list and removes all occurrences of all placeholder. If an entry remains with 0 placeholders and no Dockable it is removed.
    
    Parameters:
    
    placeholder - the placeholder to remove
  - remove
```
public Path remove(int index)
```
    Removes the index'th Dockable from this list were index is an index used in dockables().
    
    Parameters:
    
    index - the index of the element to remove
    
    Returns:
    
    the placeholder that replaces the element or null
  - remove
```
public Path remove(P dockable)
```
    Searches for dockable and replaces it by a placeholder. If dockable is a DockStation, then its PlaceholderMap is stored.
    
    Parameters:
    
    dockable - the element to remove
    
    Returns:
    
    the placeholder that was inserted, null if the current strategy does not assign a placeholder to dockable or if dockable was not found in this list
  - put
```
public int put(Path placeholder,
               P dockable)
```
    Searches for the first occurrence of placeholder and replaces it with dockable. If there is already another dockable stored at that location, then the other dockable is replaced silently. If dockable is a DockStation and a PlaceholderMap is set, then this map is transferred to dockable and removed from this list, but only if the DockStation does not already have children.
    This method also removes all occurrences of placeholder and the placeholder that is assigned by the current PlaceholderStrategy from this list.
    
    Parameters:
    
    placeholder - the placeholder to search, not null
    
    dockable - the element which will replace placeholder, not null
    
    Returns:
    
    the index in dockables() where dockable was inserted or -1 if placeholder was not found
  - getDockableIndex
```
public int getDockableIndex(Path placeholder)
```
    Emulates the insertion of a Dockable at location placeholder and returns the index that the inserted dockable would have in the dockable-list.
    
    Parameters:
    
    placeholder - the placeholder of the element to insert
    
    Returns:
    
    the location or -1 if placeholder was not found
  - getListIndex
```
public int getListIndex(Path placeholder)
```
    Searches the first occurrence of placeholder in a placeholder-set and returns the index of that entry on the BASE level.
    
    Parameters:
    
    placeholder - the placeholder to search
    
    Returns:
    
    its location or -1 if not found
  - getListIndex
```
public int getListIndex(int index,
                        Path placeholder)
```
    Searches for an index in list() described by placeholder or index.
    This method calls insertAllPlaceholders() if placeholder cannot be found.
    
    Parameters:
    
    index - the backup index, used if placeholder cannot be found
    
    placeholder - a placeholder to search, can be null
    
    Returns:
    
    the location after placeholder or index
  - getNextListIndex
```
public int getNextListIndex(int index,
                            Path placeholder)
```
    Searches for an index in list() that follows the item described by placeholder or index.
    This method calls insertAllPlaceholders() if placeholder cannot be found.
    
    Parameters:
    
    index - the backup index, used if placeholder cannot be found
    
    placeholder - a placeholder to search, can be null
    
    Returns:
    
    the location after placeholder or index
  - hasPlaceholder
```
public boolean hasPlaceholder(Path placeholder)
```
    Tells whether this list contains a reference to placeholder.
    
    Parameters:
    
    placeholder - the placeholder to search
    
    Returns:
    
    whether the placeholder was found
  - put
```
public boolean put(P dockable,
                   Path placeholder)
```
    Searches for the entry containing dockable and adds placeholder to the placeholder set. This method removes placeholder from all the other entries.
    
    Parameters:
    
    dockable - the key
    
    placeholder - the placeholder to insert
    
    Returns:
    
    true if dockable was found, false otherwise
  - getDockableAt
```
public P getDockableAt(Path placeholder)
```
    Searches the first occurrence of placeholder and returns the Dockable that is stored at that location.
    
    Parameters:
    
    placeholder - the placeholder to search
    
    Returns:
    
    either the dockable or null if there is no dockable stored or placeholder is not found
  - getMetaMap
```
public PlaceholderMetaMap getMetaMap(Path placeholder)
```
    Gets the meta-map that is associated with the set of placeholders that include placeholder.
    
    Parameters:
    
    placeholder - some placeholder to search
    
    Returns:
    
    the meta map of the group containing placeholder, can be null
  - getMap
```
public PlaceholderMap getMap(Path placeholder)
```
    Gets the PlaceholderMap that was used for a station at location placeholder.
    
    Parameters:
    
    placeholder - some placeholder to search
    
    Returns:
    
    the PlaceholderMap that was stored at the place where placeholder was found, can be null
  - getItem
```
public PlaceholderList.Item getItem(Path placeholder)
```
    Searches for the one PlaceholderList.Item in the dockables list that contains placeholder.
    
    Parameters:
    
    placeholder - the placeholder used for searching
    
    Returns:
    
    the item with placeholder or null
  - getItem
```
public PlaceholderList.Item getItem(D dockable)
```
    Searches for the one PlaceholderList.Item in the dockables list that contains dockable.
    
    Parameters:
    
    dockable - the dockable used for searching
    
    Returns:
    
    the item representing dockable or null
  - addPlaceholder
```
public void addPlaceholder(D dockable,
                           Path placeholder)
```
    Adds placeholder at the location of dockable. This method will remove placeholder from all other locations.
    
    Parameters:
    
    dockable - some dockable that is known to this list
    
    placeholder - a placeholder that should be added to the PlaceholderList.Item that represents dockable
    
    Throws:
    
    IllegalArgumentException - if either argument is null, or if the location of dockable cannot be found
  - size
```
public int size(PlaceholderList.Level level)
```
    Gets the number of entries in the level level.
    
    Parameters:
    
    level - some level to count
    
    Returns:
    
    the size of that level
  - baseToLevel
```
public int baseToLevel(int index,
                       PlaceholderList.Level level)
```
    Searches the base entry at index and returns its location in sublist level.
    
    Parameters:
    
    index - the index of some entry
    
    level - the sublist
    
    Returns:
    
    the index in the sublist or -1 if the entry is not part of level
    
    Throws:
    
    IndexOutOfBoundsException - if index is illegal
  - levelToBase
```
public int levelToBase(int index,
                       PlaceholderList.Level level)
```
    Searches the base entry at index in the sublist level and returns its location in the base list.
    
    Parameters:
    
    index - the index of some entry
    
    level - the sublist
    
    Returns:
    
    the index in the base list
    
    Throws:
    
    IndexOutOfBoundsException - if index is illegal
  - clear
```
public void clear()
```
    Clears this list, all entries are removed
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class PlaceholderList<D,S,P extends PlaceholderListItem<D>>

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

PLACEHOLDER_MAP_FORMAT

Constructor Detail

PlaceholderList

PlaceholderList

Method Detail

getPlaceholder

toString

toStation

getPlaceholders

setPlaceholders

getChildren

read

read

toMap

bind

unbind

getStrategy

setStrategy

insertAllPlaceholders

dockables

purePlaceholders

list

listPlaceholders

removeAll

removeAll

remove

remove

put

getDockableIndex

getListIndex

getListIndex

getNextListIndex

hasPlaceholder

put

getDockableAt

getMetaMap

getMap

getItem

getItem

addPlaceholder

size

baseToLevel

levelToBase

clear

toString