001: /*******************************************************************************
002: * Copyright (c) 2000, 2005 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.ui;
011:
012: import org.eclipse.core.runtime.IAdaptable;
013: import org.eclipse.swt.graphics.Image;
014: import org.eclipse.swt.widgets.Composite;
015:
016: /**
017: * A workbench part is a visual component within a workbench page. There
018: * are two subtypes: view and editor, as defined by <code>IViewPart</code> and
019: * <code>IEditorPart</code>.
020: * <p>
021: * A view is typically used to navigate a hierarchy of information (like the
022: * workspace), open an editor, or display properties for the active editor.
023: * Modifications made in a view are saved immediately.
024: * </p><p>
025: * An editor is typically used to edit or browse a document or input object.
026: * The input is identified using an <code>IEditorInput</code>. Modifications made
027: * in an editor part follow an open-save-close lifecycle model.
028: * </p><p>
029: * This interface may be implemented directly. For convenience, a base
030: * implementation is defined in <code>WorkbenchPart</code>.
031: * </p><p>
032: * The lifecycle of a workbench part is as follows:
033: * <ul>
034: * <li>When a part extension is created:
035: * <ul>
036: * <li>instantiate the part</li>
037: * <li>create a part site</li>
038: * <li>call <code>part.init(site)</code></li>
039: * </ul>
040: * <li>When a part becomes visible in the workbench:
041: * <ul>
042: * <li>add part to presentation by calling
043: * <code>part.createControl(parent)</code> to create actual widgets</li>
044: * <li>fire <code>partOpened</code> event to all listeners</li>
045: * </ul>
046: * </li>
047: * <li>When a part is activated or gets focus:
048: * <ul>
049: * <li>call <code>part.setFocus()</code></li>
050: * <li>fire <code>partActivated</code> event to all listeners</li>
051: * </ul>
052: * </li>
053: * <li>When a part is closed:
054: * <ul>
055: * <li>if save is needed, do save; if it fails or is canceled return</li>
056: * <li>if part is active, deactivate part</li>
057: * <li>fire <code>partClosed</code> event to all listeners</li>
058: * <li>remove part from presentation; part controls are disposed as part
059: * of the SWT widget tree
060: * <li>call <code>part.dispose()</code></li>
061: * </ul>
062: * </li>
063: * </ul>
064: * </p>
065: * <p>
066: * After <code>createPartControl</code> has been called, the implementor may
067: * safely reference the controls created. When the part is closed
068: * these controls will be disposed as part of an SWT composite. This
069: * occurs before the <code>IWorkbenchPart.dispose</code> method is called.
070: * If there is a need to free SWT resources the part should define a dispose
071: * listener for its own control and free those resources from the dispose
072: * listener. If the part invokes any method on the disposed SWT controls
073: * after this point an <code>SWTError</code> will be thrown.
074: * </p>
075: * <p>
076: * The last method called on <code>IWorkbenchPart</code> is <code>dispose</code>.
077: * This signals the end of the part lifecycle.
078: * </p>
079: * <p>
080: * An important point to note about this lifecycle is that following
081: * a call to init, createControl may never be called. Thus in the dispose
082: * method, implementors must not assume controls were created.
083: * </p>
084: * <p>
085: * Workbench parts implement the <code>IAdaptable</code> interface; extensions
086: * are managed by the platform's adapter manager.
087: * </p>
088: *
089: * @see IViewPart
090: * @see IEditorPart
091: */
092: public interface IWorkbenchPart extends IAdaptable {
093:
094: /**
095: * The property id for <code>getTitle</code>, <code>getTitleImage</code>
096: * and <code>getTitleToolTip</code>.
097: */
098: public static final int PROP_TITLE = IWorkbenchPartConstants.PROP_TITLE;
099:
100: /**
101: * Adds a listener for changes to properties of this workbench part.
102: * Has no effect if an identical listener is already registered.
103: * <p>
104: * The property ids are defined in {@link IWorkbenchPartConstants}.
105: * </p>
106: *
107: * @param listener a property listener
108: */
109: public void addPropertyListener(IPropertyListener listener);
110:
111: /**
112: * Creates the SWT controls for this workbench part.
113: * <p>
114: * Clients should not call this method (the workbench calls this method when
115: * it needs to, which may be never).
116: * </p>
117: * <p>
118: * For implementors this is a multi-step process:
119: * <ol>
120: * <li>Create one or more controls within the parent.</li>
121: * <li>Set the parent layout as needed.</li>
122: * <li>Register any global actions with the site's <code>IActionBars</code>.</li>
123: * <li>Register any context menus with the site.</li>
124: * <li>Register a selection provider with the site, to make it available to
125: * the workbench's <code>ISelectionService</code> (optional). </li>
126: * </ol>
127: * </p>
128: *
129: * @param parent the parent control
130: */
131: public void createPartControl(Composite parent);
132:
133: /**
134: * Disposes of this workbench part.
135: * <p>
136: * This is the last method called on the <code>IWorkbenchPart</code>. At this
137: * point the part controls (if they were ever created) have been disposed as part
138: * of an SWT composite. There is no guarantee that createPartControl() has been
139: * called, so the part controls may never have been created.
140: * </p>
141: * <p>
142: * Within this method a part may release any resources, fonts, images, etc.
143: * held by this part. It is also very important to deregister all listeners
144: * from the workbench.
145: * </p>
146: * <p>
147: * Clients should not call this method (the workbench calls this method at
148: * appropriate times).
149: * </p>
150: */
151: public void dispose();
152:
153: /**
154: * Returns the site for this workbench part. The site can be
155: * <code>null</code> while the workbench part is being initialized. After
156: * the initialization is complete, this value must be non-<code>null</code>
157: * for the remainder of the part's life cycle.
158: *
159: * @return The part site; this value may be <code>null</code> if the part
160: * has not yet been initialized
161: */
162: public IWorkbenchPartSite getSite();
163:
164: /**
165: * Returns the title of this workbench part. If this value changes
166: * the part must fire a property listener event with
167: * <code>PROP_TITLE</code>.
168: * <p>
169: * The title is used to populate the title bar of this part's visual
170: * container.
171: * </p>
172: *
173: * @return the workbench part title (not <code>null</code>)
174: */
175: public String getTitle();
176:
177: /**
178: * Returns the title image of this workbench part. If this value changes
179: * the part must fire a property listener event with
180: * <code>PROP_TITLE</code>.
181: * <p>
182: * The title image is usually used to populate the title bar of this part's
183: * visual container. Since this image is managed by the part itself, callers
184: * must <b>not</b> dispose the returned image.
185: * </p>
186: *
187: * @return the title image
188: */
189: public Image getTitleImage();
190:
191: /**
192: * Returns the title tool tip text of this workbench part.
193: * An empty string result indicates no tool tip.
194: * If this value changes the part must fire a property listener event with
195: * <code>PROP_TITLE</code>.
196: * <p>
197: * The tool tip text is used to populate the title bar of this part's
198: * visual container.
199: * </p>
200: *
201: * @return the workbench part title tool tip (not <code>null</code>)
202: */
203: public String getTitleToolTip();
204:
205: /**
206: * Removes the given property listener from this workbench part.
207: * Has no affect if an identical listener is not registered.
208: *
209: * @param listener a property listener
210: */
211: public void removePropertyListener(IPropertyListener listener);
212:
213: /**
214: * Asks this part to take focus within the workbench.
215: * <p>
216: * Clients should not call this method (the workbench calls this method at
217: * appropriate times). To have the workbench activate a part, use
218: * <code>IWorkbenchPage.activate(IWorkbenchPart) instead</code>.
219: * </p>
220: */
221: public void setFocus();
222: }
|