UserGuide

Mobile Progress Bar

From Xojo Documentation

Revision as of 19:26, 22 March 2021 by Gperlman (talk | contribs) (Properties)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

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 MobileProgressBar for the complete list.

Properties

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

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

MinimumValue - A Double that is the minimum value of the Progress Bar. This is most commonly 0, but it can also be any 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 MaximumValue to the number of tasks the operation is performing and then increment Value 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 Run event handler to update a Progress Bar:

TestProgressBar.Value = TestProgressBar.Value + 1

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

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

For i As Integer = 0 To MyArray.LastIndex
value = MyArray(i)
Process(value)
MyProgress.Value = i
Next

If you are processing a large amount of data, it is usually a better idea to use a percentage rather than set MaximumValue to some high number. In this case, you have MinimumValue as 0, MaximumValue 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
Var pct As Double
pct = i / kMax
MyProgress.Value = pct
Next

Example Projects

  • Examples/iOS/Controls/ProgressExample

See Also

MobileProgressBar, Timer, Thread classes; UserGuide:Mobile Progress Wheel topic