Class DockingWindowManager
- All Implemented Interfaces:
PlaceholderInstaller
,PropertyChangeListener
,EventListener
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 Summary
-
Constructor Summary
ConstructorDescriptionDockingWindowManager
(Tool tool, List<Image> images) Constructs a new DockingWindowManagerDockingWindowManager
(Tool tool, List<Image> images, boolean modal, boolean isDocking, boolean hasStatusBar, DropTargetFactory factory) Constructs a new DockingWindowManager -
Method Summary
Modifier and TypeMethodDescriptionvoid
addComponent
(ComponentProvider provider) Adds a new component (via the provider) to be managed by this docking window manager.void
addComponent
(ComponentProvider provider, boolean show) Adds a new component (vial the provider) to be managed by this docking window manager.void
addContextListener
(DockingContextListener listener) void
addPopupActionProvider
(PopupActionProvider provider) Adds the given popup action provider to this tool.void
addStatusItem
(JComponent c, boolean addBorder, boolean rightSide) Add a new status item component to the status area.static void
beep()
A convenience method to make an attention-grabbing noise to the userstatic void
boolean
containsProvider
(ComponentProvider provider) Returns true if this manager contains the given provider.void
contextChanged
(ComponentProvider provider) createActionContext
(DockingActionIf action) Creates theActionContext
appropriate for the given action.void
dispose()
Releases all resources used by this docking window manager.Returns the current active component.static DockingWindowManager
Returns the last active docking window manager which is visible.Returns the active window (or the root window if nobody has yet been made active).static List
<DockingWindowManager> Returns a new list of all DockingWindowManager instances known to exist, ordered from least to most-recently active.getComponentActions
(ComponentProvider provider) Get the local actions installed on the given providergetComponentProvider
(Component component) Returns the component provider that is the conceptual parent of the given component.<T extends ComponentProvider>
TgetComponentProvider
(Class<T> clazz) The first provider instance with a class equal to that of the given classgetComponentProvider
(String name) Returns the ComponentProvider with the given name.<T extends ComponentProvider>
List<T> getComponentProviders
(Class<T> clazz) Gets all components providers with a matching class.getDefaultActionContext
(Class<? extends ActionContext> contextType) Returns the defaultActionContext
for the given context typeMap
<Class<? extends ActionContext>, ActionContext> Returns a map containing a defaultActionContext
for each registered type.Returns the component which has focusReturns the set of global tool actionsstatic HelpService
Returns the global help service.static DockingWindowManager
getInstance
(Component component) A convenience method for getting the window forcomponent
and then callinggetInstanceForWindow(Window)
.Returns the root window.static DockingActionIf
static Object
getPreferenceState
(String key) Gets a preferences state object stored with the given key.Get the provider that contains the specified componentgetProviderWindow
(ComponentProvider provider) Get the window that contains the specified Provider's componentReturns the root window frame.Get the status text in the active component windowgetSubTitle
(ComponentProvider provider) Returns the current subtitle for the component for the given provider.getTool()
Returns the tool that owns this managergetWindows
(boolean includeMain) Returns a list with all the windows in the windowStack.boolean
Returns true if a status bar is present.void
installPlaceholder
(ComponentPlaceholder placeholder, WindowPosition position) boolean
isActiveProvider
(ComponentProvider provider) boolean
Returns true if the set of windows associated with this window manager are visible.boolean
isVisible
(ComponentProvider provider) Returns true if the specified provider's component is visibleboolean
Returns true if the window mode is "satellite windows always on top of root window".void
ownerRemoved
(String owner) void
void
putPreferenceState
(String key, PreferenceState state) Adds a PreferenceState object to this window manager instance that is bound to the given key.static void
registerComponentLoadedListener
(Component component, ComponentLoadedListener listener) Registers a callback to be notified when the given component has been parented to a docking window managervoid
registerDefaultContextProvider
(Class<? extends ActionContext> type, ActionContextProvider provider) Registers an action context provider as the default provider for a specific action context type.void
removeComponent
(ComponentProvider provider) Removes the ComponentProvider (component) from the docking windows manager.void
removeContextListener
(DockingContextListener listener) void
removePopupActionProvider
(PopupActionProvider provider) Removes the given popup action providervoid
Removes the Preferences state for the given key.void
Remove the specified status item.void
restoreFromXML
(org.jdom.Element rootXMLElement) Restores the docking window managers state from the XML information.void
restorePreferencesFromXML
(org.jdom.Element rootElement) void
restoreWindowDataFromXml
(org.jdom.Element rootXMLElement) Restore to the docking window manager the layout and positioning information from XML.void
saveToXML
(org.jdom.Element rootXMLElement) Generates a JDOM element object for saving the window managers state to XML.org.jdom.Element
Save this docking window manager's window layout and positioning information as XML.void
setDefaultComponent
(ComponentProvider provider) Sets the provider that should get the default focus when no component has focus.static void
setHelpLocation
(JComponent c, HelpLocation helpLocation) Register a specific Help content URL for a component.void
setHomeButton
(Icon icon, Runnable callback) Sets the icon for this window's 'home button'.void
setIcon
(ComponentProvider provider, Icon icon) void
Set the Icon for all windows.void
setMenuGroup
(String[] menuPath, String group, String menuSubGroup) Set the menu group associated with a cascaded submenu.static void
setMouseOverAction
(DockingActionIf action) static void
setMouseOverObject
(Object object) void
setStatusText
(String text) Set the status text in the active component windowvoid
setStatusText
(String text, boolean beep) Set the status text in the active component windowvoid
setToolName
(String toolName) Set the tool name which is displayed as the title for all windows.void
setVisible
(boolean state) Sets the visible state of the set of docking windows.void
setWindowsOnTop
(boolean windowsOnTop) Sets the mode such that all satellite docking windows always appear on top of the root windowvoid
showComponent
(ComponentProvider provider, boolean visibleState) Hides or shows the component associated with the given provider.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.static void
showContextMenu
(Component component) Shows a popup menu over the given component.static void
showDialog
(DialogComponentProvider dialogComponent) Shows the dialog using the tool's currently active window as a parentvoid
showDialog
(DialogComponentProvider dialogComponent, ComponentProvider centeredOnProvider) Shows the dialog using the window containing the given componentProvider as its parent windowstatic void
showDialog
(Component parent, DialogComponentProvider dialogComponent) Shows the dialog using the given parent component to find a parent window and to position the dialog.static void
showDialog
(Window parent, DialogComponentProvider dialogComponent, Component centeredOnComponent) Shows the dialog using the given parent window using the optional component for positioning.void
toFront
(ComponentProvider provider) void
toString()
void
uninstallPlaceholder
(ComponentPlaceholder placeholder, boolean keepAround) void
unregisterDefaultContextProvider
(Class<? extends ActionContext> type, ActionContextProvider provider) Removes the default provider for the given ActionContext type.void
updateTitle
(ComponentProvider provider)
-
Field Details
-
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:
-
TOOL_PREFERENCES_XML_NAME
- See Also:
-
-
Constructor Details
-
DockingWindowManager
Constructs a new DockingWindowManager- Parameters:
tool
- the toolimages
- the images to use for windows in this window manager
-
DockingWindowManager
public DockingWindowManager(Tool tool, List<Image> images, boolean modal, boolean isDocking, boolean hasStatusBar, DropTargetFactory factory) Constructs a new DockingWindowManager- Parameters:
tool
- the toolimages
- the list of icons to set on the windowmodal
- if true then the root window will be a modal dialog instead of a frameisDocking
- 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 windowfactory
- the drop target factory
-
-
Method Details
-
toString
-
getHelpService
Returns the global help service.- Returns:
- the global help service.
-
getInstance
A convenience method for getting the window forcomponent
and then callinggetInstanceForWindow(Window)
.- Parameters:
component
- The component for which to get the associatedDockingWindowManager
instance.- Returns:
- The
DockingWindowManager
instance associated withcomponent
-
getActiveInstance
Returns the last active docking window manager which is visible.- Returns:
- the last active docking window manager which is visible.
-
getAllDockingWindowManagers
Returns a new list of all DockingWindowManager instances known to exist, ordered from least to most-recently active.- Returns:
- a new list of all DockingWindowManager instances know to exist.
-
setHelpLocation
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
Set the tool name which is displayed as the title for all windows.- Parameters:
toolName
- tool name / title
-
setIcon
Set the Icon for all windows.- Parameters:
icon
- image icon
-
containsProvider
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
Returns the tool that owns this manager- Returns:
- the tool
-
getRootFrame
Returns the root window frame.- Returns:
- the root window frame.
-
setDefaultComponent
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.
-
registerDefaultContextProvider
public void registerDefaultContextProvider(Class<? extends ActionContext> type, ActionContextProvider provider) Registers an action context provider as the default provider for a specific action context type. Note that this registers a default provider for exactly that type and not a subclass of that type. If the provider want to support a hierarchy of types, then it must register separately for each type. SeeActionContext
for details on how the action context system works.- Parameters:
type
- the ActionContext class to register a default provider forprovider
- the ActionContextProvider that provides default tool context for actions that consume the given ActionContext type
-
unregisterDefaultContextProvider
public void unregisterDefaultContextProvider(Class<? extends ActionContext> type, ActionContextProvider provider) Removes the default provider for the given ActionContext type.- Parameters:
type
- the subclass of ActionContext to remove a provider forprovider
- the ActionContextProvider to remove for the given ActionContext type
-
getProviderWindow
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
Get the provider that contains the specified component- Parameters:
c
- the component- Returns:
- the provider; null if now containing provider is found
-
getActiveWindow
Returns the active window (or the root window if nobody has yet been made active).- Returns:
- the active window.
-
getActiveComponent
Returns the current active component.- Returns:
- the current active component.
-
getFocusedComponent
Returns the component which has focus- Returns:
- the placeholder
-
isActiveProvider
-
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
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
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
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
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
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
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
-
getComponentProvider
Returns the component provider that is the conceptual parent of the given component. More precisely, this will return the component provider whosecomponent
is the parent of the given component.- Parameters:
component
- the component for which to find a provider- Returns:
- the provider; null if the component is not the child of a provider
-
showComponentHeader
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 toolb
- true means to show the header
-
setIcon
-
updateTitle
-
getSubTitle
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
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.
-
getComponentActions
Get the local actions installed on the given provider- Parameters:
provider
- the provider- Returns:
- an iterator over the actions
-
ownerRemoved
-
showComponent
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 viaaddComponent(...)
.- Parameters:
provider
- the provider of the component to be hidden or shown.visibleState
- true to show the component, false to hide it.- See Also:
-
toFront
-
toFront
-
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.
-
installPlaceholder
- Specified by:
installPlaceholder
in interfacePlaceholderInstaller
-
uninstallPlaceholder
- Specified by:
uninstallPlaceholder
in interfacePlaceholderInstaller
-
propertyChange
- Specified by:
propertyChange
in interfacePropertyChangeListener
-
restorePreferencesFromXML
public void restorePreferencesFromXML(org.jdom.Element rootElement) -
putPreferenceState
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
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:
-
removePreferenceState
Removes the Preferences state for the given key.- Parameters:
key
- the key to the preference state to be removed
-
showDialog
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
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 windowdialogComponent
- the DialogComponentProvider object to be shown in a dialog.- See Also:
-
showDialog
public static void showDialog(Window parent, DialogComponentProvider dialogComponent, 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 nulldialogComponent
- the DialogComponentProvider object to be shown in a dialogcenteredOnComponent
- the component over which the dialog will be centered; cannot be null
-
getActiveComponentProvider
-
setHomeButton
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 iconcallback
- 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
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 addaddBorder
- True signals to add a border to the status arearightSide
- 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
Remove the specified status item.- Parameters:
c
- status component previously added.
-
setStatusText
Set the status text in the active component window- Parameters:
text
- status text
-
setStatusText
Set the status text in the active component window- Parameters:
text
- string to be displayed in the Status display areabeep
- whether to beep or not
-
getStatusText
Get the status text in the active component window- Returns:
- string currently displayed in the Status display area
-
beep
public static void beep()A convenience method to make an attention-grabbing noise to the user -
setMenuGroup
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 namemenuSubGroup
- 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
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
Returns the root window.- Returns:
- the root window.
-
getMouseOverAction
-
setMouseOverAction
-
getMouseOverObject
-
setMouseOverObject
-
clearMouseOverHelp
public static void clearMouseOverHelp() -
showContextMenu
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
-
contextChanged
-
addPopupActionProvider
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
Removes the given popup action provider- Parameters:
provider
- the provider
-
addContextListener
-
removeContextListener
-
getDefaultActionContext
Returns the defaultActionContext
for the given context type- Parameters:
contextType
- the class of the ActionContext to get a default value for- Returns:
- the default
ActionContext
for the given context type
-
getDefaultActionContextMap
Returns a map containing a defaultActionContext
for each registered type.- Returns:
- a map containing a default
ActionContext
for each registered type
-
createActionContext
Creates theActionContext
appropriate for the given action. This will normally be the context from the currently focusedComponentProvider
. 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 a generic ActionContext.- Parameters:
action
- the action for which to get anActionContext
- Returns:
- the
ActionContext
appropriate for the given action or null
-
getGlobalActions
Returns the set of global tool actions- Returns:
- the set of global tool actions
-
registerComponentLoadedListener
public static void registerComponentLoadedListener(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 systemlistener
- the listener to be notified the component was parented
-