AnnotationOperator

class HPS::AnnotationOperator : public HPS::Operator

The AnnotationOperator class defines an operator which allows the user to insert annotations. Annotations are text geometries with leader lines and a background. This Operator works for both mouse- and touch-driven devices.

To operate this operator on a mouse-driven device: Click on a piece of geometry and drag the mouse to position an annotation. Start typing to change the annotation text. Once an annotation has been inserted it can be repositioned, and its text can be changed after clicking on it.

To operate this operator on a touch-driven device: Tap on a piece of geometry and drag your finger to position an annotation. Start typing to change the annotation text. Once an annotation has been inserted, tap on it to edit the text. Drag a previously inserted annotation around to reposition it.

An event of type AnnotationInsertedEvent is injected when new annotations are added to the scene.

Public Functions

AnnotationOperator(MouseButtons in_mouse_trigger = MouseButtons::ButtonLeft(), ModifierKeys in_modifier_trigger = ModifierKeys())
UTF8 GetBackgroundShape() const

This function returns the name of the shape definition currently used to draw the annotation background by this operator.

Returns

The name of the shape definition currently used to draw the annotation background

inline virtual HPS::UTF8 GetName() const override

Returns the name of the operator.

virtual bool OnKeyDown(KeyboardState const &in_state) override

This function is called whenever HPS receives a KeyboardState event that signals a button was pressed. This function is used to edit the text of annotations

Parameters

in_state – A KeyboardState object describing the current keyboard state.

Returns

true if the input event was handled, false otherwise.

virtual bool OnMouseDown(MouseState const &in_state) override

This function is called whenever HPS receives a MouseEvent that signals a mouse button was pressed. If the user clicks on a piece of geometry other than an existing annotation, a new annotation will be inserted. If the user clicks on an already inserted annotation, that annotation will become editable (it can be repositioned, and its text can be changed). The user can click on the background to stop editing an annotation.

Parameters

in_state – A MouseState object describing the current mouse state.

Returns

true if the input event was handled, false otherwise.

virtual bool OnMouseMove(MouseState const &in_state) override

This function is called whenever HPS receives a MouseEvent that signals the mouse moved When users are inserting or editing an annotation, they will be able to reposition it by dragging the mouse while holding down the trigger button specified in the operator constructor (defaults to Left mouse button)

Parameters

in_state – A MouseState object describing the current mouse state.

Returns

true if the input event was handled, false otherwise.

virtual bool OnTextInput(HPS::UTF8 const &in_text) override

This function is called whenever HPS receives a TextInput event that signals a text string was received. This function is used to edit the text of annotations from a mobile device.

Parameters

in_text – The text string received.

Returns

true if the input event was handled, false otherwise.

virtual bool OnTouchDown(TouchState const &in_state) override

This function is called whenever HPS receives a TouchEvent that signals the device was touched. If the user taps a piece of geometry other than an existing annotation, a new annotation will be inserted. If the user taps an already inserted annotation, that annotation will become editable (it can be repositioned, and its text can be changed). The user can tap on the background to stop editing an annotation.

Parameters

in_state – A TouchState object describing the current touch state.

Returns

true if the input event was handled, false otherwise.

virtual bool OnTouchMove(TouchState const &in_state) override

This function is called whenever HPS receives a TouchEvent that signals a point of contact has moved. When users are inserting or editing an annotation, they will be able to reposition it by tapping it and dragging their finger

Parameters

in_state – A TouchState object describing the current touch state.

Returns

true if the input event was handled, false otherwise.

virtual bool OnTouchUp(TouchState const &in_state) override

This function is called whenever HPS receives a TouchEvent that signals a point of contact has been released.

Parameters

in_state – A TouchState object describing the current touch state.

Returns

true if the input event was handled, false otherwise.

virtual void OnViewAttached(HPS::View const &in_attached_view) override

This function is called whenever a view is attached to this operator.

Parameters

in_attached_view – The view attached to this operator.

virtual void OnViewDetached(HPS::View const &in_detached_view) override

This function is called whenever a view is detached from this operator.

Parameters

in_detached_view – The view detached from this operator.

void SetBackgroundShape(char const *in_shape)

This function sets the shape which will be use for the annotation background. The shape name provided has to match the name of a shape defined in a portfolio accessible by the view attached to this operator, or to a segment above that. This setting influences all shapes inserted by this operator after it is called, it does not change the shape of annotations already inserted by this operator. By default a rectangle shape (‘box’) is used.

Parameters

in_shape – The name of the shape definition used when inserting annotations.

class AnnotationInsertedEvent : public HPS::Event

An event injected every time a new annotation is inserted. It contains the key of the segment containing the annotation and the view currently attached to this operator. This operator places each annotation in a separate segment.

Public Functions

inline AnnotationInsertedEvent()

The default constructor creates an empty AnnotationInsertedEvent object.

inline AnnotationInsertedEvent(Event const &in_event)

This constructor converts an Event Object to a MarkupInsertedEvent object.

Parameters

in_event – The Event Object to be converted.

inline AnnotationInsertedEvent(HPS::SegmentKey const &in_text_key, HPS::View const &in_view)
inline virtual char const *ClassName() const override
inline virtual Event *Clone() const override

Allocates and returns a copy of this AnnotationInsertedEvent.

Returns

A copy of this MarkupIAnnotationInsertedEventnsertedEvent.

~AnnotationInsertedEvent()

Public Members

SegmentKey text_key
View view