# 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);