Package bibliothek.gui.dock.support.mode

Class ModeManager<H,M extends Mode<H>>

java.lang.Object
bibliothek.gui.dock.support.mode.ModeManager<H,M>
Type Parameters:
H - the kind of properties that are to be stored in this manager
M - the kind of Modes used by this manager
Direct Known Subclasses:
LocationModeManager
public abstract class ModeManager<H,M extends Mode<H>> extends Object
Associates Dockables with one Mode out of a set of modes. This manager remembers in which order the modes were applied to a Dockable.
Author:
Benjamin Sigg

  • Constructor Details

    • ModeManager

      public ModeManager(DockController controller)
      Creates a new manager.
      Parameters:
      controller - the controller in whose realm this manager will work

  • Method Details

    • destroy

      public void destroy()
      Unregisters listeners which this manager added to the DockController and other components.

    • getController

      public DockController getController()
      Gets the controller in whose realm this manager works.
      Returns:
      the controller

    • addModeManagerListener

      public void addModeManagerListener(ModeManagerListener<? super H,? super M> listener)
      Adds a listener to this manager, the listener will be informed about changes in this manager.
      Parameters:
      listener - the new listener, not null

    • removeModeManagerListener

      public void removeModeManagerListener(ModeManagerListener<? super H,? super M> listener)
      Removes listener from this manager.
      Parameters:
      listener - the listener to remove

    • putMode

      public void putMode(M mode)
      Puts a new mode in this manager. If there is already a mode with the same id registered, then the old mode gets replaced by the new one.
      Parameters:
      mode - the new mode

    • putFactory

      public void putFactory(ModeSettingFactory<H> factory)
      Adds a factory to this ModeManager. The factory will be used by the ModeSettings to read and write data of the mode with the same identifier as factory persistently.
      Note: A Mode might also provide a ModeSettingFactory, if there is a collision of unique identifiers the factory of the mode is used.
      Parameters:
      factory - the new factory

    • getFactories

      public Collection<ModeSettingFactory<H>> getFactories()
      Gets a set containing all the ModeSettingFactorys that were added to this manager.
      Returns:
      the factories

    • removeMode

      public void removeMode(M mode)
      Removes mode from this manager. Note that history information about the mode remains.
      Parameters:
      mode - the mode to remove

    • getMode

      public M getMode(Path path)
      Searches and returns the mode with given unique identifier path.
      Parameters:
      path - some unique identifier
      Returns:
      the mode with that identifier or null

    • setHistoryRewriter

      public void setHistoryRewriter(HistoryRewriter<H,M> historyRewriter)
      Sets the current HistoryRewriter. The rewriter is invoked every time before the apply method of a Mode is called. The rewriter can then change the history of one Dockable, e.g. to apply additional checks whether an old state is still valid.
      A history rewriter does not change the history permanently. It creates a new history object before the apply method is called, but that new history object will not be stored by the ModeManager.
      Parameters:
      historyRewriter - the new rewriter, can be null

    • getHistoryRewriter

      public HistoryRewriter<H,M> getHistoryRewriter()
      Gets the current HistoryRewriter.
      Returns:
      the rewriter, can be null
      See Also:

    • listeners

      protected ModeManagerListener<? super H,? super M>[] listeners()
      Gets all the listeners that are currently registered in this manager.
      Returns:
      the list of registered listeners

    • fireAdded

      protected void fireAdded(Dockable dockable)
      Calls ModeManagerListener.dockableAdded(ModeManager, Dockable) on all listeners that are currently registered
      Parameters:
      dockable - the new element

    • fireRemoved

      protected void fireRemoved(Dockable dockable)
      Calls ModeManagerListener.dockableRemoved(ModeManager, Dockable) on all listeners that are currently registered.
      Parameters:
      dockable - the removed element

    • fireModeChanged

      protected void fireModeChanged(Dockable dockable, M oldMode, M newMode)
      Calls ModeManagerListener.modeChanged(ModeManager, Dockable, Mode, Mode) on all listeners that are currently registered.
      Parameters:
      dockable - the element whose mode changed
      oldMode - its old mode
      newMode - its new mode

    • fireAdded

      protected void fireAdded(M mode)
      Calls ModeManagerListener.modeAdded(ModeManager, Mode) on all listeners that are currently registered.
      Parameters:
      mode - the added mode

    • fireRemoved

      protected void fireRemoved(M mode)
      Calls ModeManagerListener.modeRemoved(ModeManager, Mode) on all listeners that are currently registered.
      Parameters:
      mode - the removed mode

    • add

      public void add(String key, Dockable dockable)
      Registers a new Dockable at this manager. If there is already mode-information for key present, then dockable inherits this information.
      Parameters:
      key - the unique key of dockable
      dockable - the new element
      Throws:
      NullPointerException - if either key or dockable is null
      IllegalArgumentException - if there is already a dockable registered with key

    • put

      public void put(String key, Dockable dockable)
      Registers a new Dockable at this manager. This method works like add(String, Dockable) but does not throw an exception if another Dockable is already registered with key. Instead the other Dockable is unregistered and dockable inherits its mode-information.
      Parameters:
      key - the unique identifier of dockable
      dockable - some new element
      Throws:
      NullPointerException - if either key or dockable is null

    • getKey

      public String getKey(Dockable dockable)
      Gets the unique identifier which is used for dockable.
      Parameters:
      dockable - some element
      Returns:
      the unique identifier or null if dockable is not registered

    • isRegistered

      public boolean isRegistered(Dockable dockable)
      Tells whether this ModeManager knows dockable and can handle a call to any of the apply methods.
      Parameters:
      dockable - the element to check
      Returns:
      true if the element is known, false otherwise

    • listDockables

      public Set<Dockable> listDockables()
      Returns a set containing all Dockables that are currently registered at this manager.
      Returns:
      the set of dockables

    • runTransaction

      public void runTransaction(AffectingRunnable runnable)
      Runs an algorithm which affects the mode of some Dockables.
      Parameters:
      runnable - the algorithm, null will be ignored

    • runTransaction

      public void runTransaction(AffectingRunnable run, boolean continuous)
      Runs an algorithm which affects the mode of some Dockables.
      Parameters:
      run - the algorithm, null will be ignored
      continuous - if set to true the transaction should run without changing the internal cache storing the position of all Dockables. This can be important if an operation runs an apply method and additional work will change the position of some elements again. Clients should call store(Dockable) afterwards.

    • runTransaction

      public void runTransaction(Runnable run)
      Runs run as transaction, the DockRegister is stalled and isOnTransaction() returns true while run runs.
      Parameters:
      run - the runnable to execute

    • runTransaction

      public void runTransaction(Runnable run, boolean continuous)
      Runs run as transaction, the DockRegister is stalled and isOnTransaction() returns true while run runs.
      Parameters:
      run - the runnable to execute
      continuous - if set to true the transaction should run without changing the internal cache storing the position of all Dockables. This can be important if an operation runs an apply method and additional work will change the position of some elements again. Clients should call store(Dockable) afterwards.

    • apply

      public boolean apply(Dockable dockable, Path mode, boolean force)
      Alters the mode of dockable to mode. This method just calls apply(Dockable, Mode, boolean).
      Parameters:
      dockable - the element whose mode is going to be changed
      mode - the new mode
      force - if true dockable is relocated even if the current mode already is mode
      Returns:
      true if mode was found, false otherwise
      Throws:
      IllegalArgumentException - if dockable is null, mode is null or dockable is not registered.

    • apply

      public void apply(Dockable dockable, M mode, boolean force)
      Alters the mode of dockable to mode. This method just calls apply(Dockable, Mode, AffectedSet, boolean).
      Parameters:
      dockable - the element whose mode is going to be changed
      mode - the new mode
      force - if true dockable is relocated even if the current mode already is mode
      Throws:
      IllegalArgumentException - if dockable is null, mode is null or dockable is not registered.

    • apply

      public boolean apply(Dockable dockable, Path mode, AffectedSet set, boolean force)
      Alters the mode of dockable to mode. This method just calls apply(Dockable, Mode, AffectedSet, boolean).
      Parameters:
      dockable - the element whose mode is going to be changed
      mode - the new mode
      set - to store all dockables whose mode might have been changed
      force - if true dockable is relocated even if the current mode already is mode
      Returns:
      true if mode was found, false otherwise
      Throws:
      IllegalArgumentException - if dockable is null, mode is null, set is null, or dockable is not registered.

    • apply

      public void apply(Dockable dockable, M mode, AffectedSet set, boolean force)
      Alters the mode of dockable to mode. This method does nothing if the current mode of dockable already is mode.
      After initial checks and reading the history, this method calls apply(Dockable, Mode, Object, AffectedSet).
      Parameters:
      dockable - the element whose mode is going to be changed
      mode - the new mode
      set - to store all dockables whose mode might have been changed
      force - if true dockable is relocated even if the current mode already is mode
      Throws:
      IllegalArgumentException - if dockable is null, mode is null, set is null, or dockable is not registered.

    • getHistory

      public H getHistory(Dockable dockable, Path modeId)
      Gets the history of dockable in mode modeId.
      Parameters:
      dockable - the element whose history is searched
      modeId - the identifier of the mode
      Returns:
      the history information or null if not found

    • apply

      public boolean apply(Dockable dockable, Path mode, H history, AffectedSet set)
      Alters the mode of dockable to be mode. This method just calls apply(Dockable, Mode, Object, AffectedSet).
      Parameters:
      dockable - the element whose mode is changed
      mode - the new mode of dockable
      history - history information for Mode.apply(Dockable, Object, AffectedSet), can be null
      set - to store elements that have changed
      Returns:
      true if mode was found, false otherwise
      Throws:
      IllegalArgumentException - if either dockable, mode or set is null

    • apply

      public void apply(Dockable dockable, M mode, H history, AffectedSet set)
      Alters the mode of dockable to be mode. This method does not alter the modes of other dockables, notice however that the methods Mode.apply(Dockable, Object, AffectedSet) may trigger additional mode-changes.
      Parameters:
      dockable - the element whose mode is changed
      mode - the new mode of dockable
      history - history information for Mode.apply(Dockable, Object, AffectedSet), can be null
      set - to store elements that have changed
      Throws:
      IllegalArgumentException - if either dockable, mode or set is null

    • setProperties

      protected void setProperties(M mode, Dockable dockable, H property)
      Stores a property for dockable if in mode mode. This method does not trigger any version of the apply methods.
      Parameters:
      mode - the mode which is affected
      dockable - the dockables whose property is changed
      property - the new property, can be null

    • getProperties

      protected H getProperties(M mode, Dockable dockable)
      Gets the properties which correspond to dockable and mode.
      Parameters:
      mode - the first part of the key
      dockable - the second part of the key
      Returns:
      the properties or null

    • isOnTransaction

      public boolean isOnTransaction()
      Tells whether this manager is currently changing the Mode of a Dockable.
      Returns:
      true if a mode is currently working

    • isOnContinuous

      public boolean isOnContinuous()
      Tells whether this manager currently runs a continuous transaction. As long as a continuous transaction is running the internal states of this manager do not change.
      Returns:
      whether a continuous transaction is running

    • refresh

      public void refresh()
      Updates the modes of all Dockables that are registered at this ModeManager.

    • refresh

      public void refresh(Dockable dockable, boolean recursive)
      Updates the mode of dockable and updates the actions associated with dockable. This method is intended to be called by any code that changes the mode in a way that is not automatically registered by this ModeManager.
      Parameters:
      dockable - the element whose mode might have changed
      recursive - if set, then the children of dockable are refreshed as well.

    • remove

      public void remove(Dockable dockable)
      Removes the properties that belong to dockable.
      Parameters:
      dockable - the element to remove

    • reduceToEmpty

      public void reduceToEmpty(Dockable dockable)
      Removes dockable itself, put the properties of dockable remain in the system.
      Parameters:
      dockable - the element to reduce

    • applyDuringRead

      protected abstract void applyDuringRead(String key, Path old, Path current, Dockable dockable)
      Called while reading modes in readSettings(ModeSettings). Subclasses might change the mode according to newMode.
      Parameters:
      key - the identifier of dockable
      old - the mode dockable is currently in
      current - the mode dockable is going to be
      dockable - the element that changes its mode, might be null

    • createEntryDuringRead

      protected boolean createEntryDuringRead(String key)
      Tells whether an entry for a missing Dockable should be created. This will result in a call to addEmpty(String) during readSettings(ModeSettings). The default implementation returns always false.
      Parameters:
      key - the key for which to create a new entry
      Returns:
      true if an entry should be created

    • addEmpty

      public void addEmpty(String key)
      Adds an empty entry to this manager. The empty entry can be used to store information for a Dockable that has not yet been created. It is helpful if the client intends to load first its properties and create only those Dockables which are visible.
      Also an empty entry gets never deleted unless removeEmpty(String) is called.
      Parameters:
      key - the name of the empty entry
      Throws:
      NullPointerException - if key is null

    • removeEmpty

      public void removeEmpty(String name)
      Removes the entry for name but only if the entry is not associated with any Dockable.
      Parameters:
      name - the name of the entry which might be empty
      Throws:
      NullPointerException - if key is null

    • isEmpty

      public boolean isEmpty(String key)
      Tells whether information about dockable key gets stored indefinitely or not.
      Parameters:
      key - the key to check
      Returns:
      true if the key is never removed automatically false otherwise

    • getDoubleClickTarget

      public Dockable getDoubleClickTarget(Dockable target)
      Given some Dockable on which an event was registered, searches a registered dockable that is a child of target or target itself.
      Parameters:
      target - the target whose registered child is searched
      Returns:
      target, a child of target, or null

    • getDefaultMode

      protected M getDefaultMode(Dockable dockable)
      Gets the default mode of dockable, the mode dockable is in if nothing else is specified. This method checks Mode.isDefaultMode(Dockable) and returns the first Mode where the answer was true.
      Parameters:
      dockable - some dockable, not null
      Returns:
      its default mode, must be registered at this ModeManager and not be null

    • getCurrentMode

      public M getCurrentMode(Dockable dockable)
      Tries to find the mode dockable is currently in. This method calls Mode.isCurrentMode(Dockable) and returns the first Mode where the answer was true.
      Parameters:
      dockable - some dockable, not null
      Returns:
      the current mode or null if not found

    • getPreviousMode

      public M getPreviousMode(Dockable dockable)
      Reading the history this method tells which mode dockable was in before the current mode.
      Parameters:
      dockable - some element
      Returns:
      the previous mode or null if this information is not available

    • getModeHistory

      public List<M> getModeHistory(Dockable dockable)
      Gets the history which modes dockable used in the past. The older entries are at the beginning of the list. The current mode may or may not be included in the list.
      Parameters:
      dockable - the element whose history is asked
      Returns:
      the history or an empty list if no history is available

    • addToModeHistory

      public void addToModeHistory(Dockable dockable, M mode, H history)
      Adds the history data history to dockable for mode mode, and stores mode as the newest used mode.
      Parameters:
      dockable - the element whose history is modified must be known to this manager
      mode - the mode whose history is modified
      history - the new history
      Throws:
      IllegalStateException - if dockable is not known to this manager

    • getPropertyHistory

      public List<H> getPropertyHistory(Dockable dockable)
      Gets the history which properties dockable used in the past. Entries of value null are ignored. The older entries are at the beginning of the list.
      Parameters:
      dockable - the element whose history is asked
      Returns:
      the history or an empty list if no history is available

    • store

      public void store(Dockable dockable)
      Stores the current location of dockable and all its children in respect to their current Mode. Dockables that are not registered at this manager are ignored.
      This method does nothing if isOnContinuous() returns true
      Parameters:
      dockable - a root of a tree

    • store

      protected void store(M mode, Dockable dockable)
      Stores the location of dockable under the key mode.
      This method does nothing if isOnContinuous() returns true
      Parameters:
      mode - the mode dockable is currently in
      dockable - the element whose location will be stored

    • modes

      public Iterable<M> modes()
      Returns an iteration of all modes that are stored in this manager.
      Returns:
      the iteration

    • rebuildAll

      protected void rebuildAll()
      Rebuilds the actions sources for all Dockables.

    • rebuild

      protected void rebuild(Dockable dockable)
      Rebuilds the action sources of dockable.
      Parameters:
      dockable - the element whose actions are to be updated

    • getSharedActions

      public abstract DockActionSource getSharedActions(DockStation station)
      Gets a list of actions that should be shown on station depending on the current children of station. This method is called every time when either a child is added, removed or selected on station.
      Parameters:
      station - the station whose actions are asked
      Returns:
      the actions, can be null

    • createSettings

      public <B> ModeSettings<H,B> createSettings(ModeSettingsConverter<H,B> converter)
      Creates a new ModeSetting which is configured to transfer data from this ModeManager to persistent storage or the other way. The new setting contains all the ModeSettingFactorys which are currently known to this manager.
      Type Parameters:
      B - the intermediate format
      Parameters:
      converter - conversion tool from this manager's meta-data format to the intermediate format.
      Returns:
      the new empty settings

    • createModeSettings

      public <B> ModeSettings<H,B> createModeSettings(ModeSettingsConverter<H,B> converter)
      Creates the empty set of settings for this ModeManager. Subclasses may override this method to use another set of settings. This method does not need to call ModeSettings.addFactory(ModeSettingFactory).
      Type Parameters:
      B - the intermediate format
      Parameters:
      converter - conversion tool from this manager's meta-data format to the intermediate format.
      Returns:
      the new empty settings

    • writeSettings

      public void writeSettings(ModeSettings<H,?> setting)
      Writes all the information stored in this ModeManager to setting.
      Parameters:
      setting - the settings to fill

    • readSettings

      public void readSettings(ModeSettings<H,?> settings)
      Reads the contents of settings and stores it.
      Parameters:
      settings - the settings to read

    • readSettings

      public Runnable readSettings(ModeSettings<H,?> settings, UndoableModeSettings pending)
      Reads the contents of settings, creates new entries if either createEntryDuringRead(String) or if pending allows the setting to be undone if not needed.
      Parameters:
      settings - the settings to read
      pending - undoable settings, can be null
      Returns:
      an algorithm that will remove any entry that was created because pending did advise so, null if pending was null

    • addAffected

      public void addAffected(Iterable<Dockable> dockables)
      Adds all elements of dockables to the current AffectedSet.
      Parameters:
      dockables - the elements to add

    • toString

      public String toString()
      Overrides:
      toString in class Object