1 /******************************************************************************* 2 * Copyright (c) 2000, 2015 IBM Corporation and others. 3 * 4 * This program and the accompanying materials 5 * are made available under the terms of the Eclipse Public License 2.0 6 * which accompanies this distribution, and is available at 7 * https://www.eclipse.org/legal/epl-2.0/ 8 * 9 * SPDX-License-Identifier: EPL-2.0 10 * 11 * Contributors: 12 * IBM Corporation - initial API and implementation 13 *******************************************************************************/ 14 package org.eclipse.ui; 15 16 import org.eclipse.core.runtime.IAdaptable; 17 import org.eclipse.swt.graphics.Image; 18 import org.eclipse.swt.widgets.Composite; 19 20 /** 21 * A workbench part is a visual component within a workbench page. There are two 22 * subtypes: view and editor, as defined by <code>IViewPart</code> and 23 * <code>IEditorPart</code>. 24 * <p> 25 * A view is typically used to navigate a hierarchy of information (like the 26 * workspace), open an editor, or display properties for the active editor. 27 * Modifications made in a view are saved immediately. 28 * </p> 29 * <p> 30 * An editor is typically used to edit or browse a document or input object. The 31 * input is identified using an <code>IEditorInput</code>. Modifications made in 32 * an editor part follow an open-save-close lifecycle model. 33 * </p> 34 * <p> 35 * This interface may be implemented directly. For convenience, a base 36 * implementation is defined in <code>WorkbenchPart</code>. 37 * </p> 38 * <p> 39 * The lifecycle of a workbench part is as follows: 40 * </p> 41 * <ul> 42 * <li>When a part extension is created: 43 * <ul> 44 * <li>instantiate the part</li> 45 * <li>create a part site</li> 46 * <li>call <code>part.init(site)</code></li> 47 * </ul> 48 * <li>When a part becomes visible in the workbench: 49 * <ul> 50 * <li>add part to presentation by calling 51 * <code>part.createPartControl(parent)</code> to create actual widgets</li> 52 * <li>fire <code>partOpened</code> event to all listeners</li> 53 * </ul> 54 * </li> 55 * <li>When a part is activated or gets focus: 56 * <ul> 57 * <li>call <code>part.setFocus()</code></li> 58 * <li>fire <code>partActivated</code> event to all listeners</li> 59 * </ul> 60 * </li> 61 * <li>When a part is closed: 62 * <ul> 63 * <li>if save is needed, do save; if it fails or is canceled return</li> 64 * <li>if part is active, deactivate part</li> 65 * <li>fire <code>partClosed</code> event to all listeners</li> 66 * <li>remove part from presentation; part controls are disposed as part of the 67 * SWT widget tree 68 * <li>call <code>part.dispose()</code></li> 69 * </ul> 70 * </li> 71 * </ul> 72 * <p> 73 * After <code>createPartControl</code> has been called, the implementor may 74 * safely reference the controls created. When the part is closed these controls 75 * will be disposed as part of an SWT composite. This occurs before the 76 * <code>IWorkbenchPart.dispose</code> method is called. If there is a need to 77 * free SWT resources the part should define a dispose listener for its own 78 * control and free those resources from the dispose listener. If the part 79 * invokes any method on the disposed SWT controls after this point an 80 * <code>SWTError</code> will be thrown. 81 * </p> 82 * <p> 83 * The last method called on <code>IWorkbenchPart</code> is 84 * <code>dispose</code>. This signals the end of the part lifecycle. 85 * </p> 86 * <p> 87 * An important point to note about this lifecycle is that following a call to 88 * init, createPartControl may never be called. Thus in the dispose method, 89 * implementors must not assume controls were created. 90 * </p> 91 * <p> 92 * Workbench parts implement the <code>IAdaptable</code> interface; extensions 93 * are managed by the platform's adapter manager. 94 * </p> 95 * 96 * @see IViewPart 97 * @see IEditorPart 98 */ 99 public interface IWorkbenchPart extends IAdaptable { 100 101 /** 102 * The property id for <code>getTitle</code>, <code>getTitleImage</code> and 103 * <code>getTitleToolTip</code>. 104 */ 105 int PROP_TITLE = IWorkbenchPartConstants.PROP_TITLE; 106 107 /** 108 * Adds a listener for changes to properties of this workbench part. Has no 109 * effect if an identical listener is already registered. 110 * <p> 111 * The property ids are defined in {@link IWorkbenchPartConstants}. 112 * </p> 113 * 114 * @param listener a property listener 115 */ addPropertyListener(IPropertyListener listener)116 void addPropertyListener(IPropertyListener listener); 117 118 /** 119 * Creates the SWT controls for this workbench part. 120 * <p> 121 * Clients should not call this method (the workbench calls this method when it 122 * needs to, which may be never). 123 * </p> 124 * <p> 125 * For implementors this is a multi-step process: 126 * </p> 127 * <ol> 128 * <li>Create one or more controls within the parent.</li> 129 * <li>Set the parent layout as needed.</li> 130 * <li>Register any global actions with the site's 131 * <code>IActionBars</code>.</li> 132 * <li>Register any context menus with the site.</li> 133 * <li>Register a selection provider with the site, to make it available to the 134 * workbench's <code>ISelectionService</code> (optional).</li> 135 * </ol> 136 * 137 * @param parent the parent control 138 */ createPartControl(Composite parent)139 void createPartControl(Composite parent); 140 141 /** 142 * Disposes of this workbench part. 143 * <p> 144 * This is the last method called on the <code>IWorkbenchPart</code>. At this 145 * point the part controls (if they were ever created) have been disposed as 146 * part of an SWT composite. There is no guarantee that createPartControl() has 147 * been called, so the part controls may never have been created. 148 * </p> 149 * <p> 150 * Within this method a part may release any resources, fonts, images, 151 * etc. held by this part. It is also very important to deregister all 152 * listeners from the workbench. 153 * </p> 154 * <p> 155 * Clients should not call this method (the workbench calls this method at 156 * appropriate times). 157 * </p> 158 */ dispose()159 void dispose(); 160 161 /** 162 * Returns the site for this workbench part. The site can be <code>null</code> 163 * while the workbench part is being initialized. After the initialization is 164 * complete, this value must be non-<code>null</code> for the remainder of the 165 * part's life cycle. 166 * 167 * @return The part site; this value may be <code>null</code> if the part has 168 * not yet been initialized 169 */ getSite()170 IWorkbenchPartSite getSite(); 171 172 /** 173 * Returns the title of this workbench part. If this value changes the part must 174 * fire a property listener event with <code>PROP_TITLE</code>. 175 * <p> 176 * The title is used to populate the title bar of this part's visual container. 177 * </p> 178 * 179 * @return the workbench part title (not <code>null</code>) 180 */ getTitle()181 String getTitle(); 182 183 /** 184 * Returns the title image of this workbench part. If this value changes the 185 * part must fire a property listener event with <code>PROP_TITLE</code>. 186 * <p> 187 * The title image is usually used to populate the title bar of this part's 188 * visual container. Since this image is managed by the part itself, callers 189 * must <b>not</b> dispose the returned image. 190 * </p> 191 * 192 * @return the title image 193 */ getTitleImage()194 Image getTitleImage(); 195 196 /** 197 * Returns the title tool tip text of this workbench part. An empty string 198 * result indicates no tool tip. If this value changes the part must fire a 199 * property listener event with <code>PROP_TITLE</code>. 200 * <p> 201 * The tool tip text is used to populate the title bar of this part's visual 202 * container. 203 * </p> 204 * 205 * @return the workbench part title tool tip (not <code>null</code>) 206 */ getTitleToolTip()207 String getTitleToolTip(); 208 209 /** 210 * Removes the given property listener from this workbench part. Has no effect 211 * if an identical listener is not registered. 212 * 213 * @param listener a property listener 214 */ removePropertyListener(IPropertyListener listener)215 void removePropertyListener(IPropertyListener listener); 216 217 /** 218 * Asks this part to take focus within the workbench. Parts must assign focus to 219 * one of the controls contained in the part's parent composite. 220 * <p> 221 * Clients should not call this method (the workbench calls this method at 222 * appropriate times). To have the workbench activate a part, use 223 * <code>IWorkbenchPage.activate(IWorkbenchPart) instead</code>. 224 * </p> 225 */ setFocus()226 void setFocus(); 227 } 228