Developer

API Reference

IMenuModel_InsertItem()

Brew Release
Brew MP 1.0.2
See Also
Model Events IMenuModel IMenuModel_Add()
Description
This function inserts a new menu item into the menu model, inserting the new item into the existing menu at the location indicated by the 'i' parameter, which is a zero-based index value for specifying a position within the menu. Note that this inserts the new item at this location, moving all other items down in the menu model's data store. For example, with three menu items stored in the menu model, like so:
         +--------------------------+   
         |                          |  
         |           Yes            |  Menu model index 0
         |                          |
         |--------------------------|   
         |                          |  
         |            No            |  Menu model index 1
         |                          |
         |--------------------------|
         |                          |  
         |          Maybe           |  Menu model index 2
         |                          |
         +--------------------------+

Inserting a fourth item at index location 1 would move the items currently stored at index positions 1 and 2 "down" one spot, to locations 2 and 3, like so:

         +--------------------------+   
         |                          |  
         |           Yes            |  Menu model index 0
         |                          |
         |--------------------------|   
         |                          |  
         |      Can't Decide        |  Menu model index 1  <--- Inserted item
         |                          |
         |--------------------------|   
         |                          |  
         |            No            |  Menu model index 2  <--- Moved from 1
         |                          |
         |--------------------------|
         |                          |  
         |          Maybe           |  Menu model index 3  <--- Moved from 2
         |                          |
         +--------------------------+

To build a brand new menu model from top to bottom, an application would call IMenuModel_InsertItem() for each item, passing MENUINDEX_LAST in the 'i' parameter to indicate that the new item should be added at the end of the menu model.
Though the example above assumes a user interface object that displays each item stored within the menu model as text, the menu model is capable of storing any arbitrarily complex data. It is the responsibility of the object attached to the menu model to expose the stored data in a manner that makes sense for that object.
Parameters
  • pif
    []:
    Pointer to the IMenuModel interface object.
  • pvItem
    []:
    Pointer to the data that defines the content for this item. How this data is exposed on the display is up to the object that has attached itself to the menu model. The data could be as simple as a text string or as complex a lengthy data structure.
  • idCmd
    []:
    The command ID assigned to this item.
  • flags
    []:
    A set of flags that indicate various state, display or behavioral attributes for the menu item. The defined menu item flags are. MMF_ENABLED - When this flag is ON, the menu item is currently enabled. MMF_SUBMENU - When this flag is ON, the menu item is a submenu. MMF_SEPARATOR - When this flag is ON, the menu item should be drawn with a menu separator. For traditional vertical menus, this is usually drawn as a line under the menu text. However, the separator could be rendered in whatever manner is most appropriate for the object attached to the menu model.
  • index
    []:
    Indicates the zero-based index of where the new item should be inserted in the menu model. The first item stored in the menu is indexed by 0, the second is indexed by 1, and so on... When the index for an existing menu item is specified, the new item is inserted into the menu model before the item specified by 'i'. Pass MENUINDEX_LAST to indicate that the new menu item is to be added at the last position in the menu model.
Interface
Prototype
   int IMenuModel_InsertItem(IMenuModel *pif, void *pvItem, uint16 idCmd, uint16 flags, uint16 index)
Return
   AEE_SUCCESS    - The item was successfully added to the menu model.
   AEE_ENOMEMORY  - The menu model was unable to allocate enough memory to accommodate the new item,
                    or the index passed in 'i' is outside the range of the data stored in the model.
Side Effect
Successfully, inserting a new item in a menu model by calling IMenuModel_InsertItem() will cause BREW to send an EVT_MDL_LIST_CHANGE ListModelEvent to any object that has registered as a listener with the model.
The fields of the ListModelEvent will contain the following information:
       pos:      The index of the menu item that has been inserted into the model. 
       oldSize:  The number of items that were in the menu model before adding
                 the new item.
       newSize:  The number of items that are now stored in the menu model after
                 adding the new item.
Comment
None
  • Follow