Creating and Using Menus on Windows Mobile Pocket PCs

Creating and Using Menus on Windows Mobile Pocket PCs

Windows Mobile 5.0 includes a big change to menus. Pocket PC developers now have the ability to make use of Smartphone-style menus: consisting of only two menus at the bottom of the screen, optionally linked to hardware buttons (optionally in that your hardware may or may not have buttons – you can always tap the screen). Pressing the buttons pops open a traditional menu.

As far as I’m concerned, this new Windows Mobile 5.0 approach has two big bonuses:


1. You can use the same code in both Pocket PC and Smartphone applications.
2. The two-button user interface makes more sense on a hand held device (IMHO), and can be used with hardware buttons.

So, let’s take a look at how you can add some menus to your Windows Mobile 5.0 application. I’m going to assume that you’ve created a new Windows Mobile 5.0 C++ native Windows application, and not yet touched the menus.

It’s not a menu…

It’s a toolbar. That’s the first thing you need to know. The two menu buttons at the bottom of the screen aren’t menus, they are part of a toolbar. In effect, they are buttons, and creating them requires the use of toolbar APIs. In practice that means using SendMessage() to communicate with the toolbar and make changes.

Once you create a new project, you will see the menu resource in your solution. You can edit this resource using the graphical editor, add options, and change the element ID names and so on. By default, the menus are called OK (and this one will close the application) and Help (and this one will bring up the About box).

You will find the resource data for this menu structure in two separate places: the rc and rc2 files.

In the rc file associated with your project, you will find the definition of the menu that pops-up when you select a menu. It is, indeed, a popup menu. This code is created by the Visual Studio IDE when you edit the menu using the GUI. So if you add any extra menu items, this is where they will appear. You probably won’t have to edit this code manually, but here’s an example so you can see what it looks like:

		 IDR_MENU MENU 
		 BEGIN
		    POPUP "Menu 1"
		    BEGIN
		        MENUITEM "About",                       IDM_HELP_ABOUT
		        MENUITEM "Option that is Checked",      ID_MENU_CHECK, CHECKED
		        MENUITEM "Option to be Renamed",        ID_MENU_RENAME
		        MENUITEM "Some other option",           ID_MENU1_SOMEOTHEROPTION
		    END
		 END
	

As you can see, I’ve added three more options (in the GUI editor). One I’m going to check and uncheck, one I’m going to rename, and one for good measure.

Now, the other important stuff is stored in the rc2 file, as here you will find the definition of the toolbar. The important part is the NOMENU flag, which causes the toolbar button act as a button, rather than open a pop-up menu. In this example, the first button is just an OK button, but the second brings up a menu (IDR_MENU).

		 IDR_MENU RCDATA
		 BEGIN
		    IDR_MENU, 
		    2,
		    I_IMAGENONE, IDM_OK, TBSTATE_ENABLED, TBSTYLE_BUTTON | TBSTYLE_AUTOSIZE,
		    IDS_OK, 0, NOMENU,
		    I_IMAGENONE, IDM_HELP, TBSTATE_ENABLED, TBSTYLE_DROPDOWN | TBSTYLE_AUTOSIZE,
		    IDS_HELP, 0, 0,
		 END
	

As you can see, I’ve been too lazy to rename the menu from IDM_HELP. Watch for that, as we’ll use it when we want to change the menu elements.

Creating the menu

The default project will have created code that creates this new menu structure, and it will look something like this:

		 SHMENUBARINFO mbi;
		 memset(&mbi, 0, sizeof(SHMENUBARINFO));
		 mbi.cbSize     = sizeof(SHMENUBARINFO);
		 mbi.hwndParent = hWnd;
		 [mbi.nToolBarId] = IDR_MENU;
		 [mbi.hInstRes]   = g_hInst;
	

 

		 if (!SHCreateMenuBar(&mbi)) 
		 {
	

 

		     g_hWndMenuBar = NULL;
		 }
		 else
		 {
		     g_hWndMenuBar = mbi.hwndMB;
		 }
	

