PaletteController


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.netbeans.spi.palette;
21  
22  import java.awt.datatransfer.DataFlavor  ;
23  import java.beans.PropertyChangeListener  ;
24  import java.beans.PropertyChangeSupport  ;
25  import org.netbeans.modules.palette.Category;
26  import org.netbeans.modules.palette.Item;
27  import org.netbeans.modules.palette.Model;
28  import org.netbeans.modules.palette.ModelListener;
29  import org.netbeans.modules.palette.Settings;
30  import org.openide.util.Lookup;
31  
32  /**
33   * <p>PaletteController provides access to data in the palette. If an instance
34   * of this class is in the <code>Lookup</code> of any <code>TopComponent</code> 
35   * then the palette window opens and displays a new content when that 
36   * <code>TopComponent</code> opens/activates. 
37   * <br>
38   * Use <code>PaletteFactory</code> to construct a new instance of this class.</p>
39   * 
40   * <p>There's a number of attributes that can override the default palette behavior.
41   * If the palette data are defined in the layers then the palette looks for attributes
42   * of the folders and files (<code>FileObject.getAttribute</code>). If the palette
43   * data are defined as Nodes then the attributes are extracted using <code>Node.getValue</code>.</p>
44   * 
45   * <p>User can override attribute values in palette's user interface. Attribute values
46   * are persisted and restored after IDE restarts.</p>
47   *
48   * @author S. Aubrecht
49   */
50  
51  public final class PaletteController {
52  
53      /**
54       * <code>DataFlavor</code> of palette items dragged from palette to editor. 
55       * The trasfer data returned from <code>Transferable</code> for this 
56       * <code>DataFlavor</code> is the <code>Lookup</code> of the <code>Node</code>
57       * representing the palette item being dragged.
58       */
59      public static final DataFlavor   ITEM_DATA_FLAVOR;
60      static {
61          try {
62              ITEM_DATA_FLAVOR = new DataFlavor  ("application/x-java-openide-paletteitem;class=org.openide.util.Lookup", // NOI18N
63                      "Paste Item", // XXX missing I18N!
64                      Lookup.class.getClassLoader());
65          } catch (ClassNotFoundException   e) {
66              throw new AssertionError  (e);
67          }
68      }
69  
70      // Names of attributes of palette items and categories that the palette supports.
71      // User can override their values in palette's user interface. Attribute values
72      // are persisted and restored after IDE restarts.
73      //
74      // Palette clients can override these attributes in their palette model 
75      // (folder and file attributes in layers or Node attributes) to change
76      // palette's initial state.
77      
78      /**
79       * The width of palette items in pixels, if this attribute is set to -1 or is
80       * missing then the item width will be calculated dynamically depending on the length of 
81       * item display names and may differ for each category (therefore each category
82       * may have a different number of columns).
83       * This attribute applies to palette's root only and is read-only.
84       * Default value is "-1".
85       */
86      public static final String   ATTR_ITEM_WIDTH = "itemWidth";
87      /**
88       * "true" to show item names in the palette panel, "false" to show item icons only.
89       * This attribute applies to palette's root only.
90       * Default value is "true".
91       */
92      public static final String   ATTR_SHOW_ITEM_NAMES = "showItemNames";
93      /**
94       * Item icon size. 
95       * This attribute applies to palette's root only.
96       * Default value is java.beans.BeanInfo.ICON_COLOR_16x16
97       * @see java.beans.BeanInfo
98       */
99      public static final String   ATTR_ICON_SIZE = "iconSize";
100     /**
101      * "true" if palette category is expanded, "false" if category is collapsed.
102      * Default value is "false".
103      */
104     public static final String   ATTR_IS_EXPANDED = "isExpanded";
105     /**
106      * "true" if palette category or item is visible in the palette, "false" if 
107      * the category or item is visible in palette customizer only.
108      * Default value is "true".
109      */
110     public static final String   ATTR_IS_VISIBLE = "isVisible";
111     /**
112      * "true" if the category or item cannot be removed, "false" otherwise.
113      * Users cannot override this attribute's value.
114      * Default value is "false".
115      */
116     public static final String   ATTR_IS_READONLY = "isReadonly";
117     /**
118      * Use this attribut for palette's root, category or item to specify its
119      * help id.
120      * Default value is "CommonPalette".
121      */
122     public static final String   ATTR_HELP_ID = "helpId";
123 
124     /**
125      * Palette clients should listen to changes of this property if they want to
126      * notified when the selected item in palette has changed.
127      */
128     public static final String   PROP_SELECTED_ITEM = Model.PROP_SELECTED_ITEM;
129     
130     /**
131      * Palette data model.
132      */
133     private Model model;
134     /**
135      * Palette user settings (expanded/collapsed categories, hidden/visible items etc).
136      */
137     private Settings settings;
138     
139     private PropertyChangeSupport   support ;
140     
141     //:::::::::::::::::::::::::::::::::::::
142     
143     private PaletteController() {
144     }
145     
146     /** Create new instance of PaletteController */
147     PaletteController( Model model, Settings settings ) {
148         this.model = model;
149         this.settings = settings;
150 
151         support = new PropertyChangeSupport  ( this );
152         this.model.addModelListener( new ModelListener() {
153             public void propertyChange(java.beans.PropertyChangeEvent   evt) {
154                 if( Model.PROP_SELECTED_ITEM.equals( evt.getPropertyName() ) ) {
155                     Lookup oldValue = null == evt.getOldValue() ? Lookup.EMPTY : ((Item)evt.getOldValue()).getLookup();
156                     Lookup newValue = null == evt.getNewValue() ? Lookup.EMPTY : ((Item)evt.getNewValue()).getLookup();
157                     support.firePropertyChange( PROP_SELECTED_ITEM, oldValue, newValue );
158                 }
159             }
160 
161             public void categoriesRemoved(Category[] removedCategories) {
162                 //not interested
163             }
164 
165             public void categoriesAdded(Category[] addedCategories) {
166                 //not interested
167             }
168 
169             public void categoriesReordered() {
170                 //not interested
171             }
172         });
173     }
174     
175     public void addPropertyChangeListener( PropertyChangeListener   listener ) {
176         support.addPropertyChangeListener( listener );
177     }
178     
179     public void removePropertyChangeListener( PropertyChangeListener   listener ) {
180         support.removePropertyChangeListener( listener );
181     }
182     
183     /**
184      * @return Lookup representing the item currently selected in the palette. 
185      * The lookup is empty if no item is currently selected.
186      */
187     public Lookup getSelectedItem() {
188         Item selItem = model.getSelectedItem();
189         return null == selItem ? Lookup.EMPTY : selItem.getLookup();
190     }
191     
192     /**
193      * Select a new item in the palette window.
194      *
195      * @param category Lookup of the category that contains the item to be selected.
196      * @param item Item's lookup.
197      */
198     public void setSelectedItem( Lookup category, Lookup item ) {
199         model.setSelectedItem( category, item );
200     }
201     
202     /**
203      * @return Lookup representing the category of currently selected item. 
204      * The lookup is empty if no item is currently selected.
205      */
206     public Lookup getSelectedCategory() {
207         Category selCategory = model.getSelectedCategory();
208         return null == selCategory ? Lookup.EMPTY : selCategory.getLookup();
209     }
210     
211     /**
212      * Clear selection in palette (i.e. no item is selected)
213      */
214     public void clearSelection() {
215         model.clearSelection();
216     }
217     
218     /**
219      * Refresh the list of categories and items, e.g. when PaletteFilter conditions
220      * have changed.
221      */
222     public void refresh() {
223         model.refresh();
224     }
225     
226     /**
227      * Open the default Palette Manager window to allow user to customize palette's
228      * contents, especially add/import new items to palette.
229      */
230     public void showCustomizer() {
231         model.showCustomizer( this, settings );
232     }
233     
234     /**
235      * @return Lookup representing palette's root folder.
236      */
237     public Lookup getRoot() {
238         return model.getRoot();
239     }
240 
241     Model getModel() {
242         return model;
243     }
244     
245     /**
246      * For unit-testing only.
247      */
248     void setModel( Model model ) {
249         this.model = model;
250     }
251 
252     Settings getSettings() {
253         return settings;
254     }
255 }
256
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags