PocketPC-Adding a Permanent Menu Entry to the New Button Menu

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. Because I've seen that 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 the PocketPC SDK for reference. Through this brief tutorial I will show you 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 such as Contacts, New E-mail Messages, or document types such as Word documents, Excel wordbooks, and so forth. The New Button and all individual menu entries can be enabled and disabled in the New Menu property page that comes up thru Start->Settings->Menus and clicking 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 fewer than 10 lines of code if you are using a framework such as ATL for your COM object.

COM Addin

Custom items can be added to the New button popup menu through a COM addin. There are two ways to add entries to the New button menu—Dynamic and thru a COM Addin. Dynamic means that 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 a 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 addin. 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.

Thru a COM addin, 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 such as New Appointment, New Contact, Notes, Tasks, and so on. These are basically COM addins 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 addin.

Registry

As with a shell extension, a custom menu extension needs to add a few Registry entries. The following keys are important.

Getting Started

Here, we'll be creating a COM addin with ATL that adds a custom menu entry to the New button. Next, we'll see how to handle click events in our addin. So, fire up the 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, open the MenuHandler.rgs resource file, and add the following script.

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 based on the CLSID's having created the COM object. You probably would like to do something useful, such as 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 simply uses the ShellExecuteEx API to launch an instance of the Pocket PC Welcome screen (welcome.exe) executable, like this: