Package bibliothek.gui.dock.common.intern

Interface CDockable

All Known Subinterfaces:
MultipleCDockable, SingleCDockable
All Known Implementing Classes:
AbstractCDockable, AbstractDockableCStation, CGridArea, CWorkingArea, DefaultCDockable, DefaultMultipleCDockable, DefaultSingleCDockable, ExternalizingCGridArea
@FrameworkOnly public interface CDockable
A basic element representing some Component and a wrapper around a Dockable.
Note: This interface is not intended to be implemented by clients. Clients should either extend the class AbstractCDockable or use one of DefaultSingleCDockable or DefaultMultipleCDockable.
Author:
Benjamin Sigg

  • Field Details

  • Method Details

    • addCDockableStateListener

      void addCDockableStateListener(CDockableStateListener listener)
      Adds a state listener to this dockable, the listener will be informed of changes of this dockable.
      Parameters:
      listener - the new listener

    • addCDockablePropertyListener

      void addCDockablePropertyListener(CDockablePropertyListener listener)
      Adds a property listener to this dockable, the listener will be informed of changes of this dockable.
      Parameters:
      listener - the new listener

    • addCDockableLocationListener

      void addCDockableLocationListener(CDockableLocationListener listener)
      Adds a listener to this dockable which gets informed if the location or the visibility changes.
      Parameters:
      listener - the new listener

    • removeCDockableStateListener

      void removeCDockableStateListener(CDockableStateListener listener)
      Removes a state listener from this dockable.
      Parameters:
      listener - the listener to remove

    • removeCDockablePropertyListener

      void removeCDockablePropertyListener(CDockablePropertyListener listener)
      Removes a property listener from this dockable.
      Parameters:
      listener - the listener to remove

    • removeCDockableLocationListener

      void removeCDockableLocationListener(CDockableLocationListener listener)
      Removes listener from this dockable
      Parameters:
      listener - the listener to remove

    • addFocusListener

      void addFocusListener(CFocusListener listener)
      Adds a focus listener to this dockable. The focus listener gets informed when this dockable gains or loses the focus.
      Parameters:
      listener - the new listener

    • removeFocusListener

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

    • addKeyboardListener

      void addKeyboardListener(CKeyboardListener listener)
      Adds a keyboard listener to this dockable. The listener gets informed when a key is pressed or released on this dockable.
      Parameters:
      listener - the new listener

    • removeKeyboardListener

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

    • addDoubleClickListener

      void addDoubleClickListener(CDoubleClickListener listener)
      Adds a new listener to this dockable. The listener gets informed when the mouse is clicked twice on this dockable.
      Parameters:
      listener - the new listener

    • removeDoubleClickListener

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

    • addVetoClosingListener

      void addVetoClosingListener(CVetoClosingListener listener)
      Adds a veto-listener to this dockable, the listener will be informed before this dockable gets closed and can issue a veto. The listener will receive a CVetoClosingEvent which contains only this CDockable (even if other dockables are closed at the same time).
      CVetoClosingListeners added to the CControl are invoked before listeners that are added to a CDockable.
      Parameters:
      listener - the new listener
      See Also:

    • removeVetoClosingListener

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

    • isMinimizable

      boolean isMinimizable()
      Tells whether this CDockable can be minimized by the user.
      Returns:
      true if this element can be minimized

    • isMaximizable

      boolean isMaximizable()
      Tells whether this CDockable can be maximized by the user.
      Returns:
      true if this element can be maximized

    • isExternalizable

      boolean isExternalizable()
      Tells whether this CDockable can be externalized by the user.
      Returns:
      true if this element can be externalized

    • isNormalizeable

      boolean isNormalizeable()
      Tells whether this CDockable can be normalized by the user. Usually this method should return true for any dockable, as "normalizing" is the default mode.
      Clients should not override this method.
      Returns:
      true, unless a subclass requires very special behavior.

    • isStackable

      boolean isStackable()
      Tells whether this CDockable can be combined with another Dockable to create a stack.
      Returns:
      true if this element can be combined with another Dockable, normally true should be the answer.

    • isCloseable

      boolean isCloseable()
      Tells whether this CDockable can be closed by the user. A close-button has to be provided by the CDockable itself. The best way to do that is to instantiate a CloseActionSource and include this source in the array that is returned by CommonDockable.getSources().
      Returns:
      true if this element can be closed

    • isResizeLockedVertically

      boolean isResizeLockedVertically()
      Tells whether the height of this CDockable should remain the same when its parent changes the size. This has only effect if the parent can choose the size of its children. A lock is no guarantee for staying with the same size, the user still can resize this CDockable.
      Returns:
      true if the height of this CDockable should remain the same during resize events of the parent.

    • isResizeLockedHorizontally

      boolean isResizeLockedHorizontally()
      Tells whether the width of this CDockable should remain the same when its parent changes the size. This has only effect if the parent can choose the size of its children. A lock is no guarantee for staying with the same size, the user still can resize this CDockable.
      Returns:
      true if the width of this CDockable should remain the same during resize events of the parent.

    • getAndClearResizeRequest

      RequestDimension getAndClearResizeRequest()
      Gets the preferred size of this CDockable. The preferred size will be used to resize this CDockable when CControl.handleResizeRequests() is called. There are no guarantees that the request can be granted, or will be handled at all.
      Calling this method should delete the request, so calling this method twice should have the effect, that the second time null is returned.
      Returns:
      the next requested size or null

    • setVisible

      void setVisible(boolean visible)
      Shows or hides this CDockable. If this CDockable is not visible and is made visible, then the framework tries to set its location at the last known position.
      Subclasses should call CControlAccess.show(CDockable) or CControlAccess.hide(CDockable).
      Parameters:
      visible - the new visibility state
      Throws:
      IllegalStateException - if this dockable can't be made visible
      See Also:

    • isVisible

      boolean isVisible()
      Tells whether this CDockable is currently visible or not. Visibility means that this CDockable is in the tree structure of DockingFrames and has a parent. Being in the structure does not imply being visible on the screen: If some JFrame is not shown, or some DockStation not properly added to a parent component, then a visible CDockable can be invisible for the user. For CDockables that are also root-CStation this method will always return true.
      Clients interested in whether the user can actually see this dockable should call isShowing().
      Subclasses should return the result of CControlAccess.isVisible(CDockable).
      Returns:
      true if this CDockable can be accessed by the user through a graphical user interface.
      See Also:

    • hasParent

      boolean hasParent()
      Tells whether this CDockable has a root station as parent. Having a root station as parent implies isVisible(). For root-CStation this method will return false if they do not have a parent, they are not considered to be parents of themselves.
      Subclasses should return the result of CControlAccess.hasParent(CDockable).
      Returns:
      true if this dockable has a parent and is in the tree

    • isDockableVisible

      @Deprecated @Todo(compatibility=BREAK_MAJOR, priority=ENHANCEMENT, target=VERSION_1_1_3, description="remove this method") boolean isDockableVisible()
      Deprecated.
      this method gets replaced by isShowing(), which offers the exact same information. This method will be removed in a future release
      Tells whether this CDockable is currently visible to the user. A CDockable which is not visible, is not dockable visible either. The method does not take into account that a frame may be positioned such that it is not entirely visible on the screen. Neither does the method take into account, that a frame may be minimized.
      Returns:
      true if the user should be able to see this item

    • isShowing

      boolean isShowing()
      Tells whether this CDockable is currently visible to the user. A CDockable which is not visible, is not showing either. The method does not take into account that a frame may be positioned such that it is not entirely visible on the screen. The method may or may not take into account, that a frame may be minimized.
      Clients interested in monitoring this property can add a CDockableLocationListener to this dockable.
      Returns:
      true if the user should be able to see this item
      See Also:

    • setLocation

      void setLocation(CLocation location)
      Sets the location of this CDockable. If this CDockable is visible, than this method will take immediately effect. Otherwise the location will be stored in a cache and read as soon as this CDockable is made visible.
      Note that the location can only be seen as a hint, the framework tries to fit the location as good as possible, but there are no guarantees.
      Subclasses should call CControlAccess.getLocationManager() and CLocationModeManager.setLocation(bibliothek.gui.Dockable, CLocation).
      Parameters:
      location - the new location, null is possible, but will not move the CDockable immediately
      See Also:

    • setLocationsAside

      void setLocationsAside(CDockable dockable)
      Sets the location of this CDockable aside dockable in all ExtendedModes. If this Dockable is visible, then it may or may not change its location and ExtendedMode. Note that dockable and this must not be the same object, and that both CDockables must be registered at a CControl.
      Parameters:
      dockable - the item whose locations should be copied
      Throws:
      IllegalArgumentException - if dockable is null, not registered, the same as this, or has a different working area
      IllegalStateException - if this is not registered at the same CControl as dockable

    • setLocationsAside

      boolean setLocationsAside(Filter<CDockable> filter)
      Traverses the history of focused CDockables, and selects the newest item with focus and matching filter for calling setLocationsAside(CDockable).
      Parameters:
      filter - to select a CDockable which did have the focus
      Returns:
      true if an old focused Dockable was found, false if not

    • setLocationsAsideFocused

      boolean setLocationsAsideFocused()
      Searches for the last focused CDockable with the same working area as this, and calls setLocationsAside(CDockable) with it.
      Note that if this dockable is visible, then it may or may not change its location. This method should be called before making the dockable visible.
      Returns:
      true if the last focused CDockable was found, false otherwise. If false then no action was performed

    • getBaseLocation

      CLocation getBaseLocation()
      Gets the location of this CDockable. If this CDockable is visible, then a location will always be returned. Otherwise a location will only be returned if it just was set using setLocation(CLocation).
      Returns:
      the location or null

    • getAutoBaseLocation

      CLocation getAutoBaseLocation(boolean noBackwardsTransformation)
      Tries to find out at which location this CDockable may appear if it would be made visible. The default implementation of this method has severe limitations:
      • Random placements are not considered and the result will be null
      • Placeholders are not considered, if this CDockable is associated with a placeholder, then the placeholder information will be completely lost.
      • This CDockable must not be visible and it must be registered at a CControl.
      To be more precise: the location returned by this method may not be the actual location where this dockable appears because this method does not consider all circumstances.
      Clients can make use of this method in two ways:
      • They can find out whether the dockable has a location, or will be placed randomly (in which case the result of this method is null)
      • They can override this method in which case the CDockable will appear at the exact location that is returned by this method ignoring any other settings.
      Parameters:
      noBackwardsTransformation - if true, then this method should not convert any DockableProperty back to a CLocation, instead it should return null if such a conversion would be necessary. This way the method does return null in any case where information (e.g. placeholders) could be lost due to the limitations of CLocation
      Returns:
      The expected location of this invisible CDockable, this may either be the location that was set by calling setLocation(CLocation), the last location of this dockable when it was visible, the default location of the CControl or the default location for the normalized extended mode. A value of null is returned if this CDockable would appear at a random location, is not registered at a CControl or is already visible.

    • setExtendedMode

      void setExtendedMode(ExtendedMode extendedMode)
      Sets how and where this CDockable should be shown. Conflicts with isExternalizable(), isMaximizable() and isMinimizable() will just be ignored. Implementations should call LocationModeManager.setMode(Dockable, ExtendedMode).
      If this dockable is not visible, then it will be made visible in order to apply the extendedMode.
      Parameters:
      extendedMode - the size and location

    • getExtendedMode

      ExtendedMode getExtendedMode()
      Gets the size and location of this CDockable. Implementations should return LocationModeManager.getMode(Dockable).
      Returns:
      the size and location or null if this CDockable is not part of an CControl. May be null if this dockable is not visible.

    • getGrouping

      DockableGrouping getGrouping()
      Gets an algorithm that tells how this CDockable attempts to group itself automatically with other Dockables. The algorithm is able to rewrite the location of this CDockable every time when it is moved to a new location, assuming that no stronger mechanism, or the user, already defined a location.
      Returns:
      the grouping behavior, or null

    • setWorkingArea

      void setWorkingArea(CStation<?> area)
      Sets the parent of this CDockable. This method can be called by the client or indirectly through setLocation(CLocation).
      Parameters:
      area - the new parent or null

    • getWorkingArea

      CStation<?> getWorkingArea()
      Gets the parent of this CDockable, this should be the same as set by the last call of setWorkingArea(CStation).
      Returns:
      the parent or null

    • setMinimizedSize

      void setMinimizedSize(Dimension size)
      Sets the size of this CDockable when this CDockable is minimized and on a popup window.
      Parameters:
      size - the size

    • getMinimizedSize

      Dimension getMinimizedSize()
      Gets the size which is used when this CDockable is minimized and on a popup window. If a value below 0 is set, then the default size is used.
      Returns:
      the size

    • setSticky

      void setSticky(boolean sticky)
      Sets whether this CDockable should remain visible when minimized and without focus.
      Parameters:
      sticky - whether to remain visible

    • isSticky

      boolean isSticky()
      Tells whether this CDockable remains visible when minimized and without focus.
      Returns:
      true if this remains visible, false otherwise

    • setStickySwitchable

      void setStickySwitchable(boolean switchable)
      Sets whether the user can switch the isSticky() property by clicking on a button that is presented by the FlapDockStation.
      Parameters:
      switchable - whether the user is able to switch the hold property

    • isStickySwitchable

      boolean isStickySwitchable()
      Tells whether the isSticky() property can be changed by the user by clicking a button that is displayed on the FlapDockStation.
      Returns:
      true if the user is able to switch the property, false otherwise

    • isTitleShown

      boolean isTitleShown()
      Tells whether this CDockable shows its title or not. Note that some DockThemes might override this setting.
      Returns:
      true if the title is shown, false otherwise.

    • isSingleTabShown

      boolean isSingleTabShown()
      Tells whether a single tab should be shown for this CDockable. Some DockThemes might ignore this setting.
      Returns:
      true if a single tab should be shown, false if not

    • isEnabled

      boolean isEnabled(EnableableItem item)
      Tells whether a part of this dockable is enabled.
      Parameters:
      item - the part to check
      Returns:
      whether item is enabled, the default result should be true

    • getFocusComponent

      Component getFocusComponent()
      Gets the Component which should receive the focus once this CDockable is focused.
      Returns:
      the element which should receive the focus, can be null

    • intern

      CommonDockable intern()
      Gets the intern representation of this CDockable.
      Returns:
      the intern representation.

    • asStation

      CStation<?> asStation()
      Gets this or an object representing this as CStation.
      Returns:
      this as station or null

    • setControlAccess

      @FrameworkOnly void setControlAccess(CControlAccess control)
      Sets the CControl which is responsible for this CDockable. Subclasses must call CControlAccess.link(CDockable, CDockableAccess) to grant the CControl access to the internal properties of this CDockable. link can also be used to revoke access.
      Parameters:
      control - the new control or null

    • getControlAccess

      @FrameworkOnly CControlAccess getControlAccess()
      Gets the control which is responsible for this dockable. Clients should not use this method unless they know exactly what they are doing.
      Returns:
      the control

    • getControl

      CControl getControl()
      Gets the control which is responsible for this dockable. This property is set as long as this CDockable is registered at a CControl.
      Returns:
      the control in whose realm this dockable is used, can be null

    • getParentStation

      CStation<?> getParentStation()
      Searches the first CStation that is a parent of this CDockable.
      Returns:
      the closest station, may be null

    • getAction

      CAction getAction(String key)
      Gets an action which is not added to the title by this CDockable put by another module.
      Parameters:
      key - the name of the action
      Returns:
      an action or null

    • getColors

      ColorMap getColors()
      Gets a mutable map of colors. Clients can put colors into this map, and the colors will be presented on the screen by various effects.
      Returns:
      the map, this has always to be the same object

    • getFonts

      FontMap getFonts()
      Gets a mutable map of fonts. Clients can put fonts into this map, and the fonts will be presented on the screen through various effects.
      Returns:
      the map, this has always to be the same object