html.master.html Maven / Gradle / Ivy
Show all versions of geomajas-plugin-editing-documentation
Geomajas Editing plug-in guide Table of Contents
List of Examples
This plug-in provides a set of services and utilities for visually
editing geometries on the map within a GWT environment. It uses the Geomajas
Geometry Project as the base geometry type, and the
MapController definition from the Geomajas Common GWT face
library. On top of the visual geometry editing, this plug-in also provides
services for snapping, splitting and merging.
In essence the editing follows the tried and tested
Model-View-Controller principle:
-
Model: The central GeometryEditService. It keeps
track of the location and status of all vertices and edges of the
geometry being edited.
-
View: The GeometryEditService will fires events
that are being picked up by a specific renderer. Any change in the
shape of the geometry or the status of it's vertices/edges will be
caught and visually displayed on the map.
-
Controller: A series of handlers will execute methods in the
GeometryEditService, based upon user interaction on the
map.
Note
As the rendering is face specific, the focus has first gone to
the GWT face. An implementation for the Pure GWT face will follow
later.
The renderer is one example of a listener to the many events that
the GeometryEditService fires, but essentially anyone can
listen to those events. If you need to react to any change in a geometry's
shape, just add the correct handler.
Before trying to figure out how the GeometryEditService
works, it is important to understand the GeometryIndex
concept. A GeometryIndex is an index within a geometry that
points to a single vertex, edge or sub-geometry. All operations within the
GeometryEditService operate on a list such
GeometryIndices.
Take for example the "move" operation. This operation will move the
given GeometryIndex to the specified location. This operation
is used when the user drags a vertex around on the map, but this operation
could also be used to let the user drag an interior ring within a polygon,
or an entire LineString within a MultiLineString, or event the whole
geometry.
There are 3 central services that help in the editing process. All
three have a very distinct responsibility:
-
GeometryEditService: Defines the editing
workflow and the basic operations (with undo/redo) that are supported.
Also allows to add handlers to all events.
-
GeometryIndexService: This service defines
operations for creating and manipulating GeometryIndices. It also
supports retrieving information based upon a certain geometry and
index. For example what are the adjacent vertices to a certain edge
within a given geometry?
-
GeometryIndexStateService: Keeps track of
the state of all indices that make up the geometry being edited. It
allows for selecting/deselecting, enabling/disabling, highlighting,
etc any vertices/edges/sub-geometries during the editing process. This
state can then be used by the controllers. For example, a controller
could allow only selected vertices to be dragged by the user.
There are more services then the 3 mentioned above such as a
SnapService, GeometryMergeService and
GeometrySplitService, but those just add more functionality
to the basic set that the 3 above already provide.
Table of Contents
In order to use this plug-in in combination with the GWT face, the
following Maven dependency is required:
Example 2.1. Maven dependency for GWT face
<dependency>
<groupId>org.geomajas.plugin</groupId>
<artifactId>geomajas-plugin-editing-gwt</artifactId>
</dependency>
Before going deeper into the inner workings of the different
services and how they work together, we need to explain the
GeometryEditor. This is the top level editing object that makes all of the
other services work together. It has a GeometryEditService, a renderer for
the map, a SnapService, and a registry for controller on the map.
This is where you start when trying to edit geometries within the
GWT. Because the rendering is face specific, this object too is face
specific. A GeometryEditor can simply be constructed using a map:
Central service for all operations concerning the geometry editing
process. This process should work together with a set of controllers on
the map that execute methods from this service after which events are
fired for a renderer to act upon. This service makes use of the
GeometryIndexService to identify sub-geometries, vertices and
edges. All operations work on a set of such indices. This allows for great
flexibility in the operations that can be performed on geometries.
Editing a geometry comes down to starting the editing process,
applying some operations and then stopping the process again. Starting
and stopping happens through the start and
stop methods. Know also that operations onto the geometry
really do apply on the same geometry that was passed with the
start method. In other words, this service changes the
original geometry. If you want to support some roll-back functionality
within your code, make sure to create a clone of the geometry before
starting this edit service.
At any time during the editing process, the
GeometryEditService has a general state that tells you
what's going on. This state is defined in the
GeometryEditState. Currently there are 3 possible states
for the editing process to be in:
-
IDLE: The default state.
-
INSERTING: The user is currently
inserting new points into the geometry. The
GeometryEditService has an "insertIndex" (of the type
GeometryIndex), that points to the next suggested
insert location. The controllers pick up on this index to insert
points (or edges, or geometries).
-
DRAGGING: The user is currently dragging
a part of the geometry. The GeometryIndexStateService
can select vertices/edges/sub-geometries, which can then be dragged
around.
As you may have noticed from the descriptions, the
GeometryEditState is used mainly within the controllers that operate on
the map. An insert controller will only be active when the edit state is
"INSERTING". Likewise a drag controller will only be active when the
edit state is "DRAGGING".
The editing plug-in has support for snapping while inserting or
dragging. The controllers are equipped with a SnapService
which can convert the mouse event locations into snapped locations, before
they are passed to the GeometryEditService for operation
execution.
The SnapService works through a series of rules that need to be
active. Without any snapping rules, the SnapService will no snap. Adding
snapping rules, goes through the "addSnappingRule" method, and requires
the following parameters:
-
algorithm: The snapping algorithm to be
used. For example, snap to end-points only, or also to edges,
or...
-
sourceProvider: The provider of target
geometries where to snap. For example, snap to features of a
layer.
-
distance: The maximum distance to bridge
during snapping. Expressed in the unit of the map CRS.
-
highPriority: High priority means that this
rule will always be executed. Low priority means that if a previous *
snapping algorithm has found a snapping candidate, this algorithm will
not be executed anymore.
Table of Contents
The editing plug-in also provides a JavaScript API for client-side
integration with other technologies. The API resembles the Java/GWT API as
closely as possible (package names are different).
The JavaScript counterpart of the GeometryEditService is basically a
wrapper around the GWT version. It therefore has the same methods, and
works the same way.
The snapping options in JavaScript are not as rich as they are in
GWT. No separate SnappingService is available. What can be done, is
configuring snapping options in the XML configuration of the vector
layers, and using that configuration directly. The JavaScript
"GeometryEditor" has methods for activating those snapping rules during
editing.
On top of that, the GeometryEditor also has the ability to turn
snapping on and off while inserting vertices or while dragging vertices.
As with the GWT snapping you need at least one snapping rule for snapping
to occur.
The JavaScript counterpart of the GeometryMergeService is basically
a wrapper around the GWT version. It therefore has the same methods, and
works the same way.
Table of Contents
...
Table of Contents
...
This section describes how to let the user draw a new geometry of
some pre-defined type.