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 "GEF/GEF4/MVC"

< GEF‎ | GEF4
m
m
Line 80: Line 80:
 
* '''package: org.eclipse.gef4.mvc.domain'''
 
* '''package: org.eclipse.gef4.mvc.domain'''
  
The domain package contains the IDomain interface and an abstract base implementation AbstractDomain.
+
The domain package contains the IDomain interface and an abstract base implementation AbstractDomain. The domain represents the collective state of an MVC application, i.e. it is composed of all viewers and tools. Additionally, the domain provides an operation history and undo context, which are used by policies to change the state of the application.
  
 
----
 
----
Line 142: Line 142:
  
 
==== ClearHoverFocusSelectionOperation ====
 
==== ClearHoverFocusSelectionOperation ====
 +
 +
==== DetachFromContentAnchorageOperation ====
 +
 +
==== ForwardUndoCompositeOperation ====
 +
 +
==== RemoveContentChildOperation ====
 +
 +
==== ReverseUndoCompositeOperation ====
 +
 +
==== SetRefreshVisualOperation ====
 +
 +
==== SynchronizeContentAnchoragesOperation ====
 +
 +
==== SynchronizeContentChildrenOperation ====
 +
 +
==== UnexecutableOperation ====
  
 
----
 
----
Line 334: Line 350:
 
* Separation of interaction policies (directly invoked by tools, related to interaction) and transaction policies (called by interaction policies, realize the content manipulation)
 
* Separation of interaction policies (directly invoked by tools, related to interaction) and transaction policies (called by interaction policies, realize the content manipulation)
 
* Pure interaction-gesture-based tools without own transactional logic (compared to monolithic 'selection tool')
 
* Pure interaction-gesture-based tools without own transactional logic (compared to monolithic 'selection tool')
 +
 +
[[Category:GEF]]

Revision as of 03:34, 22 May 2015

Note to non-wiki readers: This documentation is generated from the Eclipse wiki - if you have corrections or additions it would be awesome if you added them in the original wiki page.


Introduction

The GEF4 MVC component provides support for building up graphical editors and views based on a model-view-controller architecture and is the intended replacement for GEF (MVC) 3.x. It is internally composed out of four modules, which provide toolkit-independent base abstractions and implementations (MVC), JavaFX-specific specializations (MVC.FX), and Eclipse UI-integration for both (MVC.UI, MVC.FX.UI). In addition there is a deployed MVC Logo Example.


MVC

  • bundle: org.eclipse.gef4.mvc

The MVC plug-in offers those core concepts that are independent of any concrete rendering toolkit as well as of the Eclipse UI. As indicated by its name, the module provides a model-view-controller architecture that can be used to build up graphical editors and views. In good tradition with GEF (MVC) 3.x, 'controllers' are referred to as 'parts' (while the term 'visual part' instead of 'edit part' is used here, to depict that the MVC framework is not limited to editors alone).

A graphical application is thus composed of one or more viewers, where each viewer (IViewer) is populated by a set of visual parts (IVisualPart), which control the visuals that are rendered inside the viewer's controls. Those of the visual parts, which are responsible of controlling to be visualized contents, are referred to as content parts (IContentPart). They are accompanied by feedback parts (IFeedbackPart) and handle parts (IHandlePart), which do not control visualized contents but feedback or handle visuals that are needed for user interaction. All visual parts are arranged in a hierarchy (which resembles the hierarchy of visuals), which is rooted by a 'root part' (IRootPart).

Besides the parent-child relationship that establishes the hierarchy, visual parts may also be related to each other by means of an anchorage-anchor relationship. That is, a visual part that is placed at an arbitrary location within the hierarchy may be anchored on another anchorage part. As the visual part hierarchy has to correspond to the visual hierarchy, this mechanism is very useful when parts that control visuals that are placed in arbitrary places within the visual hierarchy have to be related to each other. In a graphical application that usually organizes visuals into layers, it can for instance be intensively used to update feedback or handles. By explicitly anchoring a feedback part on an underlying (anchorage) target content part, the feedback part inter alia obtains the necessary hooks to listen for changes of the content part visual (e.g. a position change) and to update its own feedback visual accordingly.

