Java > Open Source Codes > org > openide > windows > WindowManager


1 /*
2  * The contents of this file are subject to the terms of the Common Development
3  * and Distribution License (the License). You may not use this file except in
4  * compliance with the License.
5  *
6  * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7  * or http://www.netbeans.org/cddl.txt.
8  *
9  * When distributing Covered Code, include this CDDL Header Notice in each file
10  * and include the License file at http://www.netbeans.org/cddl.txt.
11  * If applicable, add the following below the CDDL Header, with the fields
12  * enclosed by brackets [] replaced by your own identifying information:
13  * "Portions Copyrighted [year] [name of copyright owner]"
14  *
15  * The Original Software is NetBeans. The Initial Developer of the Original
16  * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17  * Microsystems, Inc. All Rights Reserved.
18  */
19
20 package org.openide.windows;
21
22 import java.awt.EventQueue ;
23 import java.awt.Frame ;
24 import java.awt.Image ;
25 import java.awt.Window ;
26 import java.beans.PropertyChangeListener ;
27 import java.io.Serializable ;
28 import java.util.Set ;
29 import java.util.logging.Level ;
30 import java.util.logging.Logger ;
31 import javax.swing.SwingUtilities ;
32 import org.openide.nodes.Node;
33 import org.openide.util.Lookup;
34
35 /**
36  * Manages window system.
37  * Allows the work with window system components, i.e. <code>Mode</code>s, <code>TopComponentGroup</code>s
38  * and provides handling of operations provided over <code>TopComponent</code>s.
39  * <p><p>
40  * <b><font color="red"><em>Important note: Do not provide implementation of this abstract class unless you are window system provider!</em></font></b>
41  *
42  * @author Jaroslav Tulach
43  */
44 public abstract class WindowManager extends Object implements Serializable {
45     /** property change of workspaces.
46      * @deprecated Do not use. Workspaces are not supported anymore. */
47     @Deprecated
48     public static final String PROP_WORKSPACES = "workspaces"; // NOI18N
49
50     /** property change of current workspace.
51      * @deprecated Do not use. Workspaces are not supported anymore.
52      */
53     @Deprecated
54     public static final String PROP_CURRENT_WORKSPACE = "currentWorkspace"; // NOI18N
55
56     /** Name of property for modes in the workspace.
57      * @since 4.13 */
58     public static final String PROP_MODES = "modes"; // NOI18N
59
60     /** Instance of dummy window manager. */
61     private static WindowManager dummyInstance;
62     static final long serialVersionUID = -4133918059009277602L;
63
64     /** The top component which is currently active */
65     private TopComponent activeComponent;
66
67     /** the registry */
68     private TopComponent.Registry registry;
69
70     /** Singleton instance accessor method for window manager. Provides entry
71      * point for further work with window system API of the system.
72      *
73      * @return instance of window manager installed in the system
74      * @since 2.10
75      */
76     public static final WindowManager getDefault() {
77         WindowManager wmInstance = Lookup.getDefault().lookup(WindowManager.class);
78
79         return (wmInstance != null) ? wmInstance : getDummyInstance();
80     }
81
82     private static synchronized WindowManager getDummyInstance() {
83         if (dummyInstance == null) {
84             dummyInstance = new DummyWindowManager();
85         }
86
87         return dummyInstance;
88     }
89
90     /** Finds mode of specified name.
91      * @return <code>Mode</code> whith the specified name is or <code>null</code>
92      * if there does not exist such <code>Mode</code> inside window system.
93      * @since 4.13 */
94     public abstract Mode findMode(String name);
95
96     /** Finds mode which contains specified <code>TopComponent</code>.
97      * @return <code>Mode</code> which contains specified <code>TopComponent</code> or <code>null</code>
98      * if the <code>TopComponent</code> is not added into any <code>Mode</code> inside window system.
99      * @since 4.13 */
100     public abstract Mode findMode(TopComponent tc);
101
102     /** Gets set of all <code>Mode</code>S added into window system.
103      * @since 4.13 */
104     public abstract Set <? extends Mode> getModes();
105
106     /**
107      * Gets the NetBeans Main Window.
108     * This should ONLY be used for:
109     * <UL>
110     * <LI>using the Main Window as the parent for dialogs</LI>
111     * <LI>using the Main Window's position for preplacement of windows</LI>
112     * </UL>
113     * @return the Main Window
114     */
115     public abstract Frame getMainWindow();
116
117     /** Called after a Look&amp;Feel change to update the NetBeans UI.
118     * Should call {@link javax.swing.JComponent#updateUI} on all opened windows.
119     */
120     public abstract void updateUI();
121
122     /** Create a component manager for the given top component.
123     * @param c the component
124     * @return the manager to handle opening, closing and selecting the component
125     */
126     protected abstract WindowManager.Component createTopComponentManager(TopComponent c);
127
128     /** Access method for registry of all components in the system.
129     * @return the registry
130     */
131     protected TopComponent.Registry componentRegistry() {
132         return Lookup.getDefault().lookup(TopComponent.Registry.class);
133     }
134
135     /** Getter for component registry.
136     * @return the registry
137     */
138     public synchronized TopComponent.Registry getRegistry() {
139         if (registry != null) {
140             return registry;
141         }
142
143         registry = componentRegistry();
144
145         return registry;
146     }
147
148     /** Creates new workspace.
149      * @param name the name of the workspace
150      * @return new workspace
151      * @deprecated Do not use. Workspaces are not supported anymore. */
152     @Deprecated
153     public final Workspace createWorkspace(String name) {
154         return createWorkspace(name, name);
155     }
156
157     /** Creates new workspace with I18N support.
158      * Note that it will not be displayed until {@link #setWorkspaces} is called
159      * with an array containing the new workspace.
160      * @param name the code name (used for internal purposes)
161      * @param displayName the display name
162      * @return the new workspace
163      * @deprecated Do not use. Workspaces are not supported anymore. */
164     @Deprecated
165     public abstract Workspace createWorkspace(String name, String displayName);
166
167     /** Finds workspace given its name.
168      * @param name the (code) name of workspace to find
169      * @return workspace or null if not found
170      * @deprecated Do not use. Workspaces are not supported anymore. */
171     @Deprecated
172     public abstract Workspace findWorkspace(String name);
173
174     /**
175      * Gets a list of all workspaces.
176      * @return an array of all known workspaces
177      * @deprecated Do not use. Workspaces are not supported anymore. */
178     @Deprecated
179     public abstract Workspace[] getWorkspaces();
180
181     /** Sets new array of workspaces.
182      * In conjunction with {@link #getWorkspaces}, this may be used to reorder
183      * workspaces, or add or remove workspaces.
184      * @param workspaces An array consisting of new workspaces.
185      * @deprecated Do not use. Workspaces are not supported anymore. */
186     @Deprecated
187     public abstract void setWorkspaces(Workspace[] workspaces);
188
189     /**
190      * Gets the current workspace.
191      * @return the currently active workspace
192      * @see Workspace#activate
193      * @deprecated Do not use. Workspaces are not supported anymore. */
194     @Deprecated
195     public abstract Workspace getCurrentWorkspace();
196
197     /** Finds <code>TopComponentGroup</code> of given name.
198      * @return instance of TopComponetnGroup or null
199      * @since 4.13 */
200     public abstract TopComponentGroup findTopComponentGroup(String name);
201
202     //
203 // You can add implementation to this class (+firePropertyChange), or implement it in subclass
204 // Do as you want.
205 //
206
207     /**
208      * Attaches a listener for changes in workspaces.
209      * @param l the new listener
210      */
211     public abstract void addPropertyChangeListener(PropertyChangeListener l);
212
213     /**
214      * Removes a listener for changes in workspaces.
215      * @param l the listener to remove
216      */
217     public abstract void removePropertyChangeListener(PropertyChangeListener l);
218
219     /** Finds top component manager for given top component.
220      * @param tc top component to find manager for.
221      * @return component manager for given top component.
222      * @deprecated Do not use anymore.
223      * See {@link WindowManager.Component} deprecation.
224      */
225     @Deprecated
226     protected static final Component findComponentManager(TopComponent tc) {
227         return null;
228     }
229
230     /** Activate a component. The top component containers should inform
231     * the top component that it is active via a call to this method through
232     * derived window manager implementation.
233     * @param tc the top component to activate;
234     * or <code>null</code> to deactivate all top components
235     */
236     protected void activateComponent(TopComponent tc) {
237         // check
238 if (activeComponent == tc) {
239             return;
240         }
241
242         // deactivate old if possible
243 if (activeComponent != null) {
244             try {
245                 activeComponent.componentDeactivated();
246             } catch (RuntimeException re) {
247                 IllegalStateException ise = new IllegalStateException (
248                         "[Winsys] TopComponent " + activeComponent // NOI18N
249 +" throws runtime exception from its componentDeactivated() method. Repair it!"
250                     ); // NOI18N
251 ise.initCause(re);
252                 Logger.getLogger(WindowManager.class.getName()).log(Level.WARNING, null, ise);
253             }
254         }
255
256         activeComponent = tc;
257
258         if (activeComponent != null) {
259             try {
260                 activeComponent.componentActivated();
261             } catch (RuntimeException re) {
262                 IllegalStateException ise = new IllegalStateException (
263                         "[Winsys] TopComponent " + activeComponent // NOI18N
264 +" throws runtime exception from its componentActivated() method. Repair it!"
265                     ); // NOI18N
266 ise.initCause(re);
267                 Logger.getLogger(WindowManager.class.getName()).log(Level.WARNING, null, ise);
268             }
269         }
270     }
271
272     /** Notifies component that it was opened (and wasn't opened on any
273      * workspace before). Top component manager that implements Component
274      * inner interface of this class should send open notifications via
275      * calling this method
276      * @param tc the top component to be notified
277      */
278     protected void componentOpenNotify(TopComponent tc) {
279         try {
280             tc.componentOpened();
281         } catch (RuntimeException re) {
282             IllegalStateException ise = new IllegalStateException (
283                     "[Winsys] TopComponent " + tc // NOI18N
284 +" throws runtime exception from its componentOpened() method. Repair it!"
285                 ); // NOI18N
286 ise.initCause(re);
287             Logger.getLogger(WindowManager.class.getName()).log(Level.WARNING, null, ise);
288         }
289     }
290
291     /** Notifies component that it was closed (and is not opened on any
292      * workspace anymore). Top component manager that implements Component
293      * inner interface of this class should send close notifications via
294      * calling this method
295      * @param tc the top component to be notified
296      */
297     protected void componentCloseNotify(TopComponent tc) {
298         try {
299             tc.componentClosed();
300         } catch (RuntimeException re) {
301             IllegalStateException ise = new IllegalStateException (
302                     "[Winsys] TopComponent " + tc // NOI18N
303 +" throws runtime exception from its componentClosed() method. Repair it!"
304                 ); // NOI18N
305 ise.initCause(re);
306             Logger.getLogger(WindowManager.class.getName()).log(Level.WARNING, null, ise);
307         }
308
309         if (tc == activeComponent) {
310             activateComponent(null);
311         }
312     }
313
314     /** Notifies <code>TopComponent</code> it is about to be shown.
315      * @param tc <code>TopComponent</code> to be notified
316      * @see TopComponent#componentShowing
317      * @since 2.18 */
318     protected void componentShowing(TopComponent tc) {
319         try {
320             tc.componentShowing();
321         } catch (RuntimeException re) {
322             IllegalStateException ise = new IllegalStateException (
323                     "[Winsys] TopComponent " + tc // NOI18N
324 +" throws runtime exception from its componentShowing() method. Repair it!"
325                 ); // NOI18N
326 ise.initCause(re);
327             Logger.getLogger(WindowManager.class.getName()).log(Level.WARNING, null, ise);
328         }
329     }
330
331     /** Notifies <code>TopComponent</code> it was hidden.
332      * @param tc <code>TopComponent</code> to be notified
333      * @see TopComponent#componentHidden
334      * @since 2.18 */
335     protected void componentHidden(TopComponent tc) {
336         try {
337             tc.componentHidden();
338         } catch (RuntimeException re) {
339             IllegalStateException ise = new IllegalStateException (
340                     "[Winsys] TopComponent " + tc // NOI18N
341 +" throws runtime exception from its componentHidden() method. Repair it!"
342                 ); // NOI18N
343 ise.initCause(re);
344             Logger.getLogger(WindowManager.class.getName()).log(Level.WARNING, null, ise);
345         }
346     }
347
348     /** Provides opening of specified <code>TopComponent</code>.
349      * @param tc <code>TopComponent</code> to open
350      * @since 4.13 */
351     protected abstract void topComponentOpen(TopComponent tc);
352
353     /** Provides closing of specified <code>TopComponent</code>.
354      * @param tc <code>TopComponent</code> to close
355      * @since 4.13 */
356     protected abstract void topComponentClose(TopComponent tc);
357
358     /** Provides activation of specified <code>TopComponent</code>.
359      * @param tc <code>TopComponent</code> to activate
360      * @since 4.13 */
361     protected abstract void topComponentRequestActive(TopComponent tc);
362
363     /** Provides selection of specfied <code>TopComponent</code>.
364      * @param tc <code>TopComponent</code> to set visible (select)
365      * @since 4.13 */
366     protected abstract void topComponentRequestVisible(TopComponent tc);
367
368     /** Informs about change of display name of specified <code>TopComponent</code>.
369      * @param tc <code>TopComponent</code> which display name has changed
370      * @param displayName newly changed display name value
371      * @since 4.13 */
372     protected abstract void topComponentDisplayNameChanged(TopComponent tc, String displayName);
373     
374     /** Informs about change of html display name of specified <code>TopComponent</code>.
375      * @param tc <code>TopComponent</code> which display name has changed
376      * @param htmlDisplayName newly changed html display name value
377      * @since 6.4 */
378     protected abstract void topComponentHtmlDisplayNameChanged(TopComponent tc, String htmlDisplayName);
379
380     /** Informs about change of tooltip of specified <code>TopComponent</code>.
381      * @param tc <code>TopComponent</code> which tooltip has changed
382      * @param toolTip newly changed tooltip value
383      * @since 4.13 */
384     protected abstract void topComponentToolTipChanged(TopComponent tc, String toolTip);
385
386     /** Informs about chagne of icon of specified <code>TopComponent</code>.
387      * @param tc <code>TopComponent</code> which icon has changed
388      * @param icon newly chaned icon value
389      * @since 4.13 */
390     protected abstract void topComponentIconChanged(TopComponent tc, Image icon);
391
392     /** Informs about change of activated nodes of specified <code>TopComponent</code>.
393      * @param tc <code>TopComponent</code> which activated nodes has chagned
394      * @param activatedNodes newly chaged activated nodes value
395      * @since 4.13 */
396     protected abstract void topComponentActivatedNodesChanged(TopComponent tc, Node[] activatedNodes);
397
398     /** Indicates whether specified <code>TopComponent</code> is opened.
399      * @param tc specified <code>TopComponent</code>
400      * @since 4.13 */
401     protected abstract boolean topComponentIsOpened(TopComponent tc);
402
403     /** Gets default list of actions which appear in popup menu of TopComponent.
404      * The popup menu which is handled by window systsm implementation, typically at tab.
405      * @param tc <code>TopComponent</code> for which the default actions to provide
406      * @since 4.13 */
407     protected abstract javax.swing.Action [] topComponentDefaultActions(TopComponent tc);
408
409     /** Returns unique ID for specified <code>TopComponent</code>.
410      * @param tc <code>TopComponent</code> the component for which is ID returned
411      * @param preferredID first approximation used for ID
412      * @return unique <code>TopComponent</code> ID
413      * @since 4.13 */
414     protected abstract String topComponentID(TopComponent tc, String preferredID);
415
416     /**
417      * Cause this TopComponent's tab to flash or otherwise draw the users' attention
418      * to it.
419      * Note to WindowManager providers: This method not abstract for backward compatibility reasons,
420      * please override and provide implementation.
421      * @param tc A TopComponent
422      * @since 5.1 */
423     protected void topComponentRequestAttention(TopComponent tc) {
424     }
425
426     /**
427      * Attempts to bring the parent <code>Window</code> of the given <code>TopComponent</code>
428      * to front of other windows.
429      * @see java.awt.Window#toFront()
430      * @since 5.8
431      */
432     protected void topComponentToFront(TopComponent tc) {
433         Window parentWindow = SwingUtilities.getWindowAncestor(tc);
434
435         // be defensive, although w probably will always be non-null here
436 if (null != parentWindow) {
437             if (parentWindow instanceof Frame ) {
438                 Frame parentFrame = (Frame ) parentWindow;
439                 int state = parentFrame.getExtendedState();
440
441                 if ((state & Frame.ICONIFIED) > 0) {
442                     parentFrame.setExtendedState(state & ~Frame.ICONIFIED);
443                 }
444             }
445
446             parentWindow.toFront();
447         }
448     }
449
450     /**
451      * Stop this TopComponent's tab from flashing if it is flashing.
452      * Note to WindowManager providers: This method not abstract for backward compatibility reasons,
453      * please override and provide implementation.
454      *
455      * @param tc A TopComponent
456      * @since 5.1 */
457     protected void topComponentCancelRequestAttention(TopComponent tc) {
458     }
459
460     /** Returns unique ID for specified <code>TopComponent</code>.
461      * @param tc <code>TopComponent</code> the component for which is ID returned
462      * @return unique <code>TopComponent</code> ID
463      * @since 4.13 */
464     public String findTopComponentID(TopComponent tc) {
465         return topComponentID(tc, tc.preferredID());
466     }
467
468     /** Returns <code>TopComponent</code> for given unique ID.
469      * @param tcID unique <code>TopComponent</code> ID
470      * @return <code>TopComponent</code> instance corresponding to unique ID
471      * @since 4.15 */
472     public abstract TopComponent findTopComponent(String tcID);
473     
474     /** Provides support for executing a piece of code when UI of the window
475      * system is ready.
476      * The behaviour is similar to {@link EventQueue#invokeLater}
477      * moreover it is guaranteed that only one Runnable runs at given time.
478      * This method can be invoked from any thread.
479      *
480      * <p class="non-normative">
481      * The typical usecase is to call this method during startup of NetBeans
482      * based application. The default manager then waits till the main window
483      * is opened and then executes all the registered methods one by one.
484      * </p>
485      *
486      * <b>Usage:</b>
487      * <pre>
488      * // some initialization method
489      * public static void init () {
490      * WindowManager.getDefault().invokeWhenUIReady(new Runnable() {
491      * public void run() {
492      * // code to be invoked when system UI is ready
493      * }
494      * );
495      * }
496      * </pre>
497      *
498      * Note to WindowManager providers: This method is not abstract for backward compatibility reasons,
499      * please override and provide implementation.
500      *
501      * @param run the runnable that executes piece of code when UI of the system is ready
502      * @since 6.8
503      */
504     public void invokeWhenUIReady(Runnable run) {
505         EventQueue.invokeLater(run);
506     }
507     
508     /**
509      * <p>Check whether the given TopComponent will be/is docked into an 'editor' Mode.</p>
510      * <p>Please note that some TopComponents may be docked into 'editor' modes as well as
511      * 'view' modes, see method isTopComponentAllowedToMoveAnywhere().</p>
512      *
513      * @param tc TopComponent to check.
514      * @return True if there is a Mode that the TopComponent will be/is docked to and
515      * the Mode is of 'editor' kind (i.e. holds editor windows).
516      * @since 6.13
517      */
518     public boolean isEditorTopComponent( TopComponent tc ) {
519         return false;
520     }
521
522     /**
523      * <p>Check whether the given Mode holds editor windows.</p>
524      * <p>Please note that some TopComponents may be docked into 'editor' modes as well as
525      * 'view' modes, see method isTopComponentAllowedToMoveAnywhere().</p>
526      *
527      * @param mode Mode to check.
528      * @return True the Mode contains editor windows.
529      * @since 6.13
530      */
531     public boolean isEditorMode( Mode mode ) {
532         return false;
533     }
534     
535     /** A manager that handles operations on top components.
536      * It is always attached to a {@link TopComponent}.
537      * @deprecated Do not use anymore. This interface is replaced by bunch of protected methods
538      * which name starts with topComponent prefix, i.e. {@link #topComponentOpen}, {@link #topComponentClose} etc. */
539     @SuppressWarnings ("deprecation")
540     @Deprecated
541     protected interface Component extends java.io.Serializable {
542         /**
543          * Do not use.
544          * @deprecated Only public by accident.
545          */
546         @Deprecated
547         /* public static final */ long serialVersionUID = 0L;
548
549         /** Open the component on current workspace */
550         public void open();
551
552         /**
553          * Opens this component on a given workspace.
554          * @param workspace the workspace on which to open it
555          */
556         public void open(Workspace workspace);
557
558         /**
559          * Closes this component on a given workspace.
560          * @param workspace the workspace on which to close it
561          */
562         public void close(Workspace workspace);
563
564         /** Called when the component requests focus. Moves it to be visible.
565         */
566         public void requestFocus();
567
568         /** Set this component visible but not selected or focused if possible.
569         * If focus is in other container (multitab) or other pane (split) in
570         * the same container it makes this component only visible eg. it selects
571         * tab with this component.
572         * If focus is in the same container (multitab) or in the same pane (split)
573         * it has the same effect as requestFocus().
574         */
575         public void requestVisible();
576
577         /** Get the set of activated nodes.
578         * @return currently activated nodes for this component
579         */
580         public Node[] getActivatedNodes();
581
582         /** Set the set of activated nodes for this component.
583         * @param nodes new set of activated nodes
584         */
585         public void setActivatedNodes(Node[] nodes);
586
587         /** Called when the name of the top component changes.
588         */
589         public void nameChanged();
590
591         /** Set the icon of the top component.
592         * @param icon the new icon
593         */
594         public void setIcon(final Image icon);
595
596         /**
597          * Gets the icon associated with this component.
598          * @return the icon
599          */
600         public Image getIcon();
601
602         /**
603          * Gets a list of workspaces where this component is currently open.
604          * @return the set of workspaces where the managed component is open
605          */
606         public Set <Workspace> whereOpened();
607     }
608 }
609

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags