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

Transcript

1. Accessing Accessing Device Features Ivano Malavolta Ivano Malavolta ivano.malavolta@univaq.it http://www.di.univaq.it/malavolta
2. Roadmap • Media Capture • Camera • Camera • Contacts • Events • Accelerometer
3. Media Capture navigator.device.capture Provides access for capturing • Audio Audio Audio Audio • Image Image Image Image • Video Video Video Video • Video Video Video Video directly from the device
4. The Capture Object navigator.device.capture Properties Properties supportedAudioModes supportedAudioModes supportedAudioModes supportedAudioModes The audio recording formats supported by the device supportedImageModes supportedImageModes supportedImageModes supportedImageModes The recording image sizes and formats supported by the device the device supportedVideoModes supportedVideoModes supportedVideoModes supportedVideoModes The recording video resolutions and formats supported by the device They all contain an array of ConfigurationData ConfigurationData ConfigurationData ConfigurationData objects
5. ConfigurationData It is used to describe media capture modes media capture modes media capture modes media capture modes supported by the device Properties: 1. 1. 1. 1. Type Type Type Type: String The string in lower case representing the media type The string in lower case representing the media type – video/3gpp – video/quicktime – image/jpeg – audio/amr – audio/wav
6. ConfigurationData 2. 2. 2. 2. height height height height: integer The height of the image or video in pixels The height of the image or video in pixels 3. 3. 3. 3. width width width width: integer The width of the image or video in pixels In the case of a sound clip, the value of these attributes In the case of a sound clip, the value of these attributes is 0
7. Example var imageModes = navigator.device.capture.supportedImageModes; 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 asynchronous operation asynchronous operation asynchronous operation to capture audio recordings recordings It uses the device's default audio recording default audio recording default audio recording default audio recording app app app app The operation allows the device user to capture multiple recordings multiple recordings multiple recordings multiple recordings in a single session multiple recordings multiple recordings multiple recordings multiple recordings in a single session
10. Capturing Audio When the capture operation is finished, it will invoke the CaptureCB CaptureCB CaptureCB CaptureCB callback with an array the CaptureCB CaptureCB CaptureCB CaptureCB callback with an array of MediaFile objects If the operation is terminated by the user before an audio clip is captured, the CaptureErrorCB CaptureErrorCB CaptureErrorCB CaptureErrorCB callback will be invoked callback will be invoked
11. Capture Audio Options Encapsulates audio capture configuration options Properties: • limit limit limit 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 Duration Duration Duration (not supported in Android unlimited) • Duration Duration Duration Duration (not supported in Android unlimited) The maximum duration of an audio sound clip, in seconds • Mode Mode Mode Mode (not supported in Android and iOS) The selected audio mode, it must match one of the elements in capture.supportedAudioModes audio/wav audio/amr
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 asynchronous operation asynchronous operation asynchronous operation to capture images images It uses the device camera application device camera application device camera application device camera application The operation allows the device user to capture multiple multiple multiple multiple images images images images in a single session multiple multiple multiple multiple images images images images in a single session
15. Capturing Images Similarly to captureAudio... When the capture operation is finished, it will invoke the CaptureCB CaptureCB CaptureCB CaptureCB callback with an array of MediaFile objects If the operation is terminated by the user before any If the operation is terminated by the user before any image is captured, the CaptureErrorCB CaptureErrorCB CaptureErrorCB CaptureErrorCB callback will be invoked
16. Capture Image Options Encapsulates image capture configuration options Properties: • limit limit limit 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 Mode Mode 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, navigator.device.capture.captureImage(win, fail, options); function win(mediaFiles) { var i; for (i=0; i<mediaFiles.length; i++) { upload(mediaFiles[i]); } } It is very similar to the audio 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 asynchronous operation asynchronous operation asynchronous operation to record videos It uses the device video recording application device video recording application device video recording application device video recording application The operation allows the device user to capture multiple multiple multiple multiple recordings recordings recordings recordings in a single session
20. Capturing Videos Similarly to captureAudio... When the capture operation is finished, it will invoke the CaptureCB CaptureCB CaptureCB CaptureCB callback with an array of MediaFile objects If the operation is terminated by the user before any If the operation is terminated by the user before any video is recorded, the CaptureErrorCB CaptureErrorCB CaptureErrorCB CaptureErrorCB callback will be invoked
21. Capture Video Options Encapsulates video recording configuration options Properties: • limit limit limit 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 duration duration duration (not supported in Android and iOS unlimited) • duration duration duration duration (not supported in Android and iOS unlimited) The maximum duration of a video clip, in seconds • m m m mode ode ode ode (not supported in Android and iOS) The selected video recording mode, it must match one of the elements in capture.supportedVideoModes video/quicktime video/3gpp
22. Video Example navigator.device.capture.captureVideo(win, fail, {}); navigator.device.capture.captureVideo(win, fail, {}); function win(mediaFiles) { var i; for (i=0; i<mediaFiles.length; i++) { upload(mediaFiles[i]); } } It is very similar to the 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 Name Name Name (String) The name of the file, without path information fullPath fullPath fullPath fullPath (String) The full path of the file, including the name Type Type Type Type (String) Type Type Type Type (String) The mime type lastModifiedDate lastModifiedDate lastModifiedDate lastModifiedDate (Date) The date and time that the file was last modified Size Size Size Size (Integer) The size of the file, in bytes
24. Capture Errors Encapsulates the error code resulting from a failed media capture operation media capture operation It contains a pre pre pre pre- - - -defined defined defined defined error error error error code code code code CaptureError.CAPTURE_INTERNAL_ERR CaptureError.CAPTURE_APPLICATION_BUSY CaptureError.CAPTURE_APPLICATION_BUSY CaptureError.CAPTURE_INVALID_ARGUMENT CaptureError.CAPTURE_NO_MEDIA_FILES CaptureError.CAPTURE_NOT__SUPPORTED
25. Roadmap • Media Capture • Camera • Camera • Contacts • Events • Accelerometer
26. Camera A dedicated API for capturing images from the device’s default camera application 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 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 q q q quality uality uality uality (integer) Quality of saved image Quality of saved image Range [0, 100] d d d destinationType estinationType estinationType estinationType (Integer)
30. Camera Options s s s sourceType ourceType ourceType ourceType (integer) allowEdit allowEdit allowEdit allowEdit (Boolean) Allow simple editing of image before selection
31. Camera Options encodingType encodingType encodingType encodingType (integer) targetWidth targetWidth targetWidth targetWidth, , , , targetHeight targetHeight targetHeight targetHeight (Integer) Width/height in pixels to scale image
32. Camera Options mediaType mediaType mediaType mediaType (integer) correctOrientation correctOrientation correctOrientation correctOrientation (Boolean) Rotate the image to correct for the orientation of the device during capture
33. Camera Options saveToPhotoAlbum saveToPhotoAlbum saveToPhotoAlbum saveToPhotoAlbum (Boolean) Save the image to the photo album on the device after Save the image to the photo album on the device after capture Every platform has its own quirks, you better check Every platform has its own quirks, you better check them on the Cordova documentation
34. Camera Example navigator.camera.getPicture(win, fail, { quality: 50, { quality: 50, destinationType: destinationType.FILE_URI, pictureSource.PHOTOLIBRARY }); function win(imageURI) { var element = $(“#block”); element.src(imageURI); element.src(imageURI); } // fail function omitted here
35. Roadmap • Media Capture • Camera • 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 You can call 2 methods on navigator.contacts • contacts.create contacts.create contacts.create contacts.create • contacts.find contacts.find contacts.find contacts.find
37. Creating contacts navigator.contacts.create(properties) It is a synchronous synchronous synchronous synchronous function that returns a new Contact Contact Contact Contact object To persist the Contact object to the device, you have to invoke the Contact.save method 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. ex. var contact = navigator.contacts.create({ "displayName": “Ivano“ });
39. The Contact Object It represents a user contact It represents a user contact It represents a user contact 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 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() clone() clone() clone() • clone() clone() clone() clone() Returns a new Contact object that is a deep copy of the calling object, its id property is null • remove(win, fail) remove(win, fail) remove(win, fail) remove(win, fail) Removes the contact from the device contacts database Removes the contact from the device contacts database • save(win, fail) save(win, fail) save(win, fail) save(win, fail) Saves a new contact to the device contacts database, or updates an existing contact if a contact with the same id id id 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, contactFields, contactSuccess, contactError, contactFindOptions ); It is an asyncronous asyncronous asyncronous asyncronous function that queries the device It is an asyncronous asyncronous asyncronous asyncronous function that queries the device contacts database and returns an array of Contact Contact Contact Contact objects
44. Find Parameters contactFields contactFields contactFields contactFields, String Contact fields to be used as search qualifier. Only these Contact fields to be used as search qualifier. Only these fields will have values in the resulting Contact objects contactSuccess contactSuccess contactSuccess contactSuccess Success callback function that is invoked with the array of contacts returned from the contacts database contactError contactError contactError contactError [optional] Error callback function contactFindOptions contactFindOptions contactFindOptions 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 objects resulting from a find operation var fields = ["displayName", "name"]; // or [“*”] navigator.contacts.find(fields, win, fail); function win(contacts) { 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 Properties Properties Properties filter filter filter filter (String) (Default: "") The search string used to find contacts A case-insensitive, partial value match is applied to each A case-insensitive, partial value match is applied to each field specified in the contactFields contactFields contactFields contactFields parameter multiple multiple multiple 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); 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 error occurs ContactError.UNKNOWN_ERROR ContactError.INVALID_ARGUMENT_ERROR ContactError.TIMEOUT_ERROR ContactError.PENDING_OPERATION_ERROR ContactError.IO_ERROR ContactError.IO_ERROR ContactError.NOT_SUPPORTED_ERROR ContactError.PERMISSION_DENIED_ERROR
49. Roadmap • Media Capture • Camera • Camera • Contacts • Events • Accelerometer
50. Events An event is an action that can be detected by your Javascript code Javascript code In traditional JS programs, any element of the page can have certain events – ontouchstart, onclick, ... – 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 • backbutton, menubutton, searchbutton
53. deviceready It is the most important in event in a Cordova app Cordova consists of two code bases: Cordova consists of two code bases: • native • JavaScript Once deviceready is fired, you know two things: 1. The DOM has loaded 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 Based on two main events: When running in the WP emulator, the connection.status of the device is always unknown online fires when the application's network connection changes to being online (that is, it is connected to the Internet) device is always unknown the online event will NOT fire 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 use the navigator.network.connection object It has a type property with one of the following values: Connection.UNKNOWN Connection.ETHERNET 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 fires when the battery has reached the critical level threshold batterylow similar to , but with a higher threeshold this value is device-specific similar to batterycritical, but with a higher threeshold batterystatus fires a change in the battery status is detected the battery status must change of at least 1%
58. Battery Events The handler of a battery event is always called with an object that contains two properties: level level level level (Integer) The percentage of battery (0-100) isPlugged isPlugged isPlugged 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 fires when the user presses the “menu” button searchbutton fires when the user presses the “search” button
60. Roadmap • Media Capture • Camera • 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: You can call 3 methods on it: • accelerometer.getCurrentAcceleration accelerometer.getCurrentAcceleration accelerometer.getCurrentAcceleration accelerometer.getCurrentAcceleration • accelerometer.watchAcceleration accelerometer.watchAcceleration accelerometer.watchAcceleration accelerometer.watchAcceleration • accelerometer.clearWatch accelerometer.clearWatch accelerometer.clearWatch accelerometer.clearWatch
62. getCurrentAcceleration It gets the current acceleration along the x, y, and z axis axis getCurrentAcceleration(win, fail); win win win win callback function with an Acceleration Acceleration Acceleration Acceleration parameter fail fail fail 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 win win win callback function with an Acceleration Acceleration Acceleration Acceleration parameter, it is called at regular intervals fail fail fail fail fail fail fail fail error callback options options options options the interval is specified in the frequency parameter
64. clearWatch Stop watching the Acceleration referenced by the watch ID parameter watch ID parameter clearWatch(watchID); watchID watchID watchID watchID ID returned by accelerometer.watchAcceleration ID returned by accelerometer.watchAcceleration
65. Acceleration It contains Accelerometer data captured at a specific point in time point in time Properties Properties Properties Properties x x x x (Number) Amount of acceleration on the x-axis. (in m/s^2) y y y y (Number) these values include the effect of gravity (9.81 m/s^2) Amount of acceleration on the y-axis. (in m/s^2) z z z z (Number) Amount of acceleration on the z-axis. (in m/s^2) timestamp timestamp timestamp timestamp (Timestamp) Creation timestamp in milliseconds
66. Example var options = { frequency: 3000 }; var watchID = navigator.accelerometer.watchAcceleration(win, fail, options); 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”); 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 = {}, 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'); console.log(‹shake detected'); } previousReading = { x: reading.x, y: reading.y, z: reading.z } }, null, { frequency: 300 });
68. References