View source for Efxclipse/Runtime/e4

{{Efxclipse}}

= General =

== Rendering Tags ==

Some of the model elements can be enhanced with special kind of values to influence the renderers to provide behavior very specific zu JavaFX

=== MUIElement ===
The renderes translate the following stuff in CSS-Selectors
* <code>MApplicationElement#elementId</code> is translated to the an id-selector (dots are replaced by - e.g. <code>my.app.window</code> is translated to #my-app-window)
* Model-Element-Classname (<code>MPart</code>, <code>MWindow</code>, <code>MTrimmedWindow</code>) is translated to a class-selector (<code>.MPart</code>, <code>.MWindow</code>, <code>.MTrimmedWindow</code>)
* Tags starting with <code>efx_styleclass:${name}</code> are translated to class-selectors e.g. <code>efx_styleclass:MyHome</code> is translated to <code>.MyHome</code>

=== MWindow  ===
{| class="table table-bordered" cellspacing="0" cellpadding="5"
|-
!Title
!Slot
!Value
!Since
!Description
|-
| efx.window.scene.3d
| persistedState
| boolean
| 0.9.0
| If you want to enable depthBuffering in your the windows scene you should pass true here
|-
| efx.window.root.fxml
| persistedState
| url
| 0.9.0
| In case you want to customize the main window UI (placement of menubar & trims, decoration, ...) you need to pass the url to an FXML that has a root element of one of the following types:  <code>javafx.scene.layout.BorderPane</code> for placement control or <code>org.eclipse.fx.ui.controls.stage.TrimmedWindow</code> if you also want control over the window decorations 
|-
| efx.window.decoration.fxml ('''DEPRECATED''')
| persistedState
| url
| 0.9.0
| In case you want to show a custom window decoration you should pass an URL to a fxml-File to be used. Use efx.window.root.fxml
|-
| efx.window.undecorated ('''DEPRECATED''')
| persistedState
| boolean
| 0.9.0
| '''DEPRECATED''' If you want the stage representing the window created with out any StageStyle.UNDECORATED you should pass true for it. Use 'efx.window.stagestyle'
|- 
| efx.window.stagestyle
| persistedState
| String (one of the value in javafx.stage.StageStyle)
| 1.0.0
| Allows you to define the stage-style to use Stage.initStyle. The allowed values are those defined in javafx.stage.StageStyle
|-
| efx.window.fullscreen
| persistedState
| boolean
| 0.9.0
| If set puts the stage into a window into fullscreen mode
|-
| shellMaximized
| tags
| -
| 1.0.0
| This tag is provided for SWT-Renderer compability
|- 
| efx.window.stagemodality
| persistedState
| String (one of the value in javafx.stage.Modality)
| 2.0.0
| Allows you to define the stage-style to use Stage.initModality. The allowed values are those defined in javafx.stage.Modality
|-
| efx-lightweight-dialogs
| tags
| -
| 2.0.0
| This tag makes dialogs (eg. the save dialog shown as lightweight dialogs)
|}

=== MPartSashContainer ===

