Package com.luciad.view.gxy

Interface ILcdGXYEditor

All Superinterfaces:
Cloneable, ILcdCloneable, ILcdPropertyChangeSource, Serializable
All Known Implementing Classes:
ALcdGXYEditor, TLcdGXYAISIconProviderPainter, TLcdGXYAISPointListPainter, TLcdGXYArcBandPainter, TLcdGXYArcPainter, TLcdGXYAreaShapeListPainter, TLcdGXYBoundsPainter, TLcdGXYBufferPainter, TLcdGXYCircleBy3PointsPainter, TLcdGXYCirclePainter, TLcdGXYCircularArcPainter, TLcdGXYCompositeCurvePainter, TLcdGXYCompositeRingPainter, TLcdGXYEditableLabelPainter, TLcdGXYEllipsePainter, TLcdGXYGeoBufferPainter, TLcdGXYIconPainter, TLcdGXYLonLatHeightBufferPainter, TLcdGXYOffsetIconPainter, TLcdGXYPointListPainter, TLcdGXYPointShapeListPainter, TLcdGXYPolylineShapeListPainter, TLcdGXYProcedureTrajectoryPainter, TLcdGXYRoundedPointListPainter, TLcdGXYRoutePainter, TLcdGXYShapeListPainter, TLcdGXYShapePainter, TLcdGXYSurfacePainter, TLcdGXYTextPainter, TLcdMagneticNorthGXYPainter, TLcdPOLPainter, TLcdSLDFeatureTypeStylePainter, TLcdVPFPointListPainter, TLcdVPFPointPainter
public interface ILcdGXYEditor extends Serializable, ILcdCloneable, ILcdPropertyChangeSource
Handles editing of an object through interactions with the objects representations in an ILcdGXYView.

An ILcdGXYEditor is responsible for editing objects based on user interaction (such as mouse movements or mouse clicks) with the representation of an object in an ILcdGXYView. A good understanding of the difference between model coordinates/space, world coordinates/space and view coordinates/space is recommended to fully understand the requirements an editor implementation should meet.

Refer to Implementing a painter and editor in a GXY view for more information on how to implement an editor.

An editor is responsible for the interaction with the representation of an object, in the edit method. An editor is not responsible for the representation of an object, which is handled by the ILcdGXYPainter for the object. However, for a consistent user experience, the editor should be aware of the representation of the object, in order to interpret the interaction as the user would expect it. A good practice to ensure a consistent implementation is to implement both the ILcdGXYPainter and ILcdGXYEditor interfaces in a single class.

A special case of editing is the creation of a new object, where essential properties of an object are assigned a value for the first time. Note, however, that creation of an object in this interface does not include construction of the object. The object is constructed outside the editor and passed in the setObject method. The number of user interactions required to initialize the object is defined in getCreationClickCount.

Information on the the interaction with an object's representation is passed in an ILcdGXYContext. It contains what the current location(s) of the user interaction is and where the user interaction started. This can be, for example, the current location of the mouse and the distance over which the mouse has been dragged, or the current locations of all touched fingers. The transformations in the context enable transforming these locations from view space to the model space of the object, in which the locations can be interpreted and the object can be edited accordingly.

The mode parameter passed to the edit method indicates how the interaction should be interpreted. It can be one of the following:

  • TRANSLATED
  • RESHAPED
  • START_CREATION
  • CREATING
The modes in the first group designates that the object should be modified, the modes in the second group are passed when initializing an object. From an implementation point of view there is no difference between TRANSLATED and RESHAPED. These constants only differ in semantics. For ILcdShape objects TRANSLATED can be seen as the mode that will be passed when the shape as a whole is moved. RESHAPED is used more often for moving part of a shape.

While editing the object, albeit modifying or initializing, it is possible to snap to (parts of) other objects. The method acceptSnapTarget indicates whether snapping can occur.

The object for which the representation should be modified is passed in the method setObject, which should be called before any of the above methods are called for that object. This makes implementations of this interface not re-entrant and inherently not thread-safe.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    CREATING
    Mode to indicate that the user interaction should be interpreted as a step to initialize the object.
    static final int
    END_CREATION
    Deprecated.
    This mode was not used consistently, as it was difficult to use in combination with double-click behavior or when the number of initialization steps is not known beforehand.
    static final int
    RESHAPED
    Mode to indicate that the object should be reshaped as a result of the user interaction.
    static final int
    START_CREATION
    Mode to indicate that the user interaction should be interpreted as the first step to initialize the object.
    static final int
    TRANSLATED
    Mode to indicate that the object should be translated as a result of the user interaction.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    acceptSnapTarget(Graphics aGraphics, ILcdGXYContext aGXYContext)
    Returns whether the object set to the editor can be edited so that (part of) the object snaps to the object passed as snap target in the context.
    boolean
    edit(Graphics aGraphics, int aMode, ILcdGXYContext aGXYContext)
    Defines how an object shall be edited by this editor, taking into account the mode and the context passed.
    int
    getCreationClickCount()
    Returns the number user interactions required to complete the initialization of an object set to this editor.
    String
    getDisplayName()
    Returns a textual representation of this editor.
    Object
    getObject()
    Returns the object this editor is currently set to edit.
    void
    setObject(Object aObject)
    Sets the object which may be edited by this editor.

    Methods inherited from interface com.luciad.util.ILcdCloneable

    clone

    Methods inherited from interface com.luciad.util.ILcdPropertyChangeSource

    addPropertyChangeListener, removePropertyChangeListener

  • Field Details

    • TRANSLATED

      static final int TRANSLATED
      Mode to indicate that the object should be translated as a result of the user interaction. It is up to the implementation to define 'translation of an object'.
      See Also:

    • RESHAPED

      static final int RESHAPED
      Mode to indicate that the object should be reshaped as a result of the user interaction. It is up to the implementation to define 'reshaping of an object'.
      See Also:

    • CREATING

      static final int CREATING
      Mode to indicate that the user interaction should be interpreted as a step to initialize the object.
      See Also:

    • START_CREATION

      static final int START_CREATION
      Mode to indicate that the user interaction should be interpreted as the first step to initialize the object.
      See Also:

    • END_CREATION

      static final int END_CREATION
      Deprecated.
      This mode was not used consistently, as it was difficult to use in combination with double-click behavior or when the number of initialization steps is not known beforehand. If necessary, perform the object's final initialization outside of the editor instead.
      Mode to indicate that the user interaction should be interpreted as the last step to complete the initialization of the object.
      See Also:

  • Method Details

    • setObject

      void setObject(Object aObject)
      Sets the object which may be edited by this editor.

      When the object is set to an editor, the context parameter in subsequent calls to methods in this class should contain a layer that contains this object and for which the editor for this object is this editor.

      Parameters:
      aObject - the object for which the editing shall be handled by this editor.
      See Also:

    • getObject

      Object getObject()
      Returns the object this editor is currently set to edit.
      Returns:
      the object this editor is currently set to edit.

    • edit

      boolean edit(Graphics aGraphics, int aMode, ILcdGXYContext aGXYContext)
      Defines how an object shall be edited by this editor, taking into account the mode and the context passed.

      The mode passed indicates how the interaction should be interpreted. It can be one of the following:

      • TRANSLATED
      • RESHAPED
      • START_CREATION
      • CREATING
      • END_CREATION

      The first two modes designate that the object should be modified, the last three modes are passed when initializing an object. From an implementation point of view there is no difference between TRANSLATED and RESHAPED. These constants only differ in semantics. For ILcdShape objects TRANSLATED can be seen as the mode that will be passed when the shape as a whole is moved. RESHAPED is used more often for moving part of a shape.

      The context contains information on the user interaction at hand. The methods getX and getY contain the location(s) of the user interaction. The methods getDeltaX and getDeltaY contain the distance(s) over which the user interaction is taking place. For example, getX and getY may contain the current mouse location while getDeltaX and getDeltaY contain the distance over which the mouse has been dragged. The editing behavior can take into account multiple locations, to respond to, for example, multi-touch input.

      When a snap target is accepted, the implementation of this method should take that fact into account when editing or initializing an object.

      Parameters:
      aGraphics - the Graphics on which the representation of the object is painted
      aMode - indicates how the user interaction should be interpreted. Is one of the following:
      • TRANSLATED,
      • RESHAPED,
      • START_CREATION,
      • CREATING,
      • END_CREATION.
      aGXYContext - contains information on the user interaction and the transformations to transform from view space to the object model space.
      Returns:
      true if the object has changed when this method returns, false otherwise.
      See Also:

    • getCreationClickCount

      int getCreationClickCount()
      Returns the number user interactions required to complete the initialization of an object set to this editor. For example, for a circle this can be two: one to determine the center point of the circle and one to determine the radius of the circle. A negative number indicates that there is no upper limit to the number of user interactions. For example, for a polyline this could be -2: it requires a minimum of two clicks to establish a polyline, but there is no upper limit on the number of polyline points.
      Returns:
      the number of user interactions required to initialize the object set to this editor.

    • acceptSnapTarget

      boolean acceptSnapTarget(Graphics aGraphics, ILcdGXYContext aGXYContext)
      Returns whether the object set to the editor can be edited so that (part of) the object snaps to the object passed as snap target in the context. If the snap target is accepted, a call to the edit method with this context passed should edit the object so that (part of) the object snaps to the object passed as snap target in the context.

      The context contains information on the user interaction at hand: the current location of the user interaction, given by its X and Y coordinates, and the distance in X direction and distance in Y direction over which the user interaction is taking place. For example, getX and getY may contain the current mouse location while getDeltaX and getDeltaY contain the distance over which the mouse has been dragged. The context also contains the candidate snap target and the layer the snap target is contained in.

      Parameters:
      aGraphics - the Graphics on which the representation of the object is painted
      aGXYContext - the context containing the information on the user interaction and the snap target.
      Returns:
      whether the object set to the editor can be edited so that (part of) the object snaps to the object passed as snap target in the context.
      See Also:

    • getDisplayName

      String getDisplayName()
      Returns a textual representation of this editor. This can be useful when different editor implementations are available for an object. For example, to edit different parts of an object. Having a textual representation may facilitate choosing between different editor implementations.
      Returns:
      a textual representation of this editor.