From 9ec4ad95f106ca93185367bc6f97f7ab57515fdd Mon Sep 17 00:00:00 2001 From: rosen-vladimirov Date: Thu, 2 Aug 2018 15:12:34 +0300 Subject: [PATCH] chore: Rename exposed methods and events for emulators Rename `getAvailableEmulators` to `getEmulatorImages` as we return information for all emulator images - running and not. Rename the events `emulatorImagesFound` and `emulatorImagesLost` to `emulatorImageFound` and `emulatorImageLost` as emitted data contains a single emulator image. Add docs for deviceEmitter --- PublicAPI.md | 113 ++++++++++++++++++++++++++++++++++++++++++++++++--- lib/common | 2 +- 2 files changed, 108 insertions(+), 7 deletions(-) diff --git a/PublicAPI.md b/PublicAPI.md index 216ffc7187..c6a8b29b07 100644 --- a/PublicAPI.md +++ b/PublicAPI.md @@ -53,9 +53,11 @@ const tns = require("nativescript"); * [sysInfo](#sysinfo) * [getSupportedNodeVersionRange](#getsupportednodeversionrange) * [getSystemWarnings](#getsystemwarnings) -* [devicesService](#devicesService) - * [getAvailableEmulators](#getAvailableEmulators) - * [startEmulator](#startEmulator) +* [devicesService](#devicesservice) + * [getEmulatorImages](#getemulatorimages) + * [startEmulator](#startemulator) +* [deviceEmitter](#deviceemitter) + * [events](#deviceemitterevents) ## Module projectService @@ -1204,8 +1206,8 @@ tns.sysInfo.getSystemWarnings() ## devicesService The `devicesService` module allows interaction with devices and emulators. You can get a list of the available emulators or start a specific emulator. -### getAvailableEmulators -The `getAvailableEmulators` method returns object of all running and available emulators. The result is in the following format: +### getEmulators +The `getEmulators` method returns object of all running and available emulators. The result is in the following format: ```JavaScript { android: { @@ -1223,7 +1225,7 @@ This method accepts platform parameter. If provided only devices by specified pl * Usage ```TypeScript -tns.devicesService.getAvailableEmulators() +tns.devicesService.getEmulators() .then(availableEmulatorsOutput => { Object.keys(availableEmulatorsOutput) .forEach(platform => { @@ -1240,6 +1242,105 @@ tns.devicesService.startEmulator({imageIdentifier: "my emulator imageIdentifier" .then(errors => { }); ``` +## deviceEmitter +This module is used to emit information for devices, applications on them, etc. + +### deviceEmitterEvents +`deviceEmitter` emits the following events: +`deviceEmitter` module is used to emit different events related to devices attached to the system. +You can use `deviceEmitter` to add handles for the following events: + +* `deviceFound` - Raised when a new device is attached to the system. The callback function will receive one argument - `deviceInfoData`. +Sample usage: +```JavaScript +tns.deviceEmitter.on("deviceFound", (deviceInfoData) => { + console.log("Found device with identifier: " + deviceInfoData.identifier); +}); +``` + +* `deviceLost` - Raised when a device is detached from the system. The callback function will receive one argument - `deviceInfoData`. +Sample usage: +```JavaScript +tns.deviceEmitter.on("deviceLost", (deviceInfoData) => { + console.log("Detached device with identifier: " + deviceInfoData.identifier); +}); +``` + +* `deviceLogData` - Raised when attached device reports any information. This is the output of `adb logcat` for Android devices. For iOS this is the `iOS SysLog`. +The event is raised for any device that reports data. The callback function has two arguments - `deviceIdentifier` and `reportedData`.

+Sample usage: +```JavaScript +tns.deviceEmitter.on("deviceLogData", (identifier, reportedData) => { + console.log("Device " + identifier + " reports: " + reportedData); +}); +``` + +* `applicationInstalled` - Raised when application is installed on a device. The callback has two arguments - `deviceIdentifier` and `applicationIdentifier`.

+Sample usage: +```JavaScript +tns.deviceEmitter.on("applicationInstalled", (identifier, applicationIdentifier) => { + console.log("Application " + applicationIdentifier + " has been installed on device with id: " + identifier); +}); +``` + +* `applicationUninstalled` - Raised when application is removed from device. The callback has two arguments - `deviceIdentifier` and `applicationIdentifier`.

+Sample usage: +```JavaScript +tns.deviceEmitter.on("applicationUninstalled", (identifier, applicationIdentifier) => { + console.log("Application " + applicationIdentifier + " has been uninstalled from device with id: " + identifier); +}); +``` + +* `debuggableAppFound` - Raised when application on a device becomes available for debugging. The callback has one argument - `applicationInfo`.

+Sample usage: +```JavaScript +tns.deviceEmitter.on("debuggableAppFound", (applicationInfo) => { + console.log("Application " + applicationInfo.appIdentifier + " is available for debugging on device with id: " + applicationInfo.deviceIdentifier); +}); +``` +Sample result for `applicationInfo` will be: +```JSON +{ + "deviceIdentifier": "4df18f307d8a8f1b", + "appIdentifier": "com.telerik.Fitness", + "framework": "NativeScript", + "title": "NativeScript Application" +} +``` + +* `debuggableAppLost` - Raised when application on a device is not available for debugging anymore. The callback has one argument - `applicationInfo`.

+Sample usage: +```JavaScript +tns.deviceEmitter.on("debuggableAppLost", (applicationInfo) => { + console.log("Application " + applicationInfo.appIdentifier + " is not available for debugging anymore on device with id: " + applicationInfo.deviceIdentifier); +}); +``` +Sample result for `applicationInfo` will be: +```JSON +{ + "deviceIdentifier": "4df18f307d8a8f1b", + "appIdentifier": "com.telerik.Fitness", + "framework": "NativeScript", + "title": "NativeScript Application" +} +``` + +* `emulatorImageFound` - Raised when a new Android Emulator Image or iOS Simulator is created/installed on the system. The callback has a single argument that describes the new image: +```JavaScript +tns.deviceEmitter.on("emulatorImageFound", (emulatorImageInfo) => { + console.log("Added new emulator image", emulatorImageInfo); +}); +``` +`emulatorImageInfo` is of type [Moble.IDeviceInfo](https://github.com/telerik/mobile-cli-lib/blob/61cdaaaf7533394afbbe84dd4eee355072ade2de/definitions/mobile.d.ts#L9-L86). + +* `emulatorImageLost` - Raised when an Android Emulator Image or iOS Simulator is removed from the system. The callback has a single argument that describes the removed image: +```JavaScript +tns.deviceEmitter.on("emulatorImageLost", (emulatorImageInfo) => { + console.log("Removed emulator image", emulatorImageInfo); +}); +``` +`emulatorImageInfo` is of type [Moble.IDeviceInfo](https://github.com/telerik/mobile-cli-lib/blob/61cdaaaf7533394afbbe84dd4eee355072ade2de/definitions/mobile.d.ts#L9-L86). + ## How to add a new method to Public API CLI is designed as command line tool and when it is used as a library, it does not give you access to all of the methods. This is mainly implementation detail. Most of the CLI's code is created to work in command line, not as a library, so before adding method to public API, most probably it will require some modification. For example the `$options` injected module contains information about all `--` options passed on the terminal. When the CLI is used as a library, the options are not populated. Before adding method to public API, make sure its implementation does not rely on `$options`. diff --git a/lib/common b/lib/common index 57a6eef73c..b89d237685 160000 --- a/lib/common +++ b/lib/common @@ -1 +1 @@ -Subproject commit 57a6eef73c420b0cc4d1ec2280cca6804d130b7b +Subproject commit b89d23768522987c2a56224d14d0c14997c82bc1