Application: gvSIG desktop » gvSIG tools: Vector editing

=================================================================

 New gvSIG 2.1+ vector editing support

=================================================================

-------------------

 Technical design

-------------------

:Company:   gvSIG Association 

:Author:    DiSiD Corporation, S.L.

:Revision:  $Rev: $

:Date:      $Date: $

:Copyright: 

.. contents::

   :depth: 2

   :backlinks: none

.. sectnum::

   :depth: 2

   :start: 1

.. |year| date:: %Y

.. header:: 

   .. class:: headertable

   +-----------------------+-------------------------+

   |.. class:: left        |.. class:: right         |

   |                       |                         |

   | Requisitos            |###Page###               |

   +-----------------------+-------------------------+ 

.. footer:: 

    .. include:: <isonum.txt>

    .. class:: left

    *New gvSIG 2.1+ vector editing support - Technical design*

    |copy| |year| ** 

Introduction

=============

gvSIG 2.1 provides vector editing support, which was already available since gvSIG 1.9, and has been migrated and adapted to the newer versions. But from the user point of view it lacks usability and an uniform way of interacting with the user. A lot of the editing tools provided in gvSIG are lacking from the usability point of view, as well as the limitations they have.

From the point of view of a developer, it is a bit cumbersome to develop new vector editing tools, with too much responsability given to each tool implementation. Also there is not a well defined API to be able to use the vector editing support out of the user interface.

To be able to solve those problems, a new project has been started to create a new vector editing implementation, from the core editing support to each of the editing tools. To make the most of it, a new list of funtional and technical requirements have been gathered, and a new functional analysis has been performed.

This document is the technical design of the new vector editing library and support for gvSIG 2.1+, taking into account the new requirements and the functional analysis.

First, a list of new technical requirements gathered while creating the technical design will be listed to have a bit of context of the proposed design. Next, the APIs and implementations of the different modules of the editing support will be defined.

Technical requirements

=======================

* As this may be a mid/long term project, a way to be able to coexist the old vector editing implementation with the new one must be provided. The idea is for the user to be able to install the new editing support and disable the old one, without needing another gvSIG desktop installation. That means no changes to gvSIG core projects need to be performed, or the ones to perform must be compatible with the old vector editing.

* The way to integrate de editing support in gvSIG, taking into account the previous requirement is to use MapControl Behavior objects.

* Andami Extension objects will be used to register the vector editing tools, managing also the status (enabled, active, ...) required by Andami while being added as toolbar buttons and menu entries.

* An editing tool library must be implemented which allows to use it not only from the user interface, like for example a gvSIG personalization, an addon or a script.

Technical design

=====================

To have a bit of context of the proposed design, we will first provide a description of how should work the new editing support for an example tool, and some needs for the editing library API and SPI. Next, the API, SPI, implementation and other packages will be defined.

Example use case description

-------------------------------

When gvSIG is launched, a EditingExtension registers an EditingBehavior in MapControl to provide user interaction with the editing tools. When an EditingTool is started, the EditingBehavior will interact with the tool to:

* Get the first/next parameter required by the tool

* Get the information of a parameter: type, description, ...

* Get a Geometry to represent the current editing status.

The EditingBehavior responsability will be to interact with the user to provide the EditingTool with the required parameters. That interaction will be performed through three different ways:

* Left button mouse clicks: mainly used to get map locations.

* Contextual menu options: to select between available options or open a dialog with a form to fill the required parameter values.

* Through the text console.

Each editing tool or group of tools have an Extension which registers the related toolbar buttons and menu entries, as well as register the editing tools in the editing library SPI. Also the Extension must be able to activate the editing tool when the user clicks in the related toolbar button or menu entry. That means an Extension will require to interact with the editing library for the following actions:

* Register an editing tool.

* Ask if an editing tool is enabled or active for the current context.

* Start an editing tool.

With this context, an example use case of a editing tool to create a Curve geometry will be as follows:

* The user clicks on the create Curve button, and the related Extension calls EditingManager and execute activateTool("CreateCurve", mapControl);

* Manager gets the EditingBehavior associated with MapControl and calls activateTool("CreateCurve");

* The EditingVBehavior creates a EditingService with the rigth provider.

* The EditingBehavior asks the service for a mouse icon to use, or uses a default one.

* The EditingBehavior asks the service for the first parameter.

* The EditingService responds with a parameter of type *List of Points*.

* The EditingBehavior activates a message in the console asking for the X,Y values of the next Point. 

* The user has then three options to provide the point: 

  * Click with the mouse left button in the map.

  * Write in the console the X,Y values of the point.

  * Opens the contextual menu and select the option to provide the X,Y values, which will open a dialog with a form to write the two values.

* Each time the user moves the mouse cursor, the EditingBehavior requests the tool a Geometry to draw with the current context and the map location of the mouse cursor. In this case, the Geometry will be a Curve created with the user already defined points and, as the last point, the current mouse cursor location.

* Once the value of the point is provided by the user to the EditingBehavior (through mouse, dialog or console), it creates a Point and provides the value to the tool and asks for another Point to the user, with an option to allow the user to end the Curve:

  * With a mouse left button double click.

  * With a value in the console (*?E?*)

  * With an option in the contextual menu.

