NVDA
Implements: ScreenReader
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.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
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();
})();
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.
nvda.default()
Detect whether NVDA is the default screen reader for the current OS:
true
for Windowsfalse
for MacOSfalse
for Linux
import { nvda } from "@guidepup/guidepup";
(async () => {
const isNVDADefaultScreenReader = await nvda.default();
console.log(isNVDADefaultScreenReader);
})();
nvda.detect()
Detect whether NVDA is supported for the current OS:
true
for Windowsfalse
for MacOSfalse
for Linux
import { nvda } from "@guidepup/guidepup";
(async () => {
const isNVDADefaultScreenReader = await nvda.detect();
console.log(isNVDADefaultScreenReader);
})();
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();
})();
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();
})();
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.
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 asArrowLeft
ora
.
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();
})();
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();
})();
nvda.stop()
Turn NVDA off.
import { nvda } from "@guidepup/guidepup";
(async () => {
// Start NVDA.
await nvda.start();
// ... perform some commands.
// Stop NVDA.
await nvda.stop();
})();
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();
})();
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.