@eclipse-scout/core/dist/d.ts/src/scrollbar/scrollbars.d.ts

Eclipse Scout runtime

/// <reference types="jquery" />
import { Rectangle, Scrollbar, Session, SomeRequired, WidgetModel } from '../index';
export type ScrollDirection = 'x' | 'y' | 'both';
export interface ScrollbarInstallOptions extends WidgetModel {
    /**
     * Default is both
     */
    axis?: ScrollDirection;
    borderless?: boolean;
    mouseWheelNeedsShift?: boolean;
    nativeScrollbars?: boolean;
    hybridScrollbars?: boolean;
    /**
     * Controls the scroll shadow behavior:
     * <ul>
     *   <li>To define where the shadow should appear, use one of the following values: x, y, top, right, bottom, left. Multiple values can be separated by space.
     *   <li>If no positioning value is provided, it is automatically determined based on the axis.</li>
     *   <li>To adjust the style, add one of the following values: large or gradient.</li>
     *   <li>To disable the scroll shadow completely, set the value to none.</li>
     * </ul>
     */
    scrollShadow?: string | string[];
    /**
     * function to customize the scroll shadow
     */
    scrollShadowCustomizer?($container: JQuery, $shadow: JQuery): void;
}
export interface ScrollOptions {
    /**
     * If true, the scroll position will be animated so that the element moves smoothly to its new position. Default is false.
     */
    animate?: boolean;
    /**
     * whether the animation should be stopped. Default is false.
     */
    stop?: boolean;
}
export interface ScrollToOptions extends ScrollOptions {
    /**
     * Specifies where the element should be positioned in the view port. Can either be 'top', 'center' or 'bottom'.
     * If unspecified, the following rules apply:
     *   - If the element is above the visible area it will be aligned to top.
     *   - If the element is below the visible area it will be aligned to bottom.
     *   - If the element is already in the visible area no scrolling is done.
     * Default is undefined.
     */
    align?: string;
    /**
     * If true, all running animations are stopped before executing the current scroll request. Default is true.
     */
    stop?: boolean;
    /**
     * Additional margin to assume at the top of the target element (independent of any actual CSS margin).
     * Useful when elements are positioned outside their boundaries (e.g. focus border). Default is 4.
     */
    scrollOffsetUp?: number;
    /**
     * Additional margin to assume at the bottom of the target element (independent of any actual CSS margin).
     * Useful when elements are positioned outside their boundaries (e.g. focus border). Default is 8.
     */
    scrollOffsetDown?: number;
}
export interface ExpandableElement {
    height: number;
    level?: number;
}
export interface ExpansionParent<T extends ExpandableElement> {
    element: T;
    $element: JQuery;
    $scrollable: JQuery;
    defaultChildHeight: number;
    nodePaddingLevel?: number;
    isExpanded(element: T): boolean;
    getChildren(element: T): T[];
}
/**
 * Static function to install a scrollbar on a container.
 * When the client supports pretty native scrollbars, we use them by default.
 * Otherwise, we install JS-based scrollbars. In that case the install-function
 * creates a new scrollbar.js. For native scrollbars we
 * must set some additional CSS styles.
 */
