ExplorerUtils


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  package org.openide.explorer;
20  
21  import org.openide.nodes.*;
22  import org.openide.util.*;
23  
24  import javax.swing.Action  ;
25  import javax.swing.ActionMap  ;
26  
27  /**
28   * Helper methods to embed <code>ExplorerManager</code>s and explorer views
29   * into Swing component trees.
30   * <p>
31   * To create a component that displays the content of an {@link ExplorerManager} you
32   * should make your component implement {@link ExplorerManager.Provider} and
33   * {@link org.openide.util.Lookup.Provider} and register actions in your component's {@link ActionMap}:
34  <pre>
35  <span class="keyword">public</span> <span class="keyword">class</span> <span class="type">YourComponent</span> <span class="keyword">extends</span> <span class="type">TopComponent</span>
36  <span class="keyword">implements</span> <span class="type">ExplorerManager.Provider</span>, <span class="type">Lookup.Provider</span> {
37      <span class="keyword">private</span> <span class="type">ExplorerManager</span> <span class="variable-name">manager</span>;
38      <span class="keyword">public</span> <span class="type">YourComponent</span>() {
39          <span class="keyword">this</span>.manager = <span class="keyword">new</span> <span class="type">ExplorerManager</span>();
40          <span class="type">ActionMap</span> map = <span class="keyword">this</span>.getActionMap ();
41          map.put(DefaultEditorKit.copyAction, ExplorerUtils.actionCopy(manager));
42          map.put(DefaultEditorKit.cutAction, ExplorerUtils.actionCut(manager));
43          map.put(DefaultEditorKit.pasteAction, ExplorerUtils.actionPaste(manager));
44          map.put(<span class="string">"delete"</span>, ExplorerUtils.actionDelete(manager, <span class="constant">true</span>)); <span class="comment">// or false</span>
45   *
46          <span class="comment">// following line tells the top component which lookup should be associated with it</span>
47          associateLookup (ExplorerUtils.createLookup (manager, map));
48  </span>    }
49      <span class="keyword">public</span> <span class="type">ExplorerManager</span> <span class="function-name">getExplorerManager</span>() {
50          <span class="keyword">return</span> manager;
51      }
52      <span class="comment">// It is good idea to switch all listeners on and off when the
53  </span>    <span class="comment">// component is shown or hidden. In the case of TopComponent use:
54  </span>    <span class="keyword">protected</span> <span class="type">void</span> <span class="function-name">componentActivated</span>() {
55          ExplorerUtils.activateActions(manager, <span class="constant">true</span>);
56      }
57      <span class="keyword">protected</span> <span class="type">void</span> <span class="function-name">componentDeactivated</span>() {
58          ExplorerUtils.activateActions(manager, <span class="constant">false</span>);
59      }
60  }
61  </pre>
62   * The above code will work in a NetBeans module. For a standalone NetBeans-based application
63   * you will need to set up your {@link javax.swing.InputMap} and use different triggers to
64   * turn the listeners on and off:
65  <pre>
66  <span class="keyword">public</span> <span class="keyword">class</span> <span class="type">YourComponent</span> <span class="keyword">extends</span> <span class="type">JPanel</span>
67  <span class="keyword">implements</span> <span class="type">ExplorerManager.Provider</span>, <span class="type">Lookup.Provider</span> {
68      <span class="keyword">private</span> <span class="type">ExplorerManager</span> <span class="variable-name">manager</span>;
69      <span class="keyword">private</span> <span class="type">Lookup</span> <span class="variable-name">lookup</span>;
70  </span>    <span class="keyword">public</span> <span class="type">YourComponent</span>() {
71          <span class="comment">// same as before...</span>
72          manager = <span class="keyword">new</span> <span class="type">ExplorerManager</span>();
73          <span class="type">ActionMap</span> <span class="variable-name">map</span> = getActionMap();
74          map.put(DefaultEditorKit.copyAction, ExplorerUtils.actionCopy(manager));
75          map.put(DefaultEditorKit.cutAction, ExplorerUtils.actionCut(manager));
76          map.put(DefaultEditorKit.pasteAction, ExplorerUtils.actionPaste(manager));
77          map.put(<span class="string">"delete"</span>, ExplorerUtils.actionDelete(manager, <span class="constant">true</span>)); <span class="comment">// or false
78  </span>
79          <span class="comment">// ...but add e.g.:
80  </span>        <span class="type">InputMap</span> <span class="variable-name">keys</span> = getInputMap(JComponent.WHEN_ANCESTOR_OF_FOCUSED_COMPONENT);
81          keys.put(KeyStroke.getKeyStroke(<span class="string">"control C"</span>), DefaultEditorKit.copyAction);
82          keys.put(KeyStroke.getKeyStroke(<span class="string">"control X"</span>), DefaultEditorKit.cutAction);
83          keys.put(KeyStroke.getKeyStroke(<span class="string">"control V"</span>), DefaultEditorKit.pasteAction);
84          keys.put(KeyStroke.getKeyStroke(<span class="string">"DELETE"</span>), <span class="string">"delete"</span>);
85  
86          <span class="comment">// ...and initialization of lookup variable</span>
87          lookup = ExplorerUtils.createLookup (manager, map);
88      }
89      <span class="comment">// ...method as before and getLookup</span>
90      <span class="keyword">public</span> <span class="type">ExplorerManager</span> <span class="function-name">getExplorerManager</span>() {
91          <span class="keyword">return</span> manager;
92      }
93      <span class="keyword">public</span> <span class="type">Lookup</span> <span class="function-name">getLookup</span>() {
94          <span class="keyword">return</span> lookup;
95      }
96      <span class="comment">// ...methods as before, but replace componentActivated and
97  </span>    <span class="comment">// componentDeactivated with e.g.:
98  </span>    <span class="keyword">public</span> <span class="type">void</span> <span class="function-name">addNotify</span>() {
99          <span class="keyword">super</span>.addNotify();
100         ExplorerUtils.activateActions(manager, <span class="constant">true</span>);
101     }
102     <span class="keyword">public</span> <span class="type">void</span> <span class="function-name">removeNotify</span>() {
103         ExplorerUtils.activateActions(manager, <span class="constant">false</span>);
104         <span class="keyword">super</span>.removeNotify();
105     }
106 }
107 </pre>
108  * @author Jaroslav Tulach
109  * @since 4.14
110  */
111 public final class ExplorerUtils extends Object   {
112     /** Just package private subclass
113      */
114     ExplorerUtils() {
115     }
116 
117     //
118     // Public factory methods
119     //
120 
121     /** Creates copy action
122      * @param em explorer manager the action should be attached to
123      * @return action that invokes copy on the explorer
124      */
125     public static Action   actionCopy(ExplorerManager em) {
126         return ExplorerManager.findExplorerActionsImpl(em).copyAction();
127     }
128 
129     /** Creates cut action
130      * @param em explorer manager the action should be attached to
131      * @return action that invokes cut on the explorer
132      */
133     public static Action   actionCut(ExplorerManager em) {
134         return ExplorerManager.findExplorerActionsImpl(em).cutAction();
135     }
136 
137     /** Creates delete action
138      * @param em explorer manager the action should be attached to
139      * @param confirm true if a confirmation box should be displayed before actual deletion
140      * @return action that invokes delete on the explorer
141      */
142     public static Action   actionDelete(ExplorerManager em, boolean confirm) {
143         ExplorerActionsImpl impl = ExplorerManager.findExplorerActionsImpl(em);
144 
145         return impl.deleteAction(confirm);
146     }
147 
148     /** Creates paste action
149      * @param em explorer manager the action should be attached to
150      * @return action that invokes paste on the explorer
151      */
152     public static Action   actionPaste(ExplorerManager em) {
153         return ExplorerManager.findExplorerActionsImpl(em).pasteAction();
154     }
155 
156     /** Activates or deactivates updates of actions for given <code>ExplorerManager</code>.
157      * By default actions created by <code>actionXXX</code> factory methods
158      * are started and update itself according to changes in external environment
159      * (the explorer manager itself, clipboard content, etc.). This might not
160      * be necessary and a bit of resource consuming in case when the component
161      * showing the <code>ExplorerManager</code> is not visible. In such case
162      * the implementation can disable and then again reenable refresh by calling
163      * this method.
164      *
165      * @param em the explorer manager
166      * @param enable true if actions should be updated, false otherwise
167      */
168     public static void activateActions(ExplorerManager em, boolean enable) {
169         if (enable) {
170             ExplorerManager.findExplorerActionsImpl(em).attach(em);
171         } else {
172             ExplorerManager.findExplorerActionsImpl(em).detach();
173         }
174     }
175 
176     /** Creates new lookup containing selected nodes and their lookups.
177      * @param em explorer manager which selection to follow
178      * @param map additional map to be added into the lookup
179      *
180      * @return lookup that updates itself according the changes inside the ExplorerManager
181      */
182     public static Lookup createLookup(ExplorerManager em, ActionMap   map) {
183         return new DefaultEMLookup(em, map);
184     }
185 
186     /** Utility method to get context help from a node selection.
187      *  Tries to find context helps for selected nodes.
188      *  If there are some, and they all agree, uses that.
189      *  In all other cases, uses the supplied generic help.
190      *
191      *  @param sel a list of nodes to search for help in
192      *  @param def the default help to use if they have none or do not agree
193      *  @return a help context
194      * @since 4.40
195      */
196     public static HelpCtx getHelpCtx(Node[] sel, HelpCtx def) {
197         HelpCtx result = null;
198 
199         for (int i = 0; i < sel.length; i++) {
200             HelpCtx attempt = sel[i].getHelpCtx();
201 
202             if ((attempt != null) && !attempt.equals(HelpCtx.DEFAULT_HELP)) {
203                 if ((result == null) || result.equals(attempt)) {
204                     result = attempt;
205                 } else {
206                     // More than one found, and they conflict. Get general help on the Explorer instead.
207                     result = null;
208 
209                     break;
210                 }
211             }
212         }
213 
214         return (result != null) ? result : def;
215     }
216 }
217
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags