API Reference

Core Modules

appModuleHandler

Handles application-specific modules.

class

Base class for app modulesProperties:

processID (int): Process ID
appName (str): Application name
processHandle (int): Process handle
sleepMode (bool): Whether NVDA sleeps in this app
productName (str): Product name from executable
productVersion (str): Product version
is64BitProcess (bool): Whether process is 64-bit
isWindowsStoreApp (bool): Whether this is a Store app

Methods:

chooseNVDAObjectOverlayClasses(obj, clsList): Choose overlay classes
event_appModule_gainFocus(): Called when app gains focus
event_appModule_loseFocus(): Called when app loses focus

function

Get app module for a process

mod = appModuleHandler.getAppModuleFromProcessID(processID)

function

appModuleHandler.registerExecutableWithAppModule(
    "myapp", 
    "myAppModule"
)

globalPluginHandler

Handles global plugins.

class

Base class for global pluginsMethods:

terminate(): Called when plugin is unloaded
chooseNVDAObjectOverlayClasses(obj, clsList): Choose overlay classes

set

Set of currently running global plugins

api

Core API functions for accessing NVDA state.

import api

# Get focused object
obj = api.getFocusObject()

# Get focus ancestors (parent chain)
ancestors = api.getFocusAncestors()

# Set focus
api.setFocusObject(obj)

# Get foreground object
fg = api.getForegroundObject()

import api

# Get navigator object
nav = api.getNavigatorObject()

# Set navigator object
api.setNavigatorObject(obj)

# Get desktop object
desktop = api.getDesktopObject()

import api

# Get object under mouse
obj = api.getMouseObject()

# Set mouse to object
api.setMouseObject(obj)

import api

# Get review position
info = api.getReviewPosition()

# Set review position  
api.setReviewPosition(textInfo)

ui

User interface feedback.

import ui

# Simple message
ui.message("Hello")

# Browse mode message (interruptible)
ui.browseableMessage("Long text...", title="Title")

# Report status
ui.reportTextCopied(text)
ui.reportTextNotCopied()

import ui

# Message with speech priority
from speech.priorities import Spri
ui.message("Important", speechPriority=Spri.NOW)

# Cancel speech before message
ui.message("Text", cancelSpeech=True)

controlTypes

Control roles and states.

import controlTypes

# Common roles
controlTypes.Role.BUTTON
controlTypes.Role.EDITABLETEXT
controlTypes.Role.CHECKBOX
controlTypes.Role.RADIOBUTTON
controlTypes.Role.COMBOBOX
controlTypes.Role.LIST
controlTypes.Role.LISTITEM
controlTypes.Role.LINK
controlTypes.Role.TREEVIEW
controlTypes.Role.TREEVIEWITEM
controlTypes.Role.TABLE
controlTypes.Role.TABLECELL
controlTypes.Role.MENU
controlTypes.Role.MENUITEM
controlTypes.Role.DIALOG
controlTypes.Role.WINDOW

import controlTypes

# Common states
controlTypes.State.FOCUSED
controlTypes.State.FOCUSABLE
controlTypes.State.SELECTED
controlTypes.State.SELECTABLE
controlTypes.State.CHECKED
controlTypes.State.COLLAPSED
controlTypes.State.EXPANDED
controlTypes.State.READONLY
controlTypes.State.UNAVAILABLE
controlTypes.State.INVISIBLE
controlTypes.State.OFFSCREEN
controlTypes.State.BUSY
controlTypes.State.PRESSED

scriptHandler

Script decorator and utilities.

decorator

Decorator for defining scripts

from scriptHandler import script

@script(
    description="My script",
    category="My Category",
    gesture="kb:NVDA+shift+m"
)
def script_myScript(self, gesture):
    pass

Parameters:

description (str): User-visible description
category (str): Category for Input Gestures
gesture (str): Single gesture string
gestures (list[str]): Multiple gestures
canPropagate (bool): Allow on ancestors
bypassInputHelp (bool): Run in input help
allowInSleepMode (bool): Run in sleep mode
resumeSayAllMode: Resume say all mode
speakOnDemand (bool): Speak on-demand

speech

Speech output.

import speech

# Speak text
speech.speak(["Hello world"])

# Cancel speech
speech.cancelSpeech()

# Spell text
speech.speakSpelling("word")

# Speak character
speech.speakCharacter("a")

import speech
from speech import priorities

# Build sequence
sequence = [
    "Text",
    speech.IndexCommand(1),
    "More text",
    speech.PitchCommand(offset=50)
]

speech.speak(sequence)

