Export (0) Print
Expand All

ContentElement.AddHandler Method (RoutedEvent, Delegate)

Adds a routed event handler for a specified routed event, adding the handler to the handler collection on the current element.

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

public void AddHandler(
	RoutedEvent routedEvent,
	Delegate handler
)

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.

Implements

IInputElement.AddHandler(RoutedEvent, Delegate)

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.

You typically use this method to provide the implementation of the "add" accessor for the Microsoft .NET event access pattern of a custom routed event.

For your custom event to support event routing, you need to register a RoutedEvent using the RegisterRoutedEvent method. This example demonstrates the basics of creating a custom routed event.

As shown in the following example, you first register a RoutedEvent using the RegisterRoutedEvent method. By convention, the RoutedEvent static field name should end with the suffix Event. In this example, the name of the event is Tap and the routing strategy of the event is Bubble. After the registration call, you can provide add-and-remove common language runtime (CLR) event accessors for the event.

Note that even though the event is raised through the OnTap virtual method in this particular example, how you raise your event or how your event responds to changes depends on your needs.

Note also that this example basically implements an entire subclass of Button; that subclass is built as a separate assembly and then instantiated as a custom class on a separate Extensible Application Markup Language (XAML) page. This is to illustrate the concept that subclassed controls can be inserted into trees composed of other controls, and that in this situation, custom events on these controls have the very same event routing capabilities as any native Windows Presentation Foundation (WPF) element does.

public class MyButtonSimple: Button
{
    // Create a custom routed event by first registering a RoutedEventID 
    // This event uses the bubbling routing strategy 
    public static readonly RoutedEvent TapEvent = EventManager.RegisterRoutedEvent(
        "Tap", RoutingStrategy.Bubble, typeof(RoutedEventHandler), typeof(MyButtonSimple));

    // Provide CLR accessors for the event 
    public event RoutedEventHandler Tap
    {
            add { AddHandler(TapEvent, value); } 
            remove { RemoveHandler(TapEvent, value); }
    }

    // This method raises the Tap event 
    void RaiseTapEvent()
    {
            RoutedEventArgs newEventArgs = new RoutedEventArgs(MyButtonSimple.TapEvent);
            RaiseEvent(newEventArgs);
    }
    // For demonstration purposes we raise the event when the MyButtonSimple is clicked 
    protected override void OnClick()
    {
        RaiseTapEvent();
    }

}
<Window  
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:custom="clr-namespace:SDKSample;assembly=SDKSampleLibrary"
    x:Class="SDKSample.RoutedEventCustomApp"

    >
    <Window.Resources>
      <Style TargetType="{x:Type custom:MyButtonSimple}">
        <Setter Property="Height" Value="20"/>
        <Setter Property="Width" Value="250"/>
        <Setter Property="HorizontalAlignment" Value="Left"/>
        <Setter Property="Background" Value="#808080"/>
      </Style>
    </Window.Resources>
    <StackPanel Background="LightGray">
	    <custom:MyButtonSimple Name="mybtnsimple" Tap="TapHandler">Click to see Tap custom event work</custom:MyButtonSimple>
    </StackPanel>
</Window>

Tunneling events are created the same way, but with RoutingStrategy set to Tunnel in the registration call. By convention, tunneling events in WPF are prefixed with the word "Preview".

To see an example of how bubbling events work, see How to: Handle a Routed Event.

.NET Framework

Supported in: 4.6, 4.5, 4, 3.5, 3.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Show:
© 2014 Microsoft