Step by Step: Implement Smartphone-Style Scrolling Data Entry Dialogs 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 Compact Framework version 1.0
   Windows Mobile-based Smartphones
   ASP.NET version 1.1

Summary: The objective of this exercise is for you to learn how to create a data entry dialog that implements form scrolling in the same style as native Smartphone applications and for you to learn how to post data to a Web service. This exercise builds on the previous exercise Step by Step: Build a Custom Control for Visual Studio .NET 2003 by Using the .NET Compact Framework on Smartphone. This exercise will take approximately 30 minutes to complete. (24 printed pages)

Download Lab 2 Implementing SP 2003 Style Scrolling Dialogs.msi from the Microsoft Download Center.

Part 1: Setting Up a New Form for Scrolling
Part 2: Setting Smartphone Input Modes
Part 3: Consuming a Web Service
Summary
Appendix A: Using .NET Compact Framework Version 1.0 SP2

To complete this exercise, you will need:

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

*If your computer is using .NET Compact Framework version 1.0 SP2, please see Appendix A.

Note For this exercise to work, your computer cannot be RASed in to the Microsoft network. Also, this exercise will not work if you are using a virtual computer.

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

Part 1: Setting Up a New Form for Scrolling

In this part, you will create a new form that scrolls in the same style as a native Smartphone application. To do so, you will perform the following tasks:

Create a new form
Add the dialog controls
Set the tab order
Size the controls for the standard and QVGA Smartphone screens
Add events to each text box
Build the solution on two screen sizes

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

Creating a New Form for Scrolling

In this task, you will learn to set up a new form for scrolling.

To create a new form

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.
Start Microsoft Visual Studio .NET 2003.
On the File menu, point to Open, and then click Project.
Browse to C:\Labs\Smartphone2003\Lab2\SnakeSP.
Select the SnakeSP.sln file, and then click Open, as shown in the following illustration.
On the File menu, click Add New Item.
Under Templates, select Windows Form, as shown in the following illustration.
In the Name box, type ScoreEntry.cs, and then click Open.

This form is used to capture information about the user and to upload the score to a Web service. Additionally, the form will have multiple controls that do not fit on the standard form size (182 × 212). Therefore, you will need to implement scrolling.
In the Toolbox, locate the MainMenu control.
Drop a MainMenu control onto the form.
Click the words Type Here, and then type Upload, as shown in the following illustration.

This step creates the left softkey menu item. Notice that a placeholder has been created for a new menu item to the right of the left menu item.
Click the words Type Here, and then type Cancel, as shown in the following illustration.

The menu structure is now complete, but it does not yet respond to user input. You will need to raise events when the user selects a menu item.
Double-click the Upload menu item to create a new click handler. This step should switch to the code view behind the form and will add the following method signature.
Press SHIFT+F7 to switch back to form design view.
Double-click the Cancel menu item to create a new click handler, as shown in the following illustration.
Within this method, add the following code to close the form.
```
this.Close();
```
Press SHIFT+F7 to switch back to form design view. The menu design and handlers are now complete. Next, you will resize the form to accommodate all of the controls.
Click the ScoreEntry form.
Change the Size from 182,235 to 182,336.

Scrolling on the Smartphone platform is different from scrolling on the desktop computer and Pocket PC. Instead of controlling a scroll bar to adjust the screen, the Smartphone uses the next control, which can receive focus to scroll the screen. For example, if you have a form with six text boxes and text boxes 1, 2, and 3 are visible, when the user moves down on the directional pad, the form scrolls down so that text boxes 2, 3, and 4 are visible.

Scrolling support is automatically provided for native applications, but managed applications need to implement this style of scrolling. To achieve this style of scrolling, you will use a vertical scroll bar and a panel to host your controls.
In the Toolbox, locate the VScrollBar control.
Drop a VScrollBar control on the upper-right corner of the form.
Change its Location to 168,0.
In the Toolbox, locate the Panel control.
Drop a Panel control on the upper-left corner of the form.
Change its Location to 0,0.
Set the Size of the Panel to 168,280 to fill the form.
Press F7 to switch to code view.

Locate the following comment in the constructor ScoreEntry.

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

Below this comment, add the following code.
```
// Set the scrollbar dimensions
this.vScrollBar1.Height = this.ClientSize.Height;
this.vScrollBar1.Left = this.Width-this.vScrollBar1.Width;
this.vScrollBar1.Minimum = 0;
this.vScrollBar1.Maximum = this.panel1.Height - this.ClientSize.Height + 5;
```
This code sets the height of the vertical scroll bar to the same height as the visible form. Then, it places the scroll bar so that it fits on the right side of the form. Finally, it sets the minimum value of the scroll bar to be the top of the form. It sets the maximum value to the height of the form minus the height of the visible form, so that the bottom of the scroll bar is at the end of the visible view.

Note A stylus is not available for scrolling the form. Instead, when a control receives focus (for example, by moving up or down), the form may need to scroll to the control.

Next, you will add a method responsible for ensuring that the scroll position and panel top are correctly set.

Add the following method to the ScoreEntry class.

Note Because this method is quite long, perform a cut-and-paste operation to copy the method into the code editor. You can also find this code in C:\Labs\Smartphone2003\Lab2\Code\SetScrollPosition.txt.

/// <summary>
/// Sets the scrollbar and panel position
/// </summary>
/// <param name="topSender">The identifier label for the control,/// or the control if no label exists</param>
/// <param name="bottomSender">The control with focus</param>
void SetScrollPosition(object topSender, object bottomSender) {
    // Get bounds of controls to focus on
    int top = ((Control)topSender).Top;
    int bottom = ((Control)bottomSender).Bottom;
    int height = bottom - top;

    // Get scroll position
    int pos = this.vScrollBar1.Value;

    // Check if control is within view
    if (pos < top && bottom < (pos+this.ClientSize.Height)) {
        //Do nothing
        return;
    }

    // Check if control is above view
    if (bottom < pos + height) {
        // Scroll to view, ensuring the topSender is first visible         // on form
        this.vScrollBar1.Value = top;
    }

    // Check if control is below view
    if (bottom > (pos+this.ClientSize.Height)) {
        // Scroll to view, ensuring the bottomSender is last visible         // on form
        this.vScrollBar1.Value = bottom - this.ClientSize.Height + 5;
    }

    // Set the panel position on the form, to redraw the application
    this.panel1.Top = -this.vScrollBar1.Value;

    return;
}

The ScoreEntry form is now ready to have controls added to it. After you complete that task, you will test the scrolling features.

Adding the Dialog Controls

In this task, you will place dialog controls on the form.

To add the dialog controls

Important First ensure that you have correctly set the name properties, because these properties will be referenced later.

Press SHIFT+F7 to switch back to form design view.
Click anywhere inside the panel to select panel1.
Drop a Label control on the upper-left corner of the form.
Change its Location to 0,0.
Change the Text property to First Name, as shown in the following illustration.
Change the (Name) property to lblFirstName.
Drop a TextBox control on the form below the label.
Change its Location to 8,24.
Delete the Text property so it is blank.
Change the (Name) property to FirstName.
Drop a Label control on the upper-left corner of the form.
Change its Location to 0,56.
Change the Text property to Last Name.
Change the (Name) property to lblLastName.
Drop a TextBox control on the form below the label.
Change its Location to 8,80.
Delete the Text property so it is blank.
Change the (Name) property to LastName.
Drop a Label control on the upper-left corner of the form.
Change its Location to 0,112.
Change the Text property to Initials.
Change the (Name) property to lblInitials.
Drop a TextBox control on the form below the label.
Change its Location to 8,136.
Delete the Text property so it is blank.
Change the (Name) property to Initials.
Change the MaxLength property to 3.
Drop a Label control on the upper-left corner of the form.
Change its Location to 0,168.
Change the Text property to Snake Length.
Change the (Name) property to lblLength.
Drop a TextBox control on the form below the label.
Change its Location to 8,192.
Delete the Text property so it is blank.
Change the (Name) property to SnakeLength.
Change the Enabled property to False.
Drop a Label control on the upper-left corner of the form.
Change its Location to 0,224.
Change the Text property to Delegate ID.
Change the (Name) property to lblDelegate.
Drop a TextBox control on the form below the label.
Change its Location to 8,248.
Delete the Text property so it is blank.
Change the (Name) property to DelegateID. These steps should result in the following form design:

Setting the Tab Order

You have added all of the controls to the form. Now you need to set the tab order. Traditionally, the tab order on a form dictates which control will receive focus when a user presses the TAB key. On the Smartphone, the UP/DOWN arrow keys browse the tab order on the form. Therefore, you need to ensure that the FirstName text box is first in your tab order, followed by LastName, and so on.

To set the tab order

On the View menu, click Smartphone Tab Order, as shown in the following illustration.
Move the controls until the text box items are in the following order: FirstName, LastName, Initials, SnakeLength, DelegateID, lblDelegate, lblLength, lblInitials, lblLastName, and lblFirstName. Click OK.

Sizing the Controls for the Standard and QVGA Smartphone Screens

You need to modify the form constructor to ensure that your controls are sized correctly for the standard and Quarter Video Graphics Array (QVGA) Smartphone.

To size the controls

Press F7 to switch to code view.
Locate the following line of code in ScoreEntry.cs.
```
InitializeComponent();
```
Immediately after this line, add the following lines.
```
// Set width for panel
this.panel1.Width = this.ClientSize.Width - this.vScrollBar1.Width;
// Set width for all input controls
foreach (Control c in this.panel1.Controls) {
    if (c is Label || c is TextBox || c is CheckBox || c is ComboBox) {
       c.Width = this.ClientSize.Width-(2*c.Left)-this.vScrollBar1.Width;
    }
}
```
This step ensures that the panel fills the client width, leaving room for the vertical scroll bar. It also ensures that the panel iterates through all of the controls within the panel, sets their width, and ensures that the right and left margins are equal, as shown in the following illustration.

If you had not correctly sized the width for your controls, the form would be incorrectly displayed on a QVGA device.

Adding Events to Each Text Box

Next, you need to add events for each text box.

To add events

Press SHIFT+F7 to switch back to form design view.
In the Properties pane, click the Events icon to show a list of available events, as shown in the following illustration.
Click the FirstName text box.
In the Properties pane, double-click the GotFocus event to create a new handler.
Within this handler, add the following code to enable scrolling when the control receives focus.
```
SetScrollPosition(lblFirstName, sender);
```
Press SHIFT+F7 to switch back to form design view.
Click the LastName text box.
In the Properties pane, double-click the GotFocus event to create a new handler.
Within this handler, add the following code to enable scrolling.
```
SetScrollPosition(lblLastName, sender);
```
Press SHIFT+F7 to switch back to form design view.
Click the Initials text box.
In the Properties pane, double-click the GotFocus event to create a new handler.
Within this handler, add the following code to enable scrolling.
```
SetScrollPosition(lblInitials, sender);
```
Press SHIFT+F7 to switch back to form design view.
Click the DelegateID text box.
In the Properties window, double-click the GotFocus event to create a new handler.
Within this handler, add the following code to enable scrolling.
```
SetScrollPosition(lblDelegate, sender);
```
Note You did not create a click handler for the SnakeLength text box because it is read-only (disabled) and cannot receive focus. If you had a CheckBox control, you would pass CheckBox in to SetScrollPosition as both parameters. CheckBox does not have a label identifier; instead, the control is identified with text.

