Windows Embedded Compact: Customizing the Sample Home Screen

Article
1/17/2024

Add an Application Shortcut to the Sample Home Screen

You can add an application shortcut to the menu in the sample home screen in Windows Embedded Compact. Then, a user can click the shortcut to start your application. The application must be based on Silverlight for Windows Embedded.

After you add an application shortcut using these instructions, users can view and select your application in the main menu of the sample home screen.

To build a run-time image that uses the sample home screen, do one of the following:

Include the Silverlight for Embedded based Sample Home Screen catalog item (SYSGEN_XRSHELL) in your Windows Embedded Compact OS design.
Create an OS design by using the Embedded Device with Silverlight [[XAML]] design template.

To add an application shortcut to the sample home screen

Open a text editor, such as NotePad, and paste the following XML code into the text editor:

<?xml version="1.0" encoding="utf-8"?>

<!--

-->

<!--

Use of this sample source code is subject to the terms of the Microsoft

license agreement under which you licensed this sample source code. If

you did not accept the terms of the license agreement, you are not

authorized to use this sample source code. For the terms of the license,

please see the license agreement between you and Microsoft or, if applicable,

see the LICENSE.RTF on your install media or the root of your tools installation.

THE SAMPLE SOURCE CODE IS PROVIDED "AS IS", WITH NO WARRANTIES OR INDEMNITIES.

-->

<Name _locId="IDName">Shortcut_Name</Name>

<Description _locId="IDDescription">Shortcut_Description</Description>

<Target>\Windows\application.exe</Target>

<Icon>

<![CDATA[

<Path.Fill>

</LinearGradientBrush>

</Path.Fill>

</Path>

]]>

</Icon>

</XRShellShortcut>

Note: In the <Icon> element of the XML code, the CDATA section contains a Silverlight XAML Path element that represents the icon to use for the application shortcut.

In the <Name> element, change Shortcut_Name to the name of the shortcut for your application.

In the <Description> element, change Shortcut_Description to the description of your application.

In the <Target> element, change application.exe to the name of the .exe for your application.

Save the file as an .xrsl file. For example, save the file as Custom_Application.xrsl.

Open main_default.xml, located in %_WINCEROOT%\PUBLIC\SHELL\OAK\XRSHELL\SRC.

In main_default.xml, add the following code:

<!--

; @CESYSGEN IF IE7_MODULES_IEEXR_MEDSCR

-->

<File>Custom_Application.xrsl</File>

</Item>

<!--

; @CESYSGEN ENDIF

-->

In the FILES list of the shell.bib file, add an entry for the .xrsl file. If the shortcut should only appear if a specific SYSGEN or component is included in the run-time image, put the entry inside a Cesysgen conditional statement. For example:

; @CESYSGEN IF MEDIAAPPS_MODULES_MMPLAYER

Custom_Application.xrsl $(_FLATRELEASEDIR)\Custom_Application.xrsl NK SH

; @CESYSGEN ENDIF

Open shell.dat, located in %_WINCEROOT%\PUBLIC\SHELL\OAK\FILES.

In the shell.dat file, locate the section titled: “Shortcuts for binaries built before shell in _DEPTREES, should be added here.”

Add an entry for the shortcut under that section. If the shortcut should only appear if a specific SYSGEN or component is included in the run-time image, put the entry inside a Cesysgen conditional statement. For example:

; @CESYSGEN IF MEDIAAPPS_MODULES_MMPLAYER

Directory("\XRShell\_Storage\Main"):-File("Custom_Application.xrsl", "\windows\Custom_Application.xrsl")

; @CESYSGEN ENDIF

Rebuild the run-time image.

The next time you download the run-time image to your hardware board or Virtual CEPC, the application shortcut will be included in the menu in the sample home screen.

Customize the appearance of the main menu or settings menu

You can configure the menu to display only the icon for each item, without a menu item name or description text. However, if you don't provide a text string for the Name or Description element in the .xrsl file, the menu item will display the default text from the source XAML file.

