Design Specifications and Guidelines - Integrating with the System

Using the Registry

Windows provides a special repository called the registry that serves as a central configuration database for user-, application-, and computer-specific information. Although the registry is not intended for direct user access, the information placed in it affects your application's user interface. Registered information determines the icons, commands, and other features displayed for files. The registry also makes it easier for system administrators to manage and support configuration information used by your application and eliminates redundant information stored in different locations.

The example registry entries in this chapter represent only the hierarchical relationship of the keys. For more information about the registry and registry file formats, see the documentation included in the Microsoft Platform SDK on the MSDN Online Web site at https://msdn.microsoft.com/ui/guide/sdk.asp.

An application should never fail to write a registry entry because the entry is already installed. To ensure that this happens, use registry creation functions when adding an entry.

Registering New File Types

Every file your program creates, even if it is hidden or rarely seen by users, should have a registered file type. This is important so that users can understand exactly how any file on the computer was created. Whenever possible, use conventional Windows file types. For other unique file types your application uses, at least make sure to register an icon and a friendly type name. If your program creates files that users should not modify, you can register the corresponding file type with a NoOpen option, as described in "Registering Commands" later in this chapter.

For every file type you register, include at least two entries: a file name extension key entry and a file type (class) identifier key entry.

The File Name Extension Key

The file name extension entry maps a file name extension to a file type identifier. To register an extension, create a subkey in the HKEY_CLASSES_ROOT key using the three (or more) letter extension (including a period), and set its default value to a file type identifier, as follows:

HKEY_CLASSES_ROOT

.ext = FileTypeIdentifier

You may want to consider using a longer (four- to five-character) extension. This may decrease possible file type collisions with other applications.

For the value of the file type identifier (also known as the programmatic identifier or Prog ID), use a string that uniquely identifies a given class. This string is used internally by the system and is not exposed directly to users (unless explicitly exported with a special registry utility); therefore, you do not need to localize this entry.

Avoid assigning multiple extensions to the same file type identifier. To ensure that the user can distinguish each file type, define each extension such that each has a unique file type identifier. If your application contains utility files that the user does not interact with directly, you should still register an extension (and icon) for them, preferably the same extension so that they can be identified. In addition, mark them with the hidden file attribute.

Always try to define unique identifiers for your application's file types, and check the registry to avoid accidentally writing over and replacing existing extension entries, a practice that can seriously affect the user's existing files. More importantly, avoid registering an extension that conflicts with or redefines the common file name extensions used by the system. For common file name extensions, see the Microsoft Platform SDK on the MSDN Online Web site at https://msdn.microsoft.com/ui/guide/sdk.asp. If you want to add support for existing file types, see "Taking Over a File Type" later in this chapter.

The File Type Identifier Key

The second registry entry you create for a file type is its class-definition (Prog ID) key. Using the same string as the file type identifier you used for the extension's value, create a key and assign a type name as the default value of the key, as follows:

HKEY_CLASSES_ROOT

.ext = FileTypeIdentifier

FileTypeIdentifier* = *Type Name

Under this key, you specify the shell and COM properties of the class. Include this entry even if you do not have any extra information to place under this key; doing so provides a label for users to identify the file type. In addition, you use this entry to register the icon for the file type.

Define the type name (also known as the MainUserTypeName) as the human-readable form of its file type identifier or class name. It should convey to the user the object's name, behavior, or capability. A type name can include all of the following elements:

Elements of a File Type Name
Element	Function
Company name	Communicates product identity.
Application name	Indicates which application is responsible for activating a data object.
Data type	Indicates the basic category of the object (for example, drawing, spreadsheet, or sound); limit the number of characters to a maximum of 15.
Version	Distinguishes within multiple versions of the same basic type; you may want to use this for upgrades.

When you define a type name, use book title capitalization. The name can include a maximum of up to 40 characters. Use one of the following recommended forms:

• Company Name Application Name [Version] Data Type
  For example, Microsoft Excel Worksheet
• Company Name-Application Name [Version] Data Type
  For cases when the company name and application name are the same — for example, ExampleWare 2.0 Document
• Company Name Application Name [Version]
  When the application name sufficiently describes the data type — for example, Microsoft Graph

