Developer

API Reference

IPopupMenu

Brew Release
Brew MP 1.0.2
See Also
- Form Events
- ISHELL_CreateInstance()
- IForm_SetSelectHandler()
- IForm_SetThemeBaseName()
- Model Events
Description
The popup menu is derived from the base popup form and is intended to provide applications with popup menus that are standard in appearance and consistent in their behavior. For example, an application that supports online ticket scalping might include a screen that presents the user with a list of upcoming events (Prince in Los Angeles, the San Diego Padres vs the San Francisco Giants, NCAA Final Four basketball, Oatmeal Wrestling at Denny's...). The application might also provide an "Options" softkey that, when pressed, displays a popup menu of commands that could be applied to the selected event -- "Buy Tickets", "Venue Details", "Available Seats", etc.
Applications interact with the popup menu by defining an item selection function and registering this function with the popup menu by calling IForm_SetSelectHandler(). The selection handler will be called, notifying the application of the menu item that has been selected, whenever the user presses the key mapped to AVK_SOFT1 -- usually the left softkey button. Applications that wish to invoke item selection using a different key should provide their own key event handler to hook into the popup event handler. For example, an application that uses the right softkey for actions and the left for canceling operations would need to define an event handler that swapped virtual keycodes normally generated by these keys, then hook this event handler into the popup menu event handler so that the popup menu's handler will "see" the left softkey as the right, and the right as the left.
Popup menus are automatically sized to fit the number of items to be displayed in the menu, and are placed centered horizontally and anchored near the bottom of the display.
The base popup menu form is created with the following default characteristics:
                Border width:  0
                      Shadow:  1 pixel
            Background color:  RGB_WHITE
            Foreground Color:  RGB_BLACK
   Selected Background Color:  Light grey

The popup menu will also be wrapped within a fader widget to provide an effect of the popup gradually emerging onto the display, then gradually fading from the display when it is removed.
Supported Events: The popup menu form processes events in two passes. In the first pass the popup form will attempt to process events itself -- looking for property events handled in specific ways by popup menus, specific key events and events intended to cancel the popup menu. Events not handled during the first pass are then passed on to the base popup event handler.
The popup menu form handles the following events:
Event                 Description
-----                 ------------------------------------------------------------
EVT_KEY:              The popup menu form will interpret presses of the AVK_SOFT1 virtual
                      key code as a selection from the popup menu, and will trigger the
                      popup menu's selection handler to be called, with the ID of the menu
                      item that has been selected.  Applications that wish to invoke item
                      selection using a different key should provide their own key event
                      handler to hook into the popup event handler, trapping for the virtual
                      keycode of their own choosing.

EVT_FORM_CANCEL:      The popup menu is being instructed to remove itself from the form stack
                      and will comply by initiating its fade out transition.  Popup menus
                      fade for a period of 200 ms prior to being popped off the form stack.
                      This time period is not currently configurable.

EVT_WDG_SETPROPERTY:  The popup menu form responds to this event by attempting to set the
                      property identified by the 'wParam' parameter.  The popup menu form
                      allows the following properties to be set:
                      
                           WID_BACKDROP      --  Sets the widget used to render the popup menu's
                                                 backdrop effect.
                           WID_STATIC        --  Sets the widget that will be used to display each
                                                 image static item within the popup menu to be the
                                                 static text widget passed with the event in the
                                                 'dwParam' parameter.
                           WID_LISTITEM      --  Sets the widget that will be used to display each
                                                 item within the popup menu to be the widget passed
                                                 with the event in the 'dwParam' parameter.
                           FID_SELECTHANDLER --  Sets the selection handler to be used by the
                                                 popup menu, to be the handler passed with the event
                                                 in the 'dwParam' parameter.
                           FID_LISTMODEL     --  Sets the model used by the form's decorator to be
                                                 the list model passed with the event in the
                                                 'dwParam' parameter.
                           FID_ARRAYMODEL    --  Sets the model used by the form's decorator to be
                                                 the array model passed with the event in the
                                                 'dwParam' parameter.
                           FID_THEME         --  Sets the theme file to be used by the popup menu,
                                                 and applies this theme to the popup menu's form.
                           FID_ACTIVE        --  Sets the activation state of the popup menu form.
                                                 When the popup menu is being activated its form
                                                 will be sized, positioned and displayed.
                           FID_VISIBLE       --  Sets the visible state of the popup menu form.
                           FID_FADEMS        --  Sets the fadeout time for both the backdrop, if present,
                                                 and the menu itself. 
                                                 
                      These properties are discussed below in greater detail.

EVT_WDG_GETPROPERTY:  The popup menu responds to this event by attempting to retrieve the
                      property identified by the 'wParam' parameter, passing the value of
                      the property back to the querying object in a pointer passed in the
                      'dwParam' parameter.  The popup menu allows the following properties
                      to be retrieved: 
                      
                          WID_BACKDROP   --  Retrieves a pointer to the widget used by the popup menu
                                             to render its backdrop effect.  Retrieving this
                                             property increments the reference count of the
                                             backdrop widget.
                          WID_LIST       --  Retrieves a pointer to the popup's decorator, incrementing 
                                             the reference count of the decorator.
                          WID_LISTITEM   --  Retrieves a pointer to the list item widget used as the display
                                             widget for each item in the popup menu, incrementing 
                                             the reference count of the list item.
                          FID_MENUMODEL  --  Retrieves a pointer to the menu model utilized by the
                                             popup menu's decorator, incrementing the reference count
                                             for the menu model.
                          FID_LISTMODEL  --  Retrieves a pointer to the list model utilized by the
                                             popup menu's decorator, incrementing the reference count 
                                             of the decorator.
                          FID_ARRAYMODEL --  Retrieves a pointer to the array model utilized by the
                                             popup menu's decorator, incrementing the reference count 
                                             of the array model.
                          FID_VIEWMODEL  --  Retrieves a pointer to the view model utilized by the
                                             popup menu's decorator, incrementing the reference count 
                                             of the view model.
                          FID_FADEMS     --  Gets the fadeout time for both the backdrop, if present,
                                             and the menu itself. 

Properties:
Property            Description
--------            ------------------------------------------------------------
WID_BACKDROP: This property contains a pointer to the widget used to render the backdrop for the popup menu. The backdrop provides a visual effect for the popup menu, which makes it seem as though the popup menu has been placed "above" other content on the display. The WID_BACKDROP property allows applications to access the backdrop widget that provides this visual feedback. It is important to note that popup menus supply a backdrop widget in _addition_ to the primary widget provided by the base form and accessed through the WID_FORM property. The backdrop widget is also distinguished from the background widget supplied by the root form and accessed by the WID_BACKGROUND property.
Property Value: IWidget *
WID_STATIC: This property contains a pointer to the static widget the popup will use to display the text portion of each item within its menu. Each item in the popup menu is rendered using a single image static widget. The static component of this widget is stored in the popup menu's WID_STATIC property. This widget is managed by the popup menu itself -- independent of the primary widget managed at the form level by the WID_FORM property.
Property Value: IWidget *
WID_LIST: This property contains a pointer to the list widget utilized by the popup to display and manage the items contained in the popup menu. It is important to note that the list widget is provided in _addition_ to the primary widget associated with the popup's base form and accessed by the WID_FORM property.
Property Value: IWidget *
WID_LISTITEM: This property contains a pointer to the decorator the popup will use to display each item within its menu. Each item in the popup menu is rendered using a single widget, pointed to by this decorator. Note, however, that this widget is not, necessarily, an image static widget -- as would be believed by considering the WID_STATIC property. Popup menus, by default, are created utilizing an image static as the widget to render each menu item. A popup menu could, however, use any widget of its choosing to render the menu items, with a pointer to this widget being stored in the WID_LISTITEM property. This property is, effectively, the widget wrapped within the popup menu form's WID_LIST property. The list item widget is managed by the popup menu itself -- independent of the primary widget managed at the form level by the WID_FORM property.
Property Value: IWidget *
FID_SELECTHANDLER: This property contains a pointer to the select handler used by the popup to process items selected from its menu. A pointer to a selection function is stored in the SelectHandler data structure pointed to by this property, which may be set but not retrieved -- i.e. this property is used as a mechanism for registering the popup menu's selection callback and does not contain data that would be used by a client of the popup menu.
Property Value: SelectHandler *
FID_LISTMODEL: This property contains a pointer to the list model that is attached to the list widget that manages the content of the menu displayed in the popup. The list model serves as the base model for the popup menu.
Property Value: IModel *
FID_ARRAYMODEL: This property contains a pointer to the array model that is attached to the list widget that manages the content of the menu displayed in the popup. The array model provides structure to the items to be displayed by the popup menu.
Property Value: IModel *
FID_MENUMODEL: This property contains a pointer to the menu model that is attached to the popup menu -- typically, the list widget that forms the basis for the menu contents. The property returns that pointer in an IModel pointer passed in the 'dwParam' parameter passed to the form in the EVT_WDG_GETPROPERTY event.
If an application is using this property to add popup menu items (such as via IMenuModel_Add()), the application should also set its own free function, via IMenuModel_SetPfnFree().
The popup menu does not support attempts to set the FID_MENUMODEL property.
Property Value: IModel *
FID_VIEWMODEL: This property contains a pointer to the view model that is attached to the popup menu's list widget. The property returns that pointer in an IModel pointer passed with the 'dwParam' parameter of an EVT_WDG_GETPROPERTY event.
Property Value: IModel *
FID_THEME: This property identifies the name of the theme file to be used by the popup menu. Setting FID_THEME on a popup menu will load the theme background image to be used by the popup and will notify listening objects of the theme change -- most notably, the widget responsible for displaying the popup menu itself. The popup menu will apply the new theme to the widget used to draw each menu item, and cause the menu to be drawn on the display.
Property Value: char *
FID_ROOT: This property contains a pointer to the root form that manages the popup menu's form. The root form controls the stacking order for a collection of forms and manages where the popup will be placed relative to other forms.
Property Value: IRootForm *
FID_ACTIVE: This property contains the activation state of the popup menu -- TRUE when the popup is active, FALSE when it is not. Setting the activation state of the popup will trigger the popup's form to invalidate itself and be redrawn.
Property Value: boolean
FID_VISIBLE: This property contains the visible state of the dialog -- TRUE when the popup may be all or partially visible, FALSE when it is not. Setting the visible state of the popup may trigger an invalidation if the root form client region has changed.
Usage

After a popup menu is created, the default characteristics listed above, or any other characteristic native to popup menus, popups, forms or decorators may be overridden. For example, the popup menu could choose to display vivid blue text over a hot pink background (horrifying though that may be to the naked eye).
To create a popup menu, an application would do the following:
- call ISHELL_CreateInstance() with a class ID of either:
- ISHELL_CreateInstance() will return a reference counted instance of the desired popup menu
form interface. - Call IForm_SetThemeBaseName() on the popup menu if the your application is applying
specific theme metrics to your forms, otherwise set visual properties as normal for an IWidget. - Call IForm_SetSelectHandler() to install a selection handler to manage item selections
from within the popup menu. - Initialize the text that is to appear in the popup menu, which is easily accomplished
through multiple calls to IPopupMenu_LoadMenuItem(), which will set the text for each menu item from strings stored in a resource file.
Comment
None
  • Follow