| /******************************************************************************* |
| * Copyright (c) 2000, 2015 IBM Corporation and others. |
| * |
| * This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License 2.0 |
| * which accompanies this distribution, and is available at |
| * https://www.eclipse.org/legal/epl-2.0/ |
| * |
| * SPDX-License-Identifier: EPL-2.0 |
| * |
| * Contributors: |
| * IBM Corporation - initial API and implementation |
| *******************************************************************************/ |
| package org.eclipse.ui; |
| |
| import org.eclipse.core.runtime.IAdaptable; |
| import org.eclipse.swt.graphics.Image; |
| import org.eclipse.swt.widgets.Composite; |
| |
| /** |
| * A workbench part is a visual component within a workbench page. There are two |
| * subtypes: view and editor, as defined by <code>IViewPart</code> and |
| * <code>IEditorPart</code>. |
| * <p> |
| * A view is typically used to navigate a hierarchy of information (like the |
| * workspace), open an editor, or display properties for the active editor. |
| * Modifications made in a view are saved immediately. |
| * </p> |
| * <p> |
| * An editor is typically used to edit or browse a document or input object. The |
| * input is identified using an <code>IEditorInput</code>. Modifications made in |
| * an editor part follow an open-save-close lifecycle model. |
| * </p> |
| * <p> |
| * This interface may be implemented directly. For convenience, a base |
| * implementation is defined in <code>WorkbenchPart</code>. |
| * </p> |
| * <p> |
| * The lifecycle of a workbench part is as follows: |
| * </p> |
| * <ul> |
| * <li>When a part extension is created: |
| * <ul> |
| * <li>instantiate the part</li> |
| * <li>create a part site</li> |
| * <li>call <code>part.init(site)</code></li> |
| * </ul> |
| * <li>When a part becomes visible in the workbench: |
| * <ul> |
| * <li>add part to presentation by calling |
| * <code>part.createPartControl(parent)</code> to create actual widgets</li> |
| * <li>fire <code>partOpened</code> event to all listeners</li> |
| * </ul> |
| * </li> |
| * <li>When a part is activated or gets focus: |
| * <ul> |
| * <li>call <code>part.setFocus()</code></li> |
| * <li>fire <code>partActivated</code> event to all listeners</li> |
| * </ul> |
| * </li> |
| * <li>When a part is closed: |
| * <ul> |
| * <li>if save is needed, do save; if it fails or is canceled return</li> |
| * <li>if part is active, deactivate part</li> |
| * <li>fire <code>partClosed</code> event to all listeners</li> |
| * <li>remove part from presentation; part controls are disposed as part of the |
| * SWT widget tree |
| * <li>call <code>part.dispose()</code></li> |
| * </ul> |
| * </li> |
| * </ul> |
| * <p> |
| * After <code>createPartControl</code> has been called, the implementor may |
| * safely reference the controls created. When the part is closed these controls |
| * will be disposed as part of an SWT composite. This occurs before the |
| * <code>IWorkbenchPart.dispose</code> method is called. If there is a need to |
| * free SWT resources the part should define a dispose listener for its own |
| * control and free those resources from the dispose listener. If the part |
| * invokes any method on the disposed SWT controls after this point an |
| * <code>SWTError</code> will be thrown. |
| * </p> |
| * <p> |
| * The last method called on <code>IWorkbenchPart</code> is |
| * <code>dispose</code>. This signals the end of the part lifecycle. |
| * </p> |
| * <p> |
| * An important point to note about this lifecycle is that following a call to |
| * init, createPartControl may never be called. Thus in the dispose method, |
| * implementors must not assume controls were created. |
| * </p> |
| * <p> |
| * Workbench parts implement the <code>IAdaptable</code> interface; extensions |
| * are managed by the platform's adapter manager. |
| * </p> |
| * |
| * @see IViewPart |
| * @see IEditorPart |
| */ |
| public interface IWorkbenchPart extends IAdaptable { |
| |
| /** |
| * The property id for <code>getTitle</code>, <code>getTitleImage</code> and |
| * <code>getTitleToolTip</code>. |
| */ |
| int PROP_TITLE = IWorkbenchPartConstants.PROP_TITLE; |
| |
| /** |
| * Adds a listener for changes to properties of this workbench part. Has no |
| * effect if an identical listener is already registered. |
| * <p> |
| * The property ids are defined in {@link IWorkbenchPartConstants}. |
| * </p> |
| * |
| * @param listener a property listener |
| */ |
| void addPropertyListener(IPropertyListener listener); |
| |
| /** |
| * Creates the SWT controls for this workbench part. |
| * <p> |
| * Clients should not call this method (the workbench calls this method when it |
| * needs to, which may be never). |
| * </p> |
| * <p> |
| * For implementors this is a multi-step process: |
| * </p> |
| * <ol> |
| * <li>Create one or more controls within the parent.</li> |
| * <li>Set the parent layout as needed.</li> |
| * <li>Register any global actions with the site's |
| * <code>IActionBars</code>.</li> |
| * <li>Register any context menus with the site.</li> |
| * <li>Register a selection provider with the site, to make it available to the |
| * workbench's <code>ISelectionService</code> (optional).</li> |
| * </ol> |
| * |
| * @param parent the parent control |
| */ |
| void createPartControl(Composite parent); |
| |
| /** |
| * Disposes of this workbench part. |
| * <p> |
| * This is the last method called on the <code>IWorkbenchPart</code>. At this |
| * point the part controls (if they were ever created) have been disposed as |
| * part of an SWT composite. There is no guarantee that createPartControl() has |
| * been called, so the part controls may never have been created. |
| * </p> |
| * <p> |
| * Within this method a part may release any resources, fonts, images, |
| * etc. held by this part. It is also very important to deregister all |
| * listeners from the workbench. |
| * </p> |
| * <p> |
| * Clients should not call this method (the workbench calls this method at |
| * appropriate times). |
| * </p> |
| */ |
| void dispose(); |
| |
| /** |
| * Returns the site for this workbench part. The site can be <code>null</code> |
| * while the workbench part is being initialized. After the initialization is |
| * complete, this value must be non-<code>null</code> for the remainder of the |
| * part's life cycle. |
| * |
| * @return The part site; this value may be <code>null</code> if the part has |
| * not yet been initialized |
| */ |
| IWorkbenchPartSite getSite(); |
| |
| /** |
| * Returns the title of this workbench part. If this value changes the part must |
| * fire a property listener event with <code>PROP_TITLE</code>. |
| * <p> |
| * The title is used to populate the title bar of this part's visual container. |
| * </p> |
| * |
| * @return the workbench part title (not <code>null</code>) |
| */ |
| String getTitle(); |
| |
| /** |
| * Returns the title image of this workbench part. If this value changes the |
| * part must fire a property listener event with <code>PROP_TITLE</code>. |
| * <p> |
| * The title image is usually used to populate the title bar of this part's |
| * visual container. Since this image is managed by the part itself, callers |
| * must <b>not</b> dispose the returned image. |
| * </p> |
| * |
| * @return the title image |
| */ |
| Image getTitleImage(); |
| |
| /** |
| * Returns the title tool tip text of this workbench part. An empty string |
| * result indicates no tool tip. If this value changes the part must fire a |
| * property listener event with <code>PROP_TITLE</code>. |
| * <p> |
| * The tool tip text is used to populate the title bar of this part's visual |
| * container. |
| * </p> |
| * |
| * @return the workbench part title tool tip (not <code>null</code>) |
| */ |
| String getTitleToolTip(); |
| |
| /** |
| * Removes the given property listener from this workbench part. Has no effect |
| * if an identical listener is not registered. |
| * |
| * @param listener a property listener |
| */ |
| void removePropertyListener(IPropertyListener listener); |
| |
| /** |
| * Asks this part to take focus within the workbench. Parts must assign focus to |
| * one of the controls contained in the part's parent composite. |
| * <p> |
| * Clients should not call this method (the workbench calls this method at |
| * appropriate times). To have the workbench activate a part, use |
| * <code>IWorkbenchPage.activate(IWorkbenchPart) instead</code>. |
| * </p> |
| */ |
| void setFocus(); |
| } |