Step by Step: Build a Custom Control for Visual Studio .NET 2003 by Using the .NET Compact Framework on Smartphone

Article
10/26/2006

Microsoft Corporation

February 2005

Applies to:
   Microsoft Visual Studio .NET 2003
   Microsoft .NET Framework version 1.1
   Microsoft .NET Compact Framework version 1.0
   ASP.NET version 1.1
   Windows Mobile-based Smartphones
   Microsoft eMbedded Visual C++ version 4.0
   Microsoft Windows CE .NET

Summary: The objective of this exercise is to learn how to create a reusable control that can be added to the Microsoft Visual Studio .NET 2003 Toolbox and dropped onto a form. This exercise will take approximately 30 minutes to complete. (23 printed pages)

Download Lab 1 Building a Custom Control for VSNET 2003.msi from the Microsoft Download Center.

Part 1: Creating a Custom Control for the Visual Studio .NET 2003 Toolbox
Part 2: Compiling the Design-Time Custom Control
Part 3: Creating the Client and Adding the Control to the Toolbox
Summary

To complete this exercise, you will need:

Smartphone 2003 emulator
Smartphone 2003 SE QVGA (Virtual Radio) – SDK emulator
Interop
Internet connection

Part 1: Creating a Custom Control for the Visual Studio .NET 2003 Toolbox

In this part, you will create a custom control that provides the functionality for a Snake game and allows design-time customization using the Microsoft Visual Studio .NET integrated development environment (IDE).

Some illustrations in this part of the exercise are thumbnails. You can click the thumbnails for larger images.

To add the custom control

Create a folder on drive C, and then rename this folder Labs.
Copy the Smartphone2003 folder from the download, and then paste it into the C:\Labs folder.
In the C:\Labs\Smartphone2003 folder, open the Lab1 folder.
Rename the SnakeControl folder to SnakeControl_DVD.
Rename the SnakeSP folder to SnakeSP_DVD.
Start Visual Studio .NET 2003.
On the File menu, point to New, and then click Project.
In the Project Types list, select Visual C# Projects.
Under Templates, select Smart Device Application, as shown in the following illustration.
In the Name box, type SnakeControl.
In the Location box, change the path to C:\Labs\Smartphone2003\Lab1.

Important Be sure that file names and locations are correct throughout the exercise. If not, the exercise may not work.
Click OK to start the Smart Device Application Wizard.
Select the Smartphone platform and Class Library project type, and then click OK, as shown in the following illustration.

By default, Visual Studio creates a new class when you create a new class library project. For this part of the exercise, you will delete this new class and add your own.
In the Solution Explorer, right-click Class1.cs, and then click Delete, as shown in the following illustration.
Click OK to remove the file, as shown in the following illustration.
On the File menu, click Add Existing Item.
Browse to C:\Labs\Smartphone2003\Lab1\Code.
Select the SnakeControl.cs file, and then click Open to add the file to the project. This will copy the file into your project directory.
In the Solution Explorer, double-click SnakeControl.cs to open the file.

This file contains the majority of the code for the Snake control.

Note The control inherits from System.Windows.Forms.Control. This class provides the basic functionality — such as input and messaging — that is used for creating a Windows control. The class also contains the implementation for the Snake game. In the next task, you will extend the code to work as a custom control.

Note If you try to compile the project now, it will fail, because it is missing a couple of assemblies used for drawing and winforms.
On the Project menu, click Add Reference, and then click the .NET tab.
Select the System.Windows.Forms component, and then click Select.
Select the System.Drawing component, and then click Select.
Click OK to add both references to the project, as shown in the following illustration.
On the Build menu, click Build Solution to build the control.

The compiler output should generate a couple of warnings and no errors.

To enable the control to be added to the Visual Studio .NET Toolbox, you need to add an assembly-level attribute.

To enhance the custom control

Open the SnakeControl.cs file.

Find the following line near the top of the file.

//TODO: Add assembly level attribute to enable plugin to toolbox

Immediately below this line, add the following lines.
```
#if NETCFDESIGNTIME
[assembly: System.CF.Design.RuntimeAssemblyAttribute("SnakeControl, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null")]
#endif
```
Note The attribute lives in the System.CF.Design namespace, which is not a part of this project. This location is necessary because two assemblies will be created: one to run on the device and another with extra design-time functionality. The #if NETCFDESIGNTIME and #endif statements provide conditional compilation only if the symbol NETCFDESGINTIME exists, which allows us to create one assembly for the device and another for the designer. This arrangement helps to reduce the amount of the code on the device.

