KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > ui > IWorkbenchPart


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