@eclipse-scout/core

/// <reference types="jquery" /> import { AbstractLayout, BoundsOptions, Dimension, Insets, InsetsOptions, LayoutData, Point, PrefSizeOptions, Rectangle, Session, SizeOptions } from '../index'; export interface HtmlCompPrefSizeOptions extends PrefSizeOptions { /** * Whether to include the margin in the returned size. Default is false. */ includeMargin?: boolean; /** * When set, horizontal padding, border and margin are removed from it so that the actual layout does not need to take care of it. Default is null. */ widthHint?: number; /** * When set, vertical padding, border and margin are removed from it so that the actual layout does not need to take care of it. Default is null. */ heightHint?: number; /** * Whether or not to automatically remove the margin from the hints. Default is true. */ removeMarginFromHints?: boolean; /** * Whether or not to automatically remove the insets (padding and border) from the hints. Default is true. */ removeInsetsFromHints?: boolean; /** * If true, only the preferred width should be calculated. Whether this has an effect depends on the used layout. Default is false. */ widthOnly?: boolean; } /** * A HTMLComponent wraps a {@link JQuery} object and provides a possibility to layout its children using {@link AbstractLayout}. * A layout is necessary if it is not sufficient to use CSS for layouting, e.g. for elements that need to be positioned and sized dynamically and exactly. * * Every component is responsible to layout its child components using the specified {@link layout}. The layout calculates and updates the sizes and/or positions for the children using {@link setSize} or {@link setBounds}. * If the size or bounds change, the child components get invalid and need to layout their children as well. So the layouting happens top-down. * * If a child component is modified, e.g. changes its visibility or another attribute that impacts the size or position, it needs to be invalidated. Since this not only affects the parent component but possibly every ancestor, * the whole ancestor component tree needs to be invalidated. This is done by using {@link invalidateLayoutTree}. So the invalidation happens bottom-up. */ export declare class HtmlComponent { $comp: JQuery; layout: AbstractLayout; layoutData: LayoutData; /** * Flag to indicate that the component has been layouted at least once. Invalidation should NOT reset this flag. */ layouted: boolean; /** * Flag to indicate that the component is being layouted. */ layouting: boolean; /** * Set pixelBasedSizing to false if your component automatically adjusts its size, * e.g. by using CSS styling -> setSize won't be called. */ pixelBasedSizing: boolean; /** * Object which stores the computed preferred size. Key is a string containing the width and height hints. * @see #computePrefSizeKey(options); */ prefSizeCached: Record<string, Dimension>; scrollable: boolean; session: Session; sizeCached: Dimension; /** * May be set to temporarily disable invalidation (e.g. if the component gets modified during the layouting process) */ suppressInvalidate: boolean; /** * May be set to temporarily disable layout validation (e.g. if the component gets modified during the layouting process). * It is still possible to invalidate its layout. But as long as this flag is set, it will not validate the layout. * It is the responsibility of the caller to ensure that the component is validated again (if necessary) when the layout validation suppression is removed. */ suppressValidate: boolean; valid: boolean; validateRoot: boolean; constructor($comp: JQuery, session: Session); /** * Returns the {@link HtmlComponent} of the parent DOM element or null if there is no parent DOM element or the parent DOM element is not linked to a HtmlComponent. */ getParent(): HtmlComponent; /** * @returns true if the given htmlComponent is an ancestor, false if not. */ isDescendantOf(htmlComp: HtmlComponent): boolean; /** * Computes the preferred height if the component is scrollable and returns it, if it is greater than the actual size. * If it is not scrollable, the actual height is returned. * * The returned size contains insets (padding and border) but no margin. The width is always the actual width because there are no horizontal scrollbars. */ availableSize(options?: SizeOptions): Dimension; /** * Invalidates the component (sets the valid property to false and calls {@link AbstractLayout.invalidate}. * @param htmlSource The component the invalidation originated from. * Is always set if the invalidation is triggered by using {@link invalidateLayoutTree}, may be undefined otherwise. */ invalidateLayout(htmlSource?: HtmlComponent): void; /** * Calls the layout of the component to lay out its children but only if the component is not valid. * @returns true if validation was successful, false if it could not be executed (e.g. because the element is invisible or detached) * @exception when component has no layout */ validateLayout(): boolean; protected _checkValidationPossible(): boolean; protected _validateLayoutAfterAnimation($animatedElement: JQuery): void; protected _validateLayoutAfterPromise(promise: JQuery.Promise<any>): void; /** * Performs invalidateLayout() and validateLayout() subsequently. */ revalidateLayout(): void; /** * Uses the {@link LayoutValidator} to invalidate the html component tree up to the next validate root. If invalidateParents is set to false, only the current component is invalidated. * Default for invalidateParents is true. * * Invalidating basically means setting {@link valid} to false so that the next validation cycle will layout the component again. See also {@link invalidate}. * * The caller does not need to trigger a validation manually. The {@link LayoutValidator} will schedule the next validation automatically. */ invalidateLayoutTree(invalidateParents?: boolean): void; /** * Layouts all invalid components */ validateLayoutTree(): void; /** * Performs {@link invalidateLayoutTree} and {@link validateLayoutTree} subsequently. */ revalidateLayoutTree(invalidateParents?: boolean): void; /** * Marks the end of the parent invalidation. * * A component is a validate root if its size does not depend on the visibility or bounds of its children. * * Example: It is not necessary to relayout the whole form if just the label of a form field gets invisible. * Only the form field container needs to be relayouted. In this case the form field container is the validate root. */ isValidateRoot(): boolean; /** * Sets the given layout. */ setLayout(layout: AbstractLayout): void; /** * Returns the preferred size of the component, insets included, margin excluded. * * The preferred size is cached until the component will be invalidated. * Hence, subsequent calls to this function will return the cached preferred size unless the component is invalidated. * * * @param options an optional options object. See {@link HtmlCompPrefSizeOptions} for the available options. * All other options are passed as they are to the layout when {@link AbstractLayout.preferredLayoutSize} is called. * But it depends on the actual layout if these options have an effect or not. * Short-hand version: If a boolean is passed instead of an object, the value is automatically converted to the option "includeMargin". * @exception When component has no layout */ prefSize(options?: HtmlCompPrefSizeOptions | boolean): Dimension; computePrefSizeKey(options: HtmlCompPrefSizeOptions): string; /** * Removes padding, border and margin from the width and heightHint so that the actual layout does not need to take care of it. * Also makes sure the hints consider the min and max size set by CSS. */ protected _adjustSizeHintsForPrefSize(options: HtmlCompPrefSizeOptions, minSize: Dimension, maxSize: Dimension): void; /** * The html element may define a min or max height/height -> adjust the pref size accordingly * @internal */ _adjustPrefSizeWithMinMaxSize(prefSize: Dimension, minSize?: Dimension, maxSize?: Dimension): void; /** * Returns the inset-dimensions of the component (padding and border, no margin). */ insets(options?: InsetsOptions | boolean): Insets; margins(): Insets; borders(): Insets; cssMinSize(): Dimension; cssMaxSize(): Dimension; /** * @param options an optional options object. Short-hand version: If a boolean is passed instead * of an object, the value is automatically converted to the option "includeMargin". * @returns the size of the component, insets included. * @see graphics.size */ size(options?: SizeOptions | boolean): Dimension; /** * Sets the size of the component, insets included. Which means: the method subtracts the components insets * from the given size before setting the width/height of the component. */ setSize(size: Dimension): void; /** * Delegates to {@link graphics.bounds}. */ bounds(options?: BoundsOptions | boolean): Rectangle; /** * Delegates to {@link graphics.position}. */ position(): Point; /** * Delegates to {@link graphics.offsetBounds}. */ offsetBounds(options?: BoundsOptions | boolean): Rectangle; /** * Delegates to {@link graphics.offset}. */ offset(): Point; /** * Delegates to {@link graphics.setLocation}. */ setLocation(location: Point): void; /** * Delegates to {@link graphics.location}. */ location(): Point; setBounds(bounds: Rectangle): void; /** * Sets the component to its preferred size. */ pack(): void; /** * Checks whether {@link $comp} is in the DOM or has been removed or detached. * Also returns false if the {@link $comp} does not belong to a window (defaultView) anymore. This may happen if it belonged to a popup window which is now closed. */ isAttached(): boolean; isVisible(): boolean; isAttachedAndVisible(): boolean; debug(): string; /** * Creates a new {@link HtmlComponent} and links it to the given $comp element, so it can be * retrieved again with <code>HtmlComponent.get($comp)</code>. */ static install($comp: JQuery, session: Session): HtmlComponent; /** * Returns the {@link HtmlComponent} associated with the given DOM $comp. * Throws an error when data 'htmlComponent' is not set. */ static get($comp: JQuery): HtmlComponent; /** * Returns the {@link HtmlComponent} associated with the given DOM $comp. * Returns null if data 'htmlComponent' is not set. */ static optGet($comp: JQuery): HtmlComponent; } //# sourceMappingURL=HtmlComponent.d.ts.map