Skip to main content
While primarily designed as a screen reader for blind users, NVDA includes vision enhancement features to provide visual feedback and assist users with low vision or sighted trainers and developers.

​
Overview

NVDA’s vision enhancement system uses the “vision framework” to augment visual information presented on screen. These features can help:
  • Low vision users: Highlight focus and navigation for easier tracking
  • Trainers and educators: Visualize where NVDA’s focus is during demonstrations
  • Developers: Debug and verify focus management and accessibility
  • Sighted assistants: Help troubleshoot NVDA behavior for blind users
Vision enhancements are completely optional. They do not affect NVDA’s core screen reading functionality and can be enabled or disabled independently.

​
NVDA Highlighter

The built-in NVDA Highlighter draws visual rectangles around elements that NVDA is tracking.

​
What It Highlights

Focus Tracking

Highlights the currently focused object with a solid border

Navigator Object

Shows the current object navigator position with a dashed border

Browse Mode Cursor

Highlights the current position in browse mode documents

Braille Region

Shows what’s currently displayed on braille display (optional)

​
Highlight Styles

The highlighter uses different visual styles for different contexts:
  • Color: Blue (RGB: 03, 36, FF)
  • Style: Solid line
  • Width: 5 pixels
  • Margin: 5 pixels around object
  • Purpose: Shows keyboard/application focus
  • Color: Pink (RGB: FF, 02, 66)
  • Style: Solid line
  • Width: 5 pixels
  • Margin: 5 pixels around object
  • Purpose: Shows virtual cursor position in documents
  • Color: Yellow (RGB: FF, DE, 03)
  • Style: Solid line
  • Width: 2 pixels
  • Margin: 2 pixels around text
  • Purpose: Shows what’s on braille display

​
Enabling NVDA Highlighter

To enable visual highlighting:
  1. Open NVDA menu → Preferences → Settings
  2. Select “Vision” category
  3. Click “NVDA Highlighter” in the provider list
  4. Check “Enable”
  5. Configure highlight settings (optional)
  6. Click OK

​
Highlighter Settings

  • Enable/Disable: Toggle highlighter on/off
  • Highlight Focus: Show focused element (default: on)
  • Highlight Navigator Object: Show object navigation (default: on)
  • Highlight Browse Mode: Show virtual cursor (default: on)
  • Highlight Braille: Show braille display region (default: off)
You can quickly enable/disable vision enhancement providers from the NVDA menu → Tools → Vision without opening full settings.

​
Technical Implementation

​
Vision Framework Architecture

NVDA’s vision enhancement system consists of:
  1. Vision Handler: Central coordinator managing providers
  2. Vision Enhancement Providers: Individual modules providing visual feedback
  3. Extension Points: Event-based hooks for providers to react to
  4. Settings System: Auto-generated or custom settings panels

​
How NVDA Highlighter Works

The highlighter is implemented in source/visionEnhancementProviders/NVDAHighlighter.py:
  • Window Creation: Creates a transparent, topmost window spanning all displays
  • GDI+ Graphics: Uses Windows GDI+ for hardware-accelerated drawing
  • Layered Windows: Leverages WS_EX_LAYERED for transparency
  • Color Keying: Makes black pixels transparent
  • Double Buffering: Maintains previous frame to calculate dirty regions
  • Efficient Updates: Only redraws changed areas for performance

​
Window Characteristics

windowStyle = WS_POPUP | WS_DISABLED
extendedWindowStyle = (
    WS_EX_TOPMOST        # Stay on top
    | WS_EX_LAYERED       # Support transparency
    | WS_EX_NOACTIVATE    # Don't capture focus
    | WS_EX_TRANSPARENT   # Click-through
    | WS_EX_TOOLWINDOW    # Hide from taskbar
)
These window flags ensure:
  • Highlighter stays visible over all applications
  • Doesn’t interfere with mouse or keyboard input
  • Invisible to accessibility APIs (won’t confuse screen readers)
  • Doesn’t show in Alt+Tab or taskbar

​
Context Tracking

The highlighter subscribes to vision framework events:
  • Focus Events: When application focus changes
  • Navigator Events: When object navigator moves
  • Caret Events: When browse mode cursor moves
  • Braille Events: When braille display updates
  • Display Changes: When screen resolution or display count changes

​
Performance Optimizations

  • Dirty Region Tracking: Only redraws changed areas
  • Hardware Acceleration: Uses GDI+ accelerated rendering
  • Event Coalescing: Batches rapid updates
  • Lazy Redraw: Delays redraws until after event processing
  • Smart Invalidation: Calculates minimal redraw regions

​
Multi-Monitor Support

The highlighter automatically:
  • Spans all connected displays
  • Updates window size when displays are added/removed
  • Calculates total desktop bounds including negative coordinates
  • Handles DPI scaling per monitor
  • Adjusts for taskbar position and size
