UIElement.AddHandler(RoutedEvent, Object, Boolean) Method

Reference

Definition

Namespace:: Windows.UI.Xaml

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Edit

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.

public:
 virtual void AddHandler(RoutedEvent ^ routedEvent, Platform::Object ^ handler, bool handledEventsToo) = AddHandler;

void AddHandler(RoutedEvent const& routedEvent, IInspectable const& handler, bool const& handledEventsToo);

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

function addHandler(routedEvent, handler, handledEventsToo)

Public Sub AddHandler (routedEvent As RoutedEvent, handler As Object, handledEventsToo As Boolean)

Parameters

routedEvent: RoutedEvent

An identifier for the routed event to be handled.

handler: Object
Platform::Object

IInspectable

A reference to the handler implementation.

handledEventsToo: Boolean
bool

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.

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.

void MyControl::MyPointerPressedHandler(
    winrt::Windows::Foundation::IInspectable const &sender,
    winrt::Windows::UI::Xaml::Input::PointerRoutedEventArgs const& e) {
  // implementation..
}

this->AddHandler(
    winrt::Windows::UI::Xaml::UIElement::PointerPressedEvent(),
    winrt::box_value(winrt::Windows::UI::Xaml::Input::PointerEventHandler(this, &MyControl::MyPointerPressedHandler)),
    true);

// Or passing the handler as a lambda, instead of a member function:
this->AddHandler(
    winrt::Windows::UI::Xaml::UIElement::PointerPressedEvent(),
    winrt::box_value(winrt::Windows::UI::Xaml::Input::PointerEventHandler(
      [=](auto &&, winrt::Windows::UI::Xaml::Input::PointerRoutedEventArgs const &args) {
      // ...
    })),
    true);

void MainPage::pageRoot_Tapped(Platform::Object^ sender, Windows::UI::Xaml::Input::TappedRoutedEventArgs^ e)
{
     //implementation
}
void MainPage::pageRoot_Loaded(Platform::Object^ sender, Windows::UI::Xaml::RoutedEventArgs^ e)
{
     this->AddHandler(UIElement::TappedEvent, ref new TappedEventHandler(this, &MainPage::pageRoot_Tapped), true);
}

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);
}

Private Sub Page_Tapped(sender As Object, e As TappedRoutedEventArgs)
    ' implementation
End Sub
Private Sub Page_Loaded_1(sender As Object, e As RoutedEventArgs)
    Me.AddHandler(UIElement.TappedEvent, New TappedEventHandler(AddressOf Page_Tapped), True)
End Sub

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 OnEvent 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.

Applies to

Share via