Note Because the SnakeLength text box is read-only, you need to be able to pass the final length of the snake from Form1 to the ScoreEntry form.
In ScoreEntry.cs, locate the following line.
```
public ScoreEntry()
```
Change the constructor declaration to the following.
```
public ScoreEntry(int snakeLength)
```
Within the constructor, locate the following line.
```
InitializeComponent();
```
After InitializeComponent(), add the following line.
```
this.SnakeLength.Text = snakeLength.ToString();
```
The ScoreEntry scrolling dialog is ready to be tested, but you need to display the form when the snake game ends. Remember, you added a GameFinished event in the SnakeControl project. This event was called when the game finished. Now, you will hook the client application into the event raised from the custom control.
In the Solution Explorer, double-click Form1.cs to open the original form.
Press F7 to switch to code view.

Add the following method to the Form1 class.

private void snakeControl1_GameFinished(object sender, System.EventArgs e) {
    //Do high score
    ScoreEntry sc = new ScoreEntry(this.snakeControl1.GetLength());
    sc.ShowDialog();
}

This step displays the scrolling dialog you just created.

In the constructor Form1, locate the following comment.

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

Below this comment, add the following code.

this.snakeControl1.GameFinished += new EventHandler(snakeControl1_GameFinished);

Building the Solution on Two Screen Sizes

Finally, you need to build the solution using a standard Smartphone emulator and a QVGA emulator.

To build the solution on the standard emulator

Press CTRL+SHIFT+B to build the solution.

The solution should compile without errors or warnings.
To test the application, press F5. Visual Studio .NET will present the options for deploying the application.
Select Smartphone 2003 Emulator (Virtual Radio), and then click Deploy, as shown in the following illustration.

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

If you see the screen, as shown in the following illustration, on your emulator, click the left softkey or press F1 to close the screen and continue deploying your application.
In the Smartphone 2003 emulator, wait for the application to load.
Press the left softkey or press F1 to start a game.
End the game by hitting the wall boundary or eating your own trail.
When the Snake Death screen appears, press the left softkey or press F1. The ScoreEntry screen should appear. Try scrolling by using the cursor keys, as shown in the following illustration.

	Scroll to First Name, then scroll to Initials. Notice how the scroll bar does not move position.
	However, scrolling down one more time skips the read-only Snake Length and moves to Delegate ID. Because this control fits onto the bottom of the form, the scroll bar value is maximum.
	When scrolling to Initials, because this value fits within the current scroll bar boundaries, the form does not need to scroll.
	However, when moving up to Last Name, the form needs to scroll upward just enough to display the LastName text box and the Last Name label.

Press the Cancel softkey, and then press the Done softkey to exit the application, or press SHIFT+F5 to stop debugging.

Try playing the game and using the ScoreEntry form by using the QVGA Smartphone emulator.

To build the solution on the QVGA 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 application again by using the QVGA device. Notice how the score entry form controls are sized correctly. Notice how more fields vertically fit on the screen in the QVGA resolution, as shown in the following illustration.

Part 2: Setting Smartphone Input Modes

In this part, you will learn about the different Smartphone input modes and how to set them from managed code.

Text entry does not pose a major impact when you use the emulator because you can use the keyboard on your development computer. When you try to enter data on the device, however, input modes can make a big difference. Smartphone provides three input modes for entering data by using the alphanumeric keypad:

Spell/Multitap — Requires the user to press each key multiple times. For example, for a press 2 and for b press 2 twice.
T9 — Attempts to guess the word from single keystrokes. For example, one press per target letter.

Note This mode requires much less typing than the Spell/Multitap mode.

Note This input mode is not supported on the emulator, which defaults to Spell/Multitap.
Numeric — Allows for direct mapping of numeric keys.

The .NET Compact Framework, by default, uses multitap. If the user has a search entry field, T9 may be more useful; for an order number, numeric input mode may be more useful. Note that by pressing and holding the asterisk (*) key, the user can cycle through the input modes.

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

To set input modes