These type names provide the user with a precise language for referring to objects. Because object type names appear throughout the interface, the user becomes conscious of an object's type and its associated behavior. However, because of their length, you may also want to include a short type name. A short type name is the data type portion of the full type name. Applications that support COM always include a short type name entry in the registry. Use the short type name in drop-down and shortcut menus. For example, a Microsoft Excel Worksheet is referred to simply as a "Worksheet" on menus.

To provide a short type name, add an AuxUserType subkey under the application's registered CLSID subkey (which is under the CLSID key), as follows:

HKEY_CLASSES_ROOT

.ext* = *FileTypeIdentifier

...

FileTypeIdentifier* = *File Type Display Name

CLSID = {CLSID identifier}

...

CLSID

{CLSID identifier}

AuxUserType

2 = Short Type Name

More Information

For more information about registering type names and other information you should include under the CLSID key, see the OLE documentation in the Microsoft Platform SDK on the MSDN Online Web site at https://msdn.microsoft.com/ui/guide/sdk.asp.

If a short type name is not available for an object because the string was not registered, use the full type name instead. For controls that display the full type name, allocate enough space for 40 characters in width. By comparison, you can design for only 15 characters when using the short type name.

Registering Icons

The system uses the registry to determine which icon to display for a specific file. You register an icon for every data file type that your application supports and that you want the user to be able to distinguish easily. Create a DefaultIcon subkey entry under the file type identifier subkey you created and define its value as the file name containing the icon. Typically, you use the application's executable file name and the index of the icon within the file. The index value corresponds to the icon resource within the file. A positive number represents the icon's position in the file. A negative number corresponds to the inverse of the resource ID number of the icon. The icon for your application should always be the first icon resource in your executable file. The system always uses the first icon resource to represent executable files. This means that the index value for your data files will be a number greater than 0, as follows:

HKEY_CLASSES_ROOT

FileTypeIdentifier* = *File Type Display Name

DefaultIcon = path [,index]

Instead of registering the application's executable file, you can register the name of a dynamic-link library file (.dll), an icon file (.ico), or a bitmap file (.bmp) to supply your data file icons. If an icon does not exist or is not registered, the system supplies an icon derived from the icon of the file type's registered application. If no icon is available for the application, the system supplies a generic icon. These icons do not make your files uniquely identifiable, so it is better to design and register icons for both your application and its data file types. Include 16- and 256-color versions in the following sizes: 16 x 16 pixels, 32 x 32 pixels, and 48 x 48 pixels.

More Information

For more information about designing icons for your files, see Chapter 14, "Visual Design."

Registering Commands

Many of the commands found on icons, including Send To, Cut, Copy, Paste, Create Shortcut, Delete, Rename, and Properties, are provided by their container — that is, their containing folder or the desktop. But you must provide support for the icon's primary commands, also referred to as verbs, such as Open, Edit, Play, and Print. You can also register additional commands that apply to your file types and even commands for other file types.

To add these commands, in the HKEY_CLASSES_ROOT key, you register a shell subkey and a subkey for each verb, and a command subkey for each menu command name, as follows:

HKEY_CLASSES_ROOT

FileTypeIdentifier* = *Type Name

