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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.3, Thu Jul 14 21:11:49 2005 UTC revision 1.4, Fri Jul 15 04:16:54 2005 UTC
# Line 1  Line 1 
1  <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">  <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2  <html>  <html>
3  <head>  <head>
4    <meta content="text/html; charset=ISO-8859-1"    <meta http-equiv="Content-Type"
5   http-equiv="content-type">   content="text/html; charset=windows-1252">
6    <title>Inside the Workbench: A guide to the workbench internals</title>    <title>Inside the Workbench: A guide to the workbench internals</title>
7      <link rel="stylesheet" href="default_style.css">
8  </head>  </head>
9  <body>  <body link="#0000ff" vlink="#800080">
10  <div style="text-align: center;">  <div align="right">&nbsp; <font face="Times New Roman, Times, serif"
11  <div style="text-align: left;">   size="2">Copyright &copy; 2005 International Business Machines Corp.</font>
12  <table border="0" cellpadding="2" cellspacing="5" width="100%">  <table border="0" cellpadding="2" cellspacing="0" width="100%">
13    <tbody>    <tbody>
14      <tr>      <tr>
15        <td colspan="2" align="left" bgcolor="#0080c0" valign="top"><b><font        <td colspan="2" align="left" bgcolor="#0080c0" valign="top"><b><font
16   color="#ffffff" face="Arial,Helvetica"> Platform UI Design Document<br>   face="Arial,Helvetica"><font color="#ffffff">&nbsp;Eclipse Corner
17        </font></b></td>  Article</font></font></b></td>
18      </tr>      </tr>
19    </tbody>    </tbody>
20  </table>  </table>
21  </div>  </div>
22  <span style="font-weight: bold;"><font size="+2"><span  <div align="left">
23   style="font-weight: bold;"><font size="+3"><br>  <h1><a class="mozTocH1" name="mozTocId282580"></a><img
24  Inside the   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  Workbench<br>  Workbench<br>
30  A guide to the workbench internals<br>  A guide to the workbench internals<br>
31    </h1>
32    <blockquote>
33      <b>Summary</b>
34  <br>  <br>
35  </font></span></font></span></div>  This document describes how the Eclipse 3.1 workbench works. It
36  <br>  describes the infrastructure that makes views and editors work. The
 <div style="margin-left: 40px;"><span style="font-weight: bold;">Summary<br>  
 </span>This document describes how the Eclipse 3.1 workbench works. In  
 particular, it  
 describes the internal classes that manage views and editors. The  
37  goal is to make the reader familiar with important classes in the  goal is to make the reader familiar with important classes in the
38  workbench, and how they interact. It is assumed that the reader is  workbench, and how they interact. It is assumed that the reader is
39  already familiar with using the workbench APIs and with creating views,  already familiar with using the workbench APIs and with creating views,
40  editors, action sets, etc. <br>  editors, action sets, etc.
41  <br>    <p><b>Stefan Xenos, IBM</b> <br>
42  <span style="font-weight: bold;">Stefan Xenos, IBM</span><br>    <font size="-1">July 12, 2005</font> </p>
43  July 12, 2005<br>  </blockquote>
 <br>  
 </div>  
