Camera.js 7.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185
  1. /*
  2. *
  3. * Licensed to the Apache Software Foundation (ASF) under one
  4. * or more contributor license agreements. See the NOTICE file
  5. * distributed with this work for additional information
  6. * regarding copyright ownership. The ASF licenses this file
  7. * to you under the Apache License, Version 2.0 (the
  8. * "License"); you may not use this file except in compliance
  9. * with the License. You may obtain a copy of the License at
  10. *
  11. * http://www.apache.org/licenses/LICENSE-2.0
  12. *
  13. * Unless required by applicable law or agreed to in writing,
  14. * software distributed under the License is distributed on an
  15. * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  16. * KIND, either express or implied. See the License for the
  17. * specific language governing permissions and limitations
  18. * under the License.
  19. *
  20. */
  21. var argscheck = require('cordova/argscheck'),
  22. exec = require('cordova/exec'),
  23. Camera = require('./Camera');
  24. // XXX: commented out
  25. //CameraPopoverHandle = require('./CameraPopoverHandle');
  26. /**
  27. * @namespace navigator
  28. */
  29. /**
  30. * @exports camera
  31. */
  32. var cameraExport = {};
  33. // Tack on the Camera Constants to the base camera plugin.
  34. for (var key in Camera) {
  35. cameraExport[key] = Camera[key];
  36. }
  37. /**
  38. * Callback function that provides an error message.
  39. * @callback module:camera.onError
  40. * @param {string} message - The message is provided by the device's native code.
  41. */
  42. /**
  43. * Callback function that provides the image data.
  44. * @callback module:camera.onSuccess
  45. * @param {string} imageData - Base64 encoding of the image data, _or_ the image file URI, depending on [`cameraOptions`]{@link module:camera.CameraOptions} in effect.
  46. * @example
  47. * // Show image
  48. * //
  49. * function cameraCallback(imageData) {
  50. * var image = document.getElementById('myImage');
  51. * image.src = "data:image/jpeg;base64," + imageData;
  52. * }
  53. */
  54. /**
  55. * Optional parameters to customize the camera settings.
  56. * * [Quirks](#CameraOptions-quirks)
  57. * @typedef module:camera.CameraOptions
  58. * @type {Object}
  59. * @property {number} [quality=50] - Quality of the saved image, expressed as a range of 0-100, where 100 is typically full resolution with no loss from file compression. (Note that information about the camera's resolution is unavailable.)
  60. * @property {module:Camera.DestinationType} [destinationType=FILE_URI] - Choose the format of the return value.
  61. * @property {module:Camera.PictureSourceType} [sourceType=CAMERA] - Set the source of the picture.
  62. * @property {Boolean} [allowEdit=true] - Allow simple editing of image before selection.
  63. * @property {module:Camera.EncodingType} [encodingType=JPEG] - Choose the returned image file's encoding.
  64. * @property {number} [targetWidth] - Width in pixels to scale image. Must be used with `targetHeight`. Aspect ratio remains constant.
  65. * @property {number} [targetHeight] - Height in pixels to scale image. Must be used with `targetWidth`. Aspect ratio remains constant.
  66. * @property {module:Camera.MediaType} [mediaType=PICTURE] - Set the type of media to select from. Only works when `PictureSourceType` is `PHOTOLIBRARY` or `SAVEDPHOTOALBUM`.
  67. * @property {Boolean} [correctOrientation] - Rotate the image to correct for the orientation of the device during capture.
  68. * @property {Boolean} [saveToPhotoAlbum] - Save the image to the photo album on the device after capture.
  69. * @property {module:CameraPopoverOptions} [popoverOptions] - iOS-only options that specify popover location in iPad.
  70. * @property {module:Camera.Direction} [cameraDirection=BACK] - Choose the camera to use (front- or back-facing).
  71. */
  72. /**
  73. * @description Takes a photo using the camera, or retrieves a photo from the device's
  74. * image gallery. The image is passed to the success callback as a
  75. * Base64-encoded `String`, or as the URI for the image file.
  76. *
  77. * The `camera.getPicture` function opens the device's default camera
  78. * application that allows users to snap pictures by default - this behavior occurs,
  79. * when `Camera.sourceType` equals [`Camera.PictureSourceType.CAMERA`]{@link module:Camera.PictureSourceType}.
  80. * Once the user snaps the photo, the camera application closes and the application is restored.
  81. *
  82. * If `Camera.sourceType` is `Camera.PictureSourceType.PHOTOLIBRARY` or
  83. * `Camera.PictureSourceType.SAVEDPHOTOALBUM`, then a dialog displays
  84. * that allows users to select an existing image.
  85. *
  86. * The return value is sent to the [`cameraSuccess`]{@link module:camera.onSuccess} callback function, in
  87. * one of the following formats, depending on the specified
  88. * `cameraOptions`:
  89. *
  90. * - A `String` containing the Base64-encoded photo image.
  91. * - A `String` representing the image file location on local storage (default).
  92. *
  93. * You can do whatever you want with the encoded image or URI, for
  94. * example:
  95. *
  96. * - Render the image in an `<img>` tag, as in the example below
  97. * - Save the data locally (`LocalStorage`, [Lawnchair](http://brianleroux.github.com/lawnchair/), etc.)
  98. * - Post the data to a remote server
  99. *
  100. * __NOTE__: Photo resolution on newer devices is quite good. Photos
  101. * selected from the device's gallery are not downscaled to a lower
  102. * quality, even if a `quality` parameter is specified. To avoid common
  103. * memory problems, set `Camera.destinationType` to `FILE_URI` rather
  104. * than `DATA_URL`.
  105. *
  106. * __Supported Platforms__
  107. *
  108. * - Android
  109. * - BlackBerry
  110. * - Browser
  111. * - Firefox
  112. * - FireOS
  113. * - iOS
  114. * - Windows
  115. * - WP8
  116. * - Ubuntu
  117. *
  118. * More examples [here](#camera-getPicture-examples). Quirks [here](#camera-getPicture-quirks).
  119. *
  120. * @example
  121. * navigator.camera.getPicture(cameraSuccess, cameraError, cameraOptions);
  122. * @param {module:camera.onSuccess} successCallback
  123. * @param {module:camera.onError} errorCallback
  124. * @param {module:camera.CameraOptions} options CameraOptions
  125. */
  126. cameraExport.getPicture = function(successCallback, errorCallback, options) {
  127. argscheck.checkArgs('fFO', 'Camera.getPicture', arguments);
  128. options = options || {};
  129. var getValue = argscheck.getValue;
  130. var quality = getValue(options.quality, 50);
  131. var destinationType = getValue(options.destinationType, Camera.DestinationType.FILE_URI);
  132. var sourceType = getValue(options.sourceType, Camera.PictureSourceType.CAMERA);
  133. var targetWidth = getValue(options.targetWidth, -1);
  134. var targetHeight = getValue(options.targetHeight, -1);
  135. var encodingType = getValue(options.encodingType, Camera.EncodingType.JPEG);
  136. var mediaType = getValue(options.mediaType, Camera.MediaType.PICTURE);
  137. var allowEdit = !!options.allowEdit;
  138. var correctOrientation = !!options.correctOrientation;
  139. var saveToPhotoAlbum = !!options.saveToPhotoAlbum;
  140. var popoverOptions = getValue(options.popoverOptions, null);
  141. var cameraDirection = getValue(options.cameraDirection, Camera.Direction.BACK);
  142. var args = [quality, destinationType, sourceType, targetWidth, targetHeight, encodingType,
  143. mediaType, allowEdit, correctOrientation, saveToPhotoAlbum, popoverOptions, cameraDirection];
  144. exec(successCallback, errorCallback, "Camera", "takePicture", args);
  145. // XXX: commented out
  146. //return new CameraPopoverHandle();
  147. };
  148. /**
  149. * Removes intermediate image files that are kept in temporary storage
  150. * after calling [`camera.getPicture`]{@link module:camera.getPicture}. Applies only when the value of
  151. * `Camera.sourceType` equals `Camera.PictureSourceType.CAMERA` and the
  152. * `Camera.destinationType` equals `Camera.DestinationType.FILE_URI`.
  153. *
  154. * __Supported Platforms__
  155. *
  156. * - iOS
  157. *
  158. * @example
  159. * navigator.camera.cleanup(onSuccess, onFail);
  160. *
  161. * function onSuccess() {
  162. * console.log("Camera cleanup success.")
  163. * }
  164. *
  165. * function onFail(message) {
  166. * alert('Failed because: ' + message);
  167. * }
  168. */
  169. cameraExport.cleanup = function(successCallback, errorCallback) {
  170. exec(successCallback, errorCallback, "Camera", "cleanup", []);
  171. };
  172. module.exports = cameraExport;