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
(New page: Blah Blah Blah)
 
(Window)
(93 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 +
== Overview ==
  
Blah Blah Blah
+
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 [[Image:modeled_app.jpg|1024px]]
 +
 
 +
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.
 +
 
 +
[[Image:e4_model_window.jpg]]
 +
 
 +
===== Window =====
 +
Represents a standard window used by application who are not in need of advanced stuff.
 +
 
 +
'''Inheritance:'''
 +
 
 +
[[Image:e4_model_window_inheritance.png]]
 +
 
 +
'''Attributes:'''
 +
 
 +
<table border='0' cellpadding='5' cellspacing='0'>
 +
<tr>
 +
<th>Class</th>
 +
<th>Feature</th>
 +
<th>Type</th>
 +
<th>Description</th>
 +
</tr>
 +
<tr style='background-color: #777; color: white; font-weight: bold;'>
 +
<td>MWindow</td>
 +
<td></td>
 +
<td></td>
 +
<td></td>
 +
</tr>
 +
<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>
 +
 
 +
===== 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:'''
 +
 
 +
[[Image:e4_model_trimmed_window_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>MTrimmedWindow</td>
 +
<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>
 +
 
 +
==== 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.
 +
 
 +
[[Image:e4_model_container.png]]
 +
 
 +
===== PartSashContainer =====
 +
 
 +
'''Inheritance:'''
 +
 
 +
[[Image:e4_model_partsash_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>MPartSashContainer</td>
 +
<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>
 +
 
 +
===== PartStack =====
 +
 
 +
'''Inheritance:'''
 +
 
 +
[[Image:e4_model_partstack_inheritance.png]]
 +
 
 +
'''Attributes:'''
 +
 
 +
==== Parts ====
 +
 
 +
[[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

Back to the top