NVDA

Implements: IScreenReader

A NVDA instance can be used to launch and control NVDA.

Here's a typical example using a NVDA instance:

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Stop NVDA.
  await nvda.stop();
})();

Contents:

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

nvda.keyboardCommands

Getter for all NVDA keyboard commands.

Use with the NVDA perform command to invoke a keyboard action:

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

(async () => {
  // Start NVDA.
  await nvda.start();

  // Move to the next item.
  await nvda.perform(nvda.keyboardCommands.moveToNext);

  // Stop NVDA.
  await nvda.stop();
})();

Returns: NVDAKeyCodeCommands

nvda.name

Getter for the screen reader name "NVDA".

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

console.log(nvda.name); // "NVDA"

Returns: string

nvda.version

Getter for the screen reader version.

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

console.log(nvda.version);

Returns: string

nvda.act([options])

Perform the default action for the item in the NVDA cursor.

Equivalent of executing Enter.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

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

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

• Optional: options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

nvda.clearItemTextLog()

Clear the log of all spoken phrases for this NVDA instance.

For NVDA this is the same as clearSpokenPhraseLog.

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

(async () => {
  // Start NVDA.
  await nvda.start();

  // ... perform some commands.

  // Clear the spoken phrase log.
  await nvda.clearItemTextLog();

  // Stop NVDA.
  await nvda.stop();
})();

Returns: Promise<void>

nvda.clearSpokenPhraseLog()

Clear the log of all spoken phrases for this NVDA instance.

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

(async () => {
  // Start NVDA.
  await nvda.start();

  // ... perform some commands.

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

  // Stop NVDA.
  await nvda.stop();
})();

Returns: Promise<void>

nvda.click([options])

Click the mouse.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

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

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

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

-*Optional:** options ClickOptions Click options.

Returns: Promise<void>

nvda.default()

Detect whether NVDA is the default screen reader for the current OS:

• true for Windows
• false for macOS
• false for Linux

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

const isNVDADefaultScreenReader = nvda.default();

console.log(isNVDADefaultScreenReader);

Returns: boolean

nvda.detect()

Detect whether NVDA is supported on the current machine. NVDA must be installed for this check to return true.

• true for Windows when NVDA is installed
• false for macOS
• false for Linux

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

const isNVDASupportedScreenReader = nvda.detect();

console.log(isNVDASupportedScreenReader);

Returns: boolean

nvda.getSetting(key)

Returns the value of a setting for this NVDA instance.

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

(async () => {
  // Start NVDA.
  await nvda.start();

  // Log the value for the 'virtualBuffers.autoSayAllOnPageLoad' setting.
  console.log(nvda.getSetting("virtualBuffers.autoSayAllOnPageLoad"));

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

• key string The setting name.

Returns: unknown The setting value.

nvda.getSettings()

Returns all the current settings for this NVDA instance.

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

(async () => {
  // Start NVDA.
  await nvda.start();

  // Log current settings.
  console.log(nvda.getSettings());

  // Stop NVDA.
  await nvda.stop();
})();

Returns: Record<string, unknown> Current settings values.

nvda.interact()

No-op to provide same API across screen readers.

NVDA does not require users to perform an additional command to interact with the item in the NVDA cursor.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

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

  // Stop NVDA.
  await nvda.stop();
})();

Returns: Promise<void>

nvda.itemText()

Get the text of the item in the NVDA cursor.

For NVDA this is the same as lastSpokenPhrase.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

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

  // Stop NVDA.
  await nvda.stop();
})();

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

nvda.itemTextLog()

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

For NVDA this is the same as spokenPhraseLog.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

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

  // Stop NVDA.
  await nvda.stop();
})();

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

nvda.lastSpokenPhrase()

Get the last spoken phrase.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

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

  // Stop NVDA.
  await nvda.stop();
})();

Returns: Promise<string> The last spoken phrase.

nvda.next([options])

Move the NVDA cursor to the next location.

Equivalent of executing Down Arrow.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

-*Optional:** options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

nvda.perform(command[, options])

Perform a NVDA command.

The command can be a WindowsKeyCodeCommand or WindowsKeystrokeCommand.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Keyboard commands available on the NVDA instance.
  await nvda.perform(nvda.keyboardCommands.performDefaultActionForItem);

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

• command WindowsKeyCodeCommand | WindowsKeystrokeCommand NVDA keyboard command. -*Optional:** options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

nvda.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.

See WindowsKeyCodes for the full range of available keys.

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

See WindowsModifiers for the full range of available modifiers.

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 { nvda } from "@guidepup/guidepup";

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

• key string Name of the key to press or a character to generate, such as ArrowLeft or a. -*Optional:** options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

nvda.previous([options])

Move the NVDA cursor to the previous location.

Equivalent of executing Up Arrow.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

-*Optional:** options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>

nvda.spokenPhraseLog()

Get the log of all spoken phrases for this NVDA instance.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

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

  // Stop NVDA.
  await nvda.stop();
})();

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

nvda.start([options])

Turn NVDA on.

By default, capture is set to "initial": it captures the first page of output, but not subsequent content. Set capture to true for full capture or false to disable capture.

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

(async () => {
  // Start NVDA.
  await nvda.start();

  // ... perform some commands.

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

-*Optional:** options Pick<StartOptions, "capture" | "settings"> Capture options.

Returns: Promise<void>

nvda.stop()

Turn NVDA off.

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

(async () => {
  // Start NVDA.
  await nvda.start();

  // ... perform some commands.

  // Stop NVDA.
  await nvda.stop();
})();

Returns: Promise<void>

nvda.stopInteracting()

No-op to provide same API across screen readers.

NVDA does not require users to perform an additional command to interact with the item in the NVDA cursor.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // ... perform some commands.

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

  // Stop NVDA.
  await nvda.stop();
})();

Returns: Promise<void>

nvda.type(text[, options])

Type text into the focused item.

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

Each character is typed separately. As a result, lastSpokenPhrase() returns the phrase for the final character; use spokenPhraseLog() to access output for the complete string.

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

(async () => {
  // Start NVDA.
  await nvda.start();

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

  // Stop NVDA.
  await nvda.stop();
})();

Parameters:

• text string Text to type into the focused item. -*Optional:** options Pick<CommandOptions, "capture"> Capture options.

Returns: Promise<void>