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

Parent Directory | Revision Log | Patch

-revision 1.5, Fri Jul 15 05:19:10 2005 UTC
+revision 1.6, Fri Jan  6 21:56:04 2006 UTC
 Line 30
  A guide to the workbench internals<br>
  </h1>
  <blockquote> <b>Summary</b> <br>
- This document describes how the Eclipse 3.1 workbench works. It
+ This article describes how the Eclipse 3.1 workbench works, in
- describes the infrastructure that makes views and editors work. The
+ particular the infrastructure for views and editors. The goal is to
- goal is to make the reader familiar with important classes in the
+ teach you about important classes in the workbench, and how they
- workbench, and how they interact. It is assumed that the reader is
+ interact. A familiarity with the basic workbench APIs for views,
- already familiar with using the workbench APIs and with creating views,
+ editors, action sets, and so forth is assumed.
- editors, action sets, etc.
    <p><b>Stefan Xenos, IBM</b> <br>
-   <font size="-1">July 12, 2005</font> </p>
+   <font size="-1">January 6, 2006</font> </p>
  </blockquote>
  <br>
  <hr style="width: 100%; height: 2px;">
  <h1><a class="mozTocH1" name="mozTocId744856"></a>Table of Contents</h1>
  <ul id="mozToc">
  <!--mozToc h2 1 h3 2 h4 3 h5 4 h6 5--><li><a href="#mozTocId917303">1.0
- Introduction
+ Introduction </a></li>
-     </a></li>
+   <li><a href="#mozTocId270357">2.0 Inside a part </a>
-   <li><a href="#mozTocId270357">2.0 Inside a part
-     </a>
      <ul>
-       <li><a href="#mozTocId713423">2.1 Part Lifecycle
+       <li><a href="#mozTocId713423">2.1 Part Lifecycle </a></li>
-         </a></li>
        <li><a href="#mozTocId789670">2.2 Part Construction</a></li>
      </ul>
    </li>
-   <li><a href="#mozTocId409413">3.0 Workbench Layout
+   <li><a href="#mozTocId409413">3.0 Workbench Layout </a>
-     </a>
      <ul>
        <li><a href="#mozTocId95893">3.1 An example layout</a></li>
        <li><a href="#mozTocId114962">3.2 Zoom / Unzoom
- protocol
+ protocol </a></li>
-         </a></li>
+       <li><a href="#mozTocId977378">3.3 Layout protocol </a></li>
-       <li><a href="#mozTocId977378">3.3 Layout protocol
-         </a></li>
        <li><a href="#mozTocId162591">3.4 PartStack:
- Communicating with the Presentation API
+ Communicating with the Presentation API </a></li>
-         </a></li>
        <li><a href="#mozTocId479574">3.5
  PartSashContainer: The main workbench layout </a></li>
        <li><a href="#mozTocId887241">3.6 Drag / Drop</a></li>
-Line 73
+Line 65
    </li>
    <li><a href="#mozTocId443855">4.0 Action Bars</a>
      <ul>
-       <li><a href="#mozTocId652269">4.1 Editor Action Bars
+       <li><a href="#mozTocId652269">4.1 Editor Action Bars </a></li>
-         </a></li>
+       <li><a href="#mozTocId340925">4.2 Action Sets </a></li>
-       <li><a href="#mozTocId340925">4.2 Action Sets
-         </a></li>
        <li><a href="#mozTocId277128">4.3 View Actions</a></li>
      </ul>
    </li>
-Line 88
+Line 78
        <li><a href="#mozTocId308622">5.2 No method may
  open a modal dialog unless its JavaDoc says so</a></li>
        <li><a href="#mozTocId753192">5.3 Lazy creation
- should happen as late as possible
+ should happen as late as possible </a></li>
-         </a></li>
        <li><a href="#mozTocId921869">5.4 getters should
- not modify the thing they are supposed to measure
+ not modify the thing they are supposed to measure </a></li>
-         </a></li>
      </ul>
    </li>
  </ul>
