diff --git a/packages/core/data/observable-array/index.ts b/packages/core/data/observable-array/index.ts index 03a5d7e18a..3834a047ed 100644 --- a/packages/core/data/observable-array/index.ts +++ b/packages/core/data/observable-array/index.ts @@ -424,12 +424,16 @@ export class ObservableArray extends Observable { export interface ObservableArray { /** - * A basic method signature to hook an event listener (shortcut alias to the addEventListener method). - * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change"). - * @param callback - Callback function which will be executed when event is raised. - * @param thisArg - An optional parameter which will be used as `this` context for callback execution. - */ - on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void; + * Adds a listener for the specified event name. + * + * @param eventName The name of the event. + * @param callback The event listener to add. Will be called when an event of + * the given name is raised. + * @param thisArg An optional parameter which, when set, will be bound as the + * `this` context when the callback is called. Falsy values will be not be + * bound. + */ + on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void; on(event: 'change', callback: (args: ChangedData) => void, thisArg?: any): void; } diff --git a/packages/core/data/observable/index.ts b/packages/core/data/observable/index.ts index f1d2d4a605..f587454d5f 100644 --- a/packages/core/data/observable/index.ts +++ b/packages/core/data/observable/index.ts @@ -150,27 +150,42 @@ export class Observable { } /** - * A basic method signature to hook an event listener (shortcut alias to the addEventListener method). - * @param eventName Name of the event to attach to. - * @param callback - Callback function which will be executed when event is raised. - * @param thisArg - An optional parameter which will be used as `this` context for callback execution. + * Adds a listener for the specified event name. + * + * @param eventName The name of the event. + * @param callback The event listener to add. Will be called when an event of + * the given name is raised. + * @param thisArg An optional parameter which, when set, will be bound as the + * `this` context when the callback is called. Falsy values will be not be + * bound. */ public on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void { this.addEventListener(eventName, callback, thisArg); } /** - * Adds one-time listener function for the event named `event`. - * @param eventName Name of the event to attach to. - * @param callback A function to be called when the specified event is raised. - * @param thisArg An optional parameter which when set will be used as "this" in callback method call. + * Adds a listener for the specified event name, which, once fired, will + * remove itself. + * + * @param eventName The name of the event. + * @param callback The event listener to add. Will be called when an event of + * the given name is raised. + * @param thisArg An optional parameter which, when set, will be bound as the + * `this` context when the callback is called. Falsy values will be not be + * bound. */ public once(eventName: string, callback: (data: EventData) => void, thisArg?: any): void { this.addEventListener(eventName, callback, thisArg, true); } /** - * Shortcut alias to the removeEventListener method. + * Removes the listener(s) for the specified event name. + * + * @param eventName The name of the event. + * @param callback An optional specific event listener to remove (if omitted, + * all event listeners by this name will be removed). + * @param thisArg An optional parameter which, when set, will be used to + * refine search of the correct event listener to be removed. */ public off(eventName: string, callback?: (data: EventData) => void, thisArg?: any): void { this.removeEventListener(eventName, callback, thisArg); diff --git a/packages/core/data/virtual-array/index.ts b/packages/core/data/virtual-array/index.ts index bf16e47287..30d62c4877 100644 --- a/packages/core/data/virtual-array/index.ts +++ b/packages/core/data/virtual-array/index.ts @@ -183,12 +183,16 @@ export class VirtualArray extends Observable { } export interface VirtualArray { /** - * A basic method signature to hook an event listener (shortcut alias to the addEventListener method). - * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change"). - * @param callback - Callback function which will be executed when event is raised. - * @param thisArg - An optional parameter which will be used as `this` context for callback execution. + * Adds a listener for the specified event name. + * + * @param eventName The name of the event. + * @param callback The event listener to add. Will be called when an event of + * the given name is raised. + * @param thisArg An optional parameter which, when set, will be bound as the + * `this` context when the callback is called. Falsy values will be not be + * bound. */ - on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void; + on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void; /** * Raised when still not loaded items are requested. */ diff --git a/packages/core/ui/action-bar/index.d.ts b/packages/core/ui/action-bar/index.d.ts index f57898b4a7..cda49c488f 100644 --- a/packages/core/ui/action-bar/index.d.ts +++ b/packages/core/ui/action-bar/index.d.ts @@ -129,12 +129,16 @@ export class ActionItem extends ViewBase { actionBar: ActionBar; /** - * A basic method signature to hook an event listener (shortcut alias to the addEventListener method). - * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change"). - * @param callback - Callback function which will be executed when event is raised. - * @param thisArg - An optional parameter which will be used as `this` context for callback execution. - */ - on(eventNames: string, callback: (data: EventData) => void): void; + * Adds a listener for the specified event name. + * + * @param eventName The name of the event. + * @param callback The event listener to add. Will be called when an event of + * the given name is raised. + * @param thisArg An optional parameter which, when set, will be bound as the + * `this` context when the callback is called. Falsy values will be not be + * bound. + */ + on(eventName: string, callback: (data: EventData) => void): void; /** * Raised when a tap event occurs. diff --git a/packages/core/ui/button/index.d.ts b/packages/core/ui/button/index.d.ts index 759307bf69..386bf67dfb 100644 --- a/packages/core/ui/button/index.d.ts +++ b/packages/core/ui/button/index.d.ts @@ -26,12 +26,16 @@ export class Button extends TextBase { textWrap: boolean; /** - * A basic method signature to hook an event listener (shortcut alias to the addEventListener method). - * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change"). - * @param callback - Callback function which will be executed when event is raised. - * @param thisArg - An optional parameter which will be used as `this` context for callback execution. + * Adds a listener for the specified event name. + * + * @param eventName The name of the event. + * @param callback The event listener to add. Will be called when an event of + * the given name is raised. + * @param thisArg An optional parameter which, when set, will be bound as the + * `this` context when the callback is called. Falsy values will be not be + * bound. */ - on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void; + on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void; /** * Raised when a tap event occurs. diff --git a/packages/core/ui/core/view/index.d.ts b/packages/core/ui/core/view/index.d.ts index be75016f7f..6294fba2cc 100644 --- a/packages/core/ui/core/view/index.d.ts +++ b/packages/core/ui/core/view/index.d.ts @@ -590,20 +590,27 @@ export abstract class View extends ViewCommon { public getGestureObservers(type: GestureTypes): Array | undefined; /** - * Removes listener(s) for the specified event name. - * @param eventNames Comma delimited names of the events or gesture types the specified listener is associated with. - * @param callback An optional parameter pointing to a specific listener. If not defined, all listeners for the event names will be removed. - * @param thisArg An optional parameter which when set will be used to refine search of the correct callback which will be removed as event listener. + * Removes the listener(s) for the specified event name. + * + * @param eventName The name of the event. + * @param callback An optional specific event listener to remove (if omitted, + * all event listeners by this name will be removed). + * @param thisArg An optional parameter which, when set, will be used to + * refine search of the correct event listener to be removed. */ - off(eventNames: string, callback?: (args: EventData) => void, thisArg?: any); + off(eventName: string, callback?: (args: EventData) => void, thisArg?: any); /** - * A basic method signature to hook an event listener (shortcut alias to the addEventListener method). - * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change") or you can use gesture types. - * @param callback - Callback function which will be executed when event is raised. - * @param thisArg - An optional parameter which will be used as `this` context for callback execution. - */ - on(eventNames: string, callback: (args: EventData) => void, thisArg?: any); + * Adds a listener for the specified event name. + * + * @param eventName The name of the event. + * @param callback The event listener to add. Will be called when an event of + * the given name is raised. + * @param thisArg An optional parameter which, when set, will be bound as the + * `this` context when the callback is called. Falsy values will be not be + * bound. + */ + on(eventName: string, callback: (args: EventData) => void, thisArg?: any); /** * Raised when a loaded event occurs. diff --git a/packages/core/ui/frame/index.d.ts b/packages/core/ui/frame/index.d.ts index fb5b602a24..521154806d 100644 --- a/packages/core/ui/frame/index.d.ts +++ b/packages/core/ui/frame/index.d.ts @@ -225,12 +225,16 @@ export class Frame extends FrameBase { //@endprivate /** - * A basic method signature to hook an event listener (shortcut alias to the addEventListener method). - * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change"). - * @param callback - Callback function which will be executed when event is raised. - * @param thisArg - An optional parameter which will be used as `this` context for callback execution. - */ - on(eventNames: string, callback: (args: EventData) => void, thisArg?: any): void; + * Adds a listener for the specified event name. + * + * @param eventName The name of the event. + * @param callback The event listener to add. Will be called when an event of + * the given name is raised. + * @param thisArg An optional parameter which, when set, will be bound as the + * `this` context when the callback is called. Falsy values will be not be + * bound. + */ + on(eventName: string, callback: (args: EventData) => void, thisArg?: any): void; /** * Raised when navigation to the page has started. diff --git a/packages/core/ui/image-cache/index.d.ts b/packages/core/ui/image-cache/index.d.ts index 774b5b11b7..7b4ac52f3f 100644 --- a/packages/core/ui/image-cache/index.d.ts +++ b/packages/core/ui/image-cache/index.d.ts @@ -80,12 +80,16 @@ export class Cache extends Observable { clear(): void; /** - * A basic method signature to hook an event listener (shortcut alias to the addEventListener method). - * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change"). - * @param callback - Callback function which will be executed when event is raised. - * @param thisArg - An optional parameter which will be used as `this` context for callback execution. - */ - on(eventNames: string, callback: (args: EventData) => void, thisArg?: any): void; + * Adds a listener for the specified event name. + * + * @param eventName The name of the event. + * @param callback The event listener to add. Will be called when an event of + * the given name is raised. + * @param thisArg An optional parameter which, when set, will be bound as the + * `this` context when the callback is called. Falsy values will be not be + * bound. + */ + on(eventName: string, callback: (args: EventData) => void, thisArg?: any): void; /** * Raised when the image has been downloaded. diff --git a/packages/core/ui/list-view/index.d.ts b/packages/core/ui/list-view/index.d.ts index 6b9e96178d..3c823edc33 100644 --- a/packages/core/ui/list-view/index.d.ts +++ b/packages/core/ui/list-view/index.d.ts @@ -103,12 +103,16 @@ export class ListView extends View { isItemAtIndexVisible(index: number): boolean; /** - * A basic method signature to hook an event listener (shortcut alias to the addEventListener method). - * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change"). - * @param callback - Callback function which will be executed when event is raised. - * @param thisArg - An optional parameter which will be used as `this` context for callback execution. - */ - on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void; + * Adds a listener for the specified event name. + * + * @param eventName The name of the event. + * @param callback The event listener to add. Will be called when an event of + * the given name is raised. + * @param thisArg An optional parameter which, when set, will be bound as the + * `this` context when the callback is called. Falsy values will be not be + * bound. + */ + on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void; /** * Raised when a View for the data at the specified index should be created. diff --git a/packages/core/ui/page/index.d.ts b/packages/core/ui/page/index.d.ts index 024cebd8b0..42178d4260 100644 --- a/packages/core/ui/page/index.d.ts +++ b/packages/core/ui/page/index.d.ts @@ -111,12 +111,16 @@ export declare class Page extends PageBase { public accessibilityAnnouncePageEnabled: boolean; /** - * A basic method signature to hook an event listener (shortcut alias to the addEventListener method). - * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change"). - * @param callback - Callback function which will be executed when event is raised. - * @param thisArg - An optional parameter which will be used as `this` context for callback execution. - */ - public on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void; + * Adds a listener for the specified event name. + * + * @param eventName The name of the event. + * @param callback The event listener to add. Will be called when an event of + * the given name is raised. + * @param thisArg An optional parameter which, when set, will be bound as the + * `this` context when the callback is called. Falsy values will be not be + * bound. + */ + public on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void; /** * Raised when navigation to the page has started. diff --git a/packages/core/ui/placeholder/index.d.ts b/packages/core/ui/placeholder/index.d.ts index 177fa46bba..cac9710cbd 100644 --- a/packages/core/ui/placeholder/index.d.ts +++ b/packages/core/ui/placeholder/index.d.ts @@ -13,12 +13,16 @@ export class Placeholder extends View { public static creatingViewEvent: string; /** - * A basic method signature to hook an event listener (shortcut alias to the addEventListener method). - * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change"). - * @param callback - Callback function which will be executed when event is raised. - * @param thisArg - An optional parameter which will be used as `this` context for callback execution. + * Adds a listener for the specified event name. + * + * @param eventName The name of the event. + * @param callback The event listener to add. Will be called when an event of + * the given name is raised. + * @param thisArg An optional parameter which, when set, will be bound as the + * `this` context when the callback is called. Falsy values will be not be + * bound. */ - on(eventNames: string, callback: (args: EventData) => void, thisArg?: any): void; + on(eventName: string, callback: (args: EventData) => void, thisArg?: any): void; /** * Raised when a creatingView event occurs. diff --git a/packages/core/ui/scroll-view/index.d.ts b/packages/core/ui/scroll-view/index.d.ts index a6176a3813..f3d341bf82 100644 --- a/packages/core/ui/scroll-view/index.d.ts +++ b/packages/core/ui/scroll-view/index.d.ts @@ -62,12 +62,16 @@ export class ScrollView extends ContentView { orientation: CoreTypes.OrientationType; /** - * A basic method signature to hook an event listener (shortcut alias to the addEventListener method). - * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change"). - * @param callback - Callback function which will be executed when event is raised. - * @param thisArg - An optional parameter which will be used as `this` context for callback execution. + * Adds a listener for the specified event name. + * + * @param eventName The name of the event. + * @param callback The event listener to add. Will be called when an event of + * the given name is raised. + * @param thisArg An optional parameter which, when set, will be bound as the + * `this` context when the callback is called. Falsy values will be not be + * bound. */ - on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void; + on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void; /** * Raised when a scroll event occurs. diff --git a/packages/core/ui/search-bar/index.d.ts b/packages/core/ui/search-bar/index.d.ts index 87dc902e4f..f3b1d14046 100644 --- a/packages/core/ui/search-bar/index.d.ts +++ b/packages/core/ui/search-bar/index.d.ts @@ -48,12 +48,16 @@ export class SearchBar extends View { textFieldHintColor: Color; /** - * A basic method signature to hook an event listener (shortcut alias to the addEventListener method). - * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change"). - * @param callback - Callback function which will be executed when event is raised. - * @param thisArg - An optional parameter which will be used as `this` context for callback execution. + * Adds a listener for the specified event name. + * + * @param eventName The name of the event. + * @param callback The event listener to add. Will be called when an event of + * the given name is raised. + * @param thisArg An optional parameter which, when set, will be bound as the + * `this` context when the callback is called. Falsy values will be not be + * bound. */ - on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void; + on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void; /** * Raised when a search bar search is submitted. diff --git a/packages/core/ui/segmented-bar/index.d.ts b/packages/core/ui/segmented-bar/index.d.ts index 9da03da9a4..1b59cf397b 100644 --- a/packages/core/ui/segmented-bar/index.d.ts +++ b/packages/core/ui/segmented-bar/index.d.ts @@ -60,12 +60,16 @@ export class SegmentedBar extends View implements AddChildFromBuilder, AddArrayF public static selectedIndexChangedEvent: string; /** - * A basic method signature to hook an event listener (shortcut alias to the addEventListener method). - * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change"). - * @param callback - Callback function which will be executed when event is raised. - * @param thisArg - An optional parameter which will be used as `this` context for callback execution. + * Adds a listener for the specified event name. + * + * @param eventName The name of the event. + * @param callback The event listener to add. Will be called when an event of + * the given name is raised. + * @param thisArg An optional parameter which, when set, will be bound as the + * `this` context when the callback is called. Falsy values will be not be + * bound. */ - on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void; + on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void; /** * Raised when the selected index changes. diff --git a/packages/core/ui/tab-view/index.d.ts b/packages/core/ui/tab-view/index.d.ts index 47fa963031..d3456005ae 100644 --- a/packages/core/ui/tab-view/index.d.ts +++ b/packages/core/ui/tab-view/index.d.ts @@ -145,12 +145,16 @@ export class TabView extends View { public static selectedIndexChangedEvent: string; /** - * A basic method signature to hook an event listener (shortcut alias to the addEventListener method). - * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change"). - * @param callback - Callback function which will be executed when event is raised. - * @param thisArg - An optional parameter which will be used as `this` context for callback execution. - */ - on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void; + * Adds a listener for the specified event name. + * + * @param eventName The name of the event. + * @param callback The event listener to add. Will be called when an event of + * the given name is raised. + * @param thisArg An optional parameter which, when set, will be bound as the + * `this` context when the callback is called. Falsy values will be not be + * bound. + */ + on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void; /** * Raised when the selected index changes. diff --git a/packages/core/ui/web-view/index.d.ts b/packages/core/ui/web-view/index.d.ts index ef3a3a8106..dc2b37dadb 100644 --- a/packages/core/ui/web-view/index.d.ts +++ b/packages/core/ui/web-view/index.d.ts @@ -87,12 +87,16 @@ export class WebView extends View { reload(); /** - * A basic method signature to hook an event listener (shortcut alias to the addEventListener method). - * @param eventNames - String corresponding to events (e.g. "propertyChange"). Optionally could be used more events separated by `,` (e.g. "propertyChange", "change"). - * @param callback - Callback function which will be executed when event is raised. - * @param thisArg - An optional parameter which will be used as `this` context for callback execution. - */ - on(eventNames: string, callback: (data: EventData) => void, thisArg?: any): void; + * Adds a listener for the specified event name. + * + * @param eventName The name of the event. + * @param callback The event listener to add. Will be called when an event of + * the given name is raised. + * @param thisArg An optional parameter which, when set, will be bound as the + * `this` context when the callback is called. Falsy values will be not be + * bound. + */ + on(eventName: string, callback: (data: EventData) => void, thisArg?: any): void; /** * Raised when a loadFinished event occurs.