Share via

Add a Battery Status Settings Application to the Application Launcher (Compact 7)

  • Article

3/12/2014

The sample home screen provides, by default, a widget that displays the battery status of your device. For example, the battery status widget can indicate power status to the user by displaying the percentage of remaining battery power.

By default, the battery status widget on the main page does not open a settings application when a user clicks it. However, you can create a battery status settings application, so the user can configure settings such as the power management plan, the brightness of the backlight, or the timeout period before a device shuts off due to inactivity.

To implement a battery settings application, you must:

  1. Create an application that provides the UI for users to view and configure power settings.
  2. Provide the functionality that monitors battery power and updates the battery widget’s UI.
  3. Provide the functionality that connects the battery widget to the application.

Prerequisites

To complete the tasks to implement a battery status settings application, you must first have an OS design that includes an application launcher. For more information, see Create and Prepare the OS Design and Application Launcher Project.

Create the Settings Application

You can create a custom settings application that opens when the user clicks the battery status widget in the status bar of a sample home screen. For information about creating Microsoft Silverlight for Windows Embedded applications, see Getting Started with Silverlight for Windows Embedded.

Configure the Battery Status Widget

Configure the battery status widget so that it monitors battery power status when XRShell.exe is loaded and so the battery settings application opens when a user clicks the widget.

For an example of a status widget implementation, see the source code for the volume status widget, located at %_WINCEROOT%\Public\Shell\Oak\XRShell\Controls\Volume\Status_itemvolume.cpp.

To implement code for the battery status widget

  1. In %_WINCEROOT%\Public\Shell\Oak\XRShell\Controls\Power, implement a C++ class for the battery status widget. For an example of how to implement it, you can refer to the Status_ItemVolume class implemented in %_WINCEROOT%\public\shell\oak\XRShell\controls\volume\Status_itemvolume.cpp.

  2. In the C++ class that you created for the battery status widget, provide a custom implementation for the following methods:

    • OnClick method
      Your method implementation of OnClick must handle the Click event, which occurs when the user clicks the battery status widget. In the method implementation, when the user clicks the widget, the .exe for the battery status settings application runs and the user sees the values for the various types of battery power consumption.
    • Start method
      This method starts the widget when the main page of the home screen starts. In your method implementation, you can add code to start monitoring the status of a setting, such as the brightness of the backlight. Then, you can use status monitoring information to update the UI of the status widget to communicate the status of a setting. For example, the battery UI could display an updated percentage value to indicate current power status or display the level of the brightness of the backlight.
    • Stop method
      This method stops the status widget. In your method implementation, you can add code to stop monitoring the status of a setting in order to minimize memory and CPU usage when the application launcher exits.

    You can also implement the following optional method:

    • OnLoaded method
      In your method implementation, you can add code that indicates how you want the status widget to respond to user interaction. For example, if it is a button, you can attach an OnClick event handler to the button object.

Connect the Application to the Widget

After you implement the code for the battery status widget, you must connect the application to the widget’s Click event so the application opens when the user clicks the widget.

To connect the settings application to the battery widget

  1. Create a GUID for the .exe file for the settings application. You can use the Guidgen Tool to create the GUID.

  2. Add a registry subkey that has the GUID for your settings application, and add registry settings for your settings application. For more information, see "Executable Control Panel Registry Settings" in Control Panel Registry Settings.

  3. Open Status_itempower.cpp, located in %_WINCEROOT%\Public\Shell\Oak\XRShell\Controls\Power\Status_itempower.cpp.

  4. Locate the LaunchApplication function call, in Status_ItemPower::OnClick event handler.

    CHR( m_pShell->LaunchApplication(L"\\windows\\CtlPnl2.exe", 
                                      L"", &AppHandle, &AppID) );

  5. Set the value of the second parameter of LaunchApplication to a string that contains the GUID that you created.

Next Steps

Continue to customize your application launcher as you like by using the procedures in this section. After you complete your customizations, you can use the procedures in Build and Run the Application Launcher to rebuild the theme DLL by using the Command Prompt window in Visual Studio before you rebuild your run-time image.

See Also

Concepts

Create an Application Launcher in Silverlight for Windows Embedded