Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
4/8/2010

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

Feature Area

Relevant APIs

Sequence of Events

  1. Home.exeloads the IHomePluginobject, and loads the custom configuration information from the intermediate file via the plug-in's IPersistStreaminterface.

  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.5.3 DTK\Samples\Smartphone\cpp\Win32\HomeScreen

    Microsoft Visual Studio launches and loads the solution.

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

  3. Deploy the solution (F5).

If you have not installed the SampleUnprivDevelopercertificate, 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.pfxcertificate, and click OK. By default, this is located in the following folder:

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

  3. Double-click the SampleUnprivDeveloper.pfxcertificate 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 Modelfor 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 Standard or Windows Mobile Standard emulator.

  2. Load the project in Visual Studio.

  3. Click Tools> Attach to Process.

  4. Choose Smart Devicein 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.exeprocess.

  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 Memplugfrom the drop-down list-box at the top of the screen.

  3. Select Doneto 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 Commondirectory. 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::Initializemethod, 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 Standard SDK 

Development Environment:Visual Studio 2005 or 2008.

ActiveSync:Version 4.5.

See Also