# Pickers

## Overview

The goal of the set of Picker Widgets is to present the same user interface across all applications for a common set of user tasks. Mojo offers pickers for Date, Time, and Integers that you should use whenever you want a user to be able to perform one of these tasks. The Picker widgets all present their choices as a linear sequence of values that wrap around; when you scroll to the end of a sequence, it simply continues back at the beginning.

### Styling

Picker widgets are known to be difficult to place within scenes as they take up a lot of horizontal screen real-estate.

The recommended way of styling a Picker in a scene is:

>     <div class="palm-row" x-mojo-focus-highlight="true">
>       <div class="palm-row-wrapper">
>           <div class="title">
>               <div id='datepicker' x-mojo-element="DatePicker"></div>
>           </div>
>       </div>
>     </div>

### Date Picker

The Date Picker allows you as the application developer to easily let a user view or update a date. By default, the picker provides selection inputs for day, month, and year. It operates using the JavaScript Date object so that it is easily integrated with your other JavaScript functionality, and it is turned into a JSON object for saving at a later time.

To setup a Date Picker:

>     this.dateModel = {date : new Date()};
>     this.controller.setupWidget('datepicker', {modelProperty:'date'}, this.dateModel);
>     this.propChange = this.propChange.bindAsEventListener(this);
>     this.controller.listen('datepicker', Mojo.Event.propertyChange, this.propChange);

When you receive a Mojo.Event.propertyChange event, it means your model has been updated by the user:

>     Mojo.Log.info("propertyChange event set property to this date in the event : %s and
>       the same thing in my model  %s ",
>       event.value, this.pickerModel.date);

### Time Picker

The Time Picker offers selection of the hour and minutes with an AM/PM selector. The Time picker uses the JavaScript Date object in its data model.

To setup a Time Picker:

>     this.timeModel = {time : new Date()};
>     this.controller.setupWidget('timepicker', {modelProperty:'time'}, this.timeModel);
>     this.propChange = this.propChange.bindAsEventListener(this);
>     this.controller.listen('timepicker', Mojo.Event.propertyChange, this.propChange);

When you receive a Mojo.Event.propertyChange event, it means your model has been updated by the user:

>     Mojo.Log.info("propertyChange event set property to this time in the event : %s and
>       the same thing in my model %s ",
>       event.value, this.pickerModel.time);

### Integer Picker

The Integer Picker is a simple number picker.

To setup an Integer Picker that shows all the number between 0 and 10 with a preset value of '5':

>     this.intModel = {intValue: 5};
>     this.controller.setupWidget('intpicker', {modelProperty:'intValue', min: 0, max: 10},
>       this.intModel);
>     this.propChange = this.propChange.bindAsEventListener(this);
>     this.controller.listen('intpicker', Mojo.Event.propertyChange, this.propChange);

When you receive a Mojo.Event.propertyChange event, it means your model has been updated by the user:

>     Mojo.Log.info("propertyChange event set property to this integer in the event : %s and
>       the same thing in my model %s ",
>       event.value, this.pickerModel.intValue);

### Extending Pickers

Picker Widgets all extend from the same basic widget type. If you would like to implement a new type of picker, subclass the Mojo.Widget._GenericPicker and pass a strategy object. All purpose-specific logic resides in the strategy, but all basic layout and event resides in the _GenericPicker.

## File Picker

The File Picker is an application you can use to allow a user to select files or media. The File Picker can show all files within the media partition* or limit the results presented by type (file, image, video or audio). You cannot embed the File Picker directly into your application, as it is actually an application itself. For more information on how this works, see Cross App Launching.

The presentation of the files will automatically differ by type. For example:

- Files - Name, icon, date, and size.
- Images - Album, thumbnails, and full screen preview
- Audio and Video - Name, thumbnail, and preview

By default, the File Picker will open the file the user selects with the registered application, wrapping the user task of selecting and opening.

To display all files in the media partition using the File Picker:

>     var params = {
>       onValidate: function(file){
>           if (file.fullPath.search(/bad/i) != -1) {
>               alert( $L('File not accepted') );
>               return false;
>           }
>           return true;
>       },
>       onSelect: function(file){
>           $('selection').innerHTML = Object.toJSON(file);
>       },
>       onCancel: function(){
>           $('selection').innerHTML = $L('no file selected');
>       }
>     };
>     Mojo.FilePicker.pickFile(params);

*Media Partition: the FAT-32 file partition that is accessible when attaching a webOS device through a USB connection (Mass Storage Mode)