Mouse Wheel Input
Microsoft Silverlight will reach end of support after October 2021. Learn more.
Silverlight provides support for mouse wheel input through an event of the UIElement class. The mouse wheel input for Silverlight is modeled on the mouse wheel input for WPF. Handling the mouse wheel input events has some platform dependencies. This topic describes the basics of handling mouse wheel input and how your application can account for platform dependency issues with mouse wheel input.
This topic contains the following sections.
- MouseWheel Event API
- When to Use MouseWheel API
- Handled in the MouseWheel API
- Delta in the MouseWheel API
- Platform Dependencies
- Related Topics
MouseWheel Event API
Mouse wheel input raises its own input event, MouseWheel, which is defined on UIElement along with the other mouse-specific events (such as MouseMove). The event has a delegate (MouseWheelEventHandler) to account for event data (MouseWheelEventArgs) that is specific to mouse wheel input. MouseWheelEventArgs has a Delta property that reports the amount that the mouse wheel has changed, either from a starting state or since the last MouseWheel event.
When to Use MouseWheel API
Starting in Silverlight 3, there are typically two ways to process mouse wheel input. When Silverlight is hosted in a browser, mouse wheel input can be processed by using HTML DOM events in the browser host. Alternatively, mouse wheel input can be processed by the MouseWheel event in managed code. You can still provide the DOM event handling from within managed code by calling the AttachEvent method for OnMouseWheel on the relevant DOM element and providing a handler.
There are two cases where the HTML DOM mouse wheel events are not available:
Application is displayed in full-screen mode.
Application is deployed outside the browser, such that there is no hosting HTML page to handle DOM events.
The managed MouseWheel event supports these two cases. Therefore, you should use the MouseWheel event rather than DOM events whenever possible. This is particularly true if you implement or use controls with specific mouse wheel event handling. The MouseWheel event routes through other managed objects in Silverlight UI, is cancelable with the Handled property, and integrates with the overall control templates and visual states model.
However, because of platform dependencies, you may still want to use HTML DOM handling of OnMouseWheel.This is described more in "Platform Dependencies" later in this topic.
Handled in the MouseWheel API
The event data for MouseWheel (MouseWheelEventArgs) exposes a Handled property. One purpose of Handled is common to several of the Silverlight routed events. By setting Handled to true, you prevent general handlers from acting on the event and ending the route. (An exception to this statement is that you can register handlers that can act even for already-handled routed events if required. For more information, see UIElement.AddHandler.)
In addition to ending the managed event's route, setting Handled to true also marks the related HTML DOM event as handled. On environments other than Windows and Internet Explorer in combination, Handled has no effect on the HTML DOM event.
Certain controls (for example, Calendar) provide handling for mouse wheel events at the control level. Such controls provide an override of the OnMouseWheel method. A typical control OnMouseWheel override will perform some related input action that the mouse wheel action enables, and sets Handled to true in event data. The result is that instance handlers specifically for MouseWheel are not generally invoked. In general, you should consider this to be the control's intended design. However, if you have a scenario where you still want to handle MouseWheel from a control that overrides OnMouseWheel, you can attach handlers with UIElement.AddHandler instead of XAML attributes or language keywords/operators for event handling, such as the addition assignment operator (+=) in C#.
Delta in the MouseWheel API
Delta is the event data property that is unique to a mouse wheel event. Delta reports the number of detent stops that the mouse wheel has rotated, multiplied by a factor. The factor on Microsoft Windows platforms is 120, which is consistent with WPF and predecessor input APIs. Typically you will be interested in whether Delta is positive or negative; the factor is often unimportant. Positive Delta indicates that the mouse wheel has rotated away from the user. Negative Delta indicates that the mouse wheel has rotated towards the user.
Platform Dependencies
The MouseWheel event is only raised and able to be handled for supported platforms. For example, on Microsoft Windows platforms, MouseWheel is supported in Internet Explorer and Firefox. MouseWheel is supported for out-of-browser applications. However, a browser hosted Silverlight application using a Macintosh operating system does not raise the event. The following table lists various platforms and whether MouseWheel is supported.
Platform |
MouseWheel Support |
|---|---|
Windows, Internet Explorer |
Yes |
Windows, Firefox |
Yes |
Windows, Firefox, windowless |
No |
Windows, out-of-browser |
Yes |
Macintosh, browser-hosted |
No |
Macintosh, out-of-browser |
Yes (see second note below) |
.gif "Note") Note: |
|---|
Firefox (or other browsers using NPAPI) do not raise the event if the application is running in windowless mode. |
| Note: |
|---|
Support for mouse wheel event handling for Macintosh out-of-browser was specifically added in a Silverlight 4 service release. For more information, see KB Article 2164913. |
To process mouse wheel information for clients or situations that do not raise MouseWheel, you must use the HTML DOM event handling for mouseWheel events (onMouseWheel attribute specifies a handler) that are available to HTML client scripting and HTML Bridge.
See Also