 Important: |
|---|
| This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
Microsoft Corporation
June 1999
Summary:This article describes the shell support components included in Microsoft Windows CE 3.0 and explains how to develop a customized shell. (8 printed pages)
Contents
Introduction
Windows CE Shells
Developing and Installing a Custom
Shell
Shell Design Issues
Building a Custom Configuration
For More Information
Introduction
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:
- Taskman, the sample shell that handles desktop painting, the desktop bitmap, handling of battery warnings, and launching and switching between applications. Full source code is included for this sample.
- Components that support shell-related API functions: shellapis ( Shell_NotifyIcon, SHAddToRecentDocs), shexec ( ShellExecuteEx), shmisc ( SHLoadDIBitmap, SHShowOutOfMemory), shortcut ( SHCreateShortcut, SHGetShortcutTarget), fileopen ( GetOpenFileName, GetSaveFileName), and shcore (shared functions used by the other components).
- Commdlg, common dialog boxes.
- Commctrl, common controls.
- Console, console support, including the command processor Cmd.exe.
- Control, the Control Panel and individual components for each
Control Panel applet, including: system, screen, password, sounds,
main, comm, intl, network, dialing, and power.
Windows CE Shells
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:
- Microsoft Platform Builder version 2.12 and later includes a graphical shell similar to the shell of the Handheld PC (H/PC) that may be used on OEM devices. This shell, designed for general-purpose devices such as the PC Companion line, may not be appropriate for devices intended for more specific purposes. The shell should be reviewed carefully to determine if it is appropriate for use on a given target device. In particular, this shell is designed for graphical displays larger than 480 x 240.
- For devices without a display, usually known as headless devices, the Windows CE 2.10 and later operating system includes a command processor similar to Cmd.exe available in Microsoft Windows NT Workstation. This command processor can be configured to operate over a serial port, thus providing a command-prompt shell interface for headless devices. Windows CE 3.0 will provide other remote interface options including a Web server, telnet server, and SNMP.
- For devices with small displays or specialized devices for
which the full H/PC-like shell is not suitable, source code for a
sample shell is provided that can serve as a starting point for the
development of custom shells. Also included are several components
that provide functionality that is commonly considered part of the
shell and can be used as building blocks while developing a custom
shell.
The remainder of this article is aimed at helping the custom shell developer get started.
Developing and Installing a Custom Shell
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:
- Registration with the Graphics, Windowing, and Events Subsystem (GWES) module so that windows with hide capability can be placed behind the desktop window. This desktop also supports the use of a custom background bitmap.
- A Task Manager with a window that appears when you enter one of the following key combinations: ALT+TAB, CTRL+ESC, or CTRL+ALT+BACKSPACE. The Task Manager provides access to all top-level window applications. With it you can launch an application, switch to a running application, or terminate a running application.
- An incipient Taskbar window that registers with GWES and receives notifications on window creation, deletion, and so on. However, it does not display a visible H/PC-like Taskbar, though it can easily be used as a starting point for developing such a Taskbar.
- Handling of battery warnings and low-memory situations (WM_HIBERNATE).
- In Microsoft Platform Builder 2.12, the following functionality
is added: the Taskman sample shell calls the
ShellRegisterCallbacksAPI (described in the next section)
and registers callbacks to handle the
ShellNotify_Iconand
SHAddToRecentDocsAPIs. It does not actually take any action
in these callbacks. The intent is to provide a demonstration of the
interface to the system and a starting point for developers of
custom shells.
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 Launch XX="MyShell.EXE" Depends XX=hex:14,00,1e,00
When the system starts, it executes the Launch XXkeys 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 Depends XXkey 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.
Enabling Callback Functions with ShellRegisterCallbacks
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 SHELLCALLBACKSstructure. SHELLCALLBACKSconsists of a DWORDthat denotes the size of the structure, and pointers to the appropriate callback functions. These members must be assigned appropriate values, and then ShellRegisterCallbacksshould 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_NotifyIconand 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 Shell-related Components
Other system building blocks that provide functionality commonly considered part of the shell include:
- A Control Panel that provides access to Control Panel applications used to configure the system. These applications include: Communications, Display, Keyboard, Network, Dialing, Owner, Password, Power, Regional Settings, Pointing Device Settings (Stylus), Sounds, and Volume. As shipped, these Control Panels support displays of 480 x 240 and larger or Palm-size PC style displays 240 x 320 and larger. The system can be configured to include or exclude any or all of the Control Panel applications. The full source code is also provided in Microsoft Platform Builder 2.12 so they can be customized as needed.
- Connectivity components to support remote application programming calls between a development workstation and a Windows CE target platform.
- Windows CE common controls and common dialog boxes. Windows CE common dialog boxes include the Open, Save, Color, and Printdialog boxes. Common controls include check boxes, combo boxes, command bars, command buttons, list box, list views, menus, option buttons, scroll bars, status bar, tabs, text fields, toolbars, trackbars, treeviews, and others.
- The following components support the listed shell-related API functions: shellapis ( Shell_NotifyIcon, SHAddToRecentDocs), shexec ( ShellExecuteEx), shmisc ( SHLoadDIBitmap, SHShowOutOfMemory), shortcut ( SHCreateShortcut, SHGetShortcutTarget), fileopen ( GetOpenFileName, GetSaveFileName), and shcore (shared functions used by the other components).
- A command-prompt processor (console application) and console device that supports a set of standard input/output API (STDIO) calls. This component can be used to provide an on-screen command-prompt interface, or by redirecting the output of the command processor to a serial port, this component can be used to create a shell for headless devices.
- Notification APIs (offered as part of the GWES module) that
allow an application to register its name and an event with the
system. When the event occurs, the kernel automatically notifies
the application. These APIs can also be used to notify an
application at a given date and time.
Shell Design Issues
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:
- Microsoft Windows CE Toolkit for Visual Basic version 6.0
- Microsoft Windows CE Toolkit for Visual C++ version 6.0
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:
- A well-designed, responsive UI contributes much toward a user's perception of being in control of the shell and, therefore, of the device.
- Use concepts familiar to users. A conceptual model enables users to apply knowledge gained from experience toward understanding the structure and use of the application. For example, an Address application modeled after a typical paper-based address book would allow users to apply their understanding of address books to the new application.
- Be consistent in your UI. Don't ask "Do you want to save your work before exiting?" in 9 out of 10 places and "Are you sure want to discard your work?" in the other one!
- Give the user immediate and tangible feedback during interaction with an application. Appropriate feedback includes acknowledging a request, pointing out an error, or tracking the progress of an operation. Although auditory feedback can be useful for attracting a user's attention, it should be used sparingly.
- Keep your design simple. Simplicity is not only a
characteristic of good interface design, but it also hastens the
user's acceptance of the UI.
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.
Building a Custom Configuration
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:
-
Minkern
This configuration builds a minimal version of Windows CE that includes only the core OS or kernel (Core.dll). The registry may be set so that Windows CE opens one executable application upon startup. -
Mininput
This configuration builds a minimal version of Windows CE, featuring user input and native device driver support such as the display. Mininput also supports the sample code included with Platform Builder for keyboard, battery, and notification light-emitting diode (LED). Mininput includes a sample application— Kbdmsg.exe—that accepts keyboard input and displays the appropriate key codes to the debug serial port. -
Mincomm
This configuration builds a minimal version of Windows CE featuring serial communications and networking. A sample communications application, Rasdemo.exe, creates a phone-book entry on the target platform and attempts to connect with the specified RAS server. Mincomm requires either the IRComm, IrDA, and Serial components, or the TCP and NDIS components. -
Mingdi
This configuration builds a minimal version of Windows CE featuring graphics device interface (GDI) support. One sample application, Text.exe, tests the graphic output of the target platform. -
Minwmgr
This configuration builds a minimal version of Windows CE featuring window management and includes a simple drawing application, Etcha.exe. -
Minshell
This configuration builds a nearly complete version of Windows CE featuring the command processor and the Task Manager (minimum Windows CE shell). Minshell includes three sample applications: Spincube.exe, Spintest,exe, and Generic.exe. -
Maxall
This configuration builds a fully configured version of Windows CE featuring communications applications and the Input Method Manager (IMM). It also includes the full H/PC-like shell, Pocket Internet Explorer, Pocket Word, Inbox, and Help.Modifying Cesysgen.bat
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.
For More Information
- For more information on Windows CE development, see the Windows CE Platform SDK documentation.
- For more information on customizing the Windows CE operating system, see the Microsoft Windows CE Platform Builderdocumentation.
- For more information on the Windows programming environment, see The Microsoft Platform Software Development Kit and Programming Windowsby Charles Petzold ( http://www.microsoft.com/mspress/books/2344.asp).
-
Minkern