@eclipse-scout/core/dist/d.ts/src/focus/FocusManager.d.ts

Eclipse Scout runtime

import { DisplayParent, FocusContext, FocusRule, GlassPaneRenderer, Session } from '../index';
export interface FocusManagerOptions {
    session: Session;
    active?: boolean;
    restrictedFocusGain?: boolean;
}
export interface RequestFocusOptions {
    /**
     * prevents scrolling to new focused element (defaults to false)
     */
    preventScroll?: boolean;
    /**
     * prevents focusing if not ready
     */
    onlyIfReady?: boolean;
    /**
     * automatically selects the text content of the element if supported (defaults to false)
     */
    selectText?: boolean;
}
/**
 * The focus manager ensures proper focus handling based on focus contexts.
 *
 * A focus context is bound to a $container. Once a context is activated, that container defines the tab cycle,
 * meaning that only child elements of that container can be entered by tab. Also, the context ensures proper
 * focus gaining, meaning that only focusable elements can gain focus. A focusable element is defined as an element,
 * which is natively focusable and which is not covert by a glass pane. Furthermore, if a context is uninstalled,
 * the previously active focus context is activated and its focus position restored.
 */
export declare class FocusManager implements FocusManagerOptions {
    session: Session;
    active: boolean;
    restrictedFocusGain: boolean;
    /** @internal */
    _glassPaneDisplayParents: DisplayParent[];
    /** @internal */
    _glassPaneTargets: JQuery[];
    protected _focusContexts: FocusContext[];
    protected _glassPaneRenderers: GlassPaneRenderer[];
    constructor(options: FocusManagerOptions);
    installTopLevelMouseHandlers($container: JQuery): void;
    /**
     * Activates or deactivates focus management.
     *
     * If deactivated, the focus manager still validates the current focus, but never gains focus nor enforces a valid focus position.
     * Once activated, the current focus position is revalidated.
     */
    activate(activate: boolean): void;
    /**
     * Installs a new focus context for the given $container, and sets the $container's initial focus, either by
     * the given rule, or tries to gain focus for the given element.
     * @returns the installed context.
     */
    installFocusContext($container: JQuery, focusRuleOrElement?: FocusRule | HTMLElement): FocusContext;
    /**
     * Evaluates the {@link FocusRule} or just returns the given element if focusRuleOrElement is not a focus rule.
     */
    evaluateFocusRule($container: JQuery, focusRuleOrElement?: FocusRule | HTMLElement): HTMLElement;
    /**
     * Uninstalls the focus context for the given $container, and activates the last active context.
     * This method has no effect, if there is no focus context installed for the given $container.
     *
     * @param options a boolean whether to prevent scrolling to focused element or not (default is true)
     */
    uninstallFocusContext($container: JQuery, options?: {
        preventScroll?: boolean;
    }): void;
    /**
     * Returns whether there is a focus context installed for the given $container.
     */
    isFocusContextInstalled($container: JQuery): boolean;
    /**
     * Activates the focus context of the given $container or the given focus context and validates the focus so that the previously focused element will be focused again.
     */
    activateFocusContext(focusContextOr$Container: FocusContext | JQuery): void;
    /**
     * Checks if the given element is accessible, meaning not covert by a glasspane.
     *
     * @param filter if specified, the filter is used to filter the array of glass pane targets
     */
    isElementCovertByGlassPane(element: HTMLElement | JQuery, filter?: () => boolean): boolean;
    /**
     * Registers the given glasspane target, so that the focus cannot be gained on the given target nor on its child elements.
     */
    registerGlassPaneTarget($glassPaneTarget: JQuery): void;
    /**
     * Unregisters the given glasspane target, so that the focus can be gained again for the target or one of its child controls.
     */
    unregisterGlassPaneTarget($glassPaneTarget: JQuery): void;
    registerGlassPaneDisplayParent(displayParent: DisplayParent): void;
    unregisterGlassPaneDisplayParent(displayParent: DisplayParent): void;
    registerGlassPaneRenderer(glassPaneRenderer: GlassPaneRenderer): void;
    unregisterGlassPaneRenderer(glassPaneRenderer: GlassPaneRenderer): void;
    rerenderGlassPanes(): void;
    /**
     * Enforces proper focus on the currently active focus context.
     *
     * @param filter Filter to exclude elements to gain focus.
     */
    validateFocus(filter?: () => boolean): void;
    requestFocusIfReady(element: HTMLElement | JQuery, filter?: () => boolean): boolean;
    /**
     * Requests the focus for the given element, but only if being a valid focus location.
     *
     * @param element
     *        the element to focus, or null to focus the context's first focusable element matching the given filter.
     * @param filter
     *        filter that controls which element should be focused, or null to accept all focusable candidates.
     * @param options
     *        options to customize the focus request.
     * @returns true if focus was gained, false otherwise.
     */
    requestFocus(element: HTMLElement | JQuery, filter?: () => boolean, options?: RequestFocusOptions): boolean;
    /**
     * Finds the first focusable element of the given $container, or null if not found.
     */
    findFirstFocusableElement($container: JQuery, filter?: () => boolean): HTMLElement;
    /**
     * Returns the currently active focus context, or null if not applicable.
     * @internal
     */
    _findActiveContext(): FocusContext;
    /**
     * Returns the focus context which is associated with the given $container, or null if not applicable.
     */
    getFocusContext($container: JQuery): FocusContext;
    /**
     * Focuses the next or previous valid element within the focus context of the given `activeElement`.
     */
    focusNextTabbable(activeElement: JQuery | HTMLElement, forward?: boolean): void;
    protected _findFocusContextFor(element: JQuery | HTMLElement): FocusContext;
    /**
     * Returns whether to accept a 'mousedown event'.
     */
    protected _acceptFocusChangeOnMouseDown($element: JQuery): boolean;
    /**
     * Registers the given focus context, or moves it on top if already registered.
     * @internal
     */
    _pushIfAbsentElseMoveTop(focusContext: FocusContext): void;
}
//# sourceMappingURL=FocusManager.d.ts.map