Next, you will add attributes to some of the accessors, so that you can modify them during design time.

Find the following accessor.

// TODO: ADD ATTRIBUTES FOR DESIGN PROPERTIES WINDOW
public int BlockSize {
get {return blockSize;}
    set {blockSize = value; DesignView(); this.Invalidate();}
}

Above the accessor declaration, add the code so it looks like the following.
```
#if NETCFDESIGNTIME
    // Show this property in the property grid.
    [System.ComponentModel.Category("Snake")]
    [System.ComponentModel.Description("The snake block size")]
#endif
public int BlockSize { 
get {return blockSize;}
    set {blockSize = value; DesignView(); this.Invalidate();}
}
```
These attributes control how the property is displayed in the Visual Studio .NET Properties window. The Category attribute sets the category in which the property appears. The Description attribute is displayed at the bottom of the Properties window. The property name, BlockSize, is the name given in the Properties window, as shown in the following illustration.

Next, you will link in two more accessors to control the color of the snake.

Find the following accessor.

// TODO: ADD ATTRIBUTES FOR DESIGN PROPERTIES WINDOW
public Color Head {
    get {return snakeHeadColor;}
    set {snakeHeadColor = value; this.Invalidate();}
}

Above the accessor declaration, add the following lines.

#if NETCFDESIGNTIME
    // Show this property in the property grid.
    [System.ComponentModel.Category("Snake")]
    [System.ComponentModel.Description("The color used for the snake's head")]
#endif

Find the following accessor.

// TODO: ADD ATTRIBUTES FOR DESIGN PROPERTIES WINDOW
public Color Body {
    get {return snakeBodyColor;}
    set {snakeBodyColor = value; this.Invalidate();}
}

Above the accessor declaration, add the following lines.
```
#if NETCFDESIGNTIME
    // Show this property in the property grid.
    [System.ComponentModel.Category("Snake")]
    [System.ComponentModel.Description("The color used for the snake's body")]
#endif
```
Note When any of the set accessors are called to change a value, the code calls Invalidate to repaint the control.

Next, you will add event support to the control, so that you can notify the parent control when the snake length increases and when the game is over.
Locate the following comment.
```
// TODO: ADD THE EVENTS HERE
```
Add the following event declarations.
```
public event EventHandler SnakeLengthChanged;
public event EventHandler GameFinished;
```
The EventHandler allows the host parent control to provide a method signature that you can call within the custom control. You will see this method signature in operation in the next exercise. For now, you will add code to raise events accordingly.
Locate the following comment in the OnTick method.
```
//TODO: Raise event that snake is now longer
```
Immediately after this line, add the following lines.
```
if(this.SnakeLengthChanged != null)
    this.SnakeLengthChanged(this, EventArgs.Empty);
```
This code checks to see if an event handler has been registered, in which case it will be called.
Locate the following comment in the DoDead method.
```
//TODO: raise game finished event
```
Immediately after this line, add the following lines.
```
if(this.GameFinished != null)
    this.GameFinished(this, EventArgs.Empty);
```
Finally, you need to add code to play sounds when the Snake eats a snack or when the timer interval shortens (to indicate a rise in level). Unfortunately, the .NET Compact Framework does not provide a direct mechanism to play sounds. Instead, you need to use Platform Invoke (P/Invoke) calls to a native application programming interface (API). Interop allows the control to easily communicate with COM components and the Win32 API. The .NET Compact Framework version 1.0 does not provide COM Interop, but does provide P/Invoke calls to the WinCE API.
Locate the following comment in the SnakeControl class declaration.
```
// TODO: ADD INTEROP DECLARATION AND CONSTANTS
```
Immediately after this comment, add the following lines.
```
[DllImport("CoreDll.DLL", EntryPoint="PlaySound", SetLastError=true)]
private extern static int PlaySound(string szSound, IntPtr hMod, int flags);
```
The attribute and method signature declaration allows you to use P/Invoke to make a WinCE API call. The method signature int PlaySound(string szSound, IntPtr hMod, int flags) maps to the WinCE PlaySound API function. The extern keyword modifier notifies the compiler that the method is implemented externally. The DllImport attribute specifies that the external location is CoreDll.dll and the entry point to the library is the PlaySound method. So, when you call the PlaySound method, it maps to the exported PlaySound method in CoreDll.dll.

