Instruções passo a passo: declarando e acionando eventos (Visual Basic)Walkthrough: Declaring and Raising Events (Visual Basic)

Este tutorial demonstra como declarar e gerar eventos para uma classe chamada Widget.This walkthrough demonstrates how to declare and raise events for a class named Widget. Depois de concluir as etapas, talvez você queira ler o tópico complementar, Walkthrough: Manipulando eventos, que mostra como usar eventos de Widget objetos para fornecer informações de status em um aplicativo.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.

A classe WidgetThe Widget Class

Suponha que, por enquanto, você tenha uma classe de Widget.Assume for the moment that you have a Widget class. Sua classe de Widget tem um método que pode levar muito tempo para ser executado e você deseja que seu aplicativo seja capaz de colocar algum tipo de indicador de conclusão.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.

É claro que você pode fazer com que o objeto Widget mostre uma caixa de diálogo de porcentagem concluída, mas, em seguida, você estaria preso a essa caixa de diálogo em todos os projetos nos quais usou a classe Widget.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. Um bom princípio do design de objeto é permitir que o aplicativo que usa um objeto manipule a interface do usuário — a menos que a finalidade do objeto seja gerenciar um formulário ou caixa de diálogo.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.

A finalidade do Widget é executar outras tarefas, portanto, é melhor adicionar um evento de PercentDone e permitir que o procedimento que chama os métodos de Widgetmanipule esse evento e exiba as atualizações de status.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. O evento PercentDone também pode fornecer um mecanismo para cancelar a tarefa.The PercentDone event can also provide a mechanism for canceling the task.

Para criar o exemplo de código para este tópicoTo build the code example for this topic

  1. Abra um novo projeto de aplicativo do Windows Visual Basic e crie um formulário chamado Form1.Open a new Visual Basic Windows Application project and create a form named Form1.

  2. Adicione dois botões e um rótulo a Form1.Add two buttons and a label to Form1.

  3. Nomeie os objetos como mostrado na tabela a seguir.Name the objects as shown in the following table.

    ObjectObject PropriedadeProperty ConfiguraçãoSetting
    Button1 Text Tarefa de inícioStart Task
    Button2 Text CancelCancel
    Label (Name), Text(Name), Text lblPercentDone, 0lblPercentDone, 0
  4. No menu projeto , escolha Adicionar classe para adicionar uma classe chamada Widget.vb ao projeto.On the Project menu, choose Add Class to add a class named Widget.vb to the project.

Para declarar um evento para a classe WidgetTo declare an event for the Widget class

  • Use a palavra-chave Event para declarar um evento na classe Widget.Use the Event keyword to declare an event in the Widget class. Observe que um evento pode ter argumentos ByVal e ByRef, como o evento de PercentDone de Widgetdemonstra:Note that an event can have ByVal and ByRef arguments, as Widget's PercentDone event demonstrates:

    Public Event PercentDone(ByVal Percent As Single, 
                             ByRef Cancel As Boolean)
    

Quando o objeto de chamada recebe um evento PercentDone, o argumento Percent contém a porcentagem da tarefa concluída.When the calling object receives a PercentDone event, the Percent argument contains the percentage of the task that is complete. O argumento Cancel pode ser definido como True para cancelar o método que gerou o evento.The Cancel argument can be set to True to cancel the method that raised the event.

Observação

Você pode declarar argumentos de evento da mesma forma como faz argumentos de procedimentos, com as seguintes exceções: os eventos não podem ter argumentos Optional ou ParamArray, e os eventos não têm valores de retorno.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.

O evento PercentDone é gerado pelo método LongTask da classe Widget.The PercentDone event is raised by the LongTask method of the Widget class. LongTask usa dois argumentos: o período de tempo que o método pretende a fazer funcionar e o intervalo de tempo mínimo antes de LongTask pausa para gerar o evento de PercentDone.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 PercentDone event.

Para gerar o evento PercentDoneTo raise the PercentDone event

  1. Para simplificar o acesso à propriedade Timer usada por essa classe, adicione uma instrução Imports à parte superior da seção de declarações do seu módulo de classe, acima da instrução Class Widget.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. Adicione o seguinte código à classe Widget: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
    

Quando o aplicativo chama o método LongTask, a classe Widget gera o evento PercentDone a cada MinimumInterval segundos.When your application calls the LongTask method, the Widget class raises the PercentDone event every MinimumInterval seconds. Quando o evento retorna, LongTask verifica se o argumento Cancel foi definido como True.When the event returns, LongTask checks to see if the Cancel argument was set to True.

Alguns isenções de responsabilidade são necessários aqui.A few disclaimers are necessary here. Para simplificar, o procedimento LongTask pressupõe que você saiba com antecedência quanto tempo a tarefa levará.For simplicity, the LongTask procedure assumes you know in advance how long the task will take. Esse é quase nunca o caso.This is almost never the case. Dividir tarefas em partes de tamanho par pode ser difícil e, muitas vezes, o que mais importa para os usuários é simplesmente a quantidade de tempo que o passa antes de receber uma indicação de que algo está acontecendo.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.

Você pode ter extratado outra falha neste exemplo.You may have spotted another flaw in this sample. A propriedade Timer retorna o número de segundos que passaram desde a meia-noite; Portanto, o aplicativo ficará preso se ele for iniciado logo antes da meia-noite.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. Uma abordagem mais cuidadosa para medir o tempo teria condições de limite como essa em consideração ou evitá-las completamente, usando propriedades como Now.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.

Agora que a classe Widget pode gerar eventos, você pode ir para o próximo passo a passos.Now that the Widget class can raise events, you can move to the next walkthrough. Walkthrough: manipular eventos demonstra como usar WithEvents para associar um manipulador de eventos ao evento PercentDone.Walkthrough: Handling Events demonstrates how to use WithEvents to associate an event handler with the PercentDone event.

Consulte tambémSee also