Registering Control Panel Items

  • Article

Control Panel items must be registered in order to appear in the Control Panel window. If the Control Panel item is implemented as part of a .exe file then it is registered as a command object. Registration differs if the item is implemented as a .dll file that exports the CPlApplet function.

Specific requirements are discussed in these sections.

  • Executable Control Panel Item Registration
  • DLL Control Panel Item Registration
  • Related Topics

Executable Control Panel Item Registration

For Control Panel items implemented as .exe files, no special exports or message handling is required. Any .exe file can be registered as a command object to appear with an entry point in the Control Panel folder.

An example is used here to demonstrate the registration requirements. The example shows how to register a Control Panel item called My Settings as a command object so it appears in the Control Panel window. The My Settings window also appears when the command MyApp.exe /settings is run.

  1. Generate a GUID for the Control Panel item. In this example, {0052D9FC-6764-4D29-A66F-2F3BD9E2BB40} is the GUID of the Control Panel item. The GUID uniquely identifies the Control Panel item.

  2. Add the following information to the registry.

    HKEY_LOCAL_MACHINE

    SOFTWARE

    Microsoft

    Windows

    CurrentVersion

    Explorer

    ControlPanel

    NameSpace

    • {0052D9FC-6764-4D29-A66F-2F3BD9E2BB40}

    The data for the Default entry is simply the name of the Control Panel item. The Default entry can be a useful tag when someone is examining the registry, but it is optional.

  3. Add the following information to the registry.

    HKEY_CLASSES_ROOT

    CLSID

    • {0052D9FC-6764-4D29-A66F-2F3BD9E2BB40}

    • Default. The display name for the Control Panel item.

    • LocalizedString. Optional. The module name and string table ID of the localized name of the Control Panel item. The format is an at sign (@) followed by the name of the .exe or .dll that contains the Multilingual User Interface (MUI) string table. Environment variables can be used as a substitute for a part of the path. That is followed by a comma (,) and a hyphen (-), followed by the ID in the string table. If the module does not have a string table then this value can simply be the display name string. If you use only the display name string rather than a string table, the name does not adjust to the current display language.

    • InfoTip. A description of the Control Panel item. This is displayed in an InfoTip that is displayed when the mouse hovers over the item's icon. The syntax is the same as that used for LocalizedString, including the option of simply providing a string rather than a string table reference.

    • System.ApplicationName. The canonical name of the item. The command control.exe /name MyCorporation.MySettings will open the item. See Executing Control Panel Items.

    • System.ControlPanel.Category. A value that declares the categories where the item appears. Multiple categories are separated by commas. In this case, it specifies that the My Settings item should appear in the Appearance and Personalization category and also the Programs category. See Assigning Control Panel Categories for possible values.

    • System.Software.TasksFileUrl. The path of the XML file that defines task links. This can be a path as shown in the example, or an embedded resource specified as a module name and resource ID such as "%ProgramFiles%\MyCorp\MyApp\MyApp.exe,-31".

  4. Add the following information to the registry to provide the path of the file that contains the icon and the resource ID of the image within that file.

    HKEY_CLASSES_ROOT

    CLSID

{0052D9FC-6764-4D29-A66F-2F3BD9E2BB40}

  - **DefaultIcon**

Note that while the syntax is otherwise similar to LocalizedString and InfoTip discussed earlier, no @ character is used as a prefix.

  1. Add the following information to the registry to provide the command called by the system when the user opens the Control Panel.

    HKEY_CLASSES_ROOT

    CLSID

{0052D9FC-6764-4D29-A66F-2F3BD9E2BB40}

**Shell**

**Open**

  - **Command**

DLL Control Panel Item Registration

Control Panel items implemented in a DLL that exports the CPlApplet function have different registration requirements than .exe files. For Microsoft Windows 2000 and later systems, new Control Panel item DLLs should be installed in the associated application's folder under the Program Files folder. Items stored in the System32 directory with a .cpl extension do not need to be registered; they are automatically shown in the Control Panel. All other Control Panel items using CPlApplet must be registered in one of two ways:

  • If the Control Panel item is to be available to all users, register the path on a per-computer basis by adding a REG_EXPAND_SZ value to the HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Control Panel\Cpls key, set to the DLL path.
  • If the Control Panel item is to be available on a per-user basis, use HKEY_CURRENT_USER as the root key instead of HKEY_LOCAL_MACHINE .

