From 852a5850dd83825d5c931379c93c418e53578143 Mon Sep 17 00:00:00 2001
From: Nedyalko Nikolov <nedyalko.nikolov@telerik.com>
Date: Mon, 19 Jan 2015 15:17:07 +0200
Subject: [PATCH 1/4] Adding documentation about events.

---
 bindings.md |   6 +-
 events.md   | 305 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 308 insertions(+), 3 deletions(-)
 create mode 100644 events.md

diff --git a/bindings.md b/bindings.md
index 02827603c..55ab2b072 100644
--- a/bindings.md
+++ b/bindings.md
@@ -19,7 +19,7 @@ Generally almost every UI control (since all controls are created with data bind
 
 * Target object should be a successor of **Bindable** class.
 * Target property should be a **dependency property** in order to use data binding from target to source (or two way data binding). A plain property could be used if there is no need of **twoWay** binding.
-* Data (business) object should raise **propertyChanged** event for every change in the value of the property.
+* Data (business) object should raise **propertyChange** event for every change in the value of the property.
 
 ##Direction of data flow
 
@@ -34,7 +34,7 @@ In order to use this option binding options should set **twoWay as true**. Follo
 
 * Creating binding in code.
 
-	1. In order to create a working binding first we should have a source object. Source object should raise **propertyChanged** event for every change of any property. NativeScript has a built-in class that fulfils that requirement (Observable). Following is a code snippet that creates an observable object instance.
+	1. In order to create a working binding first we should have a source object. Source object should raise **propertyChange** event for every change of any property. NativeScript has a built-in class that fulfils that requirement (Observable). Following is a code snippet that creates an observable object instance.
 
 		``` JavaScript
 		var observableModule = require("data/observable");
@@ -105,7 +105,7 @@ With an xml declaration we set only properies names both for target (text) and s
 
 ##Binding source
 
-The important part of the data binding is setting the source object. NativeScript data binding works with any object that emits a **propertyChanged** event. On the process of creating binding source can be set as second parameter of the bind(bindingOptions, source) or could be omitted. In that case for source is used a special property named **bindingContext** of the Bindable class. The special about this property is that it is inheritable across the visual tree. This means that control can use the **bindingContext** (as source) of the first **parent** element with a explicitly set **bindingContext**. With the previous example **bindingContext** can be set either on Page instance or StackPanel instance and TextField will have a proper source for its "text" property binding.
+The important part of the data binding is setting the source object. NativeScript data binding works with any object that emits a **propertyChange** event. On the process of creating binding source can be set as second parameter of the bind(bindingOptions, source) or could be omitted. In that case for source is used a special property named **bindingContext** of the Bindable class. The special about this property is that it is inheritable across the visual tree. This means that control can use the **bindingContext** (as source) of the first **parent** element with a explicitly set **bindingContext**. With the previous example **bindingContext** can be set either on Page instance or StackPanel instance and TextField will have a proper source for its "text" property binding.
 
 ``` JavaScript
 page.bindingContext = source;
diff --git a/events.md b/events.md
new file mode 100644
index 000000000..48f11febd
--- /dev/null
+++ b/events.md
@@ -0,0 +1,305 @@
+---
+nav-title: "NativeScript Events"
+title: "Events"
+description: "NativeScript Documentation: Events"
+position: 66
+---
+
+#Events
+
+##Overview
+
+Event is a message send from the event emitter for the occurrence of a specific action. This action could be generated by user action (such as finger tap), or by some program logic (indicates that downloading an image from a server is completed). The object that raises event is called **event sender** or just **sender**. The object that consumes the event is called **event listener** or just **listener**. Beeing a TypeScript (JavaScript) framework NativeScript cannot benefits from any language built-in event handling mechanism. Since events are very critical for any modern mobile application development NativeScript provides a class that powers the process of working with events. This class is called Observable ([API-Ref](./ApiReference/data/observable/observable.md)).
+
+##How events work
+
+Generally events are very similar to a radio station **sender** plays music (fires an event) and **listener** dance (executes an action). As mentioned NativeScript streamlines the events task with a class called Observable. It is one of the very basic classes within NativeScript framework so almost every NativeScript object (component) has an option for dealing with events.
+
+##Adding an event listener
+
+Adding an **event listener** means setting a function (method) which should be executed when event is raised. The example below shows how a function that prints a "Hello World!" message on the console is set to be executed when **button** is tapped.
+
+* Adding an event handler with a short-hand syntax
+
+This syntax is used to write an in-line function which should be executed when the **testButton** is tapped.
+
+``` JavaScript
+var buttonModule = require("ui/button");
+var testButton = new buttonModule.Button();
+testButton.text = "Test";
+
+testButton.on(buttonModule.knownEvents.tap, function (eventData) {
+  console.log("Hello World!");
+});
+```
+``` TypeScript
+import buttonModule = require("ui/button");
+var testButton = new buttonModule.Button();
+testButton.text = "Test";
+
+testButton.on(buttonModule.knownEvents.tap, function (eventData) {
+  console.log("Hello World!");
+  });
+```
+
+Even that this shor-hand syntax is very handy to assign some very simple functions it is missing some important features of the original syntax.
+
+* Adding an event handler
+
+``` JavaScript
+var buttonModule = require("ui/button");
+var testButton = new buttonModule.Button();
+testButton.text = "Test";
+
+var onTap = function (eventData) {
+  console.log("Hello World!");
+};
+
+testButton.addEventListener(buttonModule.knownEvents.tap, onTap, this);
+```
+``` TypeScript
+import buttonModule = require("ui/button");
+var testButton = new buttonModule.Button();
+testButton.text = "Test";
+
+var onTap = function (eventData) {
+  console.log("Hello World!");
+};
+
+testButton.addEventListener(buttonModule.knownEvents.tap, onTap, this);
+```
+The only difference here is the third optional parameter which represents the **this** argument which will be used as **event handler** context (closure). In other words if you need a **this** argument in your event handler function you have to use the long syntax otherwise **sender** object is used as this.
+
+* Adding an event handler with an xml declaration
+
+Another option to set an event handler is via an xml declaration.
+
+``` XML
+<Page>
+  <StackPanel>
+    <Button tap="onTap" />
+  </StackPanel>
+</Page>
+```
+Of course we need a code behind file in order to write the body of the function. (code behind file has same name as **xml** with **js** or **ts** extension).
+
+``` JavaScript
+function onTap(eventData) {
+  console.log("Hello World!");
+}
+exports.listViewItemTap = listViewItemTap;
+```
+``` TypeScript
+export function onTap(eventData) {
+  console.log("Hello World!");
+}
+```
+
+##Removing an event listener
+
+Usually there is no need to remove the **event listener**. However there are some scenarios where we need to receive the event just once, or just remove the event listener in order to free resources.
+
+* Remove an event listener with a short-hand syntax
+
+``` JavaScript
+testButton.off(buttonModule.knownEvents.tap);
+```
+``` TypeScript
+testButton.off(buttonModule.knownEvents.tap);
+```
+This will remove all listeners for the tap event of the testButton instance. If there are more than one **event listener** second parameter with the name of the callback function could be set and only the referenced event listener will be removed.
+
+* Remove an event listener with long syntax
+
+``` JavaScript
+testButton.removeEventListener(buttonModule.knownEvents.tap, onTap);
+```
+``` TypeScript
+testButton.removeEventListener(buttonModule.knownEvents.tap, onTap);
+```
+The difference between short and long syntax is the option of the long syntax to specify the **this** argument (which was used to add the event listener) if there are many event listeners with different **this** arguments.
+
+> There is no syntax to remove event listener via an xml declaration.
+
+##PropertyChange event
+
+Observable class has a built-in event called **propertyChange** which is called when any property has been changed. Subscribing to this event is very similar to previous examples.
+
+``` JavaScript
+var observableModule = require("data/observable");
+var observableObject = new observableModule.Observable();
+
+observableObject.on(observableModule.knownEvents.propertyChange, function(propertyChangeData){
+  console.log(propertyChangeData.propertyName + " has been changed and new value is: " + propertyChangeData.value);
+});
+```
+``` TypeScript
+import observableModule = require("data/observable");
+var observableObject = new observableModule.Observable();
+
+observableObject.on(observableModule.knownEvents.propertyChange, function(propertyChangeData){
+  console.log(propertyChangeData.propertyName + " has been changed and new value is: " + propertyChangeData.value);
+});
+```
+What is important about this event is that it is very critical for entire [data binding](./bindings.md) system to work. In order to take advantage of the data binding mechanism its enough just to create your business object as **successors** of the Observable class. Following example shows how to do that:
+
+``` JavaScript
+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.get("myProperty");
+      },
+      set: function (value) {
+        this.set("myProperty", value);
+      },
+      enumerable: true,
+      configurable: true
+    });
+    return MyClass;
+  })(observableModule.Observable);
+exports.MyClass = MyClass;
+```
+``` TypeScript
+import observableModule = require("data/observable");
+
+export class MyClass extends observableModule.Observable {
+  public get myProperty(): number {
+    return this.get("myProperty");
+  }
+
+  public set myProperty(value: number) {
+    this.set("myProperty", value);
+  }
+}
+```
+This code snippet will fire the **propertyChange** event when the value of the property is changed (out-of-the-box).
+
+##Creating a custom event
+
+Using Observable methods **get** and **set** works just great for the **propertyChange** event. In many cases, according to some business logic, there is a need to create a custom event. To fire (raise or emit) an event all we have to do is to Observable.notify() method with proper event data when the action is completed. By proper event data we refer to any **successor** of the [EventData interface](./ApiReference/data/observable/EventData.md). This is the very basic information about an event (its name as **eventName** and instance of the **event sender** as **object**).
+
+``` JavaScript
+var eventData = {
+  eventName: "myCustomEventName",
+  sender: this
+};
+this.notify(eventData);
+```
+``` TypeScript
+var eventData: observableModule.EventData = {
+  eventName: "myCustomEventName",
+  sender: this
+}
+this.notify(eventData);
+```
+The barely minimum information needed to raise an event is the eventName - it will be used to execute all **event handlers** associated with this event.
+
+Next step is to hook for this event.
+
+``` JavaScript
+var myCustomObject = new MyClass();
+myCustomObject.on("myCustomEventName", function(eventData){
+  console.log(eventData.eventName + " has been raised! by: " + eventData.sender);
+})
+```
+Almost the same logic is implemented for the **propertyChange** event, so if your business logic has some special requirements **propertyChange** could be emitted manually via **notify()** method (without using Observable.set() method which also fires the **propertyChange** event).
+
+##Avoiding memory leaks
+
+As mentioned working with events is very similar to a radio station. In fact the situation is a bit more complicated. In order to be able to notify the listener, the sender has a pointer to the listener. This means that even that listener object is set to null or undefined it is not eligible for garbage collection, since the sender is alive and has a live reference to listener object. This could result in a memory leak in some scenarios when object lifetime of the sender and the listener are quite different. For example if we have an UI element which creates a lot of another controls every control hook for the event of the parent and after some time child control is released (very similar to list view scrolling). In order to prevent such memory leaks it is a good practice to remove your event listener handler before releasing the listener object. Unfortunately in some cases we could not define the exact time when we should call (off or removeEventListener) functions. Here comes another option in NativeScript framework **weakEvents**.
+
+##Working with weak events
+
+* Adding a weak event listener
+
+Weak events as its name suggests creates an weak reference to the **listener** object, which allows this listener object to be released without removing the **event listener** pointer. Using weak event listeners is very similar to *normal* events. Here is the example with comments for each line.
+
+``` JavaScript
+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.knownEvents.tap, 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 = {
+    // a weak reference of the event listener object
+    targetWeakRef: new WeakRef(this),
+    // a weak reference if the event sender object
+    sourceWeakRef: new WeakRef(this.source),
+    // the name of the event
+    eventName: observable.knownEvents.propertyChange,
+    // the handler of the event
+    handler: handlePropertyChange,
+    // the context which will be used to execute the handler (optional)
+    handlerContext: testButton,
+    // a special property which is used for a extra event recognition (optional)
+    key: this.options.targetProperty
+  }
+  weakEL.addWeakEventListener(this.weakEventListenerOptions);
+```
+``` TypeScript
+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.knownEvents.tap, 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 = {
+  // a weak reference of the event listener object
+  targetWeakRef: new WeakRef(this),
+  // a weak reference if the event sender object
+  sourceWeakRef: new WeakRef(this.source),
+  // the name of the event
+  eventName: observable.knownEvents.propertyChange,
+  // the handler of the event
+  handler: handlePropertyChange,
+  // the context which will be used to execute the handler (optional)
+  handlerContext: testButton,
+  // a special property which is used for a extra event recognition (optional)
+  key: this.options.targetProperty
+}
+weakEL.addWeakEventListener(this.weakEventListenerOptions);
+```
+
+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 **propertyChange** event is raised (via button tap). It demonstrates how to use the **handlerContext** property - the value of this property is taken as **this** argument inside the **event handler** function.
+Generally **targetWeakRef** and **key** properties are not needed to invoke a function when an event is raised. However these properties support another useful option of the weak event listener (a possibility to remove an event listener) both properties are used as keys for a key-value pair that stores weak event listeners.
+
+* Removing weak event listener
+
+``` JavaScript
+weakEL.removeWeakEventListener(this.weakEventListenerOptions);
+```
+``` TypeScript
+weakEL.removeWeakEventListener(this.weakEventListenerOptions);
+```

From bdf41571719a77ae0430c4763a0e3b7b39c0aea7 Mon Sep 17 00:00:00 2001
From: Erjan Gavalji <erjan.gavalji@gmail.com>
Date: Mon, 19 Jan 2015 16:36:06 +0200
Subject: [PATCH 2/4] Update bindings.md

---
 bindings.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/bindings.md b/bindings.md
index 55ab2b072..c1836e6eb 100644
--- a/bindings.md
+++ b/bindings.md
@@ -19,7 +19,7 @@ Generally almost every UI control (since all controls are created with data bind
 
 * Target object should be a successor of **Bindable** class.
 * Target property should be a **dependency property** in order to use data binding from target to source (or two way data binding). A plain property could be used if there is no need of **twoWay** binding.
-* Data (business) object should raise **propertyChange** event for every change in the value of the property.
+* Data (business) object should raise `propertyChange` event for every change in the value of the property.
 
 ##Direction of data flow
 

From c67bf4b83e429f7c302e36c6e7f588ca766b3d6e Mon Sep 17 00:00:00 2001
From: Erjan Gavalji <erjan.gavalji@gmail.com>
Date: Mon, 19 Jan 2015 16:37:08 +0200
Subject: [PATCH 3/4] Update bindings.md

---
 bindings.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/bindings.md b/bindings.md
index c1836e6eb..55ab2b072 100644
--- a/bindings.md
+++ b/bindings.md
@@ -19,7 +19,7 @@ Generally almost every UI control (since all controls are created with data bind
 
 * Target object should be a successor of **Bindable** class.
 * Target property should be a **dependency property** in order to use data binding from target to source (or two way data binding). A plain property could be used if there is no need of **twoWay** binding.
-* Data (business) object should raise `propertyChange` event for every change in the value of the property.
+* Data (business) object should raise **propertyChange** event for every change in the value of the property.
 
 ##Direction of data flow
 

From 76ebe0e4b59626da980a4e40ba67fbb685c9cc3e Mon Sep 17 00:00:00 2001
From: Erjan Gavalji <erjan.gavalji@gmail.com>
Date: Mon, 19 Jan 2015 17:08:28 +0200
Subject: [PATCH 4/4] Some typo fixes

---
 events.md | 34 +++++++++++++++++-----------------
 1 file changed, 17 insertions(+), 17 deletions(-)

diff --git a/events.md b/events.md
index 48f11febd..6476c396b 100644
--- a/events.md
+++ b/events.md
@@ -9,11 +9,11 @@ position: 66
 
 ##Overview
 
-Event is a message send from the event emitter for the occurrence of a specific action. This action could be generated by user action (such as finger tap), or by some program logic (indicates that downloading an image from a server is completed). The object that raises event is called **event sender** or just **sender**. The object that consumes the event is called **event listener** or just **listener**. Beeing a TypeScript (JavaScript) framework NativeScript cannot benefits from any language built-in event handling mechanism. Since events are very critical for any modern mobile application development NativeScript provides a class that powers the process of working with events. This class is called Observable ([API-Ref](./ApiReference/data/observable/observable.md)).
+Event is a message sent from the event emitter for the occurrence of a specific action. This action could be generated by user action (such as finger tap), or by some program logic (indicates that downloading an image from a server is completed). The object that raises event is called **event sender** or just **sender**. The object that consumes the event is called **event listener** or just **listener**. Being a TypeScript (JavaScript) framework NativeScript cannot benefit from any language built-in event handling mechanism. Since events are very critical for any modern mobile application development NativeScript provides a class that powers the process of working with events. This class is called Observable ([API-Ref](./ApiReference/data/observable/observable.md)).
 
 ##How events work
 
-Generally events are very similar to a radio station **sender** plays music (fires an event) and **listener** dance (executes an action). As mentioned NativeScript streamlines the events task with a class called Observable. It is one of the very basic classes within NativeScript framework so almost every NativeScript object (component) has an option for dealing with events.
+Generally events are very similar to a radio station: **sender** plays music (fires an event) and **listener** dances (executes an action). As mentioned, NativeScript streamlines the events task with a class called Observable. It is one of the very basic classes within NativeScript framework so almost every NativeScript object (component) has an option for dealing with events.
 
 ##Adding an event listener
 
@@ -42,7 +42,7 @@ testButton.on(buttonModule.knownEvents.tap, function (eventData) {
   });
 ```
 
-Even that this shor-hand syntax is very handy to assign some very simple functions it is missing some important features of the original syntax.
+Even though this short-hand syntax is very handy to assign some very simple functions it is missing some important features available in the original syntax:
 
 * Adding an event handler
 
@@ -68,7 +68,7 @@ var onTap = function (eventData) {
 
 testButton.addEventListener(buttonModule.knownEvents.tap, onTap, this);
 ```
-The only difference here is the third optional parameter which represents the **this** argument which will be used as **event handler** context (closure). In other words if you need a **this** argument in your event handler function you have to use the long syntax otherwise **sender** object is used as this.
+The only difference here is the third optional parameter which represents the **this** argument which will be used as **event handler** context (closure). In other words, if you need a **this** argument in your event handler function you have to use the long syntax, otherwise the **sender** object is used as the **this**.
 
 * Adding an event handler with an xml declaration
 
@@ -81,7 +81,7 @@ Another option to set an event handler is via an xml declaration.
   </StackPanel>
 </Page>
 ```
-Of course we need a code behind file in order to write the body of the function. (code behind file has same name as **xml** with **js** or **ts** extension).
+Of course we need a code behind file in order to write the body of the function. (Code behind file has same name as **xml** with **js** or **ts** extension).
 
 ``` JavaScript
 function onTap(eventData) {
@@ -107,9 +107,9 @@ testButton.off(buttonModule.knownEvents.tap);
 ``` TypeScript
 testButton.off(buttonModule.knownEvents.tap);
 ```
-This will remove all listeners for the tap event of the testButton instance. If there are more than one **event listener** second parameter with the name of the callback function could be set and only the referenced event listener will be removed.
+This will remove all listeners for the tap event of the testButton instance. If there are more than one **event listener** objects, a second parameter with the name of the callback function could be set so that only the referenced event listener will be removed.
 
-* Remove an event listener with long syntax
+* Remove an event listener, long syntax
 
 ``` JavaScript
 testButton.removeEventListener(buttonModule.knownEvents.tap, onTap);
@@ -119,7 +119,7 @@ testButton.removeEventListener(buttonModule.knownEvents.tap, onTap);
 ```
 The difference between short and long syntax is the option of the long syntax to specify the **this** argument (which was used to add the event listener) if there are many event listeners with different **this** arguments.
 
-> There is no syntax to remove event listener via an xml declaration.
+> There is no syntax to remove an event listener via an xml declaration.
 
 ##PropertyChange event
 
@@ -141,7 +141,7 @@ observableObject.on(observableModule.knownEvents.propertyChange, function(proper
   console.log(propertyChangeData.propertyName + " has been changed and new value is: " + propertyChangeData.value);
 });
 ```
-What is important about this event is that it is very critical for entire [data binding](./bindings.md) system to work. In order to take advantage of the data binding mechanism its enough just to create your business object as **successors** of the Observable class. Following example shows how to do that:
+What is important about this event is that it is very critical for the entire [data binding](./bindings.md) system to work. In order to take advantage of the data binding mechanism it is enough to simply make your business object **inherit** of the Observable class. The following example demonstrates how to do that:
 
 ``` JavaScript
 var observableModule = require("data/observable");
@@ -177,41 +177,41 @@ export class MyClass extends observableModule.Observable {
   }
 }
 ```
-This code snippet will fire the **propertyChange** event when the value of the property is changed (out-of-the-box).
+This code snippet will fire the **propertyChange** event when the value of the property is changed out-of-the-box.
 
 ##Creating a custom event
 
-Using Observable methods **get** and **set** works just great for the **propertyChange** event. In many cases, according to some business logic, there is a need to create a custom event. To fire (raise or emit) an event all we have to do is to Observable.notify() method with proper event data when the action is completed. By proper event data we refer to any **successor** of the [EventData interface](./ApiReference/data/observable/EventData.md). This is the very basic information about an event (its name as **eventName** and instance of the **event sender** as **object**).
+Using Observable, methods **get** and **set** works just great for the **propertyChange** event. In many cases, according to some business logic, there is a need to create a custom event. To fire (raise or emit) an event all we have to do is to Observable.notify() method with proper event data when the action is completed. By proper event data we refer to any **implementer** of the [EventData interface](./ApiReference/data/observable/EventData.md). This is the very basic information about an event (its name as **eventName** and instance of the **event sender** as **object**).
 
 ``` JavaScript
 var eventData = {
   eventName: "myCustomEventName",
-  sender: this
+  object: this
 };
 this.notify(eventData);
 ```
 ``` TypeScript
 var eventData: observableModule.EventData = {
   eventName: "myCustomEventName",
-  sender: this
+  object: this
 }
 this.notify(eventData);
 ```
-The barely minimum information needed to raise an event is the eventName - it will be used to execute all **event handlers** associated with this event.
+The bare minimum needed to raise an event is the eventName - it will be used to execute all **event handlers** associated with this event.
 
 Next step is to hook for this event.
 
 ``` JavaScript
 var myCustomObject = new MyClass();
 myCustomObject.on("myCustomEventName", function(eventData){
-  console.log(eventData.eventName + " has been raised! by: " + eventData.sender);
+  console.log(eventData.eventName + " has been raised! by: " + eventData.object);
 })
 ```
 Almost the same logic is implemented for the **propertyChange** event, so if your business logic has some special requirements **propertyChange** could be emitted manually via **notify()** method (without using Observable.set() method which also fires the **propertyChange** event).
 
 ##Avoiding memory leaks
 
-As mentioned working with events is very similar to a radio station. In fact the situation is a bit more complicated. In order to be able to notify the listener, the sender has a pointer to the listener. This means that even that listener object is set to null or undefined it is not eligible for garbage collection, since the sender is alive and has a live reference to listener object. This could result in a memory leak in some scenarios when object lifetime of the sender and the listener are quite different. For example if we have an UI element which creates a lot of another controls every control hook for the event of the parent and after some time child control is released (very similar to list view scrolling). In order to prevent such memory leaks it is a good practice to remove your event listener handler before releasing the listener object. Unfortunately in some cases we could not define the exact time when we should call (off or removeEventListener) functions. Here comes another option in NativeScript framework **weakEvents**.
+Though the radio station comparison is convenient for understanding the concept, the situation is a bit more complicated in the inside. In order to be able to notify the listener, the sender has a pointer to the listener. This means that even if that listener object gets set to `null` or `undefined`, it is not eligible for garbage collection, since the sender is alive and has a live reference to the listener object. This could result in a memory leak in some scenarios when object lifetimes of the sender and the listener are quite different. Here's an example scenario: a UI element creates a lot of child controls, where every control hooks for an event of the parent and then a child control gets released (very similar to list view scrolling). In order to prevent such memory leaks it is a good practice to remove your event listener handler before releasing the listener object. Unfortunately in some cases we could define the exact time when we should call (off or removeEventListener) functions. Here comes another option in NativeScript framework **weakEvents**.
 
 ##Working with weak events
 
@@ -292,7 +292,7 @@ var weakEventListenerOptions: weakEventListenerModule.WeakEventListenerOptions =
 weakEL.addWeakEventListener(this.weakEventListenerOptions);
 ```
 
-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 **propertyChange** event is raised (via button tap). It demonstrates how to use the **handlerContext** property - the value of this property is taken as **this** argument inside the **event handler** function.
+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 - the value of this property is taken as a **this** argument inside the **event handler** function.
 Generally **targetWeakRef** and **key** properties are not needed to invoke a function when an event is raised. However these properties support another useful option of the weak event listener (a possibility to remove an event listener) both properties are used as keys for a key-value pair that stores weak event listeners.
 
 * Removing weak event listener