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

  • 10 Rules that Make or Break Enterprise App Development Projects In today's app-driven world, application development is a top priority. Even so, 68% of enterprise application delivery projects fail. Designing and building applications that pay for themselves and adapt to future needs is incredibly difficult. Executing one successful project is lucky, but making it a repeatable process and strategic advantage? That's where the money is. With help from our most experienced project leads and software engineers, …

  • Java developers know that testing code changes can be a huge pain, and waiting for an application to redeploy after a code fix can take an eternity. Wouldn't it be great if you could see your code changes immediately, fine-tune, debug, explore and deploy code without waiting for ages? In this white paper, find out how that's possible with a Java plugin that drastically changes the way you develop, test and run Java applications. Discover the advantages of this plugin, and the changes you can expect to see …

Most Popular Programming Stories

More for Developers

Latest Developer Headlines

RSS Feeds