Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "E4/UI/Modeled UI"

< E4‎ | UI
(→‎Data Layer)
(→‎Window)
(86 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
== Modeled UI in E4 ==
+
== Overview ==
  
−
The E4 user iunterface is model based; everything that appears in the presentation is backed
+
An e4 application is completely backed up by a domain model often called Workbench or Application Model but in contrast to e.g. the browser DOM which only holds visual elements the e4 application model also holds other informations relevant to an e4 application (e.g. commands, handlers, ...). This makes the e4 application model the center of each e4 application.
−
by a representation in the UI Model. This page will explain the structure of the model, what
+
−
information is contained in it and how it fits into the overall architecture of E4.
+
  
−
For an excellent overview of the concepts that drove the design of this model see the [http://live.eclipse.org/node/727 Modeled UI in Eclipse e4] EclipseCon09 recording.  
+
From a technical point of view the e4 application model is defined using EMFs Ecore meta model. For an average user the usage of EMF in the background is completely transparent and you don't need to know about EMF to write an develop e4 applications (you won't even notice that you are using EMF because the API presented to you is not holding EMF-Types). For people who'd like to extend the workbench model a certain knowlegde about EMF is certainly needed.
  
 +
== UI Layer ==
 +
As outlined before the application model holds the main UI structure of an e4 application. When we talk about the main UI structure this means everything part of the Application Window (Menus, PartStacks, ...) and e.g. Part menus but '''not''' the UI shown inside an application Part (e.g. the Tree in the PackageExplorer)
  
−
=== Model Structure ===
+
The following screenshot displays the domain model making up the ui on the left and the rendered application [[Image:modeled_app.jpg|1024px]]
  
−
The UI model is designed to maximize the amount of flexibility available to E4 clients
+
One of the most important things when talking about the application model we need to know that ALL modification made in the model are immediately reflected in the UI. It is in contrast so that you are only programming against the application model and not against its visual representation. This now is indeed similar to how you are implementing Browser-Applications where also modify the DOM and the browser updates the visual representation.
−
while providing the ability to define model containment hierarchies ("shapes") appropriate for a
+
−
particular application domain. The resulting model structure must be capable of spanning the
+
−
spectrum of possible E4 apps from the simplest RCP 'kiost' application up to (and including) a
+
−
structure capable of supporting the existing eclipse 3.x UI.
+
  
−
In order to accomplish this the model is breoken into three
 
−
basic layers:
 
  
−
# The Data Layer: The elements at this level represent chunks of orthogonal data from which the
+
The ui-domain objects are organized in 3 different packages:
−
Application Elements are constructed using a 'mix in' pattern. These elements cannot be directly
+
* menu: Holding menu and toolbar domain objects
−
created (they're 'abstract'), their creation will be a side-effect of the creation of some Application
+
* basic: Basic UI domain objects e.g. to create windows, stacks, ...
−
Element
+
* advanced: Advanced UI domain objects e.g. to create perspectives
−
# The Application Elements: These elements represent the basic units of functionality for a particular
+
−
application domain.  
+
−
# The Containment Hierarchy: These elements define the aggregate structure of the UI presentation.
+
  
−
Any User interface is designed to present to the user mechanisms to access the application's
+
=== Basic UI Domain Objects ===
−
underlying functionality. The most common ways that this access is granted is through the
+
These domain objects are needed to write a simple to medium size e4 application providing you with the most common UI concepts like Window, Sash and Stack.
−
display of menu and toolbar items and through the hosting of various application-defined
+
−
elements ("parts") within the UI presentation. These represent the expected 'leafs' of the
+
−
UI Model, where the model cedes reposnsibility to the application for implementation (i.e.
+
−
where the application's rubber hits the road).
+
  
−
There is also a containment hierarchy to allow
+
==== Windows ====
−
for management of the parts within the presentation; in the current eclipse 3.x UI these are the
+
There are 2 domain types available to define a window in your application.
−
various sash and stack containers. These elements are generally not relevant to the appplication's
+
−
actual functionality (it doesn't usually matter which stack a part is in...) but instead provide
+
−
a flexible environment within which the application (or user) can arrange their parts.
+
  
−
While these are supported 'out of the box' by the UI Model and
+
[[Image:e4_model_window.jpg]]
−
its default rendering engine they are just a starting point for the shapes availoable through
+
−
extending the UI Model's containment structure.
+
  
−
==== Data Layer ====
+
===== Window =====
 +
Represents a standard window used by application who are not in need of advanced stuff.
  
−
<i><b>ApplicationElement</b></i>
+
'''Inheritance:'''
−
{| border="1"
+
−
|-
+
−
! Attribute
+
−
! Description
+
−
|-
+
−
| id
+
−
| This attribute is used to identify a particular model element. It may either be null or <b>must be</b> unique within the model.
+
−
|}
+
  
−
<i><b>Contribution</b></i>
+
[[Image:e4_model_window_inheritance.png]]
−
{| border="1"
+
−
|-
+
−
! Attribute
+
−
! Description
+
−
|-
+
−
| URI
+
−
| The URI of the class supplying the implementation of this element. The class is instantiated by  ependency injection when required.
+
−
|-
+
−
| persistedState
+
−
| A string that a Contribution elelment can use to store information that it wishes to have persisted between sessions. This is used to store information specific to an instance of the element such as the column width/order for a contribution implementing a table...
+
−
|-
+
−
| object
+
−
| A reference to the implementation object created through the URI. This is a transient attribute used to limit the number of times an element's implementation needs to be re-created.
+
−
|}
+
  
−
<i><b>Command</b></i>
+
'''Attributes:'''
−
{| border="1"
+
−
|-
+
−
! Attribute
+
−
! Description
+
−
|-
+
−
| commandName
+
−
| The generic 'name' of the command. A change to this name should be reflected in all places where this command surfaces in the UI (whether as a menu item or on a toolbar).
+
−
|-
+
−
| description
+
−
| A description of the command suitable to show to a user in a dialog or wizard
+
−
|-
+
−
| parameters
+
−
| A collection of zero or more CommandParameters
+
−
|}
+
  
−
<i><b>CommandParameter</b></i>
+
<table border='0' cellpadding='5' cellspacing='0'>
−
{| border="1"
+
<tr>
−
|-
+
<th>Class</th>
−
! Attribute
+
<th>Feature</th>
−
! Description
+
<th>Type</th>
−
|-
+
<th>Description</th>
−
| name
+
</tr>
−
| The name of this parameter.
+
<tr style='background-color: #777; color: white; font-weight: bold;'>
−
|-
+
<td>MWindow</td>
−
| typeId
+
<td></td>
−
| A string defining the expected type of this parameter
+
<td></td>
−
|-
+
<td></td>
−
| optional
+
</tr>
−
| A boolean representing whether or not this parameter is optional.
+
<tr>
−
|}
+
<td></td>
 +
<td>mainMenu</td>
 +
<td>Menu</td>
 +
<td>The main menu shown in the menubar of the Shell</td>
 +
</tr>
 +
<tr style='background-color: #DDDDDD'>
 +
<td></td>
 +
<td>x</td>
 +
<td>int</td>
 +
<td>The x position on the screen</td>
 +
</tr>
 +
<tr>
 +
<td></td>
 +
<td>y</td>
 +
<td>int</td>
 +
<td>The y position on the screen</td>
 +
</tr>
 +
<tr style='background-color: #DDDDDD'>
 +
<td></td>
 +
<td>width</td>
 +
<td>int</td>
 +
<td>The width of the window</td>
 +
</tr>
 +
<tr>
 +
<td></td>
 +
<td>height</td>
 +
<td>int</td>
 +
<td>The height of the window</td>
 +
</tr>
 +
<tr style='background-color: #DDDDDD'>
 +
<td></td>
 +
<td>windows</td>
 +
<td>List<Window></td>
 +
<td>Child Windows</td>
 +
</tr>
 +
<tr>
 +
<td></td>
 +
<td>sharedElements</td>
 +
<td>List<UIElement></td>
 +
<td>Shared Elements are quite an advanced concept coming into Eclipse through perspectives. Normally an UI-Tree is made up of only contaiments but without the idea of links. In an Eclipse Application this is not necessarily this way because e.g. the editor-area with all its editors is shared between different parts of the model (the perspectives), the same holds true for certain parts (e.g. the Package Explorer). The currently supported elements to share are MPart and MPartSashContainer</td>
 +
</tr>
 +
<tr style='background-color: #777; color: white; font-weight: bold;'>
 +
<td style='border-bottom: 2px solid gray'>MBindings</td>
 +
<td style='border-bottom: 2px solid gray'></td>
 +
<td style='border-bottom: 2px solid gray'></td>
 +
<td style='border-bottom: 2px solid gray'></td>
 +
</tr>
 +
<tr style='background-color: #DDDDDD'>
 +
<td></td>
 +
<td>bindingContexts</td>
 +
<td>List<String></td>
 +
<td>Keybinding contexts active in this window</td>
 +
</tr>
 +
<tr style='background-color: #777; color: white; font-weight: bold;'>
 +
<td>MContext</td>
 +
<td></td>
 +
<td></td>
 +
<td></td>
 +
</tr>
 +
<tr  style='background-color: #DDDDDD'>
 +
<td></td>
 +
<td>context</td>
 +
<td>IEclipseContext</td>
 +
<td>The IEclipseContext used by the DI-Framework for injection</td>
 +
</tr>
 +
<tr>
 +
<td></td>
 +
<td>variables</td>
 +
<td>List<String></td>
 +
<td>Variables defined in this context (see IEclipseContext description)</td>
 +
</tr>
 +
<tr style='background-color: #777; color: white; font-weight: bold;'>
 +
<td>MElementContainer</td>
 +
<td></td>
 +
<td></td>
 +
<td></td>
 +
</tr>
 +
<tr>
 +
<td></td>
 +
<td>children</td>
 +
<td>List<MWindowElement></td>
 +
<td>Child elements layouted in the windows content pane</td>
 +
</tr>
 +
<tr style='background-color: #DDDDDD'>
 +
<td></td>
 +
<td>selectedElement</td>
 +
<td>MWindowElement</td>
 +
<td>The currently active childcontrol</td>
 +
</tr>
 +
<tr style='background-color: #777; color: white; font-weight: bold;'>
 +
<td>MUIElement</td>
 +
<td></td>
 +
<td></td>
 +
<td></td>
 +
</tr>
 +
<tr style='background-color: #DDDDDD'>
 +
<td></td>
 +
<td>widget</td>
 +
<td>Object</td>
 +
<td>the real UI-Control (e.g. SWT-Widget) rendering the element</td>
 +
</tr>
 +
<tr>
 +
<td></td>
 +
<td>renderer</td>
 +
<td>Object</td>
 +
<td>The renderer resposible to create the UI-Control and sync it with the elements attribute</td>
 +
</tr>
 +
<tr style='background-color: #DDDDDD'>
 +
<td></td>
 +
<td>toBeRendered</td>
 +
<td>boolean</td>
 +
<td></td>
 +
</tr>
 +
<tr>
 +
<td></td>
 +
<td>onTop</td>
 +
<td>boolean</td>
 +
<td></td>
 +
</tr>
 +
<tr style='background-color: #DDDDDD'>
 +
<td></td>
 +
<td>visible</td>
 +
<td>boolean</td>
 +
<td></td>
 +
</tr>
 +
<tr>
 +
<td></td>
 +
<td>parent</td>
 +
<td>MElementContainer<MUIElement></td>
 +
<td>The parent container</td>
 +
</tr>
 +
<tr style='background-color: #DDDDDD'>
 +
<td></td>
 +
<td>containerData</td>
 +
<td>String</td>
 +
<td></td>
 +
</tr>
 +
<tr>
 +
<td></td>
 +
<td>curSharedRef</td>
 +
<td>MPlaceholder</td>
 +
<td></td>
 +
</tr>
 +
<tr style='background-color: #DDDDDD'>
 +
<td></td>
 +
<td>visibleWhen</td>
 +
<td>MExpression</td>
 +
<td></td>
 +
</tr>
 +
<tr style='background-color: #777; color: white; font-weight: bold;'>
 +
<td>MApplicationElement</td>
 +
<td></td>
 +
<td></td>
 +
<td></td>
 +
</tr>
 +
<tr style='background-color: #DDDDDD'>
 +
<td></td>
 +
<td>elementId</td>
 +
<td>String</td>
 +
<td>id to identify the element e.g. when contributing</td>
 +
</tr>
 +
<tr>
 +
<td></td>
 +
<td>tags</td>
 +
<td>List<String></td>
 +
<td>Arbitary strings used to tag elements so that one can query for them</td>
 +
</tr>
 +
<tr style='background-color: #777; color: white; font-weight: bold;'>
 +
<td>MHandlerContainer</td>
 +
<td></td>
 +
<td></td>
 +
<td></td>
 +
</tr>
 +
<tr style='background-color: #DDDDDD'>
 +
<td></td>
 +
<td>handlers</td>
 +
<td>List<MHandler></td>
 +
<td>list of handlers</td>
 +
</tr>
 +
<tr style='background-color: #777; color: white; font-weight: bold;'>
 +
<td>MUILabel</td>
 +
<td></td>
 +
<td></td>
 +
<td></td>
 +
</tr>
 +
<tr>
 +
<td></td>
 +
<td>label</td>
 +
<td>String</td>
 +
<td>The label displayed on the window</td>
 +
</tr>
 +
<tr style='background-color: #DDDDDD'>
 +
<td></td>
 +
<td>iconURI</td>
 +
<td>String</td>
 +
<td>The icon displayed on the window</td>
 +
</tr>
 +
<tr>
 +
<td></td>
 +
<td>tooltip</td>
 +
<td>String</td>
 +
<td></td>
 +
</tr>
 +
</table>
  
−
<i><b>Dirtyable</b></i>
+
===== TrimmedWindow =====
−
{| border="1"
+
−
|-
+
−
! Attribute
+
−
! Description
+
−
|-
+
−
| dirty
+
−
| A boolean indicating whether or not this element should be considered 'dirty' by the UI manager. Dirty elements get prompted to save their state before they are closed. In the case where the application is shutting down <i>all</i> the dirty elements are presented to the user to manage whether or not their state should be saved. Since these elements appear in lists, dialogs etc it's recommended that elements using this data element also inherit from the UIItem element. This element is <b>not</b> persisted between application sessions.
+
−
|}
+
  
−
<i><b>Handler -> Contribution</b></i>
+
Represents a window with TrimBars e.g. to show a ToolBar at the top, a StatusBar at the bottom and minimized Stacks at the right and left
−
{| border="1"
+
−
|-
+
−
! Attribute
+
−
! Description
+
−
|-
+
−
| command
+
−
| A reference to the Command element for which this is a possible handler.
+
−
|}
+
  
−
<i><b>HandlerContaqiner</b></i>
+
'''Inheritance:'''
−
{| border="1"
+
−
|-
+
−
! Attribute
+
−
! Description
+
−
|-
+
−
| handlers
+
−
| A collection of zero or more Handler elements.
+
−
|}
+
  
−
<i><b>Input</b></i>
+
[[Image:e4_model_trimmed_window_inheritance.png]]
−
{| border="1"
+
−
|-
+
−
! Attribute
+
−
! Description
+
−
|-
+
−
| inputURI
+
−
| The URI representing the location from which this element should access its information and to which any changes should be saved. This allows 'editor style' management with inputURI being the URI to the workspace resource...
+
−
|}
+
  
−
<i><b>Parameter</b></i>
+
'''Attributes:'''
−
{| border="1"
+
<table border='0' cellpadding='5' cellspacing='0'>
−
|-
+
<tr>
−
! Attribute
+
<th>Class</th>
−
! Description
+
<th>Attribute</th>
−
|-
+
<th>Type</th>
−
| tag
+
<th>Description</th>
−
| The tag identifying this parameter
+
</tr>
−
|-
+
<tr style='background-color: #777; color: white; font-weight: bold;'>
−
| value
+
<td>MTrimmedWindow</td>
−
| The value of the parameter
+
<td></td>
−
|}
+
<td></td>
 +
<td></td>
 +
</tr>
 +
<tr>
 +
<td></td>
 +
<td>trimBars</td>
 +
<td>List<MTrimBar></td>
 +
<td>TrimBars who hold e.g. the ToolBar, Minimized Stacks, ...</td>
 +
</tr>
 +
<tr style='background-color: #777; color: white; font-weight: bold;'>
 +
<td colspan='4'>MWindow [http://wiki.eclipse.org/E4/UI/Modeled_UI#Window *]</td>
 +
</tr>
 +
</table>
  
−
<i><b>UIItem</b></i>
+
==== Containers ====
−
{| border="1"
+
−
|-
+
−
! Attribute
+
−
! Description
+
−
|-
+
−
| name
+
−
| Used by the UI manager as a label when it needs to show this element to the user
+
−
|-
+
−
| imageURI
+
−
| The URI of an image resource to use when displaying this element to the user
+
−
|-
+
−
| tooltip
+
−
| The tooltip to use when displaying this element to the user
+
−
|}
+
  
−
<i><b>UIElement</b></i>
+
There are 2 default containers used by e4 applications to build the UI-Tree PartSashContainer und PartStack. The difference between them is that PartSashContainer is designed to show all of its children at once whereas PartStack is showing only one of its children at a time.
−
{| border="1"
+
−
|-
+
−
! Attribute
+
−
! Description
+
−
|-
+
−
| widget
+
−
| A reference to the rendered UI widget that is in the presentation.
+
−
|-
+
−
| factory
+
−
| A reference to the renderer used to create the widget. The rendering engine delegates decisions as to the correct parent widget for a given element is...
+
−
|-
+
−
| visible
+
−
| A boolean used to determine whether or not this element should actually appear in the presentation. <b>NOTE:</b> We are currently in the process of deciding how to turn this into a more flexible 'state' descriptor rather than a simple boolean in order to handle more advanced mechanisms such as minimize.
+
−
|-
+
−
| parent
+
−
| The parent of this UI element
+
−
|}
+
  
−
<i><b>Context</b></i>
+
[[Image:e4_model_container.png]]
−
{| border="1"
+
−
|-
+
−
! Attribute
+
−
! Description
+
−
|-
+
−
| context
+
−
| A reference to the IEclipseContext for this element. The life-cycle of the context for an element is tied to the life of the widget in the presentation. The rendering engine guarantees that this will be available to the element before it is created and will be disposed along with the widget.
+
−
|-
+
−
| variables
+
−
| A collection of strings representing <???>
+
−
|}
+
  
−
<i><b>KeySequence</b></i>
+
===== PartSashContainer =====
−
{| border="1"
+
−
|-
+
−
! Attribute
+
−
! Description
+
−
|-
+
−
| keySequence
+
−
| A string defining the sequence of keys used to accesss a COmmand through a KeyBinding.
+
−
|}
+
  
−
=== Generic Containers ===
+
'''Inheritance:'''
  
−
<i><b>ElementContainer</b></i>
+
[[Image:e4_model_partsash_inheritance.png]]
−
{| border="1"
+
−
|-
+
−
! Attribute
+
−
! Description
+
−
|-
+
−
| children
+
−
| A collection of UIElements. This collection can be parameterized to restrict its containment to a particular set of other element types.
+
−
|-
+
−
| activeChild
+
−
| A reference to the element in the container that is 'on top'. For a stack presentation it's the selected tab, presentations that may be tiling the children should (perhaps) maximize the screen real estate give to the active element.
+
−
|}
+
  
−
<i><b>GenericTile</b></i>
+
'''Attributes:'''
−
{| border="1"
+
<table border='0' cellpadding='5' cellspacing='0'>
−
|-
+
<tr>
−
! Attribute
+
<th>Class</th>
−
! Description
+
<th>Attribute</th>
−
|-
+
<th>Type</th>
−
| weights
+
<th>Description</th>
−
| A collection of Integers used to store the weights. <b>NOTE:</b> This is under review; we may want to move this information into a new field in UIElement 'containerInfo'. The current mechanism is fine for SWT sashes but isn't flexible enough to handle more advanced containers such as PShelf or the ExpandBar.
+
</tr>
−
|-
+
<tr style='background-color: #777; color: white; font-weight: bold;'>
−
| horizontal
+
<td>MPartSashContainer</td>
−
| A boolean indicating the direction that the tiling is to take place.
+
<td></td>
−
|}
+
<td></td>
 +
<td></td>
 +
</tr>
 +
<tr style='background-color: #777; color: white; font-weight: bold;'>
 +
<td>MGenericTile</td>
 +
<td></td>
 +
<td></td>
 +
<td></td>
 +
</tr>
 +
<tr>
 +
<td></td>
 +
<td>horizontal</td>
 +
<td>boolean</td>
 +
<td>true if all children are aligned next to each other horizontally</td>
 +
</tr>
 +
<tr style='background-color: #777; color: white; font-weight: bold;'>
 +
<td>MElementContainer</td>
 +
<td></td>
 +
<td></td>
 +
<td></td>
 +
</tr>
 +
<tr>
 +
<td></td>
 +
<td>children</td>
 +
<td>List<MPartSashContainerElement></td>
 +
<td>Child elements layed out in the container depending on the horizontal attribute</td>
 +
</tr>
 +
<tr style='background-color: #DDDDDD'>
 +
<td></td>
 +
<td>selectedElement</td>
 +
<td>MWindowElement</td>
 +
<td>The currently active childcontrol</td>
 +
</tr>
 +
<tr style='background-color: #777; color: white; font-weight: bold;'>
 +
<td>MUIElement</td>
 +
<td></td>
 +
<td></td>
 +
<td></td>
 +
</tr>
 +
<tr style='background-color: #DDDDDD'>
 +
<td></td>
 +
<td>widget</td>
 +
<td>Object</td>
 +
<td>the real UI-Control (e.g. SWT-Widget) rendering the element</td>
 +
</tr>
 +
<tr>
 +
<td></td>
 +
<td>renderer</td>
 +
<td>Object</td>
 +
<td>The renderer resposible to create the UI-Control and sync it with the elements attribute</td>
 +
</tr>
 +
<tr style='background-color: #DDDDDD'>
 +
<td></td>
 +
<td>toBeRendered</td>
 +
<td>boolean</td>
 +
<td></td>
 +
</tr>
 +
<tr>
 +
<td></td>
 +
<td>onTop</td>
 +
<td>boolean</td>
 +
<td></td>
 +
</tr>
 +
<tr style='background-color: #DDDDDD'>
 +
<td></td>
 +
<td>visible</td>
 +
<td>boolean</td>
 +
<td></td>
 +
</tr>
 +
<tr>
 +
<td></td>
 +
<td>parent</td>
 +
<td>MElementContainer<MUIElement></td>
 +
<td>The parent container</td>
 +
</tr>
 +
<tr style='background-color: #DDDDDD'>
 +
<td></td>
 +
<td>containerData</td>
 +
<td>String</td>
 +
<td></td>
 +
</tr>
 +
<tr>
 +
<td></td>
 +
<td>curSharedRef</td>
 +
<td>MPlaceholder</td>
 +
<td></td>
 +
</tr>
 +
<tr style='background-color: #DDDDDD'>
 +
<td></td>
 +
<td>visibleWhen</td>
 +
<td>MExpression</td>
 +
<td></td>
 +
</tr>
 +
<tr style='background-color: #777; color: white; font-weight: bold;'>
 +
<td>MApplicationElement</td>
 +
<td></td>
 +
<td></td>
 +
<td></td>
 +
</tr>
 +
<tr style='background-color: #DDDDDD'>
 +
<td></td>
 +
<td>elementId</td>
 +
<td>String</td>
 +
<td>id to identify the element e.g. when contributing</td>
 +
</tr>
 +
<tr>
 +
<td></td>
 +
<td>tags</td>
 +
<td>List<String></td>
 +
<td>Arbitary strings used to tag elements so that one can query for them</td>
 +
</tr>
 +
<tr style='background-color: #777; color: white; font-weight: bold;'>
 +
<td colspan='4'>MPartSashContainerElement (Marker)</td>
 +
</tr>
 +
<tr style='background-color: #777; color: white; font-weight: bold;'>
 +
<td>MWindowElement (Marker)</td>
 +
<td></td>
 +
<td></td>
 +
<td></td>
 +
</tr>
 +
</table>
  
−
<i><b>TrimContainer</b></i>
+
===== PartStack =====
−
{| border="1"
+
−
|-
+
−
! Attribute
+
−
! Description
+
−
|-
+
−
| horizontal
+
−
| A boolean indicating the direction that the tiling is to take place. (<b>NOTE:</b> we can likely remove this and infer it from the 'side' value).
+
−
|-
+
−
| side
+
−
| An emumrated value that indicates on which edge of its container this element should be placed.
+
−
|}
+
  
−
=== Leaf Elements ===
+
'''Inheritance:'''
  
−
<i><b>Item -> UIItem</b></i>: The base element for menu and toolbar items.
+
[[Image:e4_model_partstack_inheritance.png]]
−
{| border="1"
+
−
|-
+
−
! Attribute
+
−
! Description
+
−
|-
+
−
| enabled
+
−
| A boolean indicating whether the element should be enabled.
+
−
|-
+
−
| selected
+
−
| A boolean indicating whether the element should be displayed as selected.
+
−
|-
+
−
| separator
+
−
| A boolean indicating whether the element should be displayed as a separator.
+
−
|}
+
  
−
<i><b>HandledItem</b></i>: An Item that manages its execution through the Commands infrastructure
+
'''Attributes:'''
−
{| border="1"
+
−
|-
+
−
! Attribute
+
−
! Description
+
−
|-
+
−
| command
+
−
| A reference to the COmmand element that this item should delegate to
+
−
|-
+
−
| wbCommand
+
−
| A reference to the prg.eclipse.core.commands.ParameterizedCOmmand <???>.
+
−
|-
+
−
| parameters
+
−
| A collection of zero or more parameters for this instance. Allows the model to re-use the same command with different parameters (think 'Show View').
+
−
|}
+
  
−
=== Model Rendering ===
+
==== Parts ====
  
−
=== Model Events ===
+
[[Image:e4_model_parts.png]]
 +
 
 +
===== Part =====
 +
 
 +
'''Inheritance:'''
 +
 
 +
[[Image:e4_model_part_inheritance.png]]
 +
 
 +
'''Attributes:'''
 +
<table border='0' cellpadding='5' cellspacing='0'>
 +
<tr>
 +
<th>Class</th>
 +
<th>Attribute</th>
 +
<th>Type</th>
 +
<th>Description</th>
 +
</tr>
 +
<tr style='background-color: #777; color: white; font-weight: bold;'>
 +
<td>MPart</td>
 +
<td></td>
 +
<td></td>
 +
<td></td>
 +
</tr>
 +
</table>
 +
 
 +
===== InputPart =====
 +
 
 +
'''Inheritance:'''
 +
 
 +
[[Image:e4_model_inputpart_inheritance.png]]
 +
 
 +
'''Attributes:'''
 +
<table border='0' cellpadding='5' cellspacing='0'>
 +
<tr>
 +
<th>Class</th>
 +
<th>Attribute</th>
 +
<th>Type</th>
 +
<th>Description</th>
 +
</tr>
 +
<tr style='background-color: #777; color: white; font-weight: bold;'>
 +
<td>MInputPart</td>
 +
<td></td>
 +
<td></td>
 +
<td></td>
 +
</tr>
 +
</table>
 +
 
 +
==== Other Elements ====
 +
===== TrimBar =====
 +
 
 +
'''Inheritance:'''
 +
 
 +
[[Image:e4_model_trimbar_inheritance.png]]
 +
 
 +
'''Attributes:'''
 +
<table border='0' cellpadding='5' cellspacing='0'>
 +
<tr>
 +
<th>Class</th>
 +
<th>Attribute</th>
 +
<th>Type</th>
 +
<th>Description</th>
 +
</tr>
 +
<tr style='background-color: #777; color: white; font-weight: bold;'>
 +
<td>MTrimBar</td>
 +
<td></td>
 +
<td></td>
 +
<td></td>
 +
</tr>
 +
</table>
 +
 
 +
=== Menu, Toolbar &amp; Trim UI Domain Objects ===
 +
 
 +
==== Menu ====
 +
 
 +
===== Menu =====
 +
===== PopupMenu =====
 +
 
 +
==== ToolBar ====
 +
 
 +
==== Trim ====
 +
 
 +
=== Advanced UI Domain Objects ===
 +
 
 +
=== Descriptors ===
 +
 
 +
== Application Logic Layer ==
 +
 
 +
=== Command, Handlers &amp; Expressions ===
 +
 
 +
== Contribution, Model Assembling &amp; Addons ==
 +
 
 +
== Extending the workbench model ==

Revision as of 16:43, 21 June 2010

Overview

An e4 application is completely backed up by a domain model often called Workbench or Application Model but in contrast to e.g. the browser DOM which only holds visual elements the e4 application model also holds other informations relevant to an e4 application (e.g. commands, handlers, ...). This makes the e4 application model the center of each e4 application.

From a technical point of view the e4 application model is defined using EMFs Ecore meta model. For an average user the usage of EMF in the background is completely transparent and you don't need to know about EMF to write an develop e4 applications (you won't even notice that you are using EMF because the API presented to you is not holding EMF-Types). For people who'd like to extend the workbench model a certain knowlegde about EMF is certainly needed.

UI Layer

As outlined before the application model holds the main UI structure of an e4 application. When we talk about the main UI structure this means everything part of the Application Window (Menus, PartStacks, ...) and e.g. Part menus but not the UI shown inside an application Part (e.g. the Tree in the PackageExplorer)

The following screenshot displays the domain model making up the ui on the left and the rendered application Modeled app.jpg

One of the most important things when talking about the application model we need to know that ALL modification made in the model are immediately reflected in the UI. It is in contrast so that you are only programming against the application model and not against its visual representation. This now is indeed similar to how you are implementing Browser-Applications where also modify the DOM and the browser updates the visual representation.


The ui-domain objects are organized in 3 different packages:

  • menu: Holding menu and toolbar domain objects
  • basic: Basic UI domain objects e.g. to create windows, stacks, ...
  • advanced: Advanced UI domain objects e.g. to create perspectives

Basic UI Domain Objects

These domain objects are needed to write a simple to medium size e4 application providing you with the most common UI concepts like Window, Sash and Stack.

Windows

There are 2 domain types available to define a window in your application.

E4 model window.jpg

Window

Represents a standard window used by application who are not in need of advanced stuff.

Inheritance:

E4 model window inheritance.png

Attributes:

Class Feature Type Description
MWindow
mainMenu Menu The main menu shown in the menubar of the Shell
x int The x position on the screen
y int The y position on the screen
width int The width of the window
height int The height of the window
windows List<Window> Child Windows
sharedElements List<UIElement> Shared Elements are quite an advanced concept coming into Eclipse through perspectives. Normally an UI-Tree is made up of only contaiments but without the idea of links. In an Eclipse Application this is not necessarily this way because e.g. the editor-area with all its editors is shared between different parts of the model (the perspectives), the same holds true for certain parts (e.g. the Package Explorer). The currently supported elements to share are MPart and MPartSashContainer
MBindings
bindingContexts List<String> Keybinding contexts active in this window
MContext
context IEclipseContext The IEclipseContext used by the DI-Framework for injection
variables List<String> Variables defined in this context (see IEclipseContext description)
MElementContainer
children List<MWindowElement> Child elements layouted in the windows content pane
selectedElement MWindowElement The currently active childcontrol
MUIElement
widget Object the real UI-Control (e.g. SWT-Widget) rendering the element
renderer Object The renderer resposible to create the UI-Control and sync it with the elements attribute
toBeRendered boolean
onTop boolean
visible boolean
parent MElementContainer<MUIElement> The parent container
containerData String
curSharedRef MPlaceholder
visibleWhen MExpression
MApplicationElement
elementId String id to identify the element e.g. when contributing
tags List<String> Arbitary strings used to tag elements so that one can query for them
MHandlerContainer
handlers List<MHandler> list of handlers
MUILabel
label String The label displayed on the window
iconURI String The icon displayed on the window
tooltip String
TrimmedWindow

Represents a window with TrimBars e.g. to show a ToolBar at the top, a StatusBar at the bottom and minimized Stacks at the right and left

Inheritance:

E4 model trimmed window inheritance.png

Attributes:

Class Attribute Type Description
MTrimmedWindow
trimBars List<MTrimBar> TrimBars who hold e.g. the ToolBar, Minimized Stacks, ...
MWindow *

Containers

There are 2 default containers used by e4 applications to build the UI-Tree PartSashContainer und PartStack. The difference between them is that PartSashContainer is designed to show all of its children at once whereas PartStack is showing only one of its children at a time.

E4 model container.png

PartSashContainer

Inheritance:

E4 model partsash inheritance.png

Attributes:

Class Attribute Type Description
MPartSashContainer
MGenericTile
horizontal boolean true if all children are aligned next to each other horizontally
MElementContainer
children List<MPartSashContainerElement> Child elements layed out in the container depending on the horizontal attribute
selectedElement MWindowElement The currently active childcontrol
MUIElement
widget Object the real UI-Control (e.g. SWT-Widget) rendering the element
renderer Object The renderer resposible to create the UI-Control and sync it with the elements attribute
toBeRendered boolean
onTop boolean
visible boolean
parent MElementContainer<MUIElement> The parent container
containerData String
curSharedRef MPlaceholder
visibleWhen MExpression
MApplicationElement
elementId String id to identify the element e.g. when contributing
tags List<String> Arbitary strings used to tag elements so that one can query for them
MPartSashContainerElement (Marker)
MWindowElement (Marker)
PartStack

Inheritance:

E4 model partstack inheritance.png

Attributes:

Parts

E4 model parts.png

Part

Inheritance:

E4 model part inheritance.png

Attributes:

Class Attribute Type Description
MPart
InputPart

Inheritance:

E4 model inputpart inheritance.png

Attributes:

Class Attribute Type Description
MInputPart

Other Elements

TrimBar

Inheritance:

E4 model trimbar inheritance.png

Attributes:

Class Attribute Type Description
MTrimBar

Menu, Toolbar & Trim UI Domain Objects

Menu

Menu
PopupMenu

ToolBar

Trim

Advanced UI Domain Objects

Descriptors

Application Logic Layer

Command, Handlers & Expressions

Contribution, Model Assembling & Addons

Extending the workbench model

Retrieved from "https://wiki.eclipse.org/index.php?title=E4/UI/Modeled_UI&oldid=208142"

Back to the top