Add Event Handlers (Compact 2013)

Article
11/09/2017

3/26/2014

Although the MyClock example does not require user interaction to operate, most XAML for Windows Embedded applications have a UI that invites interaction with the application by generating events from the keyboard, mouse, or other input devices. Your application responds to these events through event handlers that you write and attach to user-interface objects.

The Windows Embedded Event Tool Window allows you to easily add event handlers for each object in your XAML for Windows Embedded UI. This topic explains how to use the Event Handler View to add new events to your application. You will continue to extend the functionality of MyClock by adding an event handler that responds to a mouse click on the clock’s bezel.

Prerequisites

Develop Your Application by Adding C++ Code

Open the Event Handler View

The Event Handler View presents a list of objects for the current XAML file that you are working with. The top object in the list is selected by default. Below the list of objects, the Event Handler View displays a list of applicable events and any associated handlers for the selected object. When you select a different object in the object list, the event list refreshes to display all possible events that can be associated with that object. You can select only one object at a time.

To open the MyClock Event Handler View

In the Solution Explorer pane, locate the MyClock subproject and open Resource files.
Open the file MainPage.xaml.
On the Tools menu, click **Windows Embedded XAML Tools **, and then click Windows Embedded Events.

The Windows Embedded Events pane, located in the top-right region of the Visual Studio development environment, consists of a list of objects in the top portion of the display and a list of event handlers in the bottom portion of the display. When you click on an object name in the upper portion of the display, the event list changes to indicate which events (such as GetFocus, KeyDown, MouseEnter) can be attached to that object. The Name of each event appears in the left column of this display, while the Handler for that event is listed in the right column.

Click each object to see which events you can attach to it, and notice whether any event handlers are defined for that object. For example, when you click OuterCircle[Ellipse], you can see that the entire Handler column is blank, which means that no handlers have been defined for that object. In the next section, you create a new event handler for the OuterCircle object.

Create an Event Handler

You can associate a new event handler with an event on a particular object simply by typing the name of the event handler in the text box field to the right of the event. When you add a new event handler name, the Event Handler View automatically stubs out the event handler code for you.

To add an event to the OuterCircle object in the MyClock example

In the Windows Embedded Events pane, click the OuterCircle [Ellipse] object.
In the Name column of the event list, find the MouseLeftButtonDown event, and type the handler name ChangeBezel in the text field to the right. Press ENTER.

Windows Embedded XAML Tools automatically generates the stub method MainPage::ChangeBezel and opens the source file MainPage.cpp at the location of this new method, as follows:

Important

For readability, the following code examples do not contain security checking or error handling. Do not use the following code examples in a production environment.

HRESULT MainPage::ChangeBezel (IXRDependencyObject *pSender, 
                               XRMouseButtonEventArgs *pArgs)
{
    HRESULT hr = E_NOTIMPL;
    if((NULL == pSender) || (NULL == pArgs))
    {
        hr = E_INVALIDARG;
    }
    return hr;
}

In MainPage.h, Windows Embedded XAML Tools automatically adds this new method to the list of public methods for the class MainPage:

HRESULT ChangeBezel (IXRDependencyObject *pSender, 
                     XRMouseButtonEventArgs *pArgs);

Because Windows Embedded XAML Tools creates the event handler for you and automatically integrates it into your application, you only have to add application-specific code for responding to the event to the event handler. This enables you to spend far less time managing the framework so that you can focus on what your application does with these events.

In the next section, you add one line of code to the MainPage::ChangeBezel event handler to modify the appearance of MyClock when a user clicks the outer bezel of the clock face.

Add Code to the Event Handler

When a user clicks the outer bezel of MyClock, MainPage::ChangeBezel runs. For this example, you add one line of code to change the thickness of the outer border of the clock face whenever you receive this event:

m_pOuterCircle->SetStrokeThickness(20.0);

This call to the SetStrokeThickness method increases the width of the outer circle border to 20 pixels. Here is what the modified event handler looks like (see MainPage.cpp):

HRESULT MainPage::ChangeBezel (IXRDependencyObject *pSender, 
                               XRMouseButtonEventArgs *pArgs)
{
    return m_pOuterCircle->SetStrokeThickness(20.0);
}

Because this simplified event handler ignores pSender or pArgs, you can remove the generated code that checks for a NULL pSender or a NULL pArgs.

Test the Event Handler

After you make the above changes to the MainPage::ChangeBezel event handler method, save all of your changes, and then build and run MyClock.exe again. When you click the bezel of the clock, the outer border should increase in thickness as shown in the following figure.

Testing the Event Handler

You can modify this event handler to make more sophisticated changes to the clock bezel. For example, you could modify the method to toggle border thickness between two different settings on each new mouse click, or create a new IXRLinearGradientBrush to change the bezel to a different color or different subtle shadow effect on each new mouse click.

Next Steps

Merge Updates