Mobile applications Development - Lecture 15 Accessing Device Features: Camera Accelerometer Contacts Events This presentation has been developed in the context of the Mobile Applications Development course at the Computer Science Department of the University of L’Aquila (Italy). http://www.di.univaq.it/malavolta

1. Accessing
Device Features
Ivano Malavolta
ivano.malavolta@univaq.it
http://www.di.univaq.it/malavolta

2. Roadmap
• Media Capture
• Camera
• Contacts
• Events
• Accelerometer

3. Media Capture
navigator.device.capture
Provides access for capturing
• Audio
• Image
• Video
directly from the device

4. The Capture Object
navigator.device.capture
Properties
supportedAudioModes
The audio recording formats supported by the device
supportedImageModes
The recording image sizes and formats supported by
the device
supportedVideoModes
The recording video resolutions and formats supported
by the device
They all contain an array of ConfigurationData objects

5. ConfigurationData
It is used to describe media capture modes supported
by the device
Properties:
1. Type String
Type:
The string in lower case representing the media type
– video/3gpp – audio/amr
– video/quicktime – audio/wav
– image/jpeg

6. ConfigurationData
2. height integer
height:
The height of the image or video in pixels
3. width integer
width:
The width of the image or video in pixels
In the case of a sound clip, the value of these attributes
is 0

7. Example
var imageModes =
navigator.device.capture.supportedImageModes;
for each (var mode in imageModes) {
console.log(mode.type);
console.log(mode.height);
console.log(mode.width);
}

8. Capturing Audio
It is called on the capture object
Start the audio recorder application and return
information about captured audio clip files

9. Capturing Audio
It starts an asynchronous operation to capture audio
recordings
It uses the device's default audio recording app
The operation allows the device user to capture
multiple recordings in a single session

10. Capturing Audio
When the capture operation is finished, it will invoke
the CaptureCB callback with an array
of MediaFile objects
If the operation is terminated by the user before an
audio clip is captured, the CaptureErrorCB
callback will be invoked

11. Capture Audio Options
Encapsulates audio capture configuration options
Properties:
• limit (not supported in iOS only 1 recording at a time)
The maximum number of audio clips the device user can record
in a single capture operation
• Duration (not supported in Android unlimited)
The maximum duration of an audio sound clip, in seconds
audio/amr audio/wav
• Mode (not supported in Android and iOS)
The selected audio mode, it must match one of the elements
in capture.supportedAudioModes

12. Audio Example
var options = { limit: 2, duration: 5 };
navigator.device.capture.captureAudio(win, fail, options);
function win(mediaFiles) {
var i;
for (i=0; i<mediaFiles.length; i++) {
console.log(mediaFiles[i]);
}
}
function fail(error) {
console.log(‘Error with code: ' + error.code);
}

13. Capturing Images
It is called on the capture object
Start the camera application and return information
about captured image file(s)

14. Capturing Images
It starts an asynchronous operation to capture
images
It uses the device camera application
The operation allows the device user to capture
multiple images in a single session

15. Capturing Images
Similarly to captureAudio...
When the capture operation is finished, it will invoke
the CaptureCB callback with an array
of MediaFile objects
If the operation is terminated by the user before any
image is captured, the CaptureErrorCB callback
will be invoked

16. Capture Image Options
Encapsulates image capture configuration options
Properties:
• limit (not supported in iOS only 1 image at a time)
The maximum number of images the device user can capture in
a single capture operation
• Mode (not supported in Android and iOS image/jpeg only)
The selected image mode, it must match one of the elements
in capture.supportedImageModes

17. Image Example
var options = { limit: 3};
navigator.device.capture.captureImage(win, fail,
options);
function win(mediaFiles) { It is very
var i; similar to
for (i=0; i<mediaFiles.length; i++) { the audio
upload(mediaFiles[i]);
} example!
}
function fail(error) {
console.log(‘Error with code: ' + error.code);
}

18. Recording Videos
It is called on the capture object
Start the video recorder application and return
information about captured video clip file(s).

19. Recording Videos
It starts an asynchronous operation to record videos
It uses the device video recording application
The operation allows the device user to capture
multiple recordings in a single session

20. Capturing Videos
Similarly to captureAudio...
When the capture operation is finished, it will invoke
the CaptureCB callback with an array
of MediaFile objects
If the operation is terminated by the user before any
video is recorded, the CaptureErrorCB callback
will be invoked

21. Capture Video Options
Encapsulates video recording configuration options
Properties:
• limit (not supported in iOS only 1 video at a time)
The maximum number of video clips the device user can record in a
single capture operation
• duration (not supported in Android and iOS unlimited)
The maximum duration of a video clip, in seconds
video/3gpp video/quicktime
• mode (not supported in Android and iOS)
The selected video recording mode, it must match one of the
elements in capture.supportedVideoModes

22. Video Example
navigator.device.capture.captureVideo(win, fail, {});
function win(mediaFiles) {
var i; It is very
for (i=0; i<mediaFiles.length; i++) { similar to the
upload(mediaFiles[i]); image & audio
} examples!
}
function fail(error) {
console.log(‘Error with code: ' + error.code);
}

23. Media Files
A MediaFile encapsulates properties of a media capture file
Name (String)
The name of the file, without path information
fullPath (String)
The full path of the file, including the name
Type (String)
The mime type
lastModifiedDate (Date)
The date and time that the file was last modified
Size (Integer)
The size of the file, in bytes

24. Capture Errors
Encapsulates the error code resulting from a failed
media capture operation
It contains a pre-defined error code
pre-
CaptureError.CAPTURE_INTERNAL_ERR
CaptureError.CAPTURE_APPLICATION_BUSY
CaptureError.CAPTURE_INVALID_ARGUMENT
CaptureError.CAPTURE_NO_MEDIA_FILES
CaptureError.CAPTURE_NOT__SUPPORTED

25. Roadmap
• Media Capture
• Camera
• Contacts
• Events
• Accelerometer

26. Camera
A dedicated API for capturing images from the device’s
default camera application
Takes a photo using the camera or retrieves a photo
from the device's album

27. Camera
The result of a call to getPicture() can be:
• a base64 encoded string, or
• the URI of an image file
Encoding the image using Base64 has caused memory
issues on some of these devices
it is recommended to use the URI of the image file

28. Camera Options
getPicture() can be called with the following options

29. Camera Options
quality (integer)
Quality of saved image
Range [0, 100]
destinationType (Integer)

30. Camera Options
sourceType (integer)
allowEdit (Boolean)
Allow simple editing of image before selection

31. Camera Options
encodingType (integer)
targetWidth,
targetWidth, targetHeight (Integer)
Width/height in pixels to scale image

32. Camera Options
mediaType (integer)
correctOrientation (Boolean)
Rotate the image to correct for the orientation of the
device during capture

33. Camera Options
saveToPhotoAlbum (Boolean)
Save the image to the photo album on the device after
capture
Every platform has its own quirks, you better check
them on the Cordova documentation

34. Camera Example
navigator.camera.getPicture(win, fail,
{ quality: 50,
destinationType: destinationType.FILE_URI,
pictureSource.PHOTOLIBRARY
});
function win(imageURI) {
var element = $(“#block”);
element.src(imageURI);
}
// fail function omitted here

35. Roadmap
• Media Capture
• Camera
• Contacts
• Events
• Accelerometer

36. Contacts
navigator.contacts
It is a global object that provides access to the device
contacts DB
You can call 2 methods on navigator.contacts
• contacts.create
• contacts.find

37. Creating contacts
navigator.contacts.create(properties)
It is a synchronous function that returns a new
Contact object
To persist the Contact object to the device, you have
to invoke the Contact.save method

38. Creating contacts
navigator.contacts.create(properties)
the properties parameter is a map of properties of the
new Contact object
ex.
var contact = navigator.contacts.create({
"displayName": “Ivano“
});

39. The Contact Object
It represents a user contact
A contact can be created, saved or removed from the
device contacts database
The contacts.find method is used for retrieving one
or more Contacts from the device contacts database

40. Contact Properties
It contains all the properties that a contact can have
Every platform has its own quirks, you better check
them on the Cordova documentation

41. Contact Methods
A contact object provides the following methods
• clone()
Returns a new Contact object that is a deep copy of the
calling object, its id property is null
• remove(win, fail)
Removes the contact from the device contacts database
• save(win, fail)
Saves a new contact to the device contacts database, or
updates an existing contact if a contact with the same id
already exists

42. Create Contact Example
var contact = navigator.contacts.create({
"displayName": “Ivano“
});
var name = new ContactName();
name.givenName = “Ivano“;
name.familyName = “Malavolta“;
contact.name = name;
contact.birthday = new Date(“19 July 1983");
contact.save(win, fail);
function win(contact) {
alert("Save Success");
};
function fail(contactError) {
alert("Error = " + contactError.code);
};

43. Finding contacts
navigator.contacts.find(
contactFields,
contactSuccess,
contactError,
contactFindOptions
);
It is an asyncronous function that queries the device
contacts database and returns an array of Contact
objects

44. Find Parameters
contactFields,
contactFields String
Contact fields to be used as search qualifier. Only these
fields will have values in the resulting Contact objects
contactSuccess
Success callback function that is invoked with the array of
contacts returned from the contacts database
contactError [optional]
Error callback function
contactFindOptions [Optional]
Search options to filter contacts

45. Contact Fields
Specifies which fields should be included in the Contact
objects resulting from a find operation
var fields = ["displayName", "name"]; // or [“*”]
navigator.contacts.find(fields, win, fail);
function win(contacts) {
console.log(‘ok');
};
function fail(err) {
console.log(err.code);
};

46. Contact Find Options
Contains properties that can be used to filter the results
Properties
filter (String) (Default: "")
The search string used to find contacts
A case-insensitive, partial value match is applied to each
field specified in the contactFields parameter
multiple (Boolean) (default: false)
Determines if the find operation should return multiple
contacts

47. Find Contact Example
var options = new ContactFindOptions();
options.filter = “Ivano";
options.multiple = true;
filter = ["displayName",“birthday"];
navigator.contacts.find(filter, win, fail, options);
function win(contacts) {
for (var i=0; i<contacts.length; i++) {
console.log(contacts[i].displayName);
}
};
function fail(contactError) {
alert("Error = " + contactError.code);
};

48. ContactError
It is always returned to the fail callback when an
error occurs
ContactError.UNKNOWN_ERROR
ContactError.INVALID_ARGUMENT_ERROR
ContactError.TIMEOUT_ERROR
ContactError.PENDING_OPERATION_ERROR
ContactError.IO_ERROR
ContactError.NOT_SUPPORTED_ERROR
ContactError.PERMISSION_DENIED_ERROR

49. Roadmap
• Media Capture
• Camera
• Contacts
• Events
• Accelerometer

50. Events
An event is an action that can be detected by your
Javascript code
In traditional JS programs, any element of the page
can have certain events
– ontouchstart, onclick, ...

51. Listening to Events
To use any event, you’ll want to use an event listener
document.addEventListener(EVENTNAME, onEvent, false);
function onEvent() {
// handle the event
}
EVENTNAME is the name of the event you want to listen to
onEvent() is the callback function triggered every time
the event is fired

52. Main Cordova Events
other events are specific to Cordova applications
• deviceready
• pause, resume
• online, offline
• batterycritical, batterylow, batterystatus
• backbutton, menubutton, searchbutton

53. deviceready
It is the most important in event in a Cordova app
Cordova consists of two code bases:
• native
• JavaScript
Once deviceready is fired, you know two things:
1. The DOM has loaded
2. the Cordova native API are loaded too
Only at this point you can try to call Cordova APIs

54. App lifecycle Events
Based on two main events:
pause
fires when an application is put into the background
resume
fires when a paused application is put back into the
foreground

55. Connection Events
When running in the WP emulator,
Based on two main events: the connection.status of the
device is always unknown
online the online event will NOT fire
fires when the application's network connection changes to
being online (that is, it is connected to the Internet)
offline
fires when the application's network connection changes to
being offline (that is, no Internet connection available)

56. Connection
If you need to know the type of connection, you have to
use the navigator.network.connection object
It has a type property with one of the following values:
Connection.UNKNOWN
Connection.ETHERNET
Connection.WIFI
Connection.CELL_2G
Connection.CELL_3G
Connection.CELL_4G
Connection.NONE

57. Battery Events
Based on three main events:
this value is
batterycritical device-specific
fires when the battery has reached the critical level threshold
batterylow
similar to batterycritical, but with a higher threeshold
the battery status must
batterystatus change of at least 1%
fires a change in the battery status is detected

58. Battery Events
The handler of a battery event is always called with an
object that contains two properties:
level (Integer)
The percentage of battery (0-100)
isPlugged (Boolean)
Represents whether or not the device is plugged in or not

59. Android buttons Events
Based on three main events:
backbutton
fires when the user presses the “back” button
menubutton
fires when the user presses the “menu” button
searchbutton
fires when the user presses the “search” button

60. Roadmap
• Media Capture
• Camera
• Contacts
• Events
• Accelerometer

61. Accelerometer
navigator.accelerometer
It is a global object that captures device motion in
the x, y, and z direction
You can call 3 methods on it:
• accelerometer.getCurrentAcceleration
• accelerometer.watchAcceleration
• accelerometer.clearWatch

62. getCurrentAcceleration
It gets the current acceleration along the x, y, and z
axis
getCurrentAcceleration(win, fail);
win
callback function with an Acceleration parameter
fail
error callback

63. watchAcceleration
It gets the device's current acceleration at a regular interval
var watchID =
navigator.accelerometer.watchAcceleration(win, fail,
[options]);
win
callback function with an Acceleration parameter, it is called
at regular intervals
fail
error callback
options
the interval is specified in the frequency parameter

64. clearWatch
Stop watching the Acceleration referenced by the
watch ID parameter
clearWatch(watchID);
watchID
ID returned by accelerometer.watchAcceleration

65. Acceleration
It contains Accelerometer data captured at a specific
point in time
these values include the effect of
Properties gravity (9.81 m/s^2)
x (Number)
Amount of acceleration on the x-axis. (in m/s^2)
y (Number)
Amount of acceleration on the y-axis. (in m/s^2)
z (Number)
Amount of acceleration on the z-axis. (in m/s^2)
timestamp (Timestamp)
Creation timestamp in milliseconds

66. Example
var options = { frequency: 3000 };
var watchID = navigator.accelerometer.watchAcceleration(win, fail,
options);
function win(acc) {
if((acc.x == 0) && (acc.y == 0) && (acc.z == 9,81)) {
console.log(“I am on a table”);
stop();
}
}
function fail() {
console.log(“error”);
}
function stop() {
if(watchID) {
navigator.accelerometer.clearWatch(watchID);
watchID = null;
}
}

67. Shake Detection
var previousReading = {x: null, y: null, z: null};
navigator.accelerometer.watchAcceleration(function (reading) {
var changes = {},
bound = 3;
if (previousReading.x !== null) {
changes.x = Math.abs(previousReading.x, reading.x);
changes.y = Math.abs(previousReading.y, reading.y);
changes.z = Math.abs(previousReading.z, reading.z);
}
if (changes.x>bound && changes.y>bound && changes.z>bound) {
console.log(‹shake detected');
}
previousReading = {
x: reading.x,
y: reading.y,
z: reading.z
}
}, null, { frequency: 300 });

68. References