Developer

API Reference

IMenuModel_GetAt()

Brew Release
Brew MP 1.0.2
See Also
- IMenuModel Interface
- IMenuModel_InsertItem()
- IMenuModel_GetItemIndex()
- IMenuModel_SetItemFlags()
Description
This function retrieves the data for a menu item stored within the menu model. The function may either be used to retrieve an item from a specific zero-based index location within the model, or to retrieve the item that matches a specific set of menu item attribute flags, such as the third enabled item, or the first submenu. When the flag filter, 'f', is passed as MENUITEM_ALL, the data of the item stored at index location 'i' will be returned. When a specific set of flags is identified, 'i' indicates the ordinal position of the item to be returned, matching at least one of the set flags.
To illustrate, consider the following information about cool bands, lame bands, and various living and dead rock stars stored within a menu model:
                              Menu Model
                     +--------------------------+   
                     |                          |  
          Index 0    | Rage Against The Machine |  Enabled
                     |                          |
                     |--------------------------|   
                     |                          |  
          Index 1    |     Bruce Springsteen    |  Enabled
                     |                          |
                     |--------------------------|   
                     |                          |  
          Index 2    |       Jimi Hendrix       |  Disabled (he's dead, Jim)
                     |                          |
                     |--------------------------|   
                     |                          |  
          Index 3    |       Janis Joplin       |  Disabled (dead again)
                     |                          |
                     |--------------------------|   
                     |                          |  
          Index 4    |        The Pixies        |  Enabled, with Separator
                     |    ------------------    |
                     |--------------------------|   
                     |                          |  
          Index 5    |           ABBA           |  Enabled
                     |                          |
                     |--------------------------|
                     |                          |  
          Index 6    |   Captain And Tennille   |  Enabled
                     |                          |
                     +--------------------------+

From this menu model an application could request to directly retrieve the item stored at index location 3, as follows:
       IMenuModel_GetAt (pMenuModel, 3, MENUITEM_ALL, &pMenuData, &flags, &idCmd);

Called in this fashion, the function would retrieve the menu item data stored at index 3 within the model ("Janis Joplin").
Using the same menu model, an application would retrieve the third enabled menu item by calling the function with a flag filter, as follows:
       IMenuModel_GetAt (pMenuModel, 2, MMF_ENABLED, &pMenuData, &flags, &idCmd);

Here, with the index set to 2 (remember, indices are zero-based, so the third item is accessed using 2) and the flag filter set to MMF_ENABLED, the function would retrieve the third menu item that has the enabled flag set. In this case, this would be the item for "The Pixies".
Parameters
  • pif
    []:
    Pointer to the IMenuModel interface object.
  • i
    []:
    When the flag filter 'f' is passed as MENUITEM_ALL, this parameter indicates the zero-based index of the item to be retrieved from the menu model. When 'f' specifies an explicit set of menu flags, 'i' specifies which of the matching items is to be returned. For example, if the function is called with the flag filter set to only look for enabled items, 'i' will indicate which of these enabled items the function will retrieve. If there are 4 enabled items and 'i' is passed as 1, the second of these four enabled items will be returned.
  • f
    []:
    A set of menu item attribute flags that provide a filter for the item to be returned. When 'f' is passed as MENUITEM_ALL, the function will return the item specified by the 'i' parameter, from the set of all stored menu items. When 'f' specifies one or more menu item attributes, the function considers only those items that match at least one of the set filter flags, using 'i' as an index over only those matching items. The defined menu item filter flags
  • ppo
    []:
    Pointer to a void pointer into which the function will return a pointer to the data that defines the content for this item.
  • e
    []:
    Pointer into which the function will return the attribute flags for the menu item being retrieved. The defined attribute flags
  • c
    []:
    Pointer into which the function will return the command ID assigned to the menu item being retrieved.
Interface
Prototype
   int IMenuModel_GetAt(IMenuModel *pif, uint16 i, uint16 f, void **ppo, uint16 *e, uint16 *c); 
Return
   AEE_SUCCESS  - The function was able to successfully retrieve the requested item from
              the model interface.
   AEE_EBADPARM - The requested index is not within the range of items stored in the model.

Side Effect
None
Comment
The pointer passed in the 'ppo' parameter is a double-indirection -- i.e. it is a pointer to a pointer. Applications should use care in ensuring that the proper level of indirection is used in calling the function.
  • Follow