Export (0) Print
Expand All

Walkthrough: Declaring and Raising Events

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 the Widget's methods handle that event and display status updates. The PercentDone event also can provide a mechanism for canceling the task.

To build the code example for this topic

  1. Open a new Visual Basic .NET Windows Application project, and create a form named Form1.
  2. Add two buttons and a label to Form1.
  3. On the Project menu, select Add Class to add a class to the project.
  4. Name the objects as shown in the following table.
    Object Property Setting
    Class Name Widget
    Button1 Text Start Task
    Button2 Text Cancel
    Label Name, Text lblPercentDone, "0"

To declare an event for the Widget class

  • In the Declarations section of your class module, declare the event using the Event keyword. Note that an event can have ByVal and ByRef arguments, as the Widget's PercentDone event demonstrates:
    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.

Note   You can declare event arguments just as you do arguments of procedures, with the following exceptions: Events cannot have Optional or ParamArray arguments, and events do not have return values.

The PercentDone event is raised by the LongTask method of the Widget class. LongTask takes two arguments: the length of time the method will pretend to be doing work, and the minimum time interval before LongTask pauses to raise the PercentDone event.

To raise the PercentDone event

  1. To simplify access to the Timer property used by this class, add an Imports statement to the top of the declarations section of your class module, above the Class Widget statement.
    Imports Microsoft.VisualBasic.DateAndTime
    
  2. Add the following code to the Widget class:
    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
    

The Widget class raises the PercentDone event every MinimumInterval seconds when your application calls the LongTask method. When the event returns, LongTask checks to see if the Cancel argument was set to True.

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 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.

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 PercentDone event.

See Also

Walkthrough: Handling Events | Events and Event Handlers | Delegates and the AddressOf Operator | AddHandler and RemoveHandler | Writing Event Handlers | Timer Property | WithEvents | Now Property | Event Statement | ByVal | ByRef | Imports Statement

Show:
© 2014 Microsoft