Qt Reference Documentation

QML ProgressBar Element

Shows the progress or continuation of a long-running operation. More...

This element was introduced in Qt Quick Components 1.0.

Properties

Detailed Description

Some operations take a period of time to be performed and the user needs a confirmation that the operation is still ongoing. If the user does not get any confirmation, they might suspect that they did something wrong or that the device has broken. A progress bar is one of available mechanisms for providing this reassurance to the user.

ProgressBar has the following presentation modes:

  • determinate - the operation's duration is approximately known. The progress bar shows the proportion of the progress so far.
  • indeterminate - the operation's duration is unknown. The progress bar is animated but no proportion of the progress is indicated.

The user interface guidelines for a platform specify the occasions when a progress bar should be displayed and how to display it. However, a common rule of thumb is that if an operation takes less than 3 seconds, it is not necessary to show the progress bar.

Using a Determinate Progress Bar

A determinate progress bar has a minimum value, a maximum value and a current value. When you set the current value, the progress bar is drawn to indicate the proportion of that value between the minimum and maximum values.

For example, if the minimum value is 0 and the maximum value is 100, setting value to 25 will result in the progress bar being filled one quarter along and it will look like the image below.

The following code snippet creates a progress bar and demonstrates how a progress bar works. The timer is a repeating timer and, every time it is triggered, it increments the progress bar's value property. When the maximum value of the progress bar is reached, the "progress" is reset to the minimum value and it starts again.

 // Progress bar defined
 ProgressBar {
     id: pb1
     minimumValue: 0
     maximumValue: 100
     value: 0
 }

 // Timer to show off the progress bar
 Timer {
     id: simpletimer
     interval: 100
     repeat: true
     running: true
     onTriggered: pb1.value < pb1.maximumValue ? pb1.value += 1.0 : pb1.value = pb1.minimumValue
 }

Using an Indeterminate Progress Bar

To show an indeterminate progress bar, set the indeterminate property to true. Setting the different value properties of an indeterminate progress bar has no effect. An indeterminate progress bar looks like the image below.

The following code snippet binds the visible property of an indeterminate progress bar to the running property of the timer from the example above.

 // An indeterminate progress bar that is shown when the timer is running
 ProgressBar {
     id: pb2
     indeterminate: true
     visible: simpletimer.running
 }

Property Documentation

indeterminate : bool

Indicates whether the operation's duration is known or not. The property can have the following values:

  • true - the operation's duration is unknown, so the progress bar is animated. The value, minimum, and maximum properties are ignored.
  • false - the operation's duration is known, so the progress bar is drawn to indicate progress between the minimum and maximum values.

The default value is false.


maximumValue : real

The end value of a long-running operation. The progress bar shows its full width when the current value is set to maximumValue.

The default value is 1.0


minimumValue : real

The start value of a long-running operation. The progress bar's width is zero when the current value is set to minimumValue.

The default value is 0.0


platformInverted : bool

Symbian:

If platformInverted is true, the component is visualized with the inverted style. For more information, see Using Inverted Style with Symbian Components. By default platformInverted is false.

This property group was introduced in Qt Quick Components 1.1.


value : real

The progress bar's current value. The progress bar's length is calculated as the proportion of value between minimumValue and maximumValue. For example, if the value is in the middle of minimumValue and maximumValue, the progress bar will be filled half way along.

The default value is 0.0