Create a Custom Home Screen

  • Article

Windows Mobile SupportedWindows Embedded CE Not Supported

8/28/2008

This code sample is named Homescreen. It demonstrates how to create a Home-Screen plug-in and custom Home-Screen layout for Windows Mobile 6 Standard.

Feature Area

Relevant APIs

Sequence of Events

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

Usage

To run the code sample

  1. 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 Mobile 6 SDK\Samples\Smartphone\cpp\Win32\HomeScreen

    Microsoft Visual Studio 2005 launches and loads the solution.

  2. Build the solution (Ctrl+Shift+B).

  3. Deploy the solution (F5).

If you have not installed the SampleUnprivDeveloper 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

  1. Click Start > Run.

  2. Type the path-name to SampleUnprivDeveloper.pfx certificate, and click OK. By default, this is located in the following folder:

    C:\Program Files\Windows Mobile 6 SDK\Tools\Security\SDK Development Certificates

  3. Double-click the SampleUnprivDeveloper.pfx certificate icon. The Certificate Import Wizard appears.

  4. Click Next. The certificate path-name is filled-in.

  5. Click Next.

  6. Click Next (you do not need a password).

  7. Click Next. Accept the default options; automatically select the certificate store based on certificate type.

  8. 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) Home Screen plug-ins 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 plug-in is initially loaded by the plug-in manager. This keeps home.exe (which loads the plug-in on boot-up) from having to parse XML, which would dramatically increase boot time. To debug a plug-in at runtime, you must attach the debugger to the home.exe process. Here are the details:

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

To debug this project

  1. Make sure that you have a Debug Version of the plug-in installed and working on an attached Windows Mobile 6 Standard or Windows Mobile 6 Standard emulator.

  2. Load the project in Visual Studio 2005.

  3. Click Tools > Attach to Process.

  4. Choose Smart Device in the list of Transports.

  5. Select or browse for the device that you are working with. A Process list appears.

  6. Attach to the home.exe process.

  7. Switch to the Debug tab in the Output window to see debugging messages.

  8. 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

  1. From the Settings menu, select "Home Screen".

  2. Select Memplug from the drop-down list-box at the top of the screen.

  3. Select Done to return to the Settings Screen.

  4. 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 plug-ins, and a new plug-in 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 plug-in (memplug.cpp) is implemented as a COM object that supports IHomePlugin, in addition to the standard factory and class object interfaces. The Plug-in Manager does one-time initialization of the plug-in 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 plug-in is released.

Development Environments

SDK: Windows Mobile 6 Standard SDK 

Development Environment: Visual Studio 2005.

ActiveSync: Version 4.5.

See Also

Concepts

Code Samples for Windows Mobile

Other Resources

Shell, GWES, and User Interface
QVGA Home Screen
IHomePluginEnvironment2