com.luciad.edit.handles

Class PointEditHandle

java.lang.Object

com.luciad.edit.handles.PointEditHandle

All Implemented Interfaces:

IEditHandle, AutoCloseable

public final class PointEditHandle
extends Object
implements AutoCloseable, IEditHandle

This handle represents a Point on the Map and can be visualized using an icon.

It can be moved around, or react to mouse events.

The handle executes IPointEditAction, based on mouse input events. IEditHandles implementations configure concrete IPointEditAction implementations on this handle to make sure they result in geometry or feature changes. For example, when this handle is dragged around on the Map, an IEditHandles implementation for polylines can make sure that the second point of the polyline is moved.

This class supports the following gestures:

• drag events
• click events
• mouse move events

This handle is painted using an icon at its current location.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	PointEditHandle.IVisualAidProvider This interface allows to calculate a visual aid line based on the location of the handle.

Constructor Summary

Constructors

Constructor and Description
PointEditHandle(Observable<Point> locationProvider) Creates a new PointEditHandle without associated actions.
PointEditHandle(Point initialLocation) Creates a new PointEditHandle without associated actions.

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.
EditActionBinder	addOnClickAction(IPointEditAction action, long clickCount) Adds an action that will be triggered when the handle is clicked or tapped (touch).
EditActionBinder	addOnDragAction(IPointEditAction action) Adds an action that will be triggered when the handle is dragged.
EditActionBinder	addOnMouseMoveAction(IPointEditAction action) Adds an action that will be executed on every mouse move.
EditActionBinder	addOnTouchLongPressAction(IPointEditAction action) Adds an action that will be triggered when a long press is performed on a handle.
void	close()
protected void	finalize()
IIcon	getActiveIcon()
ComplexStrokeLineStyle	getActiveVisualAidComplexStrokeLineStyle() Returns the visual aid complex stroke line style to use when this handle is in an active state.
LineStyle	getActiveVisualAidLineStyle() Returns the visual aid line style to use when this handle is in an active state.
EditHandleState	getEditState()
IIcon	getHighlightedIcon()
ComplexStrokeLineStyle	getHighlightedVisualAidComplexStrokeLineStyle() Returns the visual aid complex stroke line style to use when this handle is in a highlighted state.
LineStyle	getHighlightedVisualAidLineStyle() Returns the visual aid line style to use when this handle is in a highlighted state.
Point	getLocation() Returns the current location of this handle.
Observable<Point>	getLocationProvider() Returns the location provider of this handle.
Observable<Point>	getLocationProviderWhenActive()
MouseCursor	getMouseCursor()
EditMoveConstraint	getMoveConstraint()
IIcon	getRegularIcon()
ComplexStrokeLineStyle	getRegularVisualAidComplexStrokeLineStyle() Returns the visual aid complex stroke line style to use when this handle is in an inactive state.
LineStyle	getRegularVisualAidLineStyle() Returns the visual aid line style to use when this handle is in an inactive state.
PointEditHandle.IVisualAidProvider	getVisualAidLineProvider()
int	getZOrder()
boolean	isUseFeatureAsHandle()
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	setActiveIcon(IIcon icon) Sets the icon to paint when the handle is in an active state.
void	setActiveVisualAidComplexStrokeLineStyle(ComplexStrokeLineStyle lineStyle) Sets the visual aid line style to use when this handle is in an active state.
void	setActiveVisualAidLineStyle(LineStyle lineStyle) Sets the visual aid line style to use when this handle is in an active state.
void	setHighlightedIcon(IIcon icon) Sets the icon to paint when the handle is in a highlighted state.
void	setHighlightedVisualAidComplexStrokeLineStyle(ComplexStrokeLineStyle lineStyle) Sets the visual aid line style to use when this handle is in a highlighted state.
void	setHighlightedVisualAidLineStyle(LineStyle lineStyle) Sets the visual aid line style to use when this handle is in a highlighted state.
void	setInvalidationCallback(IInvalidationCallback invalidationCallback) Sets the callback for the handle to call when its visual representation or cursor has changed.
void	setLocationProviderWhenActive(Observable<Point> locationProviderWhenActive)
void	setMoveConstraint(EditMoveConstraint moveConstraint)
void	setRegularIcon(IIcon icon) Sets the icon to paint when the handle is in a regular state.
void	setRegularVisualAidComplexStrokeLineStyle(ComplexStrokeLineStyle lineStyle) Sets the visual aid line style to use when this handle is in an inactive state.
void	setRegularVisualAidLineStyle(LineStyle lineStyle) Sets the visual aid line style to use when this handle is in an inactive state.
void	setUseFeatureAsHandle(boolean useFeatureAsHandle)
void	setVisualAidLineProvider(PointEditHandle.IVisualAidProvider provider) Sets a visual aid line provider that allows to paint a visual aid line together with this handle.
void	setZOrder(int zOrder) Sets the Z-order that is used for this handle's paint calls to the FeatureCanvas.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PointEditHandle

public PointEditHandle(@NotNull
                       Point initialLocation)

Creates a new PointEditHandle without associated actions.

Parameters:

initialLocation - the initial location of the handle, cannot be null

PointEditHandle

public PointEditHandle(@NotNull
                       Observable<Point> locationProvider)

Creates a new PointEditHandle without associated actions.

Parameters:

locationProvider - the location provider of the handle. The handle assumes the location of this point upon construction, while also observing the point to adjust its own location whenever the observable point changes; cannot be null.

Method Detail

finalize

protected void finalize()

Overrides:

finalize in class Object

close

public void close()

Specified by:

close in interface AutoCloseable

onEvent

@NotNull
public 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

Specified by:

onEvent in interface IEditHandle

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

public 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.

Specified by:

paint in interface IEditHandle

Parameters:

canvas - the canvas on which this handle gets painted.

context - the context, cannot be null

getEditState

@NotNull
public EditHandleState getEditState()

Specified by:

getEditState in interface IEditHandle

Returns:

the current state of this handle.

getMouseCursor

@Nullable
public MouseCursor getMouseCursor()

Specified by:

getMouseCursor in interface IEditHandle

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

public 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.

Specified by:

setInvalidationCallback in interface IEditHandle

Parameters:

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

addEditStateObserver

public 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.

Specified by:

addEditStateObserver in interface IEditHandle

Parameters:

observer - an observer

Throws:

IllegalArgumentException - when the observer was already added.

Since:

2023.1

removeEditStateObserver

public void removeEditStateObserver(@NotNull
                                    IInvalidationCallback observer)
                             throws IllegalArgumentException

Removes the given observer.

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

Specified by:

removeEditStateObserver in interface IEditHandle

Parameters:

observer - an observer

Throws:

IllegalArgumentException - when the observer is not known.

Since:

2023.1

getLocation

@Nullable
public Point getLocation()

Returns the current location of this handle.

Note that this location is not necessarily equal to the location provider at all times. For example, they may differ when the handle is dragged around and no location changes are triggered in the location provider.

Returns:

the current location of this handle

getLocationProvider

@NotNull
public Observable<Point> getLocationProvider()

Returns the location provider of this handle.

Note that the handle's current location is not necessarily equal to this location provider at all times. For example, they may differ when the handle is dragged around and no location changes are triggered in this location provider. Additionally, the handle may have a different location provider when it is active. See getLocationProviderWhenActive.

Returns:

the location provider of this handle. Never null.

getLocationProviderWhenActive

@Nullable
public Observable<Point> getLocationProviderWhenActive()

Returns:

locationProviderWhenActive the location provider to use when the handle is active, or null if no distinct location provider is set for when the handle is active.

setLocationProviderWhenActive

public void setLocationProviderWhenActive(@Nullable
                                          Observable<Point> locationProviderWhenActive)

Parameters:

locationProviderWhenActive - the location provider to use when the handle is active. If set, this overrides the regular location provider when the handle is active, Can be null.

getMoveConstraint

@NotNull
public EditMoveConstraint getMoveConstraint()

Returns:

the move constraint of this point handle

setMoveConstraint

public void setMoveConstraint(@NotNull
                              EditMoveConstraint moveConstraint)

Parameters:

moveConstraint - the move constraint of this point handle. By default, this is EditMoveConstraint#XY.

getZOrder

public int getZOrder()

Returns:

the Z-order that is used for this handle's paint calls to the FeatureCanvas.

See Also:

setZOrder, FeatureCanvas, FeatureCanvas.IconDrawCommand#zOrder

setZOrder

public void setZOrder(int zOrder)

Sets the Z-order that is used for this handle's paint calls to the FeatureCanvas.

This Z-order determines which handles are painted on top, when multiple handles overlap. Edit handles with a higher Z-order are painted on top of handles with a lower Z-order. Note: highlighted edit handles are always painted above regular handles, and active handles are always painted above highlighted handles. The default value is 0.

Parameters:

zOrder - the Z-order that is used for this handle's paint calls to the FeatureCanvas. Must be between [-1000,1000].

See Also:

FeatureCanvas, FeatureCanvas.IconDrawCommand#zOrder

getRegularIcon

@Nullable
public IIcon getRegularIcon()

Returns:

the icon to paint when the handle is in a regular state.

See Also:

setRegularIcon

setRegularIcon

public void setRegularIcon(@Nullable
                           IIcon icon)

Sets the icon to paint when the handle is in a regular state.

This icon is only used when setUseFeatureAsHandle is set to false.

Parameters:

icon - the icon to paint when the handle is in a regular (i.e. non-highlighted, non-active) state.

getHighlightedIcon

@Nullable
public IIcon getHighlightedIcon()

Returns:

the icon to paint when the handle is in a highlighted state.

See Also:

setHighlightedIcon

setHighlightedIcon

public void setHighlightedIcon(@Nullable
                               IIcon icon)

Sets the icon to paint when the handle is in a highlighted state.

This icon is only used when setUseFeatureAsHandle is set to false.

Parameters:

icon - the icon to paint when the handle is in a highlighted state.

getActiveIcon

@Nullable
public IIcon getActiveIcon()

Returns:

the icon to paint when the handle is in an active state.

See Also:

setActiveIcon

setActiveIcon

public void setActiveIcon(@Nullable
                          IIcon icon)

Sets the icon to paint when the handle is in an active state.

This icon is only used when setUseFeatureAsHandle is set to false.

Parameters:

icon - the icon to paint when the handle is in an active state

isUseFeatureAsHandle

public boolean isUseFeatureAsHandle()

Returns:

when this is set to true, this handle does not paint any icons for itself.

See Also:

setUseFeatureAsHandle

setUseFeatureAsHandle

public void setUseFeatureAsHandle(boolean useFeatureAsHandle)

Parameters:

useFeatureAsHandle - when this is set to true, this handle does not paint any icons for itself. In this case, the handle considers the feature that is being edited for determining whether it is touched or not. Otherwise, when this is set to false, the handle paints itself as an icon and only considers that icon for deciding whether it is touched. By default, this is false.

setVisualAidLineProvider

public void setVisualAidLineProvider(@Nullable
                                     PointEditHandle.IVisualAidProvider provider)

Sets a visual aid line provider that allows to paint a visual aid line together with this handle.

It is not possible to interact with this line. The line style can be configured using setRegularVisualAidLineStyle. The given provider is allowed

The default is null.

Parameters:

provider - the visual aid line provider. If null, no visual aid line is painted.

getVisualAidLineProvider

@Nullable
public PointEditHandle.IVisualAidProvider getVisualAidLineProvider()

Returns:

the visual aid line provider

See Also:

setVisualAidLineProvider

getRegularVisualAidLineStyle

@Nullable
public LineStyle getRegularVisualAidLineStyle()

Returns the visual aid line style to use when this handle is in an inactive state.

This method is linked to the getRegularVisualAidComplexStrokeLineStyle method:

• if both of them return null, no visual aid line is painted
• if one of them is not null, that line style is used
• it's not possible for both methods to return a non null value: they are mutually exclusive

