Instrução RaiseEvent

  • Artigo

Dispara um evento declarado no nível do módulo dentro de uma classe, formulário ou documento.

Sintaxe

RaiseEvent eventname[( argumentlist )]

Partes

eventname
Obrigatórios. O nome do evento a ser disparado.

argumentlist
Opcional. Lista delimitada por vírgulas de variáveis, matrizes ou expressões. O argumento argumentlist deve ser delimitado por parênteses. Se não houver nenhum argumento, os parênteses serão omitidos.

Comentários

O eventname necessário é o nome de um evento declarado dentro do módulo. Ele segue as convenções de nomenclatura de variáveis do Visual Basic.

Se o evento não tiver sido declarado dentro do módulo no qual ele é acionado, ocorrerá um erro. O fragmento de código a seguir ilustra uma declaração de evento e um procedimento no qual o evento é acionado.

' Declare an event at module level.
Event LogonCompleted(ByVal UserName As String)

Sub Logon(ByVal UserName As String)
    ' Raise the event.
    RaiseEvent LogonCompleted(UserName)
End Sub

Você não pode usar RaiseEvent para acionar eventos que não são declarados explicitamente no módulo. Por exemplo, todos os formulários herdam um evento Click do System.Windows.Forms.Form; ele não pode ser acionado usando RaiseEvent em uma forma derivada. Se você declarar um evento Click no módulo de formulário, ele sombreará o próprio evento Click do formulário. Você ainda pode invocar o evento Click do formulário chamando o método OnClick.

Por padrão, um evento definido no Visual Basic aciona seus manipuladores de eventos na ordem em que as conexões são estabelecidas. Como os eventos podem ter parâmetros ByRef, um processo que se conecta tardiamente pode receber parâmetros que foram alterados por um manipulador de eventos anterior. Após a execução dos manipuladores de eventos, o controle retorna para a sub-rotina que acionou o evento.

Observação

Eventos não compartilhados não devem ser acionados dentro do construtor da classe em que são declarados. Embora esses eventos não causem erros em tempo de execução, eles podem não ser capturados por manipuladores de eventos associados. Use o modificador Shared para criar um evento compartilhado se precisar acionar um evento de um construtor.

Observação

Você pode alterar o comportamento padrão dos eventos definindo um evento personalizado. Para eventos personalizados, a instrução RaiseEvent invoca o acessador do evento RaiseEvent. Para obter mais informações sobre eventos personalizados, confira Instrução de evento.

Exemplo 1

O exemplo a seguir usa eventos para contagem regressiva de segundos de 10 para 0. O código ilustra vários métodos, propriedades e instruções relacionados a evento, incluindo a instrução RaiseEvent.

A classe que aciona um evento é a origem do evento, e os métodos que processam o evento são os manipuladores de eventos. Uma origem do evento pode ter vários manipuladores para os eventos gerados. Quando a classe aciona o evento, esse evento é gerado em cada classe que optou por tratar eventos para essa instância do objeto.

O exemplo também usa um formulário (Form1) com um botão (Button1) e uma caixa de texto (TextBox1). Quando você clica no botão, a primeira caixa de texto exibe uma contagem regressiva de 10 para 0 segundos. Quando o tempo integral (10 segundos) tiver decorrido, a primeira caixa de texto exibirá "Concluído".

O código para Form1 especifica os estados iniciais e terminais do formulário. Ele também contém o código executado quando os eventos são acionados.

Para usar este exemplo, abra um novo projeto de Aplicativo do Windows, adicione um botão nomeado Button1 e uma caixa de texto nomeada TextBox1 ao formulário principal, chamado Form1. Em seguida, clique com o botão direito do mouse no formulário e clique em Exibir Código para abrir o editor de código.

Adicione uma variável WithEvents à seção declarações da classe Form1.

Private WithEvents mText As TimerState

Exemplo 2

Adicione o código a seguir ao código de Form1. Substitua todos os procedimentos duplicados que possam existir, como Form_Load ou Button_Click.

Private Sub Form1_Load() Handles MyBase.Load
    Button1.Text = "Start"
    mText = New TimerState
End Sub
Private Sub Button1_Click() Handles Button1.Click
    mText.StartCountdown(10.0, 0.1)
End Sub

Private Sub mText_ChangeText() Handles mText.Finished
    TextBox1.Text = "Done"
End Sub

Private Sub mText_UpdateTime(ByVal Countdown As Double
  ) Handles mText.UpdateTime

    TextBox1.Text = Format(Countdown, "##0.0")
    ' Use DoEvents to allow the display to refresh.
    My.Application.DoEvents()
End Sub

Class TimerState
    Public Event UpdateTime(ByVal Countdown As Double)
    Public Event Finished()
    Public Sub StartCountdown(ByVal Duration As Double,
                              ByVal Increment As Double)
        Dim Start As Double = DateAndTime.Timer
        Dim ElapsedTime As Double = 0

        Dim SoFar As Double = 0
        Do While ElapsedTime < Duration
            If ElapsedTime > SoFar + Increment Then
                SoFar += Increment
                RaiseEvent UpdateTime(Duration - SoFar)
            End If
            ElapsedTime = DateAndTime.Timer - Start
        Loop
        RaiseEvent Finished()
    End Sub
End Class

Pressione F5 para executar o exemplo anterior e clique no botão de rótulo Iniciar. A primeira caixa de texto começa a contar os segundos. Quando o tempo integral (10 segundos) tiver decorrido, a primeira caixa de texto exibirá "Concluído".

Observação

O método My.Application.DoEvents não processa eventos exatamente da mesma forma que o formulário o faz. Para habilitar o formulário para manipular os eventos diretamente, você pode usar o multithreading. Para obter mais informações, confira Threading gerenciado.

Confira também