EN
Данное содержимое не доступно на вашем языке, используйте версию на английском языке.

UIElement.AddHandler Method

July 28, 2014

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)

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.

ExceptionCondition
ArgumentNullException

routedEvent or handler is null.

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.

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 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 these core classes:

Do not use FrameworkElement.Loaded and AddHandler; FrameworkElement.Loaded is not a true routed event in the Windows Phone 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.

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.

    // Assumes the UI has a TextBox that can pop-up the keyboard defined as a child of LayoutRoot, and a 
    // TextBlock named textBlock1 that can display text onscreen.
    public partial class MainPage : PhoneApplicationPage
    {
        // Constructor
        public MainPage()
        {
            InitializeComponent();
            LayoutRoot.Loaded +=new RoutedEventHandler(Load_Main);
        }

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

        private void LayoutRoot_KeyDown(object sender, KeyEventArgs e)
        {
            if (e.PlatformKeyCode == 233)
            {
                textBlock1.Text = "Caps Lock!";
            }
        }
    }


Windows Phone OS

Supported in: 8.1, 8.0, 7.1, 7.0

Windows Phone

Показ:
© 2014 Microsoft