Building an editor
==================

Building an editor involves to main steps:

1.  Creating and registering the new editor and
2.  Populating the editor.

The following sections include step-by-step guides and useful
information for completing both parts. Throughout this introduction the
component editor located in `org.fortiss.af3.component.ui.editor.fx` is
used as an example. Consult its code whenever something is unclear, as
it is likely that the new editor will be similar in many aspects.

Creating and registering the editor
-----------------------------------

The following steps create a new editor and register it within the AF3
runtime. Once completed, the new editor can be opened but it will not
contain any elements yet as it is still to be populated.

1.  Create a new package for the FX editor (e.g.
    `org.fortiss.af3.component.ui.editor.fx`).
2.  Create the new editor class deriving from `LWFXEFEditorBase` (see
    `ComponentStructureFXEditor`).
3.  Create a new `EditorBinding` and register it in the `plugin.xml`
    (see `ComponentStructureFXEditorBinding`). Be sure to implement the
    `getEditorClass`, `getLabel` and `getPriority` methods!
4.  Add a model factory implementing `IModelFactory` and implement its
    `getRoot()` method (see `component.ui.editor.fx.ModelFactory`). Let
    other methods return null or empty lists.
5.  Add a visual factory implementing `IVisualFactory` and returning
    null in all methods
6.  Create a sub-package `controller` and add a `DiagramController`
    class deriving from `EObjectBasedDiagramControllerBase`. Nothing
    needs to be implemented here.
7.  Add a controller factory implementing `IControllerFactory` and
    return an instance of `DiagramController` in
    `createDiagramController`. Other methods may return null.
8.  Return instances of the factory class in the respective methods of
    the editor class.
9.  Start AF3 and test if the new editor is appearing (with an empty
    background canvas).

Populating the editor
---------------------

Having created and registered editor, it is now time to populate it.

### Models, views and controllers

Editors are implemented using the MVC pattern with models, views and
controllers. Hence, each editor has a `ModelFactory`, a `VisualFactory`
and a `ControllerFactory` defining models, visuals and controllers for
each of the elements to be shown and edited. For a standard
boxes-and-wires diagram this includes **contents** (boxes), **links**
(wires) and **anchorages** (ports used to connect wires to boxes). The
following sections describe how to create the respective models, visuals
and controllers for each of them.

### Layout data

Whenever dealing with graphical editors it is of *utmost* importance to
know where elements are to be located. This information can be accessed
via the `LayoutDataUtils` and `LayoutDataUIUtils` classes. They provide
methods to e.g. retrieve the position and the bounds of a node
(`LayoutDataUtils.getNodePosition(ILayoutedModelElement layouted)` and
`LayoutDataUtils.getNodeBounds(ILayoutedModelElement layouted)`
respectively). For an exhaustive listing of all methods consult the
classes’ outline.

### Populating the editor (*finally*)

Now onto populating the editor with contents, anchorages and links. Each
of them will require the implementation of the classes and methods
mentioned in the respective section. Instead of going through each of
the methods in detail, it is advised to consult the implementation of
the respective methods for the component editor.

#### Content

Implement the following methods:

-   `ModelFactory.getContentModels()`
-   `VisualFactory.createContentVisual()`
-   `ControllerFactory.createContentController()`

Custom visuals and controller classes to extend in case you want to
build a standard boxes-and-wires editor:

-   `LayoutedRectangularContentVisualBase` (e.g. `SubComponentVisual`)
-   `EObjectBasedRectangularResizableContentControllerBase` (e.g.
    `SubComponentController`)

In case you need custom shapes, you have to extend the
`org.eclipse.systemfocus.kernel.common.ui.javafx.lwfxef.visual.base.ContentVisualBase`
directly. Orient yourself at the implementation of
`org.eclipse.systemfocus.kernel.common.ui.javafx.lwfxef.visual.rectangular.RectangularContentVisualBase`
to know which methods to override and how.

#### Anchorages

There are two types of anchorages to take care of:

-   **Diagram anchorages** are attached to the parent element of the
    content shown in the diagram and are displayed directly on the
    editor’s background without being attached to any element.
-   **Content anchorages** are attached to contents (i.e. boxes,
    ellipses etc.) shown in the editor and are displayed at the border
    of the respective shape.

Implement the following methods:

-   `ModelFactory.getContentAnchorageModels()`
-   `ModelFactory.getDiagramAnchorageModels()`
-   `VisualFactory.createContentAnchorageVisual()`
-   `VisualFactory.createDiagramAnchorageVisual()`
-   `ControllerFactory.createContentAnchorageController()`
-   `ControllerFactory.createDiagramAnchorageController()`

Custom visuals and controller classes to extend:

-   `LayoutedCircularContentAnchorageVisualBase` (e.g
    `SubComponentPortVisual`)
-   `LayoutedCircularDiagramAnchorageVisualBase` (e.g
    `DiagramComponentPortVisual`)
-   `LayoutedModelElementBasedContentAnchorageController` (e.g
    `SubComponentPortController`)
-   `LayoutedModelElementBasedDiagramAnchorageController` (e.g
    `DiagramComponentPortController`)

In order to specify which ports can be linked and which do not check the
implementation of the `canConnect` method in the connection compositor
of the editor’s contents (e.g.
`ComponentConnectionCompositor.canConnect(EObject source, EObject target, IHierarchicElement parent, IConnectionCompositionContext context)`).

#### Links

Implement the following methods:

-   `ModelFactory`
    -   `getLinkModels()`
    -   `getLinkStart()`
    -   `getLinkEnd()`
-   `VisualFactory.createLinkVisual()`
-   `ControllerFactory.createLinkController()`

Make sure to implement all three methods of the `ModelFactory` at the
same time, as they depend on each other.

Custom visuals and controller classes to implement:

-   `LayoutedLineLinkVisualBase` (e.g. `ChannelVisual`)
-   `LayoutedModelElementBasedLinkBendPointController` (e.g.
    `ChannelController`)

Customizing the editor (optional)
---------------------------------

Once created, registered and populated the editor can be further
customized by overriding the `customizeViewer` method of your `FXEditor`
(e.g. `ComponentStructureFXEditor.customizeViewer()`). The following
code snipped shows how to set the indicator spacing and the background
color:

    
    /** {@inheritDoc} */
    @Override
    protected void customizeViewer() {
        DiagramViewerFeatures features = viewer.getFeatures();
        features.setIndicatorSpacing(new Dimension2D(12, 12));
        features.setBackgroundColor(LIGHTGRAY);
    }