Tools (ITool) are used to interact with the parts inside a viewer. Each tool should be responsible of handling a certain interaction gesture (e.g. mouse click/drag or touch-based pinch/spread), by locating respective target parts (e.g. via hit-testing on the visual) and forwarding the interaction to them. While a tool should not have own interaction logic, it is responsible of handling the interaction, to which several parts may contribute e.g. by updating their contents, as a whole. That is, the tool has to ensure that all content modifying operations that result from a certain interaction, are executed in a single (undoable) transaction. As an interaction may span several viewers (e.g. a drag/drop operation), tools are bound to a domain (IDomain), to which also all viewers that make up a graphical application are bound, that maintains a global operation history and facilities to initialize and commit transactions.

The handling of an interaction is not performed directly by the target visual parts themselves, but by respective (interaction) policies (IPolicy) that are bound to them. An interaction policy is a strategy that encapsulates a certain (exchangeable) interaction logic, related to a gesture (e.g. what to do on click/drag). The active tool that handles an interaction takes this into account when forwarding the interaction, as it locates target parts also by evaluating their supported policies, and interacts with these policies directly. An (interaction) policy may handle an interaction directly, e.g. by manipulating the viewer state (e.g. changing the current selection when the target part gets clicked). It may also delegate to certain (transaction) policies that manipulate the contents as a result of an interaction (and have to do this by means of executing operations within the currently active transaction, the respective interaction tool has opened via the domain).

The viewer state (e.g. the current selection), which might be manipulated as the result of an interaction, is represented by means of dedicated models (ContentModel, SelectionModel, ViewportModel, etc.), which are bound to each viewer. As changes to the viewer state, as well as to the visualized contents, may lead to necessary viewer updates as well, behaviors (Behavior) may be bound to parts similar to policies. In contrast to policies, behaviors are active themselves, that is they will actively listen for changes (e.g. newly added content). Behaviors are also responsible of creating and disposing respective visual parts as needed (e.g. to update selection feedback as a result of changes to the selection model).


{root}

  • package: org.eclipse.gef4.mvc

The root package contains a Guice Module which defines the default bindings for MVC.

MvcModule

The MvcModule defines methods to register bindings for different types (IBehavior, IVisualPart, etc.) which can be refined (overridden) by sub-classes. Additionally, it registers bindings for the ContentModel, ViewportModel, and GridModel.


Behaviors

  • package: org.eclipse.gef4.mvc.behaviors

The behaviors package contains the IBehavior and AbstractBehavior definitions. Additionally, it provides various IBehavior implementations and a utility class for IBehaviors.

IBehavior

Every IBehavior is bound to an IVisualPart, referred to as the host of the behavior. A behavior is meant to be registering change listeners on a model (e.g. SelectionModel, ContentModel, etc.) during its activation (and unregistering them during its deactivation). It will then update another model (e.g. the visualization) based on the changes to the first model. For example, the SelectionBehavior registers a listener on the SelectionModel and generates (or removes) selection feedback based on the changes reported by the listener.

AbstractBehavior

The AbstractBehavior handles activation and provides methods to add/remove feedback and handle parts using the IFeedbackPartFactory and IHandlePartFactory of the viewer.

BehaviorUtils

The BehaviorUtils class provides utility methods for establishing/unestablishing anchored-anchorage relations. These methods are used by the AbstractBehavior when adding/removing feedback or handles.

ContentBehavior

The ContentBehavior is listening for ContentModel changes to initiate a content synchronization upon changes. During a content synchronization, the currently active content parts are checked against the current content objects, i.e. content parts are created or removed based on the parent-child and anchored-anchorage relations between the content objects as defined by the content parts.

A content part that is removed is stored in a ContentPartPool, so that it can be re-used if it is needed later, and does not have to be re-created.

HoverBehavior

The HoverBehavior reacts to HoverModel changes. It can be bound to all content parts that should generate feedback/handles when the mouse hovers the part.

SelectionBehavior

The SelectionBehavior reacts to SelectionModel changes. It can be bound to all content parts that should generate feedback/handles when the part is selected.


Domain

  • package: org.eclipse.gef4.mvc.domain

The domain package contains the IDomain interface and an abstract base implementation AbstractDomain. The domain represents the collective state of an MVC application, i.e. it is composed of all viewers and tools. Additionally, the domain provides an operation history and undo context, which are used by policies to change the state of the application.


Models

  • package: org.eclipse.gef4.mvc.models

