Keyword # AddHandler --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ## Description Directs the handling of an event to a delegate method. ## Usage ``` xojo AddHandler eventName, delegateMethod ``` | Part | Description | |----------------|---------------------------------------------------------------| | eventName | The name of the event that you are handling. | | delegateMethod | The name of the method that will be used to handle the event. | ## Notes Generally you will create a subclass to expose event handlers for you to implement. AddHandler provides a way for you to instantiate a class in code and still have access to its event handlers. The delegateMethod method declaration must consist of: - A reference to the object being handled. This is the sender object and it must be the first parameter in the delegate and must be the correct type. You can get this reference using AddressOf or WeakAddressOf. - The same parameters of the event you are handling should follow next in the same order with the same types. The parameter names can be changed. - If the event you are handling returns a value, then the delegate method must also return the same value type. A handler can handle any number of events, but an event can only have one event handler. To change the event handler for an event after you have added one, you must first remove the existing handler with RemoveHandler. You can then add the new handler. Always remove any handlers added with AddHandler when you are finished with them using `RemoveHandler`. Balance AddHandler with `RemoveHandler` in the appropriate place, e.g., if AddHandler is used when a `Window` opens, use `RemoveHandler` when the `Window` closes.

Note

AddHandler is a keyword, not a function so do not surround the parameters with parentheses.

Warning

A RuntimeException will be raised if you implement an event handler that is already implemented.

## Sample code This example show you how you can handle the Timer.Action event in your own method so that you do not have to create a Timer subclass. Start by adding a property for the Timer to the layout: ``` xojo MyTimer As Timer ``` Now add a ProgressBar to the layout. The Timer will update the ProgressBar. In the Opening event handler of the layout, instantiate the Timer and indicate that its *Action* event handler should be handled by a method (called TimerAction -- you'll create the method a moment): ``` xojo MyTimer = New Timer MyTimer.Period = 1000 MyTimer.RunMode = Timer.RunModes.Multiple AddHandler MyTimer.Action, AddressOf TimerAction ``` Now add the TimerAction method to the layout: ``` xojo Sub TimerAction(sender As Timer) ' This code works on Desktop and uses ProgressBar. If ProgressBar1.Value < ProgressBar1.MaximumValue Then ProgressBar1.Value = ProgressBar1.Value + 1 Else ' Stop Timer and Remove the handler sender.RunMode = Timer.RunModes.Off RemoveHandler MyTimer.Action, AddressOf TimerAction End If End Sub ``` Now run the project and watch the Timer updated the ProgressBar. ## Mobile Projects This example lets you handle the Timer.Run event without creating a Timer subclass. Start by adding a property to the layout: ``` xojo MyTimer As Timer ``` Next, add an MobileProgressBar to the layout. The Timer will update the ProgressBar. In the Opening event handler of the layout, instantiate the Timer and indicate that its *Run* event handler should be handled by a method, TimerRun, that you will add to the layout: ``` xojo MyTimer = New Timer MyTimer.Period = 1000 MyTimer.RunMode = Timer.RunModes.Multiple AddHandler MyTimer.Run, AddressOf TimerRun ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Now add the TimerRun method to the layout: ``` xojo Sub TimerRun(sender As Timer) If ProgressBar1.Value < ProgressBar1.MaximumValue Then ProgressBar1.Value = ProgressBar1.Value + 1 Else ' Stop Timer and Remove the handler sender.RunMode = Timer.RunModes.Off RemoveHandler MyTimer.Run, AddressOf TimerRun End If End Sub ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Remember that the first parameter to TimerRun must be of the type of the original object, in this case a Timer. When you run the project, the ProgressBar is updated once per second. When using AddHandler on a class, it is more productive to use WeakAddressOf to ensure that you do not inadvertently retain references. To do so, use WeakAddressOf in place of AddressOf in the code: ``` xojo MyTimer = New Timer MyTimer.Period = 1000 MyTimer.RunMode = Timer.RunModes.Multiple AddHandler MyTimer.Run, WeakAddressOf TimerRun ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- And here: ``` xojo Sub TimerRun(sender As Timer) If ProgressBar1.Value < ProgressBar1.MaximumValue Then ProgressBar1.Value = ProgressBar1.Value + 1 Else ' Stop Timer and Remove the handler sender.RunMode = Timer.RunModes.Off RemoveHandler MyTimer.Run, WeakAddressOf TimerRun End If End Sub ``` ## Compatibility | | | |-----------------------|-----| | **Project Types** | All | | **Operating Systems** | All |

`RemoveHandler` statement