public interface ILcdGXYEditor extends Serializable, ILcdCloneable, ILcdPropertyChangeSource
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
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.
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.
|
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.
|
clone
addPropertyChangeListener, removePropertyChangeListener
static final int TRANSLATED
static final int RESHAPED
static final int CREATING
static final int START_CREATION
static final int END_CREATION
void setObject(Object aObject)
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.
aObject
- the object for which the editing shall be handled by this editor.getObject()
Object getObject()
boolean edit(Graphics aGraphics, int aMode, ILcdGXYContext aGXYContext)
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.
aGraphics
- the Graphics on which the representation of the object is paintedaMode
- 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.ILcdGXYContext
,
acceptSnapTarget
int getCreationClickCount()
boolean acceptSnapTarget(Graphics aGraphics, ILcdGXYContext aGXYContext)
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
.
aGraphics
- the Graphics on which the representation of the object is paintedaGXYContext
- the context containing the information on the user interaction and the snap target.ILcdGXYContext.getSnapTarget()
String getDisplayName()