Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "E4/UI/Modeled UI"
(→Data Layer) |
|||
Line 212: | Line 212: | ||
| variables | | variables | ||
| A collection of strings representing <???> | | A collection of strings representing <???> | ||
+ | |} | ||
+ | |||
+ | <i><b>KeySequence</b></i> | ||
+ | {| border="1" | ||
+ | |- | ||
+ | ! Attribute | ||
+ | ! Description | ||
+ | |- | ||
+ | | keySequence | ||
+ | | A string defining the sequence of keys used to accesss a COmmand through a KeyBinding. | ||
+ | |} | ||
+ | |||
+ | === Generic Containers === | ||
+ | |||
+ | <i><b>ElementContainer</b></i> | ||
+ | {| 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> | ||
+ | {| border="1" | ||
+ | |- | ||
+ | ! Attribute | ||
+ | ! Description | ||
+ | |- | ||
+ | | weights | ||
+ | | 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. | ||
+ | | horizontal | ||
+ | | A boolean indicating the direction that the tiling is to take place. | ||
+ | |} | ||
+ | |||
+ | <i><b>TrimContainer</b></i> | ||
+ | {| 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 === | ||
+ | |||
+ | <i><b>Item -> UIItem</b></i>: The base element for menu and toolbar items. | ||
+ | {| 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 | ||
+ | {| 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'). | ||
|} | |} | ||
Revision as of 16:45, 29 November 2009
Contents
Modeled UI in E4
The E4 user iunterface is model based; everything that appears in the presentation is backed 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 Modeled UI in Eclipse e4 EclipseCon09 recording.
Model Structure
The UI model is designed to maximize the amount of flexibility available to E4 clients 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
Application Elements are constructed using a 'mix in' pattern. These elements cannot be directly created (they're 'abstract'), their creation will be a side-effect of the creation of some Application Element
- 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 underlying functionality. The most common ways that this access is granted is through the 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 for management of the parts within the presentation; in the current eclipse 3.x UI these are the 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 its default rendering engine they are just a starting point for the shapes availoable through extending the UI Model's containment structure.
Data Layer
ApplicationElement
Attribute | Description |
---|---|
id | This attribute is used to identify a particular model element. It may either
be null or must be unique within the model. |
Contribution
Attribute | Description |
---|---|
URI | The URI of the class supplying the implementation of this element. The class
is instantiated by dependency 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. |
Command
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 |
CommandParameter
Attribute | Description |
---|---|
name | The name of this parameter. |
typeId | A string defining the expected type of this parameter |
optional | A boolean representing whether or not this parameter is optional. |
Dirtyable
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 all 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 not persisted between application sessions. |
Handler -> Contribution
Attribute | Description |
---|---|
command | A reference to the Command element for which this is a possible handler. |
HandlerContaqiner
Attribute | Description |
---|---|
handlers | A collection of zero or more Handler elements. |
Input
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... |
Parameter
Attribute | Description |
---|---|
tag | The tag identifying this parameter |
value | The value of the parameter |
UIItem
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 |
UIElement
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. NOTE: 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. | pasrent | The parent of this UI element |
Context
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 <???> |
KeySequence
Attribute | Description |
---|---|
keySequence | A string defining the sequence of keys used to accesss a COmmand through a KeyBinding. |
Generic Containers
ElementContainer
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. |
GenericTile
Attribute | Description | ||
---|---|---|---|
weights | A collection of Integers used to store the weights. NOTE: 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. | horizontal | A boolean indicating the direction that the tiling is to take place. |
TrimContainer
Attribute | Description | ||
---|---|---|---|
horizontal | A boolean indicating the direction that the tiling is to take place. (NOTE: 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
Item -> UIItem: The base element for menu and toolbar items.
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. |
HandledItem: An Item that manages its execution through the Commands infrastructure
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'). |