Creating a Smartphone MenuBar Control

Just as on the Pocket PC, the MenuBar creation function SHCreateMenuBar is used to create a MenuBar on the Smartphone. The format of the parameters is the same as in the Pocket PC, as is the format of the SHMENUBARINFO structure used to define the structure of the control. The combination toolbar and menu resource used by the Smartphone MenuBar is also the same. The difference is that, on the Smartphone, the MenuBar is much less flexible. The toolbar resource must define one or two buttons. The MenuBar buttons can either be designed to provide a direct action or display a menu when the associated button is pressed.

For review, the prototype of SHCreateMenuBar and SHMENUBARINFO are shown here:

BOOL SHCreateMenuBar (SHMENUBARINFO *pmb);

typedef struct tagSHMENUBARINFO {
    DWORD cbSize; 
    HWND hwndParent; 
    DWORD dwFlags; 
    UINT nToolBarId; 
    HINSTANCE hInstRes; 
    int nBmpId; 
    int cBmpImages; 
    HWND hwndMB;
    COLORREF clrBk;
} SHMENUBARINFO;

In the Smartphone MenuBar control, the cbSize, hwndParent, hInstRes, and hwndMB fields are used, as in the standard menu bar, to confirm the size of the structure, indicate the control parent, provide the instance handle of the module containing the resource, and return the handle of the created control. However, some fields are limited in comparison to their use in the standard menu bar. The nBmpId and cBmpImages fields must be 0 or the call to create the control will fail. The clrBk field is ignored even if the corresponding SHCMBF_COLORBK flag is set in the dwFlags field. The other defined flags in dwFlags also don't make sense in the limited MenuBar control.

The nToolBarId field must identify a resource structured identically to the menu bar resource described in Chapter 5. That format is shown here.

<Menu ID>, <Number of buttons (1 or 2)>,
I_IMAGENONE, <Cmd1ID>, <Btn1State>, <Btn1Style>, <String1ID>, 0, <Menu1Index>
I_IMAGENONE, <Cmd2ID>, <Btn2State>, <Btn2Style>, <String2ID>, 0, <Menu2Index>

The first field of the resource is the resource ID of any menu resource being used by the control. The second field can be either 1 or 2 depending on if the control will have one or two buttons on the bar. The remainder of the resource describes one or both buttons on the control. In the previous example, the second and third lines describe the two buttons.

The first field should be set to I_IMAGENONE to indicate that the button is text, not a bitmap. Bitmaps are not supported on the Smartphone MenuBar. The second field contains the ID value that will be sent to the owner window if the button is not a menu and is pressed. The third field describes the initial state of the button using toolbar state flags. The fourth field describes the style of the button using toolbar style flags. The String ID field must refer to a valid string resource ID that contains the text for that button. The next to last field should be set to 0, and the last field is the submenu index into the menu identified by the first field in the resource. This field can be NOMENU if the button doesn't display a menu when pressed.

An example SoftKeyBar control is shown in Figure 19-4.

Figure 19-4

A SoftKeyBar control where the menu button has been pressed

Figure 19-4 shows a Smartphone MenuBar with a Done button on the left and a Menu button on the right. This placement of direct action assigned to the left button and an optional menu assigned to the right button is the recommended arrangement suggested by the Smartphone user interface guide. In the figure, the Menu button has been pressed displaying a short menu on the screen. The two-part resource that describes the MenuBar control in Figure 19-4 is shown here:

ID_BTNBARRES RCDATA MOVEABLE PURE 
BEGIN
  ID_MENU, 2,
  I_IMAGENONE, IDM_EXIT, TBSTATE_ENABLED, TBSTYLE_AUTOSIZE | TBSTYLE_BUTTON,
               IDS_DONE, 0, NOMENU,
  I_IMAGENONE, IDM_POP, TBSTATE_ENABLED, TBSTYLE_AUTOSIZE | TBSTYLE_DROPDOWN, 
               IDS_MENU, 0, 0,
END

ID_MENU MENU DISCARDABLE 
BEGIN
    POPUP "&Dummy"
    BEGIN
        MENUITEM "Week View",                   IDM_VIEWWEEK
        MENUITEM "Month View"                   IDM_VIEWMONTH
        MENUITEM "Year View",                   IDM_VIEWYEAR
        MENUITEM SEPARATOR
        MENUITEM "Options",                     IDM_OPTIONS
    END
END

The ID_BTNBARRES resource describes the two buttons. The first button is a direct action button and the second is a button that displays a menu. One difference between the two buttons, aside from the string resource references, is the different style flag, TBSTYLE_BUTTON vs. TBSTYLE_DROPDOWN. Another difference is the NOMENU index in the first button description, where the second button uses a menu index of 0. The 0 index indicates the first, and in this case only submenu of the ID_MENU menu resource.


This topic is from Programming Microsoft Windows CE, Third Edition, by Douglas Boling, published by Microsoft Press. © 2003 by Douglas McConnaughey Boling. Reprinted here by permission of the author.

Show: