LuciadCPillar 2024.0
luciad::IEditHandle Class Referenceabstract

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

#include <luciad/edit/handles/IEditHandle.h>

Inheritance diagram for luciad::IEditHandle:
luciad::PointEditHandle luciad::TranslateEditHandle

Public Member Functions

 IEditHandle ()
 Creates a new edit handle instance. More...
 
virtual ~IEditHandle ()=default
 
virtual void addEditStateObserver (std::shared_ptr< IInvalidationCallback > observer)=0
 Adds an observer that is called when the edit state of this handle has changed. More...
 
virtual EditHandleState getEditState () const =0
 Returns the current state of this handle. More...
 
virtual std::optional< MouseCursorgetMouseCursor () const =0
 Returns the current mouse cursor that should be displayed for this handle. More...
 
virtual EventResult onEvent (const std::shared_ptr< IInputEvent > &inputEvent, const std::shared_ptr< FeatureEditContext > &context)=0
 Handles the given event, and returns if the event was consumed or not. More...
 
virtual void paint (FeatureCanvas &canvas, const std::shared_ptr< FeatureEditContext > &context) const =0
 Paints this handle on the given canvas. More...
 
virtual void removeEditStateObserver (const std::shared_ptr< IInvalidationCallback > &observer)=0
 Removes the given observer. More...
 
virtual void setInvalidationCallback (std::shared_ptr< IInvalidationCallback > invalidationCallback)=0
 Sets the callback for the handle to call when its visual representation or cursor has changed. More...
 

Detailed Description

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 luciad::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.
Since
2020.1

Constructor & Destructor Documentation

◆ IEditHandle()

luciad::IEditHandle::IEditHandle ( )

Creates a new edit handle instance.

◆ ~IEditHandle()

virtual luciad::IEditHandle::~IEditHandle ( )
virtualdefault

Member Function Documentation

◆ addEditStateObserver()

virtual void luciad::IEditHandle::addEditStateObserver ( std::shared_ptr< IInvalidationCallback observer)
pure virtual

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
observeran observer
Exceptions
InvalidArgumentExceptionwhen the observer was already added.
Since
2023.1

Implemented in luciad::PointEditHandle, and luciad::TranslateEditHandle.

◆ getEditState()

virtual EditHandleState luciad::IEditHandle::getEditState ( ) const
pure virtual

Returns the current state of this handle.

Returns
the current state of this handle.

Implemented in luciad::PointEditHandle, and luciad::TranslateEditHandle.

◆ getMouseCursor()

virtual std::optional< MouseCursor > luciad::IEditHandle::getMouseCursor ( ) const
pure virtual

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, std::nullopt can be returned.

Returns
the current mouse cursor that should be displayed for this handle.

Implemented in luciad::PointEditHandle, and luciad::TranslateEditHandle.

◆ onEvent()

virtual EventResult luciad::IEditHandle::onEvent ( const std::shared_ptr< IInputEvent > &  inputEvent,
const std::shared_ptr< FeatureEditContext > &  context 
)
pure virtual

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
inputEventthe event to handle, cannot be nullptr
contextthe context, cannot be nullptr
Returns
if the event was consumed or not
Exceptions
NullArgumentExceptionwhen nullptr is passed.

Implemented in luciad::PointEditHandle, and luciad::TranslateEditHandle.

◆ paint()

virtual void luciad::IEditHandle::paint ( FeatureCanvas canvas,
const std::shared_ptr< FeatureEditContext > &  context 
) const
pure virtual

Paints this handle on the given canvas.

This method is called when

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

Parameters
canvasthe canvas on which this handle gets painted.
contextthe context, cannot be nullptr

Implemented in luciad::PointEditHandle, and luciad::TranslateEditHandle.

◆ removeEditStateObserver()

virtual void luciad::IEditHandle::removeEditStateObserver ( const std::shared_ptr< IInvalidationCallback > &  observer)
pure virtual

Removes the given observer.

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

Parameters
observeran observer
Exceptions
InvalidArgumentExceptionwhen the observer is not known.
Since
2023.1

Implemented in luciad::PointEditHandle, and luciad::TranslateEditHandle.

◆ setInvalidationCallback()

virtual void luciad::IEditHandle::setInvalidationCallback ( std::shared_ptr< IInvalidationCallback invalidationCallback)
pure virtual

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
invalidationCallbackthe callback for the handle to call when its visual representation has changed

Implemented in luciad::PointEditHandle, and luciad::TranslateEditHandle.