Therefore, to create menu items that are icons without showing default text, you must set a Text attribute for the Description and Name elements. The Text attribute must be set to an empty string with a single space. For example:

<Description_locId="IDName"Text=" "/>

To change the order of menu items in the sample home screen, re-order the menu items in the following files:
- For the menu items in the main page, re-order elements in %_WINCEROOT%\PUBLIC\SHELL\OAK\XRSHELL\SRC\Main_Default.xml.
- For the menu items in the settings page, re-order elements in %_WINCEROOT%\PUBLIC\SHELL\OAK\XRSHELL\SRC\Setting_Default.xml.

Elements that are defined closer to the beginning of the XAML file appear first in the menu, and elements that are defined toward the end of the XAML file appear last in the menu.

Customizing Widgets

A widget is an icon that appears in the notification area on the home screen which the user clicks to view or adjust settings for the device. The sample home screen provides five widgets: clock, Wi-Fi status, Bluetooth status, power (battery) status, Bluetooth wireless technology status, and volume status.

Attaching a custom settings application to the power (battery) status widget

For the power (battery) status widget, you must create a power management settings application that reflects the power states and battery power solution that you implemented. Then, you must attach it to the power (battery) status widget so that it appears when the user clicks the power (battery) status widget. Windows Embedded Compact 7 does not include a default power (battery) XAML control panel.

After you create a power management control panel application that is based on Silverlight XAML, you must modify the call to the LaunchApplication function in the source code for the widget’s OnClick event handler in %_WINCEROOT%\public\shell\oak\xrshell\controls\power\status_itempower.cpp.

· To launch your application when the user clicks the power (battery) widget, set the second parameter of LaunchApplication to a string that contains the GUID for your control panel application.

· The source code for the OnClick event handler is as follows:

HRESULT Status_ItemPower::OnClick(__in IXRDependencyObject* pSender, __in XRMouseButtonEventArgs* pArgs)

{

MFUNCENTRY(ZONE_XRS_FUNCENTRY, (L""));

HRESULT hr = E_FAIL;

HANDLE AppHandle = NULL;

DWORD AppID = 0;

CPR(pSender);

CPR(pArgs);

CHR( m_pShell->LaunchApplication(L"\windows\CtlPnl2.exe",

L"", &AppHandle, &AppID) );

hr = S_OK;

Error:

return hr;

}

** Writing a custom status widget**

To write a custom status widget that launches a settings application, see the volume status widget source code at %_WINCEROOT%\PUBLIC\SHELL\OAK\XRSHELL\CONTROLS\VOLUTME\Status_item_volume.cpp for an example.

The important APIs for implementing custom status widgets are as follows:
- OnClick() function – Handles the Click event, which occurs when the user clicks the status widget. In the event handler implementation, you can launch additional functionality for configuring settings or details of the status widget (for example, you can launch a control panel application or settings UI by calling LaunchApplication).

- Start() function– Starts the widget. In the function implementation, you can add code to start activity to monitor status of a setting. For example, you can use status monitoring information to update the UI of the status widget to communicate status of its setting.

- Stop() function – Stops the widget. In the function implementation, you can add code to stop activity to monitor status of a setting, because the shell is being closed and you should minimize memory and CPU usage.

Status widgets on the sample home screen are controlled by three functions:
- InitializeFromXmlReader() – Creates the object and initializes it by using the XML Reader. See source code in %_WINCEROOT\PUBLIC\SHELL\OAK\XRSHELL\INC\launch_item.cpp.

- OnLoaded() – You can add custom code in the function implementation for a custom widget that indicates how you want the control to respond to user interaction, for example if it is a button, you can add an OnClick event handler. Each status widget in the sample home screen implements OnLoaded.

- Setup() – Initializes each widget. For an example of calling this function, see shellwidgetmanager.cpp in %_WINCEROOT\public\shell\oak\xrshell\src\shellwidgetmanager.cpp. If the user wants to implement a custom setup solution for a widget, you must initialize the widget object similarly to the code in the ShellWidgetManager::InitAll function.

Share via

Windows Embedded Compact: Customizing the Sample Home Screen

Additional resources