free web page counters

Windows Mobile Pocket PC Smartphone Programming

==>Click here for the SiteMap<==. Original contents with decent amount of source codes.

Friday, February 03, 2006

How to put your own Control Panel Applet to "Personal" Group?

====>SiteMap of this Blog<===

How to put your own Control Panel Applet to "Personal" Group?

In Pocket PC 2003 and Pocket PC 5.0, there are three groups of Control Panel Applets: "Personal", "System" and "Connection". Looks like if you simply build a CPL file and export "CPlApplet" function, your Applet will be displayed in the "System" group. No exception is mine. However, quite some users and managers along my management chain think that our Control Panel Applet should be put into "Personal" group. I agree. It is used by the user to control his preferred email-reading-and-composing behavior, which apparently, has nothing to do with any system-wide activity. So I was dispatched the task to drop the Applet to "Personal" group.

I failed to find any useful documentation by searching in major searching engines and MSDN documentation, at the time when I was starting to working on it. I do found an unfamiliar CPL_IDNAME message, with the following description in Pocket PC 2003 SDK documentation:

This message is sent to the Control Panel application to retrieve its unique name string. This string can be used to find its data in the registry.

Man, guess no people can understand what the heck is "... to find its data in the registry...". So I decide to take a look at Pocket PC 5.0 SDK documentation, hoping I could find more up-to-date explanation:

The CPL_IDNAME message is sent to the CPlApplet function to retrieve a Control Panel application's unique ID name string.

Handling of this message is required only if the application icon exists in a Settings application tab other than the default System tab. When this message is received, the CPlApplet function must copy the ID name of the application (specified by uAppNum) into the pszName parameter. The ID name can be used to retrieve or set information about the application via the registry subkey [HKEY_LOCAL_MACHINE\ControlPanel\<IDname>]. The primary data under this subkey is "Group" = dword:1. The possible values for the Group data indicate the tab of the Settings application where the application icon exists.

Yes, there we are. So below are what we need to do to list the CPL in "Personal" Group, whose group number is 0. Assume the IDName is called "TestingApp". By the way, this name does not need to be your real application name.

Must-Do 1: Register the ID Name in the specified registry hive. You can put the following code in your setup DLL's Install_Exit function.

    // Set up registry keys
    // [HKEY_LOCAL_MACHINE\ControlPanel\TestingApp\]
    // Groupe=dword:0
    TCHAR szKeyBase[MAX_PATH];
    _tcscpy(szKeyBase, TEXT("\\ControlPanel\\TestingApp"));
    LRESULT lr = Registry_SetDWordValue(HKEY_LOCAL_MACHINE,
              szKeyBase, TEXT("Group"), dwGroup);

Must-Do 2: Respond to CPL_IDNAME in CPlApplet function.
    case CPL_IDNAME:
      UINT uApp = lParam1;
      LPWSTR pszName = (LPTSTR)lParam2;
      _tcscpy(pszName, TEXT("TestingApp"));
      return 0;

Must-Do 3: Remember to remove the registry hive in your un-Install code. You can put such code in your setup DLL's Uninstall_Exit function.

Alternatively, you do not really need to write code for Must-Do 1 and Must-Do 3. In your .INF file for CabWiz, adding the following sections:

    CopyFiles      = XXXXX
    AddReg         = Reg.CPLApplet

    ; assuming you alrady defined AppName=TesinngApp

That is it! Microsoft Cab installer will take care the steps to add the registry key during installation, and remove the registry key during un-installation.

Below is a screen cut showing "TestingApp" is put into "Personal" group:

putting demostration Pocket PC Control Panel Applet into Personal Group

Category: [Control Panel]

====>SiteMap of this Blog<===