ScreenReader

Implements: IScreenReader

A ScreenReader instance can be used to launch and control the default screen reader for the environment: VoiceOver for MacOS and NVDA for Windows.

Here's a typical example using a ScreenReader instance:

import { screenReader } from "@guidepup/guidepup";

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // Move to the next item.
  await screenReader.next();

  // Stop the screen reader.
  await screenReader.stop();
})();

See also:

• NVDA
• VoiceOver

Contents:

• screenReader.name
• screenReader.act([options])
• screenReader.clearItemTextLog()
• screenReader.clearSpokenPhraseLog()
• screenReader.click([options])
• screenReader.default()
• screenReader.detect()
• screenReader.interact([options])
• screenReader.itemText()
• screenReader.itemTextLog()
• screenReader.lastSpokenPhrase()
• screenReader.next([options])
• screenReader.perform(command, [options])
• screenReader.press(key, [options])
• screenReader.previous([options])
• screenReader.spokenPhraseLog()
• screenReader.start([options])
• screenReader.stop([options])
• screenReader.stopInteracting([options])
• screenReader.type(text[, options])

screenReader.name

Getter for the screen reader name, either "NVDA" or "VoiceOver".

import { screenReader } from "@guidepup/guidepup";

console.log(screenReader.name); // "NVDA" or "VoiceOver"

Returns: string

screenReader.act([options])

Perform the default action for the item in the screen reader cursor.

import { screenReader } from "@guidepup/guidepup";

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // Move to the next item.
  await screenReader.next();

  // Perform the default action for the item.
  await screenReader.act();

  // Stop the screen reader.
  await screenReader.stop();
})();

Parameters:

• Optional: options CommandOptions Additional options.

Returns: Promise<void>

screenReader.clearItemTextLog()

Clear the log of all visited item text for this screen reader instance.

import { screenReader } from "@guidepup/guidepup";

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // ... perform some commands.

  // Clear the item text log.
  await screenReader.clearItemTextLog();

  // Stop the screen reader.
  await screenReader.stop();
})();

Returns: Promise<void>

screenReader.clearSpokenPhraseLog()

Clear the log of all spoken phrases for this screen reader instance.

import { screenReader } from "@guidepup/guidepup";

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // ... perform some commands.

  // Clear the spoken phrase log.
  await screenReader.clearSpokenPhraseLog();

  // Stop the screen reader.
  await screenReader.stop();
})();

Returns: Promise<void>

screenReader.click([options])

Click the mouse.

import { screenReader } from "@guidepup/guidepup";

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // Left-click the mouse.
  await screenReader.click();

  // Left-click the mouse using specific options.
  await screenReader.click({ button: "left", clickCount: 1 });

  // Double-right-click the mouse.
  await screenReader.click({ button: "right", clickCount: 2 });

  // Stop the screen reader.
  await screenReader.stop();
})();

Parameters:

• Optional: options ClickOptions Click options.

Returns: Promise<void>

screenReader.default()

Detect whether the screen reader is the default screen reader for the current OS.

When using a ScreenReader instance this will always return true.

import { screenReader } from "@guidepup/guidepup";

(() => {
  const isDefaultScreenReader = screenReader.default();

  console.log(isDefaultScreenReader); // true
})();

Returns: Promise<boolean>

screenReader.detect()

Detect whether the screen reader is supported for the current OS.

When using a ScreenReader instance this will always return true.

import { screenReader } from "@guidepup/guidepup";

(async () => {
  const isSupportedScreenReader = await screenReader.detect();

  console.log(isSupportedScreenReader);
})();

Returns: Promise<boolean>

screenReader.interact([options])

Interact with the item under the screen reader cursor.

Provided as a compatibility layer for VoiceOver; NVDA does not require users to perform an additional command to interact with the item in the NVDA cursor.

import { screenReader } from "@guidepup/guidepup";

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // Move to the next item.
  await screenReader.next();

  // Interact with the item - does nothing on NVDA.
  await screenReader.interact();

  // Stop the screen reader.
  await screenReader.stop();
})();

Parameters:

• Optional: options CommandOptions Additional options.

Returns: Promise<void>

screenReader.itemText()

Get the text of the item in the screen reader cursor.

import { screenReader } from "@guidepup/guidepup";

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // Move to the next item.
  await screenReader.next();

  // Get the text (if any) for the item currently in focus by the screen reader
  // cursor.
  const itemText = await screenReader.itemText();
  console.log(itemText);

  // Stop the screen reader.
  await screenReader.stop();
})();

Returns: Promise<string> The item's text.

screenReader.itemTextLog()

Get the log of all visited item text for this screen reader instance.

import { screenReader } from "@guidepup/guidepup";

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // Move through several items.
  for (let i = 0; i < 10; i++) {
    await screenReader.next();
  }

  // Get the text (if any) for all the items visited by the screen reader cursor.
  const itemTextLog = await screenReader.itemTextLog();
  console.log(itemTextLog);

  // Stop the screen reader.
  await screenReader.stop();
})();

Returns: Promise<Array<string>> The item text log.

screenReader.lastSpokenPhrase()

Get the last spoken phrase.

