@eclipse-scout/core

/// <reference types="jquery" /> import { Action, DeferredGlassPaneTarget, Desktop, EnumObject, EventDelegator, EventHandler, Form, HtmlComponent, InitModelOf, KeyStroke, KeyStrokeContext, LayoutData, LoadingSupport, LogicalGrid, ModelAdapter, ObjectOrChildModel, ObjectOrType, ObjectWithType, ObjectWithUuid, Predicate, PropertyDecoration, PropertyEventEmitter, ScrollbarInstallOptions, ScrollOptions, ScrollToOptions, Session, SomeRequired, TreeVisitResult, UuidPathOptions, WidgetEventMap, WidgetModel } from '../index'; export declare class Widget extends PropertyEventEmitter implements WidgetModel, ObjectWithType, ObjectWithUuid { model: WidgetModel; initModel: SomeRequired<this['model'], 'parent'>; eventMap: WidgetEventMap; self: Widget; widgetMap: WidgetMap; propertyDecorations: Record<WidgetPropertyDecoration, Set<string>>; animateRemoval: boolean; animateRemovalClass: string; attached: boolean; children: Widget[]; /** * Will be set on the clone after a widget has been cloned. */ cloneOf: this; cssClass: string; destroyed: boolean; destroying: boolean; disabledStyle: DisabledStyle; /** * The result of every enabled dimension. * * The value will only be true if every dimension is true. If one dimension is false (e.g. 'granted'), the value will be false. */ enabled: boolean; /** * The computed enabled state. * * The difference to the {@link enabled} property is that this member also considers the enabled-states of the ancestor widgets. * So, if you need to know whether a user can really access a widget, this property is what you need. */ enabledComputed: boolean; eventDelegators: EventDelegatorForCloning[]; focused: boolean; /** * Widgets creating a HtmlComponent for the main $container should assign it to this variable. * This enables the execution of layout related operations like invalidateLayoutTree directly on the widget. * @type {HtmlComponent} */ htmlComp: HtmlComponent; id: string; inheritAccessibility: boolean; keyStrokeContext: KeyStrokeContext; loading: boolean; loadingSupport: LoadingSupport; logicalGrid: LogicalGrid; objectType: string; owner: Widget; parent: Widget; removalPending: boolean; removing: boolean; /** * The 'rendering' flag is set the true while the _initial_ rendering is performed. * It is used to something different in a _render* method when the method is * called for the first time. */ rendering: boolean; scrollLeft: number; scrollTop: number; session: Session; trackFocus: boolean; uuid: string; uuidParent: ObjectWithUuid; visible: boolean; modelAdapter: ModelAdapter; $container: JQuery; $parent: JQuery; modelClass: string; classId: string; /** * The 'rendered' flag is set the true when initial rendering of the widget is completed. * * @internal */ _rendered: boolean; protected _$lastFocusedElement: JQuery; protected _focusInListener: (event: FocusEvent | JQuery.FocusInEvent) => void; protected _glassPaneContributions: GlassPaneContribution[]; protected _parentDestroyHandler: EventHandler; protected _parentRemovingWhileAnimatingHandler: EventHandler; protected _postRenderActions: (() => void)[]; protected _scrollHandler: (event: JQuery.ScrollEvent) => void; protected _storedFocusedWidget: Widget; constructor(); /** * Enum used to define different styles used when the field is disabled. */ static DisabledStyle: { readonly DEFAULT: 0; /** * Optimizes the disabled style for readability, meaning higher contrast and fewer borders. * * Should in general only be used if the enabled state of the widget cannot change dynamically, because the style is too similar to the enabled style. */ readonly READ_ONLY: 1; }; /** * Initializes the widget instance. All properties of the model parameter (object) are set as properties on the widget instance. * Calls {@link Widget#_init} and triggers an init event when initialization has been completed. */ init(model: InitModelOf<this>): void; /** * Default implementation simply returns the unmodified model. A Subclass * may override this method to alter the JSON model before the widgets * are created out of the widgetProperties in the model. */ protected _prepareModel(model: InitModelOf<this>): InitModelOf<this>; buildUuid(useFallback?: boolean): string; buildUuidPath(options?: UuidPathOptions): string; setUuid(uuid: string): void; /** * Initializes the widget instance. All properties of the model parameter (object) are set as properties on the widget instance. * Override this function to initialize widget specific properties in subclasses. */ protected _init(model: InitModelOf<this>): void; /** * Default implementation simply returns undefined. A Subclass * may override this method to load or extend a JSON model with models.getModel or models.extend. */ protected _jsonModel(): WidgetModel; protected _createChildren<T extends Widget>(models: ObjectOrChildModel<T> | string): T; protected _createChildren<T extends Widget>(models: (ObjectOrChildModel<T> | string)[]): T[]; protected _createChildren<T extends Widget>(models: ObjectOrChildModel<T> | string | (ObjectOrChildModel<T> | string)[]): T | T[]; /** * Calls {@link scout.create} for the given model, or if model is already a Widget simply returns the widget. * @internal */ _createChild<T extends Widget>(widgetOrModel: ObjectOrChildModel<T> | string): T; protected _initKeyStrokeContext(): void; /** * Destroys the widget including all owned children. * After destroying, the widget should and cannot be used anymore. Every attempt to render the widget will result in a 'Widget is destroyed' error. * * While destroying, the widget will remove itself and its children from the DOM by calling {@link remove}. * After removing, {@link _destroy} is called which can be used to remove listeners and to do other cleanup tasks. * Finally, the widget detaches itself from its parent and owner, sets the property {@link destroyed} to true and triggers a 'destroy' event. * * Notes * <ul> * <li>Children that have a different owner won't be destroyed, just removed.</li> * <li>The function does nothing if the widget is already destroyed.</li> * <li>If a remove animation is running or pending, the destroying will be delayed until the removal is done.</li> * </ul> */ destroy(): void; /** * Override this function to do clean-up (like removing listeners) when the widget is destroyed. * The default implementation does nothing. */ protected _destroy(): void; protected _destroyChildren(widgets: Widget[] | Widget): void; protected _destroyChild(child: Widget): void; protected _destroyOrUnlinkChildren(widgets: ObjectOrChildModel<Widget>[] | ObjectOrChildModel<Widget>): void; /** * Creates the UI by creating HTML elements and appending them to the DOM. * * The actual rendering happens in the methods {@link _render}, which appends the main container to the parent element, and {@link _renderProperties}, which calls the methods for each property that needs to be rendered. * After the rendering, the created {@link $container} will be linked with the widget, so the widget can be found by using {@link scout.widget}. * Finally, the widget sets the property {@link rendered} to true and triggers a 'render' event. * * @param $parent jQuery element which is used as {@link $parent} when rendering this widget. * It will be put onto the widget and is therefore accessible as {@link $parent} in the {@link _render} method. * If not specified, the {@link $container} of the parent is used. */ render($parent?: JQuery): void; /** * Creates the UI by creating HTML elements and appending them to the DOM. * * A typical widget creates exactly one container element and stores it to {@link $container}. * If it needs JS based layouting, it creates a {@link HtmlComponent} for that container and stores it to {@link htmlComp}. * * The rendering of individual properties should be done in the corresponding render methods of the properties, called by {@link _renderProperties} instead of doing it here. * This has the advantage that the render methods can also be called on property changes, allowing individual widget parts to be dynamically re-rendered. * * The default implementation does nothing. */ protected _render(): void; /** * Returns whether it is allowed to render something on the widget. * Rendering is only possible if the widget itself is rendered and not about to be removed. * * While the removal is pending, no rendering must happen to get a smooth remove animation. * It also prevents errors on property changes because {@link remove} won't be executed as well. * Preventing removal but allowing rendering could result in already rendered exceptions. * * @returns true if the widget is rendered and not being removed by an animation * * @see isRemovalPending */ get rendered(): boolean; set rendered(rendered: boolean); /** * Calls the render methods for each property that needs to be rendered during the rendering process initiated by {@link render}. * Each widget has to override this method and call the render methods for its own properties, after doing the super call. * * This method is called right after {@link _render} has been executed. */ protected _renderProperties(): void; /** * Method invoked once rendering completed and 'rendered' flag is set to 'true'. * By default executes every action of this._postRenderActions */ protected _postRender(): void; /** * Removes the widget and all its children from the DOM. * * It traverses down the widget hierarchy and calls {@link _remove} for each widget from the bottom up (depth first search). * * If the property {@link Widget.animateRemoval} is set to true, the widget won't be removed immediately. * Instead, it waits for the remove animation to complete, so it's content is still visible while the animation runs. * During that time, {@link isRemovalPending} returns true. */ remove(): void; /** * Removes the element without starting the remove animation or waiting for the remove animation to complete. * If the remove animation is running it will stop immediately because the element is removed. There will no animationend event be triggered. * * Important: You should only use this method if your widget uses remove animations (this.animateRemoval = true) * and you deliberately want to not execute or abort it. Otherwise, you should use the regular {@link remove} method. */ removeImmediately(): void; /** * Will be called by {@link #remove()}. If true is returned, the widget won't be removed. * By default it just delegates to {@link #isRemovalPending}. May be overridden to customize it. */ protected _isRemovalPrevented(): boolean; /** * Returns true if the removal of this or an ancestor widget is pending. Checking the ancestor is omitted if the parent is being removed. * This may be used to prevent a removal if an ancestor will be removed (e.g. by an animation) */ isRemovalPending(): boolean; /** @internal */ _removeInternal(): void; /** * Starts a "remove" animation for this widget. By default, a CSS class 'animate-remove' is added to the container. * After the animation is complete, the element gets removed from the DOM using this._removeInternal(). */ protected _removeAnimated(): void; protected _removeAnimatedImpl(): void; protected _animateRemovalWhileRemovingParent(): boolean; protected _onParentRemovingWhileAnimating(): void; protected _renderInspectorInfo(): void; /** * Links $container with the widget. */ protected _linkWithDOM(): void; /** * Called right before _remove is called. * Default calls {@link LayoutValidator.cleanupInvalidComponents} to make sure that child components are removed from the invalid components list. * Also uninstalls keystroke context, loading support and scrollbars. */ protected _cleanup(): void; protected _remove(): void; /** @see WidgetModel.owner */ setOwner(owner: Widget): void; /** @see WidgetModel.parent */ setParent(parent: Widget): void; protected _addChild(child: Widget): void; protected _removeChild(child: Widget): void; /** * @returns a list of all ancestors */ ancestors(): Widget[]; /** * @returns true if the given widget is the same as this or a descendant */ isOrHas(widget: Widget): boolean; /** * Checks if the current widget contains the given widget. * For a good performance, it visits the ancestors of the given widget rather than the descendants of the current widget. * * @returns true if the given widget is a descendant */ has(widget: Widget): boolean; /** * @returns the form the widget belongs to (returns the first parent which is a {@link Form}). */ getForm(): Form; /** * @returns the first form which is not an inner form of a wrapped form field */ findNonWrappedForm(): Form; /** * @returns the desktop linked to the current session. * If the desktop is still initializing, it might not be available yet, in that case, it searches the parent hierarchy for it. */ findDesktop(): Desktop; /** * Sets the 'default' dimension for the {@link Widget.enabled} property and recomputes its state. * * @param enabled * The new enabled value for the 'default' dimension, or an object containing the new enabled dimensions. * @param updateParents * If true, the enabled property of all ancestor widgets are updated to same value as well. Default is false. * @param updateChildren * If true, the enabled property of all descendant widgets are updated to same value as well. Default is false. * *Important:* Use this parameter only if really necessary because traversing every descendant may be costly and overriding their enabled state may not be reverted easily. * Instead, in most cases you should be able to use {@link WidgetModel.inheritAccessibility} to make a descendant widget independent on its ancestors. * @see WidgetModel.enabled */ setEnabled(enabled: boolean | Record<string, boolean>, updateParents?: boolean, updateChildren?: boolean): void; /** * Called whenever a new value should be set for the {@link Widget.enabled} property (which is computed based on its dimensions). * * Sets the actual property and recomputes the {@link enabledComputed} property. */ protected _setEnabled(enabled: boolean): void; /** * Sets the 'granted' dimension for the {@link Widget.enabled} property and recomputes its state. * * @param enabledGranted the new enabled value for the 'granted' dimension. * @see WidgetModel.enabledGranted */ setEnabledGranted(enabledGranted: boolean): void; get enabledGranted(): boolean; recomputeEnabled(parentEnabled?: boolean): void; protected _updateEnabledComputed(enabledComputed: boolean, enabledComputedForChildren?: boolean): void; protected _childrenForEnabledComputed(): Widget[]; protected _computeEnabled(inheritAccessibility: boolean, parentEnabled: boolean): boolean; protected _renderEnabled(): void; /** @see WidgetModel.inheritAccessibility */ setInheritAccessibility(inheritAccessibility: boolean): void; protected _setInheritAccessibility(inheritAccessibility: boolean): void; /** @see WidgetModel.disabledStyle */ setDisabledStyle(disabledStyle: DisabledStyle): void; protected _renderDisabledStyle(): void; protected _renderDisabledStyleInternal($element: JQuery): void; /** * Sets the 'default' dimension for the {@link Widget.visible} property and recomputes its state. * * @param visible the new visible value for the 'default' dimension, or an object containing the new visible dimensions. * @see WidgetModel.visibleGranted */ setVisible(visible: boolean | Record<string, boolean>): void; /** * Sets the 'granted' dimension for the {@link Widget.visible} property and recomputes its state. * * @param visibleGranted the new visible value for the 'granted' dimension. * @see WidgetModel.visibleGranted */ setVisibleGranted(visibleGranted: boolean): void; get visibleGranted(): boolean; /** * @deprecated use {@link visible} directly. Will be removed in an upcoming release. */ isVisible(): boolean; protected _renderVisible(): void; /** * @returns true if every parent within the hierarchy is visible. */ isEveryParentVisible(): boolean; /** * This function does not set the focus to the field. It toggles the 'focused' class on the field container if present. * Objects using widget as prototype must call this function onBlur and onFocus to ensure the class gets toggled. * * Use {@link focus} to set the focus to the widget. */ setFocused(focused: boolean): void; protected _renderFocused(): void; protected _setCssClass(cssClass: string): void; protected _removeCssClass(): void; protected _renderCssClass(): void; /** * @param cssClass may contain multiple css classes separated by space. * @see WidgetModel.cssClass */ setCssClass(cssClass: string): void; /** * @param cssClass may contain multiple css classes separated by space. */ addCssClass(cssClass: string): void; /** * @param cssClass may contain multiple css classes separated by space. */ removeCssClass(cssClass: string): void; /** * @param cssClass may contain multiple css classes separated by space. */ toggleCssClass(cssClass: string, condition: boolean): void; /** * @returns true, if the {@link cssClass} property contains the given css class. */ hasCssClass(cssClass: string): boolean; cssClassAsArray(): string[]; /** * Creates nothing by default. If a widget needs loading support, override this method and return a loading support. */ protected _createLoadingSupport(): LoadingSupport; /** @see WidgetModel.loading */ setLoading(loading: boolean): void; isLoading(): boolean; protected _renderLoading(): void; /** * Delegates the pack request to {@link HtmlComponent#pack}. */ pack(): void; /** * Delegates the invalidateLayout request to {@link HtmlComponent#invalidateLayout}. */ invalidateLayout(): void; /** * Delegates the validateLayout request to {@link HtmlComponent#validateLayout}. */ validateLayout(): void; /** * Delegates the revalidateLayout request to {@link HtmlComponent#revalidateLayout}. */ revalidateLayout(): void; /** * Delegates the invalidation request to {@link HtmlComponent#invalidateLayoutTree}. * @param invalidateParents Default is true */ invalidateLayoutTree(invalidateParents?: boolean): void; /** * Delegates the invalidation request to {@link HtmlComponent#validateLayoutTree}. */ validateLayoutTree(): void; /** * Delegates the invalidation request to {@link HtmlComponent#revalidateLayoutTree}. * @param invalidateParents Default is true */ revalidateLayoutTree(invalidateParents?: boolean): void; /** * The layout data contains hints for the layout of the parent container to lay out this individual child widget inside the container. * Note: this is not the same as the LayoutConfig. The LayoutConfig contains constraints for the layout itself and is therefore set on the parent container directly. * * Example: The parent container uses a {@link LogicalGridLayout} to lay out its children. Every child has a {@link LogicalGridData} to tell the layout how this specific child should be layouted. * The parent may have a {@link LogicalGridLayoutConfig} to specify constraints which affect either only the container or every child in the container. */ setLayoutData(layoutData: LayoutData): void; /** * If the widget uses a {@link LogicalGridLayout}, the grid may be validated using this method. * * If the grid is not dirty, nothing happens. */ validateLogicalGrid(): void; /** * Marks the logical grid as dirty. * Does nothing, if there is no logical grid. * @param invalidateLayout true, to invalidate the layout afterward using {@link invalidateLayoutTree}, false if not. Default is true. */ invalidateLogicalGrid(invalidateLayout?: boolean): void; /** * Invalidates the logical grid of the parent widget. Typically, done when the visibility of the widget changes. * @param invalidateLayout true, to invalidate the layout of the parent of {@link htmlComp}, false if not. Default is true. */ invalidateParentLogicalGrid(invalidateLayout?: boolean): void; revalidateLogicalGrid(invalidateLayout?: boolean): void; /** * @param logicalGrid an instance of {@link LogicalGrid} or a string representing the objectType of a logical grid. * @see WidgetModel.logicalGrid */ setLogicalGrid(logicalGrid: ObjectOrType<LogicalGrid>): void; protected _setLogicalGrid(logicalGrid: ObjectOrType<LogicalGrid>): void; /** * @returns the entry-point for this Widget or its parent. If the widget is part of the main-window it returns {@link session.$entryPoint}, * for popup-window this function will return the body of the document in the popup window. */ entryPoint(): JQuery; /** * Returns the `window` inside which this widget is currently rendered. If the widget is not rendered, `null` (or an empty jQuery * collection, respectively) is returned. * * @param domElement if true the result is returned as DOM element, otherwise it is returned as jQuery object. The default is false. */ window<T extends boolean>(domElement?: T): T extends true ? Window : JQuery<Window>; /** * Returns the `document` inside which this widget is currently rendered. If the widget is not rendered, `null` (or an empty jQuery * collection, respectively) is returned. * * @param domElement if true the result is returned as DOM element, otherwise it is returned as jQuery object. The default is false. */ document<T extends boolean>(domElement?: T): T extends true ? Document : JQuery<Document>; /** * This method attaches the detached {@link $container} to the DOM. */ attach(): void; /** * Override this method to do something when the widget is attached again. Typically, * you will append {@link $container} to {@link $parent}. */ protected _attach(): void; /** * Override this method to do something after this widget is attached. * This function is not called on any child of the attached widget. */ protected _postAttach(): void; protected _triggerChildrenOnAttach(parent: Widget): void; /** * Override this method to do something after this widget or any parent of it is attached. * This function is called regardless of whether the widget is rendered or not. */ protected _onAttach(): void; /** * Override this method to do something after this widget or any parent of it is attached. * This function is only called when this widget is rendered. */ protected _renderOnAttach(): void; /** * Detaches the element and all its children from the DOM. * Compared to {@link remove}, the state of the HTML elements are preserved, so they can be attached again without the need to render them again from scratch. * {@link attach}/{@link detach} is faster in general than {@link render}/{@link remove}, but it is much more error-prone and should therefore only be used very carefully. Rule of thumb: Don't use it, use {@link remove} instead. * The main problem with attach/detach is that a widget can change its model anytime. If this happens for a removed widget, only the model will change, and when rendered again, the recent model is used to create the HTML elements. * If the same happens when a widget is detached, the widget is still considered rendered and the model applied to the currently detached elements. * This may or may not work because a detached element for example does not have a size or a position. * * @see _beforeDetach * @see _onDetach * @see _renderOnDetach * @see _detach */ detach(): void; /** * This function is called before a widget gets detached. The function is only called on the detached widget and NOT on * any of its children. */ protected _beforeDetach(): void; protected _triggerChildrenOnDetach(): void; /** * This function is called before a widget or any of its parent getting detached. * This function is thought to be overridden. */ protected _onDetach(): void; protected _renderOnDetach(): void; /** * Override this method to do something when the widget is detached. * Typically, you will call 'this.$container.detach()'. The default implementation does nothing. */ protected _detach(): void; protected _uninstallFocusContext(): void; protected _installFocusContext(): void; /** * Does nothing by default. If a widget needs keystroke support override this method and return a keystroke context, e.g. the default KeyStrokeContext. */ protected _createKeyStrokeContext(): KeyStrokeContext; updateKeyStrokes(newKeyStrokes: KeyStroke | KeyStroke[] | Action | Action[], oldKeyStrokes?: KeyStroke | KeyStroke[] | Action | Action[]): void; registerKeyStrokes(keyStrokes: KeyStroke | KeyStroke[] | Action | Action[]): void; unregisterKeyStrokes(keyStrokes: KeyStroke | KeyStroke[] | Action | Action[]): void; /** * Sets a new value for a specific property. If the new value is the same value as the old one, nothing happens. * Otherwise, the following phases are executed: * * 1. Preparation: If the property is a widget property, several actions are performed in {@link _prepareWidgetProperty}. * 2. DOM removal: If the property is a widget property and the widget is rendered, the changed widget(s) are removed unless the property should not be preserved (see {@link preserveOnPropertyChangeProperties}). * If there is a custom remove function (e.g. \_removeXY where XY is the property name), it will be called instead of removing the widgets directly. * 3. Model update: If there is a custom set function (e.g. \_setXY where XY is the property name), it will be called. Otherwise, the default set function {@link _setProperty} is called. * 4. DOM rendering: If the widget is rendered and there is a custom render function (e.g. \_renderXY where XY is the property name), it will be called. Otherwise, nothing happens. * * @returns true, if the property was changed, false if not. */ protected setPropertyInternal(propertyName: string, value: any): boolean; protected _prepareProperty(propertyName: string, value: any): any; protected _prepareWidgetProperty(propertyName: string, models: ObjectOrChildModel<Widget>): Widget; protected _prepareWidgetProperty(propertyName: string, models: ObjectOrChildModel<Widget>[]): Widget[]; /** * Does nothing if the property is not a widget property. * If it is a widget property, it removes the existing widgets. Render has to be implemented by the widget itself. */ protected _callRemoveProperty(propertyName: string): void; /** * Removes the given widgets */ protected _internalRemoveWidgets(widgets: Widget[]): void; protected _callRenderProperty(propertyName: string): void; /** * Sets this widget as parent of the given widget(s). * * @param widgets may be a widget or array of widgets */ link(widgets: Widget[] | Widget): void; /** * Method required for widgets which are supposed to be directly covered by a glasspane. * * Returns the DOM elements to paint a glassPanes over, once a modal Form, message-box or file-chooser is shown with this widget as its 'displayParent'. * If the widget is not rendered yet, a scout.DeferredGlassPaneTarget is returned. * In both cases the method _glassPaneTargets is called which may be overridden by the actual widget. * @param element widget that requested a glass pane */ glassPaneTargets(element?: Widget): GlassPaneTarget[]; /** * @param element widget that requested a glass pane */ protected _glassPaneTargets(element: Widget): GlassPaneTarget[]; addGlassPaneContribution(contribution: GlassPaneContribution): void; /** * @param contribution a function which returns glass pane targets (jQuery elements) */ removeGlassPaneContribution(contribution: GlassPaneContribution): void; toString(): string; /** * Returns the ancestors as string delimited by '\n'. * @param count the number of ancestors to be processed. Default is -1 which means all. */ ancestorsToString(count?: number): string; resolveTextKeys(properties: string[]): void; resolveIconIds(properties: string[]): void; resolveConsts(configs: { property: string; constType: any; }[]): void; /** * A so-called widget property is a property with a widget as value incl. automatic resolution of that widget. * This means the property not only accepts the actual widget, but also a widget model or a widget reference (id) * and then either creates a new widget based on the model or resolves the id and uses the referenced widget as value. * Furthermore, it will take care of its lifecycle which means, the widget will automatically be removed and destroyed (as long as the parent is also the owner). * * If only the resolve operations without the lifecycle actions should be performed, you need to add the property to the list {@link preserveOnPropertyChangeProperties} as well. */ protected _addWidgetProperties(properties: string | string[]): void; protected _removeWidgetProperties(properties: string | string[]): void; isWidgetProperty(propertyName: string): boolean; get widgetProperties(): Set<string>; /** @internal */ _addCloneProperties(properties: string | string[]): void; isCloneProperty(propertyName: string): boolean; get cloneProperties(): Set<string>; /** * Properties in this list won't be affected by the automatic lifecycle actions performed for regular widget properties. * This means, the widget won't be removed, destroyed and also not linked, which means the parent stays the same. * But the resolve operations are still applied, as for regular widget properties. * * The typical use case for such properties is referencing another widget without taking care of that widget. */ protected _addPreserveOnPropertyChangeProperties(properties: string | string[]): void; isPreserveOnPropertyChangeProperty(propertyName: string): boolean; get preserveOnPropertyChangeProperties(): Set<string>; protected _eachProperty(model: WidgetModel, func: (propertyName: string, value: any, isWidgetProperty?: boolean) => void): void; /** * Clones the widget and mirrors the events, see {@link clone} and {@link mirror} for details. */ cloneAndMirror(model: WidgetModel): Widget; /** * @returns the original widget from which this one was cloned. If it is not a clone, itself is returned. */ original(): this; /** * Clones the widget and returns the clone. Only the properties defined in {@link cloneProperties} are copied to the clone. * The parameter model has to contain at least the property 'parent'. * * @param model The model used to create the clone is a combination of the clone properties and this model. * Therefore, this model may be used to override the cloned properties or to add additional properties. * @param options Options passed to the mirror function. */ clone(model: WidgetModel, options?: CloneOptions): this; protected _deepCloneProperties(clone: Widget, properties: string | string[], options: CloneOptions): Widget; /** * Delegates every property change event from the original widget to this cloned widget by calling the appropriate setter. * If no target is set it works only if this widget is a clone. */ mirror(options?: CloneOptions, target?: Widget): void; protected _mirror(clone: Widget, options: CloneOptions): void; unmirror(target: Widget): void; protected _unmirror(target: Widget): void; protected _onParentDestroy(): void; /** * Traverses the widget tree starting from this widget and searches for a child widget with the given ID. * * @param widgetId the ID of the widget to look for * @param type the type of the widget to look for. The return value will be cast to that type. This parameter has no effect at runtime. * @returns the widget for the requested ID or null if no widget has been found. */ widget<T extends Widget>(widgetId: string, type: abstract new () => T): T; /** * Traverses the widget tree starting from this widget and searches for a child widget with the given ID. * * If this widget has a {@link widgetMap}, its type has to contain a mapping for the given ID so the found widget can be cast to the correct type. * If there is no concrete {@link widgetMap}, the return type will be {@link Widget}. * * @param widgetId the ID of the widget to look for * @returns the widget for the requested ID or null if no widget has been found. */ widget<TId extends string & keyof WidgetMapOf<this>>(widgetId: TId): WidgetMapOf<this>[TId]; /** * Similar to {@link widget}, but uses "breadth-first" strategy, i.e. it checks all children of the * same depth (level) before it advances to the next level. If multiple widgets with the same * ID exist, the one with the smallest distance to this widget is returned. * * Example: * * Widget ['MyWidget'] #1 * +- GroupBox ['LeftBox'] #2 * +- StringField ['NameField'] #3 * +- StringField ['CityField'] #4 * +- GroupBox ['InnerBox'] #5 * +- GroupBox ['LeftBox'] #6 * +- DateField ['StartDate'] #7 * +- GroupBox ['RightBox'] #8 * +- DateField ['EndDate'] #9 * +- GroupBox ['RightBox'] #10 * +- StringField ['NameField'] #11 * +- DateField ['StartDate'] #12 * * CALL: RESULT: * --------------------------------------------------------------------------------------------- * this.widget('RightBox') #8 (might not be the expected result) * this.nearestWidget('RightBox') #10 * * this.widget('NameField') #3 * this.nearestWidget('NameField') null (because no direct child has the requested id) * this.nearestWidget('NameField', true) #3 (because #3 and #11 have the same distance) * * this.widget('StartDate') #7 * this.nearestWidget('StartDate', true) #12 (#12 has smaller distance than #7) * * @param widgetId * The ID of the widget to find. * @param deep * If false, only this widget and the next level are checked. This is the default. * If true, the entire tree is traversed. * @returns the first found widget, or null if no widget was found. */ nearestWidget(widgetId: string, deep?: boolean): Widget; /** * @param predicateOrClass may be a {@link Predicate} or a subclass of {@link Widget}. * @returns the first ancestor for which the given predicate returns true or that matches the given widget type if a subclass of {@link Widget} is provided. */ findParent<T extends Widget>(predicateOrClass: Predicate<Widget> | (abstract new () => T)): T; /** * @param predicateOrClass may be a {@link Predicate} or a subclass of {@link Widget}. * @returns the first child for which the given predicate returns true or that matches the given widget type if a subclass of {@link Widget} is provided. */ findChild<T extends Widget>(predicateOrClass: Predicate<Widget> | (abstract new () => T)): T; /** @see WidgetModel.trackFocus */ setTrackFocus(trackFocus: boolean): void; protected _renderTrackFocus(): void; restoreFocus(): void; /** * Method invoked once a 'focusin' event is fired by this context's $container or one of its child controls. */ protected _onFocusIn(event: FocusEvent | JQuery.FocusInEvent): void; /** * Tries to set the focus on the widget. * * By default the focus is set on the container but this may vary from widget to widget. * * @param options.preventScroll prevents scrolling to new focused element (defaults to false) * @returns true if the element could be focused, false if not */ focus(options?: { preventScroll?: boolean; }): boolean; /** * Calls {@link focus()} and prevents the default behavior of the event if the focusing was successful. */ focusAndPreventDefault(event: JQuery.Event): boolean; /** * @returns whether the widget is the currently active element */ isFocused(): boolean; /** * @param checkTabbable if true, the widget has to be tabbable, not only focusable. Default is true. * @returns true if the element is focusable (and tabbable, unless checkTabbable is set to false), false if not. */ isFocusable(checkTabbable?: boolean): boolean; /** * This method returns the {@link HTMLElement} to be used when {@link focus} is called. * It can be overridden, in case the widget needs to return something other than `this.$container[0]`. */ getFocusableElement(): HTMLElement | JQuery; protected _installScrollbars(options?: ScrollbarInstallOptions): void; protected _uninstallScrollbars(): void; protected _onScroll(event: JQuery.ScrollEvent): void; /** @see WidgetModel.scrollTop */ setScrollTop(scrollTop: number): void; protected _setScrollTop(scrollTop: number): void; /** @internal */ _renderScrollTop(): void; /** @see WidgetModel.scrollLeft */ setScrollLeft(scrollLeft: number): void; protected _setScrollLeft(scrollLeft: number): void; protected _renderScrollLeft(): void; /** * Returns the jQuery element which is supposed to be scrollable. This element will be used by the scroll functions like {@link _installScrollbars}, {@link setScrollTop}, {@link setScrollLeft}, {@link scrollToBottom} etc. * The element won't be used unless {@link _installScrollbars} is called. * If the widget is mainly a wrapper for a scrollable widget and does not have a scrollable element by itself, you can use @{link #getDelegateScrollable} instead. */ get$Scrollable(): JQuery; hasScrollShadow(position: string): boolean; /** * If the widget is mainly a wrapper for another widget, it is often the case that the other widget is scrollable and not the wrapper. * In that case implement this method and return the other widget so that the calls to the scroll functions can be delegated. */ getDelegateScrollable(): Widget; scrollToTop(options?: ScrollOptions): void; scrollToBottom(options?: ScrollOptions): void; /** * Brings the widget into view by scrolling the first scrollable parent. * @param options * an optional options object. Shorthand version: If a string is passed instead * of an object, the value is automatically converted to the option {@link ScrollToOptions.align}. */ reveal(options?: ScrollToOptions | string): void; /** * Visits every descendant of this widget in pre-order (top-down). * This widget itself is not visited! Only child widgets are visited recursively. * * The children with a different parent are excluded. * This makes sure the child is not visited twice if the owner and the parent are not the same * (in that case the widget would be in the children list of the owner and of the parent). * * In order to abort visiting, the visitor can return true or {@link TreeVisitResult.TERMINATE}. * * @returns true if the visitor aborted the visiting, false if the visiting completed without aborting */ visitChildren(visitor: TreeVisitor<Widget>): boolean | TreeVisitResult; /** * Visits this widget and every descendant of this widget in pre-order (top-down). * * Uses {@link visitChildren} to visit the children. */ visit(visitor: TreeVisitor<Widget>, options?: { visitSelf?: boolean; }): TreeVisitResult; /** * @returns Whether or not the widget is rendered (or rendering) and the DOM $container isAttached() */ isAttachedAndRendered(): boolean; static cssClassAsArray(cssClass: string): string[]; } export type DisabledStyle = EnumObject<typeof Widget.DisabledStyle>; export type GlassPaneTarget = JQuery | HTMLElement | DeferredGlassPaneTarget; export type GlassPaneContribution = (widget: Widget) => GlassPaneTarget | GlassPaneTarget[]; export type TreeVisitor<T> = (element: T) => boolean | TreeVisitResult | void; export interface CloneOptions { /** An array of all properties to be delegated from the original to the clone when changed on the original widget. Default is []. */ delegatePropertiesToClone?: string[]; /** An array of all properties to be excluded from delegating from the original to the clone in any cases. Default is []. */ excludePropertiesToClone?: string[]; /** True to delegate all property changes from the original to the clone. Default is false. */ delegateAllPropertiesToClone?: boolean; /** An array of all properties to be delegated from the clone to the original when changed on the clone widget. Default is []. */ delegatePropertiesToOriginal?: string[]; /** An array of all properties to be excluded from delegating from the clone to the original in any cases. Default is []. */ excludePropertiesToOriginal?: string[]; /** An array of all events to be delegated from the clone to the original when fired on the clone widget. Default is []. */ delegateEventsToOriginal?: string[]; /** True to delegate all property changes from the clone to the original. Default is false. */ delegateAllPropertiesToOriginal?: boolean; } export interface EventDelegatorForCloning { clone: Widget; originalToClone: EventDelegator; cloneToOriginal: EventDelegator; } export type WidgetMap = { [type: string]: Widget; }; export type WidgetMapOf<T> = T extends { widgetMap: infer TMap; } ? TMap : object; export type WidgetPropertyDecoration = 'widget' | 'clone' | 'preserveOnPropertyChange' | PropertyDecoration; //# sourceMappingURL=Widget.d.ts.map