Article
11/18/2011

UIElement.AddHandler Method

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Adds a routed event handler for a specified routed event, adding the handler to the handler collection on the current element. Specify handledEventsToo as true to have the provided handler be invoked for routed event that had already been marked as handled by another element along the event route.

Namespace: System.Windows
Assembly: System.Windows (in System.Windows.dll)

Syntax

'Declaration
Public Sub AddHandler ( _
    routedEvent As RoutedEvent, _
    handler As Delegate, _
    handledEventsToo As Boolean _
)

public void AddHandler(
    RoutedEvent routedEvent,
    Delegate handler,
    bool handledEventsToo
)

Parameters

routedEvent
Type: System.Windows.RoutedEvent
An identifier for the routed event to be handled.

handler
Type: System.Delegate
A reference to the handler implementation.

handledEventsToo
Type: System.Boolean
true to register the handler such that it is invoked even when the routed event is marked handled in its event data; false to register the handler with the default condition that it will not be invoked if the routed event is already marked handled. The default is false. Do not routinely ask to rehandle a routed event. For more information, see Remarks.

Exceptions

Exception	Condition
ArgumentNullException	routedEvent or handler is nulla null reference (Nothing in Visual Basic).
ArgumentException	routedEvent does not represent a supported routed event. -or- handler does not implement a supported delegate.
NotImplementedException	Attempted to add handler for an event not supported by the current platform variation.

ArgumentNullException

routedEvent or handler is nulla null reference (Nothing in Visual Basic).

ArgumentException

routedEvent does not represent a supported routed event.

-or-

handler does not implement a supported delegate.

NotImplementedException

Attempted to add handler for an event not supported by the current platform variation.

Remarks

Processing low-level input events in a practical way is a complex task. Many controls implement behavior where a certain event is marked as handled, and is replaced by another more intuitive event. Generally, a control will only mark a Silverlight routed event as handled if there is some design intention for doing so. However, in certain scenarios, those design intentions might not be what your particular handling of the input event requires. It is for these scenarios that registering handlers with handledEventsToo as true is appropriate. But you should not do this routinely. Invoking handlers in response to all events even if handled will complicate your own application event processing logic. You may see a decrease in performance if the handler logic is substantial. You should only attach handlers to already-handled events in situations where you have already discovered during the development process that certain controls are handling events that you want to handle with application and user code logic.

Another technique for avoiding the class handling behavior of certain event-control combinations is to subclass that control and override its On* class methods, which are the specific code paths by which that control marks an event as handled. However, this too can be complex. You may have to reproduce a given control's handling implementation without calling base, because base would mark the event as handled.

In order to use AddHandler, the routed event must expose a public static field that is the event identifier, which is required for the routedEvent parameter. This is only true for a limited set of events in the Silverlight core classes:

Do not use FrameworkElement.Loaded and AddHandler; FrameworkElement.Loaded is not a true routed event in the Silverlight implementation. MouseMove cannot be used with AddHandler because there is no Handled in its event data. FrameworkElement.BindingValidationError cannot be used with AddHandler because there is no event identifier, and also because there is no control handling of the event.

You can add the same handler for the same event multiple times without raising an exception. However, the handler is actually invoked multiple times when the event is handled. Therefore, consider how this behavior might have side effects that should be accounted for in your handler implementation.

Version Notes

Silverlight 3: Not all events noted in Remarks above are available in Silverlight 3. Silverlight 3 does not support right-click events, manipulation/touch events, drag/drop events, or IME support events. Attempting to add handlers for these in Silverlight 3 with AddHandler throws an ArgumentException.

Examples

The following example shows a handler implementation for a routed event (KeyDown) and a Loaded event handler that attaches that KeyDown handler to the root element of a XAML-defined page. Rather than using the += syntax, AddHandler is called, with handledEventsToo true. This enables any usage of the CapsLock key to be reported to the root element via event routing, even in cases where a control such as a TextBox has control-specific handling of KeyDown / an OnKeyDown implementation.

private void LayoutRoot_KeyDown(object sender, KeyEventArgs e)
{
    if(e.Key == Key.CapsLock) {
        HandleSpecialKey();
    }
}
private void Load_Main(object sender, RoutedEventArgs e)
{
    UIElement target = sender as UIElement;
    target.AddHandler(UIElement.KeyDownEvent, new KeyEventHandler(LayoutRoot_KeyDown), true);
}

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

Share via