Control Panel Applications


		Contents Index Topic Contents
	Previous Topic: Briefcase Reconcilers Next Topic: Debugging With the Shell

Control Panel Applications

Control Panel applications are special-purpose dynamic-link libraries (DLLs) that let users configure the environment of Microsoft® Windows®.
This section describes Control Panel applications and explains the functions and messages that these applications use and process to complete their work.
About Control Panel Applications

Creating Control Panel Applications

About Control Panel Applications

Though Windows provides a number of standard Control Panel applications, you can create additional applications that let users examine and modify the settings and operational modes of specific hardware and software.
Application Responsibilities and Operation

The primary responsibility of any Control Panel application is to display a dialog box and to carry out any tasks specified by the user. Despite this responsibility, Control Panel applications do not provide menus or other direct means for users to access their dialog boxes. Instead, these applications operate under the control of another application and display their dialog boxes only when requested by the controlling application.
Control Panel applications are usually controlled by a Windows system utility specifically designed to give users access to these applications, such as the mouse Control Panel application. However, any application can load and manage Control Panel applications as long as the controlling application sends messages and processes return values in the way that the Control Panel applications recognize.
Most Control Panel applications display and manage a single dialog box, giving the user control of the settings and operational modes of a single system component. However, any given Control Panel application can provide any number of dialog boxes to control any number of system components. To distinguish between dialog boxes, a Control Panel application typically supplies the controlling application with a unique icon for each dialog box. The controlling application displays these icons, and the user can choose a dialog box by choosing the corresponding icon.
Application Entry-Point Function

Every Control Panel application must export the standard entry-point function, CPlApplet. This function receives requests in the form of Control Panel (CPL) messages and then carries out the requested work—initializing the application, displaying and managing the dialog box(es), and closing the application.
When the controlling application first loads the Control Panel application, it retrieves the address of the CPlApplet function and subsequently uses the address to call the function and pass it messages. The controlling application may send the following messages:

Message Description

CPL_DBLCLK Sent to notify CPlApplet that the user has chosen the icon associated with a given dialog box. CPlApplet should display the corresponding dialog box and carry out any user-specified tasks.

CPL_EXIT Sent after the last CPL_STOP message and immediately before the controlling application uses the FreeLibrary function to free the DLL containing the Control Panel application. CPlApplet should free any remaining memory and prepare to close.

CPL_GETCOUNT Sent after the CPL_INIT message to prompt CPlApplet to return a number that indicates how many dialog boxes it supports.

CPL_INIT Sent immediately after the DLL containing the Control Panel application is loaded. The message prompts CPlApplet to perform initialization procedures, including memory allocation.

CPL_INQUIRE Sent after the CPL_GETCOUNT message to prompt CPlApplet to provide information about a specified dialog box. The lParam2 parameter of CPlApplet points to a CPLINFO structure.

CPL_NEWINQUIRE Sent after the CPL_GETCOUNT message to prompt CPlApplet to provide information about a specified dialog box. The lParam2 parameter is a pointer to a NEWCPLINFO structure. For better performance on Microsoft® Windows® 95 and Windows NT® version 4.0, your application should process CPL_INQUIRE and not CPL_NEWINQUIRE.

CPL_SELECT This message is obsolete. Current versions of Windows do not send this message.

CPL_STOP Sent once for each dialog box before the controlling application closes. CPlApplet should free any memory associated with the given dialog box.

Message Processing

The CPlApplet callback function processes all messages sent to a Control Panel application by a controlling application. Messages sent to the function should be in a specific order. By the same token, the application requires the messages to be processed in a specific way.
First, the CPlApplet function receives the CPL_INIT message when the controlling application first loads the Control Panel application. The function should carry out any initialization, such as allocating memory, and return nonzero. If CPlApplet cannot complete the initialization, it must return zero, directing the controlling application to terminate communication and release the DLL.
Next, if the CPL_INIT message succeeded, the controlling application sends the CPL_GETCOUNT message. The function must then return the number of dialog boxes supported by the Control Panel application.
The CPlApplet function then receives one CPL_INQUIRE message and one CPL_NEWINQUIRE message for each dialog box supported by the Control Panel application. The function fills in a CPLINFO or NEWCPLINFO structure with information about your application, such as its name, icon, and a descriptive string. Most applications should process the CPL_INQUIRE message and ignore the CPL_NEWINQUIRE message. The CPL_INQUIRE message provides information in a form that the controlling application can cache, resulting in much better performance. The CPL_NEWINQUIRE message is useful only if you need to change your application's icon or display strings based on the state of the computer.
The CPlApplet function next receives a CPL_DBLCLK message as a notification that the user has chosen the icon representing the dialog box. The function may receive this message any number of times. The message includes the dialog box identifier and the value contained in the lData parameter. The function should display the corresponding dialog box and process subsequent user input.
Before the controlling application terminates, CPlApplet receives the CPL_STOP message once for each dialog box supported by the Control Panel application. The message includes the identifier for the dialog box and the lData value. The function should free any memory that it allocated for the specified dialog box.
After the last CPL_STOP message, CPlApplet receives a CPL_EXIT message. The function should free all remaining allocated memory and unregister any private window classes that it may have registered. Immediately after the function returns from this message, the controlling application releases the Control Panel application by calling the FreeLibrary function.
Application Setup

