Difference between revisions of "GEF/GEF4/MVC"

Revision as of 10:36, 23 May 2016

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

feature: org.eclipse.gef4.mvc
bundle: org.eclipse.gef4.mvc

The MVC module of GEF4 MVC 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 com.google.inject.Module] that defines 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.

Behaviors

package: org.eclipse.gef4.mvc.behaviors

The Behaviors package contains the IBehavior and AbstractBehavior definitions. Additionally, it provides various IBehavior implementations and a related utility class.

IBehavior, AbstractBehavior

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.

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

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, ContentPartPool

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 abstraction and its related AbstractDomain realization.

IDomain, AbstractDomain

The IDomain represents the collective state of a graphical application, i.e. it is composed of all IViewers and ITools. Additionally, the IDomain provides an org.eclipse.core.commands.operations.IOperationHistory and org.eclipse.core.commands.operations.IUndoContext, 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.

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.

ITransactionalOperation

The ITransactionalOperation is a specialization of org.eclipse.core.commands.operations.IUndoableOperation, which further supports querying for content relevance and effect of the encapsulated operation.

AbstractCompositeOperation

The AbstractCompositeOperation is the base class for two concrete org.eclipse.core.commands.operations.ICompositeOperation implementations: ForwardUndoCompositeOperation and ReverseUndoCompositeOperation.

AddContentChildOperation

The AddContentChildOperation can be used to add a content child to an IContentPart. It relies on the IContentPart's addContentChild() method for doing this.

This operation is the counterpart of the RemoveContentChildOperation.

AttachToContentAnchorageOperation

The AttachToContentAnchorageOperation can be used to attach an IContentPart to a content anchorage. It relies on the IContentPart's attachToContentAnchorage() method for doing this.

This operation is the counterpart of the DetachFromContentAnchorageOperation.

BendContentOperation

The BendContentOperation allows to bend the content of an BendableContentPart.

ChangeContentsOperation

The ChangeContentsOperation allows to exchange the contents hold by the ContentModel.

ChangeFocusOperation

The ChangeFocusOperation can be used to set the currently focused part by manipulating the FocusModel.

DeselectOperation

The DeselectOperation can be used to clear the currently selected parts by manipulating the SelectionModel.

DetachFromContentAnchorageOperation

The DetachFromContentAnchorageOperation can be used to detach an IContentPart from a content anchorage. It relies on the IContentPart's detachFromContentAnchorage() method for doing this.

This operation is the counterpart of the AttachToContentAnchorageOperation.

ForwardUndoCompositeOperation

The ForwardUndoCompositeOperation is a specific AbstractCompositeOperation. It will execute(), redo(), and undo() its operations in the order they were added to the composite operation.

RemoveContentChildOperation

The RemoveContentChildOperation can be used to remove a content child from an IContentPart. It relies on the IContentPart's removeContentChild() method for doing this.

This operation is the counterpart of the AddContentChildOperation.

ResizeContentOperation

The ResizeContentOperation allows to resize the contents of an ResizableContentPart.

ReverseUndoCompositeOperation

The ReverseUndoCompositeOperation is a specific AbstractCompositeOperation. It will execute() and redo() its operations in the order they were added to the composite operation, however it will undo() its operations in reverse order.

SelectOperation

The SelectOperation can be used to manipulate the currently selected parts by manipulating the SelectionModel.

SetRefreshVisualOperation

The SetRefreshVisualOperation can be used to enable/disable the #refreshVisual() method for a specific IVisualPart.

TransformContentOperation

The TransformContentOperation can be used to transform the content of an ITransformableContentPart.

Parts

package: org.eclipse.gef4.mvc.parts

The Parts package contains all abstractions related to controllers (aka parts) in a model-view-controller architecture. For each abstraction, a corresponding (abstract) realization is provided, from which specific controllers can be sub-classed.

IVisualPart, AbstractVisualPart

The IVisualPart interface is the main MVC abstraction for controller objects, and therefore, controls a visual and handles user interaction. Visual parts are organized in a hierarchy, i.e. every part (except the root part) is associated with a parent part, and can control a number of children parts. Additional to the parent-child relations, visual parts can be part of anchored-anchorage relations, which are independent to the hierarchy, i.e. anchoreds and anchorages can be located at arbitrary places within the hierarchy.

Visual parts are adaptable, so that you can adapt policies and behaviors to them (as well as anything else if needed). This is an integral part of user interaction, because the tools will delegate input events to corresponding policies of the visual part which controls the event target (visual). Visual parts are also activatable. During activation/deactivation they will activate/deactivate their adapters.

Moreover, an IVisualPart exposes observable properties for:

"active": This visual part was activated/deactivated.
"adapters": The adapters (policies, behaviors, etc.) of this visual part changed.
"parent": The parent of this visual part changed.
"children": The children of this visual part changed.
"anchorages": The anchorages of this visual part changed.
"anchoreds": The anchoreds of this visual part changed.

IRootPart, AbstractRootPart

