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:

- `addLocalAction(DockingActionIf)`
- `addToTool()`
- `setVisible(boolean)`
- `setTitle(String)`
- `setIcon(Icon)`

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

- `componentActivated()` and `componentDeactived()`
- `componentHidden()` and `componentShown()`

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 Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `DEFAULT_WINDOW_GROUP`
  `protected Tool`
  `dockingTool`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ComponentProvider(Tool tool, String name, String owner)`
  Creates a new component provider with a default location of `WindowPosition.WINDOW`.
  `ComponentProvider(Tool tool, String name, String owner, Class<?> contextType)`
  Creates a new component provider with a default location of `WindowPosition.WINDOW`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `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`
  `adjustFontSize(boolean bigger)`
  Tells the provider to adjust the font size for this provider.
  `boolean`
  `canBeParent()`
  Returns true if the window containing this provider can be used as a parent window when showing system windows.
  `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(Component sourceComponent, Object contextObject)`
  A default method for creating an action context for this provider, using the given `context object` and component
  `protected ActionContext`
  `createContext(Object contextObject)`
  A default method for creating an action context for this provider, using the given `context object`
  `ActionContext`
  `getActionContext(MouseEvent event)`
  Returns the context object which corresponds to the area of focus within this provider's component.
  `abstract JComponent`
  `getComponent()`
  Returns the component to be displayed
  `Class<?>`
  `getContextType()`
  A signal used when installing actions.
  `WindowPosition`
  `getDefaultWindowPosition()`
  The initial `WindowPosition` of this provider.
  `String`
  `getHelpInfo()`
  Returns a descriptive String about the help object that this descriptor represents.
  `HelpLocation`
  `getHelpLocation()`
  Returns the general HelpLocation for this provider.
  `Object`
  `getHelpObject()`
  Returns the object for which help locations are defined.
  `Icon`
  `getIcon()`
  Returns the Icon associated with the component view
  `final 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 String`
  `getMappedName(String oldOwner, String oldName)`
  Returns any registered new provider owner for the oldName/oldOwner pair.
  `static String`
  `getMappedOwner(String oldOwner, String oldName)`
  Returns any registered new provider name for the oldName/oldOwner pair.
  `String`
  `getName()`
  Returns the name of this provider
  `String`
  `getOwner()`
  Returns the owner of this provider (usually a plugin)
  `String`
  `getSubTitle()`
  Returns the provider's current sub-title (Sub-titles don't show up in the window menu).
  `String`
  `getTabText()`
  Returns the optionally set text to display in the tab for a component provider.
  `String`
  `getTitle()`
  Returns the provider's current title.
  `Tool`
  `getTool()`
  `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.
  `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.
  `protected void`
  `registerAdjustableFontId(String fontId)`
  Registers a fontId for the font that will be automatically adjusted when `adjustFontSize(boolean)` is called.
  `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.
  `protected void`
  `removeAllLocalActions()`
  Removes all local actions from this component provider
  `void`
  `removeFromTool()`
  Removes this provider from the tool.
  `protected void`
  `removeLocalAction(DockingAction action)`
  Removes the given action from this component provider.
  `void`
  `requestFocus()`
  `void`
  `resetFontSize()`
  Tells the provider to reset the font size for this provider.
  `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(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(String subTitle)`
  Sets the provider's sub-title (Sub-titles don't show up in the window menu).
  `void`
  `setTabText(String tabText)`
  Sets the text to be displayed on tabs when provider is stacked with other providers.
  `void`
  `setTitle(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(String group)`
  Sets the window group.
  `protected void`
  `setWindowMenuGroup(String group)`
  Sets the window menu group.
  `void`
  `toFront()`
  `String`
  `toString()`

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### DEFAULT_WINDOW_GROUP

    public static final String DEFAULT_WINDOW_GROUP
    See Also:
      - Constant Field Values

  - ### dockingTool

    protected Tool dockingTool

- ## 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 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

    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.

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

  - ### 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:
      - `setTabText(String)`

  - ### 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

  - ### 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:
      - `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.

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