Merge pull request #1422 from NativeScript/niliev/native-apis

add ts examples and overall improvments

Author: tsonevn

docs/core-concepts/accessing-native-apis-with-javascript.md

@@ -17,16 +17,24 @@ In this article, you will learn how to call native APIs from JavaScript with var
 
 All native numeric types (e.g., char, short, int, double, float on iOS and byte, short, int, long, double, float on Android) are implicitly converted to JavaScript number and vice versa. For example, when you run the following code on iOS:
 
+- iOS
+
 ```JavaScript
-// iOS
-console.log('pow(2.5, 3) = ', pow(2.5, 3));
+console.log(`pow(2.5, 3) = ${pow(2.5, 3)}`);
+```
+```TypeScript
+console.log(`pow(2.5, 3) = ${pow(2.5, 3)}`);
 ```
 
 the iOS Runtime converts the JavaScript number literals to native doubles and passes them to the native `pow(double x, double y)` function. The returned native integer is automatically converted to a JavaScript number and passed to `console.log()`. The same is valid for Android:
 
+- Android
+
 ```JavaScript
-// Android
-console.log('min(3, 4) = ', java.lang.Math.min(3, 4));
+console.log(`min(3, 4) = ${java.lang.Math.min(3, 4)}`);
+```
+```TypeScript
+console.log(`min(3, 4) = ${java.lang.Math.min(3, 4)}`);
 ```
 
 The native `java.lang.Math.min()` method expects two integers. The Android Runtime knows the signature of the function `java.lang.Math.min()` and translates the literals `3` and `4` to their representation in a Java integer data type. The returned integer is also automatically translated to a JavaScript number and passed to `console.log()`.
@@ -35,16 +43,26 @@ The native `java.lang.Math.min()` method expects two integers. The Android Runti
 
 JavaScript strings are implicitly marshalled to `java.lang.String` on Android and `NSString` on iOS and vice versa.
 
+- iOS
+
 ```JavaScript
-// iOS
-var button = new UIButton();
+let button = new UIButton();
+button.setTitleForState('Button title', UIControlStateNormal); // 'Button title' is converted to NSString
+console.log(button.titleLabel.text); // The returned NSString is converted to JavaScript string
+```
+```TypeScript
+let button = new UIButton();
 button.setTitleForState('Button title', UIControlStateNormal); // 'Button title' is converted to NSString
 console.log(button.titleLabel.text); // The returned NSString is converted to JavaScript string
 ```
 
+- Android
+
 ```JavaScript
-// Android
-var file = new java.io.File('myfile.txt'); // 'myfile.txt' is converted to java.lang.String
+const file = new java.io.File('myfile.txt'); // 'myfile.txt' is converted to java.lang.String
+```
+```TypeScript
+const file = new java.io.File('myfile.txt'); // 'myfile.txt' is converted to java.lang.String
 ```
 
 The exception to this are the methods on `NSString` classes declared as returning `instancetype` - init methods and factory methods. This means that a call to `NSString.stringWithString` whose return type in Objective-C is `instancetype` will return a wrapper around a `NSString` instance rather than a JavaScript string.
@@ -55,38 +73,62 @@ The exception to this are the methods on `NSString` classes declared as returnin
 
 JavaScript boolean values are implicitly marshalled to `boolean` on Android and `BOOL` on iOS and vice versa.
 
+- iOS
+
 ```JavaScript
-// iOS
-var str = NSString.stringWithString('YES');
-var isTrue = str.boolValue();
+let str = NSString.stringWithString('YES');
+let isTrue = str.boolValue();
+```
+```TypeScript
+let str = NSString.stringWithString('YES');
+let isTrue = str.boolValue();
 ```
 
+- Android
+
 ```JavaScript
-// Android
-var str = new java.lang.String('Hello world!');
-var result = str.endsWith('world!');
+let str = new java.lang.String('Hello world!');
+let result = str.endsWith('world!');
+console.log(result); // true
+```
+```TypeScript
+let str = new java.lang.String('Hello world!');
+let result = str.endsWith('world!');
 console.log(result); // true
 ```
 
 ## Array
 
 JavaScript arrays map to specialized Java arrays on Android and `NSArray` on iOS.
 
+- iOS
+
 ```JavaScript
-// iOS
 // nsArray is not a JavaScript array but a JavaScript wrapper around a native NSArray
-var nsArray = NSArray.arrayWithArray(['Four', 'Five', 'Two', 'Seven']);
-var jsArray = ['One', 'Two', 'Three']; // pure JavaScript array
-var firstCommon = nsArray.firstObjectCommonWithArray(jsArray);
+let nsArray = NSArray.arrayWithArray(['Four', 'Five', 'Two', 'Seven']);
+let jsArray = ['One', 'Two', 'Three']; // pure JavaScript array
+let firstCommon = nsArray.firstObjectCommonWithArray(jsArray);
 console.log(firstCommon); // Two
 ```
+```TypeScript
+// nsArray is not a JavaScript array but a JavaScript wrapper around a native NSArray
+let nsArray = NSArray.arrayWithArray(['Four', 'Five', 'Two', 'Seven']);
+let jsArray = ['One', 'Two', 'Three']; // pure JavaScript array
+let firstCommon = nsArray.firstObjectCommonWithArray(jsArray);
+console.log(firstCommon); // Two
+```
+
+- Android
 
 The following code snippet shows how to call a `ns.example.Math.minElement(int[] array)` from JavaScript:
 
 ```JavaScript
-// Android
-var numbers = [3, 6, 19, -2, 7, 6];
-var min = ns.example.Math.minElement(numbers); // -2
+let numbers = [3, 6, 19, -2, 7, 6];
+let min = ns.example.Math.minElement(numbers); // -2
+```
+```TypeScript
+let numbers = [3, 6, 19, -2, 7, 6];
+let min = ns.example.Math.minElement(numbers); // -2
 ```
 
 ## Classes and Objects
