Event Handling in Silverlight for Windows Embedded (Compact 7)
3/12/2014
You can make your Microsoft Silverlight for Windows Embedded application respond to user input and changes in the system or application by creating handler methods and hooking them up to events.
To implement and handle events in Silverlight for Windows Embedded applications, you must be aware of some specific details of the Silverlight for Windows Embedded implementation of user-defined event handling in applications.
Default Event Handling
The Silverlight for Windows Embedded visual host propagates unhandled events through the object tree. A default scenario, which illustrates how events that are generated as a result of a user left mouse button click are "bubbled up" from the object that raises the event to successive parent objects, is shown in the following figure. This example contains six UI elements in the object tree: a UserControl at the root, a ListBox child of the UserControl, and four CheckBox children of the ListBox. Assume the default ClickMode configuration for the check box controls in this example so that each CheckBox control automatically gets focus when a MouseLeftButtonDown event occurs within the control. Each control also generates a Click event if it has focus and there is a MouseLeftButtonUp event inside the control. No user-defined event handling occurs in this example.
Suppose the user moves the mouse into the second check box and presses down on the left mouse button as shown by the arrow in the figure. The relevant events for this action are MouseEnter, MouseLeftButtonDown, and GotFocus. In this case, the default event handling sequence is:
- MouseEnter on the ListBox
- MouseEnter on the CheckBox
- MouseLeftButtonDown on the CheckBox
- GotFocus on the CheckBox
- GotFocus on the ListBox
The GotFocus event is routed up the visual tree from the CheckBox to the ListBox, as shown in the figure.
.jpg "MLBD Default Event Handling")
Default event handlers are commonly used to suppress routed events that a particular UI object implementation does not propagate further or to provide special handling of that routed event that is a feature of the object. For instance, a UI object might raise its own object-specific event that contains more specifics about what some user input condition means in the context of that particular object. The object implementation might then mark the more general routed event as handled. Object event handlers are typically implemented so that they are not invoked for routed events where shared event data was already marked handled. There are some built-in Silverlight for Windows Embedded object event handlers that set the handled flag on the event data by default. In this case, the affected event will not be routed to the parent of the control.
Particular Silverlight for Windows Embedded event routing and event handlers are designed to work by default in the same way that they do in Silverlight for the desktop browser. Properties of the events and default event routing information can be found in the Silverlight documentation for the specific control and event.
In the example illustrated in the preceding figure, the MouseLeftButtonDown and MouseLeftButtonUp event handled flags are set to true by the default event handler, and depending specifically on the configured ClickMode of the CheckBox control, the more specific Click and Checked events are raised. Neither the MouseLeftButtonDown nor the MouseLeftButtonUp events are routed to the ListBox.
The following figure shows the continuation of this scenario. When the user releases the left mouse button and moves the mouse away from the CheckBox and ListBox elements, the default event handling sequence is:
- MouseLeftButtonUp on the CheckBox
- Checked on the CheckBox
- Click on the CheckBox
- MouseLeave on the CheckBox
- MouseLeave on the ListBox
No additional events are bubbled up to the ListBox from the CheckBox, and the MouseLeave events are generated as the mouse leaves the CheckBox and the ListBox, respectively.
.jpg "MLBU Default Event Handling")
User-Defined Event Handling
You can handle UI events in Silverlight for Windows Embedded applications by using C++ delegates attached to UI objects. The Silverlight for Windows Embedded API includes a set of C++ Add*EventHandler methods to define these delegates and to specify the user-generated methods that the delegates point to for handling events. Two implementation details are especially important in designing your own event handlers:
- User-defined object event handlers that are attached with Add*EventHandler methods are always invoked in addition to and prior to internally defined or default object event handlers.
- If a user-defined event handler sets the handled flag of the XREventArgs structure to true, internal or default handlers detect that the event has been previously handled and will not perform default handling tasks. In addition, events with the handled flag set to true will not be routed to parent objects in the visual tree.
When you set the value of the Handled property to true in the event data for a routed event, this action is referred to as "marking the event handled". There is no absolute rule for when you must mark routed events as handled. Generally, there are two reasons to mark an event handled:
- You do not want the default behavior that is provided by the internal event handling of the control.
- You do not want the behavior that is provided by the event handling of a parent of the control; that is, you do not want event routing.
Typically, only one handler implementation exists for responding to any single routed event occurrence. If more responses are needed, then implement the necessary code through application logic that is chained within a single handler rather than by using the routed event system for forwarding events.
To create an application that implements customized event handlers, use the techniques and procedures that are detailed in Getting Started with Silverlight for Windows Embedded.
Differences in Silverlight Event Processing Models
Windows Embedded Compact and Windows event processing models are not identical. You must understand the Silverlight for Windows Embedded model to avoid unanticipated behavior in your applications. The major differences between Silverlight for Windows Embedded and Silverlight for the desktop browser are detailed in Differences Between Microsoft Silverlight 3 and Silverlight for Windows Embedded. Generally, Silverlight for Windows Embedded events are equivalent to events in Silverlight for the desktop browser. Silverlight for Windows Embedded provides the same event handling and routing services as those provided by the desktop version, but the Windows Embedded Compact implementation differences are significant for application developers. A summary of the differences between Silverlight for the desktop browser and Silverlight for Windows Embedded that are relevant to event handling are shown in Table 1.
| Silverlight for Windows Embedded | Silverlight for the desktop browser |
|---|---|
To handle events yourself in code, use the Add*Handler and Remove*Handler public methods on UI objects. Setting the handled flag in the event data stops event routing to other objects in the visual tree. |
To handle events yourself in code, override the method in a subclass of the object. When you set the handled flag in the event data, it stops event routing to other objects in the visual tree. |
Does not support AddHandler for subclasses. |
To additionally handle events that are marked as handled (handled flag set), subclass from the object class and use the AddHandler method. |
Always invokes user-provided event handlers before default or internal object event handlers. |
Always invokes user-defined overrides of event instead of default event handlers. |
Stores event data in structures that inherit from XREventArgs. The structures specify the type of data that is contained in the IXRDelegate<ArgType, [SenderType]> objects that handle specific types of events. |
Stores event in classes that inherit from System.EventArgs. |
Supports event binding only in C++ code by attaching event handlers to UI objects. |
Supports event binding directly in XAML through attribute values. |
Sets the focus to the first element in the visual tree that can receive the focus. However, the GotFocus event is not raised unless you explicitly call IXRControl::Focus in the initialization procedure. |
Raises the GotFocus event when the focus is automatically set on the first element in the visual tree that can receive the focus during application initialization. |
In This Section
To create and work with event handlers, refer to the procedures in the following topics.
- Create Event Handlers in Code in Silverlight for Windows Embedded
Describes how to create an event handler in code, retrieve event data, access UI elements from within an event handler, and add an event handler to an object that was generated when your XAML files were parsed.
- Use the LayoutUpdated Event to Create UI Objects in Silverlight for Windows Embedded
Describes how to use the LayoutUpdated event to add Silverlight for Windows Embedded objects to your UI in code when the application loads.
There are additional code examples for event handling in the following topics.
- Add Event Handlers
Describes how to create and modify an event handler for a UI object that already exists.