Using CPLApplet

  • Article

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 discussed in this section. 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 Microsoft 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.