ZirconProgressIndicator
Need a circular progress indicator? Need it animated, with an attached cancel button, and indeterminate state too? Need to customize the colors? ZirconProgressIndicator handles these tasks so you don't have to.
Requirements
This control requires Artisan Kit 1.2.1, which requires Xojo 2019 Release 2. Only desktop projects are supported.
Installation
Open the binary project and copy both the ZirconProgressIndicator class and ArtisanKit module into your project. If you already use Artisan Kit and encounter compile errors with the control, your ArtisanKit module needs to be updated to the included version.
Getting Started
Drag a ZirconProgressIndicator onto a window, just like any other control. The indicator will fill the smallest dimension. This means a 100x150 control will draw a 100x100 indicator, vertically centered. The control can then be used like a standard ProgressBar control.
Events
Event CancelPressed ()
If the cancel button has been pressed, this event will be triggered.
Properties
Animated As Boolean = True
If true, the properties BackColor
, ForeColor
, Maximum
, Minimum
, Value
, and Progress
will animate their value changes. Visual changes will be applied over the next 0.25 seconds, however reading the property will immediately return the new value.
AutomaticBorderColor As Boolean
Enabled by default, this property causes the indicator to calculate the border color based on the background color of the window and the background color of the control, accounting for the opacity of the control's background color. This allows the control to automatically adapt for macOS 10.14's dark mode. When enabled, the BorderColor
property is ignored.
BackColor As Color = &cFFFFFFFF
The background color of the fillable section of the indicator.
BorderColor As Color
When AutomaticBorderColor
is turned off, specifies the border color around the indicator. Translucency is supported with this property.
CanCancel As Boolean = True
If true, the control will draw a clickable square stop icon in the middle of the indicator. If clicked, the CancelPressed
event will be fired.
ForeColor As Color = &c4A91D5
The fill color of the indicator.
Indeterminate As Boolean = False
If true, the indicator will draw a continuous spinner to indicate that the progress cannot be predicted. Unlike the Xojo ProgressBar, the indeterminate state will not be set by making the minimum and maximum values equal. Only setting this property to true will change the state.
Maximum As Double = 100
The maximum of value of the indicator. Setting the maximum lower than the current value will adjust the value too.
Minimum As Double = 0
The minimum value of the indicator. Setting the minimum greater than the current value will adjust the value too.
Progress As Double = 0.5
Percentage of the job complete. Values < 0 or > 1 are adjusted to fit in range.
Value As Double = 50
The numeric value of the job completion. Values outside the range of the minimum / maximum are automatically brought into range. You may use either the Progress
property or Value
property, depending on preference.
Methods
Function Version() As String
Returns the version number of the class. Can also be found in the class attributes.
Shared Methods
Shared Function Render (Width As Integer, Height As Integer, ScalingFactor As Double, MinorAngle As Double, MajorAngle As Double, ForeColor As Color, BackColor As Color, BorderColor As Color, CancelState As ZirconProgressIndicator.CancelStates) As Picture
Be warned, this is an advanced feature use to generate indicator images at any state.
Width
andHeight
specify the dimensions in points for the image.ScalingFactor
parameter is a multiplier used for high resolution images. The pixel dimensions of the returned image will be (Width * ScalingFactor) * 72.MinorAngle
is the trailing angle. 0° is east, -90° north, 90° south, and 180° west. Values beyond range are perfectly acceptable. Values beyond range will be reduced into range. For example, 270° and 630° would both be reduced to -90°.MajorAngle
is the leading angle. Same rules apply.ForeColor
is the color of the fill.BackColor
is the color of the track.BorderColor
is the border color around the track.CancelState
is used to specify wether or not to draw a cancel button.