The highlighter removes one pixel from the bottom of the screen to prevent Windows from disabling desktop shortcut hotkeys (a Windows “feature” when windows are fullscreen).

​
Creating Custom Vision Providers

Developers can create custom vision enhancement providers.

​
Provider Requirements

A vision enhancement provider must:
  1. Inherit from vision.providerBase.VisionEnhancementProvider
  2. Implement required methods and properties
  3. Be placed in visionEnhancementProviders/ directory
  4. Export a VisionEnhancementProvider class

​
Basic Provider Structure

from vision.providerBase import VisionEnhancementProvider
from vision.visionHandlerExtensionPoints import EventExtensionPoints

class MyVisionProvider(VisionEnhancementProvider):
    name = "myProvider"
    description = _("My Custom Vision Provider")
    
    def __init__(self):
        super().__init__()
        # Initialize provider
    
    def terminate(self):
        # Cleanup resources
        super().terminate()
    
    def registerEventExtensionPoints(self, extensionPoints: EventExtensionPoints):
        # Subscribe to events
        extensionPoints.post_focusChange.register(self.onFocusChange)
    
    def onFocusChange(self, obj):
        # React to focus changes
        pass

# Export the provider
VisionEnhancementProvider = MyVisionProvider

​
Provider Settings

Providers can define settings using driver setting objects:
from autoSettingsUtils.driverSetting import BooleanDriverSetting

class MyProvider(VisionEnhancementProvider):
    mySettingId = "myFeature"
    
    @classmethod
    def getSettings(cls):
        return [
            BooleanDriverSetting(
                cls.mySettingId,
                _("Enable My Feature"),
                defaultVal=True
            )
        ]
NVDA automatically generates a settings panel from these definitions.
For complex UIs, implement a custom panel:
from gui.settingsDialogs import SettingsPanel

class MyProviderSettingsPanel(SettingsPanel):
    # Custom wx.Panel implementation
    pass

class MyProvider(VisionEnhancementProvider):
    @classmethod
    def getSettingsPanelClass(cls):
        return MyProviderSettingsPanel

​
Available Extension Points

Providers can react to:
  • post_focusChange: Application focus changed
  • post_foregroundChange: Foreground window changed
  • post_objectUpdate: Object property changed
  • post_caretMove: Text caret moved
  • post_reviewMove: Review cursor moved
  • post_browseMode: Browse mode cursor moved
  • post_brailleRegionUpdate: Braille display changed

​
Example: Auto GUI Provider

The example provider in _exampleProvider_autoGui.py demonstrates:
  • Using auto-generated settings
  • Subscribing to events
  • Boolean, numeric, and string settings
  • Settings validation
  • Proper initialization and termination
See source/visionEnhancementProviders/readme.md for complete provider development documentation.

​
Vision Enhancement Use Cases

​
Training and Demonstrations

Trainers can:
  • Show where focus is during instruction
  • Demonstrate navigation techniques visually
  • Verify focus is where expected
  • Troubleshoot focus issues collaboratively
Presenters can:
  • Help sighted audiences follow NVDA navigation
  • Show accessibility concepts visually
  • Demonstrate focus management techniques
  • Create engaging demonstrations

​
Development and Testing

Developers can:
  • Verify focus order and management
  • Debug focus trapping issues
  • Test keyboard navigation flows
  • Validate ARIA implementations
  • Ensure focus visibility
Add-on developers can:
  • Test object navigation in their code
  • Verify browse mode integration
  • Debug focus handling
  • Validate custom navigation commands

​
Low Vision Support

Low vision users can:
  • More easily track focus movement
  • Identify small focused elements
  • Follow navigation in complex interfaces
  • Combine with screen magnification

​
Disabling Vision Enhancements

To disable vision enhancements:
  1. Quick Disable: NVDA menu → Tools → Vision → Uncheck provider
  2. Settings: NVDA menu → Preferences → Settings → Vision → Uncheck “Enable”
  3. Remove Entirely: Delete provider from providers list
Disabling vision enhancements has no effect on NVDA’s core screen reading functionality.

​
Performance Considerations

Vision enhancements use system resources:
  • CPU: Minimal (graphics hardware accelerated)
  • GPU: Light rendering of overlay graphics
  • Memory: Small window and graphics buffers
  • Display: Additional window layer
On modern systems, performance impact is negligible. On older or resource-constrained systems, disabling vision enhancements may improve performance slightly.

​
Future Vision Enhancements

Potential future providers could include:
  • Screen Magnification: Built-in magnification support
  • Color Overlays: Reduce glare or improve contrast
  • Focus Animation: Animated transitions between focus changes
  • Heat Maps: Show frequently visited screen areas
  • Gesture Visualization: Show touch gestures for training
  • Braille Preview: On-screen braille simulation
Third-party developers can create custom providers as add-ons.