{| class="table table-bordered" cellspacing="0" cellpadding="5"
|-
!Title
!Slot
!Value
!Since
!Description
|-
| fx_fixedLayout
| tags
| -
| 0.9.0
| If you add this tag to a MPartSashContainer it will be rendered using a fixed layout (it isn't a Sash anymore but uses a LayoutPane)
|}

=== MPartSashContainerElement ===

{| class="table table-bordered" cellspacing="0" cellpadding="5"
|-
!Title
!Slot
!Value
!Since
!Description
|-
| fx_layout_width
| persistedState
| double
| 0.9.0
| The value is an absolute width this widget will use in the parent (MPartSashContainer tagged with "fx_fixedLayout")
|-
| fx_layout_height
| persistedState
| double
| 0.9.0
| The value is an absolute height this widget will use in the parent (MPartSashContainer tagged with "fx_fixedLayout")
|-
| fx_layout_grab_horizontal
| persistedState
| boolean
| 0.9.0
| If set to true the element grabs all free horizontal space (MPartSashContainer tagged with "fx_fixedLayout")
|-
| fx_layout_grab_vertical
| persistedState
| boolean
| 0.9.0
| If set to true the element grabs all free vertical space (MPartSashContainer tagged with "fx_fixedLayout")
|}

=== MPart ===

By default the container injected in <code>javafx.scene.layout.BorderPane</code> instance 

{| class="table table-bordered" cellspacing="0" cellpadding="5"
|-
!Title
!Slot
!Value
!Since
!Description
|-
| Part-Toolbar-FullSpan
| tags
| -
| 0.9.0
| If this tag is added to the MPart the toolbar is spanning the complete width of the part
|-
| Part-ToolBarMenu-Floating
| tags
| -
| 0.9.0
| If this tag is added to the MPart the toolbar is floating above the parts content and can be collapsed
|-
| Part-ToolBarMenu-Bottom
| tags
| -
| 0.9.0
| If this tag is added to the MPart the toolbar is rendered at the bottom instead of the top
|-
| Lifecycle URL
| tags
| EFX_LC:$URL$
| 0.9.0
| If you add a tag starting with EFX_LC: and an URL like e.g. bundleclass://my.bundle/my.lifecycle.Handler the methods @PreShow and @PreClose will be called at the appropriate time
|-
| Container:AnchorPane
| tags
| -
| 0.9.0
| If this tag is set the container passed to the contribution is an AnchorPane
|-
| Container:FlowPane
| tags
| -
| 0.9.0
| If this tag is set the container passed to the contribution is an FlowPane
|-
| Container:GridPane
| tags
| -
| 0.9.0
| If this tag is set the container passed to the contribution is an GridPane
|-
| Container:HBox
| tags
| -
| 0.9.0
| If this tag is set the container passed to the contribution is an HBox
|-
| Container:StackPane
| tags
| -
| 0.9.0
| If this tag is set the container passed to the contribution is an StackPane
|-
| Container:VBox
| tags
| -
| 0.9.0
| If this tag is set the container passed to the contribution is an VBox
|-
| Container:FillLayoutPane
| tags
| -
| 0.9.0
| If this tag is set the container passed to the contribution is an org.eclipse.fx.ui.panes.FillLayoutPane
|-
| Container:GridLayoutPane
| tags
| -
| 0.9.0
| If this tag is set the container passed to the contribution is an org.eclipse.fx.ui.panes.GridLayoutPane
|-
| Container:RowLayoutPane
| tags
| -
| 0.9.0
| If this tag is set the container passed to the contribution is an org.eclipse.fx.ui.panes.RowLayoutPane
|-
| Container:SashLayoutPane
| tags
| -
| 0.9.0
| If this tag is set the container passed to the contribution is an org.eclipse.fx.ui.panes.SashLayoutPane
|-
| Container:UrlPane:$URL$
| tags
| -
| 0.9.0
| If this tag is set the container passed to the contribution is an instance of the class provided through the URL e.g. bundleclass://my.container/my.layout.Pane the contributed class has to be a subclass of javafx.scene.layout.Pane
|-
| showTopTrimArea
| tags
| -
| 2.2.0
| If this tag is set the title/graphic of the view is shown in the top area of the view area

|}

=== MToolItem ===
{| class="table table-bordered" cellspacing="0" cellpadding="5"
|-
!Title
!Slot
!Value
!Since
!Description
|-
| fx_checkbox
| tags
| -
| 0.9.0
| If the ItemType is CHECKBOX and the tag is used a real checkbox is used (by default it is a toggle-button)
|}

=== MTrimElement ===
{| class="table table-bordered" cellspacing="0" cellpadding="5"
|-
!Title
!Slot
!Value
!Since
!Description
|-
| fillspace
| tags
| -
| 0.9.0
| If this tag is added to the MTrimElement it will fill the remaining space in the trim
|}

=== MPartStack ===
{| class="table table-bordered" cellspacing="0" cellpadding="5"
|-
!Title
!Slot
!Value
!Since
!Description
|-
| fx_pagination
| tags
| -
| 0.9.0
| If this tag is added to the MPartStack it will be rendered using a pagination control instead of a TabFolder
|-
| fx_tab_closing_policy_unavailable
| tags
| -
| 1.1.0
| If this tag is added to the MPartStack the tab pane will not have a close button, therefore it will not be possible to close part ( see: http://docs.oracle.com/javafx/2/api/javafx/scene/control/TabPane.TabClosingPolicy.html )
|-
| fx_tab_closing_policy_selectedTab
| tags
| -
| 1.1.0
| If this tag is added to the MPartStack only the selected tab will have a close button ( see: http://docs.oracle.com/javafx/2/api/javafx/scene/control/TabPane.TabClosingPolicy.html )
|-
| fx_tab_closing_policy_allTabs
| tags
| -
| 1.1.0
| If this tag is added to the MPartStack all the tabs on the tab pan will have close buttons ( see: http://docs.oracle.com/javafx/2/api/javafx/scene/control/TabPane.TabClosingPolicy.html )
|-
| fx.stack.tabslocation
| persistedState
| TOP, BOTTOM, LEFT, RIGHT
| 2.3.0
|
|}

=== MPerspective ===
{| class="table table-bordered" cellspacing="0" cellpadding="5"
|-
!Title
!Slot
!Value
!Since
!Description
|-
| Lifecycle URL
| tags
| EFX_LC:$URL$
| 0.9.0
| If you add a tag starting with EFX_LC: and an URL like e.g. bundleclass://my.bundle/my.lifecycle.Handler the methods @PreShow and @PreClose will be called at the appropriate time
|}

=== MMenuBar ===
{| class="table table-bordered" cellspacing="0" cellpadding="5"
|-
!Title
!Slot
!Value
!Since
!Description
|-
| fx.menubar.native
| persistedState
| boolean
| 0.9.0
| If you set this persistedState key to true the menubar will be renderer as a native OS-X menubar. '''WARNING''' currently this only works reliably when you have a one window application
|}

=== MMenu ===
{| class="table table-bordered" cellspacing="0" cellpadding="5"
|-
!Title
!Slot
!Value
!Since
!Description
|-
| Lifecycle URL
| tags
| EFX_LC:$URL$
| 0.9.0
| If you add a tag starting with EFX_LC: and an URL like e.g. bundleclass://my.bundle/my.lifecycle.Handler the methods @PreShow and @PreClose will be called at the appropriate time
|}

=== MPopupMenu ===
{| class="table table-bordered" cellspacing="0" cellpadding="5"
|-
!Title
!Slot
!Value
!Since
!Description
|-
| Tab Menu
| tags
| tabmenu
| 2.4.0
| If you tag a menu on a part with 'tabmenu' it will be rendered as a menu on the respective TabPane
|}

=== MToolControl ===

By default the container injected in <code>javafx.scene.Group</code> instance

{| class="table table-bordered" cellspacing="0" cellpadding="5"
|-
!Title
!Slot
!Value
!Since
!Description
|-
| Container:AnchorPane
| tags
| -
| 0.9.0
| If this tag is set the container passed to the contribution is an AnchorPane
|-
| Container:FlowPane
| tags
| -
| 0.9.0
| If this tag is set the container passed to the contribution is an FlowPane
|-
| Container:GridPane
| tags
| -
| 0.9.0
| If this tag is set the container passed to the contribution is an GridPane
|-
| Container:HBox
| tags
| -
| 0.9.0
| If this tag is set the container passed to the contribution is an HBox
|-
| Container:StackPane
| tags
| -
| 0.9.0
| If this tag is set the container passed to the contribution is an StackPane
|-
| Container:VBox
| tags
| -
| 0.9.0
| If this tag is set the container passed to the contribution is an VBox
|-
| Container:FillLayoutPane
| tags
| -
| 0.9.0
| If this tag is set the container passed to the contribution is an org.eclipse.fx.ui.panes.FillLayoutPane
|-
| Container:GridLayoutPane
| tags
| -
| 0.9.0
| If this tag is set the container passed to the contribution is an org.eclipse.fx.ui.panes.GridLayoutPane
|-
| Container:RowLayoutPane
| tags
| -
| 0.9.0
| If this tag is set the container passed to the contribution is an org.eclipse.fx.ui.panes.RowLayoutPane
|-
| Container:SashLayoutPane
| tags
| -
| 0.9.0
| If this tag is set the container passed to the contribution is an org.eclipse.fx.ui.panes.SashLayoutPane
|-
| Container:UrlPane:$URL$
| tags
| -
| 0.9.0
| If this tag is set the container passed to the contribution is an instance of the class provided through the URL e.g. bundleclass://my.container/my.layout.Pane the contributed class has to be a subclass of javafx.scene.layout.Pane
|}

= Lifecycle =

Certain renderers based on the efxclipse generic ones support the idea of a lifecycle (Show/Hide/...). We decided no to introduce a new mixin ourselves to support the lifecycle for now but abuse the tags for it because we expect to work with the upstream project on a general solution. Currently the following renderers support lifecycle:
* MMenu
* MPerspective
* MPart

There are 2 ways to register a lifecycle:
* declartive via e4xmi: by adding a tag to the element which starts with EFX_LC: followed by a URL to the lifecycle class
* programmaticall via ELifecycleService: Grab the service and register an lifecylce class using the same URL you'd have used for the tag

= None standard Services =

== PopupMenuService (removed with 1.0.0) ==

The has the same feature as the EMenuService from e4 on SWT but because the service definition is found in a bundle which has a dependency on SWT we had to invent our own one.

'''Since 1.0.0 you should use the EMenuService from the Eclipse Application Platform'''

== ELifecycleService ==

=== Registration ===

==== Programmatically ====
Allows to register/unregister lifecycle handlers on model elements using <code>ELifecycleService#registerLifecycleURI</code> and <code>ELifecycleService#unregisterLifecycleContribution</code>.

==== Through the application model ====

Instead of registering lifecycle additions through the service one can add the <code>org.eclipse.fx.ui.workbench.services.lifecycle.LifecycleAddon</code> who processes all elements in the application model searching for <code>tags</code> starting with the <code>LFC:</code> prefix (eg [[#MMenu]], [[#MPerspective]], ...). It also tracks additions to the model eg if a part is added through an <code>MPartDescriptor</code>.

For an <code>MPart</code> it might look like this in the e4xmi-File:
<source lang="xml">
  <children xsi:type="basic:Part" elementId="samplepart" 
    contributionURI="bundleclass://my.sample.app/my.sample.app.parts.PartPreClose" 
    label="My Part" closeable="true">
        <tags>EFX_LC:bundleclass://my.sample.app/my.sample.app.parts.PartLF</tags>
  </children>
</source>

and the handler like this:
<source lang="java">
public class PartLF {
  @PreClose
  public boolean preClose() {
    // Check if we can close
    return false;
  }
}
</source>

Elements who themselves define Object-Contributions (anyone inheriting from <code>MContribution</code>) can use lifecycle annotations directly within their implementation. 

So a Part could look like this:
<source lang="java">
public class Part {
  @PostConstruct
  void initUI(BorderPane parent) {
    // ...
  }

  @PreClose
  public boolean preClose() {
    // Check if we can close
    return false;
  }
}
</source>

With the draw back that your code is getting a dependency on <code>org.eclipse.fx.ui.workbench.services.lifecycle</code> so we advice to go with this solution only in very rare cases.

=== Evaluation ===
To evaluate an lifecycle annotation components like the e4 renderer will invoke <code>ELifecycleService#validateAnnotation</code> at certain points. To calculate <code>true</code>/<code>false</code> the service implementation in the following order:
* In case the provided <code>MUIElement</code> is a <code>MContribution</code> it tries to invoke the annotated method on the contribution object
* Execute all lifecycle instance registered on the object

== PerspectiveTransitionService / WindowTransitionService ==

Those 2 services allow you to control how perspective transitions and window open/close transition are done. The renderes will look up the service from the MApplications IEclipseContext and if one available use it.

== DnDFeedbackService ==

The feedback service is responsible to show the drag and drop feedback. If your are not happy with the default implementation provided simply contribute your custom version to the OSGi-Service registry with a ranking &gt; 0

= Missing Features / Services =

Some of the features implemented in e4 on SWT are not yet available in the JavaFX version. Due lack of time/funding and to some extend also due to features not yet available in JavaFX itself:
* MinMax support: There's feature request in bugzilla [https://bugs.eclipse.org/bugs/show_bug.cgi?id=409340] but there've not been enough time yet to implement it.
* DnD support: With e(fx)clipse 1.2 support to rearrange the UI was added although JavaFX by default does not supports it [https://javafx-jira.kenai.com/browse/RT-31574] compared to SWT support for detaching views using DnD is still missing.

In case you miss a feature from SWT and/or you have an idea of a new feature file bug reports and link them in this section. We'll do our best to get features in but can promise unless you decide to fund the implementation