Contents
Gauge  Sample Help

Sample Description: Gauge

Points of Interest

Generating Random Numbers

Using Scrollbars to Change Values

Displaying Values in Gauges

Control

Gauge

For Help on Help, Press F1


Gauge

The Gauge control allows you to provide the user with status on the progress of a task. For example, a gauge is often used to indicate what percentage of a task has been completed. The Orientation property of a gauge indicates how the control will be graphically displayed. A Vertical orientation will display a fill from top to bottom, while a Horizontal orientation will display a fill from left to right. The Min/Max properties specify the range of the gauge. The Value property specifies the current value being displayed between the Min and Max values.

In the sample form, there are 12 gauge controls and two scrollbars. One scrollbar is used to set the number of rolls per turn and the other is used to set the maximum value of all gauges. When the Roll button is clicked, a For loop begins running for the number of rolls per turn specified. For each roll, a random number is generated between 1 and 12. For each random number generated, the corresponding gauge value is incremented.

This sample will give you a good understanding of how gauges can be used to display the status of a task that is running. In the example, the task is to generate several random numbers and display how many of each number between 2 and 12 were generated.


Generating Random Numbers

In the sample, generating random numbers is done in the RollDice function shown below.

Function RollDice(low As Integer, high As Integer, n As Integer) As Integer

  Dim range, sum, i As Integer

  range = high - low + 1

  sum = 0

  For i = 1 To n

      sum = sum + rnd() * range + low

  Next i

  RollDice = sum

End Function

The RollDice function accepts three parameters: a low value, a high value, and a count value. The low and high values specify the range for generating a random number. In the example, 1-6 is used. The count value is used to append random numbers to each other. This gives an effective range of 2-12.


Using Scrollbars to Change Values

In the sample form, scrollbars are used to change the values used by the application. In this case, the maximum value of gauges and the number of rolls per turn are set. The scrollbars have two events that need to be handled:  Scroll and Change. The Scroll event is triggered when the scrollbar is moved by dragging, while the Change event is triggered when either end of the scrollbar is clicked. The following method is executed when the "Number of Rolls" scrollbar is moved.

Sub sbrRolls_Scroll()

  ' Update the number of rolls per turn

  NumRolls = sbrRolls.Value

End Sub

The value of the scrollbar is used to set the NumRolls property. Since this is a "procedural" property, the setNumRolls method is executed automatically when this property is set as shown below.  This is a good technique to keep multiple items such as lblRollsPerTurn and sbrRolls in sync with each other.

Sub setNumRolls(r as integer)

  lblRollsPerTurn.Text = r

  sbrRolls.Value = r

End Sub

The Caption property could have also been used. The following method is executed when the same scrollbar is clicked on either end.

Sub sbrRolls_Change()

  ' Update the NumRolls embedded integer and the rolls per turn text

  NumRolls = sbrRolls.Value

End Sub

NumRolls is a property in the sample form. It is an Integer data type and is used in the For loop that generates random numbers.


Displaying Values in Gauges

Displaying values in gauges involves setting the Value property to a number. This demonstrates the technique of setting the Value property through program code. The following program code can be found in the btnRoll_Click method.

Sub btnRoll_Click()

  Dim i, r as integer

  Dim gauge As Gauge

  ' Disable the roll button to prevent excessive clicks

  btnRoll.Enabled = "False"

  For i = 1 To NumRolls

    r = RollDice(1, 6, 2)

    Select Case r

      Case 2

        gauge = Gauge1

      Case 3

        gauge = Gauge2

      Case 4

        gauge = Gauge3

      Case 5

        gauge = Gauge4

      Case 6

        gauge = Gauge5

      Case 7

        gauge = Gauge6

      Case 8

        gauge = Gauge7

      Case 9

        gauge = Gauge8

      Case 10

        gauge = Gauge9

      Case 11

        gauge = Gauge10

      Case 12

        gauge = Gauge11

    End Select

    ' Increment the gauge and the counter

    gauge.Value = gauge.Value + 1

    RollCounter = RollCounter + 1

  Next i

  btnRoll.Enabled = "True"

End Sub

RollDice is a function that returns a random number between 2 and 12. NumRolls is a procedural property that contains the number of rolls being taken on this turn. When a random number is returned, the Dimmed "gauge," which is defined as a Gauge, is used to set the gauge number determined by the random number generated. The Value property is then incremented by 1.