On the File menu, click Add Existing Item.
Ensure that the current directory is C:\Labs\Smartphone2003\Lab2\Code. If necessary, browse to this directory, as shown in the following illustration.
Select the Smartphone.UI.cs file, and then click Open to add the file to the project. This action copies the file into your project directory.
In the Solution Explorer, double-click Smartphone.UI.cs to open the file.

This file provides the ability to set the different input modes available on the Smartphone for a control. Notice that the class uses Interop to call a few native APIs. The SetInputMode static function works by retrieving the handle for the control by using the GetCapture API call. The child window is then retrieved (if you look at a .NET Compact Framework text box using Spy, the real text box is actually a child window), and a message is sent to this child handle to set the input mode.

**Warning **The use of handles (hWnds) from within the .NET Compact Framework is unsupported and should be thoroughly tested within your application. Due to the way the runtime internally manages hWnds, the use of hWnds may not work with future releases or could break your code if you do a lot of manipulation with them.

For more information, see EM_SETINPUTMODE in Help for the Smartphone 2003 software development kit (SDK).

You will use the Smartphone.UI.cs file to set the Delegate ID entry field in the ScoreEntry form to numeric input.
In the Solution Explorer, double-click ScoreEntry.cs to open the file.
Press F7 to switch to code view.
Within the ScoreEntry constructor, locate this line.
```
this.SnakeLength.Text = snakeLength.ToString();
```

Add the following code to set the input mode for the DelegateID text box to numeric.

Microsoft.Smartphone.UI.SetInputMode(this.DelegateID, Microsoft.Smartphone.InputMode.Numbers);

To build the solution

Press CTRL+SHIFT+B to build the solution.

The solution should compile without errors or warnings.
To test the application, press F5.
Visual Studio .NET presents the options for deploying the application.
Select Smartphone 2003 Emulator (Virtual Radio) or WWE SP 2003 SE QVGA (Virtual Radio) – SDK Emulator, and then click Deploy, as shown in the following illustration.
In the emulator, wait for the application to load.
Press the left softkey or press F1 to start a game.
End the game by hitting the wall boundary or eating your own trail.
When the Snake Death screen appears, press the left softkey or press F1. The ScoreEntry screen appears.
Using the emulator's keypad, enter 123 into the Initials and Delegate ID fields, as shown in the following illustration. The Initials field reacts like MultiTap, whereas the Delegate ID field has a direct numeric mapping. The input mode is displayed in the upper-right corner of the window as either abc, 123, or t9. The emulator does not support T9 input.
Use the softkeys to quit the game and end debugging.

Part 3: Consuming a Web Service

In this part, you will consume a Web service to upload the high-score data captured on the Score Entry form.

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

A Web reference has been created for this exercise, which you will target in the following steps.

To add the Web reference

On the Project menu, click Add Web Reference, as shown in the following illustration.
In the Add Web Reference dialog box, type https://mobile.msdevtools.net/SnakeScores/default.asmx in the URL box, and then click Go.
In the Web reference name box, change the Web reference name to ScoreService, as shown in the following illustration.
Click Add Reference.

Visual Studio .NET generates the relevant proxy class to invoke the Web service.

To call the Web service

In the Solution Explorer, double-click ScoreEntry.cs to open the file.
Press F7 to switch to code view.

Within the ScoreEntry constructor, locate the line.

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

Add the following code to the function. (Because the code is quite long, do a cut-and-paste operation to copy this code into the code editor.)

// Create the WS Proxy Class
ScoreService.Scores service = new ScoreService.Scores();
try {
    // Set wait cursor
    Cursor.Current = Cursors.WaitCursor;

    // Upload scores
    service.SetScore(this.FirstName.Text, 
        this.LastName.Text, 
        this.Initials.Text,
        Convert.ToInt32(this.SnakeLength.Text),
        this.DelegateID.Text);
    Cursor.Current = Cursors.Default;
    MessageBox.Show("Score Uploaded", "Upload Done", MessageBoxButtons.OK, MessageBoxIcon.Asterisk, MessageBoxDefaultButton.Button1);

}
catch (Exception ex) {
    // Display error and close form
    Cursor.Current = Cursors.Default;
    MessageBox.Show(ex.Message, "Upload Err", MessageBoxButtons.OK, MessageBoxIcon.Exclamation, MessageBoxDefaultButton.Button1);
    this.Close();
}
finally {
    Cursor.Current = Cursors.Default;
}

