Package docking

Class ComponentProvider

java.lang.Object
docking.ComponentProvider
All Implemented Interfaces:
ActionContextProvider, HelpDescriptor
Direct Known Subclasses:
ComponentProviderAdapter, VisualGraphComponentProvider
public abstract class ComponentProvider extends Object implements HelpDescriptor, ActionContextProvider
Abstract base class for creating dockable GUI components within a tool.

The one method that must be implemented is getComponent() which is where the top level Swing JComponent is returned to be docked into the tool. Typically, the GUI components are created in the constructor along with any local actions for the provider. The getComponent() method then simply returns the top level component previously created by this provider.

There are many other methods for configuring how to dock the component, set title information, configure grouping, set the help, add actions, and receive show/hide notifications, some of which are highlighted below. Typically, implementers will use these methods to configure how the GUI component behaves within the tool, and then add the business logic that uses and reacts to the GUI components created in this provider.

To effectively use this class you merely need to create your component, add your actions to this class (addLocalAction(DockingActionIf)) and then add this provider to the tool (addToTool()).

This also provides several useful convenience methods:

There are a handful of stub methods that can be overridden as desired:

Show Provider Action - Each provider has an action to show the provider. For typical, non-transient providers (see setTransient()) the action will appear in the tool's Window menu. You can have your provider also appear in the tool's toolbar by calling addToTool().

