Create Functionality for Users to Switch the Theme (Compact 2013)
10/26/2015
Users can personalize their device by switching among home screen themes when you provide that capability.
Implementing theme switching is an advanced programming task. Instead of selecting one preliminary theme for your XAML for Windows Embedded application launcher, as you did in Create and Prepare the OS Design and Application Launcher Project, you select all four preliminary themes for a display screen size and then edit all four XAML projects to customize the themes.
So users can switch among the themes, you create a settings application that accesses the registry to switch the theme at runtime.
Note
To save registry changes after a device is rebooted, the OS design must support a hive-based registry (SYSGEN_FSREGHIVE), which provides persistent storage.
Prerequisites
You must have an OS design that includes an application launcher with all four themes to complete the following procedures. For more information, see Create and Prepare the OS Design and Application Launcher Project
Determine the Correct Theme Registry Values for Your Code
After you have added all four preliminary designs to your OS design, built the image, and edited the XAML projects to customize the designs to your liking, you must determine which registry values to use in your C++ code.
The registry key for the sample home screen’s theme is HKEY_CURRENT_USER\Software\Microsoft\XRShell\Settings\Theme. Its value is set during the build process. However, you can change its value in C++ code.
To determine registry values for each XAML project
- Use the following syntax:
<Display_Screen_Size>_Theme<Theme_Number>
Note
The Default Theme theme number is 0.
Implement Theme Switching
You can implement theme switching to let a user change the theme for the XAML for Windows Embedded application launcher on a device.
To create a theme settings application
In Microsoft Visual Studio 2013 or Microsoft Visual Studio 2015, open the OS design that you created in Create an OS Design That Uses the Preliminary Theme and Display Screen Size.
Create a theme settings application by using Windows Embedded XAML Tools. For more information, see Getting Started with XAML for Windows Embedded.
In your settings application, use Blend for Visual Studio to design a UI that users use to select a theme. For an example, see the Personalization item in Control Panel in Windows 7.
To write an event handler to change the theme registry value
In your settings application, identify a UI element, such as a button, that raises an event that will switch the theme.
In Visual Studio, in Solution Explorer, expand the Subproject name, expand Resource files, and double-click MainPage.xaml.
On the View menu, point to Other Windows, and then click Windows Embedded Events.
In Windows Embedded Events, click the name of the UI element.
In the Name column, identify the event that you want to handle.
In the Handler column, double-click the field corresponding to the event.
In MainPage.cpp, write code that obtains user input and updates the registry by calling the function RegSetValueEx and RegFlushKey. In your registry code, use the registry values that you identified in Determine the Correct Theme Registry Values for Your Code above.
Use the MessageBox function to inform the user that the device must be reset to apply the new theme settings.
Build the application. In Solution Explorer, right-click the subproject, and then click Build.
To help ensure that updates to registry files are preserved after you reset the device, adjust the preconfigured connection as follows:
- On the Target Menu, click Connectivity Options.
- Select the virtual CEPC device that you configured, and then click Core Service Settings.
- In Download Image, select Only on initial download.
- In KITL Settings, clear the Clear memory on soft reset box.
- Click Apply, and then click Close.
Start the virtual CEPC that you have preconfigured and connected to Platform Builder, as described in Use the Sample Virtual Device. For example, to start the virtual CEPC on a Windows 7 computer:
- On the Start menu, point to All Programs, point to Windows Virtual PC, and then click Windows Virtual PC.
- Double-click the virtual CEPC you have preconfigured.
In Platform Builder, on the Target menu, click Run Programs. Choose the .exe file for your application, and then click Run.
After you test your Theme settings application and switch the theme, reset the device.
On the Target menu, click Reset, and then in the dialog box click Yes.
To add the theme settings application to the settings menu
Add a menu item to the settings menu that starts your settings application. For more information, see Add a New Menu Item.
Create a GUID for the settings application. For example, use the Guidgen Tool.
Add a registry subkey that has the GUID for the application, and add registry settings for the application. For more information, see "Executable Control Panel Registry Settings" in Control Panel Registry Settings.
In the .xrsl file for the menu item, add the GUID, enclosed in brackets, to the text content in the Args start and end tags.
Build the OS design into a run-time image. On the Build menu, click Build Solution.
Sample application code is available at MSDN Code Gallery.
Example Code
The following example code shows an event handler for the Click event for a button that changes the Theme registry value to Medium_Theme1.
Important
For readability, the following code example does not contain security checking or error handling. Do not use the following code in a production environment.
#include "XamlRuntime.h"
#include "stdafx.h"
#include "MainPage.h"
#include "App.h"
#include "resource.h"
#define HKCU_Layout L"\\Software\\Microsoft\\XRShell\\Settings"
#define Theme_Key L"Theme"
HRESULT MainPage::_Button1_Click (IXRDependencyObject* pSender, XRMouseButtonEventArgs* pArgs)
{
HRESULT hr = E_NOTIMPL;
if ((NULL == pSender) || (NULL == pArgs))
{
hr = E_INVALIDARG;
}
HKEY hThemeKey = NULL;
DWORD Type = REG_SZ;
WCHAR ThemeValue[MAX_PATH+1] = L"Medium_Theme1";
DWORD Length = MAX_PATH;
long res = 0;
StringCchLength(ThemeValue, _countof(ThemeValue), (size_t*)&Length);
if(ERROR_SUCCESS == RegOpenKeyEx(HKEY_CURRENT_USER, HKCU_Layout, 0, KEY_WRITE, &hThemeKey))
{
res = RegSetValueEx(hThemeKey,
Theme_Key,
NULL,
REG_SZ,
(LPBYTE)ThemeValue,
(Length+1)*sizeof(WCHAR)
);
RegCloseKey(hThemeKey);
hThemeKey = NULL;
}
res = RegFlushKey(HKEY_CURRENT_USER);
if(ERROR_SUCCESS == RegOpenKeyEx(HKEY_CURRENT_USER, HKCU_Layout, 0, KEY_READ, &hThemeKey))
{
res = RegQueryValueEx( hThemeKey,
Theme_Key,
NULL,
&Type,
(LPBYTE) &ThemeValue,
&Length
);
RegCloseKey(hThemeKey);
hThemeKey = NULL;
}
hr = S_OK;
return hr;
}
For more information about creating event handlers in XAML for Windows Embedded, see Getting Started with XAML for Windows Embedded and Create a XAML for Windows Embedded Application.
The following example code shows one way to display a message in the UI, by using the MessageBox function.
To use this code, you must first create the IXRVisualHost for the application by using IXRApplication::CreateHostFromElementTree or IXRApplication::CreateHostFromXaml, and you must include the XAML for Windows Embedded Message Box catalog item (SYSGEN_XAMLMSGBOX) in the OS design. Then, you must copy msgbox.lib from %_WINCEROOT%\Public\Common\Oak\Lib\x86\<debug_configuration> to %_WINCEROOT%\OSDesigns\<OSDesignName>\<OSDesignName>\WINCE800\<BuildConfiguration>\cesysgen\oak\lib\x86\<debug_configuration>, and from your Theme settings application link to msgbox.lib.
Important
For readability, the following code example does not contain security checking or error handling. Do not use the following code in a production environment.
#include "XamlRuntime.h"
#include "App.h"
HRESULT MainPage::NotifyUser()
{
HRESULT hr = E_FAIL;
HWND hwnd = NULL;
IXRVisualHost* pHost;
hr = App::GetVisualHost(&pHost);
if(hr == S_OK)
{
pHost->GetContainerHWND(&hwnd);
}
MessageBox(hwnd, L"To apply the new settings,
please restart your device.", L"Theme Update", MB_OKCANCEL);
return S_OK;
}
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.