PerspectiveDescriptor


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *     Brock Janiczak (brockj_eclipse@ihug.com.au) - handler registration
11   *******************************************************************************/
12  package org.eclipse.ui.internal.registry;
13  
14  import org.eclipse.core.runtime.CoreException;
15  import org.eclipse.core.runtime.IConfigurationElement;
16  import org.eclipse.core.runtime.IStatus;
17  import org.eclipse.core.runtime.Status;
18  import org.eclipse.jface.resource.ImageDescriptor;
19  import org.eclipse.ui.IMemento;
20  import org.eclipse.ui.IPerspectiveDescriptor;
21  import org.eclipse.ui.IPerspectiveFactory;
22  import org.eclipse.ui.IPluginContribution;
23  import org.eclipse.ui.PlatformUI;
24  import org.eclipse.ui.internal.IWorkbenchConstants;
25  import org.eclipse.ui.internal.IWorkbenchGraphicConstants;
26  import org.eclipse.ui.internal.WorkbenchImages;
27  import org.eclipse.ui.internal.WorkbenchPlugin;
28  import org.eclipse.ui.plugin.AbstractUIPlugin;
29  
30  /**
31   * PerspectiveDescriptor.
32   * <p>
33   * A PerspectiveDesciptor has 3 states:
34   * </p>
35   * <ol>
36   * <li>It <code>isPredefined()</code>, in which case it was defined from an
37   * extension point.</li>
38   * <li>It <code>isPredefined()</code> and <code>hasCustomFile</code>, in
39   * which case the user has customized a predefined perspective.</li>
40   * <li>It <code>hasCustomFile</code>, in which case the user created a new
41   * perspective.</li>
42   * </ol>
43   * 
44   */
45  public class PerspectiveDescriptor implements IPerspectiveDescriptor,
46          IPluginContribution {
47      private String   id;
48  
49      private String   pluginId;
50  
51      private String   originalId;
52  
53      private String   label;
54  
55      private String   className;
56  
57      private String   description;
58  
59      private boolean singleton;
60  
61      private boolean fixed;
62  
63      private ImageDescriptor image;
64  
65      private IConfigurationElement configElement;
66  
67      /**
68       * Create a new empty descriptor.
69       * 
70       * @param id
71       *            the id of the new descriptor
72       * @param label
73       *            the label of the new descriptor
74       * @param originalDescriptor
75       *            the descriptor that this descriptor is based on
76       */
77      public PerspectiveDescriptor(String   id, String   label,
78              PerspectiveDescriptor originalDescriptor) {
79          this.id = id;
80          this.label = label;
81          if (originalDescriptor != null) {
82              this.originalId = originalDescriptor.getOriginalId();
83              this.image = originalDescriptor.image;
84  
85              // This perspective is based on a perspective in some bundle -- if
86              // that
87              // bundle goes away then I think it makes sense to treat this
88              // perspective
89              // the same as any other -- so store it with the original
90              // descriptor's
91              // bundle's list.
92              //
93              // It might also make sense the other way...removing the following
94              // line
95              // will allow the perspective to stay around when the originating
96              // bundle
97              // is unloaded.
98              //
99              // This might also have an impact on upgrade cases -- should we
100             // really be
101             // destroying all user customized perspectives when the older
102             // version is
103             // removed?
104             //
105             // I'm leaving this here for now since its a good example, but
106             // wouldn't be
107             // surprised if we ultimately decide on the opposite.
108             //
109             // The reason this line is important is that this is the value used
110             // to
111             // put the object into the UI level registry. When that bundle goes
112             // away,
113             // the registry will remove the entire list of objects. So if this
114             // desc
115             // has been put into that list -- it will go away.
116             this.pluginId = originalDescriptor.getPluginId();
117         }
118     }
119 
120     /**
121      * Create a descriptor from a config element.
122      * 
123      * @param id
124      *            the id of the element to create
125      * @param configElement
126      *            the element to base this perspective on
127      * @throws CoreException
128      *             thrown if there are any missing attributes
129      */
130     public PerspectiveDescriptor(String   id, IConfigurationElement configElement)
131             throws CoreException {
132         this.configElement = configElement;
133         this.id = id;
134         // Sanity check.
135         if ((getId() == null) || (getLabel() == null)
136                 || (getClassName() == null)) {
137             throw new CoreException(
138                     new Status(
139                             IStatus.ERROR,
140                             WorkbenchPlugin.PI_WORKBENCH,
141                             0,
142                             "Invalid extension (missing label, id or class name): " + getId(),//$NON-NLS-1$
143                             null));
144         }
145     }
146 
147     /**
148      * Creates a factory for a predefined perspective. If the perspective is not
149      * predefined return <code>null</code>.
150      * 
151      * @return the IPerspectiveFactory or <code>null</code>
152      * @throws CoreException
153      *             if the object could not be instantiated.
154      */
155     public IPerspectiveFactory createFactory() throws CoreException {
156         // if there is an originalId, then use that descriptor instead
157         if (originalId != null) {
158             // Get the original descriptor to create the factory. If the
159             // original is gone then nothing can be done.
160             IPerspectiveDescriptor target = ((PerspectiveRegistry) WorkbenchPlugin
161                     .getDefault().getPerspectiveRegistry())
162                     .findPerspectiveWithId(originalId);
163 
164             return target == null ? null : ((PerspectiveDescriptor) target)
165                     .createFactory();
166         }
167 
168         // otherwise try to create the executable extension
169         if (configElement != null) {
170             try {
171                 return (IPerspectiveFactory) configElement
172                         .createExecutableExtension(IWorkbenchRegistryConstants.ATT_CLASS);
173             } catch (CoreException e) {
174                 // do nothing
175             }
176         }
177 
178         return null;
179     }
180 
181     /**
182      * Deletes the custom definition for a perspective..
183      */
184     public void deleteCustomDefinition() {
185         ((PerspectiveRegistry) WorkbenchPlugin.getDefault()
186                 .getPerspectiveRegistry()).deleteCustomDefinition(this);
187     }
188 
189     /*
190      * (non-Javadoc)
191      * 
192      * @see org.eclipse.ui.IPerspectiveDescriptor#getDescription()
193      */
194     public String   getDescription() {
195         return configElement == null ? description : RegistryReader
196                 .getDescription(configElement);
197     }
198 
199     /**
200      * Returns whether or not this perspective is fixed.
201      * 
202      * @return whether or not this perspective is fixed
203      */
204     public boolean getFixed() {
205         return configElement == null ? fixed : Boolean.valueOf(
206                 configElement
207                         .getAttribute(IWorkbenchRegistryConstants.ATT_FIXED))
208                 .booleanValue();
209     }
210 
211     /*
212      * (non-Javadoc)
213      * 
214      * @see org.eclipse.ui.IPerspectiveDescriptor#getId()
215      */
216     public String   getId() {
217         return id;
218     }
219 
220     /*
221      * (non-Javadoc)
222      * 
223      * @see org.eclipse.ui.IPerspectiveDescriptor#getImageDescriptor()
224      */
225     public ImageDescriptor getImageDescriptor() {
226         if (image == null) {
227             if (configElement != null) {
228                 String   icon = configElement
229                         .getAttribute(IWorkbenchRegistryConstants.ATT_ICON);
230                 if (icon != null) {
231                     image = AbstractUIPlugin.imageDescriptorFromPlugin(
232                             configElement.getNamespace(), icon);
233                 }
234                 if (image == null) {
235                     image = WorkbenchImages
236                             .getImageDescriptor(IWorkbenchGraphicConstants.IMG_ETOOL_DEF_PERSPECTIVE);
237                 }
238             }
239         }
240         return image;
241     }
242 
243     /*
244      * (non-Javadoc)
245      * 
246      * @see org.eclipse.ui.IPerspectiveDescriptor#getLabel()
247      */
248     public String   getLabel() {
249         return configElement == null ? label : configElement
250                 .getAttribute(IWorkbenchRegistryConstants.ATT_NAME);
251     }
252 
253     /**
254      * Return the original id of this descriptor.
255      * 
256      * @return the original id of this descriptor
257      */
258     public String   getOriginalId() {
259         if (originalId == null) {
260             return getId();
261         }
262         return originalId;
263     }
264 
265     /**
266      * Returns <code>true</code> if this perspective has a custom definition.
267      * 
268      * @return whether this perspective has a custom definition
269      */
270     public boolean hasCustomDefinition() {
271         return ((PerspectiveRegistry) WorkbenchPlugin.getDefault()
272                 .getPerspectiveRegistry()).hasCustomDefinition(this);
273     }
274 
275     /**
276      * Returns <code>true</code> if this perspective wants to be default.
277      * 
278      * @return whether this perspective wants to be default
279      */
280     public boolean hasDefaultFlag() {
281         if (configElement == null) {
282             return false;
283         }
284 
285         return Boolean.valueOf(
286                 configElement
287                         .getAttribute(IWorkbenchRegistryConstants.ATT_DEFAULT))
288                 .booleanValue();
289     }
290 
291     /**
292      * Returns <code>true</code> if this perspective is predefined by an
293      * extension.
294      * 
295      * @return boolean whether this perspective is predefined by an extension
296      */
297     public boolean isPredefined() {
298         return getClassName() != null && configElement != null;
299     }
300 
301     /**
302      * Returns <code>true</code> if this perspective is a singleton.
303      * 
304      * @return whether this perspective is a singleton
305      */
306     public boolean isSingleton() {
307         return configElement == null ? singleton
308                 : configElement
309                         .getAttributeAsIs(IWorkbenchRegistryConstants.ATT_SINGLETON) != null;
310     }
311 
312     /**
313      * Restore the state of a perspective from a memento.
314      * 
315      * @param memento
316      *            the memento to restore from
317      * @return the <code>IStatus</code> of the operation
318      * @see org.eclipse.ui.IPersistableElement
319      */
320     public IStatus restoreState(IMemento memento) {
321         IMemento childMem = memento
322                 .getChild(IWorkbenchConstants.TAG_DESCRIPTOR);
323         if (childMem != null) {
324             id = childMem.getString(IWorkbenchConstants.TAG_ID);
325             originalId = childMem.getString(IWorkbenchConstants.TAG_DESCRIPTOR);
326             label = childMem.getString(IWorkbenchConstants.TAG_LABEL);
327             className = childMem.getString(IWorkbenchConstants.TAG_CLASS);
328             singleton = (childMem.getInteger(IWorkbenchConstants.TAG_SINGLETON) != null);
329 
330             // Find a descriptor in the registry.
331             IPerspectiveDescriptor descriptor = WorkbenchPlugin.getDefault()
332                     .getPerspectiveRegistry().findPerspectiveWithId(
333                             getOriginalId());
334 
335             if (descriptor != null) {
336                 // Copy the state from the registred descriptor.
337                 image = descriptor.getImageDescriptor();
338             }
339         }
340         return new Status(IStatus.OK, PlatformUI.PLUGIN_ID, 0, "", null); //$NON-NLS-1$
341     }
342 
343     /**
344      * Revert to the predefined extension template. Does nothing if this
345      * descriptor is user defined.
346      */
347     public void revertToPredefined() {
348         if (isPredefined()) {
349             deleteCustomDefinition();
350         }
351     }
352 
353     /**
354      * Save the state of a perspective to a memento.
355      * 
356      * @param memento
357      *            the memento to restore from
358      * @return the <code>IStatus</code> of the operation
359      * @see org.eclipse.ui.IPersistableElement
360      */
361     public IStatus saveState(IMemento memento) {
362         IMemento childMem = memento
363                 .createChild(IWorkbenchConstants.TAG_DESCRIPTOR);
364         childMem.putString(IWorkbenchConstants.TAG_ID, getId());
365         if (originalId != null) {
366             childMem.putString(IWorkbenchConstants.TAG_DESCRIPTOR, originalId);
367         }
368         childMem.putString(IWorkbenchConstants.TAG_LABEL, getLabel());
369         childMem.putString(IWorkbenchConstants.TAG_CLASS, getClassName());
370         if (singleton) {
371             childMem.putInteger(IWorkbenchConstants.TAG_SINGLETON, 1);
372         }
373         return new Status(IStatus.OK, PlatformUI.PLUGIN_ID, 0, "", null); //$NON-NLS-1$
374     }
375 
376     /**
377      * Return the configuration element used to create this perspective, if one
378      * was used.
379      * 
380      * @return the configuration element used to create this perspective
381      * @since 3.0
382      */
383     public IConfigurationElement getConfigElement() {
384         return configElement;
385     }
386 
387     /*
388      * (non-Javadoc)
389      * 
390      * @see org.eclipse.ui.activities.support.IPluginContribution#getLocalId()
391      */
392     public String   getLocalId() {
393         return getId();
394     }
395 
396     /*
397      * (non-Javadoc)
398      * 
399      * @see org.eclipse.ui.activities.support.IPluginContribution#getPluginId()
400      */
401     public String   getPluginId() {
402         return configElement == null ? pluginId : configElement.getNamespace();
403     }
404 
405     /**
406      * Returns the factory class name for this descriptor.
407      * 
408      * @return the factory class name for this descriptor
409      * @since 3.1
410      */
411     public String   getClassName() {
412         return configElement == null ? className : RegistryReader
413                 .getClassValue(configElement,
414                         IWorkbenchRegistryConstants.ATT_CLASS);
415     }
416 }
417
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags