Qt Quick Components

ProgressBar

A ProgressBar shows the continuing progress of a long-running operation to reassure the user that the operation is still progressing. More...

  • List of all members, including inherited members
  • Properties

    Detailed Description

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

    ProgressBar has two presentation modes:

    • determinate for when the period of time for the operation can be measured. In this case, the progress bar shows the proportion of progress.
    • indeterminate for when the period of time for the operation is unknown. The progress bar is animated but no proportion of 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, if an operation takes less than 3 seconds, it is not necessary to provide a 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 will look something 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 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, simply set the indeterminate property to true. Setting the different value properties of an indeterminate progress bar has no effect. An indeterminate progress bar will look something like the following image.

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

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

    Property Documentation

    indeterminate : bool

    If this is true, the progress bar is animated to indicate that the length of the operation is unknown. The value, minimum and maximum properties are ignored.

    If this is false, the progress bar is drawn to indicate progress between the minimum and maximum values.

    Default is false.


    maximumValue : real

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

    Default is 1.0


    minimumValue : real

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

    Default is 0.0


    value : real

    This current value of the progress bar. The progress bar length is calculated as the proportion that value is between the minimum and maximum values. For example, if value is half-way between the minimum and maximum values, the progress bar will be filled half way along.

    Default is 0.0