platform-ui-home/workbench_design/Inside the workbench.html

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.6 - (view) (download) (as text)

1 : sxenos 1.1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 :     <html>
3 :     <head>
4 : sxenos 1.4 <meta http-equiv="Content-Type"
5 :     content="text/html; charset=windows-1252">
6 : sxenos 1.1 <title>Inside the Workbench: A guide to the workbench internals</title>
7 : sxenos 1.4 <link rel="stylesheet" href="default_style.css">
8 : sxenos 1.1 </head>
9 : sxenos 1.4 <body link="#0000ff" vlink="#800080">
10 :     <div align="right">&nbsp; <font face="Times New Roman, Times, serif"
11 : sxenos 1.5 size="2">Copyright © 2005 International Business Machines Corp.</font>
12 : sxenos 1.4 <table border="0" cellpadding="2" cellspacing="0" width="100%">
13 : sxenos 1.1 <tbody>
14 :     <tr>
15 :     <td colspan="2" align="left" bgcolor="#0080c0" valign="top"><b><font
16 : sxenos 1.4 face="Arial,Helvetica"><font color="#ffffff">&nbsp;Eclipse Corner
17 :     Article</font></font></b></td>
18 : sxenos 1.1 </tr>
19 :     </tbody>
20 :     </table>
21 :     </div>
22 : sxenos 1.4 <div align="left">
23 :     <h1><a class="mozTocH1" name="mozTocId282580"></a><img
24 :     src="images/Idea.jpg" align="middle" height="86" width="120"></h1>
25 :     </div>
26 :     <p>&nbsp;</p>
27 :     <h1 align="center"><a class="mozTocH1" name="mozTocId119947"></a>Inside
28 :     the
29 : sxenos 1.1 Workbench<br>
30 :     A guide to the workbench internals<br>
31 : sxenos 1.4 </h1>
32 : sxenos 1.5 <blockquote> <b>Summary</b> <br>
33 : sxenos 1.6 This article describes how the Eclipse 3.1 workbench works, in
34 :     particular the infrastructure for views and editors. The goal is to
35 :     teach you about important classes in the workbench, and how they
36 :     interact. A familiarity with the basic workbench APIs for views,
37 :     editors, action sets, and so forth is assumed.
38 : sxenos 1.4 <p><b>Stefan Xenos, IBM</b> <br>
39 : sxenos 1.6 <font size="-1">January 6, 2006</font> </p>
40 : sxenos 1.4 </blockquote>
41 : sxenos 1.1 <br>
42 :     <hr style="width: 100%; height: 2px;">
43 : sxenos 1.4 <h1><a class="mozTocH1" name="mozTocId744856"></a>Table of Contents</h1>
44 : sxenos 1.1 <ul id="mozToc">
45 : sxenos 1.4 <!--mozToc h2 1 h3 2 h4 3 h5 4 h6 5--><li><a href="#mozTocId917303">1.0
46 : sxenos 1.6 Introduction </a></li>
47 :     <li><a href="#mozTocId270357">2.0 Inside a part </a>
48 : sxenos 1.1 <ul>
49 : sxenos 1.6 <li><a href="#mozTocId713423">2.1 Part Lifecycle </a></li>
50 : sxenos 1.4 <li><a href="#mozTocId789670">2.2 Part Construction</a></li>
51 : sxenos 1.1 </ul>
52 :     </li>
53 : sxenos 1.6 <li><a href="#mozTocId409413">3.0 Workbench Layout </a>
54 : sxenos 1.1 <ul>
55 : sxenos 1.4 <li><a href="#mozTocId95893">3.1 An example layout</a></li>
56 :     <li><a href="#mozTocId114962">3.2 Zoom / Unzoom
57 : sxenos 1.6 protocol </a></li>
58 :     <li><a href="#mozTocId977378">3.3 Layout protocol </a></li>
59 : sxenos 1.4 <li><a href="#mozTocId162591">3.4 PartStack:
60 : sxenos 1.6 Communicating with the Presentation API </a></li>
61 : sxenos 1.4 <li><a href="#mozTocId479574">3.5
62 :     PartSashContainer: The main workbench layout </a></li>
63 :     <li><a href="#mozTocId887241">3.6 Drag / Drop</a></li>
64 : sxenos 1.1 </ul>
65 :     </li>
66 : sxenos 1.5 <li><a href="#mozTocId443855">4.0 Action Bars</a>
67 : sxenos 1.1 <ul>
68 : sxenos 1.6 <li><a href="#mozTocId652269">4.1 Editor Action Bars </a></li>
69 :     <li><a href="#mozTocId340925">4.2 Action Sets </a></li>
70 : sxenos 1.5 <li><a href="#mozTocId277128">4.3 View Actions</a></li>
71 : sxenos 1.1 </ul>
72 :     </li>
73 : sxenos 1.5 <li><a href="#mozTocId642161">5.0 General
74 : sxenos 1.4 Conventions</a>
75 : sxenos 1.1 <ul>
76 : sxenos 1.5 <li><a href="#mozTocId892615">5.1 Objects must not
77 : sxenos 1.4 be returned through API until they are fully initialized</a></li>
78 : sxenos 1.5 <li><a href="#mozTocId308622">5.2 No method may
79 : sxenos 1.4 open a modal dialog unless its JavaDoc says so</a></li>
80 : sxenos 1.5 <li><a href="#mozTocId753192">5.3 Lazy creation
81 : sxenos 1.6 should happen as late as possible </a></li>
82 : sxenos 1.5 <li><a href="#mozTocId921869">5.4 getters should
83 : sxenos 1.6 not modify the thing they are supposed to measure </a></li>
84 : sxenos 1.1 </ul>
85 :     </li>
86 :     </ul>
87 : sxenos 1.4 <br>
88 : sxenos 1.1 <div style="margin-left: 40px;"><span style="font-weight: bold;"></span></div>
89 : sxenos 1.4 <h2><a class="mozTocH2" name="mozTocId917303"></a><span
90 : sxenos 1.1 style="font-weight: bold;"></span><span style="font-weight: bold;">1.0
91 :     Introduction</span>
92 :     <br>
93 : sxenos 1.4 </h2>
94 : sxenos 1.3 <span style="font-weight: bold;"></span> This document describes
95 :     workbench internals and not API. The design of internals changes
96 :     frequently. For information on newer Eclipse versions, the latest
97 :     version of this document can be found on the <a
98 :     href="http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/platform-ui-home/dev.html">UI
99 :     development resources page</a>.<br>
100 :     <br>
101 : sxenos 1.1 <br>
102 :     <div style="text-align: center;"><span style="font-weight: bold;">Figure
103 : sxenos 1.4 1: Ownership of views and editors<br>
104 : sxenos 1.1 <br>
105 :     </span></div>
106 :     <div style="text-align: center;"><img alt=""
107 :     src="workbench_high_level.PNG" style="width: 600px; height: 340px;"><br>
108 :     </div>
109 :     <br>
110 : sxenos 1.6 Figure 1 shows how views and editors are owned by the workbench.
111 :     <br>
112 : sxenos 1.1 <br>
113 :     The Workbench contains one or more WorkbenchWindows, each of which
114 :     contain zero or more WorkbenchPages. The WorkbenchWindow supplies the
115 : sxenos 1.6 trim widgets, and the WorkbenchPage supplies the window contents. In
116 :     theory, a WorkbenchWindow can contain any number of pages, but in
117 :     practice there is never more than 1 page in a window.
118 :     <br>
119 : sxenos 1.1 <br>
120 :     Views and editors are owned by the page, through a ViewFactory and
121 :     EditorManager respectively. EditorManager stores the list of editors
122 : sxenos 1.6 and
123 :     their shared resources, and ViewFactory stores a reference counted list
124 :     of views. The workbench works in terms of EditorReferences and
125 :     ViewReferences, and in this article the terms "editor" or "view" will
126 :     refer to these classes specifically. In situations where the
127 :     distinction
128 :     between editors and views is not important, we will simply use the term
129 :     "part". The implementation of the part (typically an IEditorPart or
130 :     IViewPart) is created lazily when it is first needed. As shown in
131 :     Figure
132 :     2, a part reference exists for every tab but the implementation is only
133 :     created the first time it becomes visible.
134 :     <br>
135 : sxenos 1.1 <br>
136 :     The page owns a set of perspectives. Perspectives contain a layout and
137 :     information about what action sets to enable. Although perspectives
138 :     appear to contain views and the editor area, they only own a layout.
139 : sxenos 1.6 The
140 :     page itself maintains a reference count for how many perspectives are
141 :     using each view, and has complete ownership of the parts and editor
142 :     area.
143 :     <br>
144 : sxenos 1.1 <br>
145 :     Not shown in figure 1 are the classes PerspectiveHelper and
146 :     EditorAreaHelper. These classes exist largely for historic purposes,
147 : sxenos 1.6 and
148 :     in this article we will treat the former as though it were part of the
149 :     Perspective class and the latter as part of the WorkbenchPage class.
150 :     <br>
151 : sxenos 1.1 <br>
152 :     <br>
153 :     <div style="text-align: center;"><span style="font-weight: bold;">Figure
154 : sxenos 1.4 2: Workbench objects and what they look like<br>
155 : sxenos 1.1 <br>
156 :     </span></div>
157 :     <div style="text-align: center;"><img alt="" src="what_you_see.PNG"
158 :     style="width: 892px; height: 700px;"><br>
159 :     </div>
160 :     <br>
161 : sxenos 1.4 <h2><a class="mozTocH2" name="mozTocId270357"></a>2.0 Inside a part<br>
162 :     </h2>
163 : sxenos 1.1 <div style="text-align: center;"><span style="font-weight: bold;">
164 : sxenos 1.4 Figure 3: Anatomy of a part</span><br>
165 : sxenos 1.1 </div>
166 :     <div style="text-align: center;"><img alt="" src="anatomy_of_a_part.PNG"
167 :     style="width: 420px; height: 280px;"><br>
168 :     </div>
169 : sxenos 1.4 Internally, a part consists of several objects (Figure 3).
170 : sxenos 1.1 WorkbenchPartReference is the topmost representation of the part.
171 :     Depending on where it is used, the part reference is often exposed as
172 :     IWorkbenchPartReference, IViewReference, IEditorRefenece, or
173 :     IPresentablePart, or PartPane. These are essentially different
174 :     interfaces to the same object. The I*Reference interfaces are
175 :     implemented directly by WorkbenchPartReference and its subclasses.
176 :     IPresentablePart is a simple adapter that redirects its methods
177 : sxenos 1.6 directly
178 :     to the part. PartPane implements the LayoutPart protocol which is
179 :     needed
180 :     to insert the part into the workbench layout. PartPane also manages the
181 :     SWT resources (such as a top-level control) that are needed to include
182 :     the control in the workbench layout.
183 :     <br>
184 : sxenos 1.1 <br>
185 :     The part implementation (the IEditorPart or IViewPart) is owned by the
186 : sxenos 1.6 reference. When the implementation is created, it is given a PartSite.
187 :     The PartSite (seen by client code as an IWorkbenchPartSite,
188 :     IEditorSite,
189 :     or IViewSite) allows the client code to communicate with the reference
190 :     and manages services created for the implementation.
191 :     <br>
192 :     <br>
193 :     WorkbenchPartReferences allocates SWT resources lazily as needed. Once
194 :     created, the part reference must be explicitly disposed. Disposing the
195 :     reference cleans up all of its resources (including the part
196 : sxenos 1.1 implementation itself) and guarantees that the reference will never
197 :     allocate additional resources. The workbench page disposes the part
198 :     reference once it is certain that it will never need to use that part
199 :     again. Unlike SWT controls, it is valid to continue using the reference
200 :     after it has been disposed. A disposed part reference is unlikely to do
201 :     anything interesting besides returning its name and cannot be used with
202 : sxenos 1.6 any methods in the workbench page. Since it is hard (or impossible) for
203 : sxenos 1.1 clients to track the lifecycle of the reference, they are permitted to
204 : sxenos 1.6 continue using its public interface after disposal.
205 :     <br>
206 : sxenos 1.1 <br>
207 : sxenos 1.4 <h3><a class="mozTocH3" name="mozTocId713423"></a>2.1 Part Lifecycle<br>
208 :     </h3>
209 : sxenos 1.1 <div style="text-align: center;"><span style="font-weight: bold;">Figure
210 : sxenos 1.4 4: WorkbenchPartReference states<br>
211 : sxenos 1.1 <br>
212 :     </span></div>
213 :     <div style="text-align: center;"><img alt="" src="part_states.PNG"
214 :     style="width: 445px; height: 590px;"><br>
215 :     </div>
216 : sxenos 1.4 Figure 4 shows the part lifecycle as a state machine. The part
217 : sxenos 1.6 reference
218 :     stores its current state in the integer state field.
219 :     <br>
220 :     <br>
221 :     Notes:
222 : sxenos 1.1 <br>
223 :     <ul>
224 :     <li>The part is in a distinct state while it is in the process of
225 :     creating the implementation. It cannot be recursively re-created or
226 :     disposed while it is in this state.</li>
227 :     <li>The part implementation cannot be recreated once the reference
228 :     has been disposed.</li>
229 :     <li>Parts cannot return to the lazy state once they have been
230 :     created. This is a limitation in the 3.1 implementation, not a
231 :     functional requirement.</li>
232 :     <li>It is valid to continue using the public interface of
233 :     WorkbenchPartReference once it has been disposed, however a disposed
234 :     reference cannot be passed to methods in workbench page (since it is,
235 :     by definition, no longer part of any page).</li>
236 :     </ul>
237 : sxenos 1.4 <h3><a class="mozTocH3" name="mozTocId789670"></a>2.2 Part Construction</h3>
238 : sxenos 1.1 <div style="text-align: center;"><span style="font-weight: bold;">Figure
239 : sxenos 1.4 5: Message sequence for creating a part<br>
240 : sxenos 1.1 <br>
241 :     </span></div>
242 :     <div style="text-align: center;"><img alt="" src="part_creation_msc.PNG"
243 :     style="width: 892px; height: 700px;"><br>
244 :     </div>
245 :     <br>
246 : sxenos 1.6 Figure 5 shows the process for creating a part. The horizontal line
247 :     separates the two phases of creating a part. First the part is added to
248 :     the layout, and then a real implementation is attached. These are two
249 :     distinct operations, and the part can exist as a tab in the page with
250 :     no
251 :     implementation for some time before it becomes visible. This diagram
252 :     focuses on the interactions with the part reference, and skips the
253 :     details of adding the part to the presentation and creating the part
254 :     site.
255 :     <br>
256 :     <br>
257 :     Suggestion: there are situations where it would be useful to only add
258 :     the part to the layout if it can be created successfully (this would be
259 :     necessary to pass a PartInitException thrown in the implementation's
260 :     init method up through IWorkbenchPage.openEditor). In these situations,
261 :     it would be possible to merge both operations into one atomic operation
262 :     by creating the part before adding it to the layout. It is unknown if
263 :     this would create event ordering bugs in client code.
264 :     <br>
265 : sxenos 1.1 <br>
266 :     <span style="font-weight: bold;"></span>
267 : sxenos 1.4 <h2><a class="mozTocH2" name="mozTocId409413"></a>3.0 Workbench Layout<br>
268 :     </h2>
269 : sxenos 1.1 <br>
270 :     <div style="text-align: center;"><span style="font-weight: bold;">Figure
271 : sxenos 1.4 6: LayoutPart hierarchy</span><br>
272 : sxenos 1.1 <img alt="" src="LayoutPart_hierarchy.PNG"
273 :     style="width: 302px; height: 412px;"><br>
274 :     </div>
275 :     <br>
276 :     The workbench layout provides supports arranging parts using drag &amp;
277 :     drop, resizing and detaching parts, fast views, etc. This section gives
278 : sxenos 1.6 a quick overview of the layout mechanism.
279 :     <br>
280 : sxenos 1.1 <br>
281 :     Anything in the workbench layout is a LayoutPart. A LayoutPart manages
282 : sxenos 1.6 a
283 :     set of widgets in a rectangular region of the screen, can contain or
284 : sxenos 1.1 arrange other layout parts, returns size constraints, responds to drag
285 :     events, etc. To this extent, a LayoutPart is very similar to a custom
286 :     SWT Control. However, LayoutPart differs from Control in several
287 : sxenos 1.6 important ways.
288 :     <br>
289 : sxenos 1.1 <ul>
290 :     <li>The LayoutPart hierarchy is not the same as the widget hierarchy.
291 :     Even though one LayoutPart may contain another, their widgets may be
292 :     peers. This allows drag and drop to work on platforms where SWT doesn't
293 :     support reparenting, since a LayoutPart can be reparented without
294 :     reparenting its widgets.<br>
295 :     </li>
296 :     <li>LayoutParts mainly perform layout-related tasks, unlike Controls
297 :     which also supply behavior and appearance. The behavior of a LayoutPart
298 :     is supplied by the widgets it arranges.<br>
299 :     </li>
300 :     <li>LayoutParts know about higher-level concepts like zoom, and can
301 :     specify constraints about their own size.<br>
302 :     </li>
303 :     </ul>
304 : sxenos 1.6 Figure 6 shows the LayoutPart hierarchy. Notice the symmetry between
305 :     the
306 :     View* classes and the Editor* classes. These classes exist largely for
307 :     historical reasons, and it should be possible to move all of the
308 :     functionality into the Part* base classes or other objects in the
309 :     system. Since all of the interesting behavior comes from the Part*
310 : sxenos 1.1 classes, the remainder of this section will focus on them without
311 : sxenos 1.6 describing the minor differences between views and editors.
312 :     <br>
313 : sxenos 1.1 <br>
314 : sxenos 1.6 PartSashContainer provides the splitting behavior in the workbench
315 :     window. It arranges rectangular regions separated by
316 : sxenos 1.1 sashes, and allows new regions to be created by splitting old ones. It
317 :     also supports the size constraints that make minimized views possible,
318 :     and determines what it means for one of these regions to be maximized.
319 :     Typically, a PartSashContainer contains a bunch of PartStacks, although
320 :     it is also possible for it to contain another PartSashContainer. The
321 :     latter case occurs since the editor area and the perspective both use a
322 :     PartSashContainer for their layout and one is embedded inside the
323 : sxenos 1.6 other.
324 :     PartSashContainer owns its stacks but does not own an embedded
325 : sxenos 1.1 PartSashContainer. In a workbench window, there is one
326 : sxenos 1.6 PartSashContainer
327 :     for each perspective and one for the editor area itself.
328 :     <br>
329 : sxenos 1.1 <br>
330 :     PartStack arranges a stack of PartPanes. PartStack allows the
331 :     presentation API to participate in the workbench layout. The code for
332 :     creating the tabs and arranging parts is supplied by the active
333 : sxenos 1.6 presentation.
334 :     <br>
335 : sxenos 1.1 <br>
336 :     PartPane allows views and editors to participate in the workbench
337 :     layout. Although PartPanes are arranged by PartStacks they belong to
338 :     part reference, not the stack. The same PartPane can exist in more than
339 :     one PartStack at a time if that part appears in more that one
340 : sxenos 1.6 perspective.
341 :     <span style="font-weight: bold;"><br>
342 : sxenos 1.1 <br>
343 :     </span>
344 : sxenos 1.4 <h3><a class="mozTocH3" name="mozTocId95893"></a>3.1 An example layout</h3>
345 : sxenos 1.1 LayoutParts are best explained through example. Imagine a
346 :     WorkbenchWindow that contains custom Java and Java Browsing
347 : sxenos 1.6 perspectives
348 :     that look like Figure 7 and Figure 8 respectively.
349 :     <br>
350 : sxenos 1.1 <br>
351 :     <br>
352 :     <div style="text-align: center;"><span style="font-weight: bold;">Figure
353 : sxenos 1.4 7: Example Java Perspective</span><br>
354 : sxenos 1.1 <img alt="" src="perspective1.PNG" style="width: 571px; height: 495px;"><br>
355 :     <br>
356 : sxenos 1.4 <span style="font-weight: bold;">Figure 8: Example Java Browsing
357 : sxenos 1.1 perspective</span><br>
358 :     <img alt="" src="perspective2.PNG" style="width: 571px; height: 495px;"><br>
359 :     </div>
360 :     <br>
361 : sxenos 1.4 <br>
362 :     Assume that the window resembles Figure 7. In this case, the Java
363 : sxenos 1.1 perspective is active, the Java Browsing perspective is hidden, and the
364 : sxenos 1.4 objects are connected as shown in Figure 9:<br>
365 :     <br>
366 : sxenos 1.1 <br>
367 :     <div style="text-align: center;"><span style="font-weight: bold;">Figure
368 : sxenos 1.4 9: LayoutPart instances when two perspectives are open</span><br>
369 : sxenos 1.1 <img alt="" src="perspective1_2_instances.PNG"
370 :     style="width: 555px; height: 670px;"><br>
371 :     <div style="text-align: left;"><br>
372 :     </div>
373 :     </div>
374 :     <br>
375 : sxenos 1.2 <br>
376 :     All LayoutParts have a container pointer that points to the object that
377 :     is currently managing their position. Since the same LayoutPart
378 : sxenos 1.6 instance
379 :     may exist in more than one perspective at once, this pointer points to
380 :     the part's container in the currently-active perspective. In the case
381 :     of
382 :     the projects view, above, the part is not in the current perspective so
383 :     its container pointer is null. When another perspective becomes active,
384 :     all the container pointers move to the new perspective. For historical
385 :     reasons, this is accomplished by setting and clearing the contianer
386 :     pointer when the container becomes visible or invisible. This works
387 :     since only one perspective is visible at a time, but it also means that
388 :     perspectives cannot be manipulated when they are invisible.
389 :     <br>
390 : sxenos 1.1 <br>
391 :     The diagram shows the internal objects that make up the only editor.
392 :     Although this detail has been omitted for the views, they would look
393 :     similar. Each view's PartPane is owned by a part reference which may
394 : sxenos 1.6 have an associated part implementation.
395 :     <br>
396 : sxenos 1.1 <br>
397 : sxenos 1.4 <h3><a class="mozTocH3" name="mozTocId114962"></a>3.2 Zoom / Unzoom
398 : sxenos 1.1 protocol<br>
399 : sxenos 1.4 </h3>
400 : sxenos 1.1 The notion of "zoom" is defined locally between a part and its
401 : sxenos 1.6 immediate
402 :     container. Zoom changes are triggered bottom-up. A part asks its parent
403 :     to "zoom me", and the parent either does something with the request or
404 :     forwards the request up to its parent. Each container determines what
405 :     it
406 :     means for a child to be zoomed. Once a part's zoom state changes, its
407 :     parent notifies it by calling setZoomed. The part may in turn zoom or
408 :     unzoom one or more of its children.
409 :     <br>
410 : sxenos 1.1 <br>
411 :     Anything that can contain LayoutParts must implement the following
412 : sxenos 1.6 methods, to support zooming:
413 :     <br>
414 : sxenos 1.4 <span style="font-family: monospace;"><br>
415 : sxenos 1.6 </span>
416 :     <code>&nbsp;&nbsp;&nbsp; /**<br>
417 : sxenos 1.1 &nbsp;&nbsp;&nbsp;&nbsp; * Called by child parts to request a zoom in,
418 :     given an immediate child <br>
419 :     &nbsp;&nbsp;&nbsp;&nbsp; * <br>
420 :     &nbsp;&nbsp;&nbsp;&nbsp; * @param toZoom part to zoom in on<br>
421 :     &nbsp;&nbsp;&nbsp;&nbsp; */<br>
422 :     &nbsp;&nbsp;&nbsp; public void childRequestZoomIn(LayoutPart toZoom);<br>
423 :     &nbsp;&nbsp;&nbsp; <br>
424 :     &nbsp;&nbsp;&nbsp; /**<br>
425 :     &nbsp;&nbsp;&nbsp;&nbsp; * Called by child parts to request a zoom out<br>
426 :     &nbsp;&nbsp;&nbsp;&nbsp; */<br>
427 :     &nbsp;&nbsp;&nbsp; public void childRequestZoomOut();<br>
428 :     &nbsp;&nbsp;&nbsp; <br>
429 :     &nbsp;&nbsp;&nbsp; /**<br>
430 :     &nbsp;&nbsp;&nbsp;&nbsp; * Returns true iff the given child is obscured
431 :     due to the fact that the container is zoomed into<br>
432 :     &nbsp;&nbsp;&nbsp;&nbsp; * another part. <br>
433 :     &nbsp;&nbsp;&nbsp;&nbsp; * <br>
434 :     &nbsp;&nbsp;&nbsp;&nbsp; * @param toTest part to test<br>
435 :     &nbsp;&nbsp;&nbsp;&nbsp; * @return true iff the part is currently
436 :     obscured <br>
437 :     &nbsp;&nbsp;&nbsp;&nbsp; */<br>
438 :     &nbsp;&nbsp;&nbsp; public boolean childObscuredByZoom(LayoutPart
439 :     toTest);<br>
440 :     &nbsp;&nbsp;&nbsp; <br>
441 :     &nbsp;&nbsp;&nbsp; /**<br>
442 :     &nbsp;&nbsp;&nbsp;&nbsp; * Returns true iff we are zoomed into the
443 : sxenos 1.6 given
444 :     part, given an immediate child of this container.<br>
445 : sxenos 1.1 &nbsp;&nbsp;&nbsp;&nbsp; * <br>
446 :     &nbsp;&nbsp;&nbsp;&nbsp; * @param toTest part to test<br>
447 :     &nbsp;&nbsp;&nbsp;&nbsp; * @return true iff this contianer is currently
448 :     zooming in on the given part<br>
449 :     &nbsp;&nbsp;&nbsp;&nbsp; */<br>
450 :     &nbsp;&nbsp;&nbsp; public boolean childIsZoomed(LayoutPart toTest);<br>
451 : sxenos 1.4 <br>
452 : sxenos 1.6 </code>
453 :     <br>
454 :     Consider again Figure 7. If we were to double-click on the java editor
455 :     to zoom it, the LayoutParts would send messages to one another in the
456 :     following sequence. (In this diagram, each cell represents a method
457 :     call. Each column is an object. The reciever's column shows the method
458 :     name and the caller contains an arrow. Rows are in ascending order of
459 :     time.)
460 :     <br>
461 : sxenos 1.1 <br>
462 :     <table style="width: 100%; text-align: left;" border="1" cellpadding="2"
463 :     cellspacing="2">
464 :     <tbody>
465 :     <tr>
466 :     <td style="vertical-align: top; font-weight: bold;">Java Editor
467 :     (PartPane)<br>
468 :     </td>
469 :     <td style="vertical-align: top; font-weight: bold;">PartStack<br>
470 :     </td>
471 :     <td style="vertical-align: top; font-weight: bold;">editor area
472 :     (EditorSashContainer)<br>
473 :     </td>
474 :     <td style="vertical-align: top; font-weight: bold;">ViewSashContainer<br>
475 :     </td>
476 :     </tr>
477 :     <tr>
478 :     <td style="vertical-align: top;">requestZoomIn<br>
479 :     </td>
480 :     <td style="vertical-align: top;"><br>
481 :     </td>
482 :     <td style="vertical-align: top;"><br>
483 :     </td>
484 :     <td style="vertical-align: top;"><br>
485 :     </td>
486 :     </tr>
487 :     <tr>
488 :     <td style="vertical-align: top;"><img alt="" src="right_arrow.PNG"
489 :     style="width: 42px; height: 17px;"><br>
490 :     </td>
491 :     <td style="vertical-align: top;">childRequestZoomIn(java editor)<br>
492 :     </td>
493 :     <td style="vertical-align: top;"><br>
494 :     </td>
495 :     <td style="vertical-align: top;"><br>
496 :     </td>
497 :     </tr>
498 :     <tr>
499 :     <td style="vertical-align: top;"><br>
500 :     </td>
501 :     <td style="vertical-align: top;"><img alt="" src="right_arrow.PNG"
502 :     style="width: 42px; height: 17px;"><br>
503 :     </td>
504 :     <td style="vertical-align: top;">childRequestZoomIn(java editor's
505 :     part stack)<br>
506 :     </td>
507 :     <td style="vertical-align: top;"><br>
508 :     </td>
509 :     </tr>
510 :     <tr>
511 :     <td style="vertical-align: top;"><br>
512 :     </td>
513 :     <td style="vertical-align: top;"><br>
514 :     </td>
515 :     <td style="vertical-align: top;">if there were other editor
516 :     stacks in the layout, we would call setVisible(false) on them here</td>
517 :     <td style="vertical-align: top;"><br>
518 :     </td>
519 :     </tr>
520 :     <tr>
521 :     <td style="vertical-align: top;"><br>
522 :     </td>
523 :     <td style="vertical-align: top;"><br>
524 :     </td>
525 :     <td style="vertical-align: top;">remember the partStack as the
526 :     zoomed part<br>
527 :     </td>
528 :     <td style="vertical-align: top;"><br>
529 :     </td>
530 :     </tr>
531 :     <tr>
532 :     <td style="vertical-align: top;"><br>
533 :     </td>
534 :     <td style="vertical-align: top;">setZoomed(true)<br>
535 :     </td>
536 :     <td style="vertical-align: top;"><img alt="" src="left_arrow.PNG"
537 :     style="width: 42px; height: 17px;"><br>
538 :     </td>
539 :     <td style="vertical-align: top;"><br>
540 :     </td>
541 :     </tr>
542 :     <tr>
543 :     <td style="vertical-align: top;">setZoomed(true)<br>
544 :     </td>
545 :     <td style="vertical-align: top;"><img alt="" src="left_arrow.PNG"
546 :     style="width: 42px; height: 17px;"><br>
547 :     </td>
548 :     <td style="vertical-align: top;"><br>
549 :     </td>
550 :     <td style="vertical-align: top;"><br>
551 :     </td>
552 :     </tr>
553 :     <tr>
554 :     <td style="vertical-align: top;"><br>
555 :     </td>
556 :     <td style="vertical-align: top;"><br>
557 :     </td>
558 :     <td style="vertical-align: top;"><img alt="" src="right_arrow.PNG"
559 :     style="width: 42px; height: 17px;"><br>
560 :     </td>
561 :     <td style="vertical-align: top;">childRequestZoomIn(editor area)<br>
562 :     </td>
563 :     </tr>
564 :     <tr>
565 :     <td style="vertical-align: top;"><br>
566 :     </td>
567 :     <td style="vertical-align: top;"><br>
568 :     </td>
569 :     <td style="vertical-align: top;"><br>
570 :     </td>
571 :     <td style="vertical-align: top;">call setVisible(false) on all
572 :     PartStacks for views in the perspective<br>
573 :     </td>
574 :     </tr>
575 :     <tr>
576 :     <td style="vertical-align: top;"><br>
577 :     </td>
578 :     <td style="vertical-align: top;"><br>
579 :     </td>
580 :     <td style="vertical-align: top;"><br>
581 :     </td>
582 :     <td style="vertical-align: top;">remember the editor area as the
583 :     zoomed part<br>
584 :     </td>
585 :     </tr>
586 :     <tr>
587 :     <td style="vertical-align: top;"><br>
588 :     </td>
589 :     <td style="vertical-align: top;"><br>
590 :     </td>
591 :     <td style="vertical-align: top;">setZoomed(true)<br>
592 :     </td>
593 :     <td style="vertical-align: top;"><img alt="" src="left_arrow.PNG"
594 :     style="width: 42px; height: 17px;"></td>
595 :     </tr>
596 :     <tr>
597 :     <td style="vertical-align: top;"><br>
598 :     </td>
599 :     <td style="vertical-align: top;"><br>
600 :     </td>
601 :     <td style="vertical-align: top;"><br>
602 :     </td>
603 :     <td style="vertical-align: top;">trigger a layout<br>
604 :     </td>
605 :     </tr>
606 :     <tr>
607 :     <td style="vertical-align: top;"><br>
608 :     </td>
609 :     <td style="vertical-align: top;"><br>
610 :     </td>
611 :     <td style="vertical-align: top;">setBounds(zoomed bounds)<br>
612 :     </td>
613 :     <td style="vertical-align: top;"><img alt="" src="left_arrow.PNG"
614 :     style="width: 42px; height: 17px;"></td>
615 :     </tr>
616 :     <tr>
617 :     <td style="vertical-align: top;"><br>
618 :     </td>
619 :     <td style="vertical-align: top;">setBounds(zoomed bounds)</td>
620 :     <td style="vertical-align: top;"><img alt="" src="left_arrow.PNG"
621 :     style="width: 42px; height: 17px;"></td>
622 :     <td style="vertical-align: top;"><br>
623 :     </td>
624 :     </tr>
625 :     <tr>
626 :     <td style="vertical-align: top;">setBounds(zoomed bounds)</td>
627 :     <td style="vertical-align: top;"><img alt="" src="left_arrow.PNG"
628 :     style="width: 42px; height: 17px;"></td>
629 :     <td style="vertical-align: top;"><br>
630 :     </td>
631 :     <td style="vertical-align: top;"><br>
632 :     </td>
633 :     </tr>
634 :     <tr>
635 :     <td style="vertical-align: top;"><br>
636 :     </td>
637 :     <td style="vertical-align: top;"><br>
638 :     </td>
639 :     <td style="vertical-align: top;">trigger a layout (nothing to do)<br>
640 :     </td>
641 :     <td style="vertical-align: top;"><br>
642 :     </td>
643 :     </tr>
644 :     </tbody>
645 :     </table>
646 :     <br>
647 : sxenos 1.4 <h3><a class="mozTocH3" name="mozTocId977378"></a>3.3 Layout protocol<br>
648 :     </h3>
649 : sxenos 1.1 Every LayoutPart can specify constraints on their size. Parts specify
650 :     constraints by implementing the ISizeProvider interface. ISizeProvider
651 :     serves a similar function as the computeSize method on an SWT control,
652 :     in that the parent layout uses it to consult with the part when
653 :     computing the part's size. ISizeProvider can provide a variety of
654 : sxenos 1.6 constraints:
655 :     <br>
656 : sxenos 1.1 <br>
657 :     <table style="width: 100%; text-align: left;" border="1" cellpadding="2"
658 :     cellspacing="2">
659 :     <tbody>
660 :     <tr>
661 :     <td style="vertical-align: top; font-weight: bold;">Constraint
662 :     type<br>
663 :     </td>
664 :     <td style="vertical-align: top; font-weight: bold;">Meaning<br>
665 :     </td>
666 :     </tr>
667 :     <tr>
668 :     <td style="vertical-align: top;">Minimum size<br>
669 :     </td>
670 :     <td style="vertical-align: top;">Given the available space along
671 :     one dimension, the part returns the minimum size that it can be
672 :     compressed to along the other dimension. For example, a stack would
673 :     typically set its minimum size to be large enough to fit its tabs. The
674 :     information about available perpendicular space could allow a stack to
675 :     have wrapping tabs and still reserve enough vertical space for the tabs
676 :     once they are wrapped to fill the available horizontal space.<br>
677 :     </td>
678 :     </tr>
679 :     <tr>
680 :     <td style="vertical-align: top;">Maximum size<br>
681 :     </td>
682 :     <td style="vertical-align: top;">Given the available space along
683 :     one dimension, the part returns the maximum size that it can utilize
684 :     along the other dimension. For example, minimized stacks are
685 :     implemented by setting their maximum size to the minimized size.
686 :     Non-minimized stacks typically have an unbounded maximum size.<br>
687 :     </td>
688 :     </tr>
689 :     <tr>
690 :     <td style="vertical-align: top;">Preferred size<br>
691 :     </td>
692 :     <td style="vertical-align: top;">Given the availble space along
693 :     one dimension and a preferred size, this returns the size closest to
694 :     the preferred size at which the part would look best. Parts can use
695 :     this to quantize their size. For example, a part can ensure that its
696 :     size is always chosen such that it can be completely filled with
697 :     toolbar icons leaving no space left over.<br>
698 :     </td>
699 :     </tr>
700 :     </tbody>
701 :     </table>
702 :     <br>
703 :     Although there are three kinds of constraints, they are all returned
704 :     using a single method. See the JavaDoc on ISizeProvider for more
705 : sxenos 1.6 information.
706 :     <br>
707 : sxenos 1.1 <br>
708 :     Whenever a size constraint changes, the part notifies its contianer by
709 :     calling resizeChild(part). This tells the container to respond to the
710 : sxenos 1.6 new constraints, and to resize the child if necessary (suggestion: if
711 :     this is ever exposed as API, it would be better to separate the
712 :     concerns
713 :     of notifying the parent of changes and triggering a layout. In general,
714 :     it may be possible for more than one part to change without requiring a
715 :     layout between each change).
716 :     <br>
717 : sxenos 1.1 <br>
718 : sxenos 1.4 <h3><a class="mozTocH3" name="mozTocId162591"></a>3.4 PartStack:
719 : sxenos 1.1 Communicating with the Presentation API<br>
720 : sxenos 1.4 </h3>
721 : sxenos 1.1 PartStack allows presentation to participate in the workbench layout.
722 : sxenos 1.6 As
723 :     shown in Figure 10, it wraps a single instance of StackPresentation,
724 :     and
725 :     allows it the presentation to manipulate parts by converting each
726 :     visible part into an IPresentablePart. The part stack outlives the
727 :     StackPresentation. Whenever the part stack needs widgets, it creates
728 :     the
729 :     StackPresentation. If the widgets are no longer needed, it disposes the
730 :     StackPresentation and remembers its persisted form. Whenever the
731 :     PartStack persists its StackPresenation, it remembers the presentation
732 :     ID so that it will not try to restore one StackPresentation from state
733 :     saved by an incompatible presentation.
734 :     <br>
735 : sxenos 1.1 <br>
736 :     <div style="text-align: center;"><span style="font-weight: bold;">Figure
737 : sxenos 1.4 10: Anatomy of PartStack</span><br>
738 : sxenos 1.1 <img alt="" src="PartStack.PNG" style="width: 430px; height: 225px;"><br>
739 :     <div style="text-align: left;"><br>
740 :     <br>
741 :     </div>
742 :     </div>
743 : sxenos 1.4 <h3><a class="mozTocH3" name="mozTocId479574"></a>3.5
744 : sxenos 1.1 PartSashContainer: The main workbench layout <br>
745 : sxenos 1.4 </h3>
746 : sxenos 1.1 <div style="text-align: center;"><span style="font-weight: bold;">Figure
747 : sxenos 1.4 11: PartSashContainer</span><br>
748 : sxenos 1.1 <img alt="" src="PartSashContainer.PNG"
749 :     style="width: 428px; height: 305px;"><br>
750 :     </div>
751 :     <br>
752 :     PartSashContainer implements the main layout for a perspective and the
753 : sxenos 1.6 editor area. As shown in Figure 11, PartSashContainer contains a list
754 :     of
755 :     children, a (possibly null) zoomed part, and a LayoutTree that manages
756 :     the actual layout.
757 :     <br>
758 : sxenos 1.1 <br>
759 :     LayoutTree is a binary tree (technically, a KD tree). Each internal
760 : sxenos 1.6 node
761 :     is an instance of LayoutTreeNode. It contains a draggable sash
762 : sxenos 1.1 (LayoutPartSash) that divides its area among its left and right
763 :     children. LayoutTreeNodes can be horizontal or vertical based on the
764 :     orientation of the sash. For horizontal nodes, the "left" child is on
765 :     top and the "right" child is on the bottom. Leaf nodes are instances of
766 :     LayoutTree (the base class), and they point to a LayoutPart that
767 :     occupies that region of the screen. Normally, this is a PartStack, but
768 : sxenos 1.6 in general it can be any LayoutPart.
769 :     <br>
770 : sxenos 1.1 <br>
771 :     Each LayoutTree occupies a recangular region of the screen that
772 :     encompasses its children. Internal nodes keep track of an integer size
773 :     for each child (implementation note: the sizes are stored in the
774 :     associated LayoutPartSash, not the LayoutTreeNode itself). Normally,
775 : sxenos 1.6 the
776 :     left and right sizes are used as a ratio for dividing up the available
777 :     space. However, when one child contains the editor area, the other
778 :     becomes "non-compressible". If one side in non-compressible, the size
779 :     value is interpreted as a fixed pixel size rather than a ratio. When
780 :     the
781 :     sash is moved, the size values are set to the current pixel sizes of
782 :     the
783 :     left and right children.
784 :     <br>
785 :     <br>
786 :     Figure 12 shows an example LayoutTree. If this tree were rendered in a
787 :     workbench window, it would resemble Figure 13. The tall vertical sash
788 :     separating the package explorer from the editor area is the root node.
789 :     The left child is the leaf node holding the package explorer's stack.
790 :     The right node is the horizontal sash separating the problems view from
791 :     the editor area. The editor area itself is a PartSashContainer, which
792 :     has its own LayoutTree. Note that the rounded rectangles in Figure 12
793 :     are LayoutParts. The upper portion of the rectangle is the part type
794 :     and
795 :     the lower portion is some text to help locate the part in the
796 :     screenshot. In this example, every internal node has the editor area on
797 :     one side of it, so all sizes are interpreted as pixel sizes and not
798 :     ratios.
799 :     <br>
800 : sxenos 1.1 <div style="text-align: center;"><span style="font-weight: bold;"></span><br>
801 : sxenos 1.4 <span style="font-weight: bold;">Figure 12: Example LayoutTree</span><br
802 : sxenos 1.1 style="font-weight: bold;">
803 :     <img alt="" src="example_LayoutTree.PNG"
804 :     style="width: 480px; height: 462px; font-weight: bold;"><br>
805 :     <span style="font-weight: bold;"><br>
806 : sxenos 1.4 Figure 13: Example perspective</span><br style="font-weight: bold;">
807 : sxenos 1.1 <img alt="" src="perspective1.PNG"
808 :     style="width: 571px; height: 495px; font-weight: bold;"><br>
809 :     </div>
810 :     <br>
811 :     Like LayoutParts, LayoutTrees also implement ISizeProvider and support
812 :     size constraints. For external nodes, the size constraints come
813 : sxenos 1.6 directly
814 :     from the LayoutPart. For internal nodes, the size constraints are
815 :     computed from the child nodes as follows:
816 :     <br>
817 : sxenos 1.1 <ol>
818 :     <li>When computing a constraint perpendicular to the sash, the result
819 :     is the sum of the constraints of the children plus the width of the
820 :     sash.</li>
821 :     <li>When computing a constraint parallel to the sash, the result is
822 :     the maximum of the constraints of the children<br>
823 :     </li>
824 :     </ol>
825 :     An example can help make this a little less abstract. Imagine we're
826 : sxenos 1.6 computing the minimum width for the root node in Figure 12, which is a
827 :     tall vertical sash. Width measurements are perpendicular to the sash,
828 :     so
829 :     we end up with case 1. The minimum width is the minimum width of the
830 :     left stack plus the sash width plus the minimum width of the right
831 :     child. This makes sense because if we made the root node any smaller,
832 :     one of the three would need to be truncated or made smaller than their
833 :     minimum size.
834 :     <br>
835 : sxenos 1.1 <br>
836 :     The "right child" mentioned above is the horizontal sash separating the
837 :     problems view from the editor area. When computing its minimum width,
838 : sxenos 1.6 we
839 :     hit case 2: the minimum width of a horizantal sash is the maximum of
840 :     the
841 :     minimum widths of each child. Intuitively, this means that the child
842 :     with the larger minimum size will be the first to reach its minimum
843 :     when
844 :     the layout gets small.
845 :     <br>
846 : sxenos 1.1 <br>
847 : sxenos 1.4 <h3><a class="mozTocH3" name="mozTocId887241"></a>3.6 Drag / Drop</h3>
848 : sxenos 1.1 <div style="text-align: center;"><span style="font-weight: bold;">Figure
849 : sxenos 1.4 14: LayoutPart drop regions</span><br>
850 : sxenos 1.1 </div>
851 :     <div style="text-align: center;"><img alt="" src="drag_regions.PNG"
852 :     style="width: 571px; height: 495px;"><br>
853 :     <div style="text-align: left;"><br>
854 :     Dragging a workbench part is triggered by calling DragUtil.performDrag.
855 :     SWT controls can respond to drag / drop by registering an
856 :     IDragOverListener with DragUtil .addDragTarget. If multiple drag
857 :     listeners are registered for the same screen position, the one
858 :     associated with the most specific control gets precidence.<br>
859 :     <br>
860 :     Rather than register drag listeners directly, LayoutParts implement a
861 :     getDropTarget method. When the window recieves a drag event, it
862 :     delegates to the top-level LayoutPart's getDropTarget. Each part either
863 :     delegates to one of its children or handles the drag event directly. If
864 :     the part returns null from getDropTarget, this means that the part has
865 :     no special preference for the drop event, and the parent may provide a
866 :     default behavior. Unlike IDragOverListener, getDropTarget works
867 :     top-down. The parent may overload any drag regions that are recognized
868 :     by the child, or provide default behaviors for drag regions not
869 :     recognized by the child.<br>
870 :     <br>
871 : sxenos 1.4 Figure 14 shows regions of the workbench where LayoutParts can be
872 : sxenos 1.1 dropped. The workbench checks these regions in the following order:<br>
873 :     <br>
874 :     <table style="width: 100%; text-align: left;" border="1" cellpadding="2"
875 :     cellspacing="2">
876 :     <tbody>
877 :     <tr>
878 :     <td style="vertical-align: top;"><span
879 :     style="color: rgb(0, 51, 0);">1. green region</span><br>
880 :     </td>
881 :     <td style="vertical-align: top;">The fast view bar registers a
882 :     IDragOverListener that responds to views being dragged.<br>
883 :     </td>
884 :     </tr>
885 :     <tr>
886 :     <td style="vertical-align: top;"><span
887 :     style="background-color: rgb(0, 0, 0);"><span
888 :     style="background-color: rgb(255, 255, 255);">2. black regions</span></span><br>
889 :     </td>
890 :     <td style="vertical-align: top;">These areas are reserved by
891 :     PartSashContainer.getDropTarget. When the user drags a part over this
892 :     region, the PartSashContainer interprets this as a split and does not
893 :     ask its child to participate in the drag. This ensures that it is never
894 :     possible for the child to prevent splitting by reserving its entire
895 :     area as a drop region. The region outside the PartSashContainer's
896 :     client area is handled by an IDragOverListener registered with the
897 :     shell. This allows parts to be attached to the edge of the layout by
898 :     dragging over the window trim.<br>
899 :     </td>
900 :     </tr>
901 :     <tr>
902 :     <td style="vertical-align: top;"><span
903 :     style="color: rgb(255, 0, 0);">3. red regions</span><br>
904 :     </td>
905 :     <td style="vertical-align: top;">For most of the screen area,
906 :     PartSashContainer delegates to its child (PartStack.getDropTarget).
907 :     PartStack filters out objects that don't belong in the stack (no
908 :     editors in view stacks, etc) and delegates to the presentation
909 :     (StackPresentation.dragOver). The default presentation recognizes the
910 :     tabs and title area as drop targets, but returns null everywhere else.
911 :     This is the best practice for presentations and PartStack since it
912 :     permits PartSashContainer to extend the split regions where possible.<br>
913 :     </td>
914 :     </tr>
915 :     <tr>
916 :     <td style="vertical-align: top;"><span
917 :     style="color: rgb(0, 0, 153);">4. blue regions</span><br>
918 :     </td>
919 :     <td style="vertical-align: top;">If the child doesn't have any
920 :     particular use for the drop location, the PartSashContainer extends the
921 :     split regions. If the child allows objects of this type to be added
922 :     (determined by calling LayoutPart.allowsAdd), it uses the center of the
923 :     rectangle for stacking. Otherwise, the entire region is used for
924 :     splitting. The latter case occurs when dragging views over the editor
925 :     area or when dragging over a standalone view.<br>
926 :     </td>
927 :     </tr>
928 :     <tr>
929 :     <td style="vertical-align: top;">5. outside the window (not shown)<br>
930 :     </td>
931 :     <td style="vertical-align: top;">The workbench page registers an
932 :     IDragOverListener that responds to views being dragged outside the
933 :     workbench window, and interprets this as a detach operation.<br>
934 :     </td>
935 :     </tr>
936 :     </tbody>
937 :     </table>
938 :     <br>
939 :     By convention, all methods used for drag / drop work in display
940 :     coordinates.<br>
941 : sxenos 1.4 <br>
942 : sxenos 1.1 </div>
943 :     </div>
944 : sxenos 1.4 <h2><a class="mozTocH2" name="mozTocId443855"></a>4.0 Action Bars</h2>
945 : sxenos 1.1 Parts contribute to menus, toolbars, coolbars, popup menus, etc. using
946 :     action bars. Each action bar implements IActionBars. It is possible to
947 :     create one action bar as a child of another. In this situation, the
948 :     parent and child share the same widgets, but the child may be disabled
949 : sxenos 1.6 independently of the parent. Figure 15 shows how the workbench action
950 :     bars are constructed. The rectangles indicate instances of IActionBars,
951 :     and the ovals indicate other entities that create or modify action
952 :     bars.
953 :     Black arrows indicate the flow of information.<br>
954 : sxenos 1.1 <br>
955 :     <div style="text-align: center;"><span style="font-weight: bold;">Figure
956 : sxenos 1.4 15: Action bar information flow</span><br>
957 : sxenos 1.1 <img alt="" src="action_bar_flow.PNG"
958 :     style="width: 800px; height: 600px;"><br>
959 :     <div style="text-align: left;"><p:colorscheme
960 :     colors="#FFFFFF,#000000,#808080,#000000,#00CC99,#3333CC,#CCCCFF,#B2B2B2"></p:colorscheme>
961 :     <div v:shape="_x0000_s2050" class="O">
962 :     <div style=""><span style="font-size: 50%;"><br>
963 :     </span><span style="font-family: Symbol; font-size: 50%;"></span><span
964 :     style="font-size: 50%;"></span><span
965 :     style="font-family: Symbol; font-size: 50%;"></span><span
966 :     style="font-size: 50%;"></span><span
967 :     style="font-family: Symbol; font-size: 50%;"></span><span
968 :     style="font-size: 50%;"></span></div>
969 :     <div style=""><span style="display: none;">
970 :     </span></div>
971 :     </div>
972 :     </div>
973 :     </div>
974 :     <br>
975 : sxenos 1.6 <br>
976 : sxenos 1.1 The workbench window has a top level IActionBars instance that
977 : sxenos 1.6 contributes to the main menubar, coolbar, etc. This top-level object is
978 :     returned by WorkbenchWindow.getActionBars().
979 :     Most action bars are descendants of this top-level object, with the
980 :     notable exception of the view action bars.<br>
981 :     <br>
982 : sxenos 1.1 <br>
983 : sxenos 1.4 <h3><a class="mozTocH3" name="mozTocId652269"></a>4.1 Editor Action Bars<br>
984 :     </h3>
985 : sxenos 1.1 Each type of editor gets a reference-counted IActionBars instance that
986 : sxenos 1.6 is a child of the window's action bars. For example, if the workbench
987 :     contains 10 java editors and 10 text editors, it will create one
988 :     IActionBars to be shared among the Java editors and another IActionBars
989 :     to be shared among the text editors. Editors can access this shared
990 :     instance by calling getSite().getActionBars(). Editor action bars are
991 :     initialized by an instance of IEditorActionBarContributor, and
992 :     additional actions are added by the editorActions extension point.
993 :     <br>
994 : sxenos 1.1 <br>
995 :     The reference counted IEditorActionBars are managed by the
996 : sxenos 1.6 EditorManager, along with the IActionBarContributor.
997 :     <br>
998 : sxenos 1.1 <br>
999 : sxenos 1.4 <h3><a class="mozTocH3" name="mozTocId340925"></a>4.2 Action Sets<br>
1000 :     </h3>
1001 : sxenos 1.1 An action set is an action bar that is identified by ID. Action sets
1002 :     are contributed by the actionSets extension point, and their action
1003 :     bars are a child of the workbench window's root action bars. Visibility
1004 :     of action sets is controlled by the following function:<br>
1005 :     <br>
1006 :     <div style="margin-left: 40px;"><img alt="" src="action_set_formula.PNG"
1007 :     style="width: 208px; height: 29px;"><br>
1008 :     </div>
1009 :     <br>
1010 :     Where:<br>
1011 :     <br>
1012 :     <div style="margin-left: 40px;">P = set of actions enabled in the
1013 :     perspective. Returned by Perspective.getAlwaysOnActionSets().
1014 :     Initialized by the perspective factory, perspective extensions
1015 :     extension point, and IWonkbenchPage.showActionSet.<br>
1016 :     A = action sets associated with the active part (associated by the
1017 :     actionSetPartAssociations extension point).<br>
1018 :     E = action sets associated with the active editor (associated by the
1019 :     actionSetPartAssociations extension point).<br>
1020 :     D = action sets that are enabled by default (a property of the
1021 :     actionSets extension markup).<br>
1022 :     N = action sets that are explicitly disabled in the current
1023 :     perspective. Initialized by IWorkbenchPage.hideActionSet.<br>
1024 :     </div>
1025 :     <br>
1026 :     The sets P and N are persisted with the current perspective between
1027 :     sessions. The sets A and E can change every time the active part or
1028 :     editor changes.<br>
1029 :     <br>
1030 :     The workbench page uses the class ActionSetManager to compute action
1031 :     set enablement. This class keeps two reference counts for each action
1032 :     set: <br>
1033 :     <ul>
1034 :     <li>a "showCount" indicates how many of P, A, E, and D the action set
1035 :     appears in</li>
1036 :     <li>a "hideCount" indicates whether the action set appears in N</li>
1037 :     </ul>
1038 :     The action set is visible iff showCount is nonzero and hideCount is
1039 :     zero.<br>
1040 :     <br>
1041 : sxenos 1.4 <h3><a class="mozTocH3" name="mozTocId277128"></a>4.3 View Actions</h3>
1042 : sxenos 1.1 Each view instance is given its own IActionBars instance. Unlike editor
1043 :     action bars, these are not shared and are not a child of the workbench
1044 :     window's root action bars. This means that view instances can
1045 :     programmatically add actions to their action bar. Additional actions
1046 : sxenos 1.6 are
1047 :     also added to a view's action bars through the viewActions extension
1048 :     point.
1049 :     <br>
1050 : sxenos 1.1 <br>
1051 : sxenos 1.4 <h2><a class="mozTocH2" name="mozTocId642161"></a>5.0 General
1052 :     Conventions</h2>
1053 : sxenos 1.1 This section describes coding conventions that apply to the entire
1054 :     workbench.<br>
1055 : sxenos 1.4 <br>
1056 :     <h3><a class="mozTocH3" name="mozTocId892615"></a>5.1 Objects must not
1057 :     be returned through API until they are fully initialized</h3>
1058 : sxenos 1.1 Some objects require several public methods to be called in a specific
1059 :     order before they are considered fully initialized. For example, to
1060 :     initialize an IViewPart, it is necessary to call the constructor,
1061 :     setInitializationData, init, and createPartControl before the part is
1062 :     considered initialized. Until <span style="font-style: italic;">all</span>
1063 :     of the above have happened successfully, it must not be possible to
1064 :     reach the object through any API method.<br>
1065 :     <br>
1066 : sxenos 1.3 Keep in mind that the object may trigger other client code during its
1067 :     own
1068 : sxenos 1.1 initialization, so it should not even be possible for an object to find
1069 :     itself during construction.<br>
1070 : sxenos 1.4 <br>
1071 :     <h3><a class="mozTocH3" name="mozTocId308622"></a>5.2 No method may
1072 :     open a modal dialog unless its JavaDoc says so</h3>
1073 : sxenos 1.1 Any method that has the possibility of opening a modal (or of calling
1074 :     Display.readAndDispatch through any other means) needs to be clearly
1075 :     documented. All callers of that method must be prepared to handle
1076 :     background
1077 :     threads running arbitrary code in *syncExecs during the method call. It
1078 :     is always a bug to open a modal dialog when extending or overloading a
1079 :     method unless the JavaDoc in the base class says otherwise. Permitting
1080 :     opening of dialogs in a method that did not previously do so is a
1081 :     breaking change for all callers of that method.<br>
1082 :     <br>
1083 :     Some common bugs:<br>
1084 :     <ul>
1085 :     <li>Views are never allowed to call MessageDialog.openError from
1086 :     their createPartControls method, especially when handling an exception.</li>
1087 :     <li>Parts can be closed in a *syncExec. If a part calls a method that
1088 :     opens dialogs, it might not still exist when the method returns. After
1089 :     calling the method, the part must check that it hasn't been disposed
1090 :     before using their widgets or accessing any members that would have
1091 : sxenos 1.4 been deallocated by the disposal.</li>
1092 : sxenos 1.1 </ul>
1093 : sxenos 1.4 <br>
1094 :     <h3><a class="mozTocH3" name="mozTocId753192"></a>5.3 Lazy creation
1095 : sxenos 1.1 should happen as late as possible<br>
1096 : sxenos 1.4 </h3>
1097 : sxenos 1.1 Part implementations should be created at the latest possible moment.
1098 :     The workbench's internal state should be restored as much as possible
1099 :     before the first object is created from an extension point. Parts
1100 :     should not be materialized until they are needed.<br>
1101 : sxenos 1.4 <br>
1102 :     <h3><a class="mozTocH3" name="mozTocId921869"></a>5.4 getters should
1103 : sxenos 1.1 not modify the thing they are supposed to measure<br>
1104 : sxenos 1.4 </h3>
1105 : sxenos 1.1 This applies to any situation where there is a getter and an associated
1106 :     listener that monitors changes in the getter's value. The getter should
1107 :     never cause such a property change to be fired while computing its
1108 :     return value.<br>
1109 :     <br>
1110 :     For example, IWorkbenchPage.getActivePart() should never create the
1111 :     active part. Unless the active part already exists and a property
1112 :     change was fired to all IPartListeners, getActivePart must return null.<br>
1113 :     <br>
1114 :     <br>
1115 :     </body>
1116 :     </html>