Walkthrough: Declaring and Raising Events (Visual Basic)
This walkthrough demonstrates how to declare and raise events for a class named
Widget. After you complete the steps, you might want to read the companion topic, Walkthrough: Handling Events, which shows how to use events from
Widget objects to provide status information in an application.
The Widget Class
Assume for the moment that you have a
Widget class. Your
Widget class has a method that can take a long time to execute, and you want your application to be able to put up some kind of completion indicator.
Of course, you could make the
Widget object show a percent-complete dialog box, but then you would be stuck with that dialog box in every project in which you used the
Widget class. A good principle of object design is to let the application that uses an object handle the user interface—unless the whole purpose of the object is to manage a form or dialog box.
The purpose of
Widget is to perform other tasks, so it is better to add a
PercentDone event and let the procedure that calls
Widget's methods handle that event and display status updates. The
PercentDone event can also provide a mechanism for canceling the task.
To build the code example for this topic
Open a new Visual Basic Windows Application project and create a form named
Add two buttons and a label to
Name the objects as shown in the following table.
Object Property Setting
On the Project menu, choose Add Class to add a class named
Widget.vbto the project.
To declare an event for the Widget class
Eventkeyword to declare an event in the
Widgetclass. Note that an event can have
Public Event PercentDone(ByVal Percent As Single, ByRef Cancel As Boolean)
When the calling object receives a
PercentDone event, the
Percent argument contains the percentage of the task that is complete. The
Cancel argument can be set to
True to cancel the method that raised the event.
You can declare event arguments just as you do arguments of procedures, with the following exceptions: Events cannot have
ParamArray arguments, and events do not have return values.
PercentDone event is raised by the
LongTask method of the
LongTask takes two arguments: the length of time the method pretends to be doing work, and the minimum time interval before
LongTask pauses to raise the
To raise the PercentDone event
To simplify access to the
Timerproperty used by this class, add an
Importsstatement to the top of the declarations section of your class module, above the
Add the following code to the
Public Sub LongTask(ByVal Duration As Single, ByVal MinimumInterval As Single) Dim Threshold As Single Dim Start As Single Dim blnCancel As Boolean ' The Timer property of the DateAndTime object returns the seconds ' and milliseconds that have passed since midnight. Start = CSng(Timer) Threshold = MinimumInterval Do While CSng(Timer) < (Start + Duration) ' In a real application, some unit of work would ' be done here each time through the loop. If CSng(Timer) > (Start + Threshold) Then RaiseEvent PercentDone( Threshold / Duration, blnCancel) ' Check to see if the operation was canceled. If blnCancel Then Exit Sub Threshold = Threshold + MinimumInterval End If Loop End Sub
When your application calls the
LongTask method, the
Widget class raises the
PercentDone event every
MinimumInterval seconds. When the event returns,
LongTask checks to see if the
Cancel argument was set to
A few disclaimers are necessary here. For simplicity, the
LongTask procedure assumes you know in advance how long the task will take. This is almost never the case. Dividing tasks into chunks of even size can be difficult, and often what matters most to users is simply the amount of time that passes before they get an indication that something is happening.
You may have spotted another flaw in this sample. The
Timer property returns the number of seconds that have passed since midnight; therefore, the application gets stuck if it is started just before midnight. A more careful approach to measuring time would take boundary conditions such as this into consideration, or avoid them altogether, using properties such as
Now that the
Widget class can raise events, you can move to the next walkthrough. Walkthrough: Handling Events demonstrates how to use
WithEvents to associate an event handler with the