Skip to content
This repository was archived by the owner on Nov 17, 2022. It is now read-only.

chore: update to {N} 7 imports wip #1935

Merged
merged 6 commits into from
Feb 15, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions build/_layouts/landing.html
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ <h3 class="start-links__title">NativeScript & Angular</h3>
<li><a href="/angular/core-concepts/navigation">Core Concepts</a></li>
<li><a href="/angular/ui/overview">Components</a></li>
<li><a href="/angular/ui/layouts/layouts">Layouts</a></li>
<li><a href="/angular/app-and-screen-templates/app-templates">Application Templates</a></li>
<li><a href="/angular/app-templates/app-templates">Application Templates</a></li>
<li><a href="/angular/tooling/testing/testing">Tooling</a></li>
<li><a href="/angular/code-sharing/intro">Code Sharing</a></li>
<li><a href="/angular/ui/overview#nativescript-ui-overview">NativeScript UI</a></li>
Expand All @@ -117,11 +117,11 @@ <h3 class="start-links__title">NativeScript & Angular</h3>
<h3 class="start-links__title">NativeScript Core</h3>
<ul>
<li><a href="/start/introduction">Getting Started</a></li>
<li><a href="/core-concepts">Core Concepts</a></li>
<li><a href="/core-concepts/technical-overview">Core Concepts</a></li>
<li><a href="/ui/overview">Components</a></li>
<li><a href="/ui/layouts">Layouts</a></li>
<li><a href="/app-and-screen-templates/app-templates">Application Templates</a></li>
<li><a href="/tooling">Tooling</a></li>
<li><a href="/ui/layouts/layouts">Layouts</a></li>
<li><a href="/app-templates/app-templates">Application Templates</a></li>
<li><a href="/tooling/visual-studio-code-extension">Tooling</a></li>
<li><a href="/ui/overview#nativescript-ui-overview">NativeScript UI</a></li>
</ul>
</div>
Expand Down
28 changes: 11 additions & 17 deletions docs/core-concepts/accessing-native-apis-with-javascript.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ slug: access-native-apis

# Accessing native iOS and Android APIs through JavaScript

In this article we are going through the basic concepts of how native APIs are accessed through JavaScript. Our focus is on how primitive types are mapped between JavaScript and the corresponding native platform. We then continue with explaining how complex objects are represented and accessed. At the end, we talk about TypeScript and the `tns-platform-declarations` add-on which gives you TypeScript definitions for the Android and iOS development platforms.
In this article we are going through the basic concepts of how native APIs are accessed through JavaScript. Our focus is on how primitive types are mapped between JavaScript and the corresponding native platform. We then continue with explaining how complex objects are represented and accessed. At the end, we talk about TypeScript and the `@nativescript/types` add-on which gives you TypeScript definitions for the Android and iOS development platforms.

NativeScript lets you access all native APIs from the underlying platform. To achieve this behaviour, many things happen under the hood. One of them is marshalling - the conversion between JavaScript and Objective-C data types for iOS and Java data types for Android.

Expand Down Expand Up @@ -223,25 +223,24 @@ button.setOnClickListener(undefined); // the Java call will be made using the nu

## IntelliSense and Access to the Native APIs via TypeScript

To have access and Intellisense for the native APIs, you have to add a developer dependency to `tns-platform-declarations`.
To have access and Intellisense for the native APIs, you have to add a developer dependency to `@nativescript/types`.

Steps to install and enable

- `npm install tns-platform-declarations --save-dev`
- `npm install @nativescript/types --save-dev`

> **Note:** Always install the plugin as a `devDependency` (`npm i tns-platform-declarations --save-dev` flag) to avoid bringing the enormously big declaration files in the output built file.
> **Note:** Always install the plugin as a `devDependency` (`npm i @nativescript/types --save-dev` flag) to avoid bringing the enormously big declaration files in the output built file.

Create `reference.d.ts` in the root project directory and add the following:
```
/// <reference path="node_modules/tns-platform-declarations/android.d.ts" />
/// <reference path="node_modules/tns-platform-declarations/ios.d.ts" />
/// <reference path="node_modules/@nativescript/types/index.d.ts" />
```

By default, the file `android.d.ts` comes with typings generated for API level 17. As an Android developer, you might need access to a specific class, method, or property introduced in a newer API level. The `tns-platform-declarations` plugin comes with generated typings for all API levels from 17 to 27 including the related typings from the respective support library. To use typings for a specific Android level replace the reference to the default declaration file with the preferred one. The files for each API level comes postfixed with a dash followed by the number of the API level (e.g. for API 21 the file is named `android-21.d.ts`).
By default, the file `android.d.ts` comes with typings generated for API level 17. As an Android developer, you might need access to a specific class, method, or property introduced in a newer API level. The `@nativescript/types` plugin comes with generated typings for all API levels from 17 to 27 including the related typings from the respective support library. To use typings for a specific Android level replace the reference to the default declaration file with the preferred one. The files for each API level comes postfixed with a dash followed by the number of the API level (e.g. for API 21 the file is named `android-21.d.ts`).

For example, let's assume you are developing an application for API 21+ and you need typings generated for that API level:
```
/// <reference path="node_modules/tns-platform-declarations/android-21.d.ts" />
/// <reference path="node_modules/@nativescript/types-android/lib/android-21.d.ts" />
```

> **Note:** Proceed with caution when using functionalities introduced in newer API level. If you attempt
Expand All @@ -252,18 +251,13 @@ For example, let's assume you are developing an application for API 21+ and you
{
"compilerOptions": {
...
"lib": ["es6", "dom"],
"baseUrl": ".",
"paths": {
"*": [
"./node_modules/tns-core-modules/*",
"./node_modules/*"
]
}
"module": "esnext",
"target": "es2015",
"moduleResolution": "node",
"lib": ["es2018", "dom"],
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wonder if we should use the same lib as the target? Not sure if any implications by using different target/libs.

}
```
Note that `d.ts` files require a lot of memory and CPU. Consider adding **skipLibCheck** option to `tsconfig.json`.
For more information visit the GitHub repository of [tns-platform-declarations](https://github.com/NativeScript/NativeScript/tree/master/tns-platform-declarations)


# See Also
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -105,19 +105,19 @@ The core modules ship with a default `androidx.appcompat.app.AppCompatActivity`
2. Declare the extend:

```javascript
const frame = require("tns-core-modules/ui/frame");
import { Frame, Application, setActivityCallbacks } from "@nativescript/core";

const superProto = androidx.appcompat.app.AppCompatActivity.prototype;
androidx.appcompat.app.AppCompatActivity.extend("org.myApp.MainActivity", {
onCreate: function(savedInstanceState) {
// Used to make sure the App is inited in case onCreate is called before the rest of the framework
appModule.android.init(this.getApplication());
Application.android.init(this.getApplication());

// Set the isNativeScriptActivity in onCreate (as done in the original NativeScript activity code)
// The JS constructor might not be called because the activity is created from Android.
this.isNativeScriptActivity = true;
if(!this._callbacks) {
frame.setActivityCallbacks(this);
setActivityCallbacks(this);
}
// Modules will take care of calling super.onCreate, do not call it here
this._callbacks.onCreate(this, savedInstanceState, this.getIntent(), superProto.onCreate);
Expand Down Expand Up @@ -155,7 +155,7 @@ The core modules ship with a default `androidx.appcompat.app.AppCompatActivity`
});
```
```typescript
import {setActivityCallbacks, AndroidActivityCallbacks} from "tns-core-modules/ui/frame";
import { Frame, Application, setActivityCallbacks, AndroidActivityCallbacks } from "@nativescript/core";

@JavaProxy("org.myApp.MainActivity")
class Activity extends androidx.appcompat.app.AppCompatActivity {
Expand Down Expand Up @@ -219,8 +219,8 @@ The core modules ship with a default `androidx.appcompat.app.AppCompatActivity`

```javascript
const appComponents = [
"tns-core-modules/ui/frame",
"tns-core-modules/ui/frame/activity",
"@nativescript/core/ui/frame",
"@nativescript/core/ui/frame/activity",
resolve(__dirname, "app/activity.android.ts"),
];
```
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ slug: marking-mode-none

Starting with NativeScript 3.2, a new (experimental at the time) feature was added to the Android runtime called `markingMode`. Its purpose is to speed up garbage collection in the V8 engine. In some cases, a GC pass could take from 0.5 to 1 second and since it runs on the main UI thread, the user would experience a frozen app until GC is done. Setting “markingMode” to “none” will speed up the garbage collection greatly, so it would be less noticeable (if at all) to the app user. The downside of this approach is that some objects could be collected while their counterparts (in V8 or Android) are still in use. Such case is when JavaScript objects are referenced only from native code and in the eyes of the V8 GC no JS object holds reference to them. In other words – the objects are no longer “marked” as used and the V8 GC might collect them too early.

The code inside `tns-core-modules` and all plugins published by the NativeScript Team (since version 5.1.0) are written in such a way, that it does not depend on the scope to keep those Java/Kotlin instances alive. This makes apps using these plugins fully compatible with the much more performant `markingMode: "none"` option.
The code inside `@nativescript/core` and all plugins published by the NativeScript Team (since version 5.1.0) are written in such a way, that it does not depend on the scope to keep those Java/Kotlin instances alive. This makes apps using these plugins fully compatible with the much more performant `markingMode: "none"` option.

## Benefits and drawbacks of using markingMode: none

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ There's a `app/package.json` option which apps can set in order to disable `Mark
}
```

The code inside `tns-core-modules` and all plugins published by the NativeScript Team (since version 5.1.0) are written in such a way, that it does not depend on the scope to keep those Java/Kotlin instances alive. This makes apps using these plugins fully compatible with the much more performant `markingMode: "none"` option. [More information on `markingMode:none`](./marking-mode-none).
The code inside `@nativescript/core` and all plugins published by the NativeScript Team (since version 5.1.0) are written in such a way, that it does not depend on the scope to keep those Java/Kotlin instances alive. This makes apps using these plugins fully compatible with the much more performant `markingMode: "none"` option. [More information on `markingMode:none`](./marking-mode-none).

> **WARNING**: Enabling this option if the JavaScript code dealing with native objects (either in the application or any plugins you are using) does not correctly take care of the lifetime of Java/Kotlin instances may cause unexpected and unpredictable crashes of the application. This would be caused by Java/Kotlin instances being prematurely collected. Use caution when enabling it and make sure to thoroughly test your apps with different memory constrains and devices! The errors generated in such cases look like this:
`Error: com.tns.NativeScriptException: Attempt to use cleared object reference id=<some-object-id-number>`
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ To find out the package name of an Android class, refer to the [Android SDK Refe

For example, if you need to work with the Google API for Google Maps, after following the installation guide, you may need to access packages from the plugin like `com.google.android.gms.maps`, which you can find a reference for at [Google APIs for Android Reference](https://developers.google.com/android/reference/com/google/android/gms/maps/package-summary)

> **Note:** To have access and Intellisense for the native APIs with **NativeScript + TypeScript** or **NativeScript + Angular** projects, you have to add a dev dependency to `tns-platform-declarations`. More details about accessing native APIs with TypeScript can be found [here]({% slug access-native-apis %}#intellisense-and-access-to-native-apis-via-typescript).
> **Note:** To have access and Intellisense for the native APIs with **NativeScript + TypeScript** or **NativeScript + Angular** projects, you have to add a dev dependency to `@nativescript/types`. More details about accessing native APIs with TypeScript can be found [here]({% slug access-native-apis %}#intellisense-and-access-to-native-apis-via-typescript).


> **Note:** **(Experimental)** Alternatively, to get Intellisense for the native APIs based on the available Android Platform SDK and imported Android Support packages (added by default to your Android project), supply the `--androidTypings` flag with your `tns run | build android` command. The resulting `android.d.ts` file can then be used to provide auto-completion.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,14 +29,14 @@ The above is a bad practice for two reasons:

### The Good Practice

To resolve the above, in NativeScript, there is a developer dependency called [tns-platform-declarations].(https://preview.npmjs.com/package/tns-platform-declarations) After the intial instalation and setup, you could directly access the `android` namespace from the Android SDK.
To resolve the above, in NativeScript, there is a developer dependency called [@nativescript/types].(https://preview.npmjs.com/package/@nativescript/types) After the intial instalation and setup, you could directly access the `android` namespace from the Android SDK.
```TypeScript
// npm i tns-platform-declarations --save-dev
// follow the setup instructions at https://preview.npmjs.com/package/tns-platform-declarations
// npm i @nativescript/types --save-dev
// follow the setup instructions at https://preview.npmjs.com/package/@nativescript/types
let androidContext = android.content.Context;
```

The `tns-platform-declarations` plugin is providing access to the Android SDK. The plugin comes with pre-generated TypeScript declaration files for all API levels from 17 to 27 exclusive (detailed usage instructions in [this documentation section](../../accessing-native-apis-with-javascript#intellisense-and-access-to-the-native-apis-via-typescript)). In cases, where we need a declaration file for a third-party library or newer API (e.g. API 28) we can generate our own definitions using the **[Android DTS generator](#android-dts-generator)**.
The `@nativescript/types` plugin is providing access to the Android SDK. The plugin comes with pre-generated TypeScript declaration files for all API levels from 17 to 27 exclusive (detailed usage instructions in [this documentation section](../../accessing-native-apis-with-javascript#intellisense-and-access-to-the-native-apis-via-typescript)). In cases, where we need a declaration file for a third-party library or newer API (e.g. API 28) we can generate our own definitions using the **[Android DTS generator](#android-dts-generator)**.

## Android DTS Generator

Expand Down Expand Up @@ -154,4 +154,4 @@ By repeating the steps above, we've found that:
- Android support 23 typings(built with super jar from Android API 23) can be reused until Android API 25
- Android support 26 typings(built with super jar from Android API 26) can be reused for API 26 and 27

The corresponding typings files can be found in the `tns-platform-declarations` package. The repo's [Makefile](https://github.com/NativeScript/android-dts-generator/blob/master/Makefile) can be used as a reference for creating these typings files.
The corresponding typings files can be found in the `@nativescript/types` package. The repo's [Makefile](https://github.com/NativeScript/android-dts-generator/blob/master/Makefile) can be used as a reference for creating these typings files.
Loading