# Mojo.Widget.ProgressBar

## Namespace Detail

### Overview

The Progress Bar is exactly the same as the Progress Pill except that you use `x-mojo-element="ProgressBar"` in your scene file. Otherwise, you would code it and manage just as you do the Progress Pill. In the default style, there isn't room for a title or any type of image on the bar, but the properties are supported nonetheless.

As with the Progress Pill, the Progress Bar is useful for showing progress while downloading, loading from a database, or just completing a long operation for which you have a sense of the duration. The indicator is designed to show a Bar image that corresponds to the model's value property, where a value of 0 has no bar exposed and a value of 1 has the bar 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="ProgressBar" id="progressbarId" class="progressbarClass"
>       name="progressbarName"></div>

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

### Events

>     Mojo.Event.listen(this.controller.get("progressbarId"),
>       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("progressbarId",
>       this.attributes = {
>           title: "Progress Bar",
>           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 |  | Widget's model property name.
title | String | Optional | Null | Dynamic title to show on 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.

### Model Properties

Model Property | Type | Required | Default | Description
--- | --- | --- | --- | ---
value | Integer | Required | Null | Current value of widget.
title | String | Optional | Null | Dynamic title to show on download bar.
image | String | Optional | Null | File path relative to app folder for dynamic image to show on 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.