Class SketchEditor

    • Constructor Detail

      • SketchEditor

        public SketchEditor()
        Constructs a default SketchEditor.
        Since:
        100.1.0
    • Method Detail

      • start

        public void start​(SketchCreationMode creationMode)
        Starts a new editing session for given sketch creation mode.
        Parameters:
        creationMode - representing the type of geometry that users are going to sketch
        Throws:
        IllegalArgumentException - if the creationMode is null
        IllegalStateException - if the method is called before the SketchEditor is set on a map view
        IllegalStateException - if the map is null or not loaded
        Since:
        100.1.0
      • start

        public void start​(SketchCreationMode creationMode,
                          SketchEditConfiguration editConfiguration)
        Starts a new editing session for given sketch creation mode and edit configuration.
        Parameters:
        creationMode - representing the type of geometry that users are going to sketch
        editConfiguration - the SketchEditConfiguration
        Throws:
        IllegalArgumentException - if creationMode or editConfiguration is null
        IllegalStateException - if the method is called before the SketchEditor is set on a map view
        IllegalStateException - if the map is null or not loaded
        Since:
        100.3.0
      • start

        public void start​(Geometry geometry)
        Starts a sketch editing session based on the provided geometry. A non-freehand sketch creation mode and a default edit configuration is created and used based on the geometry type. The sketch editor will respond to user interactions with the map view to perform a sketch.

        If you like to set the geometry in freehand editing mode, you can use the start(Geometry, SketchCreationMode) method.

        Parameters:
        geometry - the geometry to start the sketch with
        Throws:
        IllegalArgumentException - if the geometry is null
        IllegalStateException - if the method is called before the SketchEditor is set on a map view
        IllegalStateException - if the map is null or not loaded
        Since:
        100.1.0
      • start

        public void start​(Geometry geometry,
                          SketchCreationMode creationMode)
        Starts a sketch editing session based on the provided geometry and creation mode. The sketch editor will respond to user interactions with the map view to perform a sketch.
        Parameters:
        geometry - the geometry to start the sketch with
        creationMode - representing the type of geometry that users are going to sketch, the type must be compatible with the geometry being provided. A default creation mode is used if it is null
        Throws:
        IllegalArgumentException - if the geometry is null
        IllegalArgumentException - if the geometry type is incompatible with the sketch creation mode
        IllegalStateException - if the method is called before the SketchEditor is set on a map view
        IllegalStateException - if the map is null or not loaded
        Since:
        100.1.0
      • start

        public void start​(Geometry geometry,
                          SketchCreationMode creationMode,
                          SketchEditConfiguration editConfiguration)
        Starts a sketch editing session based on the provided geometry, creation mode and edit configuration. The sketch editor will respond to user interactions with the map view to perform a sketch.
        Parameters:
        geometry - the geometry to start the sketch with
        creationMode - representing the type of geometry that users are going to sketch, the type must be compatible with the geometry being provided. A default creation mode is used if it is null
        editConfiguration - the SketchEditConfiguration
        Throws:
        IllegalArgumentException - if geometry or editConfiguration is null
        IllegalArgumentException - if the geometry type is incompatible with the sketch creation mode
        IllegalStateException - if the method is called before the SketchEditor is set on a map view
        IllegalStateException - if the map is null or not loaded
        Since:
        100.3.0
      • clearGeometry

        public void clearGeometry()
        Clears the current sketch geometry.
        Since:
        100.1.0
      • replaceGeometry

        public void replaceGeometry​(Geometry geometry)
        Replaces the current sketch geometry with the given geometry if the sketch editor is started. These geometries must be matching in type.
        Parameters:
        geometry - the new geometry to be used
        Throws:
        IllegalArgumentException - if the geometry is null or geometry type is incompatible with current creation mode
        IllegalStateException - if the method is called before the SketchEditor is set on a map view and started
        Since:
        100.1.0
      • isSketchValid

        public boolean isSketchValid()
        Indicates whether the sketch geometry is valid. It is valid if:
        • It is a point and contains x & y coordinates.
        • It is a polyline and contains at least one part of 2 or more vertices.
        • It is a polygon and contains at least one part of 3 or more vertices which form a closed ring.
        • It is a multipoint and contains at least one vertex.
        • It is an envelope and it contains xmin, ymin, xmax, & ymax coordinates.
        Returns:
        true if the current sketch geometry is valid, false otherwise
        Since:
        100.1.0
      • stop

        public void stop()
        Stops the sketching session if it is started. The final sketch geometry can be obtained by getGeometry() before calling stop.
        Since:
        100.1.0
      • isVisible

        public boolean isVisible()
        Gets the visibility of the sketch geometry and associated graphics displayed by the SketchEditor such as vertices.
        Returns:
        true if the sketch geometry and associated graphics are visible, false otherwise
        Since:
        100.1.0
      • setVisible

        public void setVisible​(boolean visible)
        Sets the visibility of the sketch geometry and associated graphics displayed by the SketchEditor such as vertices.
        Parameters:
        visible - true to make the sketch geometry and associated graphics visible, false to make invisible
        Since:
        100.1.0
      • setOpacity

        public void setOpacity​(float opacity)
        Sets the opacity of the sketch geometry.
        Parameters:
        opacity - the opacity of the sketch geometry, it should be a value between 0 (fully transparent) and 1 (fully opaque)
        Throws:
        IllegalArgumentException - if the opacity value is out of range from 0 to 1
        Since:
        100.1.0
      • getOpacity

        public float getOpacity()
        Gets the opacity of the sketch geometry.
        Returns:
        the opacity of the sketch geometry, it should be a value between 0 (fully transparent) and 1 (fully opaque)
        Since:
        100.1.0
      • getSketchCreationMode

        public SketchCreationMode getSketchCreationMode()
        Gets the SketchCreationMode specifying what type of geometry will be sketched.
        Returns:
        the current sketch creation mode
        Since:
        100.1.0
      • setSketchStyle

        public void setSketchStyle​(SketchStyle sketchStyle)
        Applies the sketch style to the sketch editor.
        Parameters:
        sketchStyle - a SketchStyle object
        Throws:
        IllegalArgumentException - if the sketchStyle is null
        Since:
        100.1.0
      • getSketchStyle

        public SketchStyle getSketchStyle()
        Gets the current SketchStyle. To apply the changes of the sketch style on the sketching geometry, the setSketchStyle(SketchStyle) method needs to be called, e.g.
         SketchStyle style = sketchEditor.getSketchStyle();
           style.getLineSymbol().setColor(Color.GREEN);
           style.getLineSymbol().setWidth(2.0f);
           style.setVertexSymbol(new SimpleMarkerSymbol(SimpleMarkerSymbol.Style.CIRCLE, Color.RED, 10));
           sketchEditor.setSketchStyle(style);
         
         
        Returns:
        a SketchStyle object
        Since:
        100.1.0
        See Also:
        SketchStyle
      • getSketchEditConfiguration

        public SketchEditConfiguration getSketchEditConfiguration()
        Gets the sketch edit configuration.
        Returns:
        the SketchEditConfiguration
        Since:
        100.3.0
      • addGeometryChangedListener

        public void addGeometryChangedListener​(SketchGeometryChangedListener listener)
        Adds the geometry changed listener. A geometry changed listener will be invoked whenever a sketch geometry is updated.
        Parameters:
        listener - the geometry changed listener
        Throws:
        IllegalArgumentException - if the listener is null
        Since:
        100.1.0
      • removeGeometryChangedListener

        public boolean removeGeometryChangedListener​(SketchGeometryChangedListener listener)
        Removes the geometry changed listener.
        Parameters:
        listener - the geometry changed listener
        Since:
        100.1.0
      • addSelectedVertexChangedListener

        public void addSelectedVertexChangedListener​(SelectedVertexChangedListener selectedVertexChangedListener)
        Adds a selected vertex changed listener to the SketchEditor. A selected vertex changed listener will be called when a new vertex is selected.
        Parameters:
        selectedVertexChangedListener - the listener to add
        Throws:
        IllegalArgumentException - if selectedVertexChangedListener is null
        Since:
        100.3.0
        See Also:
        setSelectedVertex(SketchVertex)
      • removeSelectedVertexChangedListener

        public boolean removeSelectedVertexChangedListener​(SelectedVertexChangedListener selectedVertexChangedListener)
        Removes the specified selected vertex changed listener from the SketchEditor.
        Parameters:
        selectedVertexChangedListener - the listener to remove
        Returns:
        true if selectedVertexChangedListener is removed successfully, false otherwise
        Since:
        100.3.0
      • getSelectedVertex

        public SketchVertex getSelectedVertex()
        Gets the selected sketch vertex.
        Returns:
        the selected SketchVertex, or null if no sketch vertex is selected.
        Since:
        100.3.0
        See Also:
        setSelectedVertex(SketchVertex)
      • setSelectedVertex

        public boolean setSelectedVertex​(SketchVertex sketchVertex)
        Sets the SketchVertex to be selected.
        Parameters:
        sketchVertex - the SketchVertex to be selected. If sketchVertex is null, the currently selected vertex will be unselected.
        Returns:
        true if sketchVertex is valid and selected successfully, false otherwise
        Since:
        100.3.0
      • getGeometry

        public Geometry getGeometry()
        Gets the current sketch geometry.

        Use SketchGeometryChangedListener to listen to changes of geometry as the user sketches interactively on the map view.

        Returns:
        the current geometry, or null if the sketch editor is not started
        Since:
        100.1.0
      • undo

        public void undo()
        Undoes the last action to the sketch geometry.
        Since:
        100.2.0
      • canUndo

        public boolean canUndo()
        Gets whether there are actions to undo.
        Returns:
        true if there are actions to undo, otherwise false
        Since:
        100.2.0
      • redo

        public void redo()
        Redoes the last action to the sketch geometry.
        Since:
        100.2.0
      • canRedo

        public boolean canRedo()
        Gets whether there are actions to redo.
        Returns:
        true if there are actions to redo, otherwise false
        Since:
        100.2.0
      • removeSelectedVertex

        public boolean removeSelectedVertex()
        Removes the selected vertex.
        Returns:
        true if the selected vertex is removed successfully, false otherwise
        Since:
        100.3.0
      • insertVertexAfterSelectedVertex

        public boolean insertVertexAfterSelectedVertex​(Point point)
        Inserts a new vertex after the selected vertex. If the sketch geometry is empty, a new vertex is to be added and selected. If the sketch geometry is a point, this method will move the existing selected point to the specified location and selects it.
        Parameters:
        point - the new point to be inserted
        Returns:
        true if point is inserted after the selected vertex successfully, false otherwise
        Throws:
        IllegalArgumentException - if point is null
        Since:
        100.3.0
      • moveSelectedVertex

        public boolean moveSelectedVertex​(Point point)
        Moves the selected vertex to a new position.
        Parameters:
        point - the new point to which to move the selected vertex
        Returns:
        true if the selected vertex is moved to the new position successfully, false otherwise
        Throws:
        IllegalArgumentException - if point is null
        Since:
        100.3.0