Skip to content

Utterance

Overview

An utterance to be handed off to the AlertQueue, which manages the order of accessibility alerts read by a screen reader.

An utterance to be provided to the AlertQueue. An utterance can be one of TAlertable.

A single Utterance can be added to the utteranceQueue multiple times. This may be so that a number of alerts associated with the utterance get read in order (see alert in options). Or it may be that changes are being alerted rapidly from the same source. An Utterance is considered "unstable" if it is being added rapidly to the utteranceQueue. By default, utterances are only announced when they are "stable", and stop getting added to the queue. This will prevent a large number of alerts from the same interaction from spamming the user. See related options alertStableDelay, and alertMaximumDelay.

@author Jesse Greenberg @author Michael Kauzmann (PhET Interactive Simulations)

Class Utterance

import { Utterance } from 'scenerystack/utterance-queue';

Constructor

new Utterance( providedOptions? : UtteranceOptions )

Instance Methods

getAlertText( respectResponseCollectorProperties ) : ResolvedResponse

Get the string to alert. This function has potential to run a function to generate the string. Use this with caution. Most often UtteranceQueue should be the only spot calling this. @param respectResponseCollectorProperties=false - if false, then do not listen to the value of responseCollector for creating the ResponsePacket conglomerate (just combine all that are supplied).

getAlert() : AlertableNoUtterance

setAlert( alert : AlertableNoUtterance )

setAlertStableDelay( delay : number )

Set the alertStableDelay time, see alertStableDelay option for more information.

BEWARE! Why does the delay time need to be changed during the lifetime of an Utterance? It did for https://github.com/phetsims/gravity-force-lab-basics/issues/146, but does it for you? Be sure there is good reason changing this value.

toString() : string

toStateObject() : SerializedUtterance

reset()

setCanAnnounceProperties( canAnnounceProperties : TReadOnlyProperty<boolean>[] )

Set the Properties controlling whether this Utterance can announce. All Properties must be true for the alert content of this Utterance to be announced. These Properties are used in the implementation of this.canAnnounceProperty. Setting new canAnnounceProperties has no impact on the listeners added to this.canAnnounceProperty.

getCanAnnounceProperties() : TReadOnlyProperty<boolean>[]

Get the Properties that control whether the alert content for this Utterance can be announced. All must be true for the announcement to occur.

setDescriptionCanAnnounceProperties( descriptionCanAnnounceProperties : TReadOnlyProperty<boolean>[] )

Set the Properties controlling whether this Utterance can announce to AriaLiveAnnouncer. All Properties must be true for the alert content of this Utterance to be announced. These Properties are used in the implementation of this.descriptionCanAnnounceProperty. Setting new descriptionCanAnnounceProperties has no impact on the listeners added to this.descriptionCanAnnounceProperty. To announce to AriaLiveAnnouncer, this.canAnnounceProperty must also be true

getDescriptionCanAnnounceProperties() : TReadOnlyProperty<boolean>[]

Get the Properties that control whether the alert content for this Utterance can be announced. All must be true for the announcement to occur.

setVoicingCanAnnounceProperties( voicingCanAnnounceProperties : TReadOnlyProperty<boolean>[] )

Set the Properties controlling whether this Utterance can announce to SpeechSynthesisAnnouncer. All Properties must be true for the alert content of this Utterance to be announced. These Properties are used in the implementation of this.voicingCanAnnounceProperty. Setting new voicingCanAnnounceProperties has no impact on the listeners added to this.voicingCanAnnounceProperty. To announce to SpeechSynthesisAnnouncer, this.canAnnounceProperty must also be true.

getVoicingCanAnnounceProperties() : TReadOnlyProperty<boolean>[]

Get the Properties that control whether the alert content for this Utterance can be announced. All must be true for the announcement to occur.

dispose()

Make eligible for garbage collection.

Instance Properties

canAnnounceProperty : AnnouncingControlProperty

(readonly)

If the value of this Property is false, this Utterance will never be announced by an Announcer. See documentation for canAnnounceImplementationProperty for implementation details and why we use a DynamicProperty.

descriptionCanAnnounceProperty : AnnouncingControlProperty

(readonly)

If the value of this Property is false, this Utterance will never be announced by AriaLiveAnnouncer.

