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