* This process is repited until the user ends the list of points.

* The EditingBehavior notifies the tool the list of Points is finished.

* The service creates a curve with the provided points, and a Feature is created and inserted into the current Layer FeatureStore.

* The service ends and it is activated again by default. The user may create another Curve or activate another tool.

* In any point of the process, the user may activate another tool o pulse the *Esc* to finish the current tool execution and start again. **NOTE: if the user has already provided some data, ?ask him to confirm the cancelation and lose the data?** I think that we have to show a dialog to ask him to confirm the cancelation and lose data. Editing pluging has to allow user to disable this.

API

----

This is the API of the vector editing library, which wil be based on the gvSIG tools PBI model (Provider Based Implementation).

* Project: org.gvsig.vectorediting/org.gvsig.vectorediting.lib/org.gvsig.vectorediting.lib.api

* Package: or.gvsig.vectorediting.lib.api

EditingManager (extends o.g.t.s.Manager)

*********************************************

The API will provide the following services:

* getEditingService( Strin serviceName, FeatureStore featureStore) :: EditingService 

  Creates a DynObject with the necessary service parameters, set featureStore value to dynobject and creates an EditingService.

* getServiceInfo(String serviceName) :: EditingServiceInfo

  Provides information of an editing tool

* activateTool(String name, MapControl mapControl) :: void

  If mapControl has EditingBehavior added as tool, this method calls activateTool of EditingBehavior.

* beginEdition(FLyrVect layer, DefaultViewPanel view) throws DataException :: void

  Notifies observers before and after to set store in edit mode. Checks if there is a EditingBehavior registered at MapControl. If there is not a EditingBehavior registered, it will instance one and it will add it to MapControl. Moreover, shows console at of view, set caret at console, adds observers and refresh menus.

EditingService (extends Service)

*****************************************************

At this moment delagates all functionality to providers.

* start() :: void 

* getNextParameter() :: EditingServiceParameter

* setValueParameter(EditingServiceParameter param, Object value) :: void

* drawOperation(Point2D mousePosition) :: Geometry

* stop() :: void

* List<EditingServiceParameter> getParameters() :: List<EditingServiceParameter

* void finishOperation(MapControl mapcontrol);

EditingServiceInfo

*****************************************************

* Provide read only information about a tool:

  * Tool name getName :: String

  * Tool description (?use as contextual help?) getDescription :: String

  * Mouse icon. getMouseIcon() :: Image

  * The geometry types being managed. getSupportedPrimitiveGeometryType() :: int[]

  * If the tool creates new geometries. createsNewGeometries() :: boolean

  * The list of the parameters. getParameters() :: List<EditingServiceParameter>

* getParameterInfo(String name) :: EditingServiceParameter 

  Provide read only information about a tool parameter :: EditingServiceParameter

EditingServiceParameter

*****************************************************

* Provide read only information about a parameter:

  * Parameter name. getName() :: String

  * Parameter description (?use as contextual help?) getDescription :: String

  * Parameter type: There are 6 types of parameters: point, list of points, option, value, selection and geometry. None typed, EditingService 

    checks if the parameter value is correct before put it at colection values.

  * equals(EditingServiceParameter param) :: boolean

    Compares two parameters.

  * getConsoleMenssage()

    Get message to show on console.

EditingBehavior

*****************************************************

* activateTool(String name);

  Activates tool creating an EditingService and ask for the next parameter.

* void cleanBehavior();

  Set activeService and currentParam to null and show a message on console to warn user that has to active a new tool. This operation will be called when user changes active layer or set layer in edit mode.

SPI

-----

* Project: org.gvsig.vectorediting/org.gvsig.vectorediting.lib/org.gvsig.vectorediting.lib.spi

* Package: or.gvsig.vectorediting.lib.spi

EditingpProviderManager (extends ProviderManager)

*****************************************************

* getServiceInfo(String name) throws ServiceException :: EditingServiceInfo

  Return information about one service. (see EditingServiceInfo) 

EditingProviderServices (extends ProviderServices)

*****************************************************

* Methods to create features / geometries.

  * insertFeatureIntoFeatureStore (Feature feature, FeatureStore featureStore) :: void

  * insertGeometryIntoFeatureStore(Geometry geometry, FeatureStore featureStore) :: void

* Methods to delete features / geometries.

  * deleteFeatureFromFeatureStore(Feature feature, FeatureStore featureStore) :: void

  * deleteGeometryFromFeatureStore(Geometry geometry, FeatureStore featureStore) :: void

* Methods to update features / geometries

  * updateFeatureInFeatureStore(Feature feature, FeatureStore featureStore) :: void

  * updateGeometryInFeatureStore(Geometry geometry, FeatureStore featureStore) :: void

* ?Get the Symbol to draw a Geometry?.

