Package docking

Class ComponentProvider

  • All Implemented Interfaces:
    ActionContextProvider, HelpDescriptor
    Direct Known Subclasses:
    ComponentProviderAdapter, VisualGraphComponentProvider
    public abstract class ComponentProvider
extends java.lang.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.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      protected void addLocalAction​(DockingActionIf action)
      Adds the given action to the system and associates it with this provider.
      void addToTool()
      Adds this provider to the tool in a new window that is not initially visible.
      protected void addToToolbar()
      Signals that this provider's action for showing the provider should appear in the main toolbar
      void closeComponent()
      This is the callback that will happen when the user presses the 'X' button of a provider.
      void componentActivated()
      Notifies the component provider that it is now the active provider
      void componentDeactived()
      Notifies the component provider that it is no longer the active provider
      void componentHidden()
      Notifies the provider that the component is being hidden.
      void componentShown()
      Notifies the provider that the component is being shown.
      void contextChanged()
      Kicks the tool to let it know the context for this provider has changed.
      protected ActionContext createContext()
      A default method for creating an action context for this provider
      protected ActionContext createContext​(java.awt.Component sourceComponent, java.lang.Object contextObject)
      A default method for creating an action context for this provider, using the given context object and component
      protected ActionContext createContext​(java.lang.Object contextObject)
      A default method for creating an action context for this provider, using the given context object
      ActionContext getActionContext​(java.awt.event.MouseEvent event)
      Returns the context object which corresponds to the area of focus within this provider's component.
      abstract javax.swing.JComponent getComponent()
      Returns the component to be displayed
      java.lang.Class<?> getContextType()
      A signal used when installing actions.
      WindowPosition getDefaultWindowPosition()
      The initial WindowPosition of this provider.
      java.lang.String getHelpInfo()
      Returns a descriptive String about the help object that this descriptor represents.
      HelpLocation getHelpLocation()
      Returns the general HelpLocation for this provider.
      java.lang.Object getHelpObject()
      Returns the object for which help locations are defined.
      javax.swing.Icon getIcon()
      Returns the Icon associated with the component view
      long getInstanceID()
      A unique ID for this provider
      WindowPosition getIntraGroupPosition()
      The position of this provider when being placed with other members of the same group.
      static java.lang.String getMappedName​(java.lang.String oldOwner, java.lang.String oldName)
      Returns any registered new provider owner for the oldName/oldOwner pair.
      static java.lang.String getMappedOwner​(java.lang.String oldOwner, java.lang.String oldName)
      Returns any registered new provider name for the oldName/oldOwner pair.
      java.lang.String getName()
      Returns the name of this provider
      java.lang.String getOwner()
      Returns the owner of this provider (usually a plugin)
      java.lang.String getSubTitle()
      Returns the provider's current sub-title (Sub-titles don't show up in the window menu).
      java.lang.String getTabText()
      Returns the optionally set text to display in the tab for a component provider.
      java.lang.String getTitle()
      Returns the provider's current title.
      DockingTool getTool()  
      java.lang.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.
      java.lang.String getWindowSubMenuName()
      Returns the name of a cascading sub-menu name to use when when showing this provider in the "Window" menu.
      protected void initializeInstanceID​(long newID)
      A method that allows children to set the instanceID to a desired value (useful for restoring saved IDs).
      boolean isActive()
      Convenience method to indicate if this provider is the active provider (has focus)
      boolean isFocusedProvider()
      Returns true if this provider has focus
      boolean isInTool()  
      boolean isSnapshot()
      A special marker that indicates this provider is a snapshot of a primary provider, somewhat like a picture of the primary provider.
      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)
      boolean isVisible()
      Convenience method to indicate if this provider is showing.
      static void registerProviderNameOwnerChange​(java.lang.String oldName, java.lang.String oldOwner, java.lang.String newName, java.lang.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.
      void removeFromTool()
      Removes this provider from the tool.
      protected void removeLocalAction​(DockingAction action)
      Removes the given action from the system.
      void requestFocus()  
      protected void setDefaultWindowPosition​(WindowPosition windowPosition)
      Sets the default position of this provider when being shown for the first time.
      void setHelpLocation​(HelpLocation helpLocation)  
      protected void setIcon​(javax.swing.Icon icon)
      Convenience method for setting the provider's icon
      void setIntraGroupPosition​(WindowPosition position)
      See getIntraGroupPosition().
      protected void setKeyBinding​(KeyBindingData kbData)
      Sets the default key binding that will show this provider when pressed.
      void setSubTitle​(java.lang.String subTitle)
      Sets the provider's sub-title (Sub-titles don't show up in the window menu).
      void setTabText​(java.lang.String tabText)
      Sets the text to be displayed on tabs when provider is stacked with other providers.
      void setTitle​(java.lang.String title)
      Sets the provider's title.
      protected void setTransient()
      Sets this class to be transient.
      void setVisible​(boolean visible)
      Convenience method to show or hide this provider.
      protected void setWindowGroup​(java.lang.String group)
      Sets the window group.
      protected void setWindowMenuGroup​(java.lang.String group)
      Sets the window menu group.
      void toFront()  
      java.lang.String toString()  

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Constructor Detail

      • ComponentProvider

        public ComponentProvider​(DockingTool tool,
                         java.lang.String name,
                         java.lang.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​(DockingTool tool,
                         java.lang.String name,
                         java.lang.String owner,
                         java.lang.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 Detail

      • getComponent

        public abstract javax.swing.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 void requestFocus()

      • 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

        protected 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 the system.
        Parameters:
        action - The action to remove.

      • 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 java.lang.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​(java.awt.event.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​(java.lang.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​(java.awt.Component sourceComponent,
                                      java.lang.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 javax.swing.Icon getIcon()
        Returns the Icon associated with the component view
        Returns:
        the Icon associated with the component view

      • getName

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

      • getOwner

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

      • setTitle

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

      • setSubTitle

        public void setSubTitle​(java.lang.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​(java.lang.String tabText)
        Sets the text to be displayed on tabs when provider is stacked with other providers.
        Parameters:
        tabText - the tab text.

      • getTitle

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

      • getSubTitle

        public java.lang.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 java.lang.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.

      • 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​(javax.swing.Icon icon)
        Convenience method for setting the provider's icon
        Parameters:
        icon - the icon to use for this provider

      • addToToolbar

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

      • getWindowSubMenuName

        public java.lang.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

      • 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​(java.lang.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:
        getDefaultWindowPosition()

      • 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.

      • getWindowGroup

        public java.lang.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​(java.lang.String group)
        Sets the window group. See getWindowGroup().
        Parameters:
        group - the group for this provider.

      • getHelpInfo

        public java.lang.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

      • getHelpObject

        public java.lang.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

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • getMappedOwner

        public static java.lang.String getMappedOwner​(java.lang.String oldOwner,
                                              java.lang.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 java.lang.String getMappedName​(java.lang.String oldOwner,
                                             java.lang.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​(java.lang.String oldName,
                                                   java.lang.String oldOwner,
                                                   java.lang.String newName,
                                                   java.lang.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.