Package docking

Class DockingWindowManager

  • All Implemented Interfaces:
    PlaceholderInstaller, java.beans.PropertyChangeListener, java.util.EventListener
    public class DockingWindowManager
extends java.lang.Object
implements java.beans.PropertyChangeListener, PlaceholderInstaller
    Manages the "Docking" arrangement of a set of components and actions. The components can be "docked" together or exist in their own window. Actions can be associated with components so they "move" with the component as it moved from one location to another.

    Components are added via ComponentProviders. A ComponentProvider is an interface for getting a component and its related information. The docking window manager will get the component from the provider as needed. It is up to the provider if it wants to reuse the component or recreate a new one when the component is requested. When the user hides a component (by using the x button on the component header), the docking window manager removes all knowledge of the component and will request it again from the provider if the component is again shown. The provider is also notified whenever a component is hidden and shown.

    • Field Detail

      • DOCKING_WINDOWS_OWNER

        public static final java.lang.String DOCKING_WINDOWS_OWNER
        The owner name for docking windows actions.

        Warning: Any action with this owner will get removed every time the 'Window' menu is rebuilt, with the exception if reserved key bindings.

        See Also:
        Constant Field Values

      • TOOL_PREFERENCES_XML_NAME

        public static final java.lang.String TOOL_PREFERENCES_XML_NAME
        See Also:
        Constant Field Values

    • Constructor Detail

      • DockingWindowManager

        public DockingWindowManager​(Tool tool,
                            java.util.List<java.awt.Image> images)
        Constructs a new DockingWindowManager
        Parameters:
        tool - the tool
        images - the images to use for windows in this window manager

      • DockingWindowManager

        public DockingWindowManager​(Tool tool,
                            java.util.List<java.awt.Image> images,
                            boolean modal,
                            boolean isDocking,
                            boolean hasStatusBar,
                            DropTargetFactory factory)
        Constructs a new DockingWindowManager
        Parameters:
        tool - the tool
        images - the list of icons to set on the window
        modal - if true then the root window will be a modal dialog instead of a frame
        isDocking - true for normal operation, false to suppress docking support(removes component headers and window menu)
        hasStatusBar - if true a status bar will be created for the main window
        factory - the drop target factory

    • Method Detail

      • toString

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

      • setHelpService

        public static void setHelpService​(HelpService helpSvc)
        Sets the help service for the all docking window managers.
        Parameters:
        helpSvc - the help service to use.

      • getHelpService

        public static HelpService getHelpService()
        Returns the global help service.
        Returns:
        the global help service.

      • getActiveInstance

        public static DockingWindowManager getActiveInstance()
        Returns the last active docking window manager which is visible.
        Returns:
        the last active docking window manager which is visible.

      • getAllDockingWindowManagers

        public static java.util.List<DockingWindowManager> getAllDockingWindowManagers()
        Returns a new list of all DockingWindowManager instances know to exist.
        Returns:
        a new list of all DockingWindowManager instances know to exist.

      • setHelpLocation

        public static void setHelpLocation​(javax.swing.JComponent c,
                                   HelpLocation helpLocation)
        Register a specific Help content URL for a component. The DocWinListener will be notified with the helpURL if the specified component 'c' has focus and the help key is pressed.
        Parameters:
        c - component on which to set help.
        helpLocation - help content location

      • setToolName

        public void setToolName​(java.lang.String toolName)
        Set the tool name which is displayed as the title for all windows.
        Parameters:
        toolName - tool name / title

      • setIcon

        public void setIcon​(javax.swing.ImageIcon icon)
        Set the Icon for all windows.
        Parameters:
        icon - image icon

      • containsProvider

        public boolean containsProvider​(ComponentProvider provider)
        Returns true if this manager contains the given provider.
        Parameters:
        provider - the provider for which to check
        Returns:
        true if this manager contains the given provider.

      • getTool

        public Tool getTool()
        Returns the tool that owns this manager
        Returns:
        the tool

      • getRootFrame

        public javax.swing.JFrame getRootFrame()
        Returns the root window frame.
        Returns:
        the root window frame.

      • setDefaultComponent

        public void setDefaultComponent​(ComponentProvider provider)
        Sets the provider that should get the default focus when no component has focus.
        Parameters:
        provider - the provider that should get the default focus when no component has focus.

      • getProviderWindow

        public java.awt.Window getProviderWindow​(ComponentProvider provider)
        Get the window that contains the specified Provider's component
        Parameters:
        provider - component provider
        Returns:
        window or null if component is not visible or not found

      • getProvider

        public ComponentProvider getProvider​(java.awt.Component c)
        Get the provider that contains the specified component
        Parameters:
        c - the component
        Returns:
        the provider; null if now containing provider is found

      • getActiveWindow

        public java.awt.Window getActiveWindow()
        Returns the active window (or the root window if nobody has yet been made active).
        Returns:
        the active window.

      • getActiveComponent

        public java.awt.Component getActiveComponent()
        Returns the current active component.
        Returns:
        the current active component.

      • getFocusedComponent

        public ComponentPlaceholder getFocusedComponent()
        Returns the component which has focus
        Returns:
        the placeholder

      • setVisible

        public void setVisible​(boolean state)
        Sets the visible state of the set of docking windows.
        Parameters:
        state - if true the main window and all sub-windows are set to be visible. If state is false, then all windows are set to be invisible.

      • isVisible

        public boolean isVisible()
        Returns true if the set of windows associated with this window manager are visible.
        Returns:
        true if the set of windows associated with this window manager are visible.

      • isVisible

        public boolean isVisible​(ComponentProvider provider)
        Returns true if the specified provider's component is visible
        Parameters:
        provider - component provider
        Returns:
        true if the specified provider's component is visible

      • addComponent

        public void addComponent​(ComponentProvider provider)
        Adds a new component (via the provider) to be managed by this docking window manager. The component is initially hidden.
        Parameters:
        provider - the component provider

      • addComponent

        public void addComponent​(ComponentProvider provider,
                         boolean show)
        Adds a new component (vial the provider) to be managed by this docking window manager. The component will be initially shown or hidden based on the the "show" parameter.
        Parameters:
        provider - the component provider.
        show - indicates whether or not the component should be initially shown.

      • getComponentProvider

        public ComponentProvider getComponentProvider​(java.lang.String name)
        Returns the ComponentProvider with the given name. If more than one provider exists with the name, one will be returned, but it could be any one of them.
        Parameters:
        name - the name of the provider to return.
        Returns:
        a provider with the given name, or null if no providers with that name exist.

      • getComponentProvider

        public <T extends ComponentProvider> T getComponentProvider​(java.lang.Class<T> clazz)
        The first provider instance with a class equal to that of the given class
        Parameters:
        clazz - the class of the desired provider
        Returns:
        the first provider instance with a class equal to that of the given class.
        See Also:
        getComponentProviders(Class)

      • getComponentProviders

        public <T extends ComponentProvider> java.util.List<T> getComponentProviders​(java.lang.Class<T> clazz)
        Gets all components providers with a matching class. Some component providers will have multiple instances in the tool
        Parameters:
        clazz - The class of the provider
        Returns:
        all found provider instances

      • showComponentHeader

        public void showComponentHeader​(ComponentProvider provider,
                                boolean b)
        Set whether a component's header should be shown; the header is the component that is dragged in order to move the component within the tool, or out of the tool into a separate window.
        Parameters:
        provider - provider of the visible component in the tool
        b - true means to show the header

      • setIcon

        public void setIcon​(ComponentProvider provider,
                    javax.swing.Icon icon)

      • getSubTitle

        public java.lang.String getSubTitle​(ComponentProvider provider)
        Returns the current subtitle for the component for the given provider.
        Parameters:
        provider - the component provider of the component for which to get its subtitle.
        Returns:
        the current subtitle for the component for the given provider.

      • removeComponent

        public void removeComponent​(ComponentProvider provider)
        Removes the ComponentProvider (component) from the docking windows manager. The location of the window will be remember and reused if the provider is added back in later.
        Parameters:
        provider - the provider to be removed.

      • ownerRemoved

        public void ownerRemoved​(java.lang.String owner)

      • showComponent

        public void showComponent​(ComponentProvider provider,
                          boolean visibleState)
        Hides or shows the component associated with the given provider.


        Note: This method will not show the given provider if it has not previously been added via addComponent(...).

        Parameters:
        provider - the provider of the component to be hidden or shown.
        visibleState - true to show the component, false to hide it.
        See Also:
        addComponent(ComponentProvider), addComponent(ComponentProvider, boolean)

      • toFront

        public void toFront​(java.awt.Window window)

      • dispose

        public void dispose()
        Releases all resources used by this docking window manager. Once the dispose method is called, no other calls to this object should be made.

      • saveToXML

        public void saveToXML​(org.jdom.Element rootXMLElement)
        Generates a JDOM element object for saving the window managers state to XML.
        Parameters:
        rootXMLElement - The root element to which to save XML data.

      • saveWindowingDataToXml

        public org.jdom.Element saveWindowingDataToXml()
        Save this docking window manager's window layout and positioning information as XML.
        Returns:
        An XML element with the above information.

      • restoreFromXML

        public void restoreFromXML​(org.jdom.Element rootXMLElement)
        Restores the docking window managers state from the XML information.
        Parameters:
        rootXMLElement - JDOM element from which to extract the state information.

      • restoreWindowDataFromXml

        public void restoreWindowDataFromXml​(org.jdom.Element rootXMLElement)
        Restore to the docking window manager the layout and positioning information from XML.
        Parameters:
        rootXMLElement - JDOM element from which to extract the state information.

      • showEditWindow

        public void showEditWindow​(java.lang.String defaultText,
                           java.awt.Component c,
                           java.awt.Rectangle r,
                           EditListener listener)
        Display an text edit box on top of the specified component.
        Parameters:
        defaultText - initial text to be displayed in edit box
        c - component over which the edit box will be placed
        r - specifies the bounds of the edit box relative to the component. The height is ignored. The default text field height is used as the preferred height.
        listener - when the edit is complete, this listener is notified with the new text. The edit box is dismissed prior to notifying the listener.

      • propertyChange

        public void propertyChange​(java.beans.PropertyChangeEvent evt)
        Specified by:
        propertyChange in interface java.beans.PropertyChangeListener

      • restorePreferencesFromXML

        public void restorePreferencesFromXML​(org.jdom.Element rootElement)

      • putPreferenceState

        public void putPreferenceState​(java.lang.String key,
                               PreferenceState state)
        Adds a PreferenceState object to this window manager instance that is bound to the given key. When the state of the tool using this window manager is saved, then the mapped preferences will also be saved.
        Parameters:
        key - The key with which to store the preferences.
        state - The state object to store.
        See Also:
        getPreferenceState(String)

      • getPreferenceState

        public PreferenceState getPreferenceState​(java.lang.String key)
        Gets a preferences state object stored with the given key. The state objects are loaded from persistent storage when the tool using this window manager has its state loaded.
        Parameters:
        key - The key with which to store the preferences.
        Returns:
        the PrefrenceState object stored by the given key, or null if one does not exist
        See Also:
        putPreferenceState(String, PreferenceState)

      • removePreferenceState

        public void removePreferenceState​(java.lang.String key)
        Removes the Preferences state for the given key.
        Parameters:
        key - the key to the preference state to be removed

      • showDialog

        public static void showDialog​(DialogComponentProvider dialogComponent)
        Shows the dialog using the tool's currently active window as a parent
        Parameters:
        dialogComponent - the DialogComponentProvider object to be shown in a dialog

      • showDialog

        public void showDialog​(DialogComponentProvider dialogComponent,
                       ComponentProvider centeredOnProvider)
        Shows the dialog using the window containing the given componentProvider as its parent window
        Parameters:
        dialogComponent - the DialogComponentProvider object to be shown in a dialog.
        centeredOnProvider - the component provider that is used to find a parent window for this dialog. The dialog is centered on this component provider's component.

      • showDialog

        public static void showDialog​(java.awt.Component parent,
                              DialogComponentProvider dialogComponent)
        Shows the dialog using the given parent component to find a parent window and to position the dialog. If a Window can be found containing the given component, it will be used as the parent window for the dialog. If the component is null or not contained in a window, the current active window manager will be used to parent the dialog. If there are no active tools, then a frame will be created to parent the dialog.
        Parameters:
        parent - the component whose window over which the given dialog will be shown; null signals to use the active window
        dialogComponent - the DialogComponentProvider object to be shown in a dialog.
        See Also:
        for parenting notes

      • showDialog

        public static void showDialog​(java.awt.Window parent,
                              DialogComponentProvider dialogComponent,
                              java.awt.Component centeredOnComponent)
        Shows the dialog using the given parent window using the optional component for positioning.

        Warning: this method allows user to explicitly pass a parent window and component over which to be centered. There is no reason to use this method in the standard workflow. This method exists strictly to handle future unforeseen use cases. Use at your own risk of incorrectly parenting dialogs.

        Parameters:
        parent - the component whose window over which the given dialog will be shown; cannot be null
        dialogComponent - the DialogComponentProvider object to be shown in a dialog
        centeredOnComponent - the component over which the dialog will be centered; cannot be null

      • setHomeButton

        public void setHomeButton​(javax.swing.Icon icon,
                          java.lang.Runnable callback)
        Sets the icon for this window's 'home button'. This button, when pressed, will show the tool's main application window.
        Parameters:
        icon - the button's icon
        callback - the callback to execute when the button is pressed by the user

      • hasStatusBar

        public boolean hasStatusBar()
        Returns true if a status bar is present.
        Returns:
        true if a status bar is present.

      • addStatusItem

        public void addStatusItem​(javax.swing.JComponent c,
                          boolean addBorder,
                          boolean rightSide)
        Add a new status item component to the status area. The preferred height and border for the component will be altered. The components preferred width will be preserved.
        Parameters:
        c - the status item component to add
        addBorder - True signals to add a border to the status area
        rightSide - component will be added to the right-side of the status area if true, else it will be added immediately after the status text area if false.

      • removeStatusItem

        public void removeStatusItem​(javax.swing.JComponent c)
        Remove the specified status item.
        Parameters:
        c - status component previously added.

      • setStatusText

        public void setStatusText​(java.lang.String text)
        Set the status text in the active component window
        Parameters:
        text - status text

      • setStatusText

        public void setStatusText​(java.lang.String text,
                          boolean beep)
        Set the status text in the active component window
        Parameters:
        text - string to be displayed in the Status display area
        beep - whether to beep or not

      • beep

        public static void beep()
        A convenience method to make an attention-grabbing noise to the user

      • setMenuGroup

        public void setMenuGroup​(java.lang.String[] menuPath,
                         java.lang.String group,
                         java.lang.String menuSubGroup)
        Set the menu group associated with a cascaded submenu. This allows a cascading menu item to be grouped with a specific set of actions.

        The default group for a cascaded submenu is the name of the submenu.

        Parameters:
        menuPath - menu name path where the last element corresponds to the specified group name.
        group - group name
        menuSubGroup - the name used to sort the cascaded menu within other menu items at its level

      • setWindowsOnTop

        public void setWindowsOnTop​(boolean windowsOnTop)
        Sets the mode such that all satellite docking windows always appear on top of the root window
        Parameters:
        windowsOnTop - true to set mode to on top, false to disable on top mode.

      • isWindowsOnTop

        public boolean isWindowsOnTop()
        Returns true if the window mode is "satellite windows always on top of root window".
        Returns:
        true if the window mode is "satellite windows always on top of root window".

      • getWindows

        public java.util.List<java.awt.Window> getWindows​(boolean includeMain)
        Returns a list with all the windows in the windowStack. Used for testing.
        Parameters:
        includeMain - if true, include the main root window.
        Returns:
        a list with all the windows in the windowStack. Used for testing.

      • getMainWindow

        public java.awt.Window getMainWindow()
        Returns the root window.
        Returns:
        the root window.

      • setMouseOverAction

        public static void setMouseOverAction​(DockingActionIf action)

      • getMouseOverObject

        public static java.lang.Object getMouseOverObject()

      • setMouseOverObject

        public static void setMouseOverObject​(java.lang.Object object)

      • clearMouseOverHelp

        public static void clearMouseOverHelp()

      • showContextMenu

        public static void showContextMenu​(java.awt.Component component)
        Shows a popup menu over the given component. If this given component is not part of the docking windows hierarchy, then no action is taken.
        Parameters:
        component - the component

      • addPopupActionProvider

        public void addPopupActionProvider​(PopupActionProvider provider)
        Adds the given popup action provider to this tool. This provider will be called each time the popup menu is about to be shown.
        Parameters:
        provider - the provider

      • removePopupActionProvider

        public void removePopupActionProvider​(PopupActionProvider provider)
        Removes the given popup action provider
        Parameters:
        provider - the provider

      • getDefaultToolContext

        public ActionContext getDefaultToolContext()
        Returns the default action context for the tool
        Returns:
        the default action context for the tool

      • getActionContext

        public ActionContext getActionContext​(DockingActionIf action)
        Gets the ActionContext appropriate for the given action. This will normally be the context from the currently focused ComponentProvider. If that context is not valid for the given action and the action supports using the default tool context, then the default tool context will be returned. Otherwise, returns null.
        Parameters:
        action - the action for which to get an ActionContext
        Returns:
        the ActionContext appropriate for the given action or null

      • registerComponentLoadedListener

        public static void registerComponentLoadedListener​(java.awt.Component component,
                                                   ComponentLoadedListener listener)
        Registers a callback to be notified when the given component has been parented to a docking window manager
        Parameters:
        component - the component that will be parented in a docking window system
        listener - the listener to be notified the component was parented