* Create new Features based on another ones, following the common criteria about the alphanumeric information:

  * splitFeatureAndInsertIntoFeatureStore(Feature featureToSplit, Geometry splitter, FeatureStore featureStore) :: void

    splitFeature(Feature featureToSplit, Geomety splitter) :: Collection<Feature>

    New Features created from an old one clone all data, but the primary keys.

  * unionFeaturesAndInsertIntoFeatureStore(Collecion<Feature> featuresToUnion, FeatureStore featureStore) :: void

    New Feature created from a set of Features (ex: Union): for every attribute, if the values are the same for all the source Features,

    ignoring null values, clone it. Otherwise leave as null.

DefaultEditingServiceInfo and DefaultEditingServiceParameter

**************************************************************

* Default implementations to be used by the tools.

EditingProviderFactory (ProviderFactory)

*****************************************************

* getServiceInfo() :: EditingServiceInfo 

  Provide information of the tool (see EditingManager's API).

* getServiceParameterInfo() :: EditingServiceParameter

  Provide information of a tool parameter (see EditingManager's API).

EditingProvider (Provider)

*****************************************************

* start() :: void 

  Starts service, initializing attibrutes.

* getNextParameter() :: EditingServiceParameter

  Returns the next parameter required by the tool. If all parameters have values return null.  

* setValueParameter(EditingServiceParameter param, Object value) :: void

  Sets parameter value whit it param.

* drawOperation(Point mousePosition) :: Geometry

  Provides a Geometry to draw the current editing context, taking into account the values previously provided by the user and a Point with the 

  current mouse cursor location.

* stop() :: void

  Cancels the execution of the tool.

* List<EditingServiceParameter> getParameters() :: List<EditingServiceParameter

  Returns a list with all parameters required by the tool

* finishOperation(MapControl mapcontrol) :: void

  Indicates that the tool doesn't need more values.

* ?Ask for the Geometries or Features created, updated or removed by the tool?

.. admonition:: Doubt

   Not sure if this is neccessary. At this moment there is no methods to this.

AbstractEditingProvider extends AbstractProvider implements EditingProvider

****************************************************************************

Implements all creation common operations of providers such as createPoint, createCurve, createMultiCurve, createArc, createCircle...

Implementation

----------------

* Project: org.gvsig.vectorediting/org.gvsig.vectorediting.lib/org.gvsig.vectorediting.lib.impl

* Package: or.gvsig.vectorediting.lib.impl

Provides the implementation of the library components, extending the related base tools implementations.

Editing Plugin

---------------

* Project: org.gvsig.vectorediting/org.gvsig.vectorediting.app/org.gvsig.vectorediting.app.mainplugin

* Package: or.gvsig.vectorediting.app.mainplugin

Provides the implementation of the main editing plugin, and integrates the editing library API, SPI and implementation in gvSIG.

EditingExtension

*****************************************************

Registers the EditingBehavior in MapContext, as well as the actions to activate/deactivate editing.

Also activates the console when editing is started, puts the selected layer store in editing mode, and notifies about the begin and end of editing mode.

BaseEditingServiceExtension

*****************************************************

Provides utils to extensions.

* protected getActiveView() :: DefaultViewPanel

  Returns active view.

* protected canBeEdited(FLyrVect layer) :: boolean

  Returns true if layer can be edited. Return false if layer can not be edited.

* protected getActiveLayer(DefaultViewPanel vista) :: FLyrVect

  Returns active layer from view that receives as parameter.

* protected isApplicable(GeometryType[] supportedTypes, int shapeType) :: boolean

  Returns true if extension can be applied to that shapetype.

* protected loadGeometryTypes(int[] types) :: GeometryType[]

  Return a collection of geo types from a collection of geometry.types.

.. admonition:: Doubt

   Not sure if there is a mechanism to be able to have a single final implementation, or each extension must extend this one.

Other themes to take into account

-----------------------------------

Geometry construction

***********************

All geometries being constructed, not already available in the Geometry Library, must be added as operations.

Snappers

------------

Snapper support is defined in MapControl, with the current snappers available in the gvSIG main plugin. The current editing plugin only activates them and provides a configuration panel.

That panel should be moved out of the editing plugin to a new one, which also adds actions to enable or activate snappers by the user, also with a key shortcut.

Geometries composed of other geometries

-----------------------------------------

* A mechanism must be defined to allow a way for a tool to ask for new geometries, and the editing manager to be able to call other tools which create the required geometry type, in a kind of "reentering" mode.

  Two different approaches have been discussed:

  * The same EditingProvider should allow to create only Geometries instead of Features, with some kind of parameter or new methos.

  * Separate provider types, with the ones which create Features and other ones which create basic geometries.

Templates

----------------

As a future functionality, the user would be able to define templates for creating new Features, with default values for:

* Alphanumeric attributes

* Type of geometry

* Editing tool to use

* Simbology to apply

Now we are not going to implement this, but it would be nice if we could take this improvement into account so it could be implemented in the future without much changes.

Toolbar button with many option

---------------------------------

* As this needs support in Andami, for now all editing tools will be implemented simple. Ex: create a circle now asks first if the user wants to create it with center and radios or with three points. It should be implemented as two separated tools.

* In Andami it could be implemented as a way to group toolbar buttons in button menus, which could be defined through the config.xml file.