Camera

The Camera API provides access to the device camera(s). Use this API to give users the ability to take a photo via one of the cameras and return it to the application. Photos can either be stored on the device as an image file or returned as a DataURI object for storage and/or display. Optionally, image files also can be transfered to online storage using the Network API.

Enabling the API

To use this API, the following extension must be included in the build.yml:

extensions: ["mediacapture"]

JavaScript Usage

Be sure to review the JavaScript API Usage guide for important information about using this API in JavaScript

Ruby Usage

Be sure to review the Ruby API Usage guide for important information about using this API in Ruby

Methods

capture(CallBackHandler callback)

Capture the image and save it to a file.

Parameters

  • callback : CallBackHandler Mandatory

Async Callback Returning Parameters: HASH

    • status : STRING

      Whether or not the image was successfully captured. The returned string will be one of ‘ok’ or ‘error’.

    • imageUri : STRING

      If the specified ‘outputFormat’ was ‘image’ then this field is the URI to the taken image stored on the device. If the specified ‘outputFormat’ was ‘dataUri’ then this field will be the image encoded as a Data URI, In Wp8 dataUri shall provide the thumbnail for the picture taken, It is recommended to use Image over dataUri. If the specified ‘outputFormat’ was ‘imagePath’ then this field will have the image path on the device. User can use image path to transfer image over http.

    • imageHeight : INTEGER

      The actual height of the image that was captured, this may differ from the requested height as the Camera will only support a finite resolutions.

    • imageWidth : INTEGER

      The actual width of the image that was captured, this may differ from the requested width as the Camera will only support a finite resolutions.

    • imageFormat : STRING

      The format in which the image was captured, either ‘png’ or ‘jpg’.

    • message : STRING

      If the returned status is ‘error’ then this field will contain more information on the error.

Synchronous Return:

  • Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.capture(CallBackHandler callback)
  • Default Instance: This method can be accessed via the default instance object of this class.
    • JavaScript: Rho.Camera.capture(CallBackHandler callback)
    • Ruby: Rho::Camera.capture(CallBackHandler callback)

choosePicture(HASH propertyMap, CallBackHandler callback)

Choose a picture from the album.

Parameters

  • propertyMap : HASH Optional

    Provide a set of properties to configure an image, for example to specify the image size or color mode. In WM/CE,Android and WP8 devices user can only specify the outputFormat in the property bag. In iOS devices user can specify next options: compressionFormat, desiredWidth, desiredHeight, outputFormat, colorModel, enableEditing.

                            In Wp8 dataUri shall provide the thumbnail for the picture taken, It is recommended to use Image over dataUri.On wp8, wm when 'outputFormat' is 'image' then imageUri or image_uri shall have Image name with \ sign, on WP8 ImageName shall be suffixed by DTF when 'outputFormat' is 'image'
    
    Valid `properties` for this parameter are the properties avaliable to this API module. Check the property section

    Not providing properties to this function will use the Camera’s default properties, or those previously set on the Camera instance.

  • callback : CallBackHandler Mandatory

Async Callback Returning Parameters: HASH

    • status : STRING

      Whether or not the image was successfully chosen from the gallery. The returned string will be one of ‘ok’, ‘cancel’ or ‘error’.

    • imageUri : STRING

      If the specified ‘outputFormat’ was ‘image’ then this field is the URI to the taken image stored on the device.On wp8,wm when ‘outputFormat’ is ‘image’ then imageUri shall have only Image name with \ sign, on WP8 ImageName shall be suffixed by DTF when ‘outputFormat’ is ‘image’, this image will have an auto-generated name. If the specified ‘outputFormat’ was ‘dataUri’ then this field will be the image encoded as a Data URI, In Wp8 dataUri shall provide the thumbnail for the picture taken, It is recommended to use Image over dataUri. If the specified ‘outputFormat’ was ‘imagePath’ then this field will have the image path on the device. User can use image path to transfer image over http.

      Platforms:Android, WM, CE, iOS, WP8
    • imageHeight : INTEGER

      The height of the image.

    • imageWidth : INTEGER

      The width of the image.

    • imageFormat : STRING

      The format of the image, either ‘png’ or ‘jpg’.

    • message : STRING

      If the returned status is ‘error’ then this field will contain more information on the error. To maintain backward compatibility WM and Android platforms provides message for cancel status as well.

    • image_uri : STRING

      If the specified ‘outputFormat’ was ‘image’ then this field is the URI to the taken image stored on the device.On wp8,wm when ‘outputFormat’ is ‘image’ then imageUri shall have only Image name with \ sign, on WP8 ImageName shall be suffixed by DTF when ‘outputFormat’ is ‘image’, this image will have an auto-generated name. If the specified ‘outputFormat’ was ‘dataUri’ then this field will be the image encoded as a Data URI, In Wp8 dataUri shall provide the thumbnail for the picture taken, It is recommended to use Image over dataUri. If the specified ‘outputFormat’ was ‘imagePath’ then this field will have the image path on the device. User can use image path to transfer image over http.

      Platforms:Android, WM, CE, iOS, WP8
    • image_height : INTEGER

      It is recommended to use imageHeight in preference to this parameter.

    • image_width : INTEGER

      It is recommended to use imageWidth in preference to this parameter.

    • image_format : STRING

      It is recommended to use imageFormat in preference to this parameter.

Synchronous Return:

  • Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.Camera.choosePicture(HASH propertyMap, CallBackHandler callback)
    • Ruby: Rho::Camera.choosePicture(HASH propertyMap, CallBackHandler callback)

copyImageToDeviceGallery(STRING pathToImage)

Replaces: save_image_to_device_gallery

Save an image to the device gallery.

Parameters

  • pathToImage : STRING

    The real path to the image that is to be saved in the device gallery. You need to use the RhoApplication method expandDatabaseBlobFilePath to have the real path, such as Rho::RhoApplication::expandDatabaseBlobFilePath(img.image_uri).

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • JavaScript: Rho.Camera.copyImageToDeviceGallery(STRING pathToImage)
    • Ruby: Rho::Camera.copyImageToDeviceGallery(STRING pathToImage)

getAllProperties(CallBackHandler callback)

This method will return all of object/value pairs for the propertyNames of the API class.

Parameters

  • callback : CallBackHandler Optional

Async Callback Returning Parameters: HASH

    • : STRING

Synchronous Return:

  • HASH :

    Map of all available properties

    : this method also supports async callbacks - check the Callback tab for callback return parameters.
    • : STRING

Method Access:

  • Instance Method: This method can be accessed via an instance object of this class:
    • myObject.getAllProperties(CallBackHandler callback)
  • Default Instance: This method can be accessed via the default instance object of this class.
    • JavaScript: Rho.Camera.getAllProperties(CallBackHandler callback)
    • Ruby: Rho::Camera.getAllProperties(CallBackHandler callback)

getCameraByType(STRING cameraType, CallBackHandler callback)

Returns the camera of requested type if that camera exist – else return nil.

Parameters

  • cameraType : STRING

    CameraType: ‘back’ or ‘front’ in the case of Android, iOS and WP8 and ‘color’ or ‘imager’ in the case of WM, CE devices

  • callback : CallBackHandler Optional

Async Callback Returning Parameters: SELF_INSTANCE

    Synchronous Return:

    • SELF_INSTANCE :

      Camera with requested type or nil if not requested type does not exist. Refer example section for more details.

      : this method also supports async callbacks - check the Callback tab for callback return parameters.

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.Camera.getCameraByType(STRING cameraType, CallBackHandler callback)
      • Ruby: Rho::Camera.getCameraByType(STRING cameraType, CallBackHandler callback)

    getDefault()

    This method will return an object that represents the default instance of the API Class. For example Camera.getDefault will return a Camera object that represents the default camera.

    Synchronous Return:

    • SELF_INSTANCE :

      Default object of Module.

    Method Access:

    • Class Method: This method can only be accessed via the API class object.
      • JavaScript: Rho.Camera.getDefault()
      • Ruby: Rho::Camera.getDefault()

    getProperties(ARRAY arrayofNames, CallBackHandler callback)

    This method will return a set of object/value pairs for the list of the propertyName that is passed in. The propertyNames must be a valid property of the API class.

    Parameters

    • arrayofNames : ARRAY

      List of properties I want to know about

      • Object : STRING

    • callback : CallBackHandler Optional

    Async Callback Returning Parameters: HASH

      • : STRING

    Synchronous Return:

    • HASH :

      Map of properties I want to know about

      : this method also supports async callbacks - check the Callback tab for callback return parameters.
      • : STRING

    Method Access:

    • Instance Method: This method can be accessed via an instance object of this class:
      • myObject.getProperties(ARRAY arrayofNames, CallBackHandler callback)
    • Default Instance: This method can be accessed via the default instance object of this class.
      • JavaScript: Rho.Camera.getProperties(ARRAY arrayofNames, CallBackHandler callback)
      • Ruby: Rho::Camera.getProperties(ARRAY arrayofNames, CallBackHandler callback)

    getProperty(STRING propertyName, CallBackHandler callback)

    This method will return the value of the propertyName that is passed in. The propertyName must be a valid property of the API class.

    Parameters

    • propertyName : STRING

      The property to return info about.

    • callback : CallBackHandler Optional

    Async Callback Returning Parameters: STRING

      Synchronous Return:

      • STRING :

        The property to return info about.

        : this method also supports async callbacks - check the Callback tab for callback return parameters.

      Method Access:

      • Instance Method: This method can be accessed via an instance object of this class:
        • myObject.getProperty(STRING propertyName, CallBackHandler callback)
      • Default Instance: This method can be accessed via the default instance object of this class.
        • JavaScript: Rho.Camera.getProperty(STRING propertyName, CallBackHandler callback)
        • Ruby: Rho::Camera.getProperty(STRING propertyName, CallBackHandler callback)

      hidePreview()

      Hides the preview opened by using showPreview.

      Synchronous Return:

      • Void

      Method Access:

      • Instance Method: This method can be accessed via an instance object of this class:
        • myObject.hidePreview()
      • Default Instance: This method can be accessed via the default instance object of this class.
        • JavaScript: Rho.Camera.hidePreview()
        • Ruby: Rho::Camera.hidePreview()

      setDefault(SELF_INSTANCE: Rho::Camera defaultInstance)

      This method allows you to set the attributes of the default object instance by passing in an object of the same class.

      Parameters

      • defaultInstance : SELF_INSTANCE: Rho::Camera

        An instance object that is of the same class.

      Synchronous Return:

      • Void

      Method Access:

      • Class Method: This method can only be accessed via the API class object.
        • JavaScript: Rho.Camera.setDefault(SELF_INSTANCE: Rho::Camera defaultInstance)
        • Ruby: Rho::Camera.setDefault(SELF_INSTANCE: Rho::Camera defaultInstance)

      setProperties(HASH propertyMap)

      This method will set the values of a list of properties for the API class. The propertyName must be a valid property for the class and must also not be read only.

      Parameters

      • propertyMap : HASH

        Map of properties I want to set

        • Object : STRING

      Synchronous Return:

      • Void

      Method Access:

      • Instance Method: This method can be accessed via an instance object of this class:
        • myObject.setProperties(HASH propertyMap)
      • Default Instance: This method can be accessed via the default instance object of this class.
        • JavaScript: Rho.Camera.setProperties(HASH propertyMap)
        • Ruby: Rho::Camera.setProperties(HASH propertyMap)

      setProperty(STRING propertyName, STRING propertyValue)

      This method will set the value of a property for the API class. The propertyName must be a valid property for the class and must also not be read only.

      Parameters

      • propertyName : STRING

        The one property name that I want to set

      • propertyValue : STRING

        The one property value that I want to set

      Synchronous Return:

      • Void

      Method Access:

      • Instance Method: This method can be accessed via an instance object of this class:
        • myObject.setProperty(STRING propertyName, STRING propertyValue)
      • Default Instance: This method can be accessed via the default instance object of this class.
        • JavaScript: Rho.Camera.setProperty(STRING propertyName, STRING propertyValue)
        • Ruby: Rho::Camera.setProperty(STRING propertyName, STRING propertyValue)

      showPreview(HASH propertyMap)

      Shows the preview in user configurable viewer window.

      Parameters

      • propertyMap : HASH Optional

        Provide a set of properties to configure the camera.

        Valid `properties` for this parameter are the properties avaliable to this API module. Check the property section

        Not providing properties to this function will use the Camera’s default properties, or those previously set on the Camera instance.

      Synchronous Return:

      • Void

      Method Access:

      • Instance Method: This method can be accessed via an instance object of this class:
        • myObject.showPreview(HASH propertyMap)
      • Default Instance: This method can be accessed via the default instance object of this class.
        • JavaScript: Rho.Camera.showPreview(HASH propertyMap)
        • Ruby: Rho::Camera.showPreview(HASH propertyMap)

      takePicture(HASH propertyMap, CallBackHandler callback)

      Start the camera application to take a picture. The user can capture the displayed image by interacting with the resident camera app. In Windows, this method always shows the preview in full screen and user can use the native button to capture the image.

                  On wp8,wm when 'outputFormat' is 'image' then imageUri/image_uri shall have only Image name with \ sign, on WP8 ImageName shall be suffixed by DTF when 'outputFormat' is 'image'
      

      Note: To display an image, it is recommended that you use the full path to the image instead of a relative path. To do this, you can use the expandDatabaseBlobFilePath method of the Application module as such:

      Ruby
      Rho::RhoApplication.expandDatabaseBlobFilePath(x.image_uri)
      
      JavaScript
      Rho.RhoApplication.expandDatabaseBlobFilePath(x.image_uri)
      

      Parameters

      • propertyMap : HASH Optional

        Provide a set of properties to configure the camera, for example to specify the flashMode or compressionFormat.

        Valid `properties` for this parameter are the properties avaliable to this API module. Check the property section

        Not providing properties to this function will use the Camera’s default properties, or those previously set on the Camera instance.

      • callback : CallBackHandler Mandatory

      Async Callback Returning Parameters: HASH

        • status : STRING

          Whether or not the image was successfully captured. The returned string will be one of ‘ok’, ‘cancel’ or ‘error’.

          Platforms:Android, WM, CE, iOS, WP8
        • imageUri : STRING

          If the specified ‘outputFormat’ was ‘image’ then this field is the URI to the taken image stored on the device.On wp8,wm when ‘outputFormat’ is ‘image’ then imageUri shall have only Image name with \ sign, on WP8 ImageName shall be suffixed by DTF when ‘outputFormat’ is ‘image’, this image will have an auto-generated name. If the specified ‘outputFormat’ was ‘dataUri’ then this field will be the image encoded as a Data URI, In Wp8 dataUri shall provide the thumbnail for the picture taken, It is recommended to use Image over dataUri. If the specified ‘outputFormat’ was ‘imagePath’ then this field will have the image path on the device. User can use image path to transfer image over http.

          Platforms:Android, WM, CE, iOS, WP8
        • imageHeight : INTEGER

          The actual height of the image that was captured, this may differ from the requested height as the Camera will only support a finite resolutions.

          Platforms:Android, WM, CE, iOS, WP8
        • imageWidth : INTEGER

          The actual width of the image that was captured, this may differ from the requested width as the Camera will only support a finite resolutions.

          Platforms:Android, WM, CE, iOS, WP8
        • imageFormat : STRING

          The format in which the image was captured, either ‘png’ or ‘jpg’.

          Platforms:Android, WM, CE, iOS
        • message : STRING

          If the returned status is ‘error’ then this field will contain more information on the error. To maintain backward compatibility WM and Android platforms provides message for cancel status as well.

          Platforms:Android, WM, CE, iOS, WP8
        • image_uri : STRING

          If the specified ‘outputFormat’ was ‘image’ then this field is the URI to the taken image stored on the device.On wp8,wm when ‘outputFormat’ is ‘image’ then imageUri shall have only Image name with \ sign, on WP8 ImageName shall be suffixed by DTF when ‘outputFormat’ is ‘image’, this image will have an auto-generated name. If the specified ‘outputFormat’ was ‘dataUri’ then this field will be the image encoded as a Data URI, In Wp8 dataUri shall provide the thumbnail for the picture taken, It is recommended to use Image over dataUri. If the specified ‘outputFormat’ was ‘imagePath’ then this field will have the image path on the device. User can use image path to transfer image over http.

          Platforms:Android, WM, CE, iOS, WP8
        • image_height : INTEGER

          It is recommended to use imageHeight in preference to this parameter.

          Platforms:Android, WM, CE, iOS, WP8
        • image_width : INTEGER

          It is recommended to use imageWidth in preference to this parameter.

          Platforms:Android, WM, CE, iOS, WP8
        • image_format : STRING

          It is recommended to use imageFormat in preference to this parameter.

          Platforms:Android, WM, CE, iOS

      Synchronous Return:

      • Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

      Method Access:

      • Instance Method: This method can be accessed via an instance object of this class:
        • myObject.takePicture(HASH propertyMap, CallBackHandler callback)
      • Default Instance: This method can be accessed via the default instance object of this class.
        • JavaScript: Rho.Camera.takePicture(HASH propertyMap, CallBackHandler callback)
        • Ruby: Rho::Camera.takePicture(HASH propertyMap, CallBackHandler callback)

      Properties

      aimMode : STRING

      Specifies the aim behaviour when taking a picture. Applicable only for imager module.

                  This Property shall accept/return one among the values mentioned in constant section which starts with AIM_...
      

      Property Access:

      • Instance: This property can be accessed via an instance object of this class:
        • myObject.aimMode
      • Default Instance: This property can be accessed via the default instance object of this class.
        • JavaScript: Rho.Camera.aimMode
        • Ruby: Rho::Camera.aimMode

      cameraType : STRING Read Only

      Replaces:camera_type

      This property is device specific. The value for this property can be either ‘back’ or ‘front’ in the case of Android/iOS/WP8 devices.In the case of WM/CE it could be either ‘imager’ or ‘color’. WM/CE devices will use ‘color'as default and if color camera not available the default value will be 'imager’. Android/iOS/WP8 devices will use ‘back'as default and if back camera not available the default value will be 'front’,

                  This Property shall return one among the values mentioned in constant section which starts with CAMERA_TYPE_...
      

      Property Access:

      • Instance: This property can be accessed via an instance object of this class:
        • myObject.cameraType
      • Default Instance: This property can be accessed via the default instance object of this class.
        • JavaScript: Rho.Camera.cameraType
        • Ruby: Rho::Camera.cameraType

      captureSound : STRING 4.0.0

      Path to a sound file resident on the device which will be played when the image is captured.

      Property Access:

      • Instance: This property can be accessed via an instance object of this class:
        • myObject.captureSound
      • Default Instance: This property can be accessed via the default instance object of this class.
        • JavaScript: Rho.Camera.captureSound
        • Ruby: Rho::Camera.captureSound

      colorModel : STRING 2.0.0

      Replaces:color_model

      Where supported by the hardware this property can be used to select whether to capture a color or a grayscale image.

                  This Property shall accept/return one among the values mentioned in constant section which starts with COLOR_MODEL_...
      

      Default: rgb

      Property Access:

      • Instance: This property can be accessed via an instance object of this class:
        • myObject.colorModel
      • Default Instance: This property can be accessed via the default instance object of this class.
        • JavaScript: Rho.Camera.colorModel
        • Ruby: Rho::Camera.colorModel

      compressionFormat : STRING 4.0.0

      Replaces:format

      The format of the captured image in subsequent calls to takePicture(). If you do not define this property when you use choose_picture with iOS, the type of image in Gallery will be recognized, and the same format will be used for saving the image to applications data. In windows and WP8 devices the format will be always jpg type.

                  This Property shall accept/return one among the values mentioned in constant section which starts with COMPRESSION_FORMAT_...
      

      Default: jpg

      Property Access:

      • Instance: This property can be accessed via an instance object of this class:
        • myObject.compressionFormat
      • Default Instance: This property can be accessed via the default instance object of this class.
        • JavaScript: Rho.Camera.compressionFormat
        • Ruby: Rho::Camera.compressionFormat

      desiredHeight : INTEGER 2.0.0

      Replaces:desired_height

      Camera hardware is limited to taking photos in a finite number of resolutions, eg 2048x1536, 640x480 etc. Specifying a desiredHeight will request to take the photo with the specified height but if it is not supported by the hardware then the closest match will be selected. The callback received when a photo is taken contains the actual resolution of the captured photo.

      Property Access:

      • Instance: This property can be accessed via an instance object of this class:
        • myObject.desiredHeight
      • Default Instance: This property can be accessed via the default instance object of this class.
        • JavaScript: Rho.Camera.desiredHeight
        • Ruby: Rho::Camera.desiredHeight

      desiredWidth : INTEGER 2.0.0

      Replaces:desired_width

      Camera hardware is limited to taking photos in a finite number of resolutions, eg 2048x1536, 640x480 etc. Specifying a desiredWidth will request to take the photo with the specified width but if it is not supported by the hardware then the closest match will be selected. The callback received when a photo is taken contains the actual resolution of the captured photo.

      Property Access:

      • Instance: This property can be accessed via an instance object of this class:
        • myObject.desiredWidth
      • Default Instance: This property can be accessed via the default instance object of this class.
        • JavaScript: Rho.Camera.desiredWidth
        • Ruby: Rho::Camera.desiredWidth

      enableEditing : BOOLEAN 2.0.0

      Replaces:enable_editing

      Enables post photo capture image customizing; image will captured reduced to screen size (not full size of camera sensor).

      Default: true

      Property Access:

      • Instance: This property can be accessed via an instance object of this class:
        • myObject.enableEditing
      • Default Instance: This property can be accessed via the default instance object of this class.
        • JavaScript: Rho.Camera.enableEditing
        • Ruby: Rho::Camera.enableEditing

      fileName : STRING 4.0.0

      The image file path without file extension to store captured image in subsequent calls to takePicture() or capture(). Default filename will be IMG_timestamp and will be saved under root directory. The filename extension will be added automatically according to compressionFormat property value.

                  In Wp8, only filename can be changed, by default the path shall be under picture=>CameraRoll
      

      Property Access:

      • Instance: This property can be accessed via an instance object of this class:
        • myObject.fileName
      • Default Instance: This property can be accessed via the default instance object of this class.
        • JavaScript: Rho.Camera.fileName
        • Ruby: Rho::Camera.fileName

      flashMode : STRING 2.0.0

      Replaces:flash_mode

      Specifies the flash behavior when taking a picture.

                  This Property shall accept/return one among the values mentioned in constant section which starts with FLASH_...
      

      Property Access:

      • Instance: This property can be accessed via an instance object of this class:
        • myObject.flashMode
      • Default Instance: This property can be accessed via the default instance object of this class.
        • JavaScript: Rho.Camera.flashMode
        • Ruby: Rho::Camera.flashMode

      maxHeight : INTEGER Read Only

      The maximum height of images which can be captured. This is measured in pixels. On WM/CE devices this is applicable only for color camera. Imager does not support this property.

      Property Access:

      • Instance: This property can be accessed via an instance object of this class:
        • myObject.maxHeight
      • Default Instance: This property can be accessed via the default instance object of this class.
        • JavaScript: Rho.Camera.maxHeight
        • Ruby: Rho::Camera.maxHeight

      maxWidth : INTEGER Read Only

      The maximum width of images which can be captured. This is measured in pixels. On WM/CE devices this is applicable only for color camera. Imager does not support this property.

      Property Access:

      • Instance: This property can be accessed via an instance object of this class:
        • myObject.maxWidth
      • Default Instance: This property can be accessed via the default instance object of this class.
        • JavaScript: Rho.Camera.maxWidth
        • Ruby: Rho::Camera.maxWidth

      outputFormat : STRING 4.0.0

      Specifies the way to return the captured image to the application.

                  This Property shall accept/return one among the values mentioned in constant section which starts with OUTPUT_FORMAT_...
      

      Default: imagePath

      Property Access:

      • Instance: This property can be accessed via an instance object of this class:
        • myObject.outputFormat
      • Default Instance: This property can be accessed via the default instance object of this class.
        • JavaScript: Rho.Camera.outputFormat
        • Ruby: Rho::Camera.outputFormat

      previewHeight : INTEGER 4.0.0

      In cases where the resident camera application on the device is not used this API is used to control the position of the viewfinder preview window when taking a photo.

      Property Access:

      • Instance: This property can be accessed via an instance object of this class:
        • myObject.previewHeight
      • Default Instance: This property can be accessed via the default instance object of this class.
        • JavaScript: Rho.Camera.previewHeight
        • Ruby: Rho::Camera.previewHeight

      previewLeft : INTEGER 4.0.0

      Replaces:left

      In cases where the resident camera application on the device is not used this API is used to control the position of the viewfinder preview window when taking a photo.

      Property Access:

      • Instance: This property can be accessed via an instance object of this class:
        • myObject.previewLeft
      • Default Instance: This property can be accessed via the default instance object of this class.
        • JavaScript: Rho.Camera.previewLeft
        • Ruby: Rho::Camera.previewLeft

      previewTop : INTEGER 4.0.0

      Replaces:top

      In cases where the resident camera application on the device is not used this API is used to control the position of the viewfinder preview window when taking a photo.

      Property Access:

      • Instance: This property can be accessed via an instance object of this class:
        • myObject.previewTop
      • Default Instance: This property can be accessed via the default instance object of this class.
        • JavaScript: Rho.Camera.previewTop
        • Ruby: Rho::Camera.previewTop

      previewWidth : INTEGER 4.0.0

      In cases where the resident camera application on the device is not used this API is used to control the position of the viewfinder preview window when taking a photo.

      Property Access:

      • Instance: This property can be accessed via an instance object of this class:
        • myObject.previewWidth
      • Default Instance: This property can be accessed via the default instance object of this class.
        • JavaScript: Rho.Camera.previewWidth
        • Ruby: Rho::Camera.previewWidth

      saveToDeviceGallery : BOOLEAN 2.0.0

      Replaces:save_to_shared_gallery

      If true, the picture you take will be added to the device photo gallery.

      Default: false

      Property Access:

      • Instance: This property can be accessed via an instance object of this class:
        • myObject.saveToDeviceGallery
      • Default Instance: This property can be accessed via the default instance object of this class.
        • JavaScript: Rho.Camera.saveToDeviceGallery
        • Ruby: Rho::Camera.saveToDeviceGallery

      supportedSizeList : ARRAY Read Only

      List of resolutions (width and height in pixels) supported by the camera. On WM/CE devices this feature is supported only by color camera and it is not supported by imager. Refer example section for more details.

    • Object : HASH

      • width : INTEGER

      • height : INTEGER

      Property Access:

      • Instance: This property can be accessed via an instance object of this class:
        • myObject.supportedSizeList
      • Default Instance: This property can be accessed via the default instance object of this class.
        • JavaScript: Rho.Camera.supportedSizeList
        • Ruby: Rho::Camera.supportedSizeList

      useSystemViewfinder : BOOLEAN 4.0.0

      Setting the value of this property to “true”, shall open the System ViewFinder with its properties. None of the Rho camera properties shall be applicable.

      Default: false

      Property Access:

      • Instance: This property can be accessed via an instance object of this class:
        • myObject.useSystemViewfinder
      • Default Instance: This property can be accessed via the default instance object of this class.
        • JavaScript: Rho.Camera.useSystemViewfinder
        • Ruby: Rho::Camera.useSystemViewfinder

      Constants

      CAMERA_TYPE_BACK

      Back camera. This is not supported in WM/CE devices.

      CAMERA_TYPE_FRONT

      Front camera. This is not supported in WM/CE devices.

      CAMERA_TYPE_IMAGER

      Camera is an imager. This is supported only in WM/CE devices.

      CAMERA_TYPE_COLOR

      Camera is color camera. This is supported only in WM/CE devices.

      COMPRESSION_FORMAT_JPG

      JPG compression.

      COMPRESSION_FORMAT_PNG

      PNG compression.

      OUTPUT_FORMAT_IMAGE

      This shall provide the image uri. This can be used to display image directly on the page. An example is shown in the example section

      OUTPUT_FORMAT_DATAURI

      This is a base 64 encoding of the image and can be used to easily embed the image on the page or store the image in a database. On some consumer devices, captured image will be rotated 90 degrees while displaying.

      OUTPUT_FORMAT_IMAGE_PATH

      If this value used for setting the outputFormat property, the takePicture or capture API will return imageUri as the path to the saved image in the device. User can use this image path to transfer the file to an http server if required. An example is given to demonstrate, transferring a file to http server.This property is not applicable for Android and windows phone 8.

      COLOR_MODEL_RGB

      A colour image is captured.

      COLOR_MODEL_GRAYSCALE

      A grayscale image is captured.

      FLASH_ON

      Flash will be used.

      FLASH_OFF

      Flash will not be used.

      FLASH_AUTO

      Flash will be used if lighting conditions deem it necessary. This is not supported in WM/CE devices.

      FLASH_RED_EYE

      Flash with red eye reduction is used. This is supported only in Android devices.

      FLASH_TORCH

      The flash is turned on in torch mode. This is supported only in Android devices.

      AIM_ON

      Switches the imager’s aim to ON

      AIM_OFF

      Switches the imager’s aim to OFF

      Examples

      Take picture with default camera

      Take an image with as little code as possible, using all default values.

      function take_picture_with_default_camera() {
        // Capture an image from the default camera on the device, using the default image settings
        Rho.Camera.takePicture({}, picture_taken_callback);
      }
      
      function picture_taken_callback(params) {
        // Did we receive an image?
        if (params["status"]=="ok") {
          // Assuming we have an <img id="#captured_image"> tag, we will be able to see the image that was just captured
          $("#captured_image").attr("src", Rho.Application.expandDatabaseBlobFilePath(params["imageUri"]));
        }
      }
                         
                       
      def take_picture_with_default_camera
        # Capture an image from the default camera on the device, using the default image settings
        Rho::Camera.takePicture({}, :picture_taken_callback)
      end
      
      def picture_taken_callback
        # Did we really take a picture?
        if (@params["status"]=="ok")
          # If so, show it
          Rho::WebView.navigate(url_for(:action => :show_picture, :query => {:image => Rho::Application.expandDatabaseBlobFilePath(@params["imageUri"])}))
        else
          # Otherwise we are done here
          Rho::WebView.navigate(url_for(:action => :index))
        end
      end
                         
                       
      Choose which camera to use when taking images

      On devices with more than one camera, you can select which camera to use for taking pictures.

      <div id="camera_list">
      </div>
      
      
      var cameras = [];
      
      function choose_camera() {
        // get all available cameras
        cameras = Rho.Camera.enumerate();
      
        // build an HTML list
        var cameraList = "<ul>";
      
        for (var cameraIndex=0; cameraIndex<cameras.length; cameraIndex++) {
          var camera = cameras[cameraIndex];
          // Create a link for each camera with an onclick handler
          cameraList = cameraList +'<li><a href="#" class="take_picture_with_selected_camera" onclick="take_picture_with_camera('+cameraIndex+')">'+camera.cameraType+'</a></li>';
        }
      
        cameraList = cameraList+"</ul>";
      
        // make camera list visible to the user
        $("#camera_list").html(cameraList);
      }
      
      function take_picture_with_camera(cameraIndex) {
        var camera = cameras[cameraIndex];
        camera.takePicture({}, picture_taken_callback);
      }
                         
                       
      # controller.rb
      def choose_camera
        $cameras = Rho::Camera.enumerate
        render
      end
      
      def take_picture_using_chosen_camera
        camera = $cameras[@params["cameraIndex"].to_i]
        camera.takePicture({}, url_for(:action => :picture_taken_callback))
      end
      
      
      # choose_camera.erb
      <ul data-role="listview">
        <% $cameras.each_with_index do |camera, index| %>
          <li><a href="<%= url_for(:action => :take_picture_using_chosen_camera, :query => {:camera_index => index}) %>"><%= camera.cameraType %></li>
        <% end %>
      </ul>
                         
                       
      Saving a picture to the device's gallery

      Apart from taking new pictures, you can also save images to the built-in gallery. In the following examples, the picture we are adding to the gallery is one that was just taken with the camera, but you can add any other image you can access by filename.

      function take_picture_and_save_it_to_gallery() {
        Rho.Camera.choosePicture({}, picture_taken_callback_save_to_gallery);
      }
      
      function picture_taken_callback_save_to_gallery(params) {
        if (params["status"]=="ok") {
          Rho.Camera.copyImageToDeviceGallery(Rho.Application.expandDatabaseBlobFilePath(params["imageUri"]));
      
          alert("Image saved to gallery");
        }
      }
                         
                       
      def take_picture_and_save_it_to_gallery
        Rho::Camera.choosePicture({}, url_for(:action => :picture_taken_callback_save_to_gallery))
      end
      
      def picture_taken_callback_save_to_gallery
        # Did we really take a picture?
        if (@params["status"]=="ok")
          # If so, save it to the gallery
          Rho::Camera.copyImageToDeviceGallery(Rho::Application.expandDatabaseBlobFilePath(@params["imageUri"]))
        end
      
        Rho::WebView.navigate(url_for(:action => :index))
      
      end
                         
                       
      Control image properties

      You can tweak multiple options to get an image exactly as you need it

      function control_image_properties() {
        // Instead of accepting the defaults, let's set some properties to our liking
      
        // We will ask for a PNG file...
        Rho.Camera.compressionFormat = "png";
      
        // ...a particular image size...
        Rho.Camera.desiredWidth = 1024;
        Rho.Camera.desiredHeight = 768;
      
        // ...and force the flash to be used
        Rho.Camera.flashMode = "on";
      
        // Now, take the picture
        Rho.Camera.takePicture({}, picture_taken_callback);
      }
      
      function picture_taken_callback(params) {
        // Did we receive an image?
        if (params["status"]=="ok") {
          // show it in our <img id="captured_image"> tag
          $("#captured_image").attr("src", Rho.Application.expandDatabaseBlobFilePath(params["imageUri"]));
        }
      
      }
                         
                       
      def control_image_properties
        # Instead of accepting the defaults, let's set some properties to our liking
      
        # We will ask for a PNG file...
        Rho::Camera.compressionFormat = "png"
      
        # ...a particular image size...
        Rho::Camera.desiredWidth = 1024
        Rho::Camera.desiredHeight = 768
      
        # ...and force the flash to be used
        Rho::Camera.flashMode = "on"
      
        # Now, take the picture
        Rho::Camera.takePicture({}, :picture_taken_callback)
      end
      
      def picture_taken_callback
        # Did we really take a picture?
        if (@params["status"]=="ok")
          # If so, show it
          Rho::WebView.navigate(url_for(:action => :show_picture, :query => {:image => Rho::Application.expandDatabaseBlobFilePath(@params["imageUri"])}))
        else
          # Otherwise we are done here
          Rho::WebView.navigate(url_for(:action => :index))
        end
      end
                         
                       
      Determine camera capabilities

      You can get all available camera properties in a single call.

      function determine_camera_capabilities() {
        var capabilitiesList = "<ul>";
      
        // Get all capabilities of the camera...
        var capabilities = Rho.Camera.getAllProperties();
      
        // ... compose a nicely formatted list with their names and values ...
        for (var capability in capabilities) {
          capabilitiesList+="<li>"+capability+": "+capabilities[capability]+"</li>";
        }
      
        capabilitiesList += "</ul>";
      
        // ... and show it
        $("#camera_capabilities").html(capabilitiesList);
      }
                         
                       
      # controller.rb
      
      def determine_camera_capabilities
        # Get all camera properties
        @properties = Rho::Camera.getAllProperties
        render
      end
      
      # determine_camera_capabilities.erb
          <ul data-role="listview">
      
          <% @properties.each_pair do |name,value| %>
            <li><%= name %> : <%= value %></li>
          <% end %>
      
          </ul>
                         
                       
      Select picture from device gallery

      Apart from taking new pictures, the Camera API also lets you access existing images on the device’s gallery.

      function select_picture_from_gallery() {
        Rho.Camera.choose_picture({}, picture_taken_callback);
      }
      
      function picture_taken_callback(params) {
        // Did we receive an image?
        if (params["status"]=="ok") {
          // Show it in an <img> tag
          $("#captured_image").attr("src", Rho.Application.expandDatabaseBlobFilePath(params["imageUri"]));
        }
      }
                         
                       
      def select_picture_from_gallery
        Rho::Camera.choosePicture({}, url_for(:action => :picture_taken_callback))
      end
      
      def picture_taken_callback
        # Did we really take a picture?
        if (@params["status"]=="ok")
          # If so, show it
          Rho::WebView.navigate(url_for(:action => :show_picture, :query => {:image => Rho::Application.expandDatabaseBlobFilePath(@params["imageUri"])}))
        else
          # Otherwise we are done here
          Rho::WebView.navigate(url_for(:action => :index))
        end
      end
                         
                       
      Getting a camera instance by cameraType

      Camera API also lets you access camera instance by cameraType.

      //get the instance by cameraType and takePicture using that instance
      function get_color_camera_instance() {
        var camInst = Rho.Camera.getCameraByType('color');
        camInst.takePicture({'outputFormat':'image'}, my_callback);
      }
      
                         
                        
      Getting the list of resolutions supported by the camera

      Camera resolution is hardware specific. Camera API supports getting the supported resolutions of a camera instance.

      function getsupporteSizeList()
      {
      var instArray = Rho.Camera.enumerate();
      var reslnArray = instArray[0].supportedSizeList;
      alert(reslnArray[0].width);
      alert(reslnArray[0].height);
      alert(reslnArray[1].width);
      alert(reslnArray[1].height);
      }
                         
                        
      Transfering an image to HTTP server

      This example demonstrate how user can transfer an image to http server. This will be useful when application is running on a remote server.

      //enumerate the available cameras on the device
      var camArray = EB.Camera.enumerate();
      
      //below is the callback fired by network api after image upload to the server is completed
      var upload_file_callback = function (args){
              status = args['status'];
              //a status ok indicates image transferred successfully
              alert(status);
             }
      
      //below is the camera call back fired after takePicture is called
      var camera_callbackFunc = function(cbData){ 
        alert(cbData.imageUri); 
        //set the upload file properties; Refer network module for more details
        var uploadfileProps = {
                 url: 'http://10.233.82.51:8081/upload_image_file',
                //authType: "basic",
                //authUser: "admin",
                //authPassword: "password",
                filename: cbData.imageUri,
                body: "uploading file",
                fileContentType: "image/jpeg"
              };
         
         //below is the network module API used for uploading images when camera fire the callback
         EB.Network.uploadFile(uploadfileProps, upload_file_callback);      
       };
       
       //below is the test function which is used for capturing an image with outputFormat set as imagePath
      function Test_image_transfer1()
      { 
        //invoke takePicture API with outputFormat as imagePath and set the callback method
        camArray[0].takePicture({'fileName' : '/Application/Test/myImagename', 'outputFormat': 'imagePath'}, camera_callbackFunc);
      }
       //below is the test function which is used for choosing a picture from device with outputFormat set as imagePath
      function Test_image_transfer2()
      { 
        //invoke choosePicture API with outputFormat as imagePath and set the callback method
        EB.Camera.choosePicture({'outputFormat': 'image'}, camera_callbackFunc);
      }
            
      
                         
                        
      Dispalying an image using image uri.

      This example demonstrate how user can dispaly an image using image uri. The callback will return a image uri when outputFormat is set to ‘image’

      //enumerate the available cameras on the device
      var camArray = EB.Camera.enumerate();
      
      
      
      //below is the camera call back fired after takePicture is called
      var camera_callbackFunc = function(cbData){ 
      
        //uri will have relative path info only
        //user has to form the absolute local server path as shown below
        uri = 'http://localhost:'+EB.System.localServerPort + cbData.imageUri;
        //set the image uri to the image element
        document.getElementById('imageUri').src = uri ;
        
       };
       
       //below is the test function which is used for capturing an image with outputFormat set as image
      function Test_image_uri()
      { 
        //invoke takePicture API with outputFormat as image and set the callback method
        camArray[0].takePicture({'outputFormat': 'image'}, camera_callbackFunc);
      }
            
      
                         
                        

      Remarks

      SD Card Access

      SD Card access is enabled by default; grants of additional access will be ignored. The following extensions are able to write to the SD card by default.

      Camera Preview

      Despite a user-selected full screen mode, preview rendering size will be overridden by the driver on some WM/CE devices.

      DataUri

      DataUri output is dependent on availability of virtual space. DataUri may fail, be unresponsive, cause reboot, degraded performance or fail to load in certain devices. In such cases, image path is recommended.

      ImageUri

      Image Uri display is dependent on browser capability.

      GetSupportedProperties in WP8

      WP8 does not support getSupportedProperties or SetSupportedProperties.

      colorModel as Grayscale in Android

      Grayscale is supported only in the front camera of Android consumer devices.

      Invalid/Null values for properties in Android and iOS

      Only valid and non-empty values for properties are supported in Android and iOS.

      Ruby Support

      Due to platform limitations, imager and color camera are not supported in ruby applications for CE5 and CE6 devices.

      Camera in Suspend mode

      All WM and CE7 devices automatically turn off both color and imager cameras when the device is suspended. User must restart the camera to resume. Whereas CE5 (eg: MC9000) and CE6 (eg: MC31) devices retain the preview on resuming from suspend state.

      Image saving after taking picture

      In some devices (eg: Samsung), an image will be saved in landscape mode even if captured in portrait mode. This behavior is determined by the device’s default settings.

      WM/CE devices lacking support

      Due to platform limitations, the ES400, MC65 and MC67 do not support the color camera.

      takePicture resolution issue on low-memory devices with WM

      Due to platform limitations, the ES400, MC65 and MC67 do not support a color camera. The imager on the MC55 with WM does not support the Fullscreen window (eg: takePicture). Parameters such as previewLeft, previewWidth, previewTop and previewHeight are supported by the device to set up a user-defined viewer window.

      takePicture resolution issue on low-memory devices with WM

      Processor limitations of some devices may cause a low-resolution image captures to appear as a small preview with a black background when transitioning back to the application.

      Android KitKat gallery displays black image

      For images captured with the camera using a Rho app, the image might initially appear black. Refresh the view to correct the problem.

      Android preview

      High-resolution settings are not recommended for low-memory devices. Image previews on tablet devices might appear stretched or shrunken.