Difference between revisions of "Eclipse4/API/UIModel"

From Eclipsepedia

< Eclipse4‎ | API
Jump to: navigation, search
(UI Model)
 
(27 intermediate revisions by 6 users not shown)
Line 5: Line 5:
 
The model itself is based on EMF. One of the things that EMF does a really good job at is allowing multiple inheritance so the basic design of the model starts with low-level components that can then be aggregated into concrete classes.  
 
The model itself is based on EMF. One of the things that EMF does a really good job at is allowing multiple inheritance so the basic design of the model starts with low-level components that can then be aggregated into concrete classes.  
  
The model itself is composed from a number of different type of elements which are used to define the 'concrete' UI elements (i.e. the ones that actually get rendered):
+
The model itself is composed from a number of different type of elements which are used to define the 'concrete' UI elements (i.e. the ones that actually get rendered).
  
== Mix-ins ==
+
The packages that will be promoted to API for the UI model include:
  
Used to contain the attributes for different concepts such as label information or containment types. These will be useful when we eventually start to derive domain-specific models based on the current one.<br>
+
'''org.eclipse.e4.ui.model.workbench'''
 +
*org.eclipse.e4.ui.model.application
 +
*org.eclipse.e4.ui.model.application.commands
 +
*org.eclipse.e4.ui.model.application.ui
 +
*org.eclipse.e4.ui.model.application.ui.advanced
 +
*org.eclipse.e4.ui.model.application.ui.basic
 +
*org.eclipse.e4.ui.model.application.ui.menu
 +
*org.eclipse.e4.ui.model.fragment
 +
 
 +
== Mix-ins  ==
 +
 
 +
Used to contain the attributes for different concepts such as label information or containment types. These will be useful when we eventually start to derive domain-specific models based on the current one.<br>  
 +
 
 +
Context
 +
 
 +
Dirtyable
 +
 
 +
Input
 +
 
 +
UIElement
 +
 
 +
UILabel
 +
 
 +
Item
 +
 
 +
MenuItem
 +
 
 +
ToolItem
 +
 
 +
SnippetContainer
  
 
== Containment Definitions  ==
 
== Containment Definitions  ==
Line 15: Line 44:
 
In order to facilitate the use of Java generics each container may only contain elements of a single 'type' (interface really). These elements represent the type that is legal in a given container. In order to make an element legal for a given container add that container's type as one of the mix-ins for the class being contained.<br>  
 
In order to facilitate the use of Java generics each container may only contain elements of a single 'type' (interface really). These elements represent the type that is legal in a given container. In order to make an element legal for a given container add that container's type as one of the mix-ins for the class being contained.<br>  
  
WindowElement - Elements that can be added to a Window's list of children:
+
WindowElement - Elements that can be added to a Window's list of children:  
  
*Part
+
*Part  
*PartStack
+
*PartStack  
 
*PartSashContainer
 
*PartSashContainer
  
TrimElement - Elements that can be added to a TrimBar
+
TrimElement - Elements that can be added to a TrimBar  
  
*ToolBar
+
*ToolBar  
 
*ToolControl
 
*ToolControl
  
PartSashContainerElement - Elements that can be added to a PartSashContainer<br>
+
PartSashContainerElement - Elements that can be added to a PartSashContainer<br>  
  
*Part
+
*Part  
*PartStack
+
*PartStack  
 
