| nav-title | title | description | position |
|---|---|---|---|
Events in NativeScript |
App: Events |
How to handle events in NativeScript. |
7 |
This article contents:
- Overview
- Adding an Event Handler
- Removing an Event Listener
- PropertyChange Event
- Creating a Custom Event
- Avoiding Memory Leaks
- Working with Weak Events
An event is a message sent from an event emitter to signify the occurrence of a specific action. This action can be generated by a user action (such as a tap) or by program logic (for instance, to indicate that downloading an image from a server has completed). The object that raises the event is called event sender (simply sender) or event raiser. The object that consumes the event is called event listener (simply listener) or event handler.
The NativeScript framework provides a class Observable that powers the process of working with events. Find more information about it in the API Reference. Because it is one of the base classes within the NativeScript framework, almost every NativeScript object (component) has an option for dealing with events.
To add an event handler means setting a function (method) that executes when the event is raised.
The example below shows how to set a function that prints a "Hello World!" message in the console when a button is tapped. You can choose between the shorthand syntax and the full syntax or you can declare the event handler in XML.
The example below shows how to add an event listener by using the short and full syntax. There is a third optional parameter that represents the this argument.
//Adding a listener with the short syntax
var buttonModule = require("ui/button");
var testButton = new buttonModule.Button();
testButton.text = "Test";
testButton.on(buttonModule.Button.tapEvent, function (eventData) {
console.log("Hello World!");
},this);
//Adding a lister with the full syntax
var testButton2 = new buttonModule.Button();
testButton2.text = "Test";
var onTap = function (eventData) {
console.log("Hello World!");
};
testButton2.addEventListener(buttonModule.Button.tapEvent, onTap, this);//Adding a listener with the short syntax
import buttonModule = require("ui/button");
var testButton = new buttonModule.Button();
testButton.text = "Test";
testButton.on(buttonModule.Button.tapEvent, function (eventData) {
console.log("Hello World!");
},this);
//Adding a lister with the full syntax
var testButton2 = new buttonModule.Button();
testButton2.text = "Test";
var onTap = function (eventData) {
console.log("Hello World!");
};
testButton2.addEventListener(buttonModule.Button.tapEvent, onTap, this);Another option to set an event handler is to use an XML declaration like this:
<Page>
<StackLayout>
<Button tap="onTap" />
</StackLayout>
</Page>You need a code-behind file to write the function body (the code-behind file has the same file name, but a different extension: .js or .ts depending on the language you are using). It could look like this:
function onTap(eventData) {
console.log("Hello World!");
}
exports.onTap = onTap;export function onTap(eventData) {
console.log("Hello World!");
}Usually, you don't need to remove the event listener. You might need to do it when you want to receive the event just once or to free up resources. In such cases, you can apply the following methods.
There is no syntax to remove an event listener through an XML declaration.
The following example uses the shorthand and full syntax to remove all listeners for the tap event of the testButton instance. If more than one objects are listening for events, you can set a second parameter with the name of the callback function. This way only the referenced event listener is removed. When multiple event listeners with different this arguments are available, a third optional parameter is used.
//Removing a listener with short syntax
testButton.off(buttonModule.Button.tapEvent);
//Removing a listener with short syntax
testButton2.removeEventListener(buttonModule.Button.tapEvent);//Removing a listener with short syntax
testButton.off(buttonModule.Button.tapEvent);
//Removing a listener with short syntax
testButton2.removeEventListener(buttonModule.Button.tapEvent);The Observable class provides a built-in event called propertyChange which is called when a property is changed. This is how to subscribe to this event:
var observableModule = require("data/observable");
var observableObject = new observableModule.Observable();
observableObject.on(observableModule.Observable.propertyChangeEvent, function(propertyChangeData){
console.log(propertyChangeData.propertyName + " has been changed and the new value is: " + propertyChangeData.value);
});import observableModule = require("data/observable");
var observableObject = new observableModule.Observable();
observableObject.on(observableModule.Observable.propertyChangeEvent, function(propertyChangeData){
console.log(propertyChangeData.propertyName + " has been changed and the new value is: " + propertyChangeData.value);
});It is important to note that this event is critical for the entire data binding system. To take advantage of the data binding mechanism, all you have to do is make your business object inherit the Observable class. The following example demonstrates how to do that:
var observableModule = require("data/observable");
var MyClass = (function (_super) {
__extends(MyClass, _super);
function MyClass() {
_super.apply(this, arguments);
}
Object.defineProperty(MyClass.prototype, "myProperty", {
get: function () {
return this._myProperty;
},
set: function (value) {
this._myProperty = value;
},
enumerable: true,
configurable: true
});
return MyClass;
})(observableModule.Observable);
exports.MyClass = MyClass;import observableModule = require("data/observable");
export class MyClass extends observableModule.Observable {
private _myProperty:number;
public get myProperty(): number {
return this._myProperty;
}
public set myProperty(value: number) {
this._myProperty = value;
}
}The previous code snippet fires the propertyChange event when the property value is changed.
If your business logic demands it, you may want to fire (raise or emit) a custom event on a particular action. To do that, call the Observable.notify() method when the action is completed. This method takes any implementer of the EventData interface as event data. It includes basic information about an event—its name as eventName and an instance of the event sender as object).
var eventData = {
eventName: "myCustomEventName",
object: this
};
this.notify(eventData);var eventData: observableModule.EventData = {
eventName: "myCustomEventName",
object: this
}
this.notify(eventData);The minimum information needed to raise an event is the eventName—it will be used to execute all event handlers associated with this event.
The next step is to hook to this event:
var myCustomObject = new MyClass();
myCustomObject.on("myCustomEventName", function(eventData){
console.log(eventData.eventName + " has been raised! by: " + eventData.object);
})A similar logic is implemented for the propertyChange event, so if your business logic requires that, propertyChange can be emitted manually through the notify() method (without using the Observable.set() method that also fires the propertyChange event).
Though the radio station comparison is convenient for understanding the concept, events are a bit more complicated on the inside. To be able to notify the listener, the sender contains a pointer to the listener. Even if you set the listener object to null or undefined, it is not eligible for garbage collection, because the sender is alive and has a live reference to the listener object. This could result in a memory leak when the object lifetimes of the sender and the listener differ significantly.
Consider this scenario: A UI element creates a lot of child controls, each of which hooks to an event of the parent. Then a child control is released (during a list view scrolling for instance), causing a memory leak.
To prevent these memory leaks, it is a good practice to remove your event listener handler before releasing the listener object. Unfortunately, sometimes you cannot determine the exact time to call the off or removeEventListener function. In such cases use another option of the NativeScript framework: Weak Events.
A weak event, as its name suggests, creates an weak reference to the listener object, which helps you release the listener object without removing the event listener pointer.
Using weak event listeners is very similar to normal events. This is how to add a weak event listener (code comments are included for clarity):
var weakEventListenerModule = require("ui/core/weakEventListener");
var buttonModule = require("ui/button");
var observableModule = require("data/observable");
var testButton = new buttonModule.Button();
testButton.text = "Test";
testButton.on(buttonModule.Button.tapEvent, function () {
source.set("testProperty", "change" + counter);
});
var source = new observableModule.Observable();
var counter = 0;
var handlePropertyChange = function () {
counter++;
this.text = counter + "";
};
var weakEL = weakEventListenerModule.WeakEventListener;
var weakEventListenerOptions: weakEventListenerModule.WeakEventListenerOptions = {
// create a weak reference to the event listener object
targetWeakRef: new WeakRef(this),
// create a weak reference to the event sender object
sourceWeakRef: new WeakRef(this.source),
// set the name of the event
eventName: observable.Observable.propertyChangeEvent,
// set the event handler
handler: handlePropertyChange,
// (optional) set the context in which to execute the handler
handlerContext: testButton,
// (optional) set a specialized property used for extra event recognition
key: this.options.targetProperty
}
weakEL.addWeakEventListener(this.weakEventListenerOptions);import weakEventListenerModule = require("ui/core/weakEventListener");
import buttonModule = require("ui/button");
import observableModule = require("data/observable");
var testButton = new buttonModule.Button();
testButton.text = "Test";
testButton.on(buttonModule.Button.tapEvent, function () {
source.set("testProperty", "change" + counter);
});
var source = new observableModule.Observable();
var counter = 0;
var handlePropertyChange = function () {
counter++;
this.text = counter + "";
};
var weakEL = weakEventListenerModule.WeakEventListener;
var weakEventListenerOptions: weakEventListenerModule.WeakEventListenerOptions = {
// create a weak reference to the event listener object
targetWeakRef: new WeakRef(this),
// create a weak reference to the event sender object
sourceWeakRef: new WeakRef(this.source),
// set the name of the event
eventName: observable.Observable.propertyChangeEvent,
// set the event handler
handler: handlePropertyChange,
// specialized property used for extra event recognition
key: this.options.targetProperty,
// (optional) set the context in which to execute the handler
handlerContext: testButton
}
weakEL.addWeakEventListener(this.weakEventListenerOptions);The previous example shows how to attach a weak event listener to an observable object instance. A closer look to the handlePropertyChange function shows that text property of the this object is changed when the propertyChange event is raised (via the button tap event). It demonstrates how to use the handlerContext property—its value is taken as an argument to this inside the event handler function.
The targetWeakRef and key properties are optional when invoking a function on an event. However, they allow for removing an event listener. The properties are used as keys for a key-value pair that stores weak event listeners.
weakEL.removeWeakEventListener(this.weakEventListenerOptions);weakEL.removeWeakEventListener(this.weakEventListenerOptions);