com.luciad.edit.handles

Interface IEditHandle

All Known Implementing Classes:

PointEditHandle, TranslateEditHandle

public interface IEditHandle

An edit handle is a visual element on the Map that can react to events to perform an edit operation.

Edit handles are used in the context of a IEditHandles. IEditHandles implementations are responsible for providing and updating edit handles during editing. IEditHandles implementations typically allow to replace/customize/remove handles.

Edit handles can have one of 3 states. This state determines:

• the order in which the Editor passes events to handles
• the order in which the Editor gets the mouse cursor from a handle
• how a handle can paint itself. Highlighted or Active handles are typically painted differently than Inactive handles.

The edit handle is responsible for deciding when it needs to be repainted. For that purpose, it is given an IInvalidationCallback, see setInvalidationCallback. This invalidation callback must be called whenever the handle needs to be repainted.

Concrete implementations of this interface have specific behavior. For example:

• PointEditHandle: allows you to move a point to a new location, or apply an action to a point location, insert a new point in a Polyline for example. This handle typically paints itself as an IIcon.
• TranslateEditHandle: allows you to translate a Geometry to a new location. This handle typically doesn't paint itself, because the Geometry to be moved is already painted.

Method Summary

Modifier and Type	Method and Description
void	addEditStateObserver(IInvalidationCallback observer) Adds an observer that is called when the edit state of this handle has changed.
EditHandleState	getEditState()
MouseCursor	getMouseCursor()
EventResult	onEvent(IInputEvent inputEvent, FeatureEditContext context) Handles the given event, and returns if the event was consumed or not.
void	paint(FeatureCanvas canvas, FeatureEditContext context) Paints this handle on the given canvas.
void	removeEditStateObserver(IInvalidationCallback observer) Removes the given observer.
void	setInvalidationCallback(IInvalidationCallback invalidationCallback) Sets the callback for the handle to call when its visual representation or cursor has changed.

Method Detail

onEvent

@NotNull
EventResult onEvent(@NotNull
                             IInputEvent inputEvent,
                             @NotNull
                             FeatureEditContext context)
                      throws NullPointerException

Handles the given event, and returns if the event was consumed or not.

While handling events, IEditHandles can mark themselves as highlighted or as Active. Related to event handling, the main effect of this is that highlighted or active handles get a higher priority compared to other handles: they get the chance to consume events first. See EditHandleState

Parameters:

inputEvent - the event to handle, cannot be null

context - the context, cannot be null

Returns:

if the event was consumed or not

Throws:

NullPointerException - when null is passed.

paint

void paint(@NotNull
           FeatureCanvas canvas,
           @NotNull
           FeatureEditContext context)

Paints this handle on the given canvas.

This method is called when

• the handle's IEditHandles fires an EditHandlesEvent containing this handle, when the handle is newly added or removed for example.
• the handle triggers a new paint call itself by calling its invalidation callback.

This method only gets called on the UI thread, so there is no need for additional synchronization.

Parameters:

canvas - the canvas on which this handle gets painted.

context - the context, cannot be null

getEditState

@NotNull
EditHandleState getEditState()

Returns:

the current state of this handle.

getMouseCursor

@Nullable
MouseCursor getMouseCursor()

Returns:

the current mouse cursor that should be displayed for this handle. This method typically returns a value when this handle is highlighted or active. If not, null can be returned.

setInvalidationCallback

void setInvalidationCallback(@Nullable
                             IInvalidationCallback invalidationCallback)

Sets the callback for the handle to call when its visual representation or cursor has changed.

Calling this callback triggers a new call to this handle's paint method.

Parameters:

invalidationCallback - the callback for the handle to call when its visual representation has changed

addEditStateObserver

void addEditStateObserver(@NotNull
                          IInvalidationCallback observer)
                   throws IllegalArgumentException

Adds an observer that is called when the edit state of this handle has changed.

Adding the same observer twice is forbidden, and will cause an exception to be thrown.

Parameters:

observer - an observer

Throws:

IllegalArgumentException - when the observer was already added.

Since:

2023.1

removeEditStateObserver

void removeEditStateObserver(@NotNull
                             IInvalidationCallback observer)
                      throws IllegalArgumentException

Removes the given observer.

If the given observer was never added, an exception is thrown.

Parameters:

observer - an observer

Throws:

IllegalArgumentException - when the observer is not known.

Since:

2023.1