> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nvaccess/nvda/llms.txt
> Use this file to discover all available pages before exploring further.

# Vision Enhancements

> Visual highlighting and vision enhancement features in NVDA

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

<Note>
  Vision enhancements are completely optional. They do not affect NVDA's core screen reading functionality and can be enabled or disabled independently.
</Note>

## NVDA Highlighter

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

### What It Highlights

<CardGroup cols={2}>
  <Card title="Focus Tracking" icon="crosshairs">
    Highlights the currently focused object with a solid border
  </Card>

  <Card title="Navigator Object" icon="compass">
    Shows the current object navigator position with a dashed border
  </Card>

  <Card title="Browse Mode Cursor" icon="i-cursor">
    Highlights the current position in browse mode documents
  </Card>

  <Card title="Braille Region" icon="braille">
    Shows what's currently displayed on braille display (optional)
  </Card>
</CardGroup>

### Highlight Styles

The highlighter uses different visual styles for different contexts:

<Accordion title="Focus Highlighting">
  * **Color**: Blue (RGB: 03, 36, FF)
  * **Style**: Solid line
  * **Width**: 5 pixels
  * **Margin**: 5 pixels around object
  * **Purpose**: Shows keyboard/application focus
</Accordion>

<Accordion title="Navigator Object">
  * **Color**: Blue (RGB: 03, 36, FF)
  * **Style**: Dashed line
  * **Width**: 5 pixels
  * **Margin**: 5 pixels around object
  * **Purpose**: Shows NVDA's object navigation position
</Accordion>

<Accordion title="Browse Mode Cursor">
  * **Color**: Pink (RGB: FF, 02, 66)
  * **Style**: Solid line
  * **Width**: 5 pixels
  * **Margin**: 5 pixels around object
  * **Purpose**: Shows virtual cursor position in documents
</Accordion>

<Accordion title="Braille Display Area">
  * **Color**: Yellow (RGB: FF, DE, 03)
  * **Style**: Solid line
  * **Width**: 2 pixels
  * **Margin**: 2 pixels around text
  * **Purpose**: Shows what's on braille display
</Accordion>

### 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

<Accordion title="Available 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)
</Accordion>

<Note type="info">
  You can quickly enable/disable vision enhancement providers from the NVDA menu → Tools → Vision without opening full settings.
</Note>

## 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`:

<Accordion title="Rendering System">
  * **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
</Accordion>

### Window Characteristics

```python theme={null}
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

<Accordion title="Rendering 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
</Accordion>

### 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

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

## 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

```python theme={null}
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

<Accordion title="Automatic Settings GUI">
  Providers can define settings using driver setting objects:

  ```python theme={null}
  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.
</Accordion>

<Accordion title="Custom Settings Panel">
  For complex UIs, implement a custom panel:

  ```python theme={null}
  from gui.settingsDialogs import SettingsPanel

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

  class MyProvider(VisionEnhancementProvider):
      @classmethod
      def getSettingsPanelClass(cls):
          return MyProviderSettingsPanel
  ```
</Accordion>

### 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

<Note type="info">
  See `source/visionEnhancementProviders/readme.md` for complete provider development documentation.
</Note>

## Vision Enhancement Use Cases

### Training and Demonstrations

<Accordion title="Training Blind Users">
  Trainers can:

  * Show where focus is during instruction
  * Demonstrate navigation techniques visually
  * Verify focus is where expected
  * Troubleshoot focus issues collaboratively
</Accordion>

<Accordion title="Presenting NVDA">
  Presenters can:

  * Help sighted audiences follow NVDA navigation
  * Show accessibility concepts visually
  * Demonstrate focus management techniques
  * Create engaging demonstrations
</Accordion>

### Development and Testing

<Accordion title="Accessibility Development">
  Developers can:

  * Verify focus order and management
  * Debug focus trapping issues
  * Test keyboard navigation flows
  * Validate ARIA implementations
  * Ensure focus visibility
</Accordion>

<Accordion title="NVDA Add-on Development">
  Add-on developers can:

  * Test object navigation in their code
  * Verify browse mode integration
  * Debug focus handling
  * Validate custom navigation commands
</Accordion>

### Low Vision Support

<Accordion title="Focus Tracking">
  Low vision users can:

  * More easily track focus movement
  * Identify small focused elements
  * Follow navigation in complex interfaces
  * Combine with screen magnification
</Accordion>

## 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

<Note>
  Disabling vision enhancements has no effect on NVDA's core screen reading functionality.
</Note>

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

## Related Topics

* [Speech Synthesis](/features/speech-synthesis) - Audio output configuration
* [Braille Displays](/features/braille-displays) - Tactile output devices
* [Browse Mode](/features/browse-mode) - Document navigation
* [Add-ons](/features/add-ons) - Extend NVDA functionality