Historical Note: This class was created so that implementors could add local actions within the constructor without having to understand that they must first add themselves to the WindowManager.

  • Field Details

  • Constructor Details

    • ComponentProvider

      public ComponentProvider(Tool tool, String name, String owner)
      Creates a new component provider with a default location of WindowPosition.WINDOW.
      Parameters:
      tool - The tool will manage and show this provider
      name - The providers name. This is used to group similar providers into a tab within the same window.
      owner - The owner of this provider, usually a plugin name.

    • ComponentProvider

      public ComponentProvider(Tool tool, String name, String owner, Class<?> contextType)
      Creates a new component provider with a default location of WindowPosition.WINDOW.
      Parameters:
      tool - The tool that will manage and show this provider.
      name - The providers name. This is used to group similar providers into a tab within the same window.
      owner - The owner of this provider, usually a plugin name.
      contextType - the type of context supported by this provider; may be null (see getContextType()

  • Method Details

    • getComponent

      public abstract JComponent getComponent()
      Returns the component to be displayed
      Returns:
      the component to be displayed

    • initializeInstanceID

      protected void initializeInstanceID(long newID)
      A method that allows children to set the instanceID to a desired value (useful for restoring saved IDs).

      Note: this can be called only once during the lifetime of the calling instance; otherwise, an AssertException will be thrown.

      Parameters:
      newID - the new ID of this provider

    • getInstanceID

      public final long getInstanceID()
      A unique ID for this provider
      Returns:
      unique ID for this provider

    • requestFocus

      public final void requestFocus()

    • setDefaultFocusComponent

      protected void setDefaultFocusComponent(Component component)

    • isFocusedProvider

      public boolean isFocusedProvider()
      Returns true if this provider has focus
      Returns:
      true if this provider has focus

    • addToTool

      public void addToTool()
      Adds this provider to the tool in a new window that is not initially visible. The provider will then show up in the "Windows" menu of the tool

    • removeFromTool

      public void removeFromTool()
      Removes this provider from the tool.

    • addLocalAction

      public void addLocalAction(DockingActionIf action)
      Adds the given action to the system and associates it with this provider.
      Parameters:
      action - The action to add.

    • removeLocalAction

      protected void removeLocalAction(DockingAction action)
      Removes the given action from this component provider.
      Parameters:
      action - The action to remove.

    • getLocalActions

      public Set<DockingActionIf> getLocalActions()
      Returns all the local actions registered for this component provider.
      Returns:
      all the local actions registered for this component provider

    • removeAllLocalActions

      protected void removeAllLocalActions()
      Removes all local actions from this component provider

    • setVisible

      public void setVisible(boolean visible)
      Convenience method to show or hide this provider.
      Parameters:
      visible - True shows the provider; false hides the provider

    • toFront

      public void toFront()

    • isInTool

      public boolean isInTool()

    • getContextType

      public Class<?> getContextType()
      A signal used when installing actions. Some actions are only added to a given window if there is a provider in that window that can work with that action. Providers can return a context class from this method to control whether dependent actions get added. Most providers return null for this method, which means they will not have any dependent actions added to windows other than the primary application window.
      Returns:
      a class representing the desired context type or null;

    • isVisible

      public boolean isVisible()
      Convenience method to indicate if this provider is showing.
      Returns:
      true if this provider is showing.

    • isActive

      public boolean isActive()
      Convenience method to indicate if this provider is the active provider (has focus)
      Returns:
      true if this provider is active.

    • closeComponent

      public void closeComponent()
      This is the callback that will happen when the user presses the 'X' button of a provider. Transient providers will be removed from the tool completely. Non-transient providers will merely be hidden.

      Subclasses may override this method to prevent a provider from being closed; for example, if an editor has unsaved changes, then this method could prevent the close from happening.

    • componentActivated

      public void componentActivated()
      Notifies the component provider that it is now the active provider

    • componentDeactived

      public void componentDeactived()
      Notifies the component provider that it is no longer the active provider

    • componentHidden

      public void componentHidden()
      Notifies the provider that the component is being hidden. This happens when the provider is being closed.

    • componentShown

      public void componentShown()
      Notifies the provider that the component is being shown.

    • getActionContext

      public ActionContext getActionContext(MouseEvent event)
      Returns the context object which corresponds to the area of focus within this provider's component. Null is returned when there is no context.
      Specified by:
      getActionContext in interface ActionContextProvider
      Parameters:
      event - popup event which corresponds to this request. May be null for key-stroke or other non-mouse event.

    • createContext

      protected ActionContext createContext()
      A default method for creating an action context for this provider
      Returns:
      the new context

    • createContext

      protected ActionContext createContext(Object contextObject)
      A default method for creating an action context for this provider, using the given context object
      Parameters:
      contextObject - the provider-specific context object
      Returns:
      the new context

    • createContext

      protected ActionContext createContext(Component sourceComponent, Object contextObject)
      A default method for creating an action context for this provider, using the given context object and component
      Parameters:
      sourceComponent - the component that is the target of the context being created
      contextObject - the provider-specific context object
      Returns:
      the new context

    • contextChanged

      public void contextChanged()
      Kicks the tool to let it know the context for this provider has changed.

    • getHelpLocation

      public HelpLocation getHelpLocation()
      Returns the general HelpLocation for this provider. Should return null only if no help documentation exists.
      Returns:
      the help location

    • setHelpLocation

      public void setHelpLocation(HelpLocation helpLocation)

    • getIcon

      public Icon getIcon()
      Returns the Icon associated with the component view
      Returns:
      the Icon associated with the component view

    • getName

      public String getName()
      Returns the name of this provider
      Returns:
      the name of this provider

    • getOwner

      public String getOwner()
      Returns the owner of this provider (usually a plugin)
      Returns:
      the owner of this provider

    • setTitle

      public void setTitle(String title)
      Sets the provider's title.
      Parameters:
      title - the title string to use.

    • setSubTitle

      public void setSubTitle(String subTitle)
      Sets the provider's sub-title (Sub-titles don't show up in the window menu).
      Parameters:
      subTitle - the sub-title string to use.

    • setTabText

      public void setTabText(String tabText)
      Sets the text to be displayed on tabs when provider is stacked with other providers.
      Parameters:
      tabText - the tab text.

    • setCustomTitle

      public void setCustomTitle(String title)
      The new custom title. Setting the title here prevents future calls to setTitle(String) from having any effect. This is done to preserve the custom title.
      Parameters:
      title - the title

    • setCustomTabText

      public void setCustomTabText(String tabText)
      The new custom tab text. Setting the text here prevents future calls to setTabText(String) from having any effect. This is done to preserve the custom tab text.
      Parameters:
      tabText - the text

    • setCustomSubTitle

      public void setCustomSubTitle(String subTitle)
      The new custom sub-title. Setting the sub-title here prevents future calls to setSubTitle(String) from having any effect. This is done to preserve the custom sub-title.
      Parameters:
      subTitle - the sub-title

    • getTitle

      public String getTitle()
      Returns the provider's current title.
      Returns:
      the provider's current title.

    • getSubTitle

      public String getSubTitle()
      Returns the provider's current sub-title (Sub-titles don't show up in the window menu).
      Returns:
      the provider's current sub-title.

    • getTabText

      public String getTabText()
      Returns the optionally set text to display in the tab for a component provider. The text returned from getTitle() will be used by default.
      Returns:
      the optionally set text to display in the tab for a component provider.
      See Also:

    • setKeyBinding

      protected void setKeyBinding(KeyBindingData kbData)
      Sets the default key binding that will show this provider when pressed. This value can be changed by the user and saved as part of the Tool options.
      Parameters:
      kbData - the key binding

    • setIcon

      protected void setIcon(Icon icon)
      Convenience method for setting the provider's icon
      Parameters:
      icon - the icon to use for this provider

    • getBaseIcon

      protected final Icon getBaseIcon()
      Get the icon provided to setIcon(Icon)

      This method is final, guaranteeing there is always a means for extensions of this class to obtain the original icon. Some classes may override getIcon() to apply modifications when the icon is displayed in the UI. Further extensions of that class may wish to override getIcon(), too, and so might want access to the original base icon. This method provides that access.

      Returns:
      the base icon

    • addToToolbar

      protected void addToToolbar()
      Signals that this provider's action for showing the provider should appear in the main toolbar

    • getWindowSubMenuName

      public String getWindowSubMenuName()
      Returns the name of a cascading sub-menu name to use when when showing this provider in the "Window" menu. If the group name is null, the item will appear in the top-level menu.
      Returns:
      the menu group for this provider or null if this provider should appear in the top-level menu.

    • isTransient

      public boolean isTransient()
      Returns true if this component goes away during a user session (most providers remain in the tool all session long, visible or not)
      Returns:
      true if transient

    • canBeParent

      public boolean canBeParent()
      Returns true if the window containing this provider can be used as a parent window when showing system windows. All providers will return true from this method by default. This method is intended for short-lived providers to signal that their window should not be made the parent of new windows.
      Returns:
      true if this provider can be a parent

    • isSnapshot

      public boolean isSnapshot()
      A special marker that indicates this provider is a snapshot of a primary provider, somewhat like a picture of the primary provider.
      Returns:
      true if a snapshot

    • setTransient

      protected void setTransient()
      Sets this class to be transient. Setting this provider to be transient will cause this provider to be removed from the tool when the corresponding window is closed.

    • setWindowMenuGroup

      protected void setWindowMenuGroup(String group)
      Sets the window menu group. If the window menu group is null, the corresponding window menu item will appear in the root menu, otherwise it will appear in a sub-menu named group.
      Parameters:
      group - the name of the window's sub-menu for this provider

    • getDefaultWindowPosition

      public WindowPosition getDefaultWindowPosition()
      The initial WindowPosition of this provider. If a window group is provided, then this position is relative to that provider. Otherwise, this position is relative to the tool window.
      Returns:
      The initial WindowPosition of this provider.

    • setDefaultWindowPosition

      protected void setDefaultWindowPosition(WindowPosition windowPosition)
      Sets the default position of this provider when being shown for the first time. If the providers position in the tool has been saved before, then this value is ignored.
      Parameters:
      windowPosition - the position
      See Also:

    • getIntraGroupPosition

      public WindowPosition getIntraGroupPosition()
      The position of this provider when being placed with other members of the same group. As an example, assume this provider is being shown for the first time while there is another member of its window group already visible. Further, assume that this method will return WindowPosition.STACK. This provider will then be stacked upon the already showing provider.

      To determine where this provider should be initially shown, see getDefaultWindowPosition().

      Returns:
      The position of this provider when being placed with other members of the same group.

    • setIntraGroupPosition

      public void setIntraGroupPosition(WindowPosition position)
      See getIntraGroupPosition().
      Parameters:
      position - the new position

    • getWindowGroup

      public String getWindowGroup()
      Returns an optional group designator that, if non-null, the docking window manager uses to determine the initial location of the new component relative to any existing instances of this component Provider.

      The docking window manager will use Intra-group Position to decide where to place this provider inside of the already open instances of the same group. The default position is 'stack', which results in the new instance being stacked with other instances of this provider that have the same group unless that instance is the active provider or is currently stacked with the active provider. (This is to prevent new windows from covering the active window).

      Returns:
      the window group

    • setWindowGroup

      protected void setWindowGroup(String group)
      Sets the window group. See getWindowGroup().
      Parameters:
      group - the group for this provider.

    • getHelpInfo

      public String getHelpInfo()
      Description copied from interface: HelpDescriptor
      Returns a descriptive String about the help object that this descriptor represents.
      Specified by:
      getHelpInfo in interface HelpDescriptor
      Returns:
      the help info

    • getHelpObject

      public Object getHelpObject()
      Description copied from interface: HelpDescriptor
      Returns the object for which help locations are defined. This may be the implementor of this interface or some other delegate object.
      Specified by:
      getHelpObject in interface HelpDescriptor
      Returns:
      the help object

    • getTool

      public Tool getTool()

    • adjustFontSize

      public void adjustFontSize(boolean bigger)
      Tells the provider to adjust the font size for this provider. By default, this method will adjust the font for the registered font id if it has been registered using registeredFontId. Subclasses can override this method to a more comprehensive adjustment to multiple fonts if necessary.
      Parameters:
      bigger - if true, the font should be made bigger, otherwise the font should be made smaller

    • resetFontSize

      public void resetFontSize()
      Tells the provider to reset the font size for this provider.

      See adjustFontSize(boolean)

    • registerAdjustableFontId

      protected void registerAdjustableFontId(String fontId)
      Registers a fontId for the font that will be automatically adjusted when adjustFontSize(boolean) is called.
      Parameters:
      fontId - the id of the theme font to be adjusted

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getMappedOwner

      public static String getMappedOwner(String oldOwner, String oldName)
      Returns any registered new provider name for the oldName/oldOwner pair.
      Parameters:
      oldOwner - the old owner name
      oldName - the old provider name
      Returns:
      the new provider name for that oldOwner/oldName

    • getMappedName

      public static String getMappedName(String oldOwner, String oldName)
      Returns any registered new provider owner for the oldName/oldOwner pair.
      Parameters:
      oldOwner - the old owner name
      oldName - the old provider name
      Returns:
      the new provider owner for that oldOwner/oldName

    • registerProviderNameOwnerChange

      public static void registerProviderNameOwnerChange(String oldName, String oldOwner, String newName, String newOwner)
      Register a name and/or owner change to a provider so that old tools can restore those provider windows to their old position and size. Note you must supply all four arguments. If the name or owner did not change, use the name or owner that did not change for both the old and new values.

      Note: when you make use of this method, please signal when it is safe to remove its usage.

      Parameters:
      oldName - the old name of the provider.
      oldOwner - the old owner of the provider.
      newName - the new name of the provider. If the name did not change, use the old name here.
      newOwner - the new owner of the provider. If the owner did not change, use the old owner here.