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

Environment: PocketPC, eVC3.0, emulation, MS Pocket PC SDK 2000/2002, Windows CE, ATL, COM, ActiveX, Automation.

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.

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 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.

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 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:

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 start your app and open a 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 addin menu entry, change Enabled to DWORD 0. To remove it, unregister the component DLL.

References

MSDN documentation

Downloads

PPCMenuButton project source - 23 Kb


Comments

  • Add menu button on PIM application

    Posted by Legacy on 05/02/2003 12:00am

    Originally posted by: Quy

    How can I add a menu button on PIM application, example Addressbook?

    Reply
Leave a Comment
  • Your email address will not be published. All fields are required.

Top White Papers and Webcasts

  • Learn How A Global Entertainment Company Saw a 448% ROI Every business today uses software to manage systems, deliver products, and empower employees to do their jobs. But software inevitably breaks, and when it does, businesses lose money -- in the form of dissatisfied customers, missed SLAs or lost productivity. PagerDuty, an operations performance platform, solves this problem by helping operations engineers and developers more effectively manage and resolve incidents across a company's global operations. …

  • Today's agile organizations pose operations teams with a tremendous challenge: to deploy new releases to production immediately after development and testing is completed. To ensure that applications are deployed successfully, an automatic and transparent process is required. We refer to this process as Zero Touch Deployment™. This white paper reviews two approaches to Zero Touch Deployment--a script-based solution and a release automation platform. The article discusses how each can solve the key …

Most Popular Programming Stories

More for Developers

RSS Feeds