NVDA

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

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.act()

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

Equivalent of executing Enter or Spacebar (depending on the item).

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();
})();

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";

(async () => {
  const isNVDADefaultScreenReader = await nvda.default();

  console.log(isNVDADefaultScreenReader);
})();

Returns: <Promise<boolean>>

nvda.detect()

Detect whether NVDA is supported for the current OS:

true for Windows
false for MacOS
false for Linux

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

(async () => {
  const isNVDADefaultScreenReader = await nvda.detect();

  console.log(isNVDADefaultScreenReader);
})();

Returns: <Promise<boolean>>

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.

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.

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()

Move the NVDA cursor to the next location.

Equivalent of executing VO-Right 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();
})();

Returns: <Promise<void>>

nvda.perform(command)

Perform a NVDA command.

The command can be a WindowsKeyCodeCommand or WindowsKeystrokeCommand.

import { nvda, NVDAKeyCodeCommands } 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.

Returns: <Promise<void>>

nvda.press(key)

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.

Returns: <Promise<void>>

nvda.previous()

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();
})();

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()

Turn NVDA on.

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

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

  // ... perform some commands.

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

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

Type text into the focused item.

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

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.

Returns: <Promise<void>>

nvda.keyboardCommands​

nvda.act()​

nvda.click([options])​

nvda.default()​

nvda.detect()​

nvda.interact()​

nvda.itemText()​

nvda.itemTextLog()​

nvda.lastSpokenPhrase()​

nvda.next()​

nvda.perform(command)​

nvda.press(key)​

nvda.previous()​

nvda.spokenPhraseLog()​

nvda.start()​

nvda.stop()​

nvda.stopInteracting()​

nvda.type(text)​

nvda.keyboardCommands

nvda.act()

nvda.click([options])

nvda.default()

nvda.detect()

nvda.interact()

nvda.itemText()

nvda.itemTextLog()

nvda.lastSpokenPhrase()

nvda.next()

nvda.perform(command)

nvda.press(key)

nvda.previous()

nvda.spokenPhraseLog()

nvda.start()

nvda.stop()

nvda.stopInteracting()

nvda.type(text)