choosePic

Camera

Launches the native gallery app with camera roll album open for the user to choose a picture. Optionally, the chosen picture can be written to a specific location in the app.

$m.choosePic(function(response) {

        if(response.code){

// set the src of the image to the selected picture

                juci.controls.get("selected-pic").value(response.result.path);

        } else{

// show error as toast message.

                $m.toast(response.error.message);

        }

});

Syntax

        $m.choosePic(fp_callback)

        $m.choosePic(options, fp_callback)

Parameters

fp_callback

function (required)

Function that is invoked when the user has chosen a picture in the native gallery app. The function receives a response object with the following properties,

  1. code - {Number}. The value can be 0 or 1. 1 indicates that a picture has been chosen and written to the specified options.filePath, if provided. 0 indicates a failure.

  1. result - {Object}. Available when the code is 1. The result object contains,
  1. path - {String}. Path of the picture. The path returned by the native gallery app has url schemes specific to operating system like assets:// or content://, while the mowbly page (html) layer can render only file:// or http://. So the chosen picture is temporarily stored in cache dir and its path is returned. Hence, app should not store any references to this path either in preferences or in the page as the cached picture will be removed by the app framework anytime. However,  when options.filePath is provided, these constraints don’t apply.
  2. data - {String}. Base64 encoded string of the picture data. This is available only when the options.readData is set to true.

  1. error - {Object}. Available when the code is 0. The error object contains,
  1. message - {String}. A short description of the error.
  2. description - {String}. A detailed description of the error.

options

object (optional)  

Optional parameters for the choose picture operation. The options object overrides the default options set using the camSetup method.The object can contain the following properties,

  1. filePath - {Optional. String/File}. Path to store the chosen picture. The path, if provided as string is considered relative to the pack folder. Refer getFile method to get a mowbly file object. No default value.

  1. quality - {Optional. Number}. Quality of the chosen picture when returned. Default value is $m.CAM_QUALITY_MED. This quality value denotes the compression rate of the captured picture. Higher the quality higher the time taken to process the picture and the memory usage. Supported values are:
  1. $m.CAM_QUALITY_LOW
  2. $m.CAM_QUALITY_MED
  3. $m.CAM_QUALITY_HIGH

The actual picture in the gallery is not affected by this property, but the copy of the picture written to the options.filePath provided will be compressed to the specified quality.

  1. readData - {Optional. Boolean}. Flag that denotes if the picture data should be returned to the fp_callback function. The picture data will be a base64 encoded string. It is recommended to use the path returned to the fp_callback function to render the picture in the page or to upload the picture to server (Refer postMultipart method for details.). Reading picture data would increase the memory usage of the app, hence this property should be used only when absolutely needed. Default value is false.

  1. width - {Optional. Integer}. Width of the chosen picture in pixels when returned. Default value is 320. The width is applied before the chosen picture is written to the options.filePath and the actual picture in the gallery is not affected by this property

  1. height - {Optional. Integer}. Height of the captured picture in pixels when returned. Default value is 480. The height is applied before the captured picture is written to the options.filePath and the actual picture in the gallery is not affected by this property.

Remarks

The options parameter can be set globally in the page using the camSetup method, which will be used by all the following choosePic method calls.The photos gallery is the Camera roll album and can be accessed using the native Photos/Gallery app.

The native Camera app returns the picture as per its settings and it is usually the highest resolution possible. Based on the app needs, resize the image by mentioning the options.width and options.height dimensions. Combination of these dimensions and quality parameter decide the final crispness of the picture.