For more information about the PlaySound method, see Help for the Smartphone 2003 SDK. (Click Start, point to All Programs, point to Microsoft Smartphone 2003 SDK, and then click Smartphone 2003 Help.)
Click the Index tab, and then in the Type in the keyword to find box, type PlaySound.
In the list of keywords, double-click PlaySound or click Display. You can use this procedure to find out more information about calling a native function.

Note The PlaySound function has a third parameter, fdwSound, which includes a list of flags that specify the type of sound and how it is played.

To find out the values for the flags, it requires investigation. They may be in the header file listed at the end of the Help page; if they are not, you should create a native Microsoft eMbedded Visual C++ version 4.0 project that includes the type, and then view the type declaration. This method will open up the relevant header file that includes all of the flag definitions.

To view the header file

Open a Command Prompt window.
Change to the directory where the header is located by typing CD C:\Program Files\Windows CE Tools\wce420\SMARTPHONE 2003\Include\Emulator.
To open the mmsystem.h header file in Notepad, type notepad mmsystem.h.
Search for the text SND_FILENAME.

Now you can see the constants that are used for the third parameter, fdwSound.

To add these constants to the SnakeControl.cs file

Locate the Interop declaration.

private extern static int PlaySound(string szSound, IntPtr hMod, int flags);

After the declaration, add the following enumeration.
```
private enum Flags {
    SND_ASYNC = 0x1,  /* play asynchronously */
    SND_FILENAME = 0x20000, /* name is file name */
}
```
Finally, add code to play sounds when the snake increases in length or when the timer interval decreases.
Locate the following comment in the OnTick method.
```
//TODO: Play snackSound
```
Immediately after this comment, add the following line.
```
PlaySound(snackSound, IntPtr.Zero, (int) (Flags.SND_ASYNC | Flags.SND_FILENAME));
```
Note You are combining the asynchronous and filename flags with a bitwise OR operator. This combination ensures that the application doesn't pause during the sound.

Locate the following comment in the OnTick method.

//TODO: play levelSound to indicate now level up

Immediately after this comment, add the following line.
```
PlaySound(levelSound, IntPtr.Zero, (int) (Flags.SND_ASYNC | Flags.SND_FILENAME));
```
Now, you have added all of the code to the custom control.
On the Build menu, click Build Solution to build the custom control.
On the File menu, click Exit to close Visual Studio .NET.

This concludes Part 1.

Part 2: Compiling the Design-Time Custom Control

In this part, you will compile the SnakeControl.cs file into a new assembly that contains the extra code that will run in the Visual Studio .NET Toolbox.

Some illustrations in this part of the exercise are thumbnails. You can click the thumbnails for larger images.

To compile the design-time DLL

Click Start, and then click Run.
In the Open box, type C:\Labs\Smartphone2003\Lab1\Code.
Double-click BuildDesignTime.cmd.
Check that the compilation worked and that the code looks like the following screenshot. If there are any errors, check your code.

The command you ran calls with the C# compiler and then copies the DLL to the Visual Studio .NET NETCF Designer directory. This directory has assemblies that are used in the design-time environment. The actual compiler command is:

csc /noconfig /define:NETCFDESIGNTIME /target:library /out:design.SnakeControl.dll ..\SnakeControl\SnakeControl.cs /r:"C:\Program Files\Microsoft Visual Studio .NET 2003\CompactFrameworkSDK\v1.0.5000\Windows CE\Designer\System.CF.Design.dll" /r:"C:\Program Files\Microsoft Visual Studio .NET 2003\CompactFrameworkSDK\v1.0.5000\Windows CE\Designer\System.CF.Windows.Forms.dll" /r:"C:\Program Files\Microsoft Visual Studio .NET 2003\CompactFrameworkSDK\v1.0.5000\Windows CE\Designer\System.CF.Drawing.dll" /r:System.Windows.Forms.dll /r:System.Drawing.dll /r:System.dll /r:System.XML.dll /r:System.Web.Services.dll /r:System.Data.dll /nowarn:1595

copy design.SnakeControl.dll "C:\Program Files\Microsoft Visual Studio .NET 2003\CompactFrameworkSDK\v1.0.5000\Windows CE\Designer"

The C# compiler options reveal that you have specified supplemental arguments:

/noconfig tells the compiler not to automatically reference the full .NET Framework.
/define adds the preprocessor symbol NETCFDESIGNTIME, which is used in the SnakeControl code to determine if you are in design-time mode.
/target:library specifies that you are creating a DLL assembly and not an executable.
/out:design.SnakeControl.dll specifies the output file name for the assembly.
/r specifies the references for the assembly. This argument is repeated for each reference.
/nowarn:1595 suppresses the compiler warning number 1595, which warns of multiple definitions of the same namespace — for example, System.Windows.Forms, which exists in the full .NET Framework and Compact .NET Framework libraries. Because you are using /noconfig, the .NET Compact Framework libraries are automatically referenced instead of the full desktop libraries.

Finally, the assembly design.SnakeControl.dll is copied to the Windows CE Designer directory, which contains other assemblies that will be used during design time.

Part 3: Creating the Client and Adding the Control to the Toolbox

In this part, you will create the Smartphone client and add the SnakeControl to the Visual Studio .NET Toolbox.

You will perform the following tasks:

Create the Smartphone client
Add the custom control to the Visual Studio .NET Toolbox

Some illustrations in this part of the exercise are thumbnails. You can click the thumbnails for larger images.

Creating the Smartphone Client

In this task, you will create a Smartphone client and add a menu structure for the application.

To create the Smartphone client

Start Visual Studio .NET 2003.
On the File menu, point to New, and then click Project.
In the Project Types list, click Visual C# Projects.
Under Templates, click Smart Device Application, as shown in the following illustration.
In the Name box, type SnakeSP.
In the Location box, type C:\Labs\Smartphone2003\Lab1.
Click OK to start the Smart Device Application Wizard, as shown in the following illustration.
Select the Smartphone platform and Windows Application project type, and then click OK.

This will create a basic application with a form and empty menu, as shown in the following illustration.

Now you will add the menu structure for the application. A traditional Microsoft Windows or Pocket PC application can have multiple top-level and nested menus. The Smartphone user interface has been simplified to include two top-level menu items, which map to hardware keys below the screen. These top-level menus are called softkeys. If the softkey does not have a pop-up menu, pressing the softkey will run the top-level menu item. If the softkey does have submenu items, pressing the softkey will open the submenu. The user can then use the directional keypad to navigate and choose the menu item, as shown in the following illustration.

Figure 1. Smartphone directional keypad and the accompanying softkey menu

To achieve the Designed for Windows Smartphone logo certification, the left softkey should not have associated submenus — for example, it is a default action. The right softkey can have multiple nested submenu items, if required.

Note If you create a .NET Compact Framework Smartphone application that includes a pop-up menu for the left softkey, the application will compile; however, the runtime will throw a "not supported" exception at run time.

To create the Smartphone menu

In Visual Studio .NET 2003, in the lower-left corner of the Designer view, click the mainMenu1 control. This will extend the form to include the menu. It is now ready for editing, as shown in the following illustration.
Click Type Here, and then type Start, as shown in the following illustration. This step will create the left softkey menu item.

A placeholder has been created for a new menu item to the right of the left menu item.

Click the rightmost Type Here, and then type Done, as shown in the following illustration.

The menu structure is now complete, but it does not respond to user input. You need to raise events when the user chooses a menu item.
Double-click the Start menu item to create a new click handler.

This step will switch the Code view to the code behind the form and will add the following method signature:
Press SHIFT+F7 to switch the view back to form design view.
Double-click the Done menu item to create a new click handler.
Press SHIFT+F7 to switch back to form design view. The menu design and handlers are now complete.

Now you need to add the custom control to the Toolbox.

Adding the Custom Control to the Toolbox

In this task, you will add a custom control to the Toolbox, add the custom control to the form, and test the form.

To add the custom control to the Toolbox

If the Toolbox window is not visible, on the View menu, click Toolbox, as shown in the following illustration.

The Toolbox defaults to the Device Controls tab, showing the controls that are compatible with Smart Device projects.
Right-click the Toolbox, and then click Add/Remove Items, as shown in the following illustration.

The list of available components on the computer appears, as shown in the following illustration.

To choose the SnakeControl custom control, click Browse, and then browse to the C:\Program Files\Microsoft Visual Studio .NET 2003\CompactFrameworkSDK\v1.0.5000\Windows CE\Designer directory, as shown in the following illustration.
Select the design.SnakeControl.dll file, and then click Open. The view will switch to the Customize Toolbox window, which will display SnakeControl in the list of components.
Click OK to close the window. This step will add the design-time custom control, which you built in Part 2, with extra design-time functionality to the Toolbox.

Now you need to add the custom control to the form, and then test the control.

To finish the basic client

Select the form in the Designer view.
Change the BackColor to DarkGray.
Change the Text to Snake, as shown in the following illustration.

Before you drag SnakeControl onto the form, you need to add a reference to the run-time version of the control.
To add the assembly, on the Project menu, click Add Reference.
Click Browse to look for the assembly.
Browse to the C:\Labs\Smartphone2003\Lab1\SnakeControl\bin\Debug directory.
Select the SnakeControl.dll file, and then click Open.
Click OK to close the Add Reference dialog box, as shown in the following illustration.
Click OK to add the assembly to the application. Now that you have a reference to the run-time control, you can add the design-time control to the form.
In the Toolbox, scroll until you find SnakeControl.
Drag SnakeControl onto the form.
Change the BackColor of the snakeControl1 object to White.
Change the upper-left Location to 8, 8.
Change the Size to 160,160.

****Note SnakeControl has rendered an example of the Snake at design time. The Properties window also contains a Snake category with the accessors that you exposed by using the attributes in Task 1.
Change the BlockSize to 8.

Note Keep the final BlockSize set at 8 to ensure that all games and high scores are consistent.
Try changing the Body and Head colors.

Note The changes are immediate and rendered at design time, as shown in the following illustration.

Now that you have added SnakeControl and modified its properties, you can program against the control.
Press F7 to change to code view for the form.

Locate the following lines in the Form1 constructor.

//
// TODO: Add any constructor code after InitializeComponent call
//

Immediately below these lines, add the following lines.
```
this.snakeControl1.Width = this.ClientRectangle.Width-(2*this.snakeControl1.Left);
this.snakeControl1.Height = this.ClientRectangle.Height-(2*this.snakeControl1.Top);
this.snakeControl1.BlockSize = (int)this.snakeControl1.Width/20;
```
This code will ensure that SnakeControl fills the form and that the blocksize is a twentieth of the game area for standard and high-resolution devices.

Important If this code were not added, the user control would not size correctly on a Quarter Video Graphics Array (QVGA) device, as shown in the following illustration.

Locate the following line in the Form1 class.

private void menuItem1_Click(object sender, System.EventArgs e) {

Immediately below this line, add the following line.
```
this.snakeControl1.Start();
```

Locate the following line in the Form1 class.

private void menuItem2_Click(object sender, System.EventArgs e) {

Immediately below this line, add the following line.
```
Application.Exit();
```
Press CTRL+SHIFT+B to build the solution. The solution should compile with no errors or warnings.
To test the application, press F5. Visual Studio .NET will present the options for deploying the application, as shown in the following illustration.
Select Smartphone 2003 Emulator (Virtual Radio), and then click Deploy.

The Virtual Radio emulator provides emulation functionality for radio hardware; the Radio Required emulator image is designed to be used with a hardware board over a serial connection.

When Visual Studio .NET deploys the application to the emulator (or device), it will determine if the string resources for the System namespace are installed. If the emulator has been started from a cold boot, Visual Studio .NET will automatically copy a cabinet (.cab) file to the device and install the resources.

If you see the following screen on your emulator, click the left softkey or press F1 to continue deploying your application. If the application stops responding during execution, or if you cannot exit the application, press SHIFT+F5 to stop debugging.
In the Smartphone 2003 emulator, wait for the application to load.
Press the left softkey or press F1 to select the Start menu item.
Use the cursor keys to control the snake, as shown in the following illustration.
Use the softkeys to quit the game. Try redeploying the game to the high-resolution emulator.
In Visual Studio .NET, press F5.
Select WWE SP 2003 SE QVGA (Virtual Radio) - SDK Emulator, and then click Deploy, as shown in the following illustration.
Play the game again by using the QVGA device, as shown in the following illustration.