How to Create a .NET Compact Framework Application by Using Visual Studio .NET 2003 (Windows CE 5.0)

 

Mike Hall
Microsoft

January 2005

Applies to:
   Microsoft® Visual Studio® .NET 2003
   Microsoft .NET Compact Framework
   Microsoft Windows® CE

Summary: This article provides step-by-step instructions for working with Visual Studio .NET 2003 to build and debug a .NET Compact Framework application in C#. You will build a C# forms-based application that will be deployed to a Windows CE–based emulator. This application will handle mouse down, move, and up events and will capture user scribble data. The scribble data can then be viewed on a desktop .NET Framework application also written in C#. This article is divided into three parts, each containing a number of exercises that you can complete. It will take approximately 60 minutes to complete all of the steps. (18 printed pages)

Download Windows CE 5.0 Embedded Development Labs.msi from the Microsoft Download Center.

Contents

Introduction
Part 1: Creating the Initial Application
Part 2: Handling Mouse Down, Move, and Up Events
Part 3: Debugging the C# Scribble Application
Summary

Introduction

In this article, you will write an application to capture mouse movement on a Microsoft® Windows® CE–based device, which is similar to capturing a signature on a portable device.

To complete the exercises in this article, ensure that your workstation has the following software installed:

• Microsoft Windows XP Professional
• Microsoft Visual Studio® .NET 2003

For this article, you will use the Microsoft Windows CE .NET emulator, which emulates an x86-based device. The steps you will follow in this article are identical to those needed to build an application for Windows CE–based devices.

This exercise has a download including the CodeClip application, which you can use to help you work through this exercise.

For more information about the subjects in this article, visit the Microsoft Windows Embedded Developer Center or the Microsoft Visual Studio Developer Center.

Part 1: Creating the Initial Application

In this part of the exercise, you will perform the following procedures:

• Create the base application
• Set options for the project
• Change the text shown on the title bar of the form
• Rename the menu command for exiting the application
• Build and test the application

You will see just how quickly an application can be built to handle user input and communicate over a corporate network or the Internet.

To create the base application

1. Open Visual Studio .NET 2003 by using the desktop shortcut.
2. On the File menu, click New Project.
3. Under Project Types, select Visual C# Projects.
4. Under Templates, select Smart Device Application.
5. In the Name box, type Scribble

The following illustration shows the preceding selections in the New Project dialog box.

1. Click OK.

You will now set the options for your project. There are a number of project types that you can create.

You can also target Pocket PC or Windows CE–based devices. You may be wondering why there are two wizard options (and if you have the Smartphone SDK, there are three options). After all, the applications are going to be generated in Microsoft intermediate language (MSIL) format, which is processor and operating system independent. The reason is that Pocket PC devices and Windows CE–based devices typically have different screen layouts. Pocket PC devices have their menus at the bottom of the screen, whereas Windows CE–based devices typically have their menus at the top of the screen. The wizard will create a framework application that includes the correct form size and menu layout.

To set options for the project

1. In the Smart Device Application Wizard, select Windows CE as the platform, and then select Windows Application as the project type, as shown in the following illustration.

   

2. Click OK.

Figure 1 shows how the user interface of Visual Studio .NET looks after the core application has been generated. Notice that the left side of the window shows various controls that you can add to your form. The center of the window shows your application's form and is also the area that you can use to edit or add source code. The right side of the window shows Solution Explorer (the workspace) and an area that you can use to configure parts of the application.

Figure 1. Core application in Visual Studio .NET

At this point, you can change the default text shown on the title bar of the form.

To change the text shown on the title bar

1. Select the Text property for Form1, as shown in the following illustration.

   

2. Change the text from Form1 to Scribble.

   Notice that the form title has changed. Now, you can add a menu to the application, which will make it easy for you to exit the application.

3. From the Visual Studio Toolbox, click and drag MainMenu onto the form.

   You will notice that the menu is added to the form, as shown in the following illustration.

   

   Adding menu commands is extremely simple.

4. On the form's menu, click Type Here.

5. Type File, and then press ENTER.

6. Type Send Scribble, and then press ENTER.

7. Type Exit, and then press ENTER.

8. Select the Exit menu command.

As shown in the following illustration, the properties change to reflect the menu command that you have selected.

By default, the File | Exit menu command has a name of menuItem2. If you were to add code to this menu command, the click handler would be shown as menuItem2_Click. Renaming this menu command will better reflect its purpose.

To rename the menu command for exiting the application

1. Use the Properties pane to change menuItem2 to FileExit.
2. Double-click the File | Exit menu command on your form.

This step opens the code editing pane, as shown in the following illustration.

1. In the FileExit_Click handler, type this.Close( ); as shown in the following illustration.

   

   Notice how Microsoft IntelliSense® prompts you to show you what you can do with the "this" item.

You're now ready to build and test your application. (Of course, at this stage, the application isn't finished yet. You still need to add some functionality to the application to add support for scribbling in the client area.)

