Control Panel Message Processing

  • Article

The CPlApplet callback function processes all messages sent to a Control Panel item by Microsoft Windows. Messages sent to the function are in a specific order. By the same token, the .cpl item requires the messages to be processed in a specific way.

First, the CPlApplet function receives the CPL_INIT message when Windows first loads the Control Panel item. 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 Windows to terminate communication and release the DLL.

Next, if the CPL_INIT message succeeded, Windows sends the CPL_GETCOUNT message. The function must then return the number of Control Panel items supported by the .dll file.

The CPlApplet function then receives one CPL_INQUIRE message and one CPL_NEWINQUIRE message for each Control Panel item supported by the .dll file. The function fills in a CPLINFO or NEWCPLINFO structure with information about your item, 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 Windows can cache, which results in much better performance. The CPL_NEWINQUIRE message is used only if you need to change your item's icon or display strings based on the state of the computer. Control Panel items that use CPL_NEWINQUIRE cannot be found by a Start menu search in Windows Vista because it relies on caching.

The CPlApplet function next receives a CPL_DBLCLK message as a notification that the user has chosen the icon that represents the Control Panel item. The function might receive this message any number of times. The message includes the item identifier and the lpData pointer returned in the CPLINFO or NEWCPLINFO structure in the call to CPL_INQUIRE or CPL_NEWINQUIRE. The function should display the corresponding dialog box and process subsequent user input.

Besides CPL_DBLCLK, the CPL_STARTWPARMS message can be sent if a Control Panel item is invoked with input parameters, such as from a command prompt or from another program. The message includes the item identifier along with the additional parameter string.

Before the controlling application terminates, CPlApplet receives the CPL_STOP message once for each Control Panel item supported by the .dll file. The message includes the identifier for the Control Panel item and the lpData pointer returned in the CPLINFO or NEWCPLINFO structure in the call to CPL_INQUIRE or CPL_NEWINQUIRE. 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 might have registered. Immediately after the function returns from this message, Windows releases the Control Panel item by calling the FreeLibrary function.