API Reference | developer.brewmp.com API Reference | developer.brewmp.com


API Reference


Brew Release
Brew MP 1.0.2

The IMenuCtl interface is deprecated. Refer to the AEECLSID_ListWidget class topic instead.
Menu controls allow the device user to make a selection from a list of items. The UP, DOWN, LEFT and RIGHT arrow keys are used to identify the currently selected menu item, which appears highlighted on the screen. When the device user presses the SELECT key and command sending is enabled (see later in this section), an EVT_COMMAND is sent to the application or dialog that created the menu, which includes the identifier of the currently selected item. Following are four types of menu controls:
- A standard menu control (ClassID AEECLSID_MENUCTL) displays one menu item
per row on the screen, with each row containing the item's icon or text string. If all the items do not fit on the screen, use the UP and DOWN arrow keys to scroll the menu up or down.
- A list control (ClassID AEECLSID_LISTCTL) displays only the currently selected
menu item on the screen. This type of menu is useful in applications where the available screen real estate is limited. Items in a list control menu contain only text (there are no images). Use the UP and DOWN arrow keys to navigate to the specified menu selection.
- A Soft Key menu control (ClassID AEECLSID_SOFTKEYCTL) displays the menu items
side by side along the bottom portion of the screen. Use the LEFT and RIGHT arrow keys to designate the selected menu item. Soft Key menu controls contain icons and/or text strings.
- An Icon View menu control (ClassID AEECLSID_ICONVIEWCTL) uses a bitmap icon
to represent each menu item. The bitmap icons are displayed in one or more rows on the screen, and the arrow keys are used to move between rows and between the icons in each row. The text string corresponding to the currently selected item appears at the bottom of the screen.
Select the type you want by specifying its ClassID when you create an instance of the menu control. IMENUCTL_HandleEvent() handles the UP, DOWN, LEFT, and RIGHT arrow keys and the SELECT key.
The menus also handle the Character event. When you pass the EVT_CHAR message to an active menu, it will search for a menu entry which has text beginning with that letter (case-insensitive). This is type to select for a single character only. This will wrap around the menu if the selection is not found by the end of the last item. If there are no matches, the selection will not change. If the item doesn't have text associated with it, it is skipped.
If a calendar view menu is specified, a standard menu control also handles, the device number keys (AVK_0 through AVK_9), which are used to enter the time of a calendar appointment. Except for SoftKey menus, a menu control sends a control tabbing event (EVT_CTL_TAB) when the device user presses the LEFT and RIGHT keys. The softkey menu will send the control tabbing event when the UP or DOWN key is pressed. Use control tabbing to move between controls in a multicontrol screen. If your menu control is part of a dialog, the dialog intercepts the control tabbing events and changes control focus appropriately.
Menu controls support a number of properties that can be set with IMENUCTL_SetProperties(). The following property names are the names of the bitmask constants you use to get and set the properties:
- MP_WRAPSCROLL causes scrolling to wrap around (for example, the first menu
item is selected when the user presses the DOWN key while the last menu item is selected). This property is always set for soft key and list control menus. This property is also supported (disabled by default) for menuctl.
- MP_NO_ARROWS applies only to Icon View menus for which the MP_ICON_SINGLE_FRAME
property is set. It prevents the drawing of arrows on either side of the item text.
- MP_NO_REDRAW suppresses the redrawing of the menu each time the selected item
of a menu changes or the menu is set to active.
- MP_MAXSOFTKEYITEMS increases to 12, the number of Soft Key menu items that
can be displayed on the screen at once. By default, a maximum of three items are displayed.
- MP_CALENDAR allows a standard menu to be used as a as a Day View in a calendar
program. Menu items (appointments) have the following characteristics that are not described:
  • Horizontal lines are drawn between the menu items, and each item represents a calendar
  • appointment at a particular hour of the day.
  • – A small square appears in the upper left corner to indicate PM. No square means
  • AM.
  • – A triangle will be drawn on the right edge of the menu to indicate the current
  • time relative to the menu item wMinStart set via IMENUCTL_SetItemTime().
  • – The height of the menu items is proportional to the value of wDuration set via
  • IMENUCTL_SetItemTime().
  • The device's number keys are used to select the hour of an
  • appointment, and the application can set menu-item text describing the appointment.

- MP_AUTOSCROLLTIME automatically scrolls a Calendar View menu so that the entry
corresponding to the current time appears on the screen when the calendar is displayed. This only happens when IMENUCTL_SetActive() is called with bActive=TRUE and the menu is currently NOT active. An IMENUCTL_Redraw() after this would also be necessary.
- MP_ICON_TEXT_TOP causes the text string of the currently selected item in
an Icon View menu to appear at the top of the screen instead of the bottom.
- MP_ICON_SINGLE_FRAME displays only the icon of the currently selected menu
item on the screen. By default, an Icon View menu displays all the icons in rows and columns and highlights the selected one.
- MP_UNDERLINE_TITLE causes the menu's title to be underlined.