-Line 119
+Line 107
   src="workbench_high_level.PNG" style="width: 600px; height: 340px;"><br>
  </div>
  <br>
- Figure 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>
  <br>
  The Workbench contains one or more WorkbenchWindows, each of which
  contain zero or more WorkbenchPages. The WorkbenchWindow supplies the
- trim widgets, and the WorkbenchPage supplies the window
+ trim widgets, and the WorkbenchPage supplies the window contents. In
- contents. In theory, a WorkbenchWindow can contain any number of pages,
+ theory, a WorkbenchWindow can contain any number of pages, but in
- but in practice there is never more than 1 page in a window.<br>
+ practice there is never more than 1 page in a window.
+ <br>
  <br>
  Views and editors are owned by the page, through a ViewFactory and
  EditorManager respectively. EditorManager stores the list of editors
- and their shared
+ and
- resources, and ViewFactory stores a reference counted list of views.
+ their shared resources, and ViewFactory stores a reference counted list
- The workbench works in terms of EditorReferences and ViewReferences,
+ of views. The workbench works in terms of EditorReferences and
- and in this article the terms "editor" or "view" will refer to these
+ ViewReferences, and in this article the terms "editor" or "view" will
- classes specifically. In situations where the distinction between
+ refer to these classes specifically. In situations where the
- editors and views is not important, we will simply use the term "part".
+ distinction
- The implementation of the part (typically an IEditorPart or IViewPart)
+ between editors and views is not important, we will simply use the term
- is created lazily when it is first needed. As shown in Figure 2, a
+ "part". The implementation of the part (typically an IEditorPart or
- part reference exists for every tab but the implementation is only
+ IViewPart) is created lazily when it is first needed. As shown in
- created the first time it becomes visible.<br>
+ Figure
+, a part reference exists for every tab but the implementation is only
+ created the first time it becomes visible.
+ <br>
  <br>
  The page owns a set of perspectives. Perspectives contain a layout and
  information about what action sets to enable. Although perspectives
  appear to contain views and the editor area, they only own a layout.
- The page itself maintains a reference count for how many perspectives
+ The
- are using each view, and has complete ownership of the parts and editor
+ page itself maintains a reference count for how many perspectives are
- area.<br>
+ using each view, and has complete ownership of the parts and editor
+ area.
+ <br>
  <br>
  Not shown in figure 1 are the classes PerspectiveHelper and
  EditorAreaHelper. These classes exist largely for historic purposes,
- and in this article we will treat the former as though it were part of
+ and
- the Perspective class and the latter as part of the WorkbenchPage class.<br>
+ in this article we will treat the former as though it were part of the
+ Perspective class and the latter as part of the WorkbenchPage class.
+ <br>
  <br>
  <br>
  <div style="text-align: center;"><span style="font-weight: bold;">Figure
-Line 177
+Line 174
  interfaces to the same object. The I*Reference interfaces are
  implemented directly by WorkbenchPartReference and its subclasses.
  IPresentablePart is a simple adapter that redirects its methods
- directly to the part. PartPane implements the LayoutPart protocol which
+ directly
- is needed to insert the part into the workbench layout. PartPane also
+ to the part. PartPane implements the LayoutPart protocol which is
- manages the SWT resources (such as a top-level control) that are needed
+ needed
- to include the control in the workbench layout.<br>
+ to insert the part into the workbench layout. PartPane also manages the
+ SWT resources (such as a top-level control) that are needed to include
+ the control in the workbench layout.
+ <br>
  <br>
  The part implementation (the IEditorPart or IViewPart) is owned by the
- reference. When the
+ reference. When the implementation is created, it is given a PartSite.
- implementation is created, it is given a PartSite. The PartSite (seen
+ The PartSite (seen by client code as an IWorkbenchPartSite,
- by client code as an IWorkbenchPartSite, IEditorSite, or IViewSite)
+ IEditorSite,
- allows the client code to communicate with the reference and manages
+ or IViewSite) allows the client code to communicate with the reference
- services created for the implementation.<br>
+ and manages services created for the implementation.
  <br>
