com.luciad.view.gxy

LuciadLightspeedInterface 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 and Description
static int	CREATING Mode to indicate that the user interaction should be interpreted as a step to initialize the object.
static 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.
static int	RESHAPED Mode to indicate that the object should be reshaped as a result of the user interaction.
static int	START_CREATION Mode to indicate that the user interaction should be interpreted as the first step to initialize the object.
static int	TRANSLATED Mode to indicate that the object should be translated as a result of the user interaction.

Method Summary

Modifier and Type	Method and 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 Detail

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:

Constant Field Values

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:

Constant Field Values

CREATING

static final int CREATING

Mode to indicate that the user interaction should be interpreted as a step to initialize the object.

See Also:

Constant Field Values

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:

Constant Field Values

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:

Constant Field Values

Method Detail

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()

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:

ILcdGXYContext, acceptSnapTarget

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:

ILcdGXYContext.getSnapTarget()

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.