UserGuide

iOS Progress Bar

From Xojo Documentation

This control displays a horizontal progress bar to indicate how long an operation is taking and to show how close it is to completion.

Below are commonly used properties. Refer to iOSProgressBar for the complete list.

Properties

CurrentValue

A Double that indicates the current value of the Progress Bar. You use this to indicate how close the Progress Bar is to completion.

MaxValue

A Double that is the maximum value of the Progress Bar. When Current Value reaches MaxValue, the Progress Bar indicates the task has completed.

MinValue

A Double that is the minimum value of the Progress Bar. This is most commonly 0, but it can also be a other values, including negative values.

Visible

A boolean that indicates if the Progress Bar is visible when your app runs. You usually do not display the Progress Bar until the actual operation it is tracking is in progress.

Usage

iOS Progress Bar and Progress Wheel

A Progress Bar is typically used in conjunction with a long-running task that is in a Thread. You will typically use a Timer to update the Progress Bar periodically based on information from the Thread.

There are two ways that Progress Bars are used. In some cases, you can set the MaxValue to the number of tasks the operation is performing and then increment CurrentValue each time a task is completed. In other cases, you may want to have the Progress Bar go from 0 to 100 and calculate a percentage complete based on the tasks being performed.

As a simple example so you can see how a Progress Bar value moves, you can have a Timer set with a Period of 200ms with this code in its Action event handler to update a Progress Bar:

TestProgressBar.Value = TestProgressBar.Value + 1

If TestProgressBar.Value > TestProgressBar.MaxValue Then
Me.Mode = Timer.Modes.Off // stop Timer
End If

When you know exactly what you are processing, you can set the Min and Max values. For example you could have code that is looping through an array to process its information. You could set the MaxValue to the UBound of the array and the update the CurrentValue each time through the loop. This code on a Timer could do that:

For i As Integer = 0 To MyArray.UBound
value = MyArray(i)
Process(value)
MyProgress.CurrentValue = i
Next

If you are processing a large amount of data, it is usually a better idea to use a percentage rather than set MaxValue to some high number. In this case, you have MinValue as 0, MaxValue as 100 and calculate the percentage complete. For example, if you have 736 items and are on item 215, then you would calculate its percentage like this and use the percentage value to update the Progress Bar:

Const kMax = 736
For i As Integer = 0 to kMax
Dim pct As Double
pct = i / kMax
MyProgress.CurrentValue = pct
Next

Example Projects

  • Examples/iOS/Controls/ProgressExample

See Also

iOSProgressBar, Timer, Thread classes; UserGuide:iOS Progress Wheel, UserGuide:iOS UI topics