@@ -98,8 +140,11 @@ All native classes are represented in the JavaScript world by a constructor func
 Here is an example of how an instance of the `NSMutableArray` class is made and consumed in JavaScript:
 
 ```JavaScript
-// iOS
-var array = new NSMutableArray();
+let array = new NSMutableArray();
+array.addObject(new NSObject());
+```
+```TypeScript
+let array = new NSMutableArray();
 array.addObject(new NSObject());
 ```
 
@@ -109,47 +154,75 @@ This snippet creates an instance of `NSMutableArray` and adds an object to it us
 
 You will most probably encounter methods accepting NSDictionary instances as parameters. There are few ways of creating an NSDictionary instance:
 
-```Javascript
-var dict = new NSDictionary([".example.com", "cookieName", "/", "cookieValue"], [NSHTTPCookieDomain, NSHTTPCookieName, NSHTTPCookiePath,NSHTTPCookieValue]);
-var cookie = NSHTTPCookie.cookieWithProperties(dict);
+- Using `NSDictionary` and passing arrays for keys and values.
+
+```JavaScript
+let dict = new NSDictionary([".example.com", "cookieName", "/", "cookieValue"], [NSHTTPCookieDomain, NSHTTPCookieName, NSHTTPCookiePath,NSHTTPCookieValue]);
+let cookie = NSHTTPCookie.cookieWithProperties(dict);
 ```
+```TypeScript
+let dict = new NSDictionary([".example.com", "cookieName", "/", "cookieValue"], [NSHTTPCookieDomain, NSHTTPCookieName, NSHTTPCookiePath,NSHTTPCookieValue]);
+let cookie = NSHTTPCookie.cookieWithProperties(dict);
+```
+
+- Using JSON literals
 
-```Javascript
-var cookie = NSHTTPCookie.cookieWithProperties({[NSHTTPCookieDomain]:".example.com", [NSHTTPCookieName]:"cookieName", [NSHTTPCookiePath]:"/", [NSHTTPCookieValue]:"cookieValue"});
+```JavaScript
+let cookie = NSHTTPCookie.cookieWithProperties({[NSHTTPCookieDomain]:".example.com", [NSHTTPCookieName]:"cookieName", [NSHTTPCookiePath]:"/", [NSHTTPCookieValue]:"cookieValue"});
 ```
+```TypeScript
+let cookie = NSHTTPCookie.cookieWithProperties({[NSHTTPCookieDomain]:".example.com", [NSHTTPCookieName]:"cookieName", [NSHTTPCookiePath]:"/", [NSHTTPCookieValue]:"cookieValue"});
+```
+
+
 In the second example we are passing a JSON literal to the method.**NSHTTPCookieDomain** is a variable and we need to use a [computed property name](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer) in order to have its value (otherwise we are getting *"NSHTTPCookieDomain"* as key).
 
 ### Working With Classes And Objects on Android
 
 The following code snippet demonstrates how an instance of the `android.widget.Button` is created in JavaScript:
 
 ```JavaScript
-// Android
-var context = ...;
-var button = new android.widget.Button(context);
+let context = ...;
+let button = new android.widget.Button(context);
+button.setText("My Button"); // "My Button" is converted to java.lang.String
+```
+```TypeScript
+let context = ...;
+let button = new android.widget.Button(context);
 button.setText("My Button"); // "My Button" is converted to java.lang.String
 ```
+
 As you can see, the native Java types are exposed through their corresponding packages. In other words, to access a native Java type, you simply need to know the package it is contained in and explicitly state it. Native Java methods are accessed in the same way as regular JavaScript methods: by using the method identifier and supplying the required arguments. You can read more about Java packages on Android [here](https://docs.nativescript.org/runtimes/android/metadata/accessing-packages).
 
 ## Undefined and Null
 
 JavaScript [Undefined](http://www.w3schools.com/jsref/jsref_undefined.asp) & [Null](http://www.w3schools.com/js/js_datatypes.asp) map to Java null pointer and Objective-C nil. Native null values map to JavaScript null.
 
+- iOS
+
 ```JavaScript
-// iOS
 console.log(NSStringFromClass(null)); // null
 ```
+```TypeScript
+console.log(NSStringFromClass(null)); // null
+```
+
+- Android
 
 ```JavaScript
-// Android
-var context = ...;
-var button = new android.widget.Button(context);
+let context = ...;
+const button = new android.widget.Button(context);
+button.setOnClickListener(undefined); // the Java call will be made using the null keyword
+```
+```TypeScript
+let context = ...;
+const button = new android.widget.Button(context);
 button.setOnClickListener(undefined); // the Java call will be made using the null keyword
 ```
 
 ## IntelliSense and Access to the Native APIs via TypeScript
 
-To have access and Intellisense for the native APIs, you have to add a dev dependency to `tns-platform-declarations` 
+To have access and Intellisense for the native APIs, you have to add a developer dependency to `tns-platform-declarations`.
 
 Steps to install and enable