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
 
  1. Open a text editor, such as NotePad, and paste the following XML code into the text editor:
 
<?xml version="1.0" encoding="utf-8"?>
<!--
Copyright (c) Microsoft Corporation.  All rights reserved.
-->
<!--
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.
-->
 
<XRShellShortcut>
 
  <Name _locId="IDName">Shortcut_Name</Name>
  <Description _locId="IDDescription">Shortcut_Description</Description>
  <Target>\Windows\application.exe</Target>
  <Args></Args>
  <Icon>
    <![CDATA[
            <Path xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" Data="F1M168.556,119.535L168.804,120.336C169.268,122.352,169.536,124.303,169.571,126.264L169.519,127.503 167.379,131.946C164.669,136.934,161.492,141.63,157.905,145.976L153,151.373 153,148.227 153,145.433 154.819,143.432C159.954,137.209,164.211,130.234,167.399,122.697z M153,101.029C153,101.029,163.571,105.171,166.857,114.028L167.569,116.336 165.53,121.907C162.419,129.262,158.265,136.069,153.254,142.142L153,142.421 153,130.948C153,115.406,153,101.029,153,101.029z M90,77.5C83.096,77.5 77.5,83.096 77.5,90 77.5,96.904 83.096,102.5 90,102.5 96.904,102.5 102.5,96.904 102.5,90 102.5,83.096 96.904,77.5 90,77.5z M90,76C97.732,76 104,82.268 104,90 104,97.732 97.732,104 90,104 82.268,104 76,97.732 76,90 76,82.268 82.268,76 90,76z M90,73.996C81.161,73.996 73.996,81.161 73.996,90 73.996,98.839 81.161,106.004 90,106.004 98.839,106.004 106.004,98.839 106.004,90 106.004,81.161 98.839,73.996 90,73.996z M145.118,63.013C145.118,63.013 148.096,63.013 148.096,63.013 148.929,68.966 149.048,76.47 155.241,83.973 160.004,89.689 165.364,94.809 169.056,99.453 173.938,105.528 177.391,113.15 177.391,120.891 177.391,133.277 171.438,145.541 167.387,152.33 167.387,152.33 165.482,152.33 165.482,152.33 168.341,145.9 174.057,135.3 173.579,123.988 173.342,117.676 170.96,110.887 166.912,105.886 162.386,100.05 154.763,95.405 148.096,94.93 148.096,94.93 148.096,162.453 148.096,162.453 148.096,167.813 144.88,172.695 140.236,176.268 135.71,179.84 129.754,181.984 124.516,181.984 121.18,181.984 118.083,180.913 115.941,179.125 113.678,177.339 112.368,174.72 112.368,171.624 112.368,166.742 115.702,161.857 120.228,158.286 124.754,154.593 130.469,152.212 135.233,152.212 139.402,152.212 142.974,152.808 145.118,154.831 145.118,154.831 145.118,63.013 145.118,63.013z M90,61.988C105.47,61.988 118.012,74.53 118.012,90 118.012,105.47 105.47,118.012 90,118.012 74.53,118.012 61.988,105.47 61.988,90 61.988,74.53 74.53,61.988 90,61.988z M90,60C73.431,60 60,73.431 60,90 60,106.569 73.431,120 90,120 106.569,120 120,106.569 120,90 120,73.431 106.569,60 90,60z M90,8.028C135.272,8.028,171.972,44.728,171.972,90L171.671,95.963 167.342,91.008C163.169,86.436 159.143,82.186 157,78.686 154.091,73.934 151.429,59 151.429,59 151.429,59 140.964,59 140.964,59 140.964,59 140.964,148.714 140.964,148.714 140.964,148.714 133.286,146.571 125.714,150 118.143,153.429 110.398,158.075 108.429,167.857L108.183,169.879 106.52,170.307C101.184,171.399 95.659,171.972 90,171.972 50.387,171.972 17.337,143.874 9.693,106.52L9.461,105 10.226,105C16.781,105 43,105 43,105 51.284,105 58,98.284 58,90 58,81.716 51.284,75 43,75 43,75 16.781,75 10.226,75L9.461,75 9.693,73.48C17.337,36.126,50.387,8.028,90,8.028z M90,2C138.601,2 178,41.399 178,90 178,93.038 177.846,96.039 177.546,98.997L176.97,102.772 176.25,101.655 173.587,98.171 174,90C174,43.608 136.392,6 90,6 43.608,6 6,43.608 6,90 6,136.392 43.608,174 90,174 95.799,174 101.461,173.412 106.929,172.293L108.084,171.996 108.171,174.076 108.593,175.991 107.735,176.212C102.006,177.384 96.075,178 90,178 41.399,178 2,138.601 2,90 2,41.399 41.399,2 90,2z" UseLayoutRounding="False" Stretch="Fill" Margin="4,0" >
                <Path.Fill>
                    <LinearGradientBrush EndPoint="0.5,1" StartPoint="0.5,0">
                        <GradientStop Color="White" Offset="0"/>
                        <GradientStop Color="#4CFFFFFF" Offset="1"/>
                    </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.
 
  1. In the <Name> element, change Shortcut_Name to the name of the shortcut for your application.
 
  1. In the <Description> element, change Shortcut_Description to the description of your application.

 

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

 

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

 

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

 

  1. In main_default.xml, add the following code:
 
<!--
; @CESYSGEN IF IE7_MODULES_IEEXR_MEDSCR
-->
<Item Widget="Main_Item">
        <File>Custom_Application.xrsl</File>
    </Item>
<!--
; @CESYSGEN ENDIF
-->
 
  1. 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
 
  1. Open shell.dat, located in %_WINCEROOT%\PUBLIC\SHELL\OAK\FILES.
 
  1. In the shell.dat file, locate the section titled: “Shortcuts for binaries built before shell in _DEPTREES, should be added here.”

 

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