To build and test the application

1. Click Build | Build Scribble.

   The application should build without warnings or errors. You're now ready to deploy the application.

2. Click Debug | Start without Debugging. (You will debug later in the article.)

3. When you are prompted with a list of devices that you can deploy to, select Windows CE .NET Emulator (Default) for the purposes of this exercise, as shown in the following illustration.

   

4. Click Deploy.

This step starts the Windows CE .NET emulator and deploys the Microsoft .NET Compact Framework. After the .NET Compact Framework is deployed, the application starts as shown in the following illustration.

Now that the application is running, you can start adding code to handle the mouse down, mouse move, and mouse up events.

1. In the scribble application, click File | Exit.

Part 2: Handling Mouse Down, Move, and Up Events

Your scribble application will capture mouse movement from the user, but only when the mouse button is down. Therefore, you need a Boolean to show whether the mouse is down (capturing), or up (not capturing). You will check the Boolean in the mouse move handler. If the Boolean is set, you will add the new X,Y point to an array of points (which you also need to add to the application).

You're going to keep track of all the points drawn in the client area of the application. You will store this list of points in an ArrayList.

In this part of the exercise, you will perform the following procedures:

• Create a class to store points
• Add code to the class
• Create an array
• Switch to design view
• Select the MouseDown event
• Add code to the MouseDown event handler
• Add code to the MouseUp event handler
• Build the application

To create a class to store points

1. On the Project menu, click Add Class.

2. In the Name box, type csPoint.cs as shown in the following illustration.

   

3. Click Open.

   This step opens the source for the new class. Notice that the class is part of the same application namespace, "Scribble".

4. Delete the class definition for csPoint.

   This step leaves the following code.

using System;

namespace Scribble
{

}

You now need to add some code to the class. Instead of typing the code by hand, you can paste the code from a tool called CodeClip. CodeClip is a helper application that makes it simple to copy preselected code fragments to the Clipboard. CodeClip appears as a transparent blue banner on the top of the window.

To add code to the class

1. Start the CodeClip tool.
2. Open the Compact Framework Lab.
3. Double-click the csPoint item.

This step copies the csPoint code to the clipboard.

1. Paste the code into your csPoint class file.

   Your class file will now look like the following. This is a very simple class that stores the X and Y positions for a mouse down event or a mouse move event.

   using System;
   
   namespace Scribble
   {
      public class csPoint
      {
         public csPoint(int iX,int iY)
         {
            x=iX;
            y=iY;
         }
   
         public int GetX( )
         {
            return x;
         }
   
         public int GetY( )
         {
            return y;
         }
         int x;
         int y;
      }
   }
   

The application will need to store some information about whether the mouse is down, and the previous mouse location. You will also need an array to hold the points, which will be global variables in your application.

To create an array

1. Click the Form1.cs tab, as shown in the following illustration, to get back to the main application code.

   

2. Locate the FileExit function.

3. Use CodeClip to copy the Globals code to the clipboard.

4. Paste the Globals code into your application just before the FileExit handler.

You have a number of options for writing applications for Windows CE: Microsoft Win32®, Microsoft Foundation Classes (MFC), or managed code. To add mouse down, up, and move event handlers to a Win32 application, you would need to know which messages are sent to your application from Windows; these are WM_LBUTTONDOWN, WM_MOUSEMOVE, and WM_LBUTTONUP. Microsoft eMbedded Visual C++® and MFC make adding handlers somewhat easier through the wizard, which lists each of the Windows messages that the current class can handle.

The following procedure shows how easy it is to add mouse event handlers to the .NET Compact Framework application.

On the project tabs, you will notice Form1.cs shown in bold. This is your current open document. You are looking at the code view for your form, and you need to switch to design view to add the event handlers.

To switch to design view

• In the Project pane, click the Form1.cs [Design] tab, as shown in the following illustration.

  

In the Properties pane in the lower right of Visual Studio, you can change a number of attributes for this form, such as the name, color, and font size. Figure 2 shows the Properties pane.

Next to the Properties button, you will see the Events button. This button is used to select events for the currently selected form or control.

Figure 2. Properties pane

To select the MouseDown event

1. In the Properties pane, click the lightning bolt.

2. Scroll through the Properties pane until you locate the mouse events, as shown in the following illustration.

   

3. Double-click the MouseDown event.

This step adds a MouseDown handler to the application, and also opens the code editing pane.

You now need to add some code to the MouseDown handler. Again, the most efficient method is to use CodeClip.

To add code to the MouseDown handler

1. Start the CodeClip tool.
2. Select the MouseDown item, as shown in the following illustration.

1. Click the Copy button.

2. Switch back to Visual Studio .NET.

3. Click the Edit | Paste menu command to paste the text.

   This code sets the bMouseDown Boolean to true, stores the current X and Y positions, and adds a point to the array.

   private void Form1_MouseDown(object sender, 
    System.Windows.Forms.MouseEventArgs e)
   {
      bMouseDown=true;
      x=e.X;
      y=e.Y;
      arList.Add(new csPoint(x,y));      
   }
   

