Export (0) Print
Expand All
1 out of 4 rated this helpful - Rate this topic

Registering Control Panel Items

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

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}

                    • (Default) = My Settings

    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) = [REG_SZ] My Settings
          LocalizedString = [REG_EXPAND_SZ] @%ProgramFiles%\MyCorp\MyApp.exe,-9
          InfoTip = [REG_EXPAND_SZ] @%ProgramFiles%\MyCorp\MyApp.exe,-5
          System.ApplicationName = [REG_SZ] MyCorporation.MySettings
          System.ControlPanel.Category = [REG_SZ] 1,8
          System.Software.TasksFileUrl = [REG_SZ or REG_EXPAND_SZ] %ProgramFiles%\MyCorp\MyApp\MyTaskLinks.xml

    • 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

          • (Default) = [REG_EXPAND_SZ] %ProgramFiles%\MyCorp\MyApp.exe,-2

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

  5. 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

              • (Default) = [REG_EXPAND_SZ] %ProgramFiles%\MyCorp\MyApp.exe /Settings

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

                • MyCpl = [REG_EXPAND_SZ] %ProgramFiles%\MyCorp\MyApp\MyCpl.cpl
  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

                  • %ProgramFiles%\MyCorp\MyApp\MyCpl.cpl = {A newly generated GUID}

    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

                  • %ProgramFiles%\MyCorp\MyApp\MyCpl.cpl = [REG_SZ] MyCorporation.MyCpl

    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

                  • %ProgramFiles%\MyCorp\MyApp\MyCpl.cpl = [REG_DWORD] 3

    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

                  • %ProgramFiles%\MyCorp\MyApp\MyCpl.cpl = [REG_DWORD] 3

    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

                  • %ProgramFiles%\MyCorp\MyApp\MyCpl.cpl = [REG_SZ] C:\ProgramFiles\MyCorp\MyApp\MyTasks.xml

    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.

Related Topics

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

Show:
© 2014 Microsoft. All rights reserved.