*PartSashContainer (it's recursive)
 
*PartSashContainer (it's recursive)
  
StackElement
+
StackElement - Elements that can be added to a PartStack
 +
 
 +
*Part
 +
*Placeholder
 +
'''''<u>To solve Bug 8009 maybe add PartSashContainer as child of PartStack or define a new element for this [[User:Lars Vogel|Lars.Vogel@gmail.com]]</u>''
 +
 
 +
== Concrete Classes  ==
 +
 
 +
These define the true UI model as used to present an applicaton. The UI Model has been broken down into a number of discrete packages, the sections below will be based on the contents of each package:<br>
 +
 
 +
== Basic UI ==
 +
 
 +
This package contains the most elementary of the UI components:
 +
 
 +
MApplication
 +
 
 +
&nbsp; MWindow '''''Is this really useful? MTrimmedWindow without TrimElements seem to do the same thing [[User:Lars Vogel|Lars.Vogel@gmail.com]]'''''
 +
 
 +
&nbsp; MTrimmedWindow
 +
 
 +
&nbsp;&nbsp;&nbsp; MTrimBar (contained by an MTrimmedWindow but not in its list of children)
 +
 
 +
&nbsp;&nbsp;&nbsp; MPartSashContainer
 +
 
 +
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; MPartStack
 +
 
 +
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; MPart
 +
 
 +
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; MInputPart
 +
 
 +
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; MCompositePart '''''Maybe we need to add this to allow nested parts (bug 396528)?''''' [[User:Szymon.ptaszkiewicz.pl.ibm.com|Szymon.ptaszkiewicz.pl.ibm.com]]
 +
 
 +
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; MToolBar
 +
 
 +
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; MToolControl
 +
 
 +
== &nbsp;Basic UI (Descriptors)<br>  ==
 +
 
 +
This Package contains the 'descriptors' for various elements. Currently only PartDescriptors are supported but over time we may well want to include other types such as PerspectiveDescriptors. Essentially this is the e4 way to capture the set of available views that a user may wish to open and from which the actual MPart can be instantiated.
 +
 
 +
MPartDescriptor '''''<u>This appears as if it should be part of the snippet story</u>''
 +
:+1 to merge it with snippets [[User:Lars Vogel|Lars.Vogel@gmail.com]]
 +
 
 +
== Advanced UI  ==
 +
 
 +
This package contains the elements necessary to support more complex UI's such as are required by the Eclipse IDE itself such as Perspectives and (editor) Areas.
 +
 
 +
MPerspectiveStack
 +
 
 +
&nbsp; MPerspective
 +
 
 +
&nbsp; MPlaceholder
 +
 
 +
MArea
 +
 
 +
== Commands<br> ==
 +
 
 +
This package contains the elements necessary to support the Commands infrastructure. Here a single command is referenced by any number of Handlers (at most one of which will be active in any given UI context.<br>
 +
 
 +
MBindingContext<br>
 +
 
 +
MBindingTable <u>'''''Not sure we want this as API for now since we may want to combine or modify how these are used'''''</u><br>
 +
:While these are related to MBindingContext, they're not the same thing.  These are flat tables of keybindings that are used for lookups. [[User:Pwebster.ca.ibm.com|Pwebster.ca.ibm.com]]
 +
 
 +
MCategory<br>
 +
 
 +
MCommand<br>
 +
 
 +
MCommandParameter<br>
 +
 
 +
MHandler<br>
 +
 
 +
MKeyBinding<br>
 +
 
 +
MParameter '''<u>''Do we need this ?''</u>'''<br>
 +
:Yes. This is used when placing a command in a menu item or keybinding, to specify the parameter (ex: Show View(Package Explorer). [[User:Pwebster.ca.ibm.com|Pwebster.ca.ibm.com]]
 +
 
 +
== Menus (and Toolbars)  ==
 +
 
 +
This package contains the elements used to define menus, toolbars and their corresponding items. There are two flavors for the items, 'direct' and 'handled' based on wether the item is backed by a Command or not.
 +
 
 +
MDirectMenuItem
 +
 
 +
MDirectToolItem
 +
 
 +
MDynamicMenuContribution
 +
 
 +
MHandledMenuItem
 +
 
 +
MHandledToolItem
 +
 
 +
MMenu
 +
 
 +
MMenuContribution <u>'''''This appears as if it should be part of the snippet story'''''</u>
 +
:This is a candidate for snippets if 1) we use the EMF XPath support ('''org.eclipse.e4.emf.xpath''') to specify where they are placed and 2) the snippets are re-evaluated every time a new object is added to the model (we would have to be worried about performance). [[User:Pwebster.ca.ibm.com|Pwebster.ca.ibm.com]]
 +
 
 +
MMenuSeparator
 +
 
 +
MOpaqueMenu <u>'''''This is unnecessary (we can use different renderes for a standard MMenu now)'''''</u>
 +
:This might be replaceable with a tag.  It's a placeholder for a Menu that the compatibility layer creates (and so it needs to be recognized by the renderer but not under its control). [[User:Pwebster.ca.ibm.com|Pwebster.ca.ibm.com]]
 +
 
 +
:+1 to do this via a tag as Paul suggests [[User:Lars Vogel|Lars.Vogel@gmail.com]]
 +
 
 +
MOpaqueMenuItem <u>'''''This is unecessary'''''</u>
 +
:+1 for removal [[User:Lars Vogel|Lars.Vogel@gmail.com]]
 +
 
 +
MOpaqueMenuSeparator <u>'''''This is unnecessary'''''</u>
 +
:+1 for removal [[User:Lars Vogel|Lars.Vogel@gmail.com]]
 +
 
 +
MOpaqueToolItem <u>'''''This is unnecessary'''''</u>
 +
:+1 for removal [[User:Lars Vogel|Lars.Vogel@gmail.com]]
 +
 
 +
MPopupMenu <u>'''''Do we need this...why does a popup menu need a context ?'''''</u>
 +
:Yes, we need a specialized menu that participates in the context hierarchy.  A popup menu is like a child of the part it belongs to, it fills in specialized variable and state that need to be available to any commands executed from it. [[User:Pwebster.ca.ibm.com|Pwebster.ca.ibm.com]]
 +
 
 +
MRenderedMenu <u>'''''This is unnecessary'''''</u>
 +
:This generates an SWT Menu by delegating to an IMenuCreator from the action world (via an IContextFunction).  Maybe it could be replaced with a new renderer.  [[User:Pwebster.ca.ibm.com|Pwebster.ca.ibm.com]]
 +
:+1 for removal [[User:Lars Vogel|Lars.Vogel@gmail.com]]
 +
 
 +
MRenderedMenuItem <u>'''''This is unnecessary'''''</u>
 +
:+1 for removal [[User:Lars Vogel|Lars.Vogel@gmail.com]]
 +
 
 +
MRenderedToolbar <u>'''''This is unnecessary'''''</u>
 +
:+1 for removal [[User:Lars Vogel|Lars.Vogel@gmail.com]]
 +
 
 +
MToolbar
 +
 
 +
MToolBarContribution '''''<u>This appears as if it should be part of the snippet story</u>''
 +
:+1 to merge it with snippets [[User:Lars Vogel|Lars.Vogel@gmail.com]]
 +
 
 +
MToolBarSeparator
 +
 
 +
MToolControl
 +
 
 +
MTrimContribution&nbsp;'''''<u>This appears as if it should be part of the snippet story</u>''
 +
 
 +
:+1 to merge it with snippets [[User:Lars Vogel|Lars.Vogel@gmail.com]]
 +
 
  
== Concrete Classes ==
+
== Other topics added by [[User:Lars Vogel|Lars.Vogel@gmail.com]]  ==
  
These define the true UI model as used to present an applicaton.<br>
+
I think we should add support for Bug 8009 to the model, i.e. allow a PartSashStack as child of PartStack (or have a new model element for this)
  
<br>
+
I think we should have a story for Factories, e.g to create Parts

Latest revision as of 14:36, 13 March 2013

Contents

[edit] UI Model

The UI Model is used to describe the various components of an application's User Interface. This model is an abstract definition that is rendered into reality on a particular platform through the use of a presentation engine driving a set of renderers (usually but not limited to one renderer part UI Model type.

The model itself is based on EMF. One of the things that EMF does a really good job at is allowing multiple inheritance so the basic design of the model starts with low-level components that can then be aggregated into concrete classes.

The model itself is composed from a number of different type of elements which are used to define the 'concrete' UI elements (i.e. the ones that actually get rendered).

The packages that will be promoted to API for the UI model include:

org.eclipse.e4.ui.model.workbench

  • org.eclipse.e4.ui.model.application
  • org.eclipse.e4.ui.model.application.commands
  • org.eclipse.e4.ui.model.application.ui
  • org.eclipse.e4.ui.model.application.ui.advanced
  • org.eclipse.e4.ui.model.application.ui.basic
  • org.eclipse.e4.ui.model.application.ui.menu
  • org.eclipse.e4.ui.model.fragment

[edit] Mix-ins

Used to contain the attributes for different concepts such as label information or containment types. These will be useful when we eventually start to derive domain-specific models based on the current one.

Context

Dirtyable

Input

UIElement

UILabel

Item

MenuItem

ToolItem

SnippetContainer

[edit] Containment Definitions

In order to facilitate the use of Java generics each container may only contain elements of a single 'type' (interface really). These elements represent the type that is legal in a given container. In order to make an element legal for a given container add that container's type as one of the mix-ins for the class being contained.

WindowElement - Elements that can be added to a Window's list of children:

  • Part
  • PartStack
  • PartSashContainer

TrimElement - Elements that can be added to a TrimBar

  • ToolBar
  • ToolControl

PartSashContainerElement - Elements that can be added to a PartSashContainer

  • Part
  • PartStack
  • PartSashContainer (it's recursive)

StackElement - Elements that can be added to a PartStack

  • Part
  • Placeholder

To solve Bug 8009 maybe add PartSashContainer as child of PartStack or define a new element for this Lars.Vogel@gmail.com

[edit] Concrete Classes

These define the true UI model as used to present an applicaton. The UI Model has been broken down into a number of discrete packages, the sections below will be based on the contents of each package:

[edit] Basic UI

This package contains the most elementary of the UI components:

MApplication

  MWindow Is this really useful? MTrimmedWindow without TrimElements seem to do the same thing Lars.Vogel@gmail.com

  MTrimmedWindow

    MTrimBar (contained by an MTrimmedWindow but not in its list of children)

    MPartSashContainer

      MPartStack

         MPart

         MInputPart

         MCompositePart Maybe we need to add this to allow nested parts (bug 396528)? Szymon.ptaszkiewicz.pl.ibm.com

        MToolBar

        MToolControl

[edit]  Basic UI (Descriptors)

This Package contains the 'descriptors' for various elements. Currently only PartDescriptors are supported but over time we may well want to include other types such as PerspectiveDescriptors. Essentially this is the e4 way to capture the set of available views that a user may wish to open and from which the actual MPart can be instantiated.

MPartDescriptor This appears as if it should be part of the snippet story

+1 to merge it with snippets Lars.Vogel@gmail.com

[edit] Advanced UI

This package contains the elements necessary to support more complex UI's such as are required by the Eclipse IDE itself such as Perspectives and (editor) Areas.

MPerspectiveStack

  MPerspective

  MPlaceholder

MArea

[edit] Commands

This package contains the elements necessary to support the Commands infrastructure. Here a single command is referenced by any number of Handlers (at most one of which will be active in any given UI context.

MBindingContext

MBindingTable Not sure we want this as API for now since we may want to combine or modify how these are used

While these are related to MBindingContext, they're not the same thing. These are flat tables of keybindings that are used for lookups. Pwebster.ca.ibm.com

MCategory

MCommand

MCommandParameter

MHandler

MKeyBinding

MParameter Do we need this ?

Yes. This is used when placing a command in a menu item or keybinding, to specify the parameter (ex: Show View(Package Explorer). Pwebster.ca.ibm.com

[edit] Menus (and Toolbars)

This package contains the elements used to define menus, toolbars and their corresponding items. There are two flavors for the items, 'direct' and 'handled' based on wether the item is backed by a Command or not.

MDirectMenuItem

MDirectToolItem

MDynamicMenuContribution

MHandledMenuItem

MHandledToolItem

MMenu

MMenuContribution This appears as if it should be part of the snippet story

This is a candidate for snippets if 1) we use the EMF XPath support (org.eclipse.e4.emf.xpath) to specify where they are placed and 2) the snippets are re-evaluated every time a new object is added to the model (we would have to be worried about performance). Pwebster.ca.ibm.com

MMenuSeparator

MOpaqueMenu This is unnecessary (we can use different renderes for a standard MMenu now)

This might be replaceable with a tag. It's a placeholder for a Menu that the compatibility layer creates (and so it needs to be recognized by the renderer but not under its control). Pwebster.ca.ibm.com
+1 to do this via a tag as Paul suggests Lars.Vogel@gmail.com

MOpaqueMenuItem This is unecessary

+1 for removal Lars.Vogel@gmail.com

MOpaqueMenuSeparator This is unnecessary

+1 for removal Lars.Vogel@gmail.com

MOpaqueToolItem This is unnecessary

+1 for removal Lars.Vogel@gmail.com

MPopupMenu Do we need this...why does a popup menu need a context ?

Yes, we need a specialized menu that participates in the context hierarchy. A popup menu is like a child of the part it belongs to, it fills in specialized variable and state that need to be available to any commands executed from it. Pwebster.ca.ibm.com

MRenderedMenu This is unnecessary

This generates an SWT Menu by delegating to an IMenuCreator from the action world (via an IContextFunction). Maybe it could be replaced with a new renderer. Pwebster.ca.ibm.com
+1 for removal Lars.Vogel@gmail.com

MRenderedMenuItem This is unnecessary

+1 for removal Lars.Vogel@gmail.com

MRenderedToolbar This is unnecessary

+1 for removal Lars.Vogel@gmail.com

MToolbar

MToolBarContribution This appears as if it should be part of the snippet story

+1 to merge it with snippets Lars.Vogel@gmail.com

MToolBarSeparator

MToolControl

MTrimContribution This appears as if it should be part of the snippet story

+1 to merge it with snippets Lars.Vogel@gmail.com


[edit] Other topics added by Lars.Vogel@gmail.com

I think we should add support for Bug 8009 to the model, i.e. allow a PartSashStack as child of PartStack (or have a new model element for this)

I think we should have a story for Factories, e.g to create Parts