4. In the Project pane, click the Form1.cs [Design] tab.

5. Locate and double-click the MouseMove event.

6. Click the CodeClip banner to display the CodeClip dialog box.

7. Select the MouseMove item, and then click the Copy button.

8. Switch back to Visual Studio .NET.

9. Click the Edit | Paste menu command to paste the text.

The following code for the MouseMove event is slightly more complicated than the code for the MouseDown event. You check to see whether the mouse is down (note that you still get a MouseMove notification even if the mouse buttons are not down). If the mouse button is down, you create a graphics object (similar to a DeviceContext in Win32 programming). You then draw a line from the previous point to the new point. In this case, you are drawing the line in red; this color is easy to change because in Win32, all colors are referenced by their RGB (red, green, and blue) value.

private void Form1_MouseMove(object sender, 
System.Windows.Forms.MouseEventArgs e)
{
   if (bMouseDown) 
   {
      Graphics gr=this.CreateGraphics();
      if (x == -1 && y == -1) 
      {
         x=e.X;
         y=e.Y;
      }
      gr.DrawLine(new Pen(Color.Red),e.X,e.Y,x,y);
      x=e.X;
      y=e.Y;
      arList.Add(new csPoint(x,y));
   }      
}

To add code to the MouseUp handler

1. In the Project pane, click the Form1.cs [Design] tab.
2. Locate and double-click the MouseUp event.
3. Click the CodeClip banner to display the CodeClip dialog box.
4. Select the MouseUp item, and then click the Copy button.
5. Switch back to Visual Studio .NET.
6. Click the Edit | Paste menu command to paste the text.

In the MouseUp handler, you simply set the bMouseDown Boolean to false to show that the mouse is now up, and add a point with values of -1, -1 to show that you've ended a line segment, as shown in the following code.

private void Form1_MouseUp(object sender, 
System.Windows.Forms.MouseEventArgs e)
{
   bMouseDown=false;
   arList.Add(new csPoint(-1,-1));      
}

Now it's time to build the application.

To build the application

1. Click Build | Build Scribble.

   The application should build without warnings or errors. You're now ready to deploy the application.

2. Click Debug | Start without Debugging. (You will debug later in the article.)

3. When you are prompted with a list of devices you can deploy to, select Windows CE .NET Emulator (Default) for the purposes of this exercise, as shown in the following illustration.

   

4. Click Deploy to deploy and start the application.

5. Move the mouse and show that no ink is displayed in the application. The application will display ink only when the mouse button is down.

6. Click and hold the left mouse button, move the mouse, and then release the mouse button.

   The line that you made in the application should look similar to the lines in the following illustration.

   

   Congratulations! You have just written a scribble application in C#.

7. In the scribble application, click File | Exit.

Part 3: Debugging the C# Scribble Application

So far, you've built and run the application. It can be useful to debug any new application. In the case of writing an application for Windows CE (whether through eMbedded Visual C++ or Visual Studio .NET 2003), the operating system and application are running on remote devices — devices connected to the development computer. You therefore need to download the application to the device before debugging. As far as the user experience is concerned, debugging a Windows CE application is very similar to debugging a desktop application.

In this part of the exercise, you will set a breakpoint on the mouse down handler and will trace the flow of the application by stepping through it.

To set a breakpoint on the mouse down handler and step through the application

1. Click the Form1.cs tab, as shown in the following illustration, to get back to the main application code.

   

2. Locate the Form1_MouseDown function.

3. Set a breakpoint on the bMouseDown=true; line by clicking the line and pressing F9.

   You will see a red breakpoint symbol being displayed in the margin next to the bMouseDown=true; line, as shown in the following illustration.

   

   You're now ready to run the application.

4. Click Debug | Start or press F5.

   This step builds the application (if needed) and downloads the application to the emulator.

5. After the application has started in the emulator, click in the client area of the application.

   The application will break on the bMouseDown=true; line, as shown in the following illustration. You can now step through the lines of code.

   

   There are a number of items that you can look at while the application is running. The lower-left pane of the Visual Studio application may show search results or another item. You can change this pane to show the current local variables.

6. Expand the this item in the list of local variables, as shown in the following illustration.

   

   You will notice that bMouseDown is currently set to false, and that the X and Y values are currently set to zero.

7. Step through the application by pressing F11.

   You will notice that the X, Y, and bMouseDown values change as you step through the code.

   When you reach the line of code that adds a new ArrayList item, you also need to "new up" an instance of the csPoint class. As you step through the code, you will step into the csPoint class.

8. Press F5 to run the application.

9. Click File | Exit.

Summary

Following is a summary of the exercises provided in this article:

• Created a C# smart device application for Windows CE
• Added support for mouse move, mouse down, and mouse up events on the form.
• Added drawing support, including the creation of a custom pen
• Debugged the C# Scribble application