- WorkbenchPartReferences allocates SWT resources lazily as needed.
+ <br>
- Once created, the part reference must be explicitly disposed. Disposing
+ WorkbenchPartReferences allocates SWT resources lazily as needed. Once
- the reference cleans up all of its resources (including the part
+ created, the part reference must be explicitly disposed. Disposing the
+ reference cleans up all of its resources (including the part
  implementation itself) and guarantees that the reference will never
  allocate additional resources. The workbench page disposes the part
  reference once it is certain that it will never need to use that part
  again. Unlike SWT controls, it is valid to continue using the reference
  after it has been disposed. A disposed part reference is unlikely to do
  anything interesting besides returning its name and cannot be used with
- any
+ any methods in the workbench page. Since it is hard (or impossible) for
- methods in the workbench page. Since it is hard (or impossible) for
  clients to track the lifecycle of the reference, they are permitted to
- continue using its public interface after disposal.<br>
+ continue using its public interface after disposal.
+ <br>
  <br>
  <h3><a class="mozTocH3" name="mozTocId713423"></a>2.1 Part Lifecycle<br>
  </h3>
-Line 213
+Line 214
   style="width: 445px; height: 590px;"><br>
  </div>
  Figure 4 shows the part lifecycle as a state machine. The part
- reference stores its current state in the integer state field.<br>
+ reference
+ stores its current state in the integer state field.
+ <br>
+ <br>
+ Notes:
  <br>
- Notes:<br>
  <ul>
    <li>The part is in a distinct state while it is in the process of
  creating the implementation. It cannot be recursively re-created or
-Line 239
+Line 243
   style="width: 892px; height: 700px;"><br>
  </div>
  <br>
- Figure 5 shows the process for creating a part. The horizontal
+ Figure 5 shows the process for creating a part. The horizontal line
- line separates the two phases of creating a part. First the part is
+ separates the two phases of creating a part. First the part is added to
- added to the layout, and then a real implementation is attached. These
+ the layout, and then a real implementation is attached. These are two
- are two distinct operations, and the part can exist as a tab in the
+ distinct operations, and the part can exist as a tab in the page with
- page with no implementation for some time before it becomes visible.
+ no
- This diagram focuses on the interactions with the part reference, and
+ implementation for some time before it becomes visible. This diagram
- skips the details of adding the part to the presentation and creating
+ focuses on the interactions with the part reference, and skips the
- the part site.<br>
+ details of adding the part to the presentation and creating the part
- <br>
+ site.
- Suggestion: there are situations where it would be useful to only
+ <br>
- add the part to the layout if it can be created successfully (this
+ <br>
- would be necessary to pass a PartInitException thrown in the
+ Suggestion: there are situations where it would be useful to only add
- implementation's init method up through IWorkbenchPage.openEditor). In
+ the part to the layout if it can be created successfully (this would be
- these situations, it would be possible to merge both operations into
+ necessary to pass a PartInitException thrown in the implementation's
- one atomic operation by creating the part before adding it to the
+ init method up through IWorkbenchPage.openEditor). In these situations,
- layout. It is unknown if this would create event ordering bugs in
+ it would be possible to merge both operations into one atomic operation
- client code.<br>
+ by creating the part before adding it to the layout. It is unknown if
+ this would create event ordering bugs in client code.
+ <br>
  <br>
  <span style="font-weight: bold;"></span>
  <h2><a class="mozTocH2" name="mozTocId409413"></a>3.0 Workbench Layout<br>
-Line 269
+Line 275
  <br>
  The workbench layout provides supports arranging parts using drag &amp;
  drop, resizing and detaching parts, fast views, etc. This section gives
- a quick overview of the layout mechanism.<br>
+ a quick overview of the layout mechanism.
+ <br>
  <br>
  Anything in the workbench layout is a LayoutPart. A LayoutPart manages
- a set of widgets in a rectangular region of the screen, can contain or
+ a
+ set of widgets in a rectangular region of the screen, can contain or
  arrange other layout parts, returns size constraints, responds to drag
  events, etc. To this extent, a LayoutPart is very similar to a custom
  SWT Control. However, LayoutPart differs from Control in several
- important ways.<br>
+ important ways.
+ <br>
  <ul>
    <li>The LayoutPart hierarchy is not the same as the widget hierarchy.
  Even though one LayoutPart may contain another, their widgets may be
-Line 292
+Line 301
  specify constraints about their own size.<br>
    </li>
  </ul>
- Figure 6 shows the LayoutPart hierarchy. Notice the symmetry
+ Figure 6 shows the LayoutPart hierarchy. Notice the symmetry between
- between the View* classes and the Editor* classes. These classes exist
+ the
- largely for historical reasons, and it should be possible to move all
+ View* classes and the Editor* classes. These classes exist largely for
- of the functionality into the Part* base classes or other objects in
+ historical reasons, and it should be possible to move all of the
- the system. Since all of the interesting behavior comes from the Part*
+ functionality into the Part* base classes or other objects in the
+ system. Since all of the interesting behavior comes from the Part*
  classes, the remainder of this section will focus on them without
- describing the minor differences between views and editors.<br>
+ describing the minor differences between views and editors.
+ <br>
  <br>
- PartSashContainer arranges a set of child parts separated by a bunch of
+ PartSashContainer provides the splitting behavior in the workbench
- sashes. This is the object that implements the most visible aspects of
+ window. It arranges rectangular regions separated by
- the workbench layout. It arranges rectangular regions separated by
  sashes, and allows new regions to be created by splitting old ones. It
  also supports the size constraints that make minimized views possible,
  and determines what it means for one of these regions to be maximized.
-Line 310
+Line 320
  it is also possible for it to contain another PartSashContainer. The
  latter case occurs since the editor area and the perspective both use a
  PartSashContainer for their layout and one is embedded inside the
- other. PartSashContainer owns its stacks but does not own an embedded
+ other.
+ PartSashContainer owns its stacks but does not own an embedded
  PartSashContainer. In a workbench window, there is one
- PartSashContainer for each perspective and one for the editor area
+ PartSashContainer
- itself.<br>
+ for each perspective and one for the editor area itself.
+ <br>
  <br>
  PartStack arranges a stack of PartPanes. PartStack allows the
  presentation API to participate in the workbench layout. The code for
  creating the tabs and arranging parts is supplied by the active
- presentation.<br>
+ presentation.
+ <br>
  <br>
  PartPane allows views and editors to participate in the workbench
  layout. Although PartPanes are arranged by PartStacks they belong to
  part reference, not the stack. The same PartPane can exist in more than
  one PartStack at a time if that part appears in more that one
- perspective.<span style="font-weight: bold;"><br>
+ perspective.
+ <span style="font-weight: bold;"><br>
  <br>
  </span>
  <h3><a class="mozTocH3" name="mozTocId95893"></a>3.1 An example layout</h3>
  LayoutParts are best explained through example. Imagine a
  WorkbenchWindow that contains custom Java and Java Browsing
- perspectives that look like Figure 7 and Figure 8
+ perspectives
- respectively.<br>
+ that look like Figure 7 and Figure 8 respectively.
+ <br>
  <br>
  <br>
  <div style="text-align: center;"><span style="font-weight: bold;">Figure
-Line 360
+Line 375
  <br>
  All LayoutParts have a container pointer that points to the object that
  is currently managing their position. Since the same LayoutPart
- instance may exist in more than one perspective at once, this pointer
+ instance
- points to the part's container in the currently-active perspective. In
+ may exist in more than one perspective at once, this pointer points to
- the case of the projects view, above, the part is not in the current
+ the part's container in the currently-active perspective. In the case
- perspective so its container pointer is null. When another
+ of
- perspective becomes active, all the container pointers move to the new
+ the projects view, above, the part is not in the current perspective so
- perspective. For historical reasons, this is accomplished by setting
+ its container pointer is null. When another perspective becomes active,
- and
+ all the container pointers move to the new perspective. For historical
- clearing the contianer pointer when the container becomes visible or
+ reasons, this is accomplished by setting and clearing the contianer
- invisible. This works since only one perspective is visible at a time,
+ pointer when the container becomes visible or invisible. This works
- but it also means that perspectives cannot be manipulated when they are
+ since only one perspective is visible at a time, but it also means that
- invisible.<br>
+ perspectives cannot be manipulated when they are invisible.
+ <br>
  <br>
  The diagram shows the internal objects that make up the only editor.
  Although this detail has been omitted for the views, they would look
  similar. Each view's PartPane is owned by a part reference which may
- have an associated part implementation.<br>
+ have an associated part implementation.
+ <br>
  <br>
  <h3><a class="mozTocH3" name="mozTocId114962"></a>3.2 Zoom / Unzoom
  protocol<br>
  </h3>
  The notion of "zoom" is defined locally between a part and its
- immediate container. Zoom changes are triggered bottom-up. A part asks
+ immediate
- its parent to "zoom me", and the parent either does something with the
+ container. Zoom changes are triggered bottom-up. A part asks its parent
- request or forwards the request up to its parent. Each container
+ to "zoom me", and the parent either does something with the request or
- determines what it means for a child to be zoomed. Once a part's zoom
+ forwards the request up to its parent. Each container determines what
- state changes, its parent notifies it by calling setZoomed. The part
+ it
- may in turn zoom or unzoom one or more of its children.<br>
+ means for a child to be zoomed. Once a part's zoom state changes, its
+ parent notifies it by calling setZoomed. The part may in turn zoom or
+ unzoom one or more of its children.
+ <br>
  <br>
  Anything that can contain LayoutParts must implement the following
- methods, to support zooming:<br>
+ methods, to support zooming:
+ <br>
  <span style="font-family: monospace;"><br>
- </span><code>&nbsp;&nbsp;&nbsp; /**<br>
+ </span>
+ <code>&nbsp;&nbsp;&nbsp; /**<br>
  &nbsp;&nbsp;&nbsp;&nbsp; * Called by child parts to request a zoom in,
  given an immediate child <br>
  &nbsp;&nbsp;&nbsp;&nbsp; * <br>
-Line 418
+Line 440
  &nbsp;&nbsp;&nbsp; <br>
  &nbsp;&nbsp;&nbsp; /**<br>
  &nbsp;&nbsp;&nbsp;&nbsp; * Returns true iff we are zoomed into the
- given part, given an immediate child of this container.<br>
+ given
+ part, given an immediate child of this container.<br>
  &nbsp;&nbsp;&nbsp;&nbsp; * <br>
  &nbsp;&nbsp;&nbsp;&nbsp; * @param toTest part to test<br>
  &nbsp;&nbsp;&nbsp;&nbsp; * @return true iff this contianer is currently
-Line 426
+Line 449
  &nbsp;&nbsp;&nbsp;&nbsp; */<br>
  &nbsp;&nbsp;&nbsp; public boolean childIsZoomed(LayoutPart toTest);<br>
  <br>
- </code><br>
+ </code>
- Consider again Figure 7. If we were to double-click on the java
+ <br>
- editor to zoom it, the LayoutParts would send messages to one another
+ Consider again Figure 7. If we were to double-click on the java editor
- in the following sequence. (In this diagram, each cell represents a
+ to zoom it, the LayoutParts would send messages to one another in the
- method call. Each column is an object. The reciever's column shows the
+ following sequence. (In this diagram, each cell represents a method
- method name and the caller contains an arrow. Rows are in ascending
+ call. Each column is an object. The reciever's column shows the method
- order of time.)<br>
+ name and the caller contains an arrow. Rows are in ascending order of
+ time.)
+ <br>
  <br>
  <table style="width: 100%; text-align: left;" border="1" cellpadding="2"
   cellspacing="2">
-Line 626
+Line 651
  serves a similar function as the computeSize method on an SWT control,
  in that the parent layout uses it to consult with the part when
  computing the part's size. ISizeProvider can provide a variety of
- constraints:<br>
+ constraints:
+ <br>
  <br>
  <table style="width: 100%; text-align: left;" border="1" cellpadding="2"
   cellspacing="2">
-Line 676
+Line 702
  <br>
  Although there are three kinds of constraints, they are all returned
  using a single method. See the JavaDoc on ISizeProvider for more
- information.<br>
+ information.
+ <br>
  <br>
  Whenever a size constraint changes, the part notifies its contianer by
  calling resizeChild(part). This tells the container to respond to the
- new constraints, and to resize the child if necessary (suggestion:
+ new constraints, and to resize the child if necessary (suggestion: if
- if this is ever exposed as API, it would be better to separate the
+ this is ever exposed as API, it would be better to separate the
- concerns of notifying the parent of changes and triggering a layout. In
+ concerns
- general, it may be possible for more than one part to change without
+ of notifying the parent of changes and triggering a layout. In general,
- requiring a layout between each change).<br>
+ it may be possible for more than one part to change without requiring a
+ layout between each change).
+ <br>
  <br>
  <h3><a class="mozTocH3" name="mozTocId162591"></a>3.4 PartStack:
  Communicating with the Presentation API<br>
  </h3>
  PartStack allows presentation to participate in the workbench layout.
- As shown in Figure 10, it wraps a single instance of
+ As
- StackPresentation, and allows it the presentation to manipulate parts
+ shown in Figure 10, it wraps a single instance of StackPresentation,
- by converting each visible part into an IPresentablePart. The part
+ and
- stack outlives the StackPresentation. Whenever the part stack needs
+ allows it the presentation to manipulate parts by converting each
- widgets, it creates the StackPresentation. If the widgets are no longer
+ visible part into an IPresentablePart. The part stack outlives the
- needed, it disposes the StackPresentation and remembers its persisted
+ StackPresentation. Whenever the part stack needs widgets, it creates
- form. Whenever the PartStack persists its StackPresenation, it
+ the
- remembers the presentation ID so that it will not try to restore one
+ StackPresentation. If the widgets are no longer needed, it disposes the
- StackPresentation from state saved by an incompatible presentation.<br>
+ StackPresentation and remembers its persisted form. Whenever the
+ PartStack persists its StackPresenation, it remembers the presentation
+ ID so that it will not try to restore one StackPresentation from state
+ saved by an incompatible presentation.
+ <br>
  <br>
  <div style="text-align: center;"><span style="font-weight: bold;">Figure
 : Anatomy of PartStack</span><br>
  <img alt="" src="PartStack.PNG" style="width: 430px; height: 225px;"><br>
  <div style="text-align: left;"><br>
- Suggestion: it would be useful to update this document with a state
- diagram for PartStack, and message sequence charts for initializaiton
- and part activation.<br>
  <br>
  </div>
  </div>
-Line 720
+Line 750
  </div>
  <br>
  PartSashContainer implements the main layout for a perspective and the
- editor area. As shown in Figure 11, PartSashContainer contains a
+ editor area. As shown in Figure 11, PartSashContainer contains a list
- list of children, a (possibly null) zoomed part, and a LayoutTree that
+ of
- manages the actual layout. <br>
+ children, a (possibly null) zoomed part, and a LayoutTree that manages
+ the actual layout.
+ <br>
  <br>
  LayoutTree is a binary tree (technically, a KD tree). Each internal
- node is an instance of LayoutTreeNode. It contains a draggable sash
+ node
+ is an instance of LayoutTreeNode. It contains a draggable sash
  (LayoutPartSash) that divides its area among its left and right
  children. LayoutTreeNodes can be horizontal or vertical based on the
  orientation of the sash. For horizontal nodes, the "left" child is on
  top and the "right" child is on the bottom. Leaf nodes are instances of
  LayoutTree (the base class), and they point to a LayoutPart that
  occupies that region of the screen. Normally, this is a PartStack, but
- in general it can be any LayoutPart. <br>
+ in general it can be any LayoutPart.
+ <br>
  <br>
  Each LayoutTree occupies a recangular region of the screen that
  encompasses its children. Internal nodes keep track of an integer size
  for each child (implementation note: the sizes are stored in the
  associated LayoutPartSash, not the LayoutTreeNode itself). Normally,
- the left and right sizes are used as a ratio for dividing up the
+ the
- available space. However, when one child contains the editor area, the
+ left and right sizes are used as a ratio for dividing up the available
- other becomes "non-compressible". If one side in non-compressible, the
+ space. However, when one child contains the editor area, the other
- size value is interpreted as a fixed pixel size rather than a ratio.
+ becomes "non-compressible". If one side in non-compressible, the size
- When the sash is moved, the size values are set to the current pixel
+ value is interpreted as a fixed pixel size rather than a ratio. When
- sizes of the left and right children.<br>
+ the
- <br>
+ sash is moved, the size values are set to the current pixel sizes of
- Figure 12 shows an example LayoutTree. If this tree were rendered
+ the
- in a workbench window, it would resemble Figure 3.5.3. The tall
+ left and right children.
- vertical sash separating the package explorer from the editor area is
+ <br>
- the root node. The left child is the leaf node holding the package
+ <br>
- explorer's stack. The right node is the horizontal sash separating the
+ Figure 12 shows an example LayoutTree. If this tree were rendered in a
- problems view from the editor area. The editor area itself is a
+ workbench window, it would resemble Figure 13. The tall vertical sash
- PartSashContainer, which has its own LayoutTree. Note that the rounded
+ separating the package explorer from the editor area is the root node.
- rectangles in Figure 3.5.2 are LayoutParts. The upper portion of the
+ The left child is the leaf node holding the package explorer's stack.
- rectangle is the part type and the lower portion is some text to help
+ The right node is the horizontal sash separating the problems view from
- locate the part in the screenshot. In this example, every internal node
+ the editor area. The editor area itself is a PartSashContainer, which
- has the editor area on one side of it, so all sizes are interpreted as
+ has its own LayoutTree. Note that the rounded rectangles in Figure 12
- pixel sizes and not ratios.<br>
+ are LayoutParts. The upper portion of the rectangle is the part type
+ and
+ the lower portion is some text to help locate the part in the
+ screenshot. In this example, every internal node has the editor area on
+ one side of it, so all sizes are interpreted as pixel sizes and not
+ ratios.
+ <br>
  <div style="text-align: center;"><span style="font-weight: bold;"></span><br>
  <span style="font-weight: bold;">Figure 12: Example LayoutTree</span><br
   style="font-weight: bold;">
-Line 770
+Line 810
  <br>
  Like LayoutParts, LayoutTrees also implement ISizeProvider and support
  size constraints. For external nodes, the size constraints come
- directly from the LayoutPart. For internal nodes, the size constraints
+ directly
- are computed from the child nodes as follows:<br>
+ from the LayoutPart. For internal nodes, the size constraints are
+ computed from the child nodes as follows:
+ <br>
  <ol>
    <li>When computing a constraint perpendicular to the sash, the result
  is the sum of the constraints of the children plus the width of the
-Line 781
+Line 823
    </li>
  </ol>
  An example can help make this a little less abstract. Imagine we're
- computing the minimum width for the root node in Figure 12, which
+ computing the minimum width for the root node in Figure 12, which is a
- is a tall vertical sash. Width measurements are perpendicular to the
+ tall vertical sash. Width measurements are perpendicular to the sash,
- sash, so we end up with case 1. The minimum width is the minimum width
+ so
- of the left stack plus the sash width plus the minimum width of the
+ we end up with case 1. The minimum width is the minimum width of the
- right child. This makes sense because if we made the root node any
+ left stack plus the sash width plus the minimum width of the right
- smaller, one of the three would need to be truncated or made smaller
+ child. This makes sense because if we made the root node any smaller,
- than their minimum size.<br>
+ one of the three would need to be truncated or made smaller than their
+ minimum size.
+ <br>
  <br>
  The "right child" mentioned above is the horizontal sash separating the
  problems view from the editor area. When computing its minimum width,
- we hit case 2: the minimum width of a horizantal sash is the maximum of
+ we
- the minimum widths of each child. Intuitively, this means that the
+ hit case 2: the minimum width of a horizantal sash is the maximum of
- child with the larger minimum size will be the first to reach its
+ the
- minimum when the layout gets small.<br>
+ minimum widths of each child. Intuitively, this means that the child
+ with the larger minimum size will be the first to reach its minimum
+ when
+ the layout gets small.
+ <br>
  <br>
  <h3><a class="mozTocH3" name="mozTocId887241"></a>3.6 Drag / Drop</h3>
  <div style="text-align: center;"><span style="font-weight: bold;">Figure
-Line 898
+Line 946
  action bars. Each action bar implements IActionBars. It is possible to
  create one action bar as a child of another. In this situation, the
  parent and child share the same widgets, but the child may be disabled
- independently of the parent. Figure 15 shows how the workbench
+ independently of the parent. Figure 15 shows how the workbench action
- action bars are
+ bars are constructed. The rectangles indicate instances of IActionBars,
- constructed. The rectangles indicate instances of IActionBars, and the
+ and the ovals indicate other entities that create or modify action
- ovals indicate other entities that create or modify action bars.<br>
+ bars.
+ Black arrows indicate the flow of information.<br>
  <br>
  <div style="text-align: center;"><span style="font-weight: bold;">Figure
 : Action bar information flow</span><br>
-Line 923
+Line 972
  </div>
  </div>
  <br>
+ <br>
  The workbench window has a top level IActionBars instance that
- contributes to the main menubar, coolbar, etc. (this top-level object
+ contributes to the main menubar, coolbar, etc. This top-level object is
- is returned by WorkbenchWindow.getActionBars()).<br>
+ returned by WorkbenchWindow.getActionBars().
+ Most action bars are descendants of this top-level object, with the
+ notable exception of the view action bars.<br>
+ <br>
  <br>
  <h3><a class="mozTocH3" name="mozTocId652269"></a>4.1 Editor Action Bars<br>
  </h3>
  Each type of editor gets a reference-counted IActionBars instance that
- is a child of the window's action bars. For
+ is a child of the window's action bars. For example, if the workbench
- example, if the workbench contains 10 java editors and 10 text editors,
+ contains 10 java editors and 10 text editors, it will create one
- it will create one IActionBars to be shared among the Java editors and
+ IActionBars to be shared among the Java editors and another IActionBars
- another IActionBars to be shared among the text editors. Editors can
+ to be shared among the text editors. Editors can access this shared
- access this shared instance by calling getSite().getActionBars().
+ instance by calling getSite().getActionBars(). Editor action bars are
- Editor action bars are initialized by an instance of
+ initialized by an instance of IEditorActionBarContributor, and
- IEditorActionBarContributor, and additional actions are added by the
+ additional actions are added by the editorActions extension point.
- editorActions
+ <br>
- extension point.<br>
  <br>
  The reference counted IEditorActionBars are managed by the
- EditorManager, along with the IActionBarContributor.<br>
+ EditorManager, along with the IActionBarContributor.
+ <br>
  <br>
  <h3><a class="mozTocH3" name="mozTocId340925"></a>4.2 Action Sets<br>
  </h3>
-Line 990
+Line 1043
  action bars, these are not shared and are not a child of the workbench
  window's root action bars. This means that view instances can
  programmatically add actions to their action bar. Additional actions
- are also added to a view's action bars through the viewActions
+ are
- extension point.<br>
+ also added to a view's action bars through the viewActions extension
+ point.
+ <br>
  <br>
  <h2><a class="mozTocH2" name="mozTocId642161"></a>5.0 General
  Conventions</h2>

 Legend:



Removed from v.1.5
 


changed lines


 
Added in v.1.6
 Legend:



Removed from v.1.5
 


changed lines


 
Added in v.1.6
-Removed from v.1.5
+Added in v.1.6

help@eclipse.org	ViewVC Help
Powered by ViewVC 1.0.3