Package bibliothek.gui.dock.common

Class CControl

java.lang.Object
bibliothek.gui.dock.common.CControl
public class CControl extends Object
Manages the interaction between SingleCDockable, MultipleCDockable and CStations.
Clients which do no longer need a CControl can call destroy() to free resources.
A CControl is an interface between the application and the framework. The task of CControl is to provide access for actions that affect the entire realm. Such actions may include:
  • add/remove a global listener.
  • add/remove/access CDockables, CStations and CStationContainers.
  • add/remove/access factories for CDockables.
  • read/write/apply the layout, this includes reading/writing from files.
  • store properties, like for example the theme.
Author:
Benjamin Sigg

  • Field Details

  • Constructor Details

    • CControl

      public CControl()
      Creates a new control. Note that a control should know the main window of the application, thus CControl(WindowProvider) would be the better choice than this constructor.

    • CControl

      public CControl(JFrame frame)
      Creates a new control
      Parameters:
      frame - the main frame of the application, needed to create dialogs for externalized CDockables

    • CControl

      @Deprecated public CControl(boolean restrictedEnvironment)
      Deprecated.
      it is not necessary to set the restrictedEnvironment parameter anymore, the framework will choose a fitting value itself
      Creates a new control
      Parameters:
      restrictedEnvironment - whether this application runs in a restricted environment and is not allowed to listen for global events.

    • CControl

      public CControl(WindowProvider window)
      Creates a new control
      Parameters:
      window - a provider for the main window of this application. Needed to create dialogs for externalized CDockables. Must not be null, but its search method may return null

    • CControl

      @Deprecated public CControl(JFrame frame, boolean restrictedEnvironment)
      Deprecated.
      it is not necessary to set the restrictedEnvironment parameter anymore, the framework will choose a fitting value itself
      Creates a new control
      Parameters:
      frame - the main frame of the application, needed to create dialogs for externalized CDockables
      restrictedEnvironment - whether this application runs in a restricted environment and is not allowed to listen for global events.

    • CControl

      @Deprecated public CControl(WindowProvider window, boolean restrictedEnvironment)
      Deprecated.
      it is not necessary to set the restrictedEnvironment parameter anymore, the framework will choose a fitting value itself
      Creates a new control
      Parameters:
      window - a provider for the main window of this application. Needed to create dialogs for externalized CDockables. Must not be null, but its search method may return null
      restrictedEnvironment - whether this application runs in a restricted environment and is not allowed to listen for global events.

    • CControl

      public CControl(JFrame frame, CControlFactory factory)
      Creates a new control
      Parameters:
      frame - the main frame of the application, needed to create dialogs for externalized CDockables
      factory - a factory which is used to create new elements for this control.

    • CControl

      public CControl(WindowProvider window, CControlFactory factory)
      Creates a new control
      Parameters:
      window - a provider for the main window of this application. Needed to create dialogs for externalized CDockables. Must not be null, but its search method may return null
      factory - a factory which is used to create new elements for this control.

    • CControl

      protected CControl(WindowProvider window, CControlFactory factory, boolean init)
      Creates a new control
      Parameters:
      window - a provider for the main window of this application. Needed to create dialogs for externalized CDockables. Must not be null, but its search method may return null
      factory - a factory which is used to create new elements for this control.
      init - if true then this constructor calls init(WindowProvider, CControlFactory), otherwise this constructor does nothing and returns immediately. Subclasses should call init(WindowProvider, CControlFactory) in that case.

  • Method Details

    • init

      protected void init(WindowProvider window, CControlFactory factory)
      Initializes the fields of this CControl. This method is called during construction of this CControl. Subclasses may use CControl(WindowProvider, CControlFactory, boolean) to create an uninitialized CControl and then call this method by themselves.
      Parameters:
      window - a provider for the main window of this application. Needed to create dialogs for externalized CDockables. Must not be null, but its search method may return null
      factory - a factory which is used to create new elements for this control.

    • initExtensions

      protected void initExtensions(DockController controller)
      Initializes additional Extensions and registers them at the ExtensionManager of controller.
      Parameters:
      controller - the controller for which additional extensions should be loaded

    • initTransferFocusOnMinimize

      protected void initTransferFocusOnMinimize(DockController controller)
      Adds a CDockableStateListener to this CControl, if a CDockable is minimized, another Dockable receives the focus. Subclasses may override this method to disable or modify the feature.
      Parameters:
      controller - the controller used by this CControl
      See Also:

    • initExternalizeArea

      protected void initExternalizeArea()
      Called during construction of this CControl, this method creates a new CExternalizeArea and registers it as root-station using the unique identifier "external".
      Subclasses may override this method and not create a CExternalizeArea or create a customized CExternalizeArea.

    • initFactories

      protected void initFactories()
      Called during construction of this CControl, this method adds DockFactorys to the intern representation of this CControl.

    • initProperties

      protected void initProperties()
      Sets up the default properties. While subclasses can override this method, they should call this method first. Some parts of this CControl will not work correctly if the wrong properties are set or if no properties are set at all.

    • initIcons

      protected void initIcons()
      Sets up all the default icons used in the realm of this CControl.

    • initTexts

      protected void initTexts()
      Sets up all the default text that is used in the realm of this CControl

    • setLanguage

      public void setLanguage(Locale locale)
      Re-initializes the default text that is used in the realm of this CControl.
      Parameters:
      locale - the new language, must not be null

    • initTexts

      protected void initTexts(Locale locale)
      Sets up all the default text that is used in the realm of this CControl
      Parameters:
      locale - what language to use

    • initPersistentStorage

      protected void initPersistentStorage()
      Creates new ApplicationResources and registers them at the ApplicationResourceManager of this CControl. While subclasses can override this method, they should be aware that missing ApplicationResources will break persistent storage for the location and size of Dockables.

    • addControlListener

      public void addControlListener(CControlListener listener)
      Adds a listener to this control.
      Parameters:
      listener - the new listener

    • removeControlListener

      public void removeControlListener(CControlListener listener)
      Removes a listener from this control.
      Parameters:
      listener - the listener to remove

    • addFocusListener

      public void addFocusListener(CFocusListener listener)
      Adds a new focus listener to this control. The listener gets informed about changes in the focus.
      Parameters:
      listener - the new listener

    • removeFocusListener

      public void removeFocusListener(CFocusListener listener)
      Removes a listener from this control.
      Parameters:
      listener - the listener to remove

    • getFocusedCDockable

      public CDockable getFocusedCDockable()
      Gets the currently focused CDockable. This might be null if some Dockable that is not a CommonDockable has the focus.
      Returns:
      the currently focused CDockable, can be null
      See Also:

    • getFocusHistory

      public CFocusHistory getFocusHistory()
      Gets an object describing which CDockables did have the focus in which order.
      Returns:
      the focus history

    • addVetoFocusListener

      public void addVetoFocusListener(CVetoFocusListener listener)
      Adds a new veto focus listener to this control. The listener gets informed about pending changes in the focus.
      Parameters:
      listener - the new listener

    • removeVetoFocusListener

      public void removeVetoFocusListener(CVetoFocusListener listener)
      Removes a listener from this control.
      Parameters:
      listener - the listener to remove

    • addStateListener

      public void addStateListener(CDockableStateListener listener)
      Adds a global state listener. This has the same effect as adding a state listener to each CDockable that is known to this control.
      Parameters:
      listener - the new listener

    • removeStateListener

      public void removeStateListener(CDockableStateListener listener)
      Removes a global state listener.
      Parameters:
      listener - the listener to remove

    • addPropertyListener

      public void addPropertyListener(CDockablePropertyListener listener)
      Adds a global property listener. This has the same effect as adding a property listener to each CDockable that is known to this control.
      Parameters:
      listener - the new listener

    • removePropertyListener

      public void removePropertyListener(CDockablePropertyListener listener)
      Removes a global listener from this control.
      Parameters:
      listener - the listener to remove

    • addKeyboardListener

      public void addKeyboardListener(CKeyboardListener listener)
      Adds a global keyboard listener to this control. The listener gets informed whenever a key is touched on a Component which is a child of a CDockable.
      Note: listeners directly added to a CDockable will always be informed first.
      Note: if a listener processes the event, then the other listeners will not be informed.
      Parameters:
      listener - the new listener

    • removeKeyboardListener

      public void removeKeyboardListener(CKeyboardListener listener)
      Removes a listener from this control.
      Parameters:
      listener - the listener to remove

    • addGlobalKeyListener

      public void addGlobalKeyListener(KeyListener listener)
      Adds a key listener to this control that will be informed about any KeyEvent that gets processed or analyzed by this control. Especially any event that gets forwarded to a CKeyboardListener gets also forwarded to listener.
      Parameters:
      listener - the new listener

    • removeGlobalKeyListener

      public void removeGlobalKeyListener(KeyListener listener)
      Removes a global KeyListener from this control.
      Parameters:
      listener - the listener to remove

    • addDoubleClickListener

      public void addDoubleClickListener(CDoubleClickListener listener)
      Adds a global mouse double click listener to this control. The listener gets informed whenever the mouse is clicked twice on a Component which is a child of a CDockable.
      Note: listeners directly added to a CDockable will always be informed first.
      Note: if a listener processes the event, then the other listeners will not be informed.
      Parameters:
      listener - the new listener

    • removeDoubleClickListener

      public void removeDoubleClickListener(CDoubleClickListener listener)
      Removes a listener from this control.
      Parameters:
      listener - the listener to remove

    • addVetoClosingListener

      public void addVetoClosingListener(CVetoClosingListener listener)
      Adds listener to this control, the listener will be informed whenever a set of CDockables is about to be closed.
      CVetoClosingListeners added to the CControl are invoked before listeners that are added to a CDockable.
      Parameters:
      listener - the new listener, not null

    • removeVetoClosingListener

      public void removeVetoClosingListener(CVetoClosingListener listener)
      Removes a listener from this control.
      Parameters:
      listener - the listener to remove

    • setIgnoreWorkingForEntry

      public void setIgnoreWorkingForEntry(boolean ignore)
      Informs this CControl whether location of CDockables that are associated with a working area should be stored when storing a layout.
      This method installs a DockSituationIgnore on the intern DockFrontend, the filter is only used for "normal entries", "final entries" (stored when the application shuts down) are not affected.
      The default value for this property is true.
      Parameters:
      ignore - if true then some CDockables are filtered out, otherwise their location is stored.

    • destroy

      public void destroy()
      Frees as much resources as possible. This CControl will no longer work correctly after this method was called.

    • createWorkingArea

      public CWorkingArea createWorkingArea(String uniqueId)
      Creates and adds a new CWorkingArea to this control. The area is not made visible by this method.
      Parameters:
      uniqueId - the unique id of the area
      Returns:
      the new area

    • createMinimizeArea

      public CMinimizeArea createMinimizeArea(String uniqueId)
      Creates a new area where minimized CDockables can be stored. This method adds the new area directly as a root station to this control.
      Parameters:
      uniqueId - a unique identifier
      Returns:
      the new area

    • createGridArea

      public CGridArea createGridArea(String uniqueId)
      Creates a new area where normalized CDockables can be stored. This method adds the new area directly as a root station to this control
      Parameters:
      uniqueId - a unique identifier
      Returns:
      the new area

    • createContentArea

      public CContentArea createContentArea(String uniqueId)
      Creates and adds a new CContentArea.
      Parameters:
      uniqueId - the unique id of the new contentarea, the id must be unique in respect to all other contentareas which are registered at this control.
      Returns:
      the new contentarea
      Throws:
      IllegalArgumentException - if the id is not unique
      NullPointerException - if the id is null

    • addStationContainer

      public void addStationContainer(CStationContainer container)
      Adds container to this control. All children CStations of container will be added as root station to this control.
      Parameters:
      container - the additional set of stations
      Throws:
      IllegalArgumentException - if container is already registered or if the unique identifier of container is already known
      NullPointerException - if container is null

    • removeContentArea

      @Deprecated public void removeContentArea(CContentArea content)
      Deprecated.
      use removeStationContainer(CStationContainer) instead
      Removes content from the list of known contentareas. This also removes the stations of content from this control. Elements aboard the stations are made invisible, but not removed from this control.
      Parameters:
      content - the contentarea to remove
      Throws:
      IllegalArgumentException - if the default-contentarea equals content

    • removeStationContainer

      public void removeStationContainer(CStationContainer container)
      Removes container from the list of known CStationContainers. This also ensures that all child CStations of container are removed. Elements aboard the stations are made invisible, but not removed from this CControl.
      Parameters:
      container - the set of stations to remove
      Throws:
      IllegalArgumentException - if container is the default CContentArea

    • getRegister

      public CControlRegister getRegister()
      Gets the set of dockables, stations and other elements that are used by this control.
      Returns:
      the set of elements, never null

    • getStationContainers

      public List<CStationContainer> getStationContainers()
      Gets an unmodifiable list of all CStationContainers that are registered at this CControl.
      Returns:
      the list of containers

    • getFactory

      public CControlFactory getFactory()
      Gets the factory which is mainly used to create new elements for this control.
      Returns:
      the factory

    • getLocationManager

      public CLocationModeManager getLocationManager()
      Gets the manager that is responsible to handle all changes of the modes (maximized, normalized, ... ) of Dockables.
      Note: clients should be careful when working with the location manager. Changing the properties of the location manager might introduce failures that are not visible directly.
      Returns:
      the manager

    • addDestroyHook

      public void addDestroyHook(DestroyHook hook)
      Adds a destroy-hook. The hook is called when this CControl is destroyed through destroy().
      Parameters:
      hook - the new hook

    • removeDestroyHook

      public void removeDestroyHook(DestroyHook hook)
      Removes a destroy-hook from this CControl.
      Parameters:
      hook - the hook to remove

    • getResources

      public ApplicationResourceManager getResources()
      Grants access to the manager that reads and stores configurations of the common-project.
      Clients can add their own ApplicationResources to this manager, however clients are strongly discouraged from removing ApplicationResource which they did not add themselves.
      Returns:
      the persistent storage

    • putProperty

      public <A> void putProperty(PropertyKey<A> key, A value)
      Changes the value of a property. The incomplete list of properties, in alphabetical order, includes: (properties marked with '*' should not be changed by clients if using the Common project).
      Properties
      BubbleTheme.ACTION_DISTRIBUTORDefault instance of a DockActionDistributor.
      FlatTheme.ACTION_DISTRIBUTORDefault instance of a DockActionDistributor.
      DefaultDockRelocator.AUTO_DROP_ON_ANY_MOUSE_RELEASED_EVENTStop drag-and-drop operations on any mouse-released event (a workaround necessary for some Linux and Mac systems).
      DockTheme.BACKGROUND_PAINT The default value of the BackgroundPaint.
      BasicTheme.BASIC_COLOR_SCHEMEThe ColorScheme to use if the BasicTheme is installed.
      DockTheme.BORDER_MODIFIER The default value of the BorderModifier.
      ScreenDockStation.BOUNDARY_RESTRICTIONHow far the user can push a window with a Dockable out of the screen(s).
      BubbleTheme.BUBBLE_COLOR_SCHEME The ColorScheme to use if the BubbleTheme is installed.
      FlapDockStation.BUTTON_CONTENT Tells what content should be on the buttons that represent minimized Dockables.
      FlapDockStation.BUTTON_CONTENT_FILTER Tells which DockActions should be shown on a button representing a minimized Dockable.
      * CCONTROL The CControl in whose realm the property is read, is a read-only property.
      DockTheme.COMBINER Default value of the Combiner.
      StackDockStation.COMPONENT_FACTORY The factory creating the "tabbed panes" of the StackDockStation.
      DockTheme.DISPLAYER_FACTORY Default value of the DisplayerFactory.
      DockStationDropLayerFactory.DROP_LAYER_FACTORYFactory that defines which parts of the screen are targets for a drag and drop operation/
      PropertyKey.DOCK_STATION_ICON The default icon of DockStations.
      PropertyKey.DOCK_STATION_TITLE The default title of DockStations.
      PropertyKey.DOCK_STATION_TOOLTIP The default tooltip of DockStations.
      PropertyKey.DOCKABLE_ICON The default icon of Dockables.
      DockTheme.DOCKABLE_MOVING_IMAGE_FACTORY Default value of the DockableMovingImageFactory.
      DockTheme.DOCKABLE_SELECTION Default value of the DockableSelection.
      PropertyKey.DOCKABLE_TITLE The default title of Dockables.
      PropertyKey.DOCKABLE_TOOLTIP The default tooltip of Dockables.
      LocationModeManager.DOUBLE_CLICK_STRATEGY Tells what happens if the user double clicks on a DockTitle or a Dockable.
      EclipseTheme.ECLIPSE_COLOR_SCHEME The ColorScheme to use if the EclipseTheme is installed.
      * ScreenDockStation.EXPAND_ON_DOUBLE_CLICK Whether a double click on a child of a ScreenDockStation should maximize the child.
      FlatTheme.FLAT_COLOR_SCHEME The ColorScheme to use if the FlatTheme is installed.
      ScreenDockStation.FULL_SCREEN_STRATEGY Defines when a floating Dockable is considered to be in fullscreen mode.
      * DockFrontend.HIDE_ACCELERATOR The KeyStroke that will call DockFrontend.hide(Dockable)
      DockableSelector.INIT_SELECTION The KeyStroke that opens a window where the user can select a new Dockable.
      StackDockStation.IMMUTABLE_SELECTION_INDEX Prevents the StackDockStation from switching the selected index on a drop operation (but does not prevent the FocusManager from switching the focus!).
      KEY_CLOSE The KeyStroke that closes a CDockable.
      KEY_GOTO_EXTERNALIZED The KeyStroke that externalizes a CDockable.
      KEY_GOTO_MAXIMIZED The KeyStroke that maximizes a CDockable.
      KEY_GOTO_MINIMIZED The KeyStroke that minimizes a CDockable.
      KEY_GOTO_NORMALIZED The KeyStroke that normalizes a CDockable.
      KEY_MAXIMIZE_CHANGE The KeyStroke that either maximizes or normalizes a CDockable.
      KEY_CANCEL_OPERATION The KeyStroke that will cancel the current drag and drop operation.
      FlapDockStation.LAYOUT_MANAGER Tells the FlapDockStation the size and the hold property of its children.
      SplitDockStation.LAYOUT_MANAGER Logic of all SplitDockStations, used when dropping a Dockable or resizing the station.
      TabPane.LAYOUT_MANAGER Defines the size and location of tabs of a stack.
      TabPane.USE_SMALL_MINIMUM_SIZE Use really small minimum sizes for calculating the minimum size of a tab-pane, instead of trying to make the content look good
      * SplitDockStation.MAXIMIZE_ACCELERATOR The KeyStroke that maximizes a child of a SplitDockStation.
      CombinedMenuContent.MENU_CONTENT The menu that shows overflowing Dockables on a stack.
      IconManager.MINIMUM_ICON_SIZEThe expected minimal size of all icons.
      FlapDockStation.MINIMUM_SIZE The minimum size of the Component that represents the FlapDockStation.
      * LocationModeManager.MODE_ENABLEMENT Tells which CDockable is allowed to have which ExtendedMode.
      DockRelocatorMode.NO_COMBINATION_MASK What keys the user has to press during a drag and drop operation to prevent the framework from combining Dockables.
      DockTitle.ORIENTATION_STRATEGY Tells how to rotate text on a DockTitle.
      EclipseTheme.PAINT_ICONS_WHEN_DESELECTED Whether to paint icons on unselected tabs if using the EclipseTheme.
      PlaceholderStrategy.PLACEHOLDER_STRATEGY A strategy that creates placeholders for Dockables, see CPlaceholderStrategy.
      RESIZE_LOCK_CONFLICT_RESOLVER Tells what happens if two CDockables have a locked size and the user is resizing the parent of these two elements.
      DockController.RESTRICTED_ENVIRONMENT Tells whether the application runs as applet/with webstart or as free or authenticated application.
      DockRelocatorMode.SCREEN_MASK The keys the user has to press during a drag and drop operation to ensure that the Dockable is added to a ScreenDockStation.
      SingleTabDecider.SINGLE_TAB_DECIDER Tells which Dockables should be presented with a single tab - even if there is no reason to show a tab.
      DockTheme.STATION_PAINT The default value of StationPaint.
      AWTComponentCaptureStrategy.STRATEGY How to make an image of an AWT component.
      DisablingStrategy.STRATEGYWhich element to disable.
      StackDockStation.TAB_CONTENT_FILTER A filter deciding what content to show on a tab of a StackDockStation.
      EclipseTheme.TAB_PAINTER The look of tabs if using the EclipseTheme.
      StackDockStation.TAB_PLACEMENT The location of the tabs on a StackDockStation.
      EclipseTheme.THEME_CONNECTOR Detailed instructions how to present a Dockable if using the EclipseTheme.
      FlapDockStation.WINDOW_FACTORY A factory creating FlapWindows for the FlapDockStation.
      ScreenDockStation.WINDOW_FACTORY A factory creating ScreenDockWindows for the ScreenDockStation.
      Type Parameters:
      A - the type of the value
      Parameters:
      key - the name of the property
      value - the new value, can be null

    • putProperty

      protected <A> void putProperty(PropertyKey<A> key, A value, Priority priority)
      Changes the value of a property.
      Type Parameters:
      A - the type of the value
      Parameters:
      key - the name of the property
      value - the new value, can be null
      priority - the priority of the new value
      See Also:

    • getProperty

      public <A> A getProperty(PropertyKey<A> key)
      Gets the value of a property.
      Type Parameters:
      A - the type of the property
      Parameters:
      key - the name of the property
      Returns:
      the value or null

    • getContentArea

      public CContentArea getContentArea()
      Gets the element that should be in the center of the mainframe. The CContentArea is created the first time this method is called.
      Returns:
      the center of the mainframe of the application

    • addStation

      public void addStation(CStation<?> station)
      Adds an additional station to this control.
      Parameters:
      station - the new station

    • addStation

      public void addStation(CStation<?> station, boolean root)
      Adds an additional station to this control. Most CStations should be root-stations, even if they are nested.
      Parameters:
      station - the new station
      root - true if the station should be a root station. A root station may or may not have any parent station. The location of a CDockable is always relative to the first root station that can be found when travelling the tree upwards. For most stations this attribute should be true

    • isRootStation

      public boolean isRootStation(CStation<?> station)
      Tells whether station was added to this CControl with the root flag set to true.
      Parameters:
      station - the station whose root flag is asked
      Returns:
      the value of the root flag or false if station is not registered at all

    • removeStation

      public void removeStation(CStation<?> station)
      Removes a CStation from this control. It is unspecified what happens with the children on station
      Parameters:
      station - the station to remove

    • getStations

      public List<CStation<?>> getStations()
      Gets an unmodifiable list of all stations that are currently registered at this control.
      Returns:
      the list of stations

    • getStation

      public CStation<?> getStation(DockStation intern)
      Searches the CStation whose internal representation is intern.
      Parameters:
      intern - the internal representation
      Returns:
      the station or null

    • findStation

      public CStation<?> findStation(DockStation intern)
      Searches along the path to the root DockStation the first CStation that matches the DockStation. If intern is a CStation, then this method behaves as if getStation(DockStation) was called. If the parent of intern is a CStation, then this method behaves as if getStation( intern.getDockParent() ) was called.
      Parameters:
      intern - the starting point for the search of a CStation
      Returns:
      the next CStation on the path from intern (incl.) to the root station (incl.)

    • getStation

      public CStation<?> getStation(String id)
      Searches the CStation with unique identifier id.
      Parameters:
      id - the identifier
      Returns:
      the station or null

    • addDockable

      public <S extends SingleCDockable> S addDockable(S dockable)
      Adds a dockable to this control. The dockable can be made visible afterwards. This method will do nothing if dockable was already registered at this CControl.
      Type Parameters:
      S - the type of the new element
      Parameters:
      dockable - the new element to show
      Returns:
      dockable
      Throws:
      IllegalArgumentException - if dockable already is registered at another CControl or if the unique id of dockable already is used for another object

    • getSingleDockable

      public SingleCDockable getSingleDockable(String id)
      Searches for the SingleCDockable which has the unique identifier id.
      Parameters:
      id - the identifier to look out for
      Returns:
      the element with that identifier or null

    • removeSingleDockable

      public boolean removeSingleDockable(String id)
      Removes the SingleCDockable with the identifier id.
      Parameters:
      id - the id of the element to remove
      Returns:
      true if the element was removed, false otherwise

    • removeDockable

      public boolean removeDockable(SingleCDockable dockable)
      Removes dockable from this control. The location information for dockable remains stored if either there is a SingleCDockableFactory registered or the MissingCDockableStrategy tells to store the values.
      Parameters:
      dockable - the element to remove
      Returns:
      true if the element was removed, false otherwise

    • addSingleDockableFactory

      public void addSingleDockableFactory(String id, SingleCDockableFactory backupFactory)
      Adds a factory to this control. The factory will be used to create and add a SingleCDockable when one is requested that is not yet in the cache.
      If there is already information for id available and id should be visible, then the factory will be used instantaneously.
      Factories added with a specific identifier always have higher priority than factories added with a filter, see addSingleDockableFactory(Filter, SingleCDockableFactory).
      Parameters:
      id - the id of the dockable that might be requested
      backupFactory - the new factory

    • addSingleDockableFactory

      public void addSingleDockableFactory(Filter<String> ids, SingleCDockableFactory factory)
      Adds a factory to this control. The factory will be used to create and add a SingleCDockable when one is requested that is not yet in the cache.
      If there is already information for identifiers that are included by ids available and if they should be visible, then the factory will be used instantaneously to create these elements. During this action factory has a higher priority than any other factory.
      Factories added with a general filter always have lower priority than factories that were added with a specific identifier. The factories are stored in a list and a search starts at the front of that list, so a factory added early has higher priority than a factory that was added lately.
      Parameters:
      ids - a filter telling which dockables can be handled by factory
      factory - the new factory

    • getSingleDockableFactory

      public SingleCDockableFactory getSingleDockableFactory(String id)
      Searches the SingleCDockableFactory which is responsible for creating the SingleCDockable with identifier id. This method first searches for a factory which was added with a specific identifier (addSingleDockableFactory(String, SingleCDockableFactory)), if nothing is found then the factories with a filter are searched (addSingleDockableFactory(Filter, SingleCDockableFactory)).
      Parameters:
      id - the identifier of some factory
      Returns:
      the factory or null

    • removeSingleDockableFactory

      public void removeSingleDockableFactory(SingleCDockableFactory factory)
      Removes all occurrences of factory. Any location information that was held because of the existence of factory will be removed as well.
      Parameters:
      factory - the factory to remove

    • removeSingleDockableFactory

      public void removeSingleDockableFactory(String id)
      Removes a factory from this control. Location information for id will be deleted if neither a SingleCDockable is added nor the MissingCDockableStrategy tells to store the information.
      Parameters:
      id - the name of the factory
      See Also:

    • addDockable

      public <M extends MultipleCDockable> M addDockable(M dockable)
      Adds a dockable to this control. The dockable can be made visible afterwards. A random identifier is assigned to dockable, clients can also use addDockable(String, MultipleCDockable) if they want to specify the identifier themselves.
      Type Parameters:
      M - the type of the new element
      Parameters:
      dockable - the new element to show
      Returns:
      dockable
      Throws:
      IllegalArgumentException - if either the factory of dockable is null, or is not registered (see addMultipleDockableFactory(String, MultipleCDockableFactory)).

    • addDockable

      public <M extends MultipleCDockable> M addDockable(String uniqueId, M dockable)
      Adds a dockable to this control. The dockable can be made visible afterwards. This method will throw an exception when the unique identifier is already in use. Clients can also use addDockable(MultipleCDockable) if they want to assign a random identifier to dockable.
      Type Parameters:
      M - the type of the new element
      Parameters:
      uniqueId - id the unique id of the new element
      dockable - the new element to show
      Returns:
      dockable
      Throws:
      IllegalArgumentException - if the unique identifier is already in use, if dockable is already used elsewhere, if there is no factory for dockable
      NullPointerException - if any argument is null

    • replace

      public void replace(MultipleCDockable oldDockable, MultipleCDockable newDockable)
      Replaces oldDockable with newDockable. The new dockable inherits settings and location of the old one.
      Parameters:
      oldDockable - the old dockable, not null
      newDockable - the new dockable, not null

    • getMultipleDockable

      public MultipleCDockable getMultipleDockable(String id)
      Searches and returns the one MultipleCDockable which uses the unique identifier id.
      Parameters:
      id - the identifier to look out for
      Returns:
      the element using id or null if nothing was found

    • getUniqueId

      public String getUniqueId(MultipleCDockable dockable)
      Gets the unique identifier which is used internally for dockable
      Parameters:
      dockable - the item to search
      Returns:
      the internal unique identifier of dockable, may be null

    • removeDockable

      public void removeDockable(MultipleCDockable dockable)
      Removes a dockable from this control. The dockable is made invisible.
      Parameters:
      dockable - the element to remove

    • getCDockableCount

      public int getCDockableCount()
      Gets the number of CDockables that are registered in this CControl.
      Returns:
      the number of dockables

    • getCDockable

      public CDockable getCDockable(int index)
      Gets the index'th dockable that is registered in this control
      Parameters:
      index - the index of the element
      Returns:
      the selected dockable

    • addMultipleDockableFactory

      public void addMultipleDockableFactory(String id, MultipleCDockableFactory<?,?> factory)
      Adds a factory to this control. The factory will create MultipleCDockables when a layout is loaded. The NullMultipleCDockableFactory will always be preinstalled using the empty identifier.
      Parameters:
      id - the unique id of the factory, must consist of at least one character
      factory - the new factory

    • getMultipleDockableFactory

      public MultipleCDockableFactory<?,?> getMultipleDockableFactory(String id)
      Searches for the MultipleCDockableFactory with the identifier id.
      Parameters:
      id - the identifier to search for
      Returns:
      the factory or null

    • getFactoryId

      public String getFactoryId(MultipleCDockableFactory<?,?> factory)
      Gets the unique identifier of factory.
      Parameters:
      factory - the factory to search
      Returns:
      the unique identifier or null

    • removeMultipleDockableFactory

      public void removeMultipleDockableFactory(String id)
      Removes the MultipleCDockableFactory with identifier id from this control. As a side effect all MultipleCDockables which use that factory are removed as well. Nothing happens if there is no factory registered with id.
      Parameters:
      id - the identifier of the factory to remove

    • setDefaultLocation

      public void setDefaultLocation(CLocation defaultLocation)
      Sets the location where CDockables are opened when there is nothing else specified for these CDockables.
      Parameters:
      defaultLocation - the location, can be null

    • getDefaultLocation

      public CLocation getDefaultLocation()
      Gets the location where CDockables are opened when nothing else is specified.
      Returns:
      the location, might be null
      See Also:

    • setMaximizeArea

      public void setMaximizeArea(String id)
      Makes sure that all CDockables are maximized onto the area which is registered under the given unique id.
      Parameters:
      id - the unique id of the area
      See Also:

    • setGroupBehavior

      public void setGroupBehavior(CGroupBehavior behavior)
      Sets the CGroupBehavior. The behavior decides what happens when the user wants to change the ExtendedMode of a CDockable.
      To be exact: the group behavior is applied for a call to CDockable.setExtendedMode(ExtendedMode) respective a call to LocationModeManager.setMode(Dockable, ExtendedMode). The buttons that are visible to the user all link to these methods.
      Parameters:
      behavior - the new behavior, not null

    • getGroupBehavior

      public CGroupBehavior getGroupBehavior()
      Gets the currently used CGroupBehavior.
      Returns:
      the current behavior, not null
      See Also:

    • setTheme

      @Deprecated public void setTheme(DockTheme theme)
      Deprecated.
      replaced by setTheme(String). While this method still works, the theme will not get stored persistent and any module using the ThemeMap (getThemes()) will not be informed about the change.
      Sets the theme of the elements in the realm of this control.
      Parameters:
      theme - the new theme

    • setTheme

      public void setTheme(String theme)
      Sets the theme of the elements in the realm of this control. The String theme is used as key for ThemeMap.select(String).
      Parameters:
      theme - the name of the theme, this might be one of ThemeMap.KEY_BASIC_THEME, ThemeMap.KEY_BUBBLE_THEME, ThemeMap.KEY_ECLIPSE_THEME, ThemeMap.KEY_FLAT_THEME or ThemeMap.KEY_SMOOTH_THEME. This can also be a any other string which was used for ThemeMap.put(String, ThemeFactory), ThemeMap.add(String, ThemeFactory) or ThemeMap.insert(int, String, ThemeFactory).

    • getThemes

      public ThemeMap getThemes()
      Gets the list of installed themes.
      Returns:
      the list of themes

    • setMissingPerspectiveStrategy

      public void setMissingPerspectiveStrategy(MissingPerspectiveStrategy missingPerspectiveStrategy)
      Sets a strategy that creates missing CStationPerspectives.
      Parameters:
      missingPerspectiveStrategy - the strategy, not null

    • getMissingPerspectiveStrategy

      public MissingPerspectiveStrategy getMissingPerspectiveStrategy()
      Gets the strategy that is used to create missing CStationPerspective.
      Returns:
      the strategy, not null

    • getPerspectives

      public CControlPerspective getPerspectives()
      Grants access to the perspective API which allows clients to build complex layouts without the need to create any dockables or stations.
      Returns:
      access a wrapper around this CControl allowing to inspect and modify the layouts that are available
      See Also:

    • setRootWindow

      public void setRootWindow(WindowProvider window)
      Sets the root window of the application. The root window is used as owner of any dialog that is created. Already existing dialogs may be closed and reopened in order to change the owner. Short living dialogs will not change their owner.
      Parameters:
      window - the new owner, can be null

    • getRootWindow

      public WindowProvider getRootWindow()
      Gets the root window of the application. Note that this method might not return the same object as given to setRootWindow(WindowProvider), however the provide returned by this method will return the same window as specified by setRootWindow(WindowProvider).
      Returns:
      the provider, never null

    • getPreferences

      public PreferenceStorage getPreferences()
      Gets the storage container for PreferenceModels for this control. The contents of this container are stored in the resource manager.
      Returns:
      the storage for preferences
      See Also:

    • setPreferenceModel

      public void setPreferenceModel(PreferenceModel preferenceModel)
      Sets the PreferenceModel which will be used to translate between this and the preferences. This model can be set to null.
      The default value of this property is null.
      Parameters:
      preferenceModel - the new model, it will used to translate the contents of getPreferences() immediately, can be null

    • getPreferenceModel

      public PreferenceModel getPreferenceModel()
      Gets the preference model which is used to translate between the preferences and this.
      Returns:
      the model, can be null
      See Also:

    • setMissingStrategy

      public void setMissingStrategy(MissingCDockableStrategy missingStrategy)
      Sets the strategy that tells what to do if layout information of a missing CDockable is found.
      Parameters:
      missingStrategy - the strategy, null will set the default strategy

    • getMissingStrategy

      public MissingCDockableStrategy getMissingStrategy()
      Gets the strategy that tells what to do if layout information of a missing CDockable is found.
      Returns:
      the strategy, never null

    • addResizeRequestListener

      public void addResizeRequestListener(ResizeRequestListener listener)
      Adds a ResizeRequestListener to this CControl. The listener will be informed when the resize requests of a CDockable should be processed.
      Parameters:
      listener - the new listener, not null

    • removeResizeRequestListener

      public void removeResizeRequestListener(ResizeRequestListener listener)
      Removes a ResizeRequestListener from this CControl.
      Parameters:
      listener - the listener to remove

    • handleResizeRequests

      public void handleResizeRequests()
      Informs all ResizeRequestListeners, that the resize request of all CDockables should be processed. There are no guarantees that a resize requests can be granted or even gets processed.
      All requests, independent from whether they were processed, will be deleted by this method.
      Note that a request might conflict with a "resize lock" CDockable.isResizeLockedHorizontally() and CDockable.isResizeLockedVertically(). The behavior of that case is not specified, but clients can assume that the locked components introduce additional resize requests.

    • intern

      public CDockFrontend intern()
      Gets the representation of the layer beneath the common-layer.
      Returns:
      the entry point to DockingFrames

    • getController

      public DockController getController()
      Gets the DockController which is used by this CControl.
      Returns:
      the core system of the framework

    • getIcons

      public IconManager getIcons()
      Grants access to all the Icons that are used within the realm of this CControl. Clients are free to modify the set of icons.
      Returns:
      the set of icons that are used

    • setRevertToBasicModes

      public void setRevertToBasicModes(boolean revert)
      Tells this control whether basic modes like "normalized", "minimized" or "externalized" are forced upon Dockables after loading a persistent layout. Basically if this property is set, then all Dockables are un-maximized after a layout change. The default value of this property is true.
      The reasons behind forcing basic modes are:
      • If the user changes the layout, he/she most likely would like to see the effects. A maximized Dockable would hide the effects.
      • For the user re-maximizing an element requires no more than one click with the mouse. It's a cheap operation.
      • It is an additional layer of security preventing Dockables from being in the wrong position if the client was stared with new settings.
      Parameters:
      revert - whether non-basic modes should be forbidden when loading a persistent layout

    • isRevertToBasicModes

      public boolean isRevertToBasicModes()
      Tells whether basic modes are forcibly applied when loading a persistent layout.
      Returns:
      whether the non-basic modes are forbidden
      See Also:

    • setTransferFocusOnMinimize

      public void setTransferFocusOnMinimize(boolean transferFocusOnMinimize)
      If a CDockable is minimized, the focus can be automatically transferred to another CDockable. This feature is implemented by the method initTransferFocusOnMinimize(DockController), which may be overridden by subclasses.
      Parameters:
      transferFocusOnMinimize - whether to enable the feature or not (default is true)

    • isTransferFocusOnMinimize

      public boolean isTransferFocusOnMinimize()
      If a CDockable is minimized, the focus can be automatically transferred to another Dockable.
      Returns:
      whether the focus will be transferred
      See Also:

    • write

      public void write(File file) throws IOException
      Writes the current and all known layouts into file.
      This is the same as calling getResources().writeFile( file ).
      Parameters:
      file - the file to override
      Throws:
      IOException - if the file can't be written

    • write

      public void write(DataOutputStream out) throws IOException
      Writes the current and all known layouts into out.
      This is the same as calling getResources().writeStream( out ).
      Parameters:
      out - the stream to write into
      Throws:
      IOException - if the stream is not writable

    • writeXML

      public void writeXML(XElement element)
      Writes the current and all known layouts into element.
      This is the same as calling getResources().writeXML( element ).
      Parameters:
      element - the element to write into

    • writeXML

      public void writeXML(File file) throws IOException
      Writes the current and all known layouts into file in xml format.
      Parameters:
      file - the file to write into
      Throws:
      IOException - if the file is not writable

    • read

      public void read(File file) throws IOException
      Reads the current and other known layouts from file.
      This is the same as calling getResources().readFile( file ).
      Parameters:
      file - the file to read from
      Throws:
      IOException - if the file can't be read

    • read

      public void read(DataInputStream in) throws IOException
      Reads the current and other known layouts from in.
      This is the same as calling getResources().readStream( in ).
      Parameters:
      in - the stream to read from
      Throws:
      IOException - if the stream can't be read

    • readXML

      public void readXML(XElement element)
      Reads the current and other known layouts from element.
      This is the same as calling getResources().readXML( element ).
      Parameters:
      element - the element to read
      Throws:
      XException - if the xml file has the wrong structure

    • readXML

      public void readXML(File file) throws IOException
      Reads the current and other known layouts from file.
      Parameters:
      file - the file to open and to read
      Throws:
      IOException - if the file cannot be read
      XException - if the xml file has the wrong structure

    • save

      public String save()
      Saves the current layout with the current name. Does nothing if there is no name for the current layout.
      Returns:
      the name that was used to save the layout
      See Also:

    • save

      public String save(boolean includeWorkingAreas)
      Saves the current layout with the current name. Does nothing if there is no name for the current layout.
      Parameters:
      includeWorkingAreas - whether the content of the CStations that are marked as working area should be stored as well.
      Returns:
      the name that was used to save the layout
      See Also:

    • save

      public void save(String name)
      Stores the current layout with the given name. This creates "entry" (partial) layout information.
      Parameters:
      name - the name of the current layout.

    • save

      public void save(String name, boolean includeWorkingAreas)
      Stores the current layout with the given name. This creates "entry" (partial) layout information.
      Parameters:
      name - the name of the current layout.
      includeWorkingAreas - whether the content of the CStations that are marked as working area should be stored as well.

    • load

      public void load(String name)
      Loads an earlier stored layout.
      Parameters:
      name - the name of the layout.

    • load

      public void load(String name, boolean includeWorkingAreas)
      Loads an earlier stored layout.
      Parameters:
      name - the name of the layout.
      includeWorkingAreas - whether the content of the CStations that are marked as working area should be updated as well. This value should be the same as was used to call save(String, boolean).

    • delete

      public void delete(String name)
      Deletes a layout that has been stored earlier.
      Parameters:
      name - the name of the layout to delete

    • layouts

      public String[] layouts()
      Gets a list of all layouts that are currently known.
      Returns:
      the list of layouts

    • getLayout

      public String getLayout()
      Gets the name of the current layout (the one with which save(String) was called). The current layout may not have a name if it was never saved. The result of this method will be a String that is part of layouts().
      Returns:
      the name of the current layout, or null