@theia/core/lib/browser/window/window-focus-service.d.ts

Theia is a cloud & desktop IDE framework implemented in TypeScript.

import { Disposable, DisposableCollection, Emitter, Event } from '../../common';
export interface WindowFocusEvent {
    win: Window;
    hasFocus: boolean;
}
/**
 * Tracks focus state for each registered application window independently.
 *
 * The main window is registered automatically. Secondary windows should be
 * registered via {@link registerWindow} — typically by the service responsible
 * for creating them.
 *
 * Uses two complementary signals per window for robust detection:
 * - `window` `focus`/`blur` events (OS-level window focus changes)
 * - `document` `visibilitychange` events (browser tab switches)
 *
 * Blur events are debounced per window with `setTimeout(0)` so that focus
 * moving between elements within the same window does not produce a false
 * blur: the subsequent `focus` event cancels the pending blur before it fires.
 *
 * Each per-window event is latched — it only fires when that window's focus
 * state actually changes.
 */
export declare class WindowFocusService implements Disposable {
    protected readonly onDidWindowChangeFocusEmitter: Emitter<WindowFocusEvent>;
    /**
     * Fires when an individual window's focus state changes.
     * The event payload identifies which window changed and whether it gained or lost focus.
     *
     * A window losing focus to another application window will fire separately
     * for each window involved: one event with `hasFocus: false` for the window
     * that lost focus, and one with `hasFocus: true` for the window that gained it.
     */
    readonly onDidWindowChangeFocus: Event<WindowFocusEvent>;
    protected readonly toDispose: DisposableCollection;
    /** Per-window tracking state. */
    protected readonly windowStates: Map<Window, WindowTrackingState>;
    protected init(): void;
    /**
     * Register a window for focus tracking. The returned {@link Disposable}
     * removes the window from tracking when disposed.
     *
     * The main window is registered automatically. Call this for secondary
     * windows when they are created.
     */
    registerWindow(win: Window): Disposable;
    /**
     * Whether any registered window currently has focus.
     */
    get hasFocus(): boolean;
    protected windowHasFocus(win: Window): boolean;
    protected handleFocus(win: Window, state: WindowTrackingState): void;
    /**
     * Schedule a deferred blur check for this specific window.
     * If no `focus` event arrives on this same window before the timeout fires,
     * we treat it as a real focus loss for that window.
     */
    protected scheduleBlur(win: Window, state: WindowTrackingState): void;
    protected cancelPendingBlur(state: WindowTrackingState): void;
    /**
     * Re-evaluate a single window's focus and fire if it changed (latching).
     */
    protected updateWindowFocusState(win: Window, state: WindowTrackingState): void;
    dispose(): void;
}
interface WindowTrackingState {
    lastFocusState: boolean;
    pendingBlurTimeout: ReturnType<typeof setTimeout> | undefined;
}
export {};
//# sourceMappingURL=window-focus-service.d.ts.map