Skip to content

Update readme #229

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

Update readme #229

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fadc63b
docs(README): improve example codes
luizbills Oct 16, 2019
645d0c1
Merge branch 'luizbills-patch-1' into update-readme
Oct 21, 2019
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
117 changes: 72 additions & 45 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,12 +42,12 @@ npm install nativescript-camera --save
### CameraOptions
| Property | Default | Platform | Description |
| --- | --- | --- | --- |
| width | 0 | Both | Defines the desired width (in device independent pixels) of the taken image. It should be used with height property. If `keepAspectRatio` actual image width could be different in order to keep the aspect ratio of the original camera image. The actual image width will be greater than requested if the display density of the device is higher (than 1) (full HD+ resolutions). |
| height | 0 | Both | Defines the desired height (in device independent pixels) of the taken image. It should be used with width property. If `keepAspectRatio` actual image width could be different in order to keep the aspect ratio of the original camera image. The actual image height will be greater than requested if the display density of the device is higher (than 1) (full HD+ resolutions). |
| width | 0 | Both | Defines the desired width (in device independent pixels) of the taken image. It should be used with `height` property. If `keepAspectRatio` actual image width could be different in order to keep the aspect ratio of the original camera image. The actual image width will be greater than requested if the display density of the device is higher (than 1) (full HD+ resolutions). |
| height | 0 | Both | Defines the desired height (in device independent pixels) of the taken image. It should be used with `width` property. If `keepAspectRatio` actual image width could be different in order to keep the aspect ratio of the original camera image. The actual image height will be greater than requested if the display density of the device is higher (than 1) (full HD+ resolutions). |
| keepAspectRatio | true | Both | Defines if camera picture aspect ratio should be kept during picture resizing. This property could affect width or height return values. |
| saveToGallery | true | Both | Defines if camera picture should be copied to photo Gallery (Android) or Photos (iOS) |
| allowsEditing | false | iOS | Defines if camera "Retake" or "Use Photo" screen forces the user to crop camera picture to a square and optionally lets them zoom in. |
| cameraFacing | rear | Both | The initial camera facing. Use 'front' for selfies. |
| cameraFacing | rear | Both | The initial camera facing. Use `'front'` for selfies. |


> Note: The `saveToGallery` option might have unexpected behavior on Android! Some vendor camera apps (e.g. LG) will save all captured images to the gallery regardless of what the value of `saveToGallery` is. This behavior cannot be controlled by the camera plugin and if you must exclude the captured image from the photo gallery, you will need to get a local storage read/write permission and write custom code to find the gallery location and delete the new image from there.
Expand All @@ -60,14 +60,14 @@ Both Android and iOS require explicit permissions in order for the application t

```JavaScript
camera.requestPermissions().then(
function success() {
// permission request accepted or already granted
// ... call camera.takePicture here ...
},
function failure() {
// permission request rejected
// ... tell the user ...
}
function success() {
// permission request accepted or already granted
// ... call camera.takePicture here ...
},
function failure() {
// permission request rejected
// ... tell the user ...
}
);
```

Expand All @@ -84,23 +84,28 @@ function failure() {

### Using the camera module to take a picture

Using the camera module is relatively simple.
Using the camera module is relatively simple.
However, there are some points that need a little bit more explanation.

In order to use the camera module, just require it, as shown in Example 1:

> Example 1: Require camera module in the application
``` JavaScript
var camera = require("nativescript-camera");
```JavaScript
// JavaScript
const camera = require("nativescript-camera");
```
``` TypeScript

```TypeScript
// TypeScript
import * as camera from "nativescript-camera";
```

Then you are ready to use it:
> Example 2: How to take a picture and to receive image asset
``` JavaScript
var imageModule = require("tns-core-modules/ui/image");
```JavaScript
// JavaScript
const imageModule = require("tns-core-modules/ui/image");

camera.takePicture()
.then(function (imageAsset) {
console.log("Result is an image asset instance");
Expand All @@ -110,10 +115,13 @@ camera.takePicture()
console.log("Error -> " + err.message);
});
```
``` TypeScript

```TypeScript
// TypeScript
import { Image } from "tns-core-modules/ui/image";
camera.takePicture().
then((imageAsset) => {

camera.takePicture()
.then((imageAsset) => {
console.log("Result is an image asset instance");
var image = new Image();
image.src = imageAsset;
Expand Down Expand Up @@ -141,10 +149,17 @@ Setting the `keepAspectRatio` property could result in a different than requeste
__Example 3__ shows how to use the options parameter:
> Example 3: How to setup `width`, `height`, `keepAspectRatio` and `saveToGallery` properties for the camera module

``` JavaScript
var imageModule = require("tns-core-modules/ui/image");
```JavaScript
// JavaScript
const imageModule = require("tns-core-modules/ui/image");

const options = {
width: 300,
height: 300,
keepAspectRatio: false,
saveToGallery: true
};

var options = { width: 300, height: 300, keepAspectRatio: false, saveToGallery: true };
camera.takePicture(options)
.then(function (imageAsset) {
console.log("Size: " + imageAsset.options.width + "x" + imageAsset.options.height);
Expand All @@ -154,12 +169,20 @@ camera.takePicture(options)
console.log("Error -> " + err.message);
});
```
``` TypeScript

```TypeScript
// TypeScript
import { Image } from "tns-core-modules/ui/image";

var options = { width: 300, height: 300, keepAspectRatio: false, saveToGallery: true };
camera.takePicture(options).
then((imageAsset) => {
const options = {
width: 300,
height: 300,
keepAspectRatio: false,
saveToGallery: true
};

camera.takePicture(options)
.then((imageAsset) => {
console.log("Size: " + imageAsset.options.width + "x" + imageAsset.options.height);
console.log("keepAspectRatio: " + imageAsset.options.keepAspectRatio);
console.log("Photo saved in Photos/Gallery for Android or in Camera Roll for iOS");
Expand All @@ -170,22 +193,24 @@ camera.takePicture(options).

### Save a picture

To save a picture with the width & height that you have defined you must use the imageAsset and save it to the file system like so:

``` TypeScript
const source = new ImageSource();
source.fromAsset(imageAsset)
.then((imageSource: ImageSource) => {
const folderPath = knownFolders.documents().path;
const fileName = "test.jpg";
const filePath = path.join(folderPath, fileName);
const saved: boolean = imageSource.saveToFile(filePath, "jpg");
if (saved) {
console.log("Gallery: " + this._dataItem.picture_url);
console.log("Saved: " + filePath);
console.log("Image saved successfully!");
}
});
To save a picture with the width & height that you have defined you must use the `imageAsset` and save it to the file system like so:

```TypeScript
const source = new ImageSource();

source.fromAsset(imageAsset)
.then((imageSource: ImageSource) => {
const folderPath: string = knownFolders.documents().path;
const fileName: string = "test.jpg";
const filePath: string = path.join(folderPath, fileName);
const saved: boolean = imageSource.saveToFile(filePath, "jpg");

if (saved) {
console.log("Gallery: " + this._dataItem.picture_url);
console.log("Saved: " + filePath);
console.log("Image saved successfully!");
}
});
```

This could be used to create thumbnails for quick display within your application.
Expand All @@ -196,15 +221,17 @@ The first thing that the developers should check if the device has an available
The method isAvaiable will return true if the camera hardware is ready to use or false if otherwise.

```
var isAvailable = camera.isAvailable();
const isAvailable = camera.isAvailable();
```

> Note: This method will return false when used in iOS simulator (as the simulator does not have camera hardware)

## Contribute

We love PRs! Check out the [contributing guidelines](CONTRIBUTING.md). If you want to contribute, but you are not sure where to start - look for [issues labeled `help wanted`](https://github.com/NativeScript/nativescript-camera/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22).

## Get Help
## Get Help

Please, use [github issues](https://github.com/NativeScript/nativescript-camera/issues) strictly for [reporting bugs](CONTRIBUTING.md#reporting-bugs) or [requesting features](CONTRIBUTING.md#requesting-new-features). For general questions and support, check out [Stack Overflow](https://stackoverflow.com/questions/tagged/nativescript) or ask our experts in [NativeScript community Slack channel](http://developer.telerik.com/wp-login.php?action=slack-invitation).

![](https://ga-beacon.appspot.com/UA-111455-24/nativescript/nativescript-camera?pixel)