voicingCanAnnounceProperty : AnnouncingControlProperty

(readonly)

If the value of this Property is false, this Utterance will never be announced by SpeechSynthesisAnnouncer.

priorityProperty : TProperty<number>

observable for the priority, can be set to change the priority of this Utterance while it is still in the UtteranceQueue. See options documentation for behavior of priority.

Static Methods

alertableToText( alertable : TAlertable, respectResponseCollectorProperties ) : ResolvedResponse

@param alertable @param respectResponseCollectorProperties=false - if false, then do not listen to the value of responseCollector for creating the ResponsePacket conglomerate (just combine all that are supplied).

Static Properties

TOP_PRIORITY

(readonly)

Priority levels that can be used by Utterances providing the announcerOptions.priority option.

HIGH_PRIORITY

(readonly)

MEDIUM_PRIORITY

(readonly)

DEFAULT_PRIORITY

(readonly)

LOW_PRIORITY

(readonly)

UtteranceIO : IOType

(readonly)

Type FeatureSpecificAnnouncingControlProperty

The names of Properties that can be accessed on Utterance that are AnnouncingControlProperties for specific Announcing features.

import type { FeatureSpecificAnnouncingControlProperty } from 'scenerystack/utterance-queue';

"descriptionCanAnnounceProperty" | "voicingCanAnnounceProperty"

Type TAlertable

import type { TAlertable } from 'scenerystack/utterance-queue';

ResolvedResponse | ( () => string ) | TReadOnlyProperty<string> | ResponsePacket | Utterance

Type UtteranceOptions

import type { UtteranceOptions } from 'scenerystack/utterance-queue';
  • alert?: AlertableNoUtterance
    The content of the alert that this Utterance is wrapping.
  • canAnnounceProperties?: TReadOnlyProperty<boolean>[]
    List of Properties that must all be true in order for the Utterance to be announced by the Announcer. See setCanAnnounceProperties() for more information.
  • descriptionCanAnnounceProperties?: TReadOnlyProperty<boolean>[]
    List of Properties that must all be true in order for the Utterance to be announced to the Interactive Description feature of PhET Simulations. canAnnounceProperties also apply (and so must all be true) to announce with this specific feature.
  • voicingCanAnnounceProperties?: TReadOnlyProperty<boolean>[]
    List of Properties that must all be true in order for the Utterance to be announced to the Voicing feature of PhET Simulations. canAnnounceProperties also apply (and so must all be true) to announce with this specific feature.
  • predicate?: () => boolean
    if predicate returns false, the alert content associated with this utterance will not be announced by the utterance-queue. Announcers also optionally have the ability to respect this predicate before they finally alert the Utterance. This can be helpful if utterances sit and wait in the announcer before being alerted. If the predicate fails there is no retry. The utterance will be removed from the queue without announcing.
  • alertStableDelay?: number
    in ms, how long to wait before the utterance is considered "stable" and stops being added to the queue, at which point it will be spoken. Default value chosen because it sounds nice in most usages of Utterance with alertStableDelay. If you want to hear the utterance as fast as possible, reduce this delay to 0. See https://github.com/phetsims/scenery-phet/issues/491
  • alertMaximumDelay?: number
    in ms, the maximum amount of time that should pass before this alert should be spoken, even if the utterance is rapidly added to the queue and is not quite "stable"
  • announcerOptions?: Record<string, unknown>
    Options specific to the Announcer of the Utterance. See supported options in your specific Announcer's announce() function (for example AriaLiveAnnouncer.announce())
  • priority?: number
    {number} - Used to determine which utterance might interrupt another utterance. Please only use priority statics on Utterance when setting this value like Utterance.MEDIUM_PRIORITY. Any utterance (1) with a higher priority than another utterance (2) will behave as such:
  • (1) will interrupt (2) when (2) is currently being spoken, and (1) is announced by the voicingManager. In this case, (2) is interrupted, and never finished.
  • (1) will continue speaking if (1) was speaking, and (2) is added to the UtteranceQueue. In this case (2) will be spoken when (1) is done. In this case (2) will remain in the queue while waiting for (1) to finish.
  • & DisposableOptions

Source Code

See the source for Utterance.ts in the utterance-queue repository.