WorkbenchPart


1   /*******************************************************************************
2    * Copyright (c) 2000, 2007 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   *******************************************************************************/
11  package org.eclipse.ui.part;
12  
13  import java.util.Collections  ;
14  import java.util.HashMap  ;
15  import java.util.Map  ;
16  
17  import org.eclipse.core.commands.common.EventManager;
18  import org.eclipse.core.runtime.Assert;
19  import org.eclipse.core.runtime.IConfigurationElement;
20  import org.eclipse.core.runtime.IExecutableExtension;
21  import org.eclipse.core.runtime.ListenerList;
22  import org.eclipse.core.runtime.Platform;
23  import org.eclipse.jface.resource.ImageDescriptor;
24  import org.eclipse.jface.resource.JFaceResources;
25  import org.eclipse.jface.util.IPropertyChangeListener;
26  import org.eclipse.jface.util.PropertyChangeEvent;
27  import org.eclipse.jface.window.Window;
28  import org.eclipse.swt.graphics.Image;
29  import org.eclipse.swt.widgets.Composite;
30  import org.eclipse.ui.IPropertyListener;
31  import org.eclipse.ui.ISharedImages;
32  import org.eclipse.ui.IWorkbenchPart;
33  import org.eclipse.ui.IWorkbenchPart3;
34  import org.eclipse.ui.IWorkbenchPartConstants;
35  import org.eclipse.ui.IWorkbenchPartSite;
36  import org.eclipse.ui.PlatformUI;
37  import org.eclipse.ui.internal.WorkbenchMessages;
38  import org.eclipse.ui.internal.WorkbenchPlugin;
39  import org.eclipse.ui.internal.util.Util;
40  import org.eclipse.ui.plugin.AbstractUIPlugin;
41  
42  import com.ibm.icu.text.MessageFormat;
43  
44  /**
45   * Abstract base implementation of all workbench parts.
46   * <p>
47   * This class is not intended to be subclassed by clients outside this
48   * package; clients should instead subclass <code>ViewPart</code> or
49   * <code>EditorPart</code>.
50   * </p>
51   * 
52   * @see org.eclipse.ui.part.ViewPart
53   * @see org.eclipse.ui.part.EditorPart
54   */
55  public abstract class WorkbenchPart extends EventManager implements
56          IWorkbenchPart3, IExecutableExtension, IWorkbenchPartOrientation {
57      private String   title = ""; //$NON-NLS-1$
58  
59      private ImageDescriptor imageDescriptor;
60  
61      private Image titleImage;
62  
63      private String   toolTip = ""; //$NON-NLS-1$
64  
65      private IConfigurationElement configElement;
66  
67      private IWorkbenchPartSite partSite;
68  
69      private String   partName = ""; //$NON-NLS-1$
70  
71      private String   contentDescription = ""; //$NON-NLS-1$
72      
73      private ListenerList partChangeListeners = new ListenerList();
74  
75      /**
76       * Creates a new workbench part.
77       */
78      protected WorkbenchPart() {
79          super();
80      }
81  
82      /* (non-Javadoc)
83       * Method declared on IWorkbenchPart.
84       */
85      public void addPropertyListener(IPropertyListener l) {
86          addListenerObject(l);
87      }
88  
89      /* (non-Javadoc)
90       * Creates the SWT controls for this workbench part.
91       * <p>
92       * Subclasses must implement this method.  For a detailed description of the
93       * requirements see <code>IWorkbenchPart</code>
94       * </p>
95       *
96       * @param parent the parent control
97       * @see IWorkbenchPart
98       */
99      public abstract void createPartControl(Composite parent);
100 
101     /**
102      * The <code>WorkbenchPart</code> implementation of this 
103      * <code>IWorkbenchPart</code> method disposes the title image
104      * loaded by <code>setInitializationData</code>. Subclasses may extend.
105      */
106     public void dispose() {
107         if (imageDescriptor != null) {
108             JFaceResources.getResources().destroyImage(imageDescriptor);
109         }
110 
111         // Clear out the property change listeners as we
112         // should not be notifying anyone after the part
113         // has been disposed.
114         clearListeners();
115         partChangeListeners.clear();
116     }
117 
118     /**
119      * Fires a property changed event.
120      *
121      * @param propertyId the id of the property that changed
122      */
123     protected void firePropertyChange(final int propertyId) {
124         Object  [] array = getListeners();
125         for (int nX = 0; nX < array.length; nX++) {
126             final IPropertyListener l = (IPropertyListener) array[nX];
127             try {
128                 l.propertyChanged(WorkbenchPart.this, propertyId);
129             } catch (RuntimeException   e) {
130                 WorkbenchPlugin.log(e);
131             }
132         }
133     }
134 
135     /**
136      * {@inheritDoc}
137      * 
138      * Subclasses may override this method (however, if they do so, they
139      * should invoke the method on their superclass to ensure that the
140      * Platform's adapter manager is consulted).
141      */
142     public Object   getAdapter(Class   adapter) {
143 
144         /**
145          * This implementation of the method declared by <code>IAdaptable</code>
146          * passes the request along to the platform's adapter manager; roughly
147          * <code>Platform.getAdapterManager().getAdapter(this, adapter)</code>.
148          */
149 
150         return Platform.getAdapterManager().getAdapter(this, adapter);
151     }
152 
153     /**
154      * Returns the configuration element for this part. The configuration element
155      * comes from the plug-in registry entry for the extension defining this part.
156      *
157      * @return the configuration element for this part
158      */
159     protected IConfigurationElement getConfigurationElement() {
160         return configElement;
161     }
162 
163     /**
164      * Returns the default title image.
165      *
166      * @return the default image
167      */
168     protected Image getDefaultImage() {
169         return PlatformUI.getWorkbench().getSharedImages().getImage(
170                 ISharedImages.IMG_DEF_VIEW);
171     }
172 
173     /* (non-Javadoc)
174      * Method declared on IWorkbenchPart.
175      */
176     public IWorkbenchPartSite getSite() {
177         return partSite;
178     }
179 
180     /**
181      * {@inheritDoc}
182      * <p>
183      * It is considered bad practise to overload or extend this method.
184      * Parts should set their title by calling setPartName and/or setContentDescription.
185      * </p>
186      */
187     public String   getTitle() {
188         return title;
189     }
190 
191     /* (non-Javadoc)
192      * Method declared on IWorkbenchPart.
193      */
194     public Image getTitleImage() {
195         if (titleImage != null) {
196             return titleImage;
197         }
198         return getDefaultImage();
199     }
200 
201     /* (non-Javadoc)
202      * Gets the title tool tip text of this part.
203      *
204      * @return the tool tip text
205      */
206     public String   getTitleToolTip() {
207         return toolTip;
208     }
209 
210     /* (non-Javadoc)
211      * Method declared on IWorkbenchPart.
212      */
213     public void removePropertyListener(IPropertyListener l) {
214         removeListenerObject(l);
215     }
216 
217     /* (non-Javadoc)
218      * Asks this part to take focus within the workbench.
219      * <p>
220      * Subclasses must implement this method.  For a detailed description of the
221      * requirements see <code>IWorkbenchPart</code>
222      * </p>
223      *
224      * @see IWorkbenchPart
225      */
226     public abstract void setFocus();
227 
228     /**
229      * {@inheritDoc}
230      * The <code>WorkbenchPart</code> implementation of this
231      * <code>IExecutableExtension</code> records the configuration element in
232      * and internal state variable (accessible via <code>getConfigElement</code>).
233      * It also loads the title image, if one is specified in the configuration element.
234      * Subclasses may extend.
235      * 
236      * Should not be called by clients. It is called by the core plugin when creating
237      * this executable extension.
238      */
239     public void setInitializationData(IConfigurationElement cfig,
240             String   propertyName, Object   data) {
241 
242         // Save config element.
243         configElement = cfig;
244 
245         // Part name and title.  
246         partName = Util.safeString(cfig.getAttribute("name"));//$NON-NLS-1$;
247         title = partName;
248 
249         // Icon.
250         String   strIcon = cfig.getAttribute("icon");//$NON-NLS-1$
251         if (strIcon == null) {
252             return;
253         }
254 
255         imageDescriptor = AbstractUIPlugin.imageDescriptorFromPlugin(
256                 configElement.getNamespace(), strIcon);
257 
258         if (imageDescriptor == null) {
259             return;
260         }
261 
262         titleImage = JFaceResources.getResources().createImageWithDefault(imageDescriptor);
263     }
264 
265     /**
266      * Sets the part site.
267      * <p>
268      * Subclasses must invoke this method from <code>IEditorPart.init</code>
269      * and <code>IViewPart.init</code>.
270      *
271      * @param site the workbench part site
272      */
273     protected void setSite(IWorkbenchPartSite site) {
274         checkSite(site);
275         this.partSite = site;
276     }
277 
278     /**
279      * Checks that the given site is valid for this type of part.
280      * The default implementation does nothing.
281      * 
282      * @param site the site to check
283      * @since 3.1
284      */
285     protected void checkSite(IWorkbenchPartSite site) {
286         // do nothing
287     }
288 
289     /**
290      * Sets or clears the title of this part. Clients should call this method instead 
291      * of overriding getTitle.
292      * <p>
293      * This may change a title that was previously set using setPartName or setContentDescription.
294      * </p>
295      *
296      * @deprecated new code should use setPartName and setContentDescription
297      *
298      * @param title the title, or <code>null</code> to clear
299      */
300     protected void setTitle(String   title) {
301         title = Util.safeString(title);
302 
303         //Do not send changes if they are the same
304         if (Util.equals(this.title, title)) {
305             return;
306         }
307         this.title = title;
308         firePropertyChange(IWorkbenchPart.PROP_TITLE);
309     }
310 
311     /**
312      * Sets or clears the title image of this part.
313      *
314      * @param titleImage the title image, or <code>null</code> to clear
315      */
316     protected void setTitleImage(Image titleImage) {
317         Assert.isTrue(titleImage == null || !titleImage.isDisposed());
318         //Do not send changes if they are the same
319         if (this.titleImage == titleImage) {
320             return;
321         }
322         this.titleImage = titleImage;
323         firePropertyChange(IWorkbenchPart.PROP_TITLE);
324         if (imageDescriptor != null) {
325             JFaceResources.getResources().destroyImage(imageDescriptor);
326             imageDescriptor = null;
327         }
328     }
329 
330     /**
331      * Sets or clears the title tool tip text of this part. Clients should
332      * call this method instead of overriding <code>getTitleToolTip</code>
333      *
334      * @param toolTip the new tool tip text, or <code>null</code> to clear
335      */
336     protected void setTitleToolTip(String   toolTip) {
337         toolTip = Util.safeString(toolTip);
338         //Do not send changes if they are the same
339         if (Util.equals(this.toolTip, toolTip)) {
340             return;
341         }
342         this.toolTip = toolTip;
343         firePropertyChange(IWorkbenchPart.PROP_TITLE);
344     }
345 
346     /**
347      * Show that this part is busy due to a Job running that it 
348      * is listening to.
349      * @param busy boolean to indicate that the busy state has started
350      *      or ended.
351      * @see org.eclipse.ui.progress.IWorkbenchSiteProgressService#showBusyForFamily(Object)
352      * @since 3.0
353      */
354     public void showBusy(boolean busy) {
355         //By default do nothing
356     }
357 
358     /**
359      * {@inheritDoc}
360      * <p>
361      * It is considered bad practise to overload or extend this method.
362      * Parts should call setPartName to change their part name. 
363      * </p>
364      */
365     public String   getPartName() {
366         return partName;
367     }
368 
369     /**
370      * Sets the name of this part. The name will be shown in the tab area for 
371      * the part. Clients should call this method instead of overriding getPartName.
372      * Setting this to the empty string will cause a default part name to be used.
373      * 
374      * <p>
375      * setPartName and setContentDescription are intended to replace setTitle.
376      * This may change a value that was previously set using setTitle.  
377      * </p>
378      *
379      * @param partName the part name, as it should be displayed in tabs.
380      * 
381      * @since 3.0
382      */
383     protected void setPartName(String   partName) {
384 
385         internalSetPartName(partName);
386 
387         setDefaultTitle();
388     }
389 
390     void setDefaultTitle() {
391         String   description = getContentDescription();
392         String   name = getPartName();
393         String   newTitle = name;
394 
395         if (!Util.equals(description, "")) { //$NON-NLS-1$
396             newTitle = MessageFormat
397                     .format(
398                             WorkbenchMessages.WorkbenchPart_AutoTitleFormat, new String  [] { name, description });
399         }
400 
401         setTitle(newTitle);
402     }
403 
404     /**
405      * {@inheritDoc}
406      * <p>
407      * It is considered bad practise to overload or extend this method.
408      * Parts should call setContentDescription to change their content description. 
409      * </p>
410      */
411     public String   getContentDescription() {
412         return contentDescription;
413     }
414 
415     /**
416      * Sets the content description for this part. The content description is typically
417      * a short string describing the current contents of the part. Setting this to the
418      * empty string will cause a default content description to be used. Clients should
419      * call this method instead of overriding getContentDescription(). For views, the
420      * content description is shown (by default) in a line near the top of the view. For
421      * editors, the content description is shown beside the part name when showing a
422      * list of editors. If the editor is open on a file, this typically contains the path 
423      * to the input file, without the filename or trailing slash.
424      *
425      * <p>
426      * This may overwrite a value that was previously set in setTitle
427      * </p>
428      * 
429      * @param description the content description
430      * 
431      * @since 3.0
432      */
433     protected void setContentDescription(String   description) {
434         internalSetContentDescription(description);
435 
436         setDefaultTitle();
437     }
438 
439     void internalSetContentDescription(String   description) {
440         Assert.isNotNull(description);
441 
442         //Do not send changes if they are the same
443         if (Util.equals(contentDescription, description)) {
444             return;
445         }
446         this.contentDescription = description;
447 
448         firePropertyChange(IWorkbenchPartConstants.PROP_CONTENT_DESCRIPTION);
449     }
450 
451     void internalSetPartName(String   partName) {
452         partName = Util.safeString(partName);
453 
454         Assert.isNotNull(partName);
455 
456         //Do not send changes if they are the same
457         if (Util.equals(this.partName, partName)) {
458             return;
459         }
460         this.partName = partName;
461 
462         firePropertyChange(IWorkbenchPartConstants.PROP_PART_NAME);
463 
464     }
465     
466 
467     /* (non-Javadoc)
468      * @see org.eclipse.ui.part.IWorkbenchPartOrientation#getOrientation()
469      */
470     public int getOrientation(){
471         //By default use the orientation in Window
472         return Window.getDefaultOrientation();
473     }
474 
475     /* (non-Javadoc)
476      * @see org.eclipse.ui.IWorkbenchPart3#addPartPropertyListener(org.eclipse.jface.util.IPropertyChangeListener)
477      */
478     public void addPartPropertyListener(IPropertyChangeListener listener) {
479         partChangeListeners.add(listener);
480     }
481     
482     /* (non-Javadoc)
483      * @see org.eclipse.ui.IWorkbenchPart3#removePartPropertyListener(org.eclipse.jface.util.IPropertyChangeListener)
484      */
485     public void removePartPropertyListener(IPropertyChangeListener listener) {
486         partChangeListeners.remove(listener);
487     }
488     
489     /**
490      * @since 3.3
491      */
492     protected void firePartPropertyChanged(String   key, String   oldValue, String   newValue) {
493         final PropertyChangeEvent event = new PropertyChangeEvent(this, key, oldValue, newValue);
494         Object  [] l = partChangeListeners.getListeners();
495         for (int i = 0; i < l.length; i++) {
496             try {
497                 ((IPropertyChangeListener)l[i]).propertyChange(event);
498             } catch (RuntimeException   e) {
499                 WorkbenchPlugin.log(e);
500             }
501         }
502     }
503     
504     private Map   partProperties = new HashMap  ();
505     
506     /* (non-Javadoc)
507      * @see org.eclipse.ui.IWorkbenchPart3#setPartProperty(java.lang.String, java.lang.String)
508      */
509     public void setPartProperty(String   key, String   value) {
510         String   oldValue = (String  ) partProperties.get(key);
511         if (value==null) {
512             partProperties.remove(key);
513         } else {
514             partProperties.put(key, value);
515         }
516         firePartPropertyChanged(key, oldValue, value);
517     }
518     
519     /* (non-Javadoc)
520      * @see org.eclipse.ui.IWorkbenchPart3#getPartProperty(java.lang.String)
521      */
522     public String   getPartProperty(String   key) {
523         return (String  )partProperties.get(key);
524     }
525     
526     /* (non-Javadoc)
527      * @see org.eclipse.ui.IWorkbenchPart3#getPartProperties()
528      */
529     public Map   getPartProperties() {
530         return Collections.unmodifiableMap(partProperties);
531     }
532 }
533
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags