cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From agri...@apache.org
Subject [6/8] git commit: CB-5658 Add doc.index.md for Camera plugin
Date Thu, 02 Jan 2014 18:06:28 GMT
CB-5658 Add doc.index.md for Camera plugin


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/bf105f98
Tree: http://git-wip-us.apache.org/repos/asf/cordova-plugin-camera/tree/bf105f98
Diff: http://git-wip-us.apache.org/repos/asf/cordova-plugin-camera/diff/bf105f98

Branch: refs/heads/master
Commit: bf105f9832cbb2a78ff06df4e94d61ca8fc08c8e
Parents: 7574e66
Author: Andrew Grieve <agrieve@chromium.org>
Authored: Wed Dec 18 11:31:45 2013 -0500
Committer: Andrew Grieve <agrieve@chromium.org>
Committed: Wed Dec 18 11:31:45 2013 -0500

----------------------------------------------------------------------
 README.md    |  25 +++-
 doc/index.md | 414 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 435 insertions(+), 4 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cordova-plugin-camera/blob/bf105f98/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index 983346d..f84180e 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,22 @@
-cordova-plugin-camera
-==========================
-To install this plugin, follow the [Command-line Interface Guide](http://cordova.apache.org/docs/en/edge/guide_cli_index.md.html#The%20Command-line%20Interface).
+<!---
+ license: Licensed to the Apache Software Foundation (ASF) under one
+         or more contributor license agreements.  See the NOTICE file
+         distributed with this work for additional information
+         regarding copyright ownership.  The ASF licenses this file
+         to you under the Apache License, Version 2.0 (the
+         "License"); you may not use this file except in compliance
+         with the License.  You may obtain a copy of the License at
 
-If you are not using the Cordova Command-line Interface, follow [Using Plugman to Manage
Plugins](http://cordova.apache.org/docs/en/edge/plugin_ref_plugman.md.html).
+           http://www.apache.org/licenses/LICENSE-2.0
+
+         Unless required by applicable law or agreed to in writing,
+         software distributed under the License is distributed on an
+         "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+         KIND, either express or implied.  See the License for the
+         specific language governing permissions and limitations
+         under the License.
+-->
+
+# org.apache.cordova.camera
+
+Plugin documentation: [doc/index.md](doc/index.md)

http://git-wip-us.apache.org/repos/asf/cordova-plugin-camera/blob/bf105f98/doc/index.md
----------------------------------------------------------------------
diff --git a/doc/index.md b/doc/index.md
new file mode 100644
index 0000000..c9d4c02
--- /dev/null
+++ b/doc/index.md
@@ -0,0 +1,414 @@
+<!---
+ license: Licensed to the Apache Software Foundation (ASF) under one
+         or more contributor license agreements.  See the NOTICE file
+         distributed with this work for additional information
+         regarding copyright ownership.  The ASF licenses this file
+         to you under the Apache License, Version 2.0 (the
+         "License"); you may not use this file except in compliance
+         with the License.  You may obtain a copy of the License at
+
+           http://www.apache.org/licenses/LICENSE-2.0
+
+         Unless required by applicable law or agreed to in writing,
+         software distributed under the License is distributed on an
+         "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+         KIND, either express or implied.  See the License for the
+         specific language governing permissions and limitations
+         under the License.
+-->
+
+# org.apache.cordova.camera
+
+This plugin provides an API for taking pictures and for choosing images from
+the system's image libarary.
+
+    cordova plugin add org.apache.cordova.camera
+
+
+## navigator.camera.getPicture
+
+Takes a photo using the camera, or retrieves a photo from the device's
+image gallery.  The image is passed to the success callback as a
+base64-encoded `String`, or as the URI for the image file.  The method
+itself returns a `CameraPopoverHandle` object that can be used to
+reposition the file selection popover.
+
+    navigator.camera.getPicture( cameraSuccess, cameraError, [ cameraOptions ] );
+
+### Description
+
+The `camera.getPicture` function opens the device's default camera
+application that allows users to snap pictures. This behavior occurs
+by default, when `Camera.sourceType` equals
+`Camera.PictureSourceType.CAMERA`.  Once the user snaps the photo, the
+camera application closes and the application is restored.
+
+If `Camera.sourceType` is `Camera.PictureSourceType.PHOTOLIBRARY` or
+`Camera.PictureSourceType.SAVEDPHOTOALBUM`, then a dialog displays
+that allows users to select an existing image.  The
+`camera.getPicture` function returns a `CameraPopoverHandle` object,
+which can be used to reposition the image selection dialog, for
+example, when the device orientation changes.
+
+The return value is sent to the `cameraSuccess` callback function, in
+one of the following formats, depending on the specified
+`cameraOptions`:
+
+- A `String` containing the base64-encoded photo image.
+
+- A `String` representing the image file location on local storage (default).
+
+You can do whatever you want with the encoded image or URI, for
+example:
+
+- Render the image in an `<img>` tag, as in the example below
+
+- Save the data locally (`LocalStorage`, [Lawnchair](http://brianleroux.github.com/lawnchair/),
etc.)
+
+- Post the data to a remote server
+
+__NOTE__: Photo resolution on newer devices is quite good. Photos
+selected from the device's gallery are not downscaled to a lower
+quality, even if a `quality` parameter is specified.  To avoid common
+memory problems, set `Camera.destinationType` to `FILE_URI` rather
+than `DATA_URL`.
+
+### Supported Platforms
+
+- Amazon Fire OS
+- Android
+- BlackBerry 10
+- iOS
+- Tizen
+- Windows Phone 7 and 8
+- Windows 8
+
+### Amazon Fire OS Quirks
+
+Amazon Fire OS uses intents to launch the camera activity on the device to capture
+images, and on phones with low memory, the Cordova activity may be killed.  In this
+scenario, the image may not appear when the cordova activity is restored.
+
+### Android Quirks
+
+*Android 4.4 only*: Android 4.4 introduced a new [Storage Access Framework](https://developer.android.com/guide/topics/providers/document-provider.html)
that makes it 
+easier for users to browse and open documents across all of their preferred document storage
providers.
+Cordova has not yet been fully integrated with this new Storage Access Framework. Because
of this, the `getPicture()`
+method will not correctly return pictures when the user selects from the "Recent", "Drive",
"Images", or "External
+Storage" folders when the `destinationType` is `FILE_URI`. However, the user will be able
to correctly select any pictures
+if they go through the "Gallery" app first. Potential workarounds for this issue are documented
on [this StackOverflow question](http://stackoverflow.com/questions/19834842/android-gallery-on-kitkat-returns-different-uri-for-intent-action-get-content/20177611).
Please see [CB-5398](https://issues.apache.org/jira/browse/CB-5398) to track this issue. 
+
+Android uses intents to launch the camera activity on the device to capture
+images, and on phones with low memory, the Cordova activity may be killed.  In this
+scenario, the image may not appear when the Cordova activity is restored.
+
+### iOS Quirks
+
+Including a JavaScript `alert()` in either of the callback functions
+can cause problems.  Wrap the alert within a `setTimeout()` to allow
+the iOS image picker or popover to fully close before the alert
+displays:
+
+    setTimeout(function() {
+        // do your thing here!
+    }, 0);
+
+### Windows Phone 7 Quirks
+
+Invoking the native camera application while the device is connected
+via Zune does not work, and triggers an error callback.
+
+### Tizen Quirks
+
+Tizen only supports a `destinationType` of
+`Camera.DestinationType.FILE_URI` and a `sourceType` of
+`Camera.PictureSourceType.PHOTOLIBRARY`.
+
+### Example
+
+Take a photo and retrieve it as a base64-encoded image:
+
+    navigator.camera.getPicture(onSuccess, onFail, { quality: 50,
+        destinationType: Camera.DestinationType.DATA_URL
+    });
+
+    function onSuccess(imageData) {
+        var image = document.getElementById('myImage');
+        image.src = "data:image/jpeg;base64," + imageData;
+    }
+
+    function onFail(message) {
+        alert('Failed because: ' + message);
+    }
+
+Take a photo and retrieve the image's file location:
+
+    navigator.camera.getPicture(onSuccess, onFail, { quality: 50,
+        destinationType: Camera.DestinationType.FILE_URI });
+
+    function onSuccess(imageURI) {
+        var image = document.getElementById('myImage');
+        image.src = imageURI;
+    }
+
+    function onFail(message) {
+        alert('Failed because: ' + message);
+    }
+
+## CameraOptions
+
+Optional parameters to customize the camera settings.
+
+    { quality : 75,
+      destinationType : Camera.DestinationType.DATA_URL,
+      sourceType : Camera.PictureSourceType.CAMERA,
+      allowEdit : true,
+      encodingType: Camera.EncodingType.JPEG,
+      targetWidth: 100,
+      targetHeight: 100,
+      popoverOptions: CameraPopoverOptions,
+      saveToPhotoAlbum: false };
+
+### Options
+
+- __quality__: Quality of the saved image, expressed as a range of 0-100, where 100 is typically
full resolution with no loss from file compression. _(Number)_ (Note that information about
the camera's resolution is unavailable.)
+
+- __destinationType__: Choose the format of the return value. Defined in `navigator.camera.DestinationType`
_(Number)_
+
+        Camera.DestinationType = {
+            DATA_URL : 0,      // Return image as base64-encoded string
+            FILE_URI : 1,      // Return image file URI
+            NATIVE_URI : 2     // Return image native URI (e.g., assets-library:// on iOS
or content:// on Android)
+        };
+
+- __sourceType__: Set the source of the picture.  Defined in `navigator.camera.PictureSourceType`
_(Number)_
+
+        Camera.PictureSourceType = {
+            PHOTOLIBRARY : 0,
+            CAMERA : 1,
+            SAVEDPHOTOALBUM : 2
+        };
+
+- __allowEdit__: Allow simple editing of image before selection. _(Boolean)_
+
+- __encodingType__: Choose the  returned image file's encoding.  Defined in `navigator.camera.EncodingType`
_(Number)_
+
+        Camera.EncodingType = {
+            JPEG : 0,               // Return JPEG encoded image
+            PNG : 1                 // Return PNG encoded image
+        };
+
+- __targetWidth__: Width in pixels to scale image. Must be used with __targetHeight__.  Aspect
ratio remains constant. _(Number)_
+
+- __targetHeight__: Height in pixels to scale image. Must be used with __targetWidth__. Aspect
ratio remains constant. _(Number)_
+
+- __mediaType__: Set the type of media to select from.  Only works when `PictureSourceType`
is `PHOTOLIBRARY` or `SAVEDPHOTOALBUM`. Defined in `nagivator.camera.MediaType` _(Number)_
+
+        Camera.MediaType = {
+            PICTURE: 0,    // allow selection of still pictures only. DEFAULT. Will return
format specified via DestinationType
+            VIDEO: 1,      // allow selection of video only, WILL ALWAYS RETURN FILE_URI
+            ALLMEDIA : 2   // allow selection from all media types
+};
+
+- __correctOrientation__: Rotate the image to correct for the orientation of the device during
capture. _(Boolean)_
+
+- __saveToPhotoAlbum__: Save the image to the photo album on the device after capture. _(Boolean)_
+
+- __popoverOptions__: iOS-only options that specify popover location in iPad.  Defined in
`CameraPopoverOptions`.
+
+- __cameraDirection__: Choose the camera to use (front- or back-facing).  Defined in `navigator.camera.Direction`
_(Number)_
+
+        Camera.Direction = {
+            BACK : 0,      // Use the back-facing camera
+            FRONT : 1      // Use the front-facing camera
+        };
+
+### Amazon Fire OSQuirks
+
+- Any `cameraDirection` value results in a back-facing photo.
+
+- Ignores the `allowEdit` parameter.
+
+- `Camera.PictureSourceType.PHOTOLIBRARY` and `Camera.PictureSourceType.SAVEDPHOTOALBUM`
both display the same photo album.
+
+### Android Quirks
+
+- Any `cameraDirection` value results in a back-facing photo.
+
+- Ignores the `allowEdit` parameter.
+
+- `Camera.PictureSourceType.PHOTOLIBRARY` and `Camera.PictureSourceType.SAVEDPHOTOALBUM`
both display the same photo album.
+
+### BlackBerry 10 Quirks
+
+- Ignores the `quality` parameter.
+
+- Ignores the `sourceType` parameter.
+
+- Ignores the `allowEdit` parameter.
+
+- `Camera.MediaType` is not supported.
+
+- Ignores the `correctOrientation` parameter.
+
+- Ignores the `cameraDirection` parameter.
+
+### iOS Quirks
+
+- Set `quality` below 50 to avoid memory errors on some devices.
+
+- When using `destinationType.FILE_URI`, photos are saved in the application's temporary
directory.  You may delete the contents of this directory using the `navigator.fileMgr` APIs
if storage space is a concern.
+
+### Tizen Quirks
+
+- options not supported
+
+- always returns a FILE URI
+
+### Windows Phone 7 and 8 Quirks
+
+- Ignores the `allowEdit` parameter.
+
+- Ignores the `correctOrientation` parameter.
+
+- Ignores the `cameraDirection` parameter.
+
+
+## CameraError
+
+onError callback function that provides an error message.
+
+    function(message) {
+        // Show a helpful message
+    }
+
+### Parameters
+
+- __message__: The message is provided by the device's native code. _(String)_
+
+
+## cameraSuccess
+
+onSuccess callback function that provides the image data.
+
+    function(imageData) {
+        // Do something with the image
+    }
+
+### Parameters
+
+- __imageData__: Base64 encoding of the image data, _or_ the image file URI, depending on
`cameraOptions` in effect. _(String)_
+
+### Example
+
+    // Show image
+    //
+    function cameraCallback(imageData) {
+        var image = document.getElementById('myImage');
+        image.src = "data:image/jpeg;base64," + imageData;
+    }
+
+
+## CameraPopoverHandle
+
+A handle to the popover dialog created by `navigator.camera.getPicture`.
+
+### Methods
+
+- __setPosition__: Set the position of the popover.
+
+### Supported Platforms
+
+- iOS
+
+### setPosition
+
+Set the position of the popover.
+
+__Parameters__:
+
+- `cameraPopoverOptions`: the `CameraPopoverOptions` that specify the new position
+
+### Example
+
+     var cameraPopoverHandle = navigator.camera.getPicture(onSuccess, onFail,
+         { destinationType: Camera.DestinationType.FILE_URI,
+           sourceType: Camera.PictureSourceType.PHOTOLIBRARY,
+           popoverOptions: new CameraPopoverOptions(300, 300, 100, 100, Camera.PopoverArrowDirection.ARROW_ANY)
+         });
+
+     // Reposition the popover if the orientation changes.
+     window.onorientationchange = function() {
+         var cameraPopoverOptions = new CameraPopoverOptions(0, 0, 100, 100, Camera.PopoverArrowDirection.ARROW_ANY);
+         cameraPopoverHandle.setPosition(cameraPopoverOptions);
+     }
+
+
+## CameraPopoverOptions
+
+iOS-only parameters that specify the anchor element location and arrow
+direction of the popover when selecting images from an iPad's library
+or album.
+
+    { x : 0,
+      y :  32,
+      width : 320,
+      height : 480,
+      arrowDir : Camera.PopoverArrowDirection.ARROW_ANY
+    };
+
+### CameraPopoverOptions
+
+- __x__: x pixel coordinate of screen element onto which to anchor the popover. _(Number)_
+
+- __y__: y pixel coordinate of screen element onto which to anchor the popover. _(Number)_
+
+- __width__: width, in pixels, of the screen element onto which to anchor the popover. _(Number)_
+
+- __height__: height, in pixels, of the screen element onto which to anchor the popover.
_(Number)_
+
+- __arrowDir__: Direction the arrow on the popover should point.  Defined in `Camera.PopoverArrowDirection`
_(Number)_
+
+            Camera.PopoverArrowDirection = {
+                ARROW_UP : 1,        // matches iOS UIPopoverArrowDirection constants
+                ARROW_DOWN : 2,
+                ARROW_LEFT : 4,
+                ARROW_RIGHT : 8,
+                ARROW_ANY : 15
+            };
+
+Note that the size of the popover may change to adjust to the
+direction of the arrow and orientation of the screen.  Make sure to
+account for orientation changes when specifying the anchor element
+location.
+
+## navigator.camera.cleanup
+
+Removes intermediate photos taken by the camera from temporary
+storage.
+
+    navigator.camera.cleanup( cameraSuccess, cameraError );
+
+### Description
+
+Removes intermediate image files that are kept in temporary storage
+after calling `camera.getPicture`. Applies only when the value of
+`Camera.sourceType` equals `Camera.PictureSourceType.CAMERA` and the
+`Camera.destinationType` equals `Camera.DestinationType.FILE_URI`.
+
+### Supported Platforms
+
+- iOS
+
+### Example
+
+    navigator.camera.cleanup(onSuccess, onFail);
+
+    function onSuccess() {
+        console.log("Camera cleanup success.")
+    }
+
+    function onFail(message) {
+        alert('Failed because: ' + message);
+    }
+


Mime
View raw message