Returns:

the visual aid line style to use when this handle is in an inactive state.

See Also:

setRegularVisualAidLineStyle

getRegularVisualAidComplexStrokeLineStyle

@Nullable
public ComplexStrokeLineStyle getRegularVisualAidComplexStrokeLineStyle()

Returns the visual aid complex stroke line style to use when this handle is in an inactive state.

This method is linked to the getRegularVisualAidLineStyle method:

• if both of them return null, no visual aid line is painted
• if one of them is not null, that line style is used
• it's not possible for both methods to return a non null value: they are mutually exclusive

Returns:

the visual aid complex stroke line style to use when this handle is in an inactive state.

Since:

2023.1

See Also:

setRegularVisualAidComplexStrokeLineStyle

setRegularVisualAidLineStyle

public void setRegularVisualAidLineStyle(@Nullable
                                         LineStyle lineStyle)

Sets the visual aid line style to use when this handle is in an inactive state.

This style is only used when a visual aid line is set.

Only one regular line style can be set, if this function is called with a non null value when a ComplexStrokeLineStyle has already been set, it will be overwritten.

The default is a small, grey line.

Parameters:

lineStyle - the visual aid line style to use when this handle is in an inactive state.

setRegularVisualAidComplexStrokeLineStyle

public void setRegularVisualAidComplexStrokeLineStyle(@Nullable
                                                      ComplexStrokeLineStyle lineStyle)

Sets the visual aid line style to use when this handle is in an inactive state.

This style is only used when a visual aid line is set.

Only one regular line style can be set, if this function is called with a non null value when a LineStyle has already been set, it will be overwritten.

The default is null, as a linestyle is used as default regular visual aid style.

Parameters:

lineStyle - the visual aid complex stroke line style to use when this handle is in an inactive state.

Since:

2023.1

getHighlightedVisualAidLineStyle

@Nullable
public LineStyle getHighlightedVisualAidLineStyle()

Returns the visual aid line style to use when this handle is in a highlighted state.

This method is linked to the getHighlightedVisualAidComplexStrokeLineStyle method:

• if both of them return null, no visual aid line is painted
• if one of them is not null, that line style is used
• it's not possible for both methods to return a non null value: they are mutually exclusive

Returns:

the visual aid line style to use when this handle is in a highlighted state.

See Also:

setHighlightedVisualAidLineStyle

getHighlightedVisualAidComplexStrokeLineStyle

@Nullable
public ComplexStrokeLineStyle getHighlightedVisualAidComplexStrokeLineStyle()

Returns the visual aid complex stroke line style to use when this handle is in a highlighted state.

This method is linked to the getHighlightedVisualAidLineStyle method:

• if both of them return null, no visual aid line is painted
• if one of them is not null, that line style is used
• it's not possible for both methods to return a non null value: they are mutually exclusive

Returns:

the visual aid complex stroke line style to use when this handle is in a highlighted state.

Since:

2023.1

See Also:

setHighlightedVisualAidComplexStrokeLineStyle

setHighlightedVisualAidLineStyle

public void setHighlightedVisualAidLineStyle(@Nullable
                                             LineStyle lineStyle)

Sets the visual aid line style to use when this handle is in a highlighted state.

This style is only used when a visual aid line is set.

Only one regular line style can be set, if this function is called with a non null value when a ComplexStrokeLineStyle has already been set, it will be overwritten.

The default is a small, grey line.

Parameters:

lineStyle - the visual aid line style to use when this handle is in a highlighted state.

setHighlightedVisualAidComplexStrokeLineStyle

public void setHighlightedVisualAidComplexStrokeLineStyle(@Nullable
                                                          ComplexStrokeLineStyle lineStyle)

Sets the visual aid line style to use when this handle is in a highlighted state.

This style is only used when a visual aid line is set.

Only one highlighted line style can be set, if this function is called with a non null value when a LineStyle has already been set, it will be overwritten.

The default is null, as a linestyle is used as default highlighted visual aid style.

Parameters:

lineStyle - the visual aid complex stroke line style to use when this handle is in a highlighted state.

