Using CPLApplet
Prior to Windows Vista, you created a Control Panel item by creating a .dll file and naming it with a .cpl extension. This file exported the CPlApplet function. This scheme is still supported in Windows Vista and later versions and is discussed in this topic. However, the guidelines for new Control Panel items recommend a simpler approach with the Control Panel item built as a .exe file that uses a task flow layout.
When Control Panel loads a .dll (or .cpl) file, it calls the CPlApplet function to get information such as the number of Control Panel items the file hosts, as well as information about each item. Control Panel also calls the function when the item's window is initialized, opened, or closed.
When Windows first loads the Control Panel item, it retrieves the address of the CPlApplet function and subsequently uses that address to call the function and pass it messages. It might send the following messages.
| Message | Description |
|---|---|
| CPL_DBLCLK | Sent to notify CPlApplet that the user has chosen the icon associated with a given Control Panel item. CPlApplet should display the dialog box for the specified item and carry out any user-specified tasks. The CPlApplet lParam1 parameter is an integer that represents the zero-based index of the Control Panel item. The lParam2 parameter is the lpData pointer returned in the CPLINFO or NEWCPLINFO structure in the CPL_INQUIRE or CPL_NEWINQUIRE message. The return value is ignored. |
| CPL_EXIT | Sent after the last CPL_STOP message and immediately before Windows uses the FreeLibrary function to free the DLL that contains the Control Panel item. CPlApplet should free any remaining memory and prepare to close. The return value is ignored. |
| CPL_GETCOUNT | Sent after the CPL_INIT message to prompt CPlApplet to return a number that indicates how many subprograms it supports. |
| CPL_INIT | Sent immediately after the DLL that contains the Control Panel item 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 subprogram. The lParam1 value is an integer that represents the zero-based index of the subprogram about which information is being requested. The lParam2 parameter of CPlApplet points to a CPLINFO structure. The return value is ignored. |
| CPL_NEWINQUIRE | Sent after the CPL_GETCOUNT message to prompt CPlApplet to provide information about a specified Control Panel item. The lParam1 value is an integer that represents the zero-based index of the subprogram about which information is being requested. The lParam2 parameter is a pointer to a NEWCPLINFO structure. CPL_NEWINQUIRE normally should be ignored. Your application should process only CPL_INQUIRE on Windows 95, Microsoft Windows NT 4.0, and later systems since Control Panel performance suffers when CPL_NEWINQUIRE is used. This is because the returned strings and icons cannot be cached. The return value is ignored. |
| CPL_SELECT | Obsolete. Current versions of Windows do not send this message. |
| CPL_STARTWPARMS | 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. This message is similar to CPL_DBLCLK, but there might be some additional information. The lParam1 parameter is the Control Panel item number and lParam2 is an LPCTSTR to any extra directions that might be necessary. Return TRUE if this message is handled; otherwise, FALSE. This message is valid for version 5.00 and later of Shell32.dll. |
| CPL_STOP | Sent once for each Control Panel item in the .cpl file before Windows unloads the Control Panel extension. CPlApplet should free any memory associated with the item number provided in lParam1. The lParam2 parameter is lpData pointer returned in the CPLINFO or NEWCPLINFO structure in the CPL_INQUIRE or CPL_NEWINQUIRE message. The return value is ignored. |
Related topics