Article
11/17/2011

Hit Testing and Input Events

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

Hit testing is the mechanism by which the Silverlight plug-in and its input subsystem process input (such as mouse clicks) coming from a host (either a Web browser host or an out-of-browser window). This topic describes hit testing, APIs or conditions that affect hit testing, and the implications of hit testing on input events.

Hit Testing and the Host

The Silverlight plug-in can be hosted in a browser. It is the browser host that first processes input generated from input devices and hardware (mouse, keyboard, ink and tablet devices, multitouch). The browser uses the platform-specific input API. The browser host then forwards the input to Silverlight by using the plug-in API that is used by that browser. At this level, there is no concept of a source for the input event other than the overall Silverlight content area. For Silverlight's own input events, the input is mapped to a screen device coordinate system and mouse pointer coordinates, or interpreted as keyboard input. The input"hit" is thus identified as coming from a particular UIElement derived class in the visual tree within the Silverlight content area.

The input subsystem and the hit testing mechanism determine which UIElement in the UI layout and in the visual tree should be noted as the source of the Silverlight input event. That source is transmitted in event data, and determination of the event source also affects other behavior, such as visual state in control templates.

For an application hosted in a browser, you can also process input through the HTML DOM. This is most useful for input that is coming from an HTML element source other than within the Silverlight content area. HTML DOM processing of input also involves a process that resembles hit testing, which uses DOM-level focus value and mouse pointer position to determine where events should be raised. For more information, see HTML Bridge: Interaction Between HTML and Managed Code.

For an out-of-browser application, or if Silverlight is incorporated into an alternative hosting framework, the process is similar. The difference is that the input is interpreted within the window, or processed by input API that is part of the hosting framework application, which possibly has an HWND that represents the host. There is no browser host involved. For more information, see Out-of-Browser Support or Alternative Hosting.

Hit Testing and APIs

There are various APIs exposed on UIElement and derived classes that can affect hit testing. The following is a list of conditions that affect hit testing for typical UI classes.

Setting a Visibility state to Visibility.Collapsed disables hit testing. More obviously, it causes the UIElement to request a zero-size slot whenever the layout system processes it. Therefore, there is no physical point on the display where a mouse could be over, or where keyboard focus could be held. If you set Visibility state to Visibility.Collapsed on an element that had mouse capture, it is released. If you set Visibility state to Visibility.Collapsed on an element that had keyboard focus, focus goes to the next element in the focus traversal order (typically this uses the tab sequence).
You can explicitly set the IsHitTestVisible property to false to disable hit testing even if a UIElement is not visibly transparent.
Although UIElement does not define it, many derived classes implement a Background property (for example Control.Background, Border.Background) or a Fill property (for example Shape.Fill, Glyphs.Fill). These properties use a Brush value. If the Brush is null, the rendering behavior for that area is transparent. An additional behavior is that the area where the brush is applied is not hit testable. (If you want a transparent area that is hit testable, use a Transparent value for a SolidColorBrush.)
TextBlock does hit testing based on its layout slot within a container. TextBlock does not have a Background property where you can set a null brush. You can disable hit testing for a TextBlock with IsHitTestVisible.
Glyphs is hit testable over its layout slot as a rectangle of its Height and Width. The text area (the area painted by Glyphs.Fill) is considered part of that rectangle.
Image and MediaElement are hit testable over their image/media display areas, basically their Height and Width. Transparent / full alpha pixels in the image file are still hit testable, which is analogous to the behavior for Transparent value for a SolidColorBrush.
You can disable controls, which also disables hit testing and thus input events. For more information, see Control.IsEnabled.
Most Panel classes are deliberately implemented to not be hit testable, so that the items within the Panel report input rather than the container. The panel or container can often still handle the event by taking advantage of event routing.
InkPresenter has a dedicated HitTest method. This method is used to determine whether a provided region (point or rectangle) intersects with the existing Strokes collection held by the InkPresenter. Therefore HitTest is only useful for inking scenarios.
Within a visual tree subset, you can potentially pre-determine hit testing results without mouse input by using the APIs in VisualTreeHelper, specifically VisualTreeHelper.FindElementsInHostCoordinates.
Applied transforms can change the coordinate system. You can often resolve these differences by calling RenderTransform.

Changing element layout is also relevant to hit testing. Layout might determine which specific element is the reported input source if the user clicks an area of UI where several elements share a layout space. However, changes to layout typically change the visual appearance as well as the hit-test characteristics, and this might not be what you want. There are various techniques for changing element layout that are not discussed in this topic; for more information, see Layout System.