Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

Camera API

Use the camera on a device. See the controller and view in the /app/Image folder of the System API Samples application for an example.

Using JavaScript API

You can call the Camera methods from JavaScript as well as Ruby. To use the JavaScript API, add the public/js/rho_javascript_api.js file – created at build time as part of the application package – to the .html, .erb, or .js file calling the JavaScript method.

The JavaScript API methods with a return value can pass it as a parameter in jQuery-compatible continuation (deferred object, a kind of callback). Possible continuations to handle are done, fail, and complete.

Rho.Class.method(params).done(function(handler) { /* handler... */ })

You must enable JavaScript by putting rho-javascript into extensions in your build.yml.

extensions: ["rho-javascript"]

You must have a RhoElements license to use the JavaScript API.

Enabling the Camera

To use the camera API, you need to enable the camera on the device. Do this by adding that capability to the build.yml file:

capabilities:
  - camera

get_camera_info

Get camera information. Returns max_resolution: a hash with width and height numeric values (returns NIL if the camera_type is not supported). iOS and Android only.

Ruby syntax:

Camera::get_camera_info(camera_type)

JavaScript syntax:

Rho.Camera.get_camera_info(camera_type)
camera_type String. "main" or "front". Default = "main".

choose_picture

Choose a picture from an album. options_hash is only used with iOS.

Camera::choose_picture(callback_url, options_hash)

JavaScript syntax:

Rho.Camera.choose_picture(callback_function, options_hash)
callback_url url to the callback method, such as '/app/model/camera_callback'.
options_hash (iOS only) a hash of additional parameters.

The callback is a POST message; the body of the message contains the return status and image_uri.

status "ok", "cancel", "error".
image_uri uri to the chosen image stored in the /public/db-files folder; the image file has an auto-generated name.

take_picture

Take a picture. options_hash is used with iOS, Android, and RhoElements Zebra devices.

Note: On low memory devices, the take_picture method may not work. As a workaround, you can use the Imager API’s capture() method.

Ruby syntax:

Camera::take_picture(callback_url, options_hash)

JavaScript syntax:

Rho.Camera.take_picture(callback_function, options_hash)
callback_url url to the callback method, such as '/app/model/camera_callback'.
options_hash (Android, iOS, Zebra devices only) a hash of additional parameters.

save_image_to_device_gallery

Save an image to the device gallery.

Ruby syntax:

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

Callback Parameters

Once the user has taken/chosen a picture (take_picture, choose_picture), the callback URL you specified will be called. The callback is a POST message; the body of the message contains the following parameters.

status "ok", "cancel", "error".
image_uri uri to the taken image stored in the /public/db-files folder; the image file has an auto-generated name.
message (Android and iOS only) if status = "error", a string containing an error message.
image_width (Android and iOS only) image width in pixels.
image_height (Android and iOS only) image height in pixels.
image_format (Android and iOS only) "png" or "jpg".

options_hash for iOS and Android Devices

options_hash is a hash used with take_picture and choose_picture on iOS and Android.

camera_type "main" or "front". Default = "main".
desired_width desired width in pixels. Default = max camera width.
desired_height desired height in pixels. Default = max camera height.
color_model "RGB" or "Grayscale". Default = "RGB".
format "png" or "jpg". Default = "jpg". 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.
enable_editing (iPhone only) boolean. Enables post photo capture image customizing; image will captured reduced to screen size (not full size). Default = true.
flash_mode (Android only) String. "off", "on", "auto", "red-eye", "torch".
save_to_shared_gallery (iOS only) if true, picture you take will be added to the camera roll. Default value = false.

options_hash for RhoElements Zebra Devices

options_hash is a hash used with take_picture on RhoElements Zebra devices,

left camera left position in pixels. Default value = 0.
top camera top position in pixels. Default value = 0.
desired_width desired width in pixels. Default value = max camera width.
desired_height desired width in pixels. Default value = max camera height.

Devices lacking support

Due to platform limitation devices such as ES400, MC65 and MC67 does not support camera API. Preferred Imager APIs in that case.

Back to Top