Repository: cordova-plugin-camera Updated Branches: refs/heads/master daf5fa48d -> 6d058fe9e
CB-11003: Added Sample section to the Camera plugin README This closes #203 Project: http://git-wip-us.apache.org/repos/asf/cordova-plugin-camera/repo Commit: http://git-wip-us.apache.org/repos/asf/cordova-plugin-camera/commit/6d058fe9 Tree: http://git-wip-us.apache.org/repos/asf/cordova-plugin-camera/tree/6d058fe9 Diff: http://git-wip-us.apache.org/repos/asf/cordova-plugin-camera/diff/6d058fe9 Branch: refs/heads/master Commit: 6d058fe9e7987e4b495e656cd4e9b347f82c26fa Parents: daf5fa4 Author: Mikejo5001 <[email protected]> Authored: Fri Apr 8 15:38:19 2016 -0700 Committer: Richard Knoll <[email protected]> Committed: Fri Apr 15 15:44:38 2016 -0700 ---------------------------------------------------------------------- README.md | 199 ++++++++++++++++++++++++++++++++++++++++++++++ jsdoc2md/TEMPLATE.md | 199 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 398 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cordova-plugin-camera/blob/6d058fe9/README.md ---------------------------------------------------------------------- diff --git a/README.md b/README.md index 6d175f0..10443bd 100644 --- a/README.md +++ b/README.md @@ -526,3 +526,202 @@ Tizen only supports a `destinationType` of [web_activities]: https://hacks.mozilla.org/2013/01/introducing-web-activities/ [wp8_bug]: https://issues.apache.org/jira/browse/CB-2083 [msdn_wp8_docs]: http://msdn.microsoft.com/en-us/library/windowsphone/develop/hh394006.aspx + +## Sample: Take Pictures, Select Pictures from the Picture Library, and Get Thumbnails <a name="sample"></a> + +The Camera plugin allows you to do things like open the device's Camera app and take a picture, or open the file picker and select one. The code snippets in this section demonstrate different tasks including: + +* Open the Camera app and [take a Picture](#takePicture) +* Take a picture and [return thumbnails](#getThumbnails) (resized picture) +* Take a picture and [generate a FileEntry object](#convert) +* [Select a file](#selectFile) from the picture library +* Select a JPEG image and [return thumbnails](#getFileThumbnails) (resized image) +* Select an image and [generate a FileEntry object](#convert) + +## Take a Picture <a name="takePicture"></a> + +Before you can take a picture, you need to set some Camera plugin options to pass into the Camera plugin's `getPicture` function. Here is a common set of recommendations. In this example, you create the object that you will use for the Camera options, and set the `sourceType` dynamically to support both the Camera app and the file picker. + +```js +function setOptions(srcType) { + var options = { + // Some common settings are 20, 50, and 100 + quality: 50, + destinationType: Camera.DestinationType.FILE_URI, + // In this app, dynamically set the picture source, Camera or photo gallery + sourceType: srcType, + encodingType: Camera.EncodingType.JPEG, + mediaType: Camera.MediaType.PICTURE, + allowEdit: true, + correctOrientation: true //Corrects Android orientation quirks + } + return options; +} +``` + +Typically, you want to use a FILE_URI instead of a DATA_URL to avoid most memory issues. JPEG is the recommended encoding type for Android. + +You take a picture by passing in the options object to `getPicture`, which takes a CameraOptions object as the third argument. When you call `setOptions`, pass `Camera.PictureSourceType.CAMERA` as the picture source. + +```js +function openCamera(selection) { + + var srcType = Camera.PictureSourceType.CAMERA; + var options = setOptions(srcType); + var func = createNewFileEntry; + + navigator.camera.getPicture(function cameraSuccess(imageUri) { + + displayImage(imageUri); + // You may choose to copy the picture, save it somewhere, or upload. + func(imageUri); + + }, function cameraError(error) { + console.debug("Unable to obtain picture: " + error, "app"); + + }, options); +} +``` + +Once you take the picture, you can display it or do something else. In this example, call the app's `displayImage` function from the preceding code. + +```js +function displayImage(imgUri) { + + var elem = document.getElementById('imageFile'); + elem.src = imgUri; +} +``` + +To display the image on some platforms, you might need to include the main part of the URI in the Content-Security-Policy <meta> element in index.html. For example, on Windows 10, you can include `ms-appdata:` in your <meta> element. Here is an example. + +```html +<meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap: ms-appdata: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *"> +``` + +## Take a Picture and Return Thumbnails (Resize the Picture) <a name="getThumbnails"></a> + +To get smaller images, you can return a resized image by passing both `targetHeight` and `targetWidth` values with your CameraOptions object. In this example, you resize the returned image to fit in a 100px by 100px box (the aspect ratio is maintained, so 100px is either the height or width, whichever is greater in the source). + +```js +function openCamera(selection) { + + var srcType = Camera.PictureSourceType.CAMERA; + var options = setOptions(srcType); + var func = createNewFileEntry; + + if (selection == "camera-thmb") { + options.targetHeight = 100; + options.targetWidth = 100; + } + + navigator.camera.getPicture(function cameraSuccess(imageUri) { + + // Do something + + }, function cameraError(error) { + console.debug("Unable to obtain picture: " + error, "app"); + + }, options); +} +``` + +## Select a File from the Picture Library <a name="selectFile"></a> + +When selecting a file using the file picker, you also need to set the CameraOptions object. In this example, set the `sourceType` to `Camera.PictureSourceType.SAVEDPHOTOALBUM`. To open the file picker, call `getPicture` just as you did in the previous example, passing in the success and error callbacks along with CameraOptions object. + +```js +function openFilePicker(selection) { + + var srcType = Camera.PictureSourceType.SAVEDPHOTOALBUM; + var options = setOptions(srcType); + var func = createNewFileEntry; + + navigator.camera.getPicture(function cameraSuccess(imageUri) { + + // Do something + + }, function cameraError(error) { + console.debug("Unable to obtain picture: " + error, "app"); + + }, options); +} +``` + +## Select an Image and Return Thumbnails (resized images) <a name="getFileThumbnails"></a> + +Resizing a file selected with the file picker works just like resizing using the Camera app; set the `targetHeight` and `targetWidth` options. + +```js +function openFilePicker(selection) { + + var srcType = Camera.PictureSourceType.SAVEDPHOTOALBUM; + var options = setOptions(srcType); + var func = createNewFileEntry; + + if (selection == "picker-thmb") { + // To downscale a selected image, + // Camera.EncodingType (e.g., JPEG) must match the selected image type. + options.targetHeight = 100; + options.targetWidth = 100; + } + + navigator.camera.getPicture(function cameraSuccess(imageUri) { + + // Do something with image + + }, function cameraError(error) { + console.debug("Unable to obtain picture: " + error, "app"); + + }, options); +} +``` + +## Take a picture and get a FileEntry Object <a name="convert"></a> + +If you want to do something like copy the image to another location, or upload it somewhere using the FileTransfer plugin, you need to get a FileEntry object for the returned picture. To do that, call `window.resolveLocalFileSystemURL` on the file URI returned by the Camera app. If you need to use a FileEntry object, set the `destinationType` to `Camera.DestinationType.FILE_URI` in your CameraOptions object (this is also the default value). + +>*Note* You need the [File plugin](https://www.npmjs.com/package/cordova-plugin-file) to call `window.resolveLocalFileSystemURL`. + +Here is the call to `window.resolveLocalFileSystemURL`. The image URI is passed to this function from the success callback of `getPicture`. The success handler of `resolveLocalFileSystemURL` receives the FileEntry object. + +```js +function getFileEntry(imgUri) { + window.resolveLocalFileSystemURL(imgUri, function success(fileEntry) { + + // Do something with the FileEntry object, like write to it, upload it, etc. + // writeFile(fileEntry, imgUri); + console.log("got file: " + fileEntry.fullPath); + // displayFileData(fileEntry.nativeURL, "Native URL"); + + }, function () { + // If don't get the FileEntry (which may happen when testing + // on some emulators), copy to a new FileEntry. + createNewFileEntry(imgUri); + }); +} +``` + +In the example shown in the preceding code, you call the app's `createNewFileEntry` function if you don't get a valid FileEntry object. The image URI returned from the Camera app should result in a valid FileEntry, but platform behavior on some emulators may be different for files returned from the file picker. + +>*Note* To see an example of writing to a FileEntry, see the [File plugin README](https://www.npmjs.com/package/cordova-plugin-file). + +The code shown here creates a file in your app's cache (in sandboxed storage) named `tempFile.jpeg`. With the new FileEntry object, you can copy the image to the file or do something else like upload it. + +```js +function createNewFileEntry(imgUri) { + window.resolveLocalFileSystemURL(cordova.file.cacheDirectory, function success(dirEntry) { + + // JPEG file + dirEntry.getFile("tempFile.jpeg", { create: true, exclusive: false }, function (fileEntry) { + + // Do something with it, like write to it, upload it, etc. + // writeFile(fileEntry, imgUri); + console.log("got file: " + fileEntry.fullPath); + // displayFileData(fileEntry.fullPath, "File copied to"); + + }, onErrorCreateFile); + + }, onErrorResolveUrl); +} +``` http://git-wip-us.apache.org/repos/asf/cordova-plugin-camera/blob/6d058fe9/jsdoc2md/TEMPLATE.md ---------------------------------------------------------------------- diff --git a/jsdoc2md/TEMPLATE.md b/jsdoc2md/TEMPLATE.md index 687b0fd..5888928 100644 --- a/jsdoc2md/TEMPLATE.md +++ b/jsdoc2md/TEMPLATE.md @@ -203,3 +203,202 @@ Tizen only supports a `destinationType` of [web_activities]: https://hacks.mozilla.org/2013/01/introducing-web-activities/ [wp8_bug]: https://issues.apache.org/jira/browse/CB-2083 [msdn_wp8_docs]: http://msdn.microsoft.com/en-us/library/windowsphone/develop/hh394006.aspx + +## Sample: Take Pictures, Select Pictures from the Picture Library, and Get Thumbnails <a name="sample"></a> + +The Camera plugin allows you to do things like open the device's Camera app and take a picture, or open the file picker and select one. The code snippets in this section demonstrate different tasks including: + +* Open the Camera app and [take a Picture](#takePicture) +* Take a picture and [return thumbnails](#getThumbnails) (resized picture) +* Take a picture and [generate a FileEntry object](#convert) +* [Select a file](#selectFile) from the picture library +* Select a JPEG image and [return thumbnails](#getFileThumbnails) (resized image) +* Select an image and [generate a FileEntry object](#convert) + +## Take a Picture <a name="takePicture"></a> + +Before you can take a picture, you need to set some Camera plugin options to pass into the Camera plugin's `getPicture` function. Here is a common set of recommendations. In this example, you create the object that you will use for the Camera options, and set the `sourceType` dynamically to support both the Camera app and the file picker. + +```js +function setOptions(srcType) { + var options = { + // Some common settings are 20, 50, and 100 + quality: 50, + destinationType: Camera.DestinationType.FILE_URI, + // In this app, dynamically set the picture source, Camera or photo gallery + sourceType: srcType, + encodingType: Camera.EncodingType.JPEG, + mediaType: Camera.MediaType.PICTURE, + allowEdit: true, + correctOrientation: true //Corrects Android orientation quirks + } + return options; +} +``` + +Typically, you want to use a FILE_URI instead of a DATA_URL to avoid most memory issues. JPEG is the recommended encoding type for Android. + +You take a picture by passing in the options object to `getPicture`, which takes a CameraOptions object as the third argument. When you call `setOptions`, pass `Camera.PictureSourceType.CAMERA` as the picture source. + +```js +function openCamera(selection) { + + var srcType = Camera.PictureSourceType.CAMERA; + var options = setOptions(srcType); + var func = createNewFileEntry; + + navigator.camera.getPicture(function cameraSuccess(imageUri) { + + displayImage(imageUri); + // You may choose to copy the picture, save it somewhere, or upload. + func(imageUri); + + }, function cameraError(error) { + console.debug("Unable to obtain picture: " + error, "app"); + + }, options); +} +``` + +Once you take the picture, you can display it or do something else. In this example, call the app's `displayImage` function from the preceding code. + +```js +function displayImage(imgUri) { + + var elem = document.getElementById('imageFile'); + elem.src = imgUri; +} +``` + +To display the image on some platforms, you might need to include the main part of the URI in the Content-Security-Policy <meta> element in index.html. For example, on Windows 10, you can include `ms-appdata:` in your <meta> element. Here is an example. + +```html +<meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap: ms-appdata: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *"> +``` + +## Take a Picture and Return Thumbnails (Resize the Picture) <a name="getThumbnails"></a> + +To get smaller images, you can return a resized image by passing both `targetHeight` and `targetWidth` values with your CameraOptions object. In this example, you resize the returned image to fit in a 100px by 100px box (the aspect ratio is maintained, so 100px is either the height or width, whichever is greater in the source). + +```js +function openCamera(selection) { + + var srcType = Camera.PictureSourceType.CAMERA; + var options = setOptions(srcType); + var func = createNewFileEntry; + + if (selection == "camera-thmb") { + options.targetHeight = 100; + options.targetWidth = 100; + } + + navigator.camera.getPicture(function cameraSuccess(imageUri) { + + // Do something + + }, function cameraError(error) { + console.debug("Unable to obtain picture: " + error, "app"); + + }, options); +} +``` + +## Select a File from the Picture Library <a name="selectFile"></a> + +When selecting a file using the file picker, you also need to set the CameraOptions object. In this example, set the `sourceType` to `Camera.PictureSourceType.SAVEDPHOTOALBUM`. To open the file picker, call `getPicture` just as you did in the previous example, passing in the success and error callbacks along with CameraOptions object. + +```js +function openFilePicker(selection) { + + var srcType = Camera.PictureSourceType.SAVEDPHOTOALBUM; + var options = setOptions(srcType); + var func = createNewFileEntry; + + navigator.camera.getPicture(function cameraSuccess(imageUri) { + + // Do something + + }, function cameraError(error) { + console.debug("Unable to obtain picture: " + error, "app"); + + }, options); +} +``` + +## Select an Image and Return Thumbnails (resized images) <a name="getFileThumbnails"></a> + +Resizing a file selected with the file picker works just like resizing using the Camera app; set the `targetHeight` and `targetWidth` options. + +```js +function openFilePicker(selection) { + + var srcType = Camera.PictureSourceType.SAVEDPHOTOALBUM; + var options = setOptions(srcType); + var func = createNewFileEntry; + + if (selection == "picker-thmb") { + // To downscale a selected image, + // Camera.EncodingType (e.g., JPEG) must match the selected image type. + options.targetHeight = 100; + options.targetWidth = 100; + } + + navigator.camera.getPicture(function cameraSuccess(imageUri) { + + // Do something with image + + }, function cameraError(error) { + console.debug("Unable to obtain picture: " + error, "app"); + + }, options); +} +``` + +## Take a picture and get a FileEntry Object <a name="convert"></a> + +If you want to do something like copy the image to another location, or upload it somewhere using the FileTransfer plugin, you need to get a FileEntry object for the returned picture. To do that, call `window.resolveLocalFileSystemURL` on the file URI returned by the Camera app. If you need to use a FileEntry object, set the `destinationType` to `Camera.DestinationType.FILE_URI` in your CameraOptions object (this is also the default value). + +>*Note* You need the [File plugin](https://www.npmjs.com/package/cordova-plugin-file) to call `window.resolveLocalFileSystemURL`. + +Here is the call to `window.resolveLocalFileSystemURL`. The image URI is passed to this function from the success callback of `getPicture`. The success handler of `resolveLocalFileSystemURL` receives the FileEntry object. + +```js +function getFileEntry(imgUri) { + window.resolveLocalFileSystemURL(imgUri, function success(fileEntry) { + + // Do something with the FileEntry object, like write to it, upload it, etc. + // writeFile(fileEntry, imgUri); + console.log("got file: " + fileEntry.fullPath); + // displayFileData(fileEntry.nativeURL, "Native URL"); + + }, function () { + // If don't get the FileEntry (which may happen when testing + // on some emulators), copy to a new FileEntry. + createNewFileEntry(imgUri); + }); +} +``` + +In the example shown in the preceding code, you call the app's `createNewFileEntry` function if you don't get a valid FileEntry object. The image URI returned from the Camera app should result in a valid FileEntry, but platform behavior on some emulators may be different for files returned from the file picker. + +>*Note* To see an example of writing to a FileEntry, see the [File plugin README](https://www.npmjs.com/package/cordova-plugin-file). + +The code shown here creates a file in your app's cache (in sandboxed storage) named `tempFile.jpeg`. With the new FileEntry object, you can copy the image to the file or do something else like upload it. + +```js +function createNewFileEntry(imgUri) { + window.resolveLocalFileSystemURL(cordova.file.cacheDirectory, function success(dirEntry) { + + // JPEG file + dirEntry.getFile("tempFile.jpeg", { create: true, exclusive: false }, function (fileEntry) { + + // Do something with it, like write to it, upload it, etc. + // writeFile(fileEntry, imgUri); + console.log("got file: " + fileEntry.fullPath); + // displayFileData(fileEntry.fullPath, "File copied to"); + + }, onErrorCreateFile); + + }, onErrorResolveUrl); +} +``` --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
