AnnotationBase

The AnnotationBase node is the abstract base for all the annotation node types. This means is not possible to create a node of this type directly. It inherits from RectBase2D and contains all the properties to customize shape and handles and perform selection.

Platform Support

This element is fully supported on XR-Windows, XR-Portable Windows, XR-Portable iOS, XR-Portable Android, and XR-P WASM platforms.

Features

The main common features are:

• Customizing shape aspect

• Customizing handlers aspect

• AutoSelection logic

Shape aspect customization

All annotations have a line-based shape. Some annotations may include a text area.

The AnnotationBase provides settings to customize the look of the shape when it is selected and when it is not selected.

• Shape: shapeThickness, shapeColor, shapeSelectedColor

• Border: shapeUseBorder, shapeBorderThickness, shapeBorderColor.

• Style: shapeLineStyle, shapeLineCustomPattern

  Note: Style applies to line only, while the border remains solid. It's possible to hide or make the border color partially transparent to change the effect.

Handles aspect customization

Handles are used to resize the Annotation node. Each annotation can have a different number of handles. The handles are represented as circle elements and they offer more or less the same configuration options as available for the shape.

• Handle: handleRadius, handleColor, handleSelectedColor.

• Border: handleUseBorder, handleBorderThickness, handleBorderColor.

AutoSelection

AnnotationBase exposes a selected field for changing the annotation state. When the annotation is selected, the handles are shown and the field can be moved by dragging on its shape.

Besides the direct management of the selected field, AnnotationBase offers a prebuilt selection mechanism that works for all and only those nodes that have the autoSelection field set to true.

When performing mouseDown (with mouse, with touch, with virtual hand on an ItemMonitor) event on a shape contour—that node becomes selected. If another node was already selected, it gets automatically unselected.

When performing a mouseDown out of the selected annotation node and not on another node shape, the node gets unselected.

Note: Automatic selection does not manages the sorting of the objects.

Joining Selection

Disabling autoSelection can be used to join two or more annotations, so that all of them get selected when clicking on one of them.

The idea is to have a master annotation whose selected state is copied on the others who have the autoSelection set to false.

The dependant annotations can then use the Hit events to trigger the selection on the master one.

Because this behavior can introduce some race conditions due to the sorting of the annotation, we suggest adding some conditional clause to the routes.

Code example

This code example shows how to join an AnnotationText and an AnnotationArrow to form a callout object that can be selected as a single item.

<!-- definition of the annotations that have a joint selection -->

<AnnotationText name="text" position="200 200" text="Your text here!" shapeBorderThickness="10" visible="true" />

<AnnotationArrow" name="arrow" shapeThickness="10" autoSelection="false" position="200 300" size="200 100" order="90" visible="true"/>

<!-- copying master text selection into dependant arrow -->

<!-- the condition avoids race conditions preventing unselection when hitting on the arrow -->

<createroute from="text.selected" to="arrow.selected" condition="[?[@text.selected],true,[?[@arrow.hitOnShape.isModified],false,[?[@arrow.hitOnHandle.isModified],false,true]]]" />

<!-- selecting the text when hitting on the arrow -->

<createroute from="arrow.hitOnShape" to="text.selected" value="true" />

<createroute from="arrow.hitOnHandle" to="text.selected" value="true" />

Hit info

AnnotationBase provides a set of events that are triggered when interacting with the node. The hit events are raised when a down (mouse/touch/hand) event happens on an annotation node.

Depending on what is hit, one of the following events are raised:

• hitOnShape—When hitting the shape.

• hitOnHandleHit—When hitting an handle.

• hitOnBlank—When hitting on an empty area.

Handles

Every AnnotationBase derived node can have one or multiple handles that are used to manipulate it. Each handle exposes a set of fields that can be used for customization and observation.

When an handle is set to not active, it's not shown over the node when in selection state.

Touchscreen support

By default, interactions with AnnotationBase-derived nodes are optimized for cursor-based setups.

To improve precision and usability of the same on touchscreen devices, the interactionRadius, shapeThickness and handleRadius fields should be properly adjusted.

The interactionRadius should be adjusted based on the number of pixels covered by the fingertip, which is influenced by the screen's DPI (dots per inch).

For instance, if the shapeThickness of an AnnotationBase-derived node is set to 6, and the fingertip covers approximately 30 pixels in diameter, a suitable interactionRadius value could be 12. This ensures that the shape is detected within the entire area covered by the fingertip.

AnnotationBase fields

These are the fields for AnnotationBase node. Only the node-specific fields are indicated, not fields obtained by inheritance.

Field inheritance: NodeBase > RectBase2D > AnnotationBase

Handle parameters

The attributes of the handle of an AnnotationBase node can be accessed with the syntax:

handle\[HANDLE NAME]\[ATTRIBUTE NAME]

Note: that when patching one of these fields, you need to use dots instead of back-slash characters:

<patch name="annRect" handle.top-left.active="false" />

Also note that when resolving these type of fields at runtime, you need to use double backslashes, like in the following example since the back-slash is also used for character escape.

<setfield name="mySStringVar.value" value="[@annRect.handle\\top-left\\active]" />