Code Of The Week Issue #4 for Visual Basic

Visual Basic Code of the Week (COTW)
http://www.codeoftheweek.com
Issue #4
All content and source code is Copyright (c) 1997 by C&D Programming Corp. None of the source can be reprinted in any manner without express written permission of C&D Programming Corp.
If you would like to view this page in HTML format, point your browser to http://www.codeoftheweek.com/issues/0004.html

Subscription Update

Thank you for trying Code of the Week for Visual Basic.

Your free trial expires after you receive your fourth issue. If you want to continue to receive Code of the Week you can get 52 issues of COTW for only $19.95. This is a full year of Visual Basic source code and information to help with all your development. So don't wait, subscribe now! The quickest way to subscribe is to jump to our online order form at http://www.codeoftheweek.com/order.html

We accept payment by Mastercard, Visa, check or money order. All payments must be in U.S. Dollars. If you are an international customer paying by credit card is usually the easiest method of payment.

If you prefer not to visit our web site:

1. Enclose a note with your email address and name.

2. If you are paying by credit card, make sure you include the credit card number, credit card expiration and name on the credit card and your signature. If you are paying by check, make it payable to C&D Programming Corp.

3. Mail it to:
C&D Programming Corp.
PO Box 20128
Floral Park, NY 11002-0128

4. As soon as we receive your payment you will be added to our paid subscriber list.

Now, onto the fun stuff!

Requirements for this Issue

The source code in this issue is designed for Visual Basic 4.0 and higher. Similiar techniques can be used for Visual Basic 3.0, it would just need to be converted to a regular BAS module. If anyone is interested in VB 3.0 source code, please contact us. We don't currently have it available, but if we get enough requests we will convert it.

In this Issue

In this issue we are going to implement a gauge control without requiring the gauge control VBX or OCX. This will avoid having to ship yet another control with your application. It also provides some better error checking and some features to improve performance.

cGauge Class

This class is a replacement for the standard Gauge VBX/OCX included in Visual Basic. It allows you to show a gauge or meter bar to indicate the progress of a particular task. The uniqueness of this class is that it uses a standard Picture Control.

All you do to use this class is drop a Picture Control on your form and resize it to the size you want. Create an instance of the class, define a couple of properties and execute your task. During your task you need to call the Current property to assign the current value to the gauge. Assigning this property will automatically update the control to show how close to completion the task is.

This class works by using the Line method to draw a box on the picture control to simulate a gauge. The Refresh method is the one that does all the work. A good exercise would be to modify it to work vertically as well as horizontally (which is the default method). If anyone implements this and would like to share it with the rest of our subscribers, let us know.

Properties

GaugeControl - The Picture Control (or any control that supports the Line method) that you want to draw the gauge in.
Min - Minimum step value of the process (if you have 10 steps to complete, the minimum value would be 1 and the maximum value would be 10).
Max - Maximum step value of the process.
Current - The current value of the process (In the example above where you have 10 steps and you set the Current value to 6, the bar drawn will cover 60% of the picture box).
UpdateInterval - Allows you to control how often the actual gauge will be refreshed. It defaults to updating every 100 steps or if there are less than 100 steps it defaults to 1. See the notes about this feature below.
BarColor - The color of the bar that shows the progress of the task. You can use the standard Visual Basic constants (such as vbWhite or vbBlack) or the RGB function. Refer to the Visual Basic help for complete details.

NOTE:

This UpdateInterval feature is really only important for when you have many steps (over 50 or so). Every screen refresh of the gauge takes a significant amount of CPU cycles (time). The more you refresh the control, the greater the overhead the gauge. Depending on the task, you can implement a gauge that will take more time to update than the entire process takes to run.

An example of a case like this would be a calculation loop that was able to be done completely in memory. If each iteration of the loop occurs very fast and you update the gauge on each iteration, it is likely that using the gauge will increase the total time to complete the calculation significantly. The UpdateInterval forces the gauge to only update every x times the Current property is incremented. Let's say you have a task that has 1000 steps. By default the UpdateInterval will be set to 10. This means the gauge will only update when Current is equal to 10, 20, 30, 40, and so on. Instead of updating the gauge 1000 times the cGauge class will only update it 100 times, which will save LOTS of CPU cycles.

Methods

Refresh - Should not ever need to be called. Use the Current property to do a Smart Refresh.
QuickStart - This provides a quicker way to set the values of several properties at once. You need to pass this method the picture control, min value and max value.

Sample Usage

This sample assumes you have a form that has a picture control on it called pictGauge.

Dim oGauge as New cGauge

oGauge.QuickStart pictGauge, 0, 100
For x = 0 to 100
    ... Do something ...
    oGauge.Current = x