Every Control Panel application is a dynamic-link library. To make sure the DLL containing your Control Panel application can be located and automatically loaded by the Windows system utility, the DLL file must have the CPL file name extension and must be set up in one of the following ways:
Copied to the directory that contains the Windows system utility.
Copied to the Windows SYSTEM directory.
Registered under the MMCPL key of the HKEY_CURRENT_USER key in the registry.

You should register the DLL in the registry if the DLL exports functions other than CPlApplet and provides functionality beyond the scope of a Control Panel application.
Creating Control Panel Applications

Although a Control Panel application may support more than one dialog box, it processes all requests through the single CPlApplet function. In the following example, the Control Panel application supports three dialog boxes that let the user set preferences for a component stereo system attached to the computer. The example uses an application-defined StereoApplets array that contains three structures, each corresponding to one of the dialog boxes. Each structure contains all the information required by the CPL_INQUIRE message as well as the dialog box template and dialog box procedure required by the CPL_DBLCLK message. The code demonstrates how to fill the structures in the StereoApplets array.
#define NUM_APPLETS 3 
 
typedef struct tagApplets 
{ 
    int icon;         // icon resource identifier 
    int namestring;   // name-string resource identifier 
    int descstring;   // description-string resource identifier 
    int dlgtemplate;  // dialog box template resource identifier 
    DLGPROC dlgfn;    // dialog box procedure 
} APPLETS; 
 
APPLETS StereoApplets[NUM_APPLETS] = 
{ 
    AMP_ICON, AMP_NAME, AMP_DESC, AMP_DLG, AmpDlgProc, 
    TUNER_ICON, TUNER_NAME, TUNER_DESC, TUNER_DLG, TunerDlgProc, 
    TAPE_ICON, TAPE_NAME, TAPE_DESC, TAPE_DLG, TapeDlgProc, 
}; 

HANDLE  hinst = NULL;

LONG CALLBACK CPlApplet(hwndCPL, uMsg, lParam1, lParam2) 
HWND hwndCPL;      // handle to Control Panel window 
UINT uMsg;         // message 
LPARAM lParam1;    // first message parameter 
LPARAM lParam2;    // second message parameter 
{ 
    int i; 
    LPCPLINFO lpCPlInfo; 
 
    i = (int) lParam1; 
 
    switch (uMsg) { 
        case CPL_INIT:      // first message, sent once 
            hinst = GetModuleHandle("ecp.cpl"); 
            return TRUE; 
 
        case CPL_GETCOUNT:  // second message, sent once 
            return NUM_APPLETS; 
            break; 
 
        case CPL_INQUIRE: // third message, sent once per application 
            lpCPlInfo = (LPCPLINFO) lParam2; 
            lpCPlInfo->lData = 0; 
            lpCPlInfo->idIcon = StereoApplets[i].icon;
            lpCPlInfo->idName = StereoApplets[i].namestring;
            lpCPlInfo->idInfo = StereoApplets[i].descstring;
            break; 

        case CPL_DBLCLK:    // application icon double-clicked 
            DialogBox(hinst, 
                MAKEINTRESOURCE(StereoApplets[i].dlgtemplate), 
                hwndCPL, StereoApplets[i].dlgfn); 
            break; 
 
        case CPL_STOP:      // sent once per application before CPL_EXIT 
            break; 
 
        case CPL_EXIT:    // sent once before FreeLibrary is called 
            break; 
 
        default: 
            break; 
    } 
    return 0; 
} 
 
Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.

Message	Description
CPL_DBLCLK	Sent to notify CPlApplet that the user has chosen the icon associated with a given dialog box. CPlApplet should display the corresponding dialog box and carry out any user-specified tasks.
CPL_EXIT	Sent after the last CPL_STOP message and immediately before the controlling application uses the FreeLibrary function to free the DLL containing the Control Panel application. CPlApplet should free any remaining memory and prepare to close.
CPL_GETCOUNT	Sent after the CPL_INIT message to prompt CPlApplet to return a number that indicates how many dialog boxes it supports.
CPL_INIT	Sent immediately after the DLL containing the Control Panel application is loaded. The message prompts CPlApplet to perform initialization procedures, including memory allocation.
CPL_INQUIRE	Sent after the CPL_GETCOUNT message to prompt CPlApplet to provide information about a specified dialog box. The lParam2 parameter of CPlApplet points to a CPLINFO structure.
CPL_NEWINQUIRE	Sent after the CPL_GETCOUNT message to prompt CPlApplet to provide information about a specified dialog box. The lParam2 parameter is a pointer to a NEWCPLINFO structure. For better performance on Microsoft® Windows® 95 and Windows NT® version 4.0, your application should process CPL_INQUIRE and not CPL_NEWINQUIRE.
CPL_SELECT	This message is obsolete. Current versions of Windows do not send this message.
CPL_STOP	Sent once for each dialog box before the controlling application closes. CPlApplet should free any memory associated with the given dialog box.