shell [ = default verb [,verb2 [,..]]

verb [ = Menu Command Name]

command = pathname [parameters]

A verb is a language-independent name of the command. Applications can use it to invoke a specific command programmatically. When you supply verbs other than "open," "print," "find," and "explore," you must provide menu command names localized for the specific version of Windows on which the application is run. (Windows automatically provides menu command names and appropriate access key assignments for "open," "print," "find," and "explore," localized in each international version of Windows.) To assign a menu command name for a verb, make it the default value of the verb subkey. For example, here's how the registry entry for the verb "open" might look:

HKEY_CLASSES_ROOT

txtfile = Text Document

shell = open

command = C:\windows\NOTEPAD.EXE /p %1

The menu command names corresponding to the verbs for a file type are displayed to the user, either on a folder's File menu or on the shortcut menu for a file's icon. These commands appear at the top of the menu. You define the order of the menu commands by ordering the verbs in the value of the shell key. The first verb becomes the default command in the menu.

By default, capitalization follows how you format the menu command name value of the verb subkey. Although the system automatically capitalizes the standard commands (Open, Print, Explore, and Find), you can use the value of the menu command name to format the capitalization differently. Similarly, you use the menu command name value to set the access key for the menu command following normal menu conventions, prefixing the desired access character in the name with an ampersand (&). Otherwise, the system sets the first letter of the command as the access key for that command.

To support user execution of a verb, provide the path for the application (or a DDE command string).

You can include command-line switches. For paths, include a %1 parameter. This parameter is an operational placeholder for whatever file the user selects.

For example, to register an Analyze command for an application that manages stock market information, the registry entries might look like the following:

HKEY_CLASSES_ROOT

stockfile = Stock Data

shell = analyze

analyze = &Analyze

command = C:\Program Files\Stock Analysis\Stock.exe /A

You can have different values for each command. For example, you can assign one application to carry out the Open command and another to carry out the Print command, or use the same application for all commands.

If you have a file type that users should not open, register it by adding a NoOpen value under the file type identifier key.

HKEY_CLASSES_ROOT

FileTypeIdentifier* = *File Type Display Name

NoOpen = Optional text message to display.

If the user attempts to open this file, the system displays a warning message. If you set the value of NoOpen, the system uses your text to display in the message box. Marking your files this way does not prevent users from still opening the files, but it does automatically warn the users.

Supporting the New Command

The system supports the creation of new objects in system containers, such as folders and the desktop. Register information for each file type that you want the system to include. The registered type will appear in the New command that the system includes on menus for the desktop and folders, and in the Open and Save As common dialog boxes. This provides a more data-centered design because the user can create a new object without having to locate and run the associated application.

To register a file type for inclusion, create a subkey using the FileTypeIdentifier under the extension's subkey in HKEY_ CLASSES_ROOT. Under it, also create the ShellNew subkey, as follows:

HKEY_CLASSES_ROOT

.ext = FileTypeIdentifier

FileTypeIdentifier

ShellNew Value Name = Value

Assign a value entry to the ShellNew subkey with one of the following four methods for creating a file with this extension.

Ways to Support the New Command Using the Registry
Value name	Value	Result
NullFile	" "	Creates a new file of this type as a null (empty) file.
Data	binary data	Creates a new file containing the binary data.
FileName	path	Creates a new file by copying the specified file.
Command	file name	Carries out the command. Use this to run your own application code to create a new file (for example, to run a wizard).

The system also automatically provides a unique file name for the new file using the type name you register.

When you use a FileName value, store the file that will serve as the template in the system-managed Templates folder. You can retrieve the path to that folder with SHGetFolderPath(), using CSIDL_TEMPLATES (or CSIDL_COMMON_TEMPLATES on platforms that support it). This way you don't need to specify a fully qualified path name that could potentially break if the user roams from one computer to another.

Enabling Printing

If the files in your application are of a type that can be printed, include a "print" verb entry in the shell subkey under HKEY_CLASSES_ROOT, following the conventions described in the previous section. This will display the Print command on the shortcut menu for the icon and on the File menu of the folder in which the icon resides when the user clicks the icon. When the user clicks the Print command, the system uses the registry entry to determine which application to run to print the file.

Also register a Print To registry entry for the file types your application supports. This entry enables dragging and dropping a file onto a printer icon. Although a Print To command is not displayed on any menu, the printer includes Print Here as the default command on the shortcut menu displayed when the user drags and drops a file onto the printer icon using the secondary mouse button.

In both cases, it is preferable to print the file without opening the application's primary window. One way to do this is to provide a command-line switch that runs the application for handling the printing operation only (for example, WordPad.exe /p). In addition, display some form of user feedback that indicates whether printing has been initiated and, if so, its progress. For example, this feedback could be a modeless message box that displays, "Printing page m of n on printer name" and a Cancel button. You can also include a progress indicator control.

Supporting InfoTips

When you create a new file type, also include an InfoTip description for the type. The system automatically displays a ToolTip with this description when the user moves the pointer over an icon of this type. To register the InfoTip description for a specific type, add an InfoTip value to the file extension subkey, as follows:

HKEY_CLASSES_ROOT

.ext = FileTypeIdentifier

InfoTip=Text to display when user hovers over this file type

You can also support an InfoTip for a shortcut link to a program that you include in the Programs folder of the Start menu. To do so, include a text description in the Comment field for the shortcut's properties.

Setting Other File Type Values

You can also register certain attributes for your file types. For example, you can mark your file type as being safe to download or keep files of a specific type from being included in the Recent Documents folder. To do this, add an EditFlag value to your file type identifier key. For information about values you can set, see the Microsoft Platform SDK on the MSDN Online Web site.

Taking Over a File Type

If your application supports the file type of another application or a common file type that might be used by multiple applications, such as text or HTML files, you may want your application to take over that type. Typically this means taking over the "open" verb of that type so that when the user opens or double-clicks a file of that type, the system automatically runs your application to open (and edit) the file. However, it is also possible to take over (or add) other verbs for a particular file type.

Always warn the user during your application's installation before you take over the file type, offering the user the choice. If your application uses a silent install, don't take over the association or prompt for user confirmation until the user runs your application.

Always store the previous association and provide an option in your application interface that enables the user to restore the previous file type association. In addition, restore the previous association automatically when the user uninstalls your application.

Note that in Windows 2000, if the user explicitly changes the file type association, the system maintains the user's choice even if you overwrite the current association.

Registering NoOpenWith

If your application supports only its own unique file type or you have executable (.exe) files that perform very specific functions, you don't want these files to appear in the system's Open With dialog box. To ensure that your application file is not included, add an entry for your application in the Application subkey of HKEY_CLASSES_ROOT. Then add a NoOpenWith subkey, as follows:

HKEY_CLASSES_ROOT

Applications

Application.Exe

NoOpenWith

You can also register file types that the user cannot open by adding a NoOpen subkey to your Prog ID for your file type. This is especially good for a type of file that the user could accidentally corrupt by attempting to open. Users can still access a file registered with this setting by using the Open With command.

Registering Application State Information

Use the registry to store state information for your application. Typically, the data you store here is information you may have stored in initialization (.ini) files in previous releases of Windows. Create subkeys under the Software subkey in the HKEY_LOCAL_MACHINE and HKEY_CURRENT_USER keys that include information about your application, as follows:

HKEY_LOCAL_MACHINE

Software

CompanyName

ProductName

Version

...

HKEY_CURRENT_USER

Software

CompanyName

ProductName

Version

Store computer-specific data in your application's HKEY_LOCAL_MACHINE entry, and store user-specific data in your application's HKEY_CURRENT _USER entry. The latter key allows you to store settings to tailor your application for individual users working with the same computer. Under your application's subkey, you can define your own structure for the information. Although the system still supports initialization files for backward compatibility, use the registry wherever possible to store your application's state information instead.

Use these keys to save your application's state whenever appropriate, such as when the user closes your application's primary window. In most cases, it is best to restore a window to its previous state when the user reopens it.

When the user shuts down the system with your application's window open, you can optionally store information in the registry so that the application's state is restored when the user starts Windows. (The system does this for folders.) To have your application's state restored, store your window and application state information under its registry entries when the system notifies your application that it is shutting down. Store the state information in your application's entries under HKEY_CURRENT_USER and add a value name_value pair to the RunOnce subkey that corresponds to your application. When the user restarts the computer, the system runs the command line you supply. When your application runs, you can use the data you stored to restore its state, as follows:

HKEY_CURRENT_USER

Software

Microsoft

Windows

CurrentVersion

RunOnce file type identifier = command line

More Information

Use Run and RunOnce capabilities sparingly. Confronting many different windows simultaneously at the beginning of a session creates a bad end-user experience. On Windows 2000, it is possible to serialize Run and RunOnce options, so that the system waits for each process to finish before launching the next. For more information, see the Microsoft Platform SDK on the MSDN Online Web site at https://msdn.microsoft.com/ui/guide/sdk.asp.

If you have multiple instances open, you can include value name entries for each instance, or consolidate them as a single entry and use the command-line switches that are most appropriate for your application. For example, you can include entries like the following:

WordPad Document 1 = C:\Program Files\Wordpad.exe Letter to Bill /restore

WordPad Document 2 = C:\Program Files\Wordpad.exe Letter to Paul /restore

Paint = C:\Program Files\Paint.exe Abstract.bmp Cubist.bmp

As long as you provide a valid command-line string that your application can process, you can format the entry in a way that best fits your application.

You can also include a RunOnce entry under the HKEY_LOCAL_ MACHINE key. When using this entry, however, the system runs the application before starting up. You can use this entry for applications that need to query the user for information that affects how Windows starts. Remember that any entry here will affect all users of the computer.

RunOnce entries are automatically removed from the registry after the system starts. Therefore, you do not need to remove or update the entries, but your application must always save the registry's state when the user shuts down the system. The system also supports a Run subkey in both the HKEY_CURRENT_USER and HKEY_LOCAL_ MACHINE keys. The system runs any value name entries under this subkey after the system starts, but it does not remove those entries from the registry. For example, a virus-check program can be installed to run automatically after the system starts. You can also support this functionality by placing a file or shortcut to a file in the Startup folder. The registry stores the location of the Startup folder as a value in HKEY_CURRENT_USER \Software\Microsoft\ Windows\CurrentVersion\Explorer\Shell Folders.

The system's ability to restore an application's state depends on the availability of the application and its data files. If they have been deleted or if the user has logged on over the network where the same files are not available, the system may not be able to restore the state.

Registering Application Path Information

The system supports "per application" paths. If you register a path, Windows sets the PATH environment variable to be the registered path when it starts your application. You set your application's path in the AppPaths subkey under the HKEY_LOCAL_MACHINE key. Create a new key using your application's executable file name as its name. Set this key's default value to the path of your executable file. The system uses this entry to locate your application if it fails to find it in the current path — for example, if the user chooses the Run command on the Start menu and includes only the file name of the application, or if a shortcut icon doesn't include a path setting. To identify the location of .dll files placed in a separate folder, you can also include another value entry called Path and set its value to the path of your .dll files, as follows:

HKEY_LOCAL_MACHINE

Software

Microsoft

Windows

CurrentVersion

App Paths

Application Executable Filename* *= path

Path = path

The system will automatically update the path and default entries if the user moves or renames the application's executable file using the system shell user interface.

Register any system-wide shared .dll files in a subkey under a SharedDLLs subkey of the HKEY_LOCAL_MACHINE key. If the file already exists, increment the entry's usage count index, as follows:

HKEY_LOCAL_MACHINE

Software

Microsoft

Windows

CurrentVersion

SharedDLLs file name [= usage count index]

For more information about the usage count index, see "Installation" later in this chapter.

Adding Features to File Types

Windows provides interfaces that enable you to add menu items or property pages for other file types, define instance-specific icons, enhance drag-and-drop operation support, and monitor file transfer operations. However, use these shell extensions judiciously because these add to the user's existing interface. If you use shell extensions to enhance or extend the interfaces of files other than those your application creates, inform users during installation, giving them the choice to accept the change. Also provide users with support to disable or remove the extension you provide.

Shell extensions are COM objects, implemented as in process-server .dll files. These objects implement the interfaces that provide the functionality of the shell extension. The following types of handlers can be registered.

Types of Shell Extension Handlers
Handler	Function
Shortcut (context)	Adds menu items to the shortcut menu handler menu for a particular file type.
Drag handler	Allows you to support the OLE data transfer conventions for drag-and-drop operations of a specific file type.
Drop handler	Allows you to carry out some action when the user drops objects on a specific type of file.
Nondefault drag-and-drop handler	Shortcut menu handlers that the system calls when the user drags and drops an object by using the secondary mouse button.
Icon handler	Adds per-instance icons for file objects or supplies icons for all files of a specific type.
Property sheet handler	Adds pages to a property sheet that the shell displays for a file object. The pages can be specific to a class of files or to a particular file object.
Copy-hook handler	Called when a folder or printer object is about to be moved, copied, DEL eted, or renamed by the user. The handler can be used to allow or prevent the operation.
Thumbnail extractor	Shows your file type in thumbnail view and previews it in the Web view preview control.
Details handler	Adds extra columns to the folder details view.

More Information

For more information about creating COM objects and shell extensions, see the COM and ActiveX documentation included in the Microsoft Platform SDK on the MSDN Online Web site at https://msdn.microsoft.com/ui/guide/sdk.asp.

Fundamentals of Designing User Interaction

Windows Interface Components

Design Specifications and Guidelines

Appendixes and References