CPL++ v1.30

Welcome to CPL++, An MFC class framework to encapsulate developing DLL based Control Panel Applets.

Usage

• As of v1.29, the classes are now designed for VC 2005 or later. They will not compile on earlier releases of VC.
• Ensure your DLL has a DEF file and exports at a minimum the function CPlApplet. Note: You do not need to write this function as it is provided internally by the CPL++ code.
• Use the DECLARE_CPLAPP / IMPLEMENT_CPLAPP macros to hook up the main control panel applet callback function for your applet.
• Use the DECLARE_CPLREGISTER / IMPLEMENT_CPLREGISTER_FOR_ALL_USERS / IMPLEMENT_CPLREGISTER_FOR_CURRENT_USER macros if you want to make your applet self registering so that it can be registered / unregistered just like any COM dll. Please note that even though we are using these COM registration functions, this is just a convenience and your code need not do anything COM related, in fact it does not even need to initialize the COM libraries. This division of labour is based on the ATL registration design pattern. For more info on the how's and why's of Applet Registration, please consult the MSDN. If you are supporting registration, then you also need to export "DllRegisterServer" and "DllUnregisterServer" in your def file. Please note that Windows best practices is that your install should implement registration and unregistration using the MSI declarative model rather than using "regsvr32" style registration.
• Ensure cpl.h is included in your DLL's stdafx.h header file. These pull in the various Control Panel Applet defines.
• Include "cpl_pp.h" and "cpl_pp.cpp" in your project (configured to produce a standard DLL including MFC either dynamically or statically).
• Derive a class from CControlPanelApp and override its OnInit function. In it call AddApplet to add each applet you want. Normally this you would do this just once, but for demonstration purposes, the sample creates two applets.
• Each applet you add should be an instance of the class "CControlPanelApplet". It should be created on the heap. See CApp::OnInit() for an example. Depending on which constructor you call, you will have created an dynamic (responds to CPL_NEWINQUIRE) or static (responds to CPL_INQUIRE) control panel applet.
• The code is UNICODE enabled and UNICODE build configurations are provided for the test applet.
• The CPL++ framework is for developing DLL based control panel applets. As of Windows Vista, you can also create control panel applets as exes. For more information about these type of applets, please consult the MSDN.
• For further information on developing and debugging control panel applets, please refer to the MSDN.

Copyright

• You are allowed to include the source code in any product (commercial, shareware, freeware or otherwise) when your product is released in binary form.
• You are allowed to modify the source code in any way you want except you cannot modify the copyright details at the top of each module.
• If you want to distribute source code with your application, then you are only allowed to distribute versions released by the author. This is to maintain a single distribution point for the source code.

History

V1.0 (18 July 1999)

• First public release.

V1.1 (20 November 1999)

• Now fully supports CPL_INQUIRE as well as CPL_NEWINQUIRE messages.
• Now supports a document template approach to creating applets. This means that you can easily support multiple applets per dll using the CPL++ framework.
• Demo program now supports demo'ing both static and dynamic applets.
• Control panel applet now always output as a ".cpl" file instead of a ".dll" file.
• Now supports displaying the specified property page (via the CPL_STARTWPARMS message) when a control panel applet is called via the rundll32 command line.

V1.2 (8 August 2002)

• Included copyright message in source code.
• Now includes framework code to register and unregister the applet as per new Windows 2000 coding guidelines. See the MSDN for further details. This basically means that you do not need to copy your applet into the Windows System directory for it to be recognized by the OS. Thanks to Armen Hakobyan for this suggestion.
• Updated the sample applet to use standard COM registration methods of  DllRegisterServer and DllUnregisterServer. This allows your applets to be self-registering thro standard apps such as regsvr32.
• Updated demo applet to remove non-existent resources.

V1.21 (2 October 2002)

• Fixed small typo in the help file. Thanks to "Marty" for spotting this.
• Implemented DECLARE_CPLAPP / IMPLEMENT_CPLAPP and DECLARE_CPLREGISTER macros. This keeps client code as clean as possible. Basically something similar to the MFC / ATL macros.
• Made the CPlApplet call-back function visible in the public names space again through the use of the DECLARE_CPLAPP macro. This means that the class framework can be safely used in an MFC extension DLL. Thanks to Armen Hakobyan for the last 2 great updates.

• Fixed an issue / bug in the registration process methods where the Applet name had spaces in it. For some reason the Control Panel does not like this. The code now registers using a name which has "_" in place of spaces.

V1.22 (21 October 2002)

• Now supports registration of a Category. This is a new feature in Windows XP and Windows Server 2003 where control panel applets can be grouped into a category. For more info on the available categories, please see the MS KB article Q292463. Thanks to Pykälämäki Juha for suggesting this improvement.

V1.23 (4 June 2003)

• Creation of CDialog based applets now correctly observe the parent window as passed into it. Thanks to Vijay Chegu for suggesting the fix for this.

V1.24 (18 March 2004)

• Updated the sample app settings, to support debugging the sample applet. Please note that if you do not have Windows installed to C:\Windows then you will need to change your project's Debug settings to point to your Windows installation directory. Unfortunately I was unable to find a way to handle this automatically.
• Fixed an issue with the support for CPL_STARTWPARAMS on XP. Thanks to Jon Baggott for researching this area and providing the fix.
• The Framework and sample applet now correctly sets up support for XP Visual Styles. Because of this you will need to have a recentish copy of the Platform SDK installed to get the correct defines for "RT_MANIFEST".
• Moved framework and sample app up to VC 6.

V1.25 (23 July 2004)

• Now uses relative paths for debugging settings. This means that so long as you install the sample app on your system drive then debugging of the sample app will work out of the box.
• In CControlPanelApp::RegisterAppletViaRegistry(), Fixed an issue where the Cpls regkey doesn't always exist and registration via regsvr32 fails with return code 80020007 (if memory serves), which is a file not found error. This can be fixed by changing the call to RegOpenKeyEx to RegCreateKeyEx. Thanks to Jason Slater for reporting this issue. This change is also applied to the function CControlPanelApp::RegisterCategory which registers a Control Panel Applet's Category.

V1.26 (11 November 2004)

• Fixed a number of compiler warnings when the Detect 64 bit compatibility issues option is enabled in Visual Studio .Net.

V1.27 (7 July 2006)

• Updated copyright details.
• Code now uses newer C++ style casts instead of C style casts.
• Updated documentation to use the same style as the web site.
• Replaced calls to ZeroMemory with memset.
• Removed various unused destructors from the sample applet provided with the code.
• Updated the code to clean compile on VC 2005.
• Code now uses SEVERITY_ERROR define for MAKE_HRESULT calls.
• Updated the definition of all the virtual CControlPanelApp and CControlPanelApplet functions to use the same layout as defined by the MSDN. If you are upgrading your code, please ensure you review your code to match the new layout.

22 July 2006

• Updated documentation to refer to need for Platform SDK if compiling with VC 6.

V1.28 (6 August 2006)

• Fix for some compiler errors when the code is compiled for Win64.

V1.29 (12 April 2009)

• Updated copyright details.
• Removed VC 6 style classwizard comments from the code.
• Updated code to compile correctly using _ATL_CSTRING_EXPLICIT_CONSTRUCTORS define
• The code now only supports VC 2005 or later.
• Code now compiles cleanly using Code Analysis (/analyze)
• Updated code to clean compile on VC 2008.
• Now supports Vista specific registration using a GUID. This is required to support task links being associated with a Control Panel item.
• RegisterCategory now supports per user registration. It has also been renamed to RegisterXPCategory
• Now supports Vista specific category registration via RegisterVistaCategory.
• Now supports Vista multi category registration via RegisterVistaCategories
• Now supports Vista specific canonical name registration via RegisterCanonicalName
• Now supports Vista specific task link registration via RegisterTaskLinks
• RegisterApplet now has support for replacable parameters. The two supported values are %MODULE% which is the full path to the current DLL and %APPPATH% which represents the directory associated with %MODULE%.
• Now supports Vista specific safe mode registration via RegisterSafeMode
• Now supports XP multi category registration via RegisterXPCategories

V1.30 (7 September 2009)

• Fixed a bug in the declaration of IMPLEMENT_DYNAMIC(CControlPanelApp...). It was incorrectly setting the 2nd parameter to also be "CControlPanelApp". This was uncovered due to a change in the implementation of CDialog::DoModal in VC 2005. Thanks to Ivo Rytir for reporting this bug.

Contacting the Author

PJ Naughter
Email: pjna@naughter.com
Web: http://www.naughter.com
7 September 2009