import { screenReader } from "@guidepup/guidepup";

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // Move to the next item.
  await screenReader.next();

  // Get the phrase spoken by the screen reader from moving to the next item above.
  const lastSpokenPhrase = await screenReader.lastSpokenPhrase();
  console.log(lastSpokenPhrase);

  // Stop the screen reader.
  await screenReader.stop();
})();

Returns: Promise<string> The last spoken phrase.

screenReader.next([options])

Move the screen reader cursor to the next location.

import { screenReader } from "@guidepup/guidepup";

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // Move to the next item.
  await screenReader.next();

  // Stop the screen reader.
  await screenReader.stop();
})();

Parameters:

• Optional: options CommandOptions Additional options.

Returns: Promise<void>

screenReader.perform(command[, options])

Perform a screen reader command.

import {
  NVDAKeyCodeCommands,
  voiceOverKeyCodeCommands,
} from "@guidepup/guidepup";

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // Type using a custom keystroke command.
  await screenReader.perform({ characters: "my-username" });

  if (screenReader.name === "NVDA") {
    await screenReader.perform(NVDAKeyCodeCommands.performDefaultActionForItem);
  } else {
    await screenReader.perform(
      voiceOverKeyCodeCommands.performDefaultActionForItem,
    );
  }

  // Stop the screen reader.
  await screenReader.stop();
})();

Parameters:

• command any Screen reader command to execute.
• Optional: options CommandOptions Additional options.

Returns: Promise<void>

screenReader.press(key[, options])

Press a key on the focused item.

key can specify the intended keyboardEvent.key value or a single character to generate the text for. A superset of the key values can be found on the MDN key values page. Examples of the keys are:

F1 - F20, Digit0 - Digit9, KeyA - KeyZ, Backquote, Minus, Equal, Backslash, Backspace, Tab, Delete, Escape, ArrowDown, End, Enter, Home, Insert, PageDown, PageUp, ArrowRight, ArrowUp, etc.

Following modification shortcuts are also supported: Shift, Control, Alt, Meta.

Holding down Shift will type the text that corresponds to the key in the upper case.

If key is a single character, it is case-sensitive, so the values a and A will generate different respective texts.

Shortcuts such as key: "Control+f" or key: "Control+Shift+f" are supported as well. When specified with the modifier, modifier is pressed and being held while the subsequent key is being pressed.

import { screenReader } from "@guidepup/guidepup";

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // Open a find text modal.
  await screenReader.press("Control+f");

  // Stop the screen reader.
  await screenReader.stop();
})();

Parameters:

• key string Name of the key to press or a character to generate, such as ArrowLeft or a.
• Optional: options KeyboardOptions Additional options.

Returns: Promise<void>

screenReader.previous([options])

Move the screen reader cursor to the previous location.

import { screenReader } from "@guidepup/guidepup";

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // Move to the previous item.
  await screenReader.previous();

  // Stop the screen reader.
  await screenReader.stop();
})();

Parameters:

• Optional: options CommandOptions Additional options.

Returns: Promise<void>

screenReader.spokenPhraseLog()

Get the log of all spoken phrases for this screen reader instance.

import { screenReader } from "@guidepup/guidepup";

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // Move through several items.
  for (let i = 0; i < 10; i++) {
    await screenReader.next();
  }

  // Get the phrase spoken by the screen reader from moving through the items above.
  const spokenPhraseLog = await screenReader.spokenPhraseLog();
  console.log(spokenPhraseLog);

  // Stop the screen reader.
  await screenReader.stop();
})();

Returns: Promise<Array<string>> The spoken phrase log.

screenReader.start([options])

Turn the screen reader on.

import { screenReader } from "@guidepup/guidepup";

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // ... perform some commands.

  // Stop the screen reader.
  await screenReader.stop();
})();

Parameters:

• Optional: options CommandOptions Additional options.

Returns: Promise<void>

screenReader.stop([options])

Turn the screen reader off.

import { screenReader } from "@guidepup/guidepup";

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // ... perform some commands.

  // Stop the screen reader.
  await screenReader.stop();
})();

Parameters:

• Optional: options CommandOptions Additional options.

Returns: Promise<void>

screenReader.stopInteracting([options])

Stop interacting with the current item.

Provided as a compatibility layer for VoiceOver; NVDA does not require users to perform an additional command to stop interacting with the item in the NVDA cursor.

import { screenReader } from "@guidepup/guidepup";

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // Interact with the item - does nothing on NVDA.
  await screenReader.interact();

  // ... perform some commands.

  // Stop interacting with the item - does nothing on NVDA.
  await screenReader.stopInteracting();

  // Stop the screen reader.
  await screenReader.stop();
})();

Parameters:

• Optional: options CommandOptions Additional options.

Returns: Promise<void>

screenReader.type(text[, options])

Type text into the focused item.

To press a special key, like Control or ArrowDown, use screenReader.press(key[, options]).

import { screenReader } from "@guidepup/guidepup";

(async () => {
  // Start the screen reader.
  await screenReader.start();

  // Type a username and key Enter.
  await screenReader.type("my-username");
  await screenReader.press("Enter");

  // Stop the screen reader.
  await screenReader.stop();
})();

Parameters:

• text string Text to type into the focused item.
• Optional: options CommandOptions Additional options.

Returns: Promise<void>