The IRootPart interface is a specialization of the IVisualPart interface. There is exactly one IRootPart per IViewer. It contains all IContentParts, IFeedbackParts, and IHandleParts as children and manages the root visuals.

IContentPart, AbstractContentPart

The IContentPart interface is a specialization of the IVisualPart interface. Content parts are bound to content model elements, i.e. they provide a link to the model, and allow manipulations of the model via addContentChild(), removeContentChild(), attachToContentAnchorage(), and detachFromContentAnchorage().

IFeedbackPart, AbstractFeedbackPart

The IFeedbackPart interface is a specialization of the IVisualPart interface. Feedback parts are used to give visual feedback to the user during interactions. They are usually rendered on top of the content parts.

IHandlePart, AbstractHandlePart

The IHandlePart interface is a specialization of the IVisualPart interface. Handle parts are used for visual handles, which can be used for interaction, i.e. to manipulate elements. They are usually rendered on top of the feedback parts.

IContentPartFactory

The IContentPartFactory interface is part of a default mechanic in MVC: It is used during the content synchronization within the ContentBehavior to create new content parts. Therefore, if you want to use this default mechanic, you have to supply an IContentPartFactory suitable to your content model.

ITransformableContentPart

The ITransformableContentPart interface is to be implemented by IContentParts, which support transformations of their content. This is e.g. used to persist a translate operation.

IResizableContentPart

The IResizableContentPart interface is to be implemented by IContentParts, which support resize of their content. This is e.g. used to persist a resize operation.

IBendableContentPart

The IBendableContentPart interface is to be implemented by IContentParts, which support bending of their content (i.e. manipulation throw inserting or moving of bend points). This is e.g. used to persist a bend operation.

IFeedbackPartFactory

The IFeedbackPartFactory interface is part of a default mechanic in MVC: It is used for creating feedback parts within the default behaviors, i.e. in response to mouse hover or selection changes.

IHandlePartFactory

The IHandlePartFactory interface is part of a default mechanic in MVC: It is used for creating handle parts within the default behaviors, i.e. in response to mouse hover or selection changes.

PartUtils

The PartUtils class is a collection of utility methods when working with visual parts.

Policies

package: org.eclipse.gef4.mvc.policies

The Policies package contains the IPolicy abstraction, a related abstract base implementation (AbstractPolicy), and concrete implementations for the manipulation of the ContentModel, namely ContentPolicy, CreationPolicy, and DeletionPolicy.

IPolicy, AbstractPolicy

An IPolicy is similar to an IBehavior in that it is bound to an IVisualPart. However, behaviors start actions by themselves (they are active), while policies are always called from the outside (they are passive).

There are basically two kinds of policies, interaction and transaction policies (while these are not differentiated via type). An interaction policy is called by a ITool to handle part of an interaction (e.g. click, drag). A transaction policy is one that may be used by other (interaction or transaction) policies to actually perform a visual or semantic operation (e.g. create model element). It has to implement the ITransactional interface , encapsulating the to be performed operation as an org.eclipse.core.commands.operations.IUndoableOperation.

AbstractTransactionPolicy

The AbstractTransactionPolicy is the base class for all policies that perform undoable changes. The offer init(), commit(), and rollback(), which enclose an undoable transaction.

AbstractInteractionPolicy

The AbstractInteractionPolicy is the base class for all policies that response to an interaction gesture. They usually delegate to some transactional policies to perform a visual or content relevant reaction.

ContentPolicy

The ContentPolicy is an AbstractTransactionPolicy to handle content changes, i.e. adding/removing of content children, as well as attaching/detaching to/from content anchorages. Therefore, it can be used to retrieve an operation which performs the desired content changes.

CreationPolicy

The CreationPolicy is an AbstractTransactionPolicy that handles the creation of new content objects using the ContentPolicy. Therefore, it can be used to retrieve an operation which performs the desired creations.

DeletionPolicy

The DeletionPolicy is an AbstractTransactionPolicy that handles the deletion of existing content objects using the ContentPolicy. Therefore, it can be used to retrieve an operation which performs the desired deletions.

AbstractTransformPolicy

The AbstractTransformPolicy is an AbstractTransactionPolicy that supports content transformation of ITransformableContentParts.

AbstractResizePolicy

The AbstractResizePolicy is an AbstractTransactionPolicy that supports content resizing of IResizableContentParts.

AbstractBendPolicy

The AbstractBendPolicy is an AbstractTransactionPolicy that supports content bending of IBendableContentParts.

Tools

package: org.eclipse.gef4.mvc.tools

The Tools package contains the ITool abstraction and its related AbstractTool realization.

ITool, AbstractTool

An ITool delegates input events to corresponding (interaction) IPolicies, which are responsible of handling the interaction.

Viewer

package: org.eclipse.gef4.mvc.viewer

The Viewer package contains the IViewer abstraction and the related AbstractViewer realization.

IViewer, AbstractViewer

An IViewer is the container for an IVisualPart hierarchy and provides a link to the IDomain.

MVC.FX

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

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