diff --git a/packages/core/ui/core/view-base/index.d.ts b/packages/core/ui/core/view-base/index.d.ts deleted file mode 100644 index 2276dfb93..000000000 --- a/packages/core/ui/core/view-base/index.d.ts +++ /dev/null @@ -1,570 +0,0 @@ -import { Property, CssProperty, CssAnimationProperty, InheritedProperty } from '../properties'; -import { BindingOptions } from '../bindable'; -import { Observable } from '../../../data/observable'; -import { Style } from '../../styling/style'; -import { CoreTypes } from '../../../core-types'; -import { Page } from '../../page'; - -import { Order, FlexGrow, FlexShrink, FlexWrapBefore, AlignSelf } from '../../layouts/flexbox-layout'; -import { Length } from '../../styling/style-properties'; -import { DOMNode } from '../../../debugger/dom-node'; -import type { ModalTransition } from '../../transition/modal-transition'; - -/** - * Iterates through all child views (via visual tree) and executes a function. - * @param view - Starting view (parent container). - * @param callback - A function to execute on every child. If function returns false it breaks the iteration. - */ -export function eachDescendant(view: ViewBase, callback: (child: ViewBase) => boolean); - -/** - * Gets an ancestor from a given type. - * @param view - Starting view (child view). - * @param criterion - The type of ancestor view we are looking for. Could be a string containing a class name or an actual type. - * Returns an instance of a view (if found), otherwise undefined. - */ -export function getAncestor(view: ViewBase, criterion: string | Function): ViewBase; - -export function isEventOrGesture(name: string, view: ViewBase): boolean; - -/** - * Gets a child view by id. - * @param view - The parent (container) view of the view to look for. - * @param id - The id of the view to look for. - * Returns an instance of a view (if found), otherwise undefined. - */ -export function getViewById(view: ViewBase, id: string): ViewBase; - -/** - * Gets a child view by domId. - * @param view - The parent (container) view of the view to look for. - * @param domId - The id of the view to look for. - * Returns an instance of a view (if found), otherwise undefined. - */ -export function getViewByDomId(view: ViewBase, domId: number): ViewBase; - -/** - * Gets a child view by selector. - * @param view - The parent (container) view of the view to look for. - * @param selector - The selector of the view to look for. - * Returns an instance of a view (if found), otherwise undefined. - */ -export function querySelectorAll(view: ViewBase, selector: string): Array; - -export interface ModalTransitionType { - name?: string; - instance?: ModalTransition; - duration?: number; - curve?: any; -} - -export interface ShowModalOptions { - /** - * Any context you want to pass to the modally shown view. This same context will be available in the arguments of the shownModally event handler. - */ - context: any; - - /** - * A function that will be called when the view is closed. Any arguments provided when calling ShownModallyData.closeCallback will be available here. - */ - closeCallback: Function; - - /** - * An optional parameter specifying whether to show the modal view in full-screen mode. - */ - fullscreen?: boolean; - - /** - * An optional parameter specifying whether to show the modal view with animation. - */ - animated?: boolean; - - /** - * An optional parameter specifying whether to stretch the modal view when not in full-screen mode. - */ - stretched?: boolean; - - /** - * An optional custom transition effect - */ - transition?: ModalTransition; - - /** - * An optional parameter that specify options specific to iOS as an object. - */ - ios?: { - /** - * The UIModalPresentationStyle to be used when showing the dialog in iOS . - */ - presentationStyle?: any /* UIModalPresentationStyle */; - /** - * width of the popup dialog - */ - width?: number; - /** - * height of the popup dialog - */ - height?: number; - }; - android?: { - /** - * @deprecated Use ShowModalOptions.cancelable instead. - * An optional parameter specifying whether the modal view can be dismissed when not in full-screen mode. - */ - cancelable?: boolean; - /** - * An optional parameter specifying the windowSoftInputMode of the dialog window - * For possible values see https://developer.android.com/reference/android/view/WindowManager.LayoutParams#softInputMode - */ - windowSoftInputMode?: number; - }; - /** - * An optional parameter specifying whether the modal view can be dismissed when not in full-screen mode. - */ - cancelable?: boolean; -} - -export abstract class ViewBase extends Observable { - // Dynamic properties. - left: CoreTypes.LengthType; - top: CoreTypes.LengthType; - effectiveLeft: number; - effectiveTop: number; - dock: 'left' | 'top' | 'right' | 'bottom'; - row: number; - col: number; - /** - * Setting `column` property is the same as `col` - */ - column: number; - rowSpan: number; - colSpan: number; - /** - * Setting `columnSpan` property is the same as `colSpan` - */ - columnSpan: number; - domNode: DOMNode; - - order: Order; - flexGrow: FlexGrow; - flexShrink: FlexShrink; - flexWrapBefore: FlexWrapBefore; - alignSelf: AlignSelf; - - /** - * @private - * Module name when the view is a module root. Otherwise, it is undefined. - */ - _moduleName?: string; - - //@private - /** - * @private - */ - _oldLeft: number; - /** - * @private - */ - _oldTop: number; - /** - * @private - */ - _oldRight: number; - /** - * @private - */ - _oldBottom: number; - /** - * @private - */ - _defaultPaddingTop: number; - /** - * @private - */ - _defaultPaddingRight: number; - /** - * @private - */ - _defaultPaddingBottom: number; - /** - * @private - */ - _defaultPaddingLeft: number; - - /** - * A property bag holding suspended native updates. - * Native setters that had to execute while there was no native view, - * or the view was detached from the visual tree etc. will accumulate in this object, - * and will be applied when all prerequisites are met. - * @private - */ - _suspendedUpdates: { - [propertyName: string]: Property | CssProperty | CssAnimationProperty; - }; - //@endprivate - - /** - * Shows the View contained in moduleName as a modal view. - * @param moduleName - The name of the module to load starting from the application root. - * @param modalOptions - A ShowModalOptions instance - */ - showModal(moduleName: string, modalOptions?: ShowModalOptions): ViewBase; - - /** - * Shows the view passed as parameter as a modal view. - * @param view - View instance to be shown modally. - * @param modalOptions - A ShowModalOptions instance - */ - showModal(view: ViewBase, modalOptions?: ShowModalOptions): ViewBase; - - /** - * Closes the current modal view that this page is showing. - * @param context - Any context you want to pass back to the host when closing the modal view. - */ - closeModal(context?: any): void; - - public effectiveMinWidth: number; - public effectiveMinHeight: number; - public effectiveWidth: number; - public effectiveHeight: number; - public effectiveMarginTop: number; - public effectiveMarginRight: number; - public effectiveMarginBottom: number; - public effectiveMarginLeft: number; - public effectivePaddingTop: number; - public effectivePaddingRight: number; - public effectivePaddingBottom: number; - public effectivePaddingLeft: number; - public effectiveBorderTopWidth: number; - public effectiveBorderRightWidth: number; - public effectiveBorderBottomWidth: number; - public effectiveBorderLeftWidth: number; - - /** - * String value used when hooking to loaded event. - */ - public static loadedEvent: string; - - /** - * String value used when hooking to unloaded event. - */ - public static unloadedEvent: string; - - /** - * String value used when hooking to creation event - */ - public static createdEvent: string; - - /** - * String value used when hooking to disposeNativeView event - */ - public static disposeNativeViewEvent: string; - - public ios: any; - public android: any; - - /** - * returns the native UIViewController. - */ - public viewController: any; - - /** - * read-only. If you want to set out-of-band the nativeView use the setNativeView method. - */ - public nativeViewProtected: any; - public nativeView: any; - public bindingContext: any; - - /** - * Gets or sets if the view is reusable. - * Reusable views are not automatically destroyed when removed from the View tree. - */ - public reusable: boolean; - - /** - * Gets the name of the constructor function for this instance. E.g. for a Button class this will return "Button". - */ - public typeName: string; - - /** - * Gets the parent view. This property is read-only. - */ - public readonly parent: ViewBase; - - /** - * Gets the template parent or the native parent. Sets the template parent. - */ - public parentNode: ViewBase; - - /** - * Gets or sets the id for this view. - */ - public id: string; - - /** - * Gets or sets the CSS class name for this view. - */ - public className: string; - - /** - * Gets or sets the shared transition tag for animated view transitions - */ - public sharedTransitionTag: string; - - /** - * Gets owner page. This is a read-only property. - */ - public readonly page: Page; - - /** - * Gets the style object associated to this view. - */ - public readonly style: Style; - - /** - * Returns true if visibility is set to 'collapse'. - * Readonly property - */ - public isCollapsed: boolean; - public readonly isLoaded: boolean; - - /** - * Returns the child view with the specified id. - */ - public getViewById(id: string): T; - - /** - * Returns the child view with the specified domId. - */ - public getViewByDomId(id: number): T; - - /** - * Load view. - * @param view to load. - */ - public loadView(view: ViewBase): void; - - /** - * Unload view. - * @param view to unload. - */ - public unloadView(view: ViewBase): void; - - public onLoaded(): void; - public onUnloaded(): void; - public onResumeNativeUpdates(): void; - - public bind(options: BindingOptions, source?: Object): void; - public unbind(property: string): void; - - /** - * Invalidates the layout of the view and triggers a new layout pass. - */ - public requestLayout(): void; - - /** - * Iterates over children of type ViewBase. - * @param callback Called for each child of type ViewBase. Iteration stops if this method returns falsy value. - */ - public eachChild(callback: (child: ViewBase) => boolean): void; - - public _addView(view: ViewBase, atIndex?: number): void; - /** - * Method is intended to be overridden by inheritors and used as "protected" - */ - public _addViewCore(view: ViewBase, atIndex?: number): void; - - public _removeView(view: ViewBase): void; - /** - * Method is intended to be overridden by inheritors and used as "protected" - */ - public _removeViewCore(view: ViewBase): void; - public _parentChanged(oldParent: ViewBase): void; - /** - * Method is intended to be overridden by inheritors and used as "protected" - */ - public _dialogClosed(): void; - /** - * Method is intended to be overridden by inheritors and used as "protected" - */ - public _onRootViewReset(): void; - - _domId: number; - - _cssState: any /* "ui/styling/style-scope" */; - /** - * @private - * Notifies each child's css state for change, recursively. - * Either the style scope, className or id properties were changed. - */ - _onCssStateChange(): void; - - public cssClasses: Set; - public cssPseudoClasses: Set; - - public _goToVisualState(state: string): void; - - public setInlineStyle(style: string): void; - - _context: any /* android.content.Context */; - - /** - * Setups the UI for ViewBase and all its children recursively. - * This method should *not* be overridden by derived views. - */ - _setupUI(context: any /* android.content.Context */, atIndex?: number): void; - - /** - * Tears down the UI for ViewBase and all its children recursively. - * This method should *not* be overridden by derived views. - */ - _tearDownUI(force?: boolean): void; - - /** - * Tears down the UI of a reusable node by making it no longer reusable. - * @see _tearDownUI - * @param forceDestroyChildren Force destroy the children (even if they are reusable) - */ - destroyNode(forceDestroyChildren?: boolean): void; - - /** - * Creates a native view. - * Returns either android.view.View or UIView. - */ - createNativeView(): Object; - - /** - * Initializes properties/listeners of the native view. - */ - initNativeView(): void; - - /** - * Clean up references to the native view. - */ - disposeNativeView(): void; - - /** - * Resets properties/listeners set to the native view. - */ - resetNativeView(): void; - - /** - * Set the nativeView field performing extra checks and updates to the native properties on the new view. - * Use in cases where the createNativeView is not suitable. - * As an example use in item controls where the native parent view will create the native views for child items. - */ - setNativeView(view: any): void; - - _isAddedToNativeVisualTree: boolean; - - /** - * Performs the core logic of adding a child view to the native visual tree. Returns true if the view's native representation has been successfully added, false otherwise. - */ - _addViewToNativeVisualTree(view: ViewBase, atIndex?: number): boolean; - _removeViewFromNativeVisualTree(view: ViewBase): void; - _childIndexToNativeChildIndex(index?: number): number; - - /** - * @protected - * @unstable - * A widget can call this method to add a matching css pseudo class. - */ - public addPseudoClass(name: string): void; - - /** - * @protected - * @unstable - * A widget can call this method to discard matching css pseudo class. - */ - public deletePseudoClass(name: string): void; - - /** - * @unstable - * Ensures a dom-node for this view. - */ - public ensureDomNode(); - - public recycleNativeView: 'always' | 'never' | 'auto'; - - /** - * @private - */ - public _isPaddingRelative: boolean; - - /** - * @private - */ - public _ignoreFlexMinWidthHeightReset: boolean; - - public _styleScope: any; - - /** - * @private - */ - public _automaticallyAdjustsScrollViewInsets: boolean; - /** - * @private - */ - _isStyleScopeHost: boolean; - - /** - * @private - */ - public _layoutParent(): void; - - /** - * Determines the depth of suspended updates. - * When the value is 0 the current property updates are not batched nor scoped and must be immediately applied. - * If the value is 1 or greater, the current updates are batched and does not have to provide immediate update. - * Do not set this field, the _batchUpdate method is responsible to keep the count up to date, - * as well as adding/rmoving the view to/from the visual tree. - */ - public _suspendNativeUpdatesCount: number; - - /** - * Allow multiple updates to be performed on the instance at once. - */ - public _batchUpdate(callback: () => T): T; - /** - * @private - */ - _setupAsRootView(context: any): void; - - /** - * When returning true the callLoaded method will be run in setTimeout - * Method is intended to be overridden by inheritors and used as "protected" - */ - _shouldDelayLayout(): boolean; - - /** - * @private - */ - _inheritStyleScope(styleScope: any /* StyleScope */): void; - - /** - * @private - */ - callLoaded(): void; - - /** - * @private - */ - callUnloaded(): void; - //@endprivate -} - -export class Binding { - constructor(target: ViewBase, options: BindingOptions); - public bind(source: Object): void; - public unbind(); -} - -export const idProperty: Property; -export const classNameProperty: Property; -export const bindingContextProperty: InheritedProperty; - -/** - * Converts string into boolean value. - * Throws error if value is not 'true' or 'false'. - */ -export function booleanConverter(v: string): boolean; diff --git a/packages/core/ui/core/view-base/index.ts b/packages/core/ui/core/view-base/index.ts index eaf5df936..32236ff13 100644 --- a/packages/core/ui/core/view-base/index.ts +++ b/packages/core/ui/core/view-base/index.ts @@ -112,6 +112,12 @@ export interface ShowModalOptions { cancelable?: boolean; } +/** + * Gets an ancestor from a given type. + * @param view - Starting view (child view). + * @param criterion - The type of ancestor view we are looking for. Could be a string containing a class name or an actual type. + * Returns an instance of a view (if found), otherwise undefined. + */ export function getAncestor(view: ViewBaseDefinition, criterion: string | { new () }): ViewBaseDefinition { let matcher: (view: ViewBaseDefinition) => boolean = null; if (typeof criterion === 'string') { @@ -129,6 +135,12 @@ export function getAncestor(view: ViewBaseDefinition, criterion: string | { new return null; } +/** + * Gets a child view by id. + * @param view - The parent (container) view of the view to look for. + * @param id - The id of the view to look for. + * Returns an instance of a view (if found), otherwise undefined. + */ export function getViewById(view: ViewBaseDefinition, id: string): ViewBaseDefinition { if (!view) { return undefined; @@ -155,6 +167,12 @@ export function getViewById(view: ViewBaseDefinition, id: string): ViewBaseDefin return retVal; } +/** + * Gets a child view by domId. + * @param view - The parent (container) view of the view to look for. + * @param domId - The id of the view to look for. + * Returns an instance of a view (if found), otherwise undefined. + */ export function getViewByDomId(view: ViewBaseDefinition, domId: number): ViewBaseDefinition { if (!view) { return undefined; @@ -182,6 +200,12 @@ export function getViewByDomId(view: ViewBaseDefinition, domId: number): ViewBas } // TODO: allow all selector types (just using attributes now) +/** + * Gets a child view by selector. + * @param view - The parent (container) view of the view to look for. + * @param selector - The selector of the view to look for. + * Returns an instance of a view (if found), otherwise undefined. + */ export function querySelectorAll(view: ViewBaseDefinition, selector: string): Array { if (!view) { return undefined; @@ -205,6 +229,11 @@ export function querySelectorAll(view: ViewBaseDefinition, selector: string): Ar return retVal; } +/** + * Iterates through all child views (via visual tree) and executes a function. + * @param view - Starting view (parent container). + * @param callback - A function to execute on every child. If function returns false it breaks the iteration. + */ export function eachDescendant(view: ViewBaseDefinition, callback: (child: ViewBaseDefinition) => boolean) { if (!callback || !view) { return; @@ -280,9 +309,21 @@ namespace SuspendType { } export abstract class ViewBase extends Observable implements ViewBaseDefinition { + /** + * String value used when hooking to loaded event. + */ public static loadedEvent = 'loaded'; + /** + * String value used when hooking to unloaded event. + */ public static unloadedEvent = 'unloaded'; + /** + * String value used when hooking to creation event + */ public static createdEvent = 'created'; + /** + * String value used when hooking to disposeNativeView event + */ public static disposeNativeViewEvent = 'disposeNativeView'; private _onLoadedCalled = false; @@ -299,24 +340,62 @@ export abstract class ViewBase extends Observable implements ViewBaseDefinition public domNode: dnm.DOMNode; public recycleNativeView: 'always' | 'never' | 'auto'; + /** + * returns the native UIViewController. + */ public viewController: any; public bindingContext: any; + /** + * read-only. If you want to set out-of-band the nativeView use the setNativeView method. + */ public nativeViewProtected: any; + /** + * Gets the parent view. This property is read-only. + */ public parent: ViewBase; - public isCollapsed; // Default(false) set in prototype + /** + * Returns true if visibility is set to 'collapse'. + * Default(false) set in prototype + * Readonly property + */ + public isCollapsed; + /** + * Gets or sets the id for this view. + */ public id: string; + /** + * Gets or sets the CSS class name for this view. + */ public className: string; + /** + * Gets or sets the shared transition tag for animated view transitions + */ public sharedTransitionTag: string; public _domId: number; - public _context: any; + public _context: any /* android.content.Context */; public _isAddedToNativeVisualTree: boolean; - public _cssState: ssm.CssState = new ssm.CssState(new WeakRef(this)); + /* "ui/styling/style-scope" */ public _cssState: ssm.CssState = new ssm.CssState(new WeakRef(this)); public _styleScope: ssm.StyleScope; + /** + * A property bag holding suspended native updates. + * Native setters that had to execute while there was no native view, + * or the view was detached from the visual tree etc. will accumulate in this object, + * and will be applied when all prerequisites are met. + * @private + */ public _suspendedUpdates: { [propertyName: string]: Property | CssProperty | CssAnimationProperty; }; + //@endprivate + /** + * Determines the depth of suspended updates. + * When the value is 0 the current property updates are not batched nor scoped and must be immediately applied. + * If the value is 1 or greater, the current updates are batched and does not have to provide immediate update. + * Do not set this field, the _batchUpdate method is responsible to keep the count up to date, + * as well as adding/rmoving the view to/from the visual tree. + */ public _suspendNativeUpdatesCount: number; public _isStyleScopeHost: boolean; public _automaticallyAdjustsScrollViewInsets: boolean; @@ -369,8 +448,16 @@ export abstract class ViewBase extends Observable implements ViewBaseDefinition public _defaultPaddingLeft: number; public _isPaddingRelative: boolean; + /** + * @private + * Module name when the view is a module root. Otherwise, it is undefined. + */ public _moduleName: string; + /** + * Gets or sets if the view is reusable. + * Reusable views are not automatically destroyed when removed from the View tree. + */ public reusable: boolean; constructor() { @@ -380,7 +467,10 @@ export abstract class ViewBase extends Observable implements ViewBaseDefinition this.notify({ eventName: ViewBase.createdEvent, type: this.constructor.name, object: this }); } - // Used in Angular. + // Used in Angular. TODO: remove from here + /** + * Gets the template parent or the native parent. Sets the template parent. + */ get parentNode() { return this._templateParent || this.parent; } @@ -397,10 +487,16 @@ export abstract class ViewBase extends Observable implements ViewBaseDefinition } // TODO: Use Type.prototype.typeName instead. + /** + * Gets the name of the constructor function for this instance. E.g. for a Button class this will return "Button". + */ get typeName(): string { return getClass(this); } + /** + * Gets the style object associated to this view. + */ get style(): Style { return this._style; } @@ -433,14 +529,23 @@ export abstract class ViewBase extends Observable implements ViewBaseDefinition this.className = v; } + /** + * Returns the child view with the specified id. + */ getViewById(id: string): T { return getViewById(this, id); } + /** + * Returns the child view with the specified domId. + */ getViewByDomId(domId: number): T { return getViewByDomId(this, domId); } + /** + * Gets owner page. This is a read-only property. + */ get page(): Page { if (this.parent) { return this.parent.page; @@ -449,6 +554,10 @@ export abstract class ViewBase extends Observable implements ViewBaseDefinition return null; } + /** + * @unstable + * Ensures a dom-node for this view. + */ public ensureDomNode() { if (!this.domNode) { ensuredomNodeModule(); @@ -531,6 +640,9 @@ export abstract class ViewBase extends Observable implements ViewBaseDefinition } } + /** + * Allow multiple updates to be performed on the instance at once. + */ public _batchUpdate(callback: () => T): T { try { this._suspendNativeUpdates(SuspendType.Incremental); @@ -602,6 +714,11 @@ export abstract class ViewBase extends Observable implements ViewBaseDefinition return allStates; } + /** + * @protected + * @unstable + * A widget can call this method to add a matching css pseudo class. + */ @profile public addPseudoClass(name: string): void { const allStates = this.getAllAliasedStates(name); @@ -613,6 +730,11 @@ export abstract class ViewBase extends Observable implements ViewBaseDefinition } } + /** + * @protected + * @unstable + * A widget can call this method to discard matching css pseudo class. + */ @profile public deletePseudoClass(name: string): void { const allStates = this.getAllAliasedStates(name); @@ -696,6 +818,9 @@ export abstract class ViewBase extends Observable implements ViewBaseDefinition } } + /** + * Invalidates the layout of the view and triggers a new layout pass. + */ @profile public requestLayout(): void { // Default implementation for non View instances (like TabViewItem). @@ -705,6 +830,10 @@ export abstract class ViewBase extends Observable implements ViewBaseDefinition } } + /** + * Iterates over children of type ViewBase. + * @param callback Called for each child of type ViewBase. Iteration stops if this method returns falsy value. + */ public eachChild(callback: (child: ViewBase) => boolean) { // } @@ -734,6 +863,9 @@ export abstract class ViewBase extends Observable implements ViewBaseDefinition } } + /** + * Method is intended to be overridden by inheritors and used as "protected" + */ public _addViewCore(view: ViewBase, atIndex?: number) { propagateInheritableProperties(this, view); view._inheritStyleScope(this._styleScope); @@ -748,16 +880,28 @@ export abstract class ViewBase extends Observable implements ViewBaseDefinition } } + /** + * Load view. + * @param view to load. + */ public loadView(view: ViewBase): void { if (view && !view.isLoaded) { view.callLoaded(); } } + /** + * When returning true the callLoaded method will be run in setTimeout + * Method is intended to be overridden by inheritors and used as "protected" + */ public _shouldDelayLayout(): boolean { return false; } + /** + * Unload view. + * @param view to unload. + */ public unloadView(view: ViewBase): void { if (view && view.isLoaded) { view.callUnloaded(); @@ -796,10 +940,17 @@ export abstract class ViewBase extends Observable implements ViewBaseDefinition } } + /** + * Creates a native view. + * Returns either android.view.View or UIView. + */ public createNativeView(): Object { return undefined; } + /** + * Clean up references to the native view. + */ public disposeNativeView() { this.notify({ eventName: ViewBase.disposeNativeViewEvent, @@ -807,10 +958,16 @@ export abstract class ViewBase extends Observable implements ViewBaseDefinition }); } + /** + * Initializes properties/listeners of the native view. + */ public initNativeView(): void { // } + /** + * Resets properties/listeners set to the native view. + */ public resetNativeView(): void { // } @@ -838,8 +995,12 @@ export abstract class ViewBase extends Observable implements ViewBaseDefinition this._setupUI(context); } + /** + * Setups the UI for ViewBase and all its children recursively. + * This method should *not* be overridden by derived views. + */ @profile - public _setupUI(context: any, atIndex?: number, parentIsLoaded?: boolean): void { + public _setupUI(context: any /* android.content.Context */, atIndex?: number, parentIsLoaded?: boolean): void { if (this._context === context) { // this check is unnecessary as this function should never be called when this._context === context as it means the view was somehow detached, // which is only possible by setting reusable = true. Adding it either way for feature flag safety @@ -926,6 +1087,11 @@ export abstract class ViewBase extends Observable implements ViewBaseDefinition }); } + /** + * Set the nativeView field performing extra checks and updates to the native properties on the new view. + * Use in cases where the createNativeView is not suitable. + * As an example use in item controls where the native parent view will create the native views for child items. + */ setNativeView(value: any): void { if (this.__nativeView === value) { return; @@ -944,12 +1110,21 @@ export abstract class ViewBase extends Observable implements ViewBaseDefinition } } + /** + * Tears down the UI of a reusable node by making it no longer reusable. + * @see _tearDownUI + * @param forceDestroyChildren Force destroy the children (even if they are reusable) + */ public destroyNode(forceDestroyChildren?: boolean): void { this.reusable = false; this.callUnloaded(); this._tearDownUI(forceDestroyChildren); } + /** + * Tears down the UI for ViewBase and all its children recursively. + * This method should *not* be overridden by derived views. + */ @profile public _tearDownUI(force?: boolean): void { // No context means we are already teared down. @@ -1014,6 +1189,7 @@ export abstract class ViewBase extends Observable implements ViewBaseDefinition } /** + * Performs the core logic of adding a child view to the native visual tree. Returns true if the view's native representation has been successfully added, false otherwise. * Method is intended to be overridden by inheritors and used as "protected". */ public _addViewToNativeVisualTree(view: ViewBase, atIndex?: number): boolean { @@ -1107,6 +1283,11 @@ export abstract class ViewBase extends Observable implements ViewBaseDefinition return str; } + /** + * @private + * Notifies each child's css state for change, recursively. + * Either the style scope, className or id properties were changed. + */ _onCssStateChange(): void { this._cssState.onChange(); eachDescendant(this, (child: ViewBase) => { @@ -1134,12 +1315,29 @@ export abstract class ViewBase extends Observable implements ViewBaseDefinition } } - public showModal(...args): ViewBase { + /** + * Shows the view passed as parameter as a modal view. + * @param view - View instance to be shown modally. + * @param modalOptions - A ShowModalOptions instance + */ + public showModal(view: ViewBase, modalOptions?: ShowModalOptions): ViewBase; + /** + * Shows the View contained in moduleName as a modal view. + * @param moduleName - The name of the module to load starting from the application root. + * @param modalOptions - A ShowModalOptions instance + */ + public showModal(moduleName: string, modalOptions?: ShowModalOptions): ViewBase; + + public showModal(moduleOrView: string | ViewBase, modalOptions?: ShowModalOptions): ViewBase { const parent = this.parent; - return parent && parent.showModal(...args); + return parent && parent.showModal(moduleOrView, modalOptions); } + /** + * Closes the current modal view that this page is showing. + * @param context - Any context you want to pass back to the host when closing the modal view. + */ public closeModal(...args): void { const parent = this.parent; if (parent) { @@ -1147,6 +1345,9 @@ export abstract class ViewBase extends Observable implements ViewBaseDefinition } } + /** + * Method is intended to be overridden by inheritors and used as "protected" + */ public _dialogClosed(): void { eachDescendant(this, (child: ViewBase) => { child._dialogClosed(); @@ -1155,6 +1356,9 @@ export abstract class ViewBase extends Observable implements ViewBaseDefinition }); } + /** + * Method is intended to be overridden by inheritors and used as "protected" + */ public _onRootViewReset(): void { eachDescendant(this, (child: ViewBase) => { child._onRootViewReset();