Microsoft Corporation
June 1999
Summary: Describes the shell support components included in Microsoft® Windows® CE version 3.0 and explains how to develop a customized shell. (8 printed pages) Includes:
Introduction
Windows CE Shells
Developing and Installing a Custom Shell
Shell Design Issues
Building a Custom Configuration
For More Information
Microsoft® Windows® CE is a compact, scalable operating system (OS) that is fast becoming the OS of choice for many embedded-systems developers. Its modular design allows for full customization—requiring that a developer select only the modules and components necessary for an embedded application.
Components are provided to support the development of custom shells. A platform developer can select from a set of components that support shell-related API functionality.
These shell support components offer flexibility by enabling a wide variety of shells. They are designed to make it as easy as possible for embedded-systems developers to create and use whatever shell they want. These components should be thought of as providing underlying system support only. Sample code is provided to help better understand system integration and to reduce development time.
This article describes the shell support components offered in Windows CE 3.0 and explains how to develop a customized shell. The components include:
A shell is a set of user interface components and underlying support routines that translates user input into useful OS actions. A Windows CE–based platform can have its own unique shell that is developed and customized for a device and its target audience. Windows CE–based devices span a range of configurations that require a variety of different types of shells. An OEM developing a Windows CE–based platform has the following options when choosing a shell:
The remainder of this article is aimed at helping the custom shell developer get started.
The starting point for a custom shell is the Taskman component. The source code for this component can be found in \wince\public\common\oak\shell in Microsoft Platform Builder 2.11 and in \wince\public\wceshell\oak\taskman in Microsoft Platform Builder 2.12 and later.
This sample provides the following:
The sample can be modified as needed to develop a custom shell suited to a device.
Once you have finished, install your shell on your device and debug and test your code as you would with any other application. To install a shell onto a device, insert the name of your application in the following Registry key:
HKEY_LOCAL_MACHINE\Init
LaunchXX="MyShell.EXE"
DependsXX=hex:14,00,1e,00
When the system starts, it executes the LaunchXX keys in order, launching Launch10, then Launch20, and so on. Make your shell the last item numbered in the list.
Also, make sure you add a DependsXX key that lists dependencies on previous launch components. The value of this key is a sequence of DWORDs that list the sequence numbers of dependent components. The system will wait for dependent components to run and initialize before launching the launch key with the matching number. For example, if your shell is registered as Launch60="MyShell.exe", you should have a Depends60 key that lists components, such as GWES, that must be initialized before your shell is launched. Before executing your Launch60 key, the system will wait for all components listed in the Depends60 to be executed and initialized.
Note that there can never be more than one shell running on a device. For your custom shell to work correctly, you must use a configuration without any other shell.
Microsoft Windows CE version 2.12 enables custom shells to register a callback function to intercept a limited number of H/PC shell function calls, such as tray icon notifications. The callback function is registered by means of a new function, ShellRegisterCallbacks.
To utilize this feature, a custom shell must first allocate a SHELLCALLBACKS structure. SHELLCALLBACKS consists of a DWORD that denotes the size of the structure, and pointers to the appropriate callback functions. These members must be assigned appropriate values, and then ShellRegisterCallbacks should be called. To use this API, include the shellcb.h header file and link with shellcb.lib.
Once a custom shell has registered its callbacks, application calls to the supported shell functions—Shell_NotifyIcon and SHAddToRecentDocs—will be forwarded to the custom shell through these callbacks. Also, any subsequent calls to IsAPIReady(SH_SHELL) by any application will return TRUE.
When an application calls one of the supported functions, such as Shell_NotifyIcon, the OS forwards the callback to the shell. Because the OS performs no thread-switching during such callbacks, the thread belongs to the client process. It is therefore very important that the callback functions do only a minimal amount of processing. Typically, the callback would save a copy of the parameter data and defer any required processing or display updates to a separate thread belonging to the shell. Note that parameter data must be fully copied, because any pointers passed to the callback function will be invalid on another thread or at a later callback, so they should not be saved and dereferenced later.
Other system building blocks that provide functionality commonly considered part of the shell include:
The primary purpose of a shell is to make it easy for users to access the features of a device. In this regard, developing a shell is similar to developing an application. The same principles of good design apply.
The first step in any development process is to determine the unique configuration of the hardware platform for which you are developing. Because Windows CE is a modular OS, you must decide which specific modules and components your target audience will need to operate your device.
Once you have designed your target platform, you then must decide what programming environment to use. You can choose either the Microsoft Visual C++® or Microsoft Visual Basic® development system. In addition to the tools provided with the Windows CE Platform Builder 3.0, each of these programming environments has its own unique toolkit for you to use. They include:
After choosing a programming environment and toolkit, you can begin developing your shell. Use standard components and Microsoft Win32® APIs. Keep usability in mind by designing a simple, easy-to-use interface.
Here are some general user interface (UI) design guidelines:
Control Panel applications are related to the style of the shell of a device. For example, a device with a text-based display will likely have a shell that consists of a series of menus. To match this style, any Control Panel applications should also consist of a series of menus. Similarly, a device with a graphical user interface should provide graphical Control Panel applications.
Microsoft now includes source code for Control Panel applications with Platform Builder. This source code can be customized so that Control Panel applications will be tailored to the specifications of a given target device or so that the source code may be used as reference material to create new Control Panel applications.
Before you can select which components to add to your shell, you must first decide which modules and components you want to include in your OS. Then you must modify the Cesysgen.bat file.
Out of the many modules and components available in Windows CE, selecting the right combination of components to support your target platform can be difficult. To assist you in this task, Windows CE supplies several component configurations from which you can choose. These configurations represent different sets of system capabilities, ranging from a base system with minimal user input and no display capabilities, to a system with keyboard and touch-pad input, a full-color display, and fax/modem and networking support. All configurations included with Windows CE have been fully tested by Microsoft. Other combinations of modules and components are possible, but Microsoft has not tested them and therefore cannot guarantee their reliability. If you choose to create your own configurations, contact Microsoft for assistance.
Standard Windows CE configurations include:
The Cesysgen.bat file specifies the environment variables used to create your Windows CE project. Cesysgen.bat allows you to choose the modules for your Windows CE OS to install on your hardware development platform. Some modules, such as the OS kernel module (Nk), are required.
To add components to your Cesysgen.bat file, modify Cesysgen.bat in the \Oak\Misc directory to specify the modules of the Windows CE OS to be included in your Windows CE–based project. See the following example:
set CE_MODULES=%CE_MODULES% gwes
set GWE1_COMPONENTS=wmbase gweshare gwesmain immthunk msgque
if "%CONFIG5_NOCURSOR%"=="1" set GWE3_COMPONENTS=icon cursor cursor8
On the basis of these modifications, Cesysgen.bat sets the value of the component environment variables.
The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication. This document is for informational purposes only.
This White Paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, IN THIS DOCUMENT.
© 1999 Microsoft Corporation. All rights reserved.
Microsoft, ActiveX, Visual Basic, Visual C++, Win32, Windows, and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.
Other product and company names mentioned herein may be the trademarks of their respective owners.