- MP_MULTI_SEL allows multiple choices on one menu. Choices are toggled when
the user presses the Select key on a menu item. These pressed will not cause an EVT_COMMAND message to be sent to the application. The applet should handle the EVT_CTL_TAB control tabbing message to either set focus to another control or collect relevant data.
- MP_BI_STATE_IMAGE ensures that the selected menu or soft key item looks different
from unselected menu or soft key items.
- MP_TRI_STATE_IMAGE ensures that the selected menu or soft key, pressed menu
or soft key, and unselected menu or soft key items look different from each other.
- MP_ICON_ANIMATED ensures that a selected icon of an animated type or a square
image can be animated.
Menu controls implement several functions in addition to those in the IControl Interface.
  • IMENUCTL_SetTitle() specifies a value for the menu's title, which is drawn at the
  • top of its rectangle.

  • IMENUCTL_EnableCommand() enables or disables the sending of
  • EVT_COMMAND events to your application when the device user presses the SELECT key
  • (command sending is enabled by default).

  • IMENUCTL_SetStyle() customizes the appearance
  • of the selected item and of the non-selected items in a menu including special pixel
  • borders, padding space around each item, and other appearance elements.

After creating a menu, you must specify the items that the menu contains.

  • IMENUCTL_AddItem()adds items to the menu that do not contain bitmap icons. When calling this function,
  • you specify the item's text string either from a resource file or defined in your
  • code, an integer item ID, and an optional double-word data pointer. When the device
  • user selects the item, your application's IAPPLET_HandleEvent() function is called
  • with an EVT_COMMAND event; the item ID and double-word pointer are specified as
  • the wParam and dwParam parameters in this function call.

  • IMENUCTL_AddItemEx() is
  • an extended version of IMENUCTL_AddItem() that provides additional information about
  • the added menu item including its bitmap icon and the font used to display its text
  • string.

  • IMENUCTL_DeleteItem() deletes a menu item with a particular ID, and IMENUCTL_DeleteAll()
  • deletes all the items from a menu.

  • IMENUCTL_GetSel() returns the item ID of the currently selected menu item. You use
  • this function when the device user's selection is not obtained by pressing the SELECT
  • key. For example, you may retrieve the device user's selection when the dialog containing
  • the menu control is terminated. IMENUCTL_SetSel() specifies the item ID that to
  • be the currently selected one. The menu control normally determines this based on
  • the device user pressing the arrow keys, but you can use IMENUCTL_SetSel() to designate
  • the initially selected item when the menu is first displayed.

  • IMENUCTL_GetItemData() retrieves the double-word data pointer of a menu item.

  • IMENUCTL_SetItemText() changes the text string of an existing menu item.

  • IMENUCTL_SetItemTime() sets the start time and duration associated with an item
  • in a calendar menu (see above), and

  • IMENUCTL_GetItemTime() retrieves the time information
  • of a calendar-menu item.

To create and use a menu control

1. Call ISHELL_CreateInstance() to create the menu control instance and obtain an interface pointer to it, specifying which of the four types of menu control you choose by its ClassID.
2. Call IMENUCTL_SetRect() to define the screen rectangle in which the menu is to be drawn.
3. Call IMENUCTL_SetProperties() to set any of the menu control properties, and call IMENUCTL_SetStyle to customize the appearance of your menu items.
4. Call IMENUCTL_SetTitle() to specify a menu title, and call IMENUCTL_AddItem() or IMENUCTL_AddItemEx() for each item to be added to the menu.
5. When you have completely specified the properties and contents of the menu control, call IMENUCTL_SetActive() to draw the control on the screen and enable it to receive key events from the device user. While the menu control is active, your application's IAPPLET_HandleEvent() function must call IMENUCTL_HandleEvent() to pass all handled key events to the menu control for processing.
6. Determine how you are to obtain the device user's menu selection. If you process the selection when the device user presses the SELECT key, the IAPPLET_HandleEvent() function can contain logic to handle the selection of each menu item when the EVT_COMMAND is received. If your application receives EVT_COMMAND events from more than one control, be sure that the item IDs passed in the wParam parameter are unique. If you retrieve the device user's selection at some other time, you must call IMENUCTL_GetSel() or IMENUCTL_GetItemData() at this time to access the currently selected menu item and its double-word data, if any.
7. When you no longer need the menu control, call IMENUCTL_Release() to free it.

The following header file is required: