Referenceannotation

<annotation>

An annotation for screen reader navigation of a graph

<annotation> describes a single graph element for screen-reader navigation when a <graph> is rendered through the Prefigure backend. Each <annotation> attaches to a referenced component (with the ref attribute) and supplies the spoken text that assistive technology will read when the user navigates to that element.

Annotations must be placed inside an <annotations> child of a <graph>. Only the first (root) <annotation> child is used, and it should, in general, describe the entire graph. Any additional <annotation> components that sit inside the <annotations> but are not nested inside the first <annotation> are ignored.

To annotate individual components of the graph, nest additional <annotation> components inside the root <annotation>. If an <annotation> references a component in the graph via the ref attribute, it annotates that one component. Alternatively, if an <annotation> contains multiple <annotation> children, it annotates the entire group of components as a unit (e.g. a cluster of points whose individual points are sub-annotations).

Attributes and Properties

Attributes for <annotation>

Other (5)

boolean. Default value: false. Whether navigation through this annotation's children wraps around.

ref

reference. Reference to the component this annotation is attached to.

boolean. Default value: false. Whether to play a tone when this annotation is focused and it references a function.

text. More detailed spoken text used by screen readers; used if expert mode is activated or extra details are requested.

text

text. The annotation text read by screen readers.

Common to all components (9)
copy

reference. Create an independent copy of another component by reference. Enter a references a $name.

disabled

boolean. Default value: false. Whether this component is disabled and cannot be interacted with.

extend

reference. Extend another component by reference, inheriting its children and attributes. Enter a reference as $name.

fixed

boolean. Default value: false. Whether this component's value is fixed and cannot be modified.

fixLocation

boolean. Default value: false. Whether this component's location is fixed (preventing it from being moved while still allowing other modifications).

hide

boolean. Default value: false. Whether to hide this component from the rendered output.

isResponse

boolean. Default value: false. Whether this component is treated as a response for the purposes of assessment.

name

text. The name used to reference this component from elsewhere in the document.

styleNumber

integer. Default value: 1. The style number used to select this component's visual styling from the available style definitions.

Properties for <annotation name="a">

Other (8)
$a.circular

boolean. Whether navigation through this annotation's children wraps around.

$a.disabled

boolean. Whether this component is disabled and cannot be interacted with.

$a.fixed

boolean. Whether this component's value is fixed and cannot be modified.

$a.fixLocation

boolean. Whether this component's location is fixed (preventing it from being moved while still allowing other modifications).

$a.hidden

boolean. Whether this component is hidden from the rendered output.

$a.sonify

boolean. Whether to play a tone when this annotation is focused and it references a function.

$a.speech

text. More detailed spoken text used by screen readers; used if expert mode is activated or extra details are requested.

$a.text

text. The annotation text read by screen readers.

Common to all components (4)
$a.doenetML

text. The DoenetML source code that produced this component.

$a.hide

boolean. Whether to hide this component from the rendered output.

$a.isResponse

boolean. Whether this component is treated as a response for the purposes of assessment.

$a.styleNumber

integer. The style number used to select this component's visual styling from the available style definitions.

Examples

Example: Label a single point

The <annotation> references the named point with ref="$P" and supplies the text screen readers announce when the user navigates to that point. References inside the text value (here $P.x and $P.y) are substituted in, so the announcement updates as the point moves.

Example: Nested annotations for a group of points

Nesting <annotation> elements groups related graph elements together under a parent annotation, allowing screen-reader users to navigate from the group description down to individual members.

Attribute Examples

Attribute Example: speech

When speech is set, screen readers read out the text attribute by default and read out the extra speech details when the user presses W. Alternatively, when the user turns on expert mode by pressing X, the screen reader reads out the speech attribute (if set) in place of text.

Attribute Example: sonify

Setting sonify to true on an <annotation> that references a function lets the user press O to sound out the shape of the function.

Attribute Example: circular

When circular is set on a parent <annotation>, navigating past the last child wraps back to the first child. Useful for describing closed shapes (cycles, polygons) where there is no natural “end”.

animateFromSequenceannotations