Create a Custom Home Screen

Article
08/28/2006

This code sample is named Homescreen. It demonstrates how to create a home-screen plugin and custom home-screen layout for the Smartphone.

Feature Area

Relevant APIs

Sequence of Events

Home.exe loads the IHomePlugin object, and loads the custom configuration information from the intermediate file via the plugin's IPersistStream:IPersist interface.
The user returns to the Home Screen.
The new layout is drawn, and the plugin responds to a number of system and User Interface (UI) messages.
The user can select the plugin (a status bar indicating percentage of remaining system memory), and a dialog box appears with more detailed information.

Usage

To run the code sample

Navigate to the solution file (*.sln), and double-click it. By default, the solution file is copied to the following folder:

C:\Program Files\Windows CE Tools\wce500\Windows Mobile 5.0 Smartphone SDK\Samples\CPP\Win32\Homescreen\HomeScreen.sln

Microsoft Visual Studio 2005 launches and loads the solution.
Build the solution (Ctrl+Shift+B).
Deploy the solution (F5).

If you have not installed the SDKSampleUnprivDeveloper certificate, you will need to so that your DLL and CAB projects are signed correctly.

To install the SDK Sample Standard Developer Certificate from the Windows Desktop

Click Start > Run.
Type the path-name to SDKSampleUnprivDeveloper.pfx certificate, and click OK. By default, this is located in the following folder:
```
C:\Program Files\Windows CE Tools\wce500\Windows Mobile 5.0 Pocket PC SDK\Tools\
```
Double-click the SDKSampleUnprivDeveloper.pfx certificate icon. The Certificate Import Wizard appears.
Click Next. The certificate path-name is filled-in.
Click Next.
Click Next (you do not need a password).
Click Next. Accept the default options; automatically select the certificate store based on certificate type.
9. Click Finish.

See Mobile device Security Model for further details on how to install the SDK certificates onto the mobile device, and how to use the privileged SDK certificate to sign this application.

Developing (and particularly debugging) Homescreen plugins can be tricky because of the complex way in which they are loaded and configured. To keep CPU-heavy XML parsing to a minimum on resource-limited devices, such parsing occurs only when the plugin is initially loaded by the plugin manager. This keeps home.exe (which loads the plugin on boot-up) from having to parse XML, which would dramatically increase boot time. To debug a plugin at runtime, you must attach the debugger to the home.exe process. Here are the details:

Debugging a Home Screen Plugin at Runtime can be a bit tricky, because the plugin is already loaded when you want to debug. You must attach to the *home.*exe process.

To debug this project

Make sure that you have a Debug Version of the plugin installed and working on an attached Smartphone or Smartphone emulator.
Load the project in Visual Studio 2005.
Click Tools > Attach to Process.
Choose Smart Device in the list of Transports.
Select or browse for the device that you are working with. A Process list appears.
Attach to the home.exe process.
Switch to the Debug tab in the Output window to see debugging messages.
Open the source file you want to debug, and set a break point in it, such as on IHomePlugin::OnEvent. When you trigger that event, the breakpoint is reached, and you will be able to debug normally.

To use the application

From the Settings menu, select "Home Screen".
Select Memplug from the drop-down list-box at the top of the screen.
Select Done to return to the Settings Screen.
From there, return to the Home screen. You will see a new Home Screen with the memory usage status bar. The text above it is specified in the layout XML. You can change it by modifying the XML and restarting the device.

Remarks

This code sample runs as an standard API. Applications that use it must be signed with an standard certificate.

The layout consists of standard plugins, and a new plugin that displays information about available memory. The layout is specified in an XML file that is found in the Common directory. The included memory status plugin (memplug.cpp) is implemented as a COM object that supports IHomePlugin, in addition to the standard factory and class object interfaces. The Plugin Manager does one-time initialization of the plugin via its IHomePlugin::Initialize method, using the custom configuration information specified in the layout XML. Configuration information is saved to an intermediate file (via IPersistStream::Save) and the plugin is released.

Requirements

Smartphone SDK: Windows Mobile 5.0 Smartphone SDK.
Development Environment: Visual Studio 2005.
ActiveSync: Version 4.0.