@theia/core/lib/browser/hover-service.d.ts

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

import { Disposable, DisposableCollection, PreferenceService } from '../common';
import { MarkdownString } from '../common/markdown-rendering/markdown-string';
import { MarkdownRenderer } from './markdown-rendering/markdown-renderer';
import { OpenerService } from './opener-service';
import '../../src/browser/style/hover-service.css';
export type HoverPosition = 'left' | 'right' | 'top' | 'bottom';
export declare namespace HoverPosition {
    function invertIfNecessary(position: HoverPosition, target: DOMRect, host: DOMRect, totalWidth: number, totalHeight: number): HoverPosition;
    /**
     * Tests whether a hover of the given dimensions fits next to its target in the given
     * position without extending beyond the window bounds.
     */
    function fits(position: HoverPosition, target: DOMRect, host: DOMRect, totalWidth: number, totalHeight: number): boolean;
}
export interface HoverRequest {
    content: string | MarkdownString | HTMLElement;
    target: HTMLElement;
    /**
     * The position where the hover should appear.
     * Note that the hover service will try to invert the position (i.e. right -> left)
     * if the specified content does not fit in the window next to the target element
     */
    position: HoverPosition;
    /**
     * Additional css classes that should be added to the hover box.
     * Used to style certain boxes different e.g. for the extended tab preview.
     */
    cssClasses?: string[];
    /**
     * A function to render a visual preview on the hover.
     * Function that takes the desired width and returns a HTMLElement to be rendered.
     */
    visualPreview?: (width: number) => HTMLElement | undefined;
    /**
     * Indicates if the hover contains interactive/clickable items.
     * When true, the hover will register a click handler to allow interaction with elements in the hover area.
     */
    interactive?: boolean;
    /**
     * If implemented, this method will be called when the hover is no longer shown or no longer scheduled to be shown.
     */
    onHide?(): void;
    /**
     * When true, the hover will be shown immediately without any delay.
     * Useful for explicitly triggered hovers (e.g., on click) where the user expects instant feedback.
     * @default false
     */
    skipHoverDelay?: boolean;
}
export declare class HoverService {
    protected static hostClassName: string;
    protected static styleSheetId: string;
    protected readonly preferences: PreferenceService;
    protected readonly markdownRenderer: MarkdownRenderer;
    protected readonly openerService: OpenerService;
    protected _hoverHost: HTMLElement | undefined;
    /**
     * The host of the current hover, which may live in a secondary window's document.
     * Resolving against the main document here instead would silently replace the host
     * whenever the current hover lives in another document, detaching the dismissal
     * listeners and `unRenderHover` from the host that is actually rendered.
     */
    protected get hoverHost(): HTMLElement;
    /**
     * Returns the host element to render hovers into for the given document, creating it if the
     * current one belongs to a different document. A host is always created in the document it is
     * shown in: adopting a host into another document would let it outlive its window, and touching
     * it after that window was closed breaks (and in Electron crashes) the application.
     */
    protected getOrCreateHoverHost(targetDocument: Document): HTMLElement;
    protected pendingTimeout: Disposable | undefined;
    protected hoverTarget: HTMLElement | undefined;
    /** Identifies the latest render so that superseded renders can detect they are stale. */
    protected renderSequence: number;
    protected lastHidHover: number;
    protected readonly disposeOnHide: DisposableCollection;
    requestHover(request: HoverRequest): void;
    /**
     * Cancels the hover when the window hosting the target element goes away, e.g. when the
     * secondary window containing the target is closed: neither the hover host nor any listeners
     * may outlive the document they belong to.
     */
    protected listenForWindowClose(target: HTMLElement): void;
    protected getHoverDelay(): number;
    protected renderHover(request: HoverRequest): Promise<void>;
    /**
     * Waits for an animation frame in the window hosting the given target element,
     * which may be a secondary window whose rendering is independent of the main window's.
     */
    protected hostAnimationFrame(target: HTMLElement): Promise<void>;
    protected setHostPosition(target: HTMLElement, host: HTMLElement, position: HoverPosition): HoverPosition;
    protected listenForMouseOut(): void;
    cancelHover(): void;
    /**
     * Listen for mouse click (mousedown) events and handle them based on hover interactivity.
     * For non-interactive hovers, any mousedown cancels the hover immediately.
     * For interactive hovers, the hover remains visible to allow interaction with its elements.
     */
    protected listenForMouseClick(request: HoverRequest): void;
    protected unRenderHover(): void;
}
//# sourceMappingURL=hover-service.d.ts.map