The models package contains all viewer models, i.e. the data constituting a viewer state.

ContentModel

The ContentModel stores the viewer's contents, i.e. the data that is processed by your application.

FocusModel

The FocusModel stores the IVisualPart with keyboard focus, i.e. the part that will receive all keyboard input.

GridModel

The GridModel stores the viewer's background grid settings:

  • snap-to-grid, true or false, indicates whether the visualization should snap to grid points.
  • show-grid, true or false, indicates whether to show the grid, or not.
  • zoom-grid, true or false, indicates whether to zoom the grid, or not.
  • grid-cell-width, Double, specifies the width of grid cells.
  • grid-cell-height, Double, specifies the height of grid cells.

HoverModel

The HoverModel stores the currently hovered IVisualPart.

SelectionModel

The SelectionModel stores all currently selected IContentParts.

ViewportModel

The ViewportModel stores the current viewport information, i.e. a scroll offset and a viewport transformation.


Operations

  • package: org.eclipse.gef4.mvc.operations

The operations package contains implementations of IUndoableOperation which can be used to manipulate the default models, especially content creation and removal.

AbstractCompositeOperation

AddContentChildOperation

AttachToContentAnchorageOperation

ChangeFocusOperation

ChangeHoverOperation

ChangeSelectionOperation

ClearHoverFocusSelectionOperation

DetachFromContentAnchorageOperation

ForwardUndoCompositeOperation

RemoveContentChildOperation

ReverseUndoCompositeOperation

SetRefreshVisualOperation

SynchronizeContentAnchoragesOperation

SynchronizeContentChildrenOperation

UnexecutableOperation


Parts

  • package: org.eclipse.gef4.mvc.parts

The parts package contains all IVisualPart abstractions.


Policies

  • package: org.eclipse.gef4.mvc.policies

The policies package contains the IPolicy (and AbstractPolicy) abstraction and concrete implementations for the manipulation of the ContentModel: ContentPolicy, CreationPolicy, and DeletionPolicy.


Tools

  • package: org.eclipse.gef4.mvc.tools

The tools package contains the ITool (and AbstractTool) abstraction.


Viewer

  • package: org.eclipse.gef4.mvc.viewer

The viewer package contains the IViewer (and AbstractViewer) abstraction.


MVC.FX

  • bundle: org.eclipse.gef4.mvc.fx

The MVC.FX module provides specializations of the abstractions and implementations provided by MVC, which are bound to JavaFX-based visualizations.


{root}

  • package: org.eclipse.gef4.mvc.fx

The root pacakge contains a Guice Module with default bindings for MVC.FX.


Behaviors

  • package: org.eclipse.gef4.mvc.fx.behaviors

The behaviors package contains JavaFX/MVC.FX-specific IBehavior implementations.

FXCursorBehavior

The FXCursorBehavior is listening for mouse and keyboard input, so that it can change the JavaFX mouse cursor when the user presses/releases a key while moving the mouse.

FXFocusBehavior

The FXFocusBehavior is listening for FocusModel changes and transfers them over to JavaFX.

FXGridBehavior

The FXGridBehavior is listening for GridModel changes in order to apply those changes to the GridLayout of the viewer.

FXHoverBehavior

The FXHoverBehavior is listening for HoverModel changes in order to generate feedback/handles when hovering a part.

FXViewportBehavior

The FXViewportBehavior is listening for ViewportModel changes and transfers them over to the ScrollPaneEx of the viewer.


Domain

  • package: org.eclipse.gef4.mvc.fx.domain

org.eclipse.gef4.mvc.fx.domain contains a JavaFX-specific IDomain implementation.


Operations

  • package: org.eclipse.gef4.mvc.fx.operations

org.eclipse.gef4.mvc.fx.operations contains all IUndoableOperation implementations contributed by MVC.FX.


Parts

  • package: org.eclipse.gef4.mvc.fx.parts

org.eclipse.gef4.mvc.fx.parts contains all IContentPart, IVisualPart, IFeedbackPart, and IHandlePart implementations and related classes.


Policies

  • package: org.eclipse.gef4.mvc.fx.policies

org.eclipse.gef4.mvc.fx.policies contains all IPolicy implementations contributed by MVC.FX.


Tools

  • package: org.eclipse.gef4.mvc.fx.tools

