Introduction
For a PocketPC application that I was writing recently, one of my tasks was to add a custom menu entry to the PocketPC New Button Menu. Since I've seen the topic gets asked enough times on Pocket PC programming forums, I thought I'd write something to this end. Of course you can always look through the documentation to New Menu items that comes along with PocketPC SDK for reference. Through this brief tutorial I will show you, what are the steps involved to do this. The sample project adds such menu items and handles respective menu clicks.
I assume you are a PocketPC programmer developing with eMbedded Visual C++ 3.0 and have some experience programming COM, although newbie eVC++ programmers shouldn't have any problems following.
Overview
The New button, present at the bottom of the PocketPC Today screen, allows the user to quickly create a new item of any type and launches the parent application. Clicking the New button displays a popup menu, that consists of a list of menu items, each of which gives the user quick access to commonly used items like Contacts, New Email Message or document types like Word Documents, Excel workbooks etc. The New button and all individual menu entries can be enabled and disabled in the New Menu property page that comes up through Start->Settings->Menus and clicking on the New Menu tab.
Adding custom menu items to the New button menu is very easy, as you will find out. The cool thing here is that, you can do all this with less than 10 lines of code if you are using a framework like ATL for your COM object.
COM Add-in
Custom items can be added to the New button popup menu through a COM add-in. There are two ways to add entries to the New button menu - Dynamic and thru a COM Add-in. Dynamic means - a notification message (NMN_GETAPPREGKEY) is received by the application when it is in the foreground and the New menu is clicked. The NMNEWMENU pointer passed as parameter to this notification message can be used to add/modify entries to the New button menu. However in this article, our discussion is restricted to a COM add-in. So if you are interested in dynamically adding entries, please take a look at the documentation regarding the NMNEWMENU structure and the NMN_GETAPPREGKEY notification message at MSDN.
Through a COM add-in a new custom entry to the New menu button's popup menu can be created. Such a component is like a Windows shell extension and such a menu addition will be more permanent in nature. You probably have seen the New menu submenus like New Appointment, New Contact, Notes, Tasks etc. These are basically COM add-ins that appear at all times. The documentation advises that an application should add a single menu item to the New button menu via a COM add-in.
Registry
Like a shell extension, a custom menu extension needs to add a few registry entries. The following keys are of importance:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Shell\Extensions\NewMenu
\CLSID = <menu string>
\Enabled = DWORD
HKEY_CLASSES_ROOT\CLSID\
\CLSID\InprocServer = <component dll location>
Getting started
Here, we'll be creating a COM add-in with ATL, that adds a custom menu entry to the New button. Next we'll see how to handle click event in our add-in. So fire up eVC++ IDE and use the WCE COM ATL Appwizard to create a new ATL COM project. After you have saved the project, use the Insert->New ATL Object menu to add a new ATL simple object to your project called MenuHandler (Choose all defaults and click ok).
First up, the necessary registry routines. Go to FileView and open the MenuHandler.rgs resource file and add the following script.
HKLM
{
SOFTWARE
{
Microsoft
{
Shell
{
Extensions
{
NewMenu
{
ForceRemove
{7EB8A0D7-7D17-44CC-A74A-00DC6AB30734} = s 'Clickety'
{
val Enabled = d '1'
}
}
}
}
}
}
}
Luckily, the code to create the registry keys, necessary to register the COM DLL, has already been added to our registry script by the ATL Object Wizard and we don't have to bother with those keys.
When our menu entry is clicked, the shell enumerates the NewMenu registry key and based on the CLSIDs creates the COM object. You probably would like to do something useful, like run your app when your 'App Document' menu item is clicked. Here to handle a 'Clickety' click, we add code to our project's ATL class. The class constructor simple uses the ShellExecuteEx API to launch an instance of the Pocket PC Welcome screen (welcome.exe) executable like:
SHELLEXECUTEINFO sei;
ZeroMemory(&sei, sizeof(SHELLEXECUTEINFO));
sei.cbSize = sizeof(SHELLEXECUTEINFO);
sei.lpFile = _T("\\windows\\welcome.exe");
sei.nShow = SW_SHOW;
ShellExecuteEx(&sei);
But in your application, for example, you could run the following code to run your app and open new document when your 'New App Document' menu is clicked:
sei.lpFile = _T("\\windows\\myapp.exe");
sei.lpParameters = _T("-new");
ShellExecuteEx(&sei);
That's it. To disable the add-in menu entry, change Enabled to DWORD 0. To remove it unregister the component DLL.
Enjoy!
References
Others
Yes - 'The Ladder' album which I seem to listen to incessantly. :)
