# Mojo.Widget.ProgressPill

## Namespace Detail

### Overview

When you need to show progress while downloading, loading from a database, or just completing a long operation for which you have a sense of the duration, you can use Progress Pill as the indicator. This indicator is designed to show a Pill image that corresponds to the model's value property, where a value of 0 has no pill exposed and a value of 1 has the pill in a complete position. To control the indicator, initialize its value at 0, then progressively update the model property until it reaches the value of 1. The best way to do this is by using an interval timer, to which you can respond by increasing the progress indicator's value property incrementally and calling the updateModel function.

### Declaration

>     <div x-mojo-element="ProgressPill" id="progresspillId"
>       class="progresspillClass" name="progresspillName"></div>

Properties | Required | Value | Description
--- | --- | --- | ---
x-mojo-element | Required | ProgressPill | Declares the widget as type 'ProgressPill'.
id | Required | Any String | Identifies the widget element for use when instantiating or rendering.
class | Optional | Any String | There is no default class for ProgressPill, but you can assign one if you want to apply custom styling.
name | Optional | Any String | Adds a unique name to the ProgressPill widget; generally used in templates.

### Events

>     Mojo.Event.listen(this.controller.get("progresspillId"),
>       Mojo.Event.progressIconTap, this.handleUpdate);

Event Type | Value | Event Handling
--- | --- | ---
Mojo.Event.progressIconTap | {model: this.controller.model} | The icon in the bar was tapped, app-specific action but usually cancel operation.
Mojo.Event.progressComplete |  | Progress is complete.

### Instantiation

>     this.controller.setupWidget("progresspillId",
>       this.attributes = {
>           title: "Progress Pill",
>           image: "images/header-icon.png",
>           modelProperty: "progress"
>       },
>       this.model = {
>           iconPath: "../images/progress-bar-background.png",
>           progress: 0
>       }
>     );

### Attribute Properties

Attribute Property | Type | Required | Default | Description
--- | --- | --- | --- | ---
modelProperty | String | Optional | value | Widget's model property name
modelStartProperty | String | Optional | modelStartProperty | Name of start value property for this widget instance
title | String | Required | Null | Dynamic title to show on download bar
titleRight | String | Optional | Null | Dynamic title to show on the right side of the download bar
image | String | Optional | Null | File path relative to app folder for dynamic image to show on bar
icon | String | Optional | Null | CSS class for icon to display on the bar
iconPath | String | Optional | Null | File path relative to app folder for icon

### Model Properties

Model Property | Type | Required | Default | Description
--- | --- | --- | --- | ---
value | Integer | Required | Null | Current value of widget; if value is undefined or negative, will show in "button-mode" which gives a selected class
title | String | Required | Null | Dynamic title to show on download bar
titleRight | String | Optional | Null | Dynamic title to show on the right side of the download bar
image | String | Optional | Null | File path relative to app folder for dynamic image to show on bar
modelStartProperty | Integer | Optional | Null | Starting position of the progress bar

### Methods

To invoke a method on a widget, use the scene controller's `get` method for the desired widget, and append `mojo` followed by the method.

Example:

>     this.controller.get('myWidget').mojo.getValue()

Method | Arguments | Description
--- | --- | ---
reset |  | Resets the progress to 0.
cancelProgress |  | Stops progress and leaves the progress pill visually where it was.