export declare const scrollbars: {
    /** @internal */
    _$scrollables: Record<string, JQuery<HTMLElement>[]>;
    intersectionObserver: IntersectionObserver;
    getScrollables(session?: Session): JQuery[];
    pushScrollable(session: Session, $container: JQuery): void;
    removeScrollable(session: Session, $container: JQuery): void;
    install($container: JQuery, options?: SomeRequired<ScrollbarInstallOptions, 'parent'>): JQuery;
    /** @internal */
    _installNative($container: JQuery, options: ScrollbarInstallOptions): void;
    /** @internal */
    _installNativeInternal($container: JQuery, options: ScrollbarInstallOptions): void;
    installScrollShadow($container: JQuery, options: ScrollbarInstallOptions): void;
    uninstallScrollShadow($container: JQuery, session: Session): void;
    _hasScrollShadow(session: Session, entryPoint?: HTMLElement): boolean;
    /** @internal */
    _computeScrollShadowStyle(options: ScrollbarInstallOptions): string[];
    updateScrollShadowWhileScrolling($container: JQuery): void;
    updateScrollShadow($container: JQuery): void;
    /**
     * Installs a dom mutation observer that tracks all scrollables in order to move the scroll shadow along with the scrollable.
     * @internal
     */
    _installMutationObserver($entryPoint: JQuery): void;
    /** @internal */
    _onDomMutation(mutationList: MutationRecord[], observer: MutationObserver): void;
    /** @internal */
    _processDomMutation(mutation: MutationRecord): void;
    /** @internal */
    _uninstallMutationObserver($entryPoint: JQuery): void;
    /**
     * Installs an intersection observer that tracks the visibility of a scrollable in order to update the visibility of the scroll shadow accordingly.
     * @internal
     */
    _installIntersectionObserver(): void;
    /** @internal */
    _uninstallIntersectionObserver(): void;
    /** @internal */
    _onScrollableVisibleChange(element: Element, visible: boolean): void;
    hasScrollShadow($container: JQuery, position: string): boolean;
    isHybridScrolling($scrollable: JQuery): boolean;
    isNativeScrolling($scrollable: JQuery): boolean;
    isJsScrolling($scrollable: JQuery): boolean;
    getScrollAxis($scrollable: JQuery): ScrollDirection;
    /** @internal */
    _installJs($container: JQuery, options: SomeRequired<ScrollbarInstallOptions, 'parent'>): void;
    /**
     * Removes the js scrollbars for the $container, if there are any.<p>
     */
    uninstall($container: JQuery, session: Session): void;
    /**
     * Recalculates the scrollbar size and position.
     * @param $scrollable JQuery element that has .data('scrollbars'), when $scrollable is falsy the function returns immediately
     * @param immediate set to true to immediately update the scrollbar. If set to false, it will be queued in order to prevent unnecessary updates.
     */
    update($scrollable: JQuery, immediate?: boolean): void;
    /** @internal */
    _update(scrollbarArr: Scrollbar[]): void;
    /**
     * IOS has problems with nested scrollable containers. Sometimes the outer container goes completely white hiding the elements behind.
     * This happens with the following case: Main box is scrollable but there are no scrollbars because content is smaller than container.
     * In the main box there is a tab box with a scrollable table. This table has scrollbars.
     * If the width of the tab box is adjusted (which may happen if the tab item is selected and eventually prefSize called), the main box will go white.
     * <p>
     * This happens only if -webkit-overflow-scrolling is set to touch.
     * To work around this bug the flag -webkit-overflow-scrolling will be removed if the scrollable component won't display any scrollbars
     * @internal
     */
    _handleIosPaintBug($scrollable: JQuery): void;
    reset($scrollable: JQuery): void;
    /**
     * Scrolls the $scrollable to the given $element (must be a child of $scrollable)
     *
     * @param $scrollable
     *          the scrollable object
     * @param $element
     *          the element to scroll to
     * @param opts
     *          Shorthand version: If a string is passed instead
     *          of an object, the value is automatically converted to the option {@link ScrollToOptions.align}.
     */
    scrollTo($scrollable: JQuery, $element: JQuery, opts?: ScrollToOptions | string): void;
    /** @internal */
    _createDefaultScrollToOptions(options?: ScrollbarInstallOptions): ScrollToOptions;
    /**
     * Horizontally scrolls the $scrollable to the given $element (must be a child of $scrollable)
     */
    scrollHorizontalTo($scrollable: JQuery, $element: JQuery, options?: ScrollOptions): void;
    /**
     * @param $scrollable the scrollable object
     * @param scrollTop the new scroll position
     */
    scrollTop($scrollable: JQuery, scrollTop: number, options?: ScrollOptions): void;
    /**
     * @param $scrollable the scrollable object
     * @param scrollLeft the new scroll position
     */
    scrollLeft($scrollable: JQuery, scrollLeft: number, options?: ScrollOptions): void;
    animateScrollTop($scrollable: JQuery, scrollTop: number): void;
    animateScrollLeft($scrollable: JQuery, scrollLeft: number): void;
    scrollbar($scrollable: JQuery, axis: 'x' | 'y'): Scrollbar;
    scrollToBottom($scrollable: JQuery, options?: ScrollOptions): void;
    /**
     * Computes whether the given location is in the viewport of the given $scrollables.
     *
     * @param $scrollables one or more scrollables to check against
     * @returns true if the location is visible in the current viewport of the $scrollables or if $scrollables is null.
     */
    isLocationInView(location: {
        x: number;
        y: number;
    }, $scrollables: JQuery): boolean;
    /**
     * Clips the given bounds and removes the parts that are not in the current viewport of the given $scrollables.
     *
     * @param $scrollables one or more scrollables to check against
     * @returns the intersection between the bounds and the viewports of the $scrollables.
     *          If $scrollables is null or empty, the given bounds are returned without clipping.
     */
    intersectViewport(bounds: Rectangle, $scrollables: JQuery): Rectangle;
    /**
     * Attaches the given handler to each scrollable parent, including $anchor if it is scrollable as well.
     * Make sure you remove the handlers when not needed anymore using offScroll.
     */
    onScroll($anchor: JQuery, handler: (event: JQuery.ScrollEvent) => void): void;
    offScroll(handler: (event: JQuery.ScrollEvent) => void): void;
    /**
     * Sets the position to fixed and updates left and top position.
     * This is necessary to prevent flickering in IE.
     */
    fix($elem: JQuery): void;
    /**
     * Reverts the changes made by fix().
     */
    unfix($elem: JQuery, timeoutId: number, immediate?: boolean): number;
    /** @internal */
    _unfix($elem: JQuery): void;
    /**
     * Stores the position of all scrollables that belong to an optional session.
     * @param [session] when no session is given, scrollables from all sessions are stored
     */
    storeScrollPositions($container: JQuery, session?: Session): void;
    /**
     * Restores the position of all scrollables that belong to an optional session.
     * @param session when no session is given, scrollables from all sessions are restored
     */
    restoreScrollPositions($container: JQuery, session?: Session): void;
    setVisible($scrollable: JQuery, visible: boolean): void;
    opacity($scrollable: JQuery, opacity: number): void;
    /** @internal */
    _getCompleteChildRowsHeightRecursive(children: ExpandableElement[], getChildren: (element: ExpandableElement) => ExpandableElement[], isExpanded: (element: ExpandableElement) => boolean, defaultChildHeight: number): number;
    ensureExpansionVisible<T extends ExpandableElement>(parent: ExpansionParent<T>): void;
};
//# sourceMappingURL=scrollbars.d.ts.map