Walkthrough: Authoring User Controls for Devices

In this walkthrough you create a control library and author a user control to put in it. Distinguish a user control, a combination of Windows Forms controls in a single reusable unit, from a custom control, a control that requires UI or functionality not available through standard controls.

The user control in this walkthrough is a simple clock display for devices and is modeled after similar desktop walkthroughs, such as Walkthrough: Authoring a Composite Control with Visual Basic and Walkthrough: Authoring a Composite Control with Visual C#.

The walkthrough consists of four main tasks:

• Creating a control library and a control.

• Renaming the library and the control.

• Adding components to the control.

• Testing the control on the Device Emulator.

You can use either Visual Basic or Visual C# for this walkthrough. Where both languages use the same file name that has a language-specific extension, a vertical bar reminds you to choose the extension for the language you are using, as in filename.vb|cs.

This walkthrough was written by using Visual Basic Development Settings and Visual C# Development Settings.

Prerequisites

None.

Choosing a Target Device

To ensure that you are prompted to select a device when you deploy your solution, complete the following procedure.

To prompt for device choices at deployment time

1. On the Tools menu, click Options, expand Device Tools, and then click General.

   (If you cannot see Device Tools, select Show all settings at the bottom of the Options dialog box.)

2. Select the Show device choices before deploying a device project check box.

Creating the Project

The name that you give a new project also sets the root namespace and the assembly name.

To create the control library and the control

1. (Visual Basic) On the File menu, click New Project.

   —or—

   (Visual C#) On the File menu, point to New, and then click Project.

2. In the Project Types pane of the New Project dialog box, expand Visual Basic or Visual C#, and then click Smart Device.

   If the language you want does not at first appear, expand Other Languages. This display is governed by your development settings.

3. In the Templates pane, click Smart Device Project.

4. In the Name box, type ctlDevClockLib, and then click OK.

5. (Visual C# only) In the Location box, verify where you want to store your project files, and then click OK.

6. In the Target platform drop-down, select Pocket PC 2003.

7. Select .NET Compact Framework Version 2.0 from the .NET Compact Framework version drop-down.

8. Click Control Library in the Templates pane, and then click OK.

   The Component Designer appears.

You have already specified the project name, root namespace, and assembly name (ctlDevClockLib). However, components in the project have default names assigned by Visual Studio (for example, UserControl1). You typically want to change these names to more meaningful terms.

To rename the library and the control

1. In Solution Explorer, right-click UserControl1.vb|cs, and then click Properties.

2. Change the File Name to ctlDevClock.vb|cs.

3. (Visual C# only) In the message box asking whether you want all references to this code element renamed, click Yes.

   The name change in the Properties window now propagates to other references, such as the class name and constructor.

Next you add components from the Toolbox to provide functionality and user interaction for your user control. In this walkthrough, you add a Timer control to access the system time and a Label control to display the time.

To add components and change their properties

1. In the Toolbox, double-click Label.

   A label control is added to the user control in the Component Designer.

2. In the Properties window for the label control, do the following:

1. In the Toolbox, double-click Timer.

   A Timer control appears in the component tray.

2. In the Properties window for the timer control, do the following:

In the next steps, you add an event handler to display clock ticks in the Label control.

To add an event handler

1. In the component tray, double-click Timer1 (Visual Basic) or timer1 (C#) to open the code editor at the tick event.

2. (Visual Basic) Insert this event-handing code:

   lblDisplay.Text = Format(Now, "hh:mm:ss")
   

   —or—

   (Visual C#)

   lblDisplay.Text = DateTime.Now.ToLongTimeString();
   

3. (Visual Basic) Change the access modifier from Private to Protected, and add the Overridable keyword, so that the handler code resembles the following:

   Protected Overridable Sub Timer1_Tick(ByVal sender As Object, _
      ByVal e As System.EventArgs) Handles Timer1.Tick
      ' Causes the label to display the current time  
      lblDisplay.Text = Format(Now, "hh:mm:ss")
   End Sub
   

   —or—

   (Visual C#) Change the access modifier from private to protected, and add the virtual keyword, so that the handler code resembles the following:

   protected virtual void timer1_Tick(object sender, System.EventArgs
      e)
   {
      // Causes the label to display the current time.
      lblDisplay.Text = DateTime.Now.ToLongTimeString(); 
   }
   

4. On the File menu, click Save All.

5. (Visual Basic only) In the Save Project dialog box, save the project as ctlDevClockLib to a location of your choice.

Testing the Control

This simple device application serves as a test container for your control.

To build the control and create a test container

1. On the Build menu, click Build (or Build ctlDevClockLib).

2. On the File menu, point to Add, and then click New Project.

3. In the Add New Project dialog box, click Smart Device in the Project types pane, and then click Smart Device Project in the Templates pane.

4. In the Name box, type Test, and then click OK.

5. In the Add New Smart Device Project dialog box, select the Pocket PC 2003 from the Target platform drop-down, select .NET Compact Framework Version 2.0 from the .NET Compact Framework drop-down, click Device Application in the Templates pane, and then click OK.

6. In Solution Explorer, right-click the Test project, and then click Set as StartUp Project.

7. Right-click the Test project, and then click Add Reference.

8. In the Add Reference dialog box, click the Projects tab, and then double-click ctlDevClockLib.

9. In the Toolbox, locate the ctlDevClockLib Components tab, and then double-click the ctlDevClock component.

   The control is loaded into the designer.

10. On the Debug menu, click Start (or Start Debugging).

11. In the Deploy dialog box, select Pocket PC 2003 SE Emulator, and then click Deploy.

See Also

Concepts

Control Type Recommendations

Other Resources

Developing Windows Forms Controls at Design Time