Mojo.FilePicker

Namespace Detail

Method for picking a file from the device's local storage. Allows for selection by file type, with filtering for file extensions. This is the only sanctioned method for selecting a file from the file system.

Note:

It is not safe to push a new scene while handling the onSelect or onCancel callbacks from a Mojo.FilePicker. This is because the file picker is a separate scene, and is the active scene when the callback occurs. Instead, store the return data, and use it when your scene is reactivated.

Method Summary

Mojo.FilePicker.pickFile(params, stageController)

Method Detail

Mojo.FilePicker.pickFile(params, stageController)

Parameters

  • {Object} params - Object containing information about the file to select as described above.
  • {Object} stageController - The calling application's stage assistant.

params object description:

Type Name Required Description
function params.onSelect Required Method to call after selection is made and scene is returned to. The onSelect function is passed an object of the format described below as its first parameter.
function params.onCancel Optional Method to call after selection is canceled and scene is returned to.
array params.kinds Optional Array of pseudo types, which will result in a radio button widget at the bottom of the picker to allow the user to select among the specified file types. Allowable values are "image", "audio", "video", and "file". The default is that all kinds will be selectable.

If only one type is needed, use "kind:" along with the desired file type (string only, not an array) instead.
string params.defaultKind Optional The view to go to when the picker is first displayed. Allowable values are "image", "audio", "video", or "file". If no default is specified, the initially selected type will be "file".
string params.actionType Optional Selects the button text to be displayed when selecting a file of "image" type. If set to "attach", button will display "Attach Photo". If set to "open", button will display "Open Photo". Default is "open".
string params.actionName Optional String to override the default string defined by actionType. Replaces the text on the button that would otherwise say "Attach Photo" or "Open Photo".
array params.extensions Optional Array of file extensions (e.g., "pdf") to filter the files displayed in the picker. If not selected, there will not be any filtering by extension.
object params.crop Optional Object of the form crop: { width: 150, height: 150 }. When an image is selected, a cropping box of the specified size will be overlayed onto the image. The image can be moved by user gestures under the cropping box. When the select or attach button is pressed, information about the cropping position will be returned, in addition to the base image information.

Example params

{ kind: 'file', extensions: ['pdf', 'txt'] }
{ kinds: ['audio', 'video'], defaultKind: 'video' }
{ actionType: 'attach', kinds: ['image'], crop: { width: 150, height: 150 } }
{ actionType: 'attach', kinds: ['image'] }
{ actionType: 'attach', kinds: ['audio', 'video'], defaultKind: 'audio' }
{ actionName: 'Select', kinds: ['other'] }

Returned parameters

The following table describes the parameters returned for each file type. Path information (fullPath and iconPath) should be treated as opaque strings, and can be used directly with in-app <img> tags, etc., without the need for additional parsing. Formats are shown for reference only.

Return type Return parameters Type
"video" fullPath, in the form {"fullPath": "/full/path/to/file.ext"} string
iconPath, in the form {"iconPath: "/full/path/to/icon/name.ext:0:0:"} string
attachmentType string ("video")
size number (bytes)
isTmpVideoFile boolean
"image" fullPath, in the form {"fullPath": "/full/path/to/file.ext"} string
iconPath, in the form {"iconPath: "/full/path/to/icon/name.ext:0:0:"} string
attachmentType string ("image")
"file" fullPath, in the form {"fullPath": "/full/path/to/file.ext"} string
size number (bytes)
"audio" fullPath, in the form {"fullPath": "/full/path/to/file.ext"} string
iconPath, in the form {"iconPath: "/full/path/to/icon/name.ext:0:0:"} string

Sample returns

{"fullPath": "/media/internal/Open Source Information.pdf", "size": "262375"}

{"fullPath": "/media/internal/wallpapers/04.jpg",
  "iconPath": "/var/luna/data/extractfs/media/internal/wallpapers/04.jpg:0:0:",
  "attachmentType": "image"}

If "crop" parameters are specified for an image file, the following parameters will also be returned, in addition to the "fullPath", "iconPath", and "attachmentType" values. The example below contains sample values.

"cropInfo": {
  "window": {
      "focusX": 0.765625,
      "focusY": 0.84375,
      "sourceImage": "/media/internal/wallpapers/06.jpg",
      "scale": 1,
      "sourceWidth": 320,
      "sourceHeight": 480,
      "suggestedXSize": 150, //Size of crop specified
      "suggestedYSize": 150,
      "suggestedScale": 100, //Scale of the image
      "suggestedXTop": 170, //Position of the upper left corner
      "suggestedYTop": 330
  },
  "full": {
      "focusX": 0.765625,
      "focusY": 0.84375,
      "sourceImage": "/media/internal/wallpapers/06.jpg",
      "scale": 1,
      "sourceWidth": 320,
      "sourceHeight": 480,
      "suggestedXSize": 320,
      "suggestedYSize": 480,
      "suggestedScale": 100,
      "suggestedXTop": 85,
      "suggestedYTop": 165
  }
} 

Example use

var self = this; //Retain the reference for the callback
var params = { defaultKind: 'image',
  onSelect: function(file){
      self.controller.get('selection').innerHTML = Object.toJSON(file);
  }
}

Mojo.FilePicker.pickFile(params, this.controller.stageController);