Since:

2023.1

getActiveVisualAidLineStyle

@Nullable
public LineStyle getActiveVisualAidLineStyle()

Returns the visual aid line style to use when this handle is in an active state.

This method is linked to the getActiveVisualAidComplexStrokeLineStyle method:

• if both of them return null, no visual aid line is painted
• if one of them is not null, that line style is used
• it's not possible for both methods to return a non null value: they are mutually exclusive

Returns:

the visual aid line style to use when this handle is in an active state.

See Also:

setActiveVisualAidLineStyle

getActiveVisualAidComplexStrokeLineStyle

@Nullable
public ComplexStrokeLineStyle getActiveVisualAidComplexStrokeLineStyle()

Returns the visual aid complex stroke line style to use when this handle is in an active state.

This method is linked to the getActiveVisualAidLineStyle method:

• if both of them return null, no visual aid line is painted
• if one of them is not null, that line style is used
• it's not possible for both methods to return a non null value: they are mutually exclusive

Returns:

the visual aid complex stroke line style to use when this handle is in an active state.

Since:

2023.1

See Also:

setActiveVisualAidComplexStrokeLineStyle

setActiveVisualAidLineStyle

public void setActiveVisualAidLineStyle(@Nullable
                                        LineStyle lineStyle)

Sets the visual aid line style to use when this handle is in an active state.

This style is only used when a visual aid line is set.

Only one active line style can be set, if this function is called with a non null value when a ComplexStrokeLineStyle has already been set, it will be overwritten.

The default is a small, grey line.

Parameters:

lineStyle - the visual aid line style to use when this handle is in an active state.

setActiveVisualAidComplexStrokeLineStyle

public void setActiveVisualAidComplexStrokeLineStyle(@Nullable
                                                     ComplexStrokeLineStyle lineStyle)

Sets the visual aid line style to use when this handle is in an active state.

This style is only used when a visual aid line is set.

Only one active line style can be set, if this function is called with a non null value when a LineStyle has already been set, it will be overwritten.

The default is null, as a linestyle is used as default active visual aid style.

Parameters:

lineStyle - the visual aid complex stroke line style to use when this handle is in a EditHandleState#Active state.

Since:

2023.1

addOnClickAction

@NotNull
public EditActionBinder addOnClickAction(@NotNull
                                                  IPointEditAction action,
                                                  long clickCount)

Adds an action that will be triggered when the handle is clicked or tapped (touch).

Parameters:

action - the action to be performed on click, cannot be null.

clickCount - the action will only be performed when an event is received with this click count

Returns:

an object on which more options or requirements can be specified regarding the given on-click action, such as the mouse buttons that need to be pressed for the action to be executed.

addOnTouchLongPressAction

@NotNull
public EditActionBinder addOnTouchLongPressAction(@NotNull
                                                           IPointEditAction action)

Adds an action that will be triggered when a long press is performed on a handle.

Parameters:

action - the action to be performed, cannot be null.

Returns:

an object on which more options or requirements can be specified regarding the given on-drag action

addOnDragAction

@NotNull
public EditActionBinder addOnDragAction(@NotNull
                                                 IPointEditAction action)

Adds an action that will be triggered when the handle is dragged.

The given action is executed at least when the drag gesture starts and ends, and if EditActionBinder#performOnIntermediateEvents is set to true, it also gets executed on every intermediate drag event. The action is always called with an EventStatus parameter corresponding to the drag event.

Parameters:

action - the action to be performed on drag, cannot be null.

Returns:

an object on which more options or requirements can be specified regarding the given on-drag action, such as the mouse buttons that need to be pressed for the action to be executed.

addOnMouseMoveAction

@NotNull
public EditActionBinder addOnMouseMoveAction(@NotNull
                                                      IPointEditAction action)

Adds an action that will be executed on every mouse move.

Parameters:

action - the action to be performed during the mouse move, cannot be null.

Returns:

an object on which more options or requirements can be specified regarding the given action, such as the modifier keys that need to be pressed for the action to be executed.