org.eclipse.gef4.mvc.fx.tools contains JavaFX-specific ITool implementations for different interactions (e.g. mouse drag).


Viewer

  • package: org.eclipse.gef4.mvc.fx.viewer

org.eclipse.gef4.mvc.fx.viewer contains a JavaFX-specific IViewer implementation.


MVC.UI

  • bundle: org.eclipse.gef4.mvc.ui

The MVC.UI module provides aspects for an integration into the Eclipse UI:

  • Binding the operation history from the Eclipse Workbench.
  • An UndoablePropertySheetPage for contribution to the "Properties View".

MVC.FX.UI

  • bundle: org.eclipse.gef4.mvc.fx.ui

The MVC.FX.UI module provides JavaFX-specific aspects for an integration into the Eclipse UI:

  • org.eclipse.gef4.mvc.fx.ui contains a Guice Module which binds an Eclipse ISelectionProvider and handles the construction of an FXCanvas to render the JavaFX scene graph.
  • org.eclipse.gef4.mvc.fx.ui.parts contains spcific Eclipse ViewPart and EditorPart implementations which wrap an FXCanvas.
  • org.eclipse.gef4.mvc.fx.ui.properties contains helper classes for the integration and manipulation of properties within the Eclipse "Properties View".
  • org.eclipse.gef4.mvc.fx.ui.viewer provides an ISceneContainer implementation for the propagation of a JavaFX Scene to an FXCanvas.

Logo Example (Standalone, Eclipse UI, Web)

The GEF4 MVC Logo example demonstrates the interplay of all MVC components (i.e. MVC, MVC.FX, MVC.UI, and MVC.FX.UI), and is also based on other GEF4 components. It comes in three variants:

  • A standalone JavaFX application (org.eclipse.gef4.mvc.examples.logo.MvcLogoExample)

GEF4 MVC FX Example.png

The standalone JavaFX application is only indirectly-bundled on our update-site and can better be checked out in source (org.eclipse.gef4.mvc.examples.logo) from our GEF4 Git repository. In order to have the example plug-in compile properly, all other required GEF4 bundles will either have to be installed (in a matching version) into your running eclipse platform, added to a target definition (the already provided in the active target platform (the provided target definitions may be augmented for this purpose), or checked out in source as well. You will also have to install e(fx)clipse in your running eclipse instance and target platform (see GEF Project Contributor Guide for details on how to obtain the sources and setup your workspace). Having prepared everything as outlined before, the standalone example might easily be started by launching org.eclipse.gef4.mvc.examples.logo.MvcLogoExample via the context menu ('Run As' -> 'Java Application').

  • An extended version in the form of an Eclipse view (org.eclipse.gef4.mvc.examples.logo.ui), which integrates with the Eclipse Workbench operation history as well as the Eclipse UI properties view)

GEF4 MVC FX UI Example.png

The Eclipse UI-integrated version can simply be installed from our update-sites. It can then easily be accessed in your runtime eclipse application via the Window->Show View->Other... menu, where it is located in the Other category.

  • A web-integrated version of the standalone application, embedded into a web page (via Java WebStart)

GEF4 MVC FX Example Web.png

The web-integrated version of the standalone example is provided in a bundled form on hudson.eclipse.org and can be accessed at https://hudson.eclipse.org/hudson/job/gef4-master/lastSuccessfulBuild/artifact/org.eclipse.gef4.mvc.examples.logo.web-files/index.html. You will need to have the Java plug-in installed into your browser, and you may have to adjust your Java plug-in security settings to allow java content for the respective url.


Migration from GEF (MVC) 3.x to MVC, MVC.FX, MVC.UI, MVC.FX.UI

GEF4 MVC was written completely from scratch. While some proven concepts have been transferred from GEF (MVC) 3.x, central concepts and mechanisms have been reworked. The most notable differences are:

  • More modularity, separating out Eclipse Workbench UI dependencies
  • Usage of adapter pattern throughout
  • Usage of dependency injection
  • Own visual parts for feedback and handles (compared to 'lightweight' feedback)
  • Separation of policies (passive, invoked by tools) and behaviors (active, listening for changes)
  • Separation of interaction policies (directly invoked by tools, related to interaction) and transaction policies (called by interaction policies, realize the content manipulation)
  • Pure interaction-gesture-based tools without own transactional logic (compared to monolithic 'selection tool')

Back to the top