|
|
| Line 1: |
Line 1: |
| − | == Modeled UI in E4 == | + | == Overview == |
| | | | |
| − | The E4 user interface 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 Model == |
| − | === Model Structure ===
| + | 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 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 'kiosk' application up to (and including) a
| + | |
| − | structure capable of supporting the existing eclipse 3.x UI.
| + | |
| − | | + | |
| − | In order to accomplish this the model is broken 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 responsibility 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 application'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 available through
| + | |
| − | extending the UI Model's containment structure.
| + | |
| − | | + | |
| − | ==== Data Layer ====
| + | |
| − | | + | |
| − | <i><b>ApplicationElement</b></i>
| + | |
| − | {| 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>
| + | |
| − | {| border="1"
| + | |
| − | |-
| + | |
| − | ! 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 element 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>
| + | |
| − | {| 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>
| + | |
| − | {| border="1"
| + | |
| − | |-
| + | |
| − | ! 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.
| + | |
| − | |}
| + | |
| − | | + | |
| − | <i><b>Dirtyable</b></i>
| + | |
| − | {| 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>
| + | |
| − | {| border="1"
| + | |
| − | |-
| + | |
| − | ! Attribute
| + | |
| − | ! Description
| + | |
| − | |-
| + | |
| − | | command
| + | |
| − | | A reference to the Command element for which this is a possible handler.
| + | |
| − | |}
| + | |
| − | | + | |
| − | <i><b>HandlerContainer</b></i>
| + | |
| − | {| border="1"
| + | |
| − | |-
| + | |
| − | ! Attribute
| + | |
| − | ! Description
| + | |
| − | |-
| + | |
| − | | handlers
| + | |
| − | | A collection of zero or more Handler elements.
| + | |
| − | |}
| + | |
| − | | + | |
| − | <i><b>Input</b></i>
| + | |
| − | {| 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>
| + | |
| − | {| border="1"
| + | |
| − | |-
| + | |
| − | ! Attribute
| + | |
| − | ! Description
| + | |
| − | |-
| + | |
| − | | tag
| + | |
| − | | The tag identifying this parameter
| + | |
| − | |-
| + | |
| − | | value
| + | |
| − | | The value of the parameter
| + | |
| − | |}
| + | |
| − | | + | |
| − | <i><b>UIItem</b></i>
| + | |
| − | {| 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>
| + | |
| − | {| 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>
| + | |
| − | {| 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>
| + | |
| − | {| border="1"
| + | |
| − | |-
| + | |
| − | ! Attribute
| + | |
| − | ! Description
| + | |
| − | |-
| + | |
| − | | keySequence
| + | |
| − | | A string defining the sequence of keys used to access 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 enumerated 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').
| + | |
| − | |}
| + | |
| − | | + | |
| − | === Model Rendering ===
| + | |
| − | | + | |
| − | === Model Events ===
| + | |
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.
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)