Next

Source Code

Just paste this code into a Class Module and name the class module cGauge.

'----------------------------------------------------------------------
'
'   Class:          cGauge
'   Written By:     C&D Programming Corp.
'   Create Date:    9/29/97
'
'   Purpose:        Implement a simple, quick gauge control without
'                   requiring an extra control to ship with your
'                   application.
'
'   Notes:          To use this, drop a picture control on the form
'                   where you want to have a gauge and size
'                   it to be the size you want. This class does
'                   not resize and controls.
'
'   Sample Call:    Dim G as New cGauge
'
'                   G.QuickStart pictGauge, 0, 100
'                   For x = 0 to 100
'                       ... Do something ...
'                       G.Current = x
'                   Next
'----------------------------------------------------------------------

Option Explicit

Private mctlGauge As Control        ' control to draw the gauge in
Private mlMin As Long               ' min value of the gauge control
Private mlMax As Long               ' max value of the gauge control
Private mlCurrent As Long           ' current value of the gauge control
Private mlBarColor As Long          ' color of the gauge bar, default is vbBlue
Private mlUpdateInterval As Long    ' how often the bar actually gets drawn
                                    ' the bigger the interval the less the control
                                    ' actually gets updated. But, the bigger the
                                    ' interval, the less overhead the gauge
                                    ' imposes on the process you are running
                                    ' Drawing on a control is a very time
                                    ' consuming process as far as CPU cycles
                                    ' go.


Public Property Get GaugeControl() As Control
    Set GaugeControl = mctlGauge
End Property

Public Property Set GaugeControl(ctlGauge As Control)
    Set mctlGauge = ctlGauge
    ctlGauge.AutoRedraw = True
    BarColor = vbBlue
End Property

Public Property Get Min() As Long
    Min = mlMin
End Property

Public Property Let Min(lMin As Long)
    mlMin = lMin
End Property
'
'   It is assumed the the Min value is set before the Max
'   value.
'
Public Property Get Max() As Long
    Max = mlMax
End Property
'
'   It is assumed the the Min value is set before the Max
'   value.
'
Public Property Let Max(lMax As Long)
    mlMax = lMax
    UpdateInterval = (lMax - Min) / 100
End Property

Public Property Get Current() As Long
    Current = mlCurrent
End Property

Public Property Let Current(lCurrent As Long)
    mlCurrent = lCurrent
    Refresh
End Property

Public Property Get BarColor() As Long
    BarColor = mlBarColor
End Property

Public Property Let BarColor(lBarColor As Long)
    mlBarColor = lBarColor
End Property

Public Property Get UpdateInterval() As Long
    UpdateInterval = mlUpdateInterval
End Property

Public Property Let UpdateInterval(lUpdateInterval As Long)
    mlUpdateInterval = lUpdateInterval
    If lUpdateInterval = 0 Then
        mlUpdateInterval = 1
    End If
End Property

Public Sub Refresh()
    If Current Mod UpdateInterval = 0 Then
        If (Max - Min) = 0 Then
            Exit Sub
        End If
        GaugeControl.Line (0, 0)-((Current / (Max - Min)) * GaugeControl.Width, _
                                  GaugeControl.Height), BarColor, BF
        GaugeControl.Refresh        ' Force control to update
    End If
End Sub

Public Sub QuickStart(ctl As Control, lMin As Long, lMax As Long)
    Set GaugeControl = ctl
    Min = lMin
    Max = lMax
End Sub

Summary

That concludes this issue of COTW. We hope you find the source code useful in your development.

The below describes the ways you can supply us some feedback about COTW. We would like to see our members help mold COTW into the best Visual Basic source code resource available. But to do that we need your feedback about what you like and what you do not like about COTW.

How to tell us what you think

If you have any suggestions for topics you would like to see covered or questions about this issue, please email them to info@codeoftheweek.com or use online feedback form at http://www.codeoftheweek.com/feedback.html.

If you have any source code you would like to submit for possible inclusion in COTW, please fill out our online submission form at http://www.codeoftheweek.com/submission.html.

Contact Information

C&D Programming Corp.
PO Box 20128
Floral Park, NY 11002-0128
Phone or Fax: (212) 504-7945
Email: info@codeoftheweek.com
Web: http://www.codeoftheweek.com

About Code of the Week and How to get your own subscription

If you have received this issue in a free offer, please check out http://www.codeoftheweek.com to order your own subscription to COTW.

For a limited time you can get 52 issues of COTW for only $19.95. This is a full year of Visual Basic source code and information to help with all your development. So don't wait, subscribe now!