Using traditional menu resources

Since a menu structure based on softkeys can be fully described using a plain, old-fashioned menu resource, you don't really need to use a toolbar resource at all:

		 IDM_MY_MENU MENU
		   BEGIN
		     MENUITEM "Action",  IDM_ACTION
		       POPUP "Menu"
		       BEGIN
	

MENUITEM "Item 1", IDM_ITEM1
MENUITEM "Item 2", IDM_ITEM2

		       END
		   END
	

All you have to do is tell ""SHCreateMenuBar"" that you are using a menu resource, by passing in the SHCMBF_HMENU flag:

		 SHMENUBARINFO mbi;
		 memset(&mbi, 0, sizeof(SHMENUBARINFO));
		 mbi.cbSize     = sizeof(SHMENUBARINFO);
		 mbi.dwFlags = SHCMBF_HMENU;
		 mbi.hwndParent = hWnd;
		 [mbi.nToolBarId] = IDM_MY_MENU;
		 [mbi.hInstRes]   = g_hInst;
	

 

		 [SHCreateMenuBar(&mbi);]
	

Changing the name of a menu

Here is how to change the name of a menu – this changes the actual text that appears at the bottom of the screen. This code changes the menu to be called “Renamed”. Because we’re dealing with a toolbar, we don’t use any menu APIs, we use a SendMessage() with the correct TB_ flag.

		 // Change title of menu 
		 memset(&tbbi,0,sizeof(tbbi));
		 tbbi.cbSize = sizeof(tbbi);
		 tbbi.dwMask = TBIF_TEXT;
		 tbbi.pszText = L"Renamed";
		 SendMessage(SHFindMenuBar(hWnd),TB_SETBUTTONINFO,IDM_HELP,(LPARAM)&tbbi);
		 DrawMenuBar(g_hWndMenuBar);
	

Checking a menu option

Here is how to add a check mark to a menu element. This time we are dealing with a menu (a pop-up menu), but we need to get a handle to the menu before we can do anything. To get the handle, we have to use SendMessage() with a special SHCMDMGETSUBMENU flag. Once we get the handle, we can use CheckMenuItem(). This code uses a bool called menustate for demonstration purposes.

		 hMenuMB = [(HWND)SHFindMenuBar(hWnd);]
		 hMenu = (HMENU) [SendMessage(hMenuMB,] SHCMBM_GETSUBMENU,0,IDM_HELP);
		 if (menu_state)
		 	CheckMenuItem(hMenu,ID_MENU_CHECK,MF_BYCOMMAND|MF_CHECKED);
		 else
		 	CheckMenuItem(hMenu,ID_MENU_CHECK,MF_BYCOMMAND|MF_UNCHECKED);
	

Changing the text of a menu item

Here is how to change the text displayed by a menu item. As it turns out, there is no API to modify a menu name directly. Instead you have to (gulp) delete the menu item, and then insert a replacement.



In this example, I rename the text in the menu item that is at position 2 in the menu. The menu ID is “IDMENURENAME”. Obviously you will need to change the position and ID for your particular menu.

		 // Rename a menu item (by deleting it and recreating it)
		 hMenuMB = [(HWND)SHFindMenuBar(hWnd);]
		 hMenu = (HMENU) [SendMessage(hMenuMB,] SHCMBM_GETSUBMENU,0,IDM_HELP);
		 DeleteMenu(hMenu,2,MF_BYPOSITION);
		 InsertMenu(hMenu,2,MF_BYPOSITION, ID_MENU_RENAME,L"Changed!");          
	

Menu Design

Remember also that the two button menu design brings with it a new philosophy. The left button is supposed to perform an action – for example, OK, to close a window. The right button is supposed to list the options. Try to stick to these design guidelines to avoid confusing you users.