44  <br>  <br>
45  <hr style="width: 100%; height: 2px;">  <hr style="width: 100%; height: 2px;">
46  <h1><a class="mozTocH1" name="mozTocId932753"></a>Table of Contents</h1>  <h1><a class="mozTocH1" name="mozTocId744856"></a>Table of Contents</h1>
47  <ul id="mozToc">  <ul id="mozToc">
48  <!--mozToc h1 1 h2 2 h3 3 h4 4 h5 5 h6 6--><li><a href="#mozTocId932753">Table  <!--mozToc h2 1 h3 2 h4 3 h5 4 h6 5--><li><a href="#mozTocId917303">1.0
49  of Contents</a></li>  Introduction
50    <li><a href="#mozTocId777378">1.0 Introduction </a></li>      </a></li>
51    <li><a href="#mozTocId611837">2.0 Inside a part </a>    <li><a href="#mozTocId270357">2.0 Inside a part
52        </a>
53      <ul>      <ul>
54        <li><a href="#mozTocId683987">2.1 Part Lifecycle </a></li>        <li><a href="#mozTocId713423">2.1 Part Lifecycle
55        <li><a href="#mozTocId623821">2.2 Part Construction</a></li>          </a></li>
56          <li><a href="#mozTocId789670">2.2 Part Construction</a></li>
57      </ul>      </ul>
58    </li>    </li>
59    <li><a href="#mozTocId304467">3.0 Workbench Layout </a>    <li><a href="#mozTocId409413">3.0 Workbench Layout
60        </a>
61      <ul>      <ul>
62        <li><a href="#mozTocId913623">3.1 An example layout</a></li>        <li><a href="#mozTocId95893">3.1 An example layout</a></li>
63        <li><a href="#mozTocId994793">3.2 Zoom / Unzoom protocol </a></li>        <li><a href="#mozTocId114962">3.2 Zoom / Unzoom
64        <li><a href="#mozTocId364295">3.3 Layout protocol </a></li>  protocol
65        <li><a href="#mozTocId867109">3.4 PartStack: Communicating with          </a></li>
66  the Presentation API </a></li>        <li><a href="#mozTocId977378">3.3 Layout protocol
67        <li><a href="#mozTocId854140">3.5 PartSashContainer: The main          </a></li>
68  workbench layout </a></li>        <li><a href="#mozTocId162591">3.4 PartStack:
69        <li><a href="#mozTocId370659">3.6 Drag / Drop</a></li>  Communicating with the Presentation API
70            </a></li>
71          <li><a href="#mozTocId479574">3.5
72    PartSashContainer: The main workbench layout </a></li>
73          <li><a href="#mozTocId887241">3.6 Drag / Drop</a></li>
74      </ul>      </ul>
75    </li>    </li>
76    <li><a href="#mozTocId438049">3.0 Action Bars</a>    <li><a href="#mozTocId443855">3.0 Action Bars</a>
77      <ul>      <ul>
78        <li><a href="#mozTocId808539">3.1 Editor Action Bars </a></li>        <li><a href="#mozTocId652269">3.1 Editor Action Bars
79        <li><a href="#mozTocId809219">3.2 Action Sets </a></li>          </a></li>
80        <li><a href="#mozTocId846891">3.3 View Actions</a></li>        <li><a href="#mozTocId340925">3.2 Action Sets
81            </a></li>
82          <li><a href="#mozTocId277128">3.3 View Actions</a></li>
83      </ul>      </ul>
84    </li>    </li>
85    <li><a href="#mozTocId453994">4.0 General Conventions</a>    <li><a href="#mozTocId642161">4.0 General
86    Conventions</a>
87      <ul>      <ul>
88        <li><a href="#mozTocId451497">4.1 Objects must not be returned        <li><a href="#mozTocId892615">4.1 Objects must not
89  through API until they are fully initialized</a></li>  be returned through API until they are fully initialized</a></li>
90        <li><a href="#mozTocId959546">4.2 No method may open a modal        <li><a href="#mozTocId308622">4.2 No method may
91  dialog unless its JavaDoc says so</a></li>  open a modal dialog unless its JavaDoc says so</a></li>
92        <li><a href="#mozTocId877708">4.3 Lazy creation should happen as        <li><a href="#mozTocId753192">4.3 Lazy creation
93  late as possible</a></li>  should happen as late as possible
94        <li><a href="#mozTocId758931">4.4 getters should not modify the          </a></li>
95  thing they are supposed to measure</a></li>        <li><a href="#mozTocId921869">4.4 getters should
96    not modify the thing they are supposed to measure
97            </a></li>
98      </ul>      </ul>
99    </li>    </li>
100  </ul>  </ul>
101    <br>
102  <div style="margin-left: 40px;"><span style="font-weight: bold;"></span></div>  <div style="margin-left: 40px;"><span style="font-weight: bold;"></span></div>
103  <h1><a class="mozTocH1" name="mozTocId777378"></a><span  <h2><a class="mozTocH2" name="mozTocId917303"></a><span
104   style="font-weight: bold;"></span><span style="font-weight: bold;">1.0   style="font-weight: bold;"></span><span style="font-weight: bold;">1.0
105  Introduction</span>  Introduction</span>
106  <br>  <br>
107  </h1>  </h2>
108  <span style="font-weight: bold;"></span> This document describes  <span style="font-weight: bold;"></span> This document describes
109  workbench internals and not API. The design of internals changes  workbench internals and not API. The design of internals changes
110  frequently. For information on newer Eclipse versions, the latest  frequently. For information on newer Eclipse versions, the latest
# Line 99  Line 114 
114  <br>  <br>
115  <br>  <br>
116  <div style="text-align: center;"><span style="font-weight: bold;">Figure  <div style="text-align: center;"><span style="font-weight: bold;">Figure
117  1.0.1: Ownership of views and editors<br>  1: Ownership of views and editors<br>
118  <br>  <br>
119  </span></div>  </span></div>
120  <div style="text-align: center;"><img alt=""  <div style="text-align: center;"><img alt=""
121   src="workbench_high_level.PNG" style="width: 600px; height: 340px;"><br>   src="workbench_high_level.PNG" style="width: 600px; height: 340px;"><br>
122  </div>  </div>
123  <br>  <br>
124  Figure 1.0.1 shows how views and editors are owned by the workbench.<br>  Figure 1 shows how views and editors are owned by the workbench.<br>
125  <br>  <br>
126  The Workbench contains one or more WorkbenchWindows, each of which  The Workbench contains one or more WorkbenchWindows, each of which
127  contain zero or more WorkbenchPages. The WorkbenchWindow supplies the  contain zero or more WorkbenchPages. The WorkbenchWindow supplies the
# Line 123  Line 138 
138  classes specifically. In situations where the distinction between  classes specifically. In situations where the distinction between
139  editors and views is not important, we will simply use the term "part".  editors and views is not important, we will simply use the term "part".
140  The implementation of the part (typically an IEditorPart or IViewPart)  The implementation of the part (typically an IEditorPart or IViewPart)
141  is created lazily when it is first needed. As shown in figure 1.0.2, a  is created lazily when it is first needed. As shown in Figure 2, a
142  part reference exists for every tab but the implementation is only  part reference exists for every tab but the implementation is only
143  created the first time it becomes visible.<br>  created the first time it becomes visible.<br>
144  <br>  <br>
# Line 141  Line 156 
156  <br>  <br>
157  <br>  <br>
158  <div style="text-align: center;"><span style="font-weight: bold;">Figure  <div style="text-align: center;"><span style="font-weight: bold;">Figure
159  1.0.2: Workbench objects and what they look like<br>  2: Workbench objects and what they look like<br>
160  <br>  <br>
161  </span></div>  </span></div>
162  <div style="text-align: center;"><img alt="" src="what_you_see.PNG"  <div style="text-align: center;"><img alt="" src="what_you_see.PNG"
163   style="width: 892px; height: 700px;"><br>   style="width: 892px; height: 700px;"><br>
164  </div>  </div>
165  <br>  <br>
166  <h1><a class="mozTocH2" name="mozTocId611837"></a>2.0 Inside a part<br>  <h2><a class="mozTocH2" name="mozTocId270357"></a>2.0 Inside a part<br>
167  </h1>  </h2>
168  <div style="text-align: center;"><span style="font-weight: bold;">  <div style="text-align: center;"><span style="font-weight: bold;">
169  Figure 2.0.1: Anatomy of a part</span><br>  Figure 3: Anatomy of a part</span><br>
170  </div>  </div>
171  <div style="text-align: center;"><img alt="" src="anatomy_of_a_part.PNG"  <div style="text-align: center;"><img alt="" src="anatomy_of_a_part.PNG"
172   style="width: 420px; height: 280px;"><br>   style="width: 420px; height: 280px;"><br>
173  </div>  </div>
174  Internally, a part consists of several objects (figure 2.0.1).  Internally, a part consists of several objects (Figure 3).
175  WorkbenchPartReference is the topmost representation of the part.  WorkbenchPartReference is the topmost representation of the part.
176  Depending on where it is used, the part reference is often exposed as  Depending on where it is used, the part reference is often exposed as
177  IWorkbenchPartReference, IViewReference, IEditorRefenece, or  IWorkbenchPartReference, IViewReference, IEditorRefenece, or
# Line 190  Line 205 
205  clients to track the lifecycle of the reference, they are permitted to  clients to track the lifecycle of the reference, they are permitted to
206  continue using its public interface after disposal.<br>  continue using its public interface after disposal.<br>
207  <br>  <br>
208  <h2><a class="mozTocH3" name="mozTocId683987"></a>2.1 Part Lifecycle<br>  <h3><a class="mozTocH3" name="mozTocId713423"></a>2.1 Part Lifecycle<br>
209  </h2>  </h3>
210  <div style="text-align: center;"><span style="font-weight: bold;">Figure  <div style="text-align: center;"><span style="font-weight: bold;">Figure
211  2.1.1: WorkbenchPartReference states<br>  4: WorkbenchPartReference states<br>
212  <br>  <br>
213  </span></div>  </span></div>
214  <div style="text-align: center;"><img alt="" src="part_states.PNG"  <div style="text-align: center;"><img alt="" src="part_states.PNG"
215   style="width: 445px; height: 590px;"><br>   style="width: 445px; height: 590px;"><br>
216  </div>  </div>
217  Figure 2.1.1 shows the part lifecycle as a state machine. The part  Figure 4 shows the part lifecycle as a state machine. The part
218  reference stores its current state in the integer state field.<br>  reference stores its current state in the integer state field.<br>
219  <br>  <br>
220  Notes:<br>  Notes:<br>
# Line 217  Line 232 
232  reference cannot be passed to methods in workbench page (since it is,  reference cannot be passed to methods in workbench page (since it is,
233  by definition, no longer part of any page).</li>  by definition, no longer part of any page).</li>
234  </ul>  </ul>
235  <h2><a class="mozTocH3" name="mozTocId623821"></a>2.2 Part Construction</h2>  <h3><a class="mozTocH3" name="mozTocId789670"></a>2.2 Part Construction</h3>
236  <div style="text-align: center;"><span style="font-weight: bold;">Figure  <div style="text-align: center;"><span style="font-weight: bold;">Figure
237  2.2.1: Message sequence for creating a part<br>  5: Message sequence for creating a part<br>
238  <br>  <br>
239  </span></div>  </span></div>
240  <div style="text-align: center;"><img alt="" src="part_creation_msc.PNG"  <div style="text-align: center;"><img alt="" src="part_creation_msc.PNG"
241   style="width: 892px; height: 700px;"><br>   style="width: 892px; height: 700px;"><br>
242  </div>  </div>
243  <br>  <br>
244  Figure 2.2.1 shows the process for creating a part. The horizontal  Figure 5 shows the process for creating a part. The horizontal
245  line separates the two phases of creating a part. First the part is  line separates the two phases of creating a part. First the part is
246  added to the layout, and then a real implementation is attached. These  added to the layout, and then a real implementation is attached. These
247  are two distinct operations, and the part can exist as a tab in the  are two distinct operations, and the part can exist as a tab in the
# Line 235  Line 250 
250  skips the details of adding the part to the presentation and creating  skips the details of adding the part to the presentation and creating
251  the part site.<br>  the part site.<br>
252  <br>  <br>
253  Author's note: there are situations where it would be useful to only  Suggestion: there are situations where it would be useful to only
254  add the part to the layout if it can be created successfully (this  add the part to the layout if it can be created successfully (this
255  would be necessary to pass a PartInitException thrown in the  would be necessary to pass a PartInitException thrown in the
256  implementation's init method up through IWorkbenchPage.openEditor). In  implementation's init method up through IWorkbenchPage.openEditor). In
# Line 245  Line 260 
260  client code.<br>  client code.<br>
261  <br>  <br>
262  <span style="font-weight: bold;"></span>  <span style="font-weight: bold;"></span>
263  <h1><a class="mozTocH2" name="mozTocId304467"></a>3.0 Workbench Layout<br>  <h2><a class="mozTocH2" name="mozTocId409413"></a>3.0 Workbench Layout<br>
264  </h1>  </h2>
265  <br>  <br>
266  <div style="text-align: center;"><span style="font-weight: bold;">Figure  <div style="text-align: center;"><span style="font-weight: bold;">Figure
267  3.0.1: LayoutPart hierarchy</span><br>  6: LayoutPart hierarchy</span><br>
268  <img alt="" src="LayoutPart_hierarchy.PNG"  <img alt="" src="LayoutPart_hierarchy.PNG"
269   style="width: 302px; height: 412px;"><br>   style="width: 302px; height: 412px;"><br>
270  </div>  </div>
# Line 279  Line 294 
294  specify constraints about their own size.<br>  specify constraints about their own size.<br>
295    </li>    </li>
296  </ul>  </ul>
297  Figure 3.0.1 shows the LayoutPart hierarchy. Notice the symmetry  Figure 6 shows the LayoutPart hierarchy. Notice the symmetry
298  between the View* classes and the Editor* classes. These classes exist  between the View* classes and the Editor* classes. These classes exist
299  largely for historical reasons, and it should be possible to move all  largely for historical reasons, and it should be possible to move all
300  of the functionality into the Part* base classes or other objects in  of the functionality into the Part* base classes or other objects in
# Line 314  Line 329 
329  perspective.<span style="font-weight: bold;"><br>  perspective.<span style="font-weight: bold;"><br>
330  <br>  <br>
331  </span>  </span>
332  <h2><a class="mozTocH3" name="mozTocId913623"></a>3.1 An example layout</h2>  <h3><a class="mozTocH3" name="mozTocId95893"></a>3.1 An example layout</h3>
333  LayoutParts are best explained through example. Imagine a  LayoutParts are best explained through example. Imagine a
334  WorkbenchWindow that contains custom Java and Java Browsing  WorkbenchWindow that contains custom Java and Java Browsing
335  perspectives that look like figure 3.1.1 and figure 3.1.2  perspectives that look like Figure 7 and Figure 8
336  respectively.<br>  respectively.<br>
337  <br>  <br>
338  <br>  <br>
339  <div style="text-align: center;"><span style="font-weight: bold;">Figure  <div style="text-align: center;"><span style="font-weight: bold;">Figure
340  3.1.1: Example Java Perspective</span><br>  7: Example Java Perspective</span><br>
341  <img alt="" src="perspective1.PNG" style="width: 571px; height: 495px;"><br>  <img alt="" src="perspective1.PNG" style="width: 571px; height: 495px;"><br>
342  <br>  <br>
343  <span style="font-weight: bold;">Figure 3.1.2: Example Java Browsing  <span style="font-weight: bold;">Figure 8: Example Java Browsing
344  perspective</span><br>  perspective</span><br>
345  <img alt="" src="perspective2.PNG" style="width: 571px; height: 495px;"><br>  <img alt="" src="perspective2.PNG" style="width: 571px; height: 495px;"><br>
346  </div>  </div>
347  <br>  <br>
348  Assume that the window resembles Figure 3.1.1. In this case, the Java  <br>
349    Assume that the window resembles Figure 7. In this case, the Java
350  perspective is active, the Java Browsing perspective is hidden, and the  perspective is active, the Java Browsing perspective is hidden, and the
351  objects are connected as shown in figure 3.1.3:<br>  objects are connected as shown in Figure 9:<br>
352    <br>
353  <br>  <br>
354  <div style="text-align: center;"><span style="font-weight: bold;">Figure  <div style="text-align: center;"><span style="font-weight: bold;">Figure
355  3.1.3: LayoutPart instances when two perspectives are open</span><br>  9: LayoutPart instances when two perspectives are open</span><br>
356  <img alt="" src="perspective1_2_instances.PNG"  <img alt="" src="perspective1_2_instances.PNG"
357   style="width: 555px; height: 670px;"><br>   style="width: 555px; height: 670px;"><br>
358  <div style="text-align: left;"><br>  <div style="text-align: left;"><br>
# Line 362  Line 379 
379  similar. Each view's PartPane is owned by a part reference which may  similar. Each view's PartPane is owned by a part reference which may
380  have an associated part implementation.<br>  have an associated part implementation.<br>
381  <br>  <br>
382  <h2><a class="mozTocH3" name="mozTocId994793"></a>3.2 Zoom / Unzoom  <h3><a class="mozTocH3" name="mozTocId114962"></a>3.2 Zoom / Unzoom
383  protocol<br>  protocol<br>
384  </h2>  </h3>
385  The notion of "zoom" is defined locally between a part and its  The notion of "zoom" is defined locally between a part and its
386  immediate container. Zoom changes are triggered bottom-up. A part asks  immediate container. Zoom changes are triggered bottom-up. A part asks
387  its parent to "zoom me", and the parent either does something with the  its parent to "zoom me", and the parent either does something with the
# Line 374  Line 391 
391  may in turn zoom or unzoom one or more of its children.<br>  may in turn zoom or unzoom one or more of its children.<br>
392  <br>  <br>
393  Anything that can contain LayoutParts must implement the following  Anything that can contain LayoutParts must implement the following
394  methods, to support zooming:<span style="font-family: monospace;"><br>  methods, to support zooming:<br>
395  <br>  <span style="font-family: monospace;"><br>
396  </span><code>&nbsp;&nbsp;&nbsp; /**<br>  </span><code>&nbsp;&nbsp;&nbsp; /**<br>
397  &nbsp;&nbsp;&nbsp;&nbsp; * Called by child parts to request a zoom in,  &nbsp;&nbsp;&nbsp;&nbsp; * Called by child parts to request a zoom in,
398  given an immediate child <br>  given an immediate child <br>
# Line 410  Line 427 
427  zooming in on the given part<br>  zooming in on the given part<br>
428  &nbsp;&nbsp;&nbsp;&nbsp; */<br>  &nbsp;&nbsp;&nbsp;&nbsp; */<br>
429  &nbsp;&nbsp;&nbsp; public boolean childIsZoomed(LayoutPart toTest);<br>  &nbsp;&nbsp;&nbsp; public boolean childIsZoomed(LayoutPart toTest);<br>
430    <br>
431  </code><br>  </code><br>
432  Consider again Figure 3.1.1. If we were to double-click on the java  Consider again Figure 7. If we were to double-click on the java
433  editor to zoom it, the LayoutParts would send messages to one another  editor to zoom it, the LayoutParts would send messages to one another
434  in the following sequence. (In this diagram, each cell represents a  in the following sequence. (In this diagram, each cell represents a
435  method call. Each column is an object. The reciever's column shows the  method call. Each column is an object. The reciever's column shows the
# Line 603  Line 621 
621    </tbody>    </tbody>
622  </table>  </table>
623  <br>  <br>
624  <h2><a class="mozTocH3" name="mozTocId364295"></a>3.3 Layout protocol<br>  <h3><a class="mozTocH3" name="mozTocId977378"></a>3.3 Layout protocol<br>
625  </h2>  </h3>
626  Every LayoutPart can specify constraints on their size. Parts specify  Every LayoutPart can specify constraints on their size. Parts specify
627  constraints by implementing the ISizeProvider interface. ISizeProvider  constraints by implementing the ISizeProvider interface. ISizeProvider
628  serves a similar function as the computeSize method on an SWT control,  serves a similar function as the computeSize method on an SWT control,
# Line 664  Line 682 
682  <br>  <br>
683  Whenever a size constraint changes, the part notifies its contianer by  Whenever a size constraint changes, the part notifies its contianer by
684  calling resizeChild(part). This tells the container to respond to the  calling resizeChild(part). This tells the container to respond to the
685  new constraints, and to resize the child if necessary (author's note:  new constraints, and to resize the child if necessary (suggestion:
686  if this is ever exposed as API, it would be better to separate the  if this is ever exposed as API, it would be better to separate the
687  concerns of notifying the parent of changes and triggering a layout. In  concerns of notifying the parent of changes and triggering a layout. In
688  general, it may be possible for more than one part to change without  general, it may be possible for more than one part to change without
689  requiring a layout between each change).<br>  requiring a layout between each change).<br>
690  <br>  <br>
691  <h2><a class="mozTocH3" name="mozTocId867109"></a>3.4 PartStack:  <h3><a class="mozTocH3" name="mozTocId162591"></a>3.4 PartStack:
692  Communicating with the Presentation API<br>  Communicating with the Presentation API<br>
693  </h2>  </h3>
694  PartStack allows presentation to participate in the workbench layout.  PartStack allows presentation to participate in the workbench layout.
695  As shown in Figure 3.4.1, it wraps a single instance of  As shown in Figure 10, it wraps a single instance of
696  StackPresentation, and allows it the presentation to manipulate parts  StackPresentation, and allows it the presentation to manipulate parts
697  by converting each visible part into an IPresentablePart. The part  by converting each visible part into an IPresentablePart. The part
698  stack outlives the StackPresentation. Whenever the part stack needs  stack outlives the StackPresentation. Whenever the part stack needs
# Line 685  Line 703 
703  StackPresentation from state saved by an incompatible presentation.<br>  StackPresentation from state saved by an incompatible presentation.<br>
704  <br>  <br>
705  <div style="text-align: center;"><span style="font-weight: bold;">Figure  <div style="text-align: center;"><span style="font-weight: bold;">Figure
706  3.4.1: Anatomy of PartStack</span><br>  10: Anatomy of PartStack</span><br>
707  <img alt="" src="PartStack.PNG" style="width: 430px; height: 225px;"><br>  <img alt="" src="PartStack.PNG" style="width: 430px; height: 225px;"><br>
708  <div style="text-align: left;"><br>  <div style="text-align: left;"><br>
709  Author's note: it would be useful to update this document with a state  Suggestion: it would be useful to update this document with a state
710  diagram for PartStack, and message sequence charts for initializaiton  diagram for PartStack, and message sequence charts for initializaiton
711  and part activation.<br>  and part activation.<br>
712  <br>  <br>
713  </div>  </div>
714  </div>  </div>
715  <h2><a class="mozTocH3" name="mozTocId854140"></a>3.5  <h3><a class="mozTocH3" name="mozTocId479574"></a>3.5
716  PartSashContainer: The main workbench layout <br>  PartSashContainer: The main workbench layout <br>
717  </h2>  </h3>
718  <div style="text-align: center;"><span style="font-weight: bold;">Figure  <div style="text-align: center;"><span style="font-weight: bold;">Figure
719  3.5.1: PartSashContainer</span><br>  11: PartSashContainer</span><br>
720  <img alt="" src="PartSashContainer.PNG"  <img alt="" src="PartSashContainer.PNG"
721   style="width: 428px; height: 305px;"><br>   style="width: 428px; height: 305px;"><br>
722  </div>  </div>
723  <br>  <br>
724  PartSashContainer implements the main layout for a perspective and the  PartSashContainer implements the main layout for a perspective and the
725  editor area. As shown in figure 3.5.1, PartSashContainer contains a  editor area. As shown in Figure 11, PartSashContainer contains a
726  list of children, a (possibly null) zoomed part, and a LayoutTree that  list of children, a (possibly null) zoomed part, and a LayoutTree that
727  manages the actual layout. <br>  manages the actual layout. <br>
728  <br>  <br>
# Line 729  Line 747 
747  When the sash is moved, the size values are set to the current pixel  When the sash is moved, the size values are set to the current pixel
748  sizes of the left and right children.<br>  sizes of the left and right children.<br>
749  <br>  <br>
750  Figure 3.5.2 shows an example LayoutTree. If this tree were rendered  Figure 12 shows an example LayoutTree. If this tree were rendered
751  in a workbench window, it would resemble Figure 3.5.3. The tall  in a workbench window, it would resemble Figure 3.5.3. The tall
752  vertical sash separating the package explorer from the editor area is  vertical sash separating the package explorer from the editor area is
753  the root node. The left child is the leaf node holding the package  the root node. The left child is the leaf node holding the package
# Line 742  Line 760 
760  has the editor area on one side of it, so all sizes are interpreted as  has the editor area on one side of it, so all sizes are interpreted as
761  pixel sizes and not ratios.<br>  pixel sizes and not ratios.<br>
762  <div style="text-align: center;"><span style="font-weight: bold;"></span><br>  <div style="text-align: center;"><span style="font-weight: bold;"></span><br>
763  <span style="font-weight: bold;">Figure 3.5.2: Example LayoutTree</span><br  <span style="font-weight: bold;">Figure 12: Example LayoutTree</span><br
764   style="font-weight: bold;">   style="font-weight: bold;">
765  <img alt="" src="example_LayoutTree.PNG"  <img alt="" src="example_LayoutTree.PNG"
766   style="width: 480px; height: 462px; font-weight: bold;"><br>   style="width: 480px; height: 462px; font-weight: bold;"><br>
767  <span style="font-weight: bold;"><br>  <span style="font-weight: bold;"><br>
768  Figure 3.5.3: Example perspective</span><br style="font-weight: bold;">  Figure 13: Example perspective</span><br style="font-weight: bold;">
769  <img alt="" src="perspective1.PNG"  <img alt="" src="perspective1.PNG"
770   style="width: 571px; height: 495px; font-weight: bold;"><br>   style="width: 571px; height: 495px; font-weight: bold;"><br>
771  </div>  </div>
# Line 765  Line 783 
783    </li>    </li>
784  </ol>  </ol>
785  An example can help make this a little less abstract. Imagine we're  An example can help make this a little less abstract. Imagine we're
786  computing the minimum width for the root node in figure 3.5.1, which  computing the minimum width for the root node in Figure 12, which
787  is a tall vertical sash. Width measurements are perpendicular to the  is a tall vertical sash. Width measurements are perpendicular to the
788  sash, so we end up with case 1. The minimum width is the minimum width  sash, so we end up with case 1. The minimum width is the minimum width
789  of the left stack plus the sash width plus the minimum width of the  of the left stack plus the sash width plus the minimum width of the
# Line 780  Line 798 
798  child with the larger minimum size will be the first to reach its  child with the larger minimum size will be the first to reach its
799  minimum when the layout gets small.<br>  minimum when the layout gets small.<br>
800  <br>  <br>
801  <h2><a class="mozTocH2" name="mozTocId370659"></a>3.6 Drag / Drop</h2>  <h3><a class="mozTocH3" name="mozTocId887241"></a>3.6 Drag / Drop</h3>
802  <div style="text-align: center;"><span style="font-weight: bold;">Figure  <div style="text-align: center;"><span style="font-weight: bold;">Figure
803  3.6.1: LayoutPart drop regions</span><br>  14: LayoutPart drop regions</span><br>
804  </div>  </div>
805  <div style="text-align: center;"><img alt="" src="drag_regions.PNG"  <div style="text-align: center;"><img alt="" src="drag_regions.PNG"
806   style="width: 571px; height: 495px;"><br>   style="width: 571px; height: 495px;"><br>
# Line 804  Line 822 
822  by the child, or provide default behaviors for drag regions not  by the child, or provide default behaviors for drag regions not
823  recognized by the child.<br>  recognized by the child.<br>
824  <br>  <br>
825  Figure 3.6.1 shows regions of the workbench where LayoutParts can be  Figure 14 shows regions of the workbench where LayoutParts can be
826  dropped. The workbench checks these regions in the following order:<br>  dropped. The workbench checks these regions in the following order:<br>
827  <br>  <br>
828  <table style="width: 100%; text-align: left;" border="1" cellpadding="2"  <table style="width: 100%; text-align: left;" border="1" cellpadding="2"
# Line 874  Line 892 
892  <br>  <br>
893  By convention, all methods used for drag / drop work in display  By convention, all methods used for drag / drop work in display
894  coordinates.<br>  coordinates.<br>
895    <br>
896  </div>  </div>
897  </div>  </div>
898  <h1><a class="mozTocH2" name="mozTocId438049"></a>3.0 Action Bars</h1>  <h2><a class="mozTocH2" name="mozTocId443855"></a>4.0 Action Bars</h2>
899  Parts contribute to menus, toolbars, coolbars, popup menus, etc. using  Parts contribute to menus, toolbars, coolbars, popup menus, etc. using
900  action bars. Each action bar implements IActionBars. It is possible to  action bars. Each action bar implements IActionBars. It is possible to
901  create one action bar as a child of another. In this situation, the  create one action bar as a child of another. In this situation, the
902  parent and child share the same widgets, but the child may be disabled  parent and child share the same widgets, but the child may be disabled
903  independently of the parent. Figure 3.0.1 shows how the workbench  independently of the parent. Figure 15 shows how the workbench
904  action bars are  action bars are
905  constructed. The rectangles indicate instances of IActionBars, and the  constructed. The rectangles indicate instances of IActionBars, and the
906  ovals indicate other entities that create or modify action bars.<br>  ovals indicate other entities that create or modify action bars.<br>
907  <br>  <br>
908  <div style="text-align: center;"><span style="font-weight: bold;">Figure  <div style="text-align: center;"><span style="font-weight: bold;">Figure
909  3.0.1: Action bar information flow</span><br>  15: Action bar information flow</span><br>
910  <img alt="" src="action_bar_flow.PNG"  <img alt="" src="action_bar_flow.PNG"
911   style="width: 800px; height: 600px;"><br>   style="width: 800px; height: 600px;"><br>
912  <div style="text-align: left;"><p:colorscheme  <div style="text-align: left;"><p:colorscheme
# Line 910  Line 929 
929  contributes to the main menubar, coolbar, etc. (this top-level object  contributes to the main menubar, coolbar, etc. (this top-level object
930  is returned by WorkbenchWindow.getActionBars()).<br>  is returned by WorkbenchWindow.getActionBars()).<br>
931  <br>  <br>
932  <h2><a class="mozTocH3" name="mozTocId808539"></a>3.1 Editor Action Bars<br>  <h3><a class="mozTocH3" name="mozTocId652269"></a>4.1 Editor Action Bars<br>
933  </h2>  </h3>
934  Each type of editor gets a reference-counted IActionBars instance that  Each type of editor gets a reference-counted IActionBars instance that
935  is a child of the window's action bars. For  is a child of the window's action bars. For
936  example, if the workbench contains 10 java editors and 10 text editors,  example, if the workbench contains 10 java editors and 10 text editors,
# Line 926  Line 945 
945  The reference counted IEditorActionBars are managed by the  The reference counted IEditorActionBars are managed by the
946  EditorManager, along with the IActionBarContributor.<br>  EditorManager, along with the IActionBarContributor.<br>
947  <br>  <br>
948  <h2><a class="mozTocH3" name="mozTocId809219"></a>3.2 Action Sets<br>  <h3><a class="mozTocH3" name="mozTocId340925"></a>4.2 Action Sets<br>
949  </h2>  </h3>
950  An action set is an action bar that is identified by ID. Action sets  An action set is an action bar that is identified by ID. Action sets
951  are contributed by the actionSets extension point, and their action  are contributed by the actionSets extension point, and their action
952  bars are a child of the workbench window's root action bars. Visibility  bars are a child of the workbench window's root action bars. Visibility
# Line 968  Line 987 
987  The action set is visible iff showCount is nonzero and hideCount is  The action set is visible iff showCount is nonzero and hideCount is
988  zero.<br>  zero.<br>
989  <br>  <br>
990  <h2><a class="mozTocH3" name="mozTocId846891"></a>3.3 View Actions</h2>  <h3><a class="mozTocH3" name="mozTocId277128"></a>4.3 View Actions</h3>
991  Each view instance is given its own IActionBars instance. Unlike editor  Each view instance is given its own IActionBars instance. Unlike editor
992  action bars, these are not shared and are not a child of the workbench  action bars, these are not shared and are not a child of the workbench
993  window's root action bars. This means that view instances can  window's root action bars. This means that view instances can
# Line 976  Line 995 
995  are also added to a view's action bars through the viewActions  are also added to a view's action bars through the viewActions
996  extension point.<br>  extension point.<br>
997  <br>  <br>
998  <h1><a class="mozTocH1" name="mozTocId453994"></a>4.0 General  <h2><a class="mozTocH2" name="mozTocId642161"></a>5.0 General
999  Conventions</h1>  Conventions</h2>
1000  This section describes coding conventions that apply to the entire  This section describes coding conventions that apply to the entire
1001  workbench.<br>  workbench.<br>
1002  <h2><a class="mozTocH3" name="mozTocId451497"></a>4.1 Objects must not  <br>
1003  be returned through API until they are fully initialized</h2>  <h3><a class="mozTocH3" name="mozTocId892615"></a>5.1 Objects must not
1004    be returned through API until they are fully initialized</h3>
1005  Some objects require several public methods to be called in a specific  Some objects require several public methods to be called in a specific
1006  order before they are considered fully initialized. For example, to  order before they are considered fully initialized. For example, to
1007  initialize an IViewPart, it is necessary to call the constructor,  initialize an IViewPart, it is necessary to call the constructor,
# Line 994  Line 1014 
1014  own  own
1015  initialization, so it should not even be possible for an object to find  initialization, so it should not even be possible for an object to find
1016  itself during construction.<br>  itself during construction.<br>
1017  <h2><a class="mozTocH3" name="mozTocId959546"></a>4.2 No method may  <br>
1018  open a modal dialog unless its JavaDoc says so</h2>  <h3><a class="mozTocH3" name="mozTocId308622"></a>5.2 No method may
1019    open a modal dialog unless its JavaDoc says so</h3>
1020  Any method that has the possibility of opening a modal (or of calling  Any method that has the possibility of opening a modal (or of calling
1021  Display.readAndDispatch through any other means) needs to be clearly  Display.readAndDispatch through any other means) needs to be clearly
1022  documented. All callers of that method must be prepared to handle  documented. All callers of that method must be prepared to handle
# Line 1014  Line 1035 
1035  opens dialogs, it might not still exist when the method returns. After  opens dialogs, it might not still exist when the method returns. After
1036  calling the method, the part must check that it hasn't been disposed  calling the method, the part must check that it hasn't been disposed
1037  before using their widgets or accessing any members that would have  before using their widgets or accessing any members that would have
1038  been deallocated by the disposal.<br>  been deallocated by the disposal.</li>
   </li>  
1039  </ul>  </ul>
1040  <h2><a class="mozTocH3" name="mozTocId877708"></a>4.3 Lazy creation  <br>
1041    <h3><a class="mozTocH3" name="mozTocId753192"></a>5.3 Lazy creation
1042  should happen as late as possible<br>  should happen as late as possible<br>
1043  </h2>  </h3>
1044  Part implementations should be created at the latest possible moment.  Part implementations should be created at the latest possible moment.
1045  The workbench's internal state should be restored as much as possible  The workbench's internal state should be restored as much as possible
1046  before the first object is created from an extension point. Parts  before the first object is created from an extension point. Parts
1047  should not be materialized until they are needed.<br>  should not be materialized until they are needed.<br>
1048  <h2><a class="mozTocH3" name="mozTocId758931"></a>4.4 getters should  <br>
1049    <h3><a class="mozTocH3" name="mozTocId921869"></a>5.4 getters should
1050  not modify the thing they are supposed to measure<br>  not modify the thing they are supposed to measure<br>
1051  </h2>  </h3>
1052  This applies to any situation where there is a getter and an associated  This applies to any situation where there is a getter and an associated
1053  listener that monitors changes in the getter's value. The getter should  listener that monitors changes in the getter's value. The getter should
1054  never cause such a property change to be fired while computing its  never cause such a property change to be fired while computing its
Legend:
Removed from v.1.3  
changed lines
  Added in v.1.4