Click here to Skip to main content
15,867,308 members
Articles / Desktop Programming / ATL
Article

Adding Custom Pages to Control Panel Applets

Rate me:
Please Sign up or sign in to vote.
5.00/5 (6 votes)
3 Apr 2001 160.1K   1.4K   62   25
This article shows how to add your own pages to Control Panel applets by writing a property sheet handler.

Introduction

After writing my tutorial on property sheet shell extensions, I had some folks ask me how to go about customizing pages in Control Panel applets. The procedure is very similar to writing a "normal" property sheet extension, so I have written this article that summarizes how to do it.

I classified this article as intermediate level, as you should already be familiar with property sheet extensions, the COM interfaces involved and their methods, and how to code property pages in straight SDK calls. If you need a refresher, see my tutorial.

Also keep in mind that customizing Control Panel applets shouldn't be done lightly. If you're writing custom driver software (e.g., something like Microsoft's IntelliPoint or IntelliType), then it's perfectly reasonable. But if you just have a little wallpaper-switching program, you'd be better served to write your own configuration app instead of adding to the already-crowded Display Control Panel.

The sample project for this article is a simple extension that adds two custom pages to the Display applet.

The Extension Interfaces

As with a normal property sheet extension, a Control Panel extension implements two interfaces: IShellExtInit and IShellPropSheetExt. The sequence of method calls is a bit different from normal property sheet extensions. The sequence goes like this:

  • IShellExtInit::Initialize() is called first, but since there are no files to be selected, the pidlFolder and lpdobj parameters are both NULL. You can perform any one-time initialization in Initialize().
  • IShellPropSheetExt::ReplacePage() is called once for each page that is replaceable, if the applet allows pages to be replaced. You can replace one page in each ReplacePage() call; I'll explain this below.
  • IShellPropSheetExt::AddPages() is called once. You can add as many pages as you like in AddPages().

The big difference is the ReplacePage() method, which went unused in normal property sheet extensions. Certain Control Panel applets let extensions replace pages in the property sheet. You can find the exact pages and applets in the cplext.h file, but I've summarized them here:

  • Display applet: You can replace the Background page.
  • Keyboard applet: You can replace the Speed page.
  • Mouse applet: You can replace the Buttons and Motion pages.

The initialization interface

As I mentioned above, IShellExtInit::Initialize() is called, but since there is no selection in a Control Panel applet, the parameters are meaningless. If you have any one-time initialization to do, Initialize() is a good place to do it.

The property sheet interface

The Display applet allows extensions to replace one page (Background), so the IShellPropSheetExt::ReplacePage() method is called once. An extension can just return S_OK if it doesn't want to replace the page. If the extension does want to replace the page, it creates a new property page and the applet displays it in place of the built-in Background page.

The prototype for ReplacePage() is:

HRESULT IShellPropSheetExt::ReplacePage (
    UINT uPageID,
    LPFNADDPROPSHEETPAGE lpfnReplaceWith,
    LPARAM lParam );

The parameters are:

uPageID
A constant from cplext.h that indicates which page the applet is querying for. For example, the Display applet calls ReplacePage() with uPageID set to CPLPAGE_DISPLAY_BACKGROUND to indicate the extension can replace the Background page. In applets that allow more than one page to be replaced (such as the Mouse applet), ReplacePage() is called once for each page.
lpfnReplaceWith, lParam
lpfnReplaceWith is a function pointer that the extension calls to actually replace the page. lParam is a value that's meaningful to the shell and gets passed to the lpfnReplaceWith function.

The process for replacing a page is pretty much the same as adding a page. Our extension fills in a PROPSHEETPAGE struct, creates a page, and calls the lpfnReplaceWith function to replace the Background page. The sample page has no controls on it; the purpose is just to show how to get pages in the Display applet. I'm assuming that you're able to code a dialog proc for the page; if you need help with this, check out other articles on property sheets at CodeProject.

Here's the code for our ReplacePage() method. We first verify that uPageID is a value we expect.

#include <cplext.h>

STDMETHODIMP CDisplayCplExt::ReplacePage ( UINT uPageID, 
                                           LPFNADDPROPSHEETPAGE lpfnReplaceWith,
                                           LPARAM lParam )
{
    <FONT COLOR="#009900">// Check that we're being called with the page ID we expect.</FONT>
    if ( CPLPAGE_DISPLAY_BACKGROUND != uPageID )
        return S_OK;

We then fill in a PROPSHEETPAGE struct. The code here references the dialog proc and a callback function, which I'll get to in a bit.

PROPSHEETPAGE  psp;
HPROPSHEETPAGE hPage;

    <FONT COLOR="#009900">// Set up the PROPSHEETPAGE struct.</FONT>
    ZeroMemory ( &psp, sizeof(PROPSHEETPAGE) );

    psp.dwSize      = sizeof(PROPSHEETPAGE);
    psp.dwFlags     = PSP_USEREFPARENT | PSP_DEFAULT | PSP_USECALLBACK;
    psp.hInstance   = _Module.GetResourceInstance();
    psp.pszTemplate = MAKEINTRESOURCE(IDD_REPLACEPAGE);
    psp.pfnDlgProc  = ReplacementPageDlgProc;
    psp.pfnCallback = ReplacementPageCallbackProc;
    psp.pcRefParent = (UINT*) &_Module.m_nLockCnt;

We then create a page and pass it to the lpfnReplaceWith function.

    <FONT COLOR="#009900">// Create the page & get a handle.</FONT>
    hPage = CreatePropertySheetPage ( &psp );

    if ( NULL != hPage )
        {
        <FONT COLOR="#009900">// Call the shell's callback function, so it adds the page to
        // the property sheet.</FONT>
        if ( !lpfnReplaceWith ( hPage, lParam ))
            {
            DestroyPropertySheetPage ( hPage );
            }
        }

    return S_OK;
}

There are two additional functions, ReplacementPageDlgProc and ReplacementPageCallbackProc. You can check out the code in the sample project; they are just skeletons since the page has no controls.

Note that shell version 4.71 and later includes a Display extension that has a Background page replacement, so if you use the above code without disabling the shell's own extension, you'll still see a Background tab, as shown here:

 [Our page with the shell's page - 13K]

An extension can also add any number of pages to the property sheet from its AddPages() method. This is done just as in normal property sheet extensions, and the code is almost identical to the ReplacePage() code above. Check out the sample project if you're dying to see the code.

The sample extension adds one page to the Display applet in AddPages(), and here are the final results:

 [Our replacement page - 8K]

 [Our additional display page - 7K]

Registering the Extension

The Control Panel applets that can be customized have their own area of the registry in HKEY_LOCAL_MACHINE. Unfortunately, the registry key used to extend the main Display property sheet is different on 9x and 2000, so we can't register our extension with an RGS script. On Windows 9x, it's

HKLM\Software\Microsoft\Windows\CurrentVersion\Controls
Folder\<FONT COLOR="#009900">Display</FONT>\shellex\PropertySheetHandlers
, and on Windows 2000 it's
HKLM\Software\Microsoft\Windows\CurrentVersion\Controls
Folder\<FONT COLOR="#009900">Desk</FONT>\shellex\PropertySheetHandlers
. We create a new key under PropertySheetHandlers for our extension in DllRegisterServer(), and remove the key in DllUnregisterServer().

I don't have an NT 4 system handy to check which registry key it uses, so for the time being the registration code treats NT 4 the same as Win 2000. I'd appreciate it if a kind reader could check on NT 4 for me, and let me know if the code is using the wrong key.

Debugging Control Panel Extensions

It's easy to debug a Control Panel extension in the Visual C debugger, once you know what debug settings to use. Microsoft Knowledge Base articles Q166168 and Q135068 have a good description of how to do it, but I'll give a quick summary here.

In your project settings, go to the Debug tab and set the executable to "rundll32.exe". The program arguments should be "shell32.dll,Control_RunDLL" followed by the full path to the CPL file that contains the applet. (Note that the "Control_RunDLL" part is case-sensitive.) It's not always obvious which CPL file to use, so here are some common ones:

Applet

Arguments (change "C:\windows\system" if you have Windows installed in some other directory)

Display

shell32.dll,Control_RunDLL C:\windows\system\desk.cpl

Mouse

shell32.dll,Control_RunDLL C:\windows\system\main.cpl

Keyboard

shell32.dll,Control_RunDLL C:\windows\system\main.cpl,@1

The "@1" part indicates which applet in main.cpl to run. (CPL files can contain more than one applet; adding @n runs applet number n, where n is a 0-based count.)

Here's a screen shot that demonstrates the settings, in case things still are a bit unclear:

 [Debug settings - 7K]

When you start debugging, rundll32 will call the Control_RunDLL function in the shell, which in turn will launch the Control Panel applet. To end debugging, just close the applet's window.

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here


Written By
Software Developer (Senior) VMware
United States United States
Michael lives in sunny Mountain View, California. He started programming with an Apple //e in 4th grade, graduated from UCLA with a math degree in 1994, and immediately landed a job as a QA engineer at Symantec, working on the Norton AntiVirus team. He pretty much taught himself Windows and MFC programming, and in 1999 he designed and coded a new interface for Norton AntiVirus 2000.
Mike has been a a developer at Napster and at his own lil' startup, Zabersoft, a development company he co-founded with offices in Los Angeles and Odense, Denmark. Mike is now a senior engineer at VMware.

He also enjoys his hobbies of playing pinball, bike riding, photography, and Domion on Friday nights (current favorite combo: Village + double Pirate Ship). He would get his own snooker table too if they weren't so darn big! He is also sad that he's forgotten the languages he's studied: French, Mandarin Chinese, and Japanese.

Mike was a VC MVP from 2005 to 2009.

Comments and Discussions

 
GeneralLinker errors coming while building in XP 64 bit Pin
Sandilya Bhagi18-May-09 2:17
Sandilya Bhagi18-May-09 2:17 
GeneralMMC Property Sheet Pin
alex@alexhitchins.com12-Aug-08 5:12
alex@alexhitchins.com12-Aug-08 5:12 
GeneralLnk file path Pin
john563214-Mar-08 2:41
john563214-Mar-08 2:41 
GeneralThis code is not working in 64 bit XP [modified] Pin
NleshForU31-Aug-06 3:03
NleshForU31-Aug-06 3:03 
GeneralMulti-language support for this class Pin
chueh819-Apr-06 21:58
chueh819-Apr-06 21:58 
General64-bit issue Pin
ccm21624-Jan-06 16:24
ccm21624-Jan-06 16:24 
GeneralRe: 64-bit issue Pin
Michael Dunn24-Jan-06 21:06
sitebuilderMichael Dunn24-Jan-06 21:06 
Questionproperty sheet for mmc snap-in? Pin
cycoder20-Sep-04 6:39
cycoder20-Sep-04 6:39 
AnswerRe: property sheet for mmc snap-in? Pin
Michael Dunn22-Sep-04 12:40
sitebuilderMichael Dunn22-Sep-04 12:40 
I've never written stuff for MMC, but I know MMC has its own snap-in system that's different from shell extensions. In VC 6, the ATL Object Wizard can make a skeleton snap-in for you, so that's a good place to start.

--Mike--
Personal stuff:: Ericahist | Homepage
Shareware stuff:: 1ClickPicGrabber | RightClick-Encrypt
CP stuff:: CP SearchBar v2.0.2 | C++ Forum FAQ

----
Laugh it up, fuzzball.
GeneralReplacePage for Drive Properties Pin
swati chawdhary1-Sep-04 22:49
swati chawdhary1-Sep-04 22:49 
GeneralHelp : Show the current time on new page Pin
david0729562-Feb-04 23:31
david0729562-Feb-04 23:31 
GeneralMarry that girl! Pin
Caddy16-Jun-03 16:49
Caddy16-Jun-03 16:49 
Generalgraphics in Property Sheet Pin
14-Jun-02 5:15
suss14-Jun-02 5:15 
Questionwhy I cant addpage on WIN 95 system? Pin
25-Mar-02 23:50
suss25-Mar-02 23:50 
AnswerRe: why I cant addpage on WIN 95 system? Pin
Michael Dunn2-Jun-02 18:33
sitebuilderMichael Dunn2-Jun-02 18:33 
Questionwhy Can't use COMBOBOXEX in this? Pin
6-Dec-01 18:49
suss6-Dec-01 18:49 
GeneralRemoving the page Pin
Binesh7-Nov-01 1:24
Binesh7-Nov-01 1:24 
GeneralInternet Options Extension Pin
Shaun Kaasten10-Jul-01 11:00
Shaun Kaasten10-Jul-01 11:00 
GeneralRe: Internet Options Extension Pin
Michael Dunn10-Jul-01 19:26
sitebuilderMichael Dunn10-Jul-01 19:26 
GeneralRe: Internet Options Extension Pin
Shaun Kaasten10-Jul-01 20:16
Shaun Kaasten10-Jul-01 20:16 
GeneralRe: Internet Options Extension Pin
Serge Baltic3-Jan-05 7:42
Serge Baltic3-Jan-05 7:42 
GeneralSomeone asked me about doing this in Delphi Pin
Michael Dunn19-Nov-00 19:00
sitebuilderMichael Dunn19-Nov-00 19:00 
GeneralRe: Someone asked me about doing this in Delphi Pin
omeran5-Aug-02 3:43
omeran5-Aug-02 3:43 
GeneralRegistering on NT4 Pin
Stuart Carter3-Nov-00 0:36
Stuart Carter3-Nov-00 0:36 
GeneralRe: Registering on NT4 Pin
Michael Dunn3-Nov-00 15:46
sitebuilderMichael Dunn3-Nov-00 15:46 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.