================================================================= 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:: .. 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 getParameters() :: List * 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 New Features created from an old one clone all data, but the primary keys. * unionFeaturesAndInsertIntoFeatureStore(Collecion 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 getParameters() :: List