Modes, TopComponentGroups
* and provides handling of operations provided over TopComponents.
*
* Important note: Do not provide implementation of this abstract class unless you are window system provider!
*
* @author Jaroslav Tulach
*/
public abstract class WindowManager extends Object implements Serializable {
/** property change of workspaces.
* @deprecated Do not use. Workspaces are not supported anymore. */
@Deprecated
public static final String PROP_WORKSPACES = "workspaces"; // NOI18N
/** property change of current workspace.
* @deprecated Do not use. Workspaces are not supported anymore.
*/
@Deprecated
public static final String PROP_CURRENT_WORKSPACE = "currentWorkspace"; // NOI18N
/** Name of property for modes in the workspace.
* @since 4.13 */
public static final String PROP_MODES = "modes"; // NOI18N
/** Instance of dummy window manager. */
private static WindowManager dummyInstance;
static final long serialVersionUID = -4133918059009277602L;
/** The top component which is currently active */
private Reference
* The typical usecase is to call this method during startup of NetBeans
* based application. The default manager then waits till the main window
* is opened and then executes all the registered methods one by one.
* Check whether the given TopComponent will be/is docked into an 'editor' Mode. Please note that some TopComponents may be docked into 'editor' modes as well as
* 'view' modes, see method isTopComponentAllowedToMoveAnywhere(). Check whether the given TopComponent is opened and docked into an 'editor' Mode.
* It is safe to call this method outside the event dispatch thread. Please note that some TopComponents may be docked into 'editor' modes as well as
* 'view' modes, see method isTopComponentAllowedToMoveAnywhere(). Check whether the given Mode holds editor windows. Please note that some TopComponents may be docked into 'editor' modes as well as
* 'view' modes, see method isTopComponentAllowedToMoveAnywhere(). Switches the window system to a new role (perspective). A role may customize the default window layout by adding/removing TopComponents,
* changing window positions and/or sizes etc. Roles are defined in XML
* layers in folder The default implementation of this method in core.windows module does
* the following:
* Mode whith the specified name is or null
* if there does not exist such Mode inside window system.
* @since 4.13 */
public abstract Mode findMode(String name);
/** Finds mode which contains specified TopComponent.
* @return Mode which contains specified TopComponent or null
* if the TopComponent is not added into any Mode inside window system.
* @since 4.13 */
public abstract Mode findMode(TopComponent tc);
/** Gets set of all ModeS added into window system.
* @since 4.13 */
public abstract Set getModes();
/**
* Gets the NetBeans Main Window.
* This should ONLY be used for:
*
*
* Since version 6.36 the default implementation in org.netbeans.core.windows
* module first checks already opened Frames (see Frame.getFrames()) and if
* there is a Frame named 'NbMainWindow' then it is reused as NetBeans main
* window. Otherwise a new Frame is created instead.
* @return the Main Window
*/
public abstract Frame getMainWindow();
/** Called after a Look&Feel change to update the NetBeans UI.
* Should call {@link javax.swing.JComponent#updateUI} on all opened windows.
*/
public abstract void updateUI();
/** Create a component manager for the given top component.
* @param c the component
* @return the manager to handle opening, closing and selecting the component
*/
protected abstract WindowManager.Component createTopComponentManager(TopComponent c);
/** Access method for registry of all components in the system.
* @return the registry
*/
protected TopComponent.Registry componentRegistry() {
return Lookup.getDefault().lookup(TopComponent.Registry.class);
}
/** Getter for component registry.
* @return the registry
*/
public synchronized TopComponent.Registry getRegistry() {
if (registry != null) {
return registry;
}
onShowing.initialize();
return registry = componentRegistry();
}
/** Creates new workspace.
* @param name the name of the workspace
* @return new workspace
* @deprecated Do not use. Workspaces are not supported anymore. */
@Deprecated
public final Workspace createWorkspace(String name) {
return createWorkspace(name, name);
}
/** Creates new workspace with I18N support.
* Note that it will not be displayed until {@link #setWorkspaces} is called
* with an array containing the new workspace.
* @param name the code name (used for internal purposes)
* @param displayName the display name
* @return the new workspace
* @deprecated Do not use. Workspaces are not supported anymore. */
@Deprecated
public abstract Workspace createWorkspace(String name, String displayName);
/** Finds workspace given its name.
* @param name the (code) name of workspace to find
* @return workspace or null if not found
* @deprecated Do not use. Workspaces are not supported anymore. */
@Deprecated
public abstract Workspace findWorkspace(String name);
/**
* Gets a list of all workspaces.
* @return an array of all known workspaces
* @deprecated Do not use. Workspaces are not supported anymore. */
@Deprecated
public abstract Workspace[] getWorkspaces();
/** Sets new array of workspaces.
* In conjunction with {@link #getWorkspaces}, this may be used to reorder
* workspaces, or add or remove workspaces.
* @param workspaces An array consisting of new workspaces.
* @deprecated Do not use. Workspaces are not supported anymore. */
@Deprecated
public abstract void setWorkspaces(Workspace[] workspaces);
/**
* Gets the current workspace.
* @return the currently active workspace
* @see Workspace#activate
* @deprecated Do not use. Workspaces are not supported anymore. */
@Deprecated
public abstract Workspace getCurrentWorkspace();
/** Finds TopComponentGroup of given name.
* @return instance of TopComponetnGroup or null
* @since 4.13 */
public abstract TopComponentGroup findTopComponentGroup(String name);
//
// You can add implementation to this class (+firePropertyChange), or implement it in subclass
// Do as you want.
//
/**
* Attaches a listener for changes in workspaces.
* @param l the new listener
*/
public abstract void addPropertyChangeListener(PropertyChangeListener l);
/**
* Removes a listener for changes in workspaces.
* @param l the listener to remove
*/
public abstract void removePropertyChangeListener(PropertyChangeListener l);
/** Finds top component manager for given top component.
* @param tc top component to find manager for.
* @return component manager for given top component.
* @deprecated Do not use anymore.
* See {@link WindowManager.Component} deprecation.
*/
@Deprecated
protected static final Component findComponentManager(TopComponent tc) {
return null;
}
/** Activate a component. The top component containers should inform
* the top component that it is active via a call to this method through
* derived window manager implementation.
* @param tc the top component to activate;
* or null to deactivate all top components
*/
protected void activateComponent(TopComponent tc) {
// check
if (getActiveComponent() == tc) {
return;
}
TopComponent old = getActiveComponent();
// deactivate old if possible
if (old != null) {
try {
old.componentDeactivated();
} catch (Throwable th) {
logThrowable(th, "[Winsys] TopComponent " + old.getClass().getName() // NOI18N
+" throws runtime exception from its componentDeactivated() method.\nPlease repair it!"); // NOI18N
}
}
setActiveComponent(tc);
TopComponent newTC = getActiveComponent();
if (newTC != null) {
try {
newTC.componentActivated();
} catch (Throwable th) {
logThrowable(th, "[Winsys] TopComponent " + newTC.getClass().getName() // NOI18N
+" throws runtime exception from its componentActivated() method.\nPlease repair it!"); // NOI18N
}
}
}
/** Notifies component that it was opened (and wasn't opened on any
* workspace before). Top component manager that implements Component
* inner interface of this class should send open notifications via
* calling this method
* @param tc the top component to be notified
*/
protected void componentOpenNotify(TopComponent tc) {
try {
tc.componentOpened();
} catch (Throwable th) {
logThrowable(th, "[Winsys] TopComponent " + tc.getClass().getName() // NOI18N
+" throws exception/error from its componentOpened() method.\nPlease repair it!"); // NOI18N
}
}
/** Notifies component that it was closed (and is not opened on any
* workspace anymore). Top component manager that implements Component
* inner interface of this class should send close notifications via
* calling this method
* @param tc the top component to be notified
*/
protected void componentCloseNotify(TopComponent tc) {
try {
tc.componentClosed();
} catch (Throwable th) {
logThrowable(th, "[Winsys] TopComponent " + tc.getClass().getName() // NOI18N
+" throws exception/error from its componentClosed() method.\nPlease repair it!"); // NOI18N
}
if (tc == getActiveComponent()) {
activateComponent(null);
}
}
/** Notifies TopComponent it is about to be shown.
* @param tc TopComponent to be notified
* @see TopComponent#componentShowing
* @since 2.18 */
protected void componentShowing(TopComponent tc) {
try {
tc.componentShowing();
} catch (Throwable th) {
logThrowable(th, "[Winsys] TopComponent " + tc.getClass().getName() // NOI18N
+" throws runtime exception from its componentShowing() method.\nPlease repair it!"); // NOI18N
}
}
/** Notifies TopComponent it was hidden.
* @param tc TopComponent to be notified
* @see TopComponent#componentHidden
* @since 2.18 */
protected void componentHidden(TopComponent tc) {
try {
tc.componentHidden();
} catch (Throwable th) {
logThrowable(th, "[Winsys] TopComponent " + tc.getClass().getName() // NOI18N
+" throws runtime exception from its componentHidden() method.\nPlease repair it!"); // NOI18N
}
}
/** #113158: even errors may come
* from TopComponent.componentOpened or componentClosed.
*/
private static void logThrowable (Throwable th, String message) {
if (th instanceof ThreadDeath || th instanceof OutOfMemoryError) {
// let us R.I.P. :-)
throw (Error) th;
}
Logger.getLogger(WindowManager.class.getName()).log(Level.WARNING, message, th);
}
/** Provides opening of specified TopComponent.
* @param tc TopComponent to open
* @since 4.13 */
protected abstract void topComponentOpen(TopComponent tc);
/** Opens given TopComponent at given position in the mode. TopComponent is inserted at given
* position, positions of already opened TopComponents in the same mode are
* incremented.
*
*
*
*
* @param tc TopComponent which is opened.
* @param position Index of the requested position.
* @since 6.15
*/
protected void topComponentOpenAtTabPosition(TopComponent tc, int position) {
topComponentOpen(tc);
}
/** Gives position index of given TopComponent in the mode. Result is
* undefined for closed TopComponents.
*
* @param tc TopComponent for which position is returned.
* @return Index of position.
* @since 6.15
*/
protected int topComponentGetTabPosition(TopComponent tc) {
Mode mode = findMode(tc);
if (mode == null || !topComponentIsOpened(tc)) {
return -1;
}
TopComponent[] tcs = mode.getTopComponents();
for (int i = 0; i < tcs.length; i++) {
if (tcs[i] == tc) {
return i;
}
}
return -1;
}
/** Provides closing of specified TopComponent.
* @param tc TopComponent to close
* @since 4.13 */
protected abstract void topComponentClose(TopComponent tc);
/** Provides activation of specified TopComponent.
* @param tc TopComponent to activate
* @since 4.13 */
protected abstract void topComponentRequestActive(TopComponent tc);
/** Provides selection of specfied TopComponent.
* @param tc TopComponent to set visible (select)
* @since 4.13 */
protected abstract void topComponentRequestVisible(TopComponent tc);
/** Informs about change of display name of specified TopComponent.
* @param tc TopComponent which display name has changed
* @param displayName newly changed display name value
* @since 4.13 */
protected abstract void topComponentDisplayNameChanged(TopComponent tc, String displayName);
/** Informs about change of html display name of specified TopComponent.
* @param tc TopComponent which display name has changed
* @param htmlDisplayName newly changed html display name value
* @since 6.4 */
protected abstract void topComponentHtmlDisplayNameChanged(TopComponent tc, String htmlDisplayName);
/** Informs about change of tooltip of specified TopComponent.
* @param tc TopComponent which tooltip has changed
* @param toolTip newly changed tooltip value
* @since 4.13 */
protected abstract void topComponentToolTipChanged(TopComponent tc, String toolTip);
/** Informs about chagne of icon of specified TopComponent.
* @param tc TopComponent which icon has changed
* @param icon newly chaned icon value
* @since 4.13 */
protected abstract void topComponentIconChanged(TopComponent tc, Image icon);
/** Informs about change of activated nodes of specified TopComponent.
* @param tc TopComponent which activated nodes has chagned
* @param activatedNodes newly chaged activated nodes value
* @since 4.13 */
protected abstract void topComponentActivatedNodesChanged(TopComponent tc, Node[] activatedNodes);
/** Indicates whether specified TopComponent is opened.
* @param tc specified TopComponent
* @since 4.13 */
protected abstract boolean topComponentIsOpened(TopComponent tc);
/** Gets default list of actions which appear in popup menu of TopComponent.
* The popup menu which is handled by window systsm implementation, typically at tab.
* @param tc TopComponent for which the default actions to provide
* @since 4.13 */
protected abstract javax.swing.Action[] topComponentDefaultActions(TopComponent tc);
/** Returns unique ID for specified TopComponent.
* @param tc TopComponent the component for which is ID returned
* @param preferredID first approximation used for ID
* @return unique TopComponent ID
* @since 4.13 */
protected abstract String topComponentID(TopComponent tc, String preferredID);
/**
* Cause this TopComponent's tab to flash or otherwise draw the users' attention
* to it.
* Note to WindowManager providers: This method not abstract for backward compatibility reasons,
* please override and provide implementation.
* @param tc A TopComponent
* @since 5.1 */
protected void topComponentRequestAttention(TopComponent tc) {
}
/**
* Notifies the user that some process is running in the given TopComponent,
* for example by drawing an animated "wait" icon in TopComponent's header.
* The default implementation does nothing.
*
* @param tc
* @param busy True to start 'busy' notification, false to stop it.
*
* @since 6.51
*/
protected void topComponentMakeBusy( TopComponent tc, boolean busy ) {
}
/**
* Attempts to bring the parent Window of the given TopComponent
* to front of other windows.
* @see java.awt.Window#toFront()
* @since 5.8
*/
protected void topComponentToFront(TopComponent tc) {
Window parentWindow = SwingUtilities.getWindowAncestor(tc);
// be defensive, although w probably will always be non-null here
if (null != parentWindow) {
if (parentWindow instanceof Frame) {
Frame parentFrame = (Frame) parentWindow;
int state = parentFrame.getExtendedState();
if ((state & Frame.ICONIFIED) > 0) {
parentFrame.setExtendedState(state & ~Frame.ICONIFIED);
}
}
parentWindow.toFront();
}
}
/**
* Stop this TopComponent's tab from flashing if it is flashing.
* Note to WindowManager providers: This method not abstract for backward compatibility reasons,
* please override and provide implementation.
*
* @param tc A TopComponent
* @since 5.1 */
protected void topComponentCancelRequestAttention(TopComponent tc) {
}
/**
* Highlights the tab of the given TopComponent until user activates it.
* @param tc
* @param highlight True to highlight the tab, false to switch the highlight off.
* @since 6.58
*/
protected void topComponentAttentionHighlight(TopComponent tc, boolean highlight) {
}
/** Returns unique ID for specified TopComponent.
* @param tc TopComponent the component for which is ID returned
* @return unique TopComponent ID
* @since 4.13 */
public String findTopComponentID(TopComponent tc) {
return topComponentID(tc, tc.preferredID());
}
/** Returns TopComponent for given unique ID.
* @param tcID unique TopComponent ID
* @return TopComponent instance corresponding to unique ID
* @since 4.15 */
public abstract TopComponent findTopComponent(String tcID);
/** Provides support for executing a piece of code when UI of the window
* system is ready.
* The behaviour is similar to {@link EventQueue#invokeLater}
* moreover it is guaranteed that only one Runnable runs at given time.
* This method can be invoked from any thread.
*
*
* // some initialization method
* public static void init () {
* WindowManager.getDefault().invokeWhenUIReady(new Runnable() {
* public void run() {
* // code to be invoked when system UI is ready
* }
* );
* }
*
*
* Note to WindowManager providers: This method is not abstract for backward compatibility reasons,
* please override and provide implementation.
*
* @param run the runnable that executes piece of code when UI of the system is ready
* @since 6.8
*/
public void invokeWhenUIReady(Runnable run) {
EventQueue.invokeLater(run);
}
/**
* Window2/Roles. Each role has a unique name corresponding
* to a sub-folder in Window2/Roles. The content of a role sub-folder has
* the same syntax and meaning as the default window layout in Windows2 folder.
* The content of role sub-folder is merged with the defaults in Windows2 folder
* when the window system loads. User's changes to the window layout are persisted
* per role. So user's customizations in role A are not propagated to
* role B and vice versa.
*
* The whole operation may take a few seconds to complete.
Windows that were opened in previous role but are not opened or present
* in the new role will receive TopComponent.componentClosed() notification.
Note: To keep the main window showing while switching the role, use the following branding:
* org.netbeans.core.windows.WinSys.Show.Hide.MainWindow.While.Switching.Role=false
*
Note: Action org.netbeans.core.windows.actions.SwitchRoleKeepDocumentsAction
* in Actions/Window layer folder can change the role too but it
* also attempts to keep documents from previous role opened in the new role as well.
* The new role name is ActionEvent.getActionCommand() argument.
*
If the window system has been already loaded then the method must be
* called from EDT thread, otherwise it's safe to set the initial startup
* role in e.g. ModuleInstall.restored() method.