The following two examples register the MyCplApp Control Panel item. The DLL is named MyCpl.cpl and is located in the MyCorp\MyApp application directory. This first example illustrates per-computer registration.

  1. Add this information to the registry to register the existence of the .cpl file.

    HKEY_LOCAL_MACHINE

    Software

    Microsoft

    Windows

    CurrentVersion

    Control Panel

    • Cpls

  2. Windows Vista and later: Add this additional information to the registry to provide a GUID for the Control Panel item.

    HKEY_LOCAL_MACHINE

    Software

    Microsoft

    Windows

    CurrentVersion

    Control Panel

    ExtendedProperties

    • System.Software.AppId

    By generating a GUID to uniquely identify the Control Panel item, you can add task links to the Control Panel. Without this GUID, there is no way for the task links to be associated with the Control Panel item. See Creating Searchable Task Links for a Control Panel Item.

  3. Windows Vista and later: Add the following information to the registry to create a canonical name for the item.

    HKEY_LOCAL_MACHINE

    Software

    Microsoft

    Windows

    CurrentVersion

    Control Panel

    ExtendedProperties

    • System.ApplicationName

    By adding a canonical name, users can launch the Control Panel item from a command line by entering control.exe /name MyCorporation.MyCpl. This also makes it possible to change an implementation from a .cpl file to a .exe file later, without requiring calling programs to make any changes since they can continue opening the item through its canonical name. For more information on canonical names, see Executing Control Panel Items.

  4. Windows Vista and later: Add the following information to the registry to assign a Control Panel item to one or more categories.

    HKEY_LOCAL_MACHINE

    Software

    Microsoft

    Windows

    CurrentVersion

    Control Panel

    ExtendedProperties

    • System.ControlPanel.Category

    Windows XP: Add the following information to the registry to assign a Control Panel item to one or more categories.

    HKEY_LOCAL_MACHINE

    Software

    Microsoft

    Windows

    CurrentVersion

    Control Panel

    ExtendedProperties

    • {305CA226-D286-468e-B848-2B2E8E697B74} 2

    This example assigns the item to category 3, which is Network and Internet. To add an item to multiple categories, provide the list as a REG_SZ value separated by commas, such as "3,8". Values can be provided as either decimal or hexidecimal. Note that the ability to add an item to multiple categories is only possible in Windows XP Service Pack 2 (SP2) and later. See Assigning Control Panel Categories for all possible values.

  5. Windows Vista and later: Add the following information to the registry to create and point to an XML file to hold task links for the item. The value must be a REG_SZ path as shown here or a module and resource ID (for example, "C:\Program Files\MyCorp\MyApp\MyApp.exe,-31") if it is an embedded resource. The location of the XML file should be fully specified. It cannot use an environment variable such as %ProgramFiles%.

    HKEY_LOCAL_MACHINE

    Software

    Microsoft

    Windows

    CurrentVersion

    Control Panel

    ExtendedProperties

    • System.Software.TasksFileUrl

    For more details on task links and how to create the XML file to hold them, see Creating Searchable Task Links for a Control Panel Item.

For systems prior to Windows 2000, new Control Panel items must be set up in one of the following ways:

  • Copy the DLL to the directory that contains the Windows system utility.

  • Copy the DLL to the Windows SYSTEM directory.

  • Write the path of the DLL using the WritePrivateProfileString function, specifying the string "MMCPL" as the section name and the string "control.ini" as the file name (no path). Do not actually write directly to the Control.ini file. Instead, use the WritePrivateProfileString function, which automatically handles differences among platforms. The following example demonstrates how you would set up the path for MyCpl.cpl.

    WritePrivateProfileString("MMCPL", "MyCpl.cpl", "C:\\mydir\\MyCpl.cpl", "control.ini");

    Note  Control.ini can also restrict which Control Panel items are loaded. It is not recommended that applications alter Control.ini for this purpose.