UtteranceQueue¶

Overview¶

Manages a queue of Utterances that are read in order by assistive technology (AT). This queue typically reads things in a first-in-first-out manner, but it is possible to send an alert directly to the front of the queue. Items in the queue are sent to AT front to back, driven by AXON/timer.

An Utterance instance is used as a unique value to the UtteranceQueue. If you add an Utterance a second time to the, queue, the queue will remove the previous instance, and treat the new addition as if the Utterance has been in the queue the entire time, but in the new position.

AT are inconsistent in the way that they order alerts, some use last-in-first-out order, others use first-in-first-out order, others just read the last alert that was provided. This queue manages order and improves consistency.

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

Class UtteranceQueue¶

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

Constructor¶

new UtteranceQueue( announcer : A, providedOptions? : UtteranceQueueOptions )¶

Instance Methods¶

addToBack( utterance : TAlertable )¶

Add an utterance ot the end of the queue. If the utterance has a type of alert which is already in the queue, the older alert will be immediately removed.

addToFront( utterance : TAlertable )¶

Add an utterance to the front of the queue to be read immediately. @deprecated

removeUtterance( utterance : Utterance )¶

Remove an Utterance from the queue. This function is only able to remove Utterance instances, and cannot remove other TAlertable types.

hasUtterance( utterance : Utterance ) : boolean¶

Returns true if the utterances is in this queue.

clear()¶

Clear the utteranceQueue of all Utterances, any Utterances remaining in the queue will not be announced by the screen reader.

cancelUtterance( utterance : Utterance )¶

Cancel the provided Utterance if it is being spoken by the Announcer. Removes the Utterance from the queue if it is not being spoken by the announcer. Does nothing to other Utterances. The Announcer implements the behavior to stop speech.

cancel()¶

Clears all Utterances from the queue and cancels announcement of any Utterances that are being announced by the Announcer.

setMuted( isMuted : boolean )¶

Set whether or not the utterance queue is muted. When muted, Utterances will still move through the queue, but nothing will be sent to assistive technology.

getMuted() : boolean¶

Get whether or not the utteranceQueue is muted. When muted, Utterances will still move through the queue, but nothing will be read by asistive technology.

setEnabled( isEnabled : boolean )¶

Set whether or not the utterance queue is enabled. When enabled, Utterances cannot be added to the queue, and the Queue cannot be cleared. Also nothing will be sent to assistive technology.

isEnabled() : boolean¶

Get whether or not the utterance queue is enabled. When enabled, Utterances cannot be added to the queue, and the Queue cannot be cleared. Also nothing will be sent to assistive technology.

announceImmediately( utterance : TAlertable )¶

Immediately announce the provided Utterance. If the Announcer is ready to announce, the Utterance will be announced synchronously with this call. Otherwise, the Utterance will be added to the front of the queue to be announced as soon as the Announcer is ready.

This function should generally not be used. Use addToBack() in correlation with priorityProperty and timing variables to control the flow of Utterances. This function can be useful when you need an Utterance to be announced synchronously with user input (for example, due to browser constraints on initializing SpeechSynthesis).

Any duplicate instance of the provided Utterance that is already in the queue will be removed, matching the behavior of addToBack().

announceImmediately() respects Utterance.priorityProperty. A provided Utterance with a priority equal to or lower than what is being announced will not interrupt and will never be announced. If an Utterance at the front of the queue has a higher priority than the provided Utterance, the provided Utterance will never be announced. If the provided Utterance has a higher priority than what is at the front of the queue or what is being announced, it will be announced immediately and interrupt the announcer. Otherwise, it will never be announced.

dispose()¶

Instance Properties¶

announcer : A¶

(readonly)

Sends browser requests to announce either through aria-live with a screen reader or SpeechSynthesis with Web Speech API (respectively), or any method that implements this interface. Use with caution, and only with the understanding that you know what Announcer this UtteranceQueue instance uses.

Static Methods¶

fromFactory() : UtteranceQueue¶

Simple factory to wire up all steps for using UtteranceQueue for aria-live alerts. This accomplishes the three items needed for UtteranceQueue to run: 1. Step stepTimer on animation frame (passing it elapsed time in seconds) 2. Add UtteranceQueue's aria-live elements to the document 3. Create the UtteranceQueue instance

Source Code¶

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