Programming Navigation Controls

In most respects, programming a navigation control is identical to programming any other Windows input device; that is, your application captures messages and acts on them in the WndProc function. However, Windows CE for a Palm-size PC implements a specific messaging style that you need to be aware of in order to write applications efficiently.

Navigation controls communicate with the Windows CE operating system by sending messages. An OEM provides the driver that links each navigation control with WM_KEYUP and WM_KEYDOWN messages individually or in a series. Each message has a virtual key message in its wParam parameter. A user activates the driver when he or she presses a navigation control. The driver then sends the window messages to the Palm-size PC shell. The shell passes the messages to the current application. The following table shows a sample message map. The messages for each operation on a control are sent in the order shown. This sample may not be consistent with the driver installed on your target device.

Keep the following information in mind when programming an application with a message map similar to the previous sample:

• The Action and Exit controls do not send VK_RETURN and VK_EXIT messages until the user releases the control. This makes chording easier. For more information on chording, see Programming Chords.
• The ArrowUp and ArrowDown controls each send a pair of WM_KEYDOWN and WM_KEYUP messages when held down. The driver continues sending these pairs for each auto-repeat, until the user releases the control.
• The lParam message associated with a program control message is VK_LWIN, which toggles the shell between routing messages to the application and routing messages to the shell itself. When the shell receives a VK_LWIN message, it uses the lParam value of the next message to look up a key in the registry. In the previous example, the Prog1 control is associated with the \HKEY_LOCAL_MACHINES\Software\Microsoft\Shell\Keys\40C1 subkey. App2 is associated with the \HKEY_LOCAL_MACHINES\Software\Microsoft\Shell\Keys\40C2 subkey, and so on. Each Program control key has several subkeys. The default value of the subkey is an application name and command line. The shell uses this value to launch the application. The following table shows the other optional subkeys. After the shell launches the application, the next VK_LWIN message toggles the shell to routing messages to the application again.

On a Palm-size PC, a user can access the Button Properties dialog to associate a program control with any application that is accessible through the Start menu or its Program submenu. When the user changes a control, the operating system sends out a WM_WININICHANGE message to all active applications. This message informs the applications that the hardware control map has been changed.

The Palm-size PC shell adds a layer of indirection between the hardware driver and your application, which may slow your application down. To increase the speed of your application, you can send the VK_* messages directly to your application. This includes the VK_LWIN messages from a program control.

    To send navigation messages to your application

1. Call the SHGetAppKeyAssoc function.

   If there is a valid VK code associated with the navigation control, this function will return that key code to your application.

2. Call the RegisterHotKey function.

   This registers your application to receive messages when the user presses a navigation control.

Note The shell does not automatically launch your application if you send navigation messages directly to your application.

You can also alter the application that a program control launches by directly modifying the registry key of that program control. If you do alter the registry of a program control, you may have difficulties with the RegisterHotKey function. Because HotKeys are sent directly to the application without first passing through the shell, the shell will not notice your change. To avoid this problem, ask the user to change the associated program of the program control from the Button Properties dialog box. Optionally, you can change the registry value, and then ask the user to reboot.

When you program a navigation control, follow these guidelines:

• Use the arrow controls for viewing data, but not for changing it. An application should have its navigation controls associated with the data view controls.
• Have your application automatically place its focus in the data view controls when you receive data from a database. This lets the user quickly move through and find necessary information.
• Be sure that the content of a software control does not change when a user moves between other software controls.
• Keep the focus and default focus the same as much as possible. This allows an action control to activate the software control that currently has the focus.
• Use the press-and-hold feature of a program control to create a new document. This process is similar to selecting New from the File menu on a desktop computer.

    To program a press-and-hold feature for a program control

1. Call the SHGetAppKeyAssoc function in the beginning of your application.

   The shell launches your application in response to a user pressing the associated program control. SHGetAppKeyAssoc returns the valid VK code of that program control.

2. Set a timer in your application to the amount of time you want a user to hold down the control. In general, this should be no longer than one second.
3. When the timer expires, call GetAsyncKeyState using the VK message received from SHGetKeyAssoc.

   If GetAsyncKeyState returns a VK_DOWN message, then the program control was held the entire time.

For more information about VK mapping, consult the documentation for the device driver available from the manufacturer of your target device.