// Close the form
this.Close();

Note You are setting the URL property of the service object to a different endpoint. If you used the default value, which was localhost, the device would attempt to find the Web service on the device.

Consuming Web services by using the .NET Compact Framework is the same as consuming them by using desktop managed code. There are limitations, however — for example, no support exists for typed DataSets. If your Web service returns a typed DataSet, you must expose an extra Web method that casts and returns it to an untyped DataSet. For more information, see the Visual Studio .NET documentation.

To build the solution

Press CTRL+SHIFT+B to build the solution. The solution should compile without errors or warnings.

You can now test the Web service functionality.
To test the application, press F5.
Visual Studio .NET presents the options for deploying the application.
Select Smartphone 2003 Emulator (Virtual Radio) or WWE SP 2003 SE QVGA (Virtual Radio) – SDK Emulator, and then click Deploy, as shown in the following illustration.
Wait for the application to load in the Smartphone 2003 emulator.
Press the left softkey or press F1 to start a game.
When the game finishes, press the left softkey or press F1 to open the High Scores entry form.
Type your information, and then press the left softkey or press F1 to upload your data to the Web service.
Move the pointer over the emulator screen. Notice that the pointer changes to a wait cursor. If your application is performing a lengthy task, it is good practice to show a wait cursor until the task is complete. When the task is complete, a message displays, as shown in the following illustration.
Press the OK softkey, and then press the Done softkey to exit the application, or press SHIFT+F5 to stop debugging.

Congratulations! You have now completed this exercise.

Summary

In this exercise, you used Visual Studio .NET to design a form for the Smartphone that implemented scrolling in the same style as a native application. In this exercise, you performed the following:

Set up a new form for scrolling Placed controls within a panel.
Set Smartphone input modes.
Consumed a Web service.

Appendix A: Using .NET Compact Framework Version 1.0 SP2

If your computer has .NET Compact Framework version 1.0 SP2 installed and you have not updated the netcf.core.ppc3.ARM.cab and netcf.core.ppc3.x86.cab files in .NET Compact Framework version 1.0, you need to update these files prior to beginning this exercise. The installation of SP2 does not automatically update these .cab files for you.

Open two instances of My Computer.
In the first instance, browse to C:\Program Files\Microsoft Visual Studio .NET 2003\CompactFrameworkSDK\v1.0.5000\Windows CE\wce300\arm.
In the second instance, navigate to C:\Program Files\Microsoft .NET Compact Framework 1.0 SP2.
Copy the netcf.core.ppc3.ARM.cab file from the second instance and paste it into the first instance.
Click Yes to replace the existing file.
Change the path of the first instance of My Computer to C:\Program Files\Microsoft Visual Studio .NET 2003\CompactFrameworkSDK\v1.0.5000\Windows CE\wce300\x86.
In the second instance, copy the netcf.core.ppc3.x86.cab file, and then paste it into the first instance.
Click Yes to replace the existing file.

Step by Step: Implement Smartphone-Style Scrolling Data Entry Dialogs by Using the .NET Compact Framework on Smartphone

Contents

To complete this exercise, you will need:

Part 1: Setting Up a New Form for Scrolling

Creating a New Form for Scrolling

Adding the Dialog Controls

Setting the Tab Order

Sizing the Controls for the Standard and QVGA Smartphone Screens

Adding Events to Each Text Box

Building the Solution on Two Screen Sizes

Part 2: Setting Smartphone Input Modes

Part 3: Consuming a Web Service

Summary

Appendix A: Using .NET Compact Framework Version 1.0 SP2

Additional resources