Focus Manager

Location: system/focus.js
Type: GUI Subsystem
Status: ✅ Fully Implemented

Overview

The Focus Manager handles window activation and keyboard focus, distinguishing between "active" (top-level window) and "focused" (control with keyboard focus). This is essential for proper window behavior and keyboard input routing.

Concepts

  • Active Window: The top-level window that is currently active (receives WM_ACTIVATE messages)
  • Focused Window: The control that currently has keyboard focus (receives keyboard input)
  • Z-Order: The stacking order of windows (topmost window is active)

Features

  • Window Activation: WM_ACTIVATE messages for top-level windows
  • Focus Management: WM_SETFOCUS and WM_KILLFOCUS messages
  • Z-Order Management: Maintains window stacking order
  • Focus Traversal: Tab key navigation between controls

API

activateWindow(hwnd)

Activates a top-level window:

  • hwnd - Window handle to activate

Sends WM_ACTIVATE to old and new active windows, and brings window to top of z-order.

deactivateWindow(hwnd)

Deactivates a window:

  • hwnd - Window handle to deactivate

setFocus(hwnd)

Sets keyboard focus to a control:

  • hwnd - Control handle to focus

Sends WM_SETFOCUS to new focused control and WM_KILLFOCUS to previously focused control.

getFocus()

Returns the currently focused window handle.

getActiveWindow()

Returns the currently active top-level window handle.

bringToTop(hwnd)

Brings a window to the top of the z-order:

  • hwnd - Window handle

Usage Example

const FocusManager = require('./system/focus');

const focusManager = new FocusManager();

// Activate a window
focusManager.activateWindow(windowHwnd);

// Set focus to a control
focusManager.setFocus(buttonHwnd);

// Get current focus
const focusedHwnd = focusManager.getFocus();

// Get active window
const activeHwnd = focusManager.getActiveWindow();

Message Flow

When a window is activated:

  1. Old active window receives WM_ACTIVATE (active=false)
  2. New window is brought to top of z-order
  3. New active window receives WM_ACTIVATE (active=true)

When focus changes:

  1. Previously focused control receives WM_KILLFOCUS
  2. New focused control receives WM_SETFOCUS

Integration

The Focus Manager integrates with:

  • Window Manager: Window activation and focus
  • Input Manager: Keyboard input routing
  • Controls: Focus visual feedback
  • GUI Integration: Initialized as part of the GUI system

Related Documentation