Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

UIElement.AddHandler method

Applies to Windows and Windows Phone

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 even if the event is handled elsewhere.

Syntax


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

Parameters

routedEvent

Type: RoutedEvent

An identifier for the routed event to be handled.

handler

Type: System.Object [.NET] | Platform::Object [C++]

A reference to the handler implementation.

handledEventsToo

Type: System.Boolean [.NET] | Platform::Boolean [C++]

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, because it interferes with the intended design of the Windows Runtime event system for control compositing.

Remarks

Don't try to use AddHandler as a general substitute for the language-specific syntax you normally use for wiring event handlers; it won't work, because not all events have an identifier you can pass as routedEvent. AddHandler is specifically for routed events, and intended mainly for the particular scenario enabled by passing handledEventsToo as true. For more info, see Events and routed events overview.

Routed event identifiers

The routed event identifier is generally a static property member of UIElement. For example, to add a handler for the KeyUp event, pass KeyUpEvent for this parameter. Only a small number of Windows Runtime events have this identifier; only routed events on UIElement have an identifier API available for this usage. These are generally events that are related to input actions at various levels: pointer level, gesture level, manipulation level. Also, the key input events can be handled this way.

Here is a list of routed events that expose a routed event identifier, and thus can be processed by handlers that are registered by an AddHandler call:

The handler parameter

The handler parameter is an untyped parameter, but you should provide a new delegate that references a handler method that is specific to the desired event. For example, if handling a KeyUp event, pass a new KeyEventHandler instance that references a method that is based on that KeyEventHandler delegate signature. This requires a dereference, and the dereference syntax varies depending on which language you are using. See the examples in this topic.

When to use handledEventsToo

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 mark a routed event as handled only 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 app event-processing logic. You may see a decrease in performance if the handler logic is substantial. You should attach handlers to already-handled events only if you have discovered that certain controls are handling events that you want to handle with app logic.

Another technique for avoiding a control's class-handling behavior is to subclass that control and override its On* methods, which are pre-configured overrides by which the control marks an event as handled. However, this too can be complex. You may have to reproduce a control's handling implementation without calling the base implementation, because the base implementation would mark the event as handled. For more info, see Events and routed events overview.

Examples

This example shows the basic syntax for wiring an event handler with AddHandler and handledEventsToo as true. In this case the event being wired is Tapped. The typical place to wire handlers is either Loaded for a page or OnApplyTemplate for a templated control.


        private void pageRoot_Tapped(object sender, TappedRoutedEventArgs e)
        {
            //implementation
        }
        private void pageRoot_Loaded_1(object sender, RoutedEventArgs e)
        {
            this.AddHandler(UIElement.TappedEvent, new TappedEventHandler(pageRoot_Tapped), true);
        }


Requirements

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Minimum supported phone

Windows Phone 8.1 [Windows Runtime apps only]

Namespace

Windows.UI.Xaml
Windows::UI::Xaml [C++]

Metadata

Windows.winmd

See also

UIElement
RemoveHandler
Events and routed events overview
Quickstart: Touch input

 

 

Show:
© 2014 Microsoft. All rights reserved.