# With priority
speech.speak(
    sequence,
    priority=priorities.Spri.NOW
)

import speech

# Get current mode
mode = speech.getState().speechMode

# Set mode
speech.setSpeechMode(speech.SpeechMode.talk)
speech.setSpeechMode(speech.SpeechMode.onDemand)
speech.setSpeechMode(speech.SpeechMode.off)

tones

Audio feedback.

tones.py

import tones

# Beep (frequency, duration in ms)
tones.beep(550, 50)

# Error beep
tones.beep(220, 150)

# Success beep
tones.beep(880, 100)

config

Configuration management.

import config

# Access settings
rate = config.conf["speech"]["rate"]
verbosity = config.conf["speech"]["symbolLevel"]

# Check if value exists
if "myAddon" in config.conf:
    enabled = config.conf["myAddon"]["enabled"]

import config

# Define spec
config.conf.spec["myAddon"] = {
    "enabled": "boolean(default=True)",
    "level": "integer(default=1, min=0, max=3)",
    "name": "string(default=\"\")"
}

# Write values
config.conf["myAddon"]["enabled"] = False
config.conf["myAddon"]["level"] = 2

# Save
config.conf.save()

import config

class MyTrigger(config.ProfileTrigger):
    def __init__(self):
        self.spec = "addon:myAddon"

trigger = MyTrigger()
trigger.enter()
trigger.exit()

textInfos

Text access and manipulation.

import textInfos

# Get text
info = obj.makeTextInfo(textInfos.POSITION_CARET)
text = info.text

# Move
info.move(textInfos.UNIT_CHARACTER, 1)
info.move(textInfos.UNIT_WORD, -1)
info.move(textInfos.UNIT_LINE, 1)

# Expand
info.expand(textInfos.UNIT_LINE)
info.expand(textInfos.UNIT_PARAGRAPH)

import textInfos

textInfos.UNIT_CHARACTER
textInfos.UNIT_WORD  
textInfos.UNIT_LINE
textInfos.UNIT_SENTENCE
textInfos.UNIT_PARAGRAPH
textInfos.UNIT_PAGE
textInfos.UNIT_STORY  # Entire document

import textInfos

textInfos.POSITION_FIRST
textInfos.POSITION_LAST
textInfos.POSITION_CARET
textInfos.POSITION_SELECTION
textInfos.POSITION_ALL

queueHandler

Thread-safe queue operations.

queueHandler.py

import queueHandler
import ui

# Queue function on main thread
def myFunction(arg1, arg2):
    ui.message(f"{arg1}, {arg2}")

queueHandler.queueFunction(
    queueHandler.eventQueue,
    myFunction,
    "hello",
    "world"
)

# Register generator (for long operations)
def myGenerator():
    for i in range(10):
        yield lambda: ui.message(str(i))

queueHandler.registerGeneratorObject(myGenerator())

winUser

Windows API functions.

winUser.py

import winUser

# Window functions
hwnd = winUser.getForegroundWindow()
winUser.setForegroundWindow(hwnd)
winUser.isWindow(hwnd)

# Window text
text = winUser.getWindowText(hwnd)
winUser.setWindowText(hwnd, "New title")

# Window class
className = winUser.getClassName(hwnd)

# Process/thread
threadId, processId = winUser.getWindowThreadProcessID(hwnd)

# Send messages
winUser.sendMessage(hwnd, message, wParam, lParam)

# Get control ID
controlId = winUser.getControlID(hwnd)

gui

GUI dialogs and utilities.

import gui
import wx

# Message dialog
gui.messageBox(
    "Message text",
    "Title",
    wx.OK | wx.ICON_INFORMATION
)

# Input dialog
result = gui.textEntryDialog(
    "Enter text:",
    "Title",
    defaultValue=""
)

import gui
import wx

def myGuiFunction():
    # GUI code here
    pass

# Run on main thread
wx.CallAfter(myGuiFunction)

# Run and wait for result
if gui.isInMainThread():
    result = myGuiFunction()
else:
    result = gui.runInMainThread(myGuiFunction)

NVDAObjects Classes

Base Classes

from NVDAObjects.IAccessible import IAccessible

class MyControl(IAccessible):
    """MSAA/IAccessible object."""
    pass

from NVDAObjects.UIA import UIA

class MyControl(UIA):
    """UI Automation object."""
    pass

from NVDAObjects.window import Window

class MyControl(Window):
    """Basic window object."""
    pass

from NVDAObjects.JAB import JAB  

class MyControl(JAB):
    """Java Access Bridge object."""
    pass

Behaviors

behaviors.py

from NVDAObjects.behaviors import (
    EditableText,      # Editable text with caret
    Dialog,            # Dialog handling
    ProgressBar,       # Progress announcements
    RowWithFakeNavigation,  # Table row navigation
    KeyboardHandlerBasedTypedCharSupport,  # Typed chars
)

Events

Common NVDA Object events:

event

Object gained keyboard focus

event

Object lost keyboard focus

event

Focus moved inside container (object is ancestor)

event

Object became foreground window

event

Object’s name changed

event

Object’s value changed

event

Object’s state changed

event

Selection changed in container

event

Caret moved within object

event

Object’s screen location changed

Gesture Identifiers

Keyboard

# Standard
"kb:NVDA+shift+v"
"kb:control+alt+delete"
"kb:f1"

# Laptop layout
"kb(laptop):NVDA+t"

# Named keys
"kb:escape"
"kb:enter" 
"kb:space"
"kb:tab"
"kb:backspace"
"kb:delete"
"kb:home"
"kb:end"
"kb:pageUp"
"kb:pageDown"
"kb:upArrow"
"kb:downArrow"
"kb:leftArrow"
"kb:rightArrow"
"kb:numpad0" through "kb:numpad9"
"kb:numpadPlus"
"kb:numpadMinus"
"kb:numpadMultiply"
"kb:numpadDivide"
"kb:numpadEnter"

Braille

# Freedom Scientific
"br(freedomScientific):leftWizWheelUp"
"br(freedomScientific):rightWizWheelDown"

# Alva
"br(alva):t1"
"br(alva):etouch1"

# Generic
"br:space+dot1"

Touch

"ts:tap"
"ts:2finger_tap"
"ts:3finger_flickRight"
"ts:4finger_flickUp"

Logging

logging.py

from logHandler import log

# Log levels
log.debug("Debug info")
log.info("Information")
log.warning("Warning") 
log.error("Error")
log.exception("Exception with traceback")

# With exc_info for stack traces
log.error("Error occurred", exc_info=True)

# Stack info without exception
log.warning("Check this", stack_info=True)

Utility Modules

locationHelper

locationHelper.py

import locationHelper

# Rectangle operations
rect1 = locationHelper.RectLTWH(0, 0, 100, 100)
rect2 = locationHelper.RectLTWH(50, 50, 100, 100)

# Check if rectangles intersect
if rect1.intersection(rect2):
    pass

# Get center point
center = rect1.center

textUtils

textUtils.py

import textUtils

# Unicode normalization
normalized = textUtils.normalizeText(text)

# Word boundaries
words = textUtils.WideStringOffsetConverter(text)

Best Practices

Always import from the original module (check source code)
Don’t rely on transitive imports
Private symbols (starting with _) may change without notice
Package pip dependencies with your add-on

Use ui.message() for user feedback
Use log.debug() for development
Use queueHandler for thread safety
Cache expensive operations
Handle exceptions gracefully

Version Compatibility

Check NVDA version:

version.py

import versionInfo

# Version tuple: (year, major, minor)
if versionInfo.version_year >= 2024:
    # Use newer API
    pass

# Version string
version = versionInfo.version  # e.g., "2024.1"

Getting Started

Contributing

Architecture

Add-on Development

Advanced Topics

API Reference

Core Modules

appModuleHandler

globalPluginHandler

api

ui

controlTypes

scriptHandler

speech

tones

config

textInfos

queueHandler

winUser

gui

NVDAObjects Classes

Base Classes

Behaviors

Events

Gesture Identifiers

Keyboard

Braille

Touch

Logging

Utility Modules

locationHelper

textUtils

Best Practices

Version Compatibility

​Core Modules

​appModuleHandler

​globalPluginHandler

​api

​ui

​controlTypes

​scriptHandler

​speech

​tones

​config

​textInfos

​queueHandler

​winUser

​gui

​NVDAObjects Classes

​Base Classes

​Behaviors

​Events

​Gesture Identifiers

​Keyboard

​Braille

​Touch

​Logging

​Utility Modules

​locationHelper

​textUtils

​Best Practices

​Version Compatibility

​Related Resources

Core Modules

appModuleHandler

globalPluginHandler

api

ui

controlTypes

scriptHandler

speech

tones

config

textInfos

queueHandler

winUser

gui

NVDAObjects Classes

Base Classes

Behaviors

Events

Gesture Identifiers

Keyboard

Braille

Touch

Logging

Utility Modules

locationHelper

textUtils

Best Practices

Version Compatibility

Related Resources