Developer

API Reference

AEECLSID_PopupForm

Brew Release
Brew MP 1.0.2
See Also
ISHELL_CreateInstance() Widget Events
Description
Popups are specialized forms that provide the ability for an application to display a quick, transient screen to the user, either to display a message (such as an error or progress message) or provide some level of rapid user interaction (such as a popup menu or a simple dialog). For example, an application that displays an "Options" softkey could choose to display a quick popup menu from which the user would select any of the available "options" provided by the app.
Popups share all of the usual characteristics of a form (background image, properties, etc) and are drawn as small windows that appear to float on top of the display. They also contain a backdrop widget which can be used to control the appearance of the form that is beneath the popup. Alone, the popup class is actually the base object form from which more complex forms such as dialogs and popup menus will be derived. Forms that derive from popups have control over how the popup will be sized and positioned. For example, dialogs (which derive from the base popup form) center themselves horizontally and vertically within the form's root container. Conversely, the popup menu, which also derives from the base popup form, will choose its size based on the number of items contained in its menu, and will position itself just above the softkey area of the root form.
The base popup form is created with the following default characteristics:
           Border width:  0
                 Shadow:  1 pixel
               Backdrop:  none

After a popup is created, these or other characteristics common to popups or forms may be overridden. For example, an object that drives from the popup class could choose to alter the background color or transparency to create the effect of the popup truly overlaying the display.
To create a popup form, an application would do the following:
       1. Call ISHELL_CreateInstance() with a class ID of AEECLSID_PopupForm to
          retrieve a reference counted instance of the popup form.
       2. Set any specialized properties for the popup, such as the border, background,
          or backdrop properties.
       3. Create the content to be displayed on the popup
       4. If an application so chooses to do so, it may wrap the popup in a blender or
          fader to provide a transitional visual effect each time the popup appears or
          disappears from the screen.

Supported Events: The base popup form processes events in two passes. In the first pass the popup form will attempt to process a small set of property events that the popup form will handle in a very specific manner. Events not handled during this pass are then passed on to the base form event handler.
The popup form handles the following events:
Event                 Description
-----                 ------------------------------------------------------------
EVT_WDG_SETPROPERTY:  The popup form responds to this event by attempting to set the
                      property identified by the 'wParam' parameter.  The popup form
                      allows the following properties to be set...
                      
                          WID_BACKDROP --  Sets the widget used to render the popup's backdrop
                                           effect.
                          FID_ACTIVE   --  Sets the activation state of the popup form.
                          FID_VISIBLE  --  Sets the visible state of the popup form
                          FID_FADEMS   --  Sets the fadeout time for the backdrop if the popup
                                           has a backdrop
                      
                      These properties are discussed below in greater detail.

EVT_WDG_GETPROPERTY:  The popup form 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 form allows the following properties
                      to be retrieved...
                      
                          WID_BACKDROP  --  Retrieves a pointer to the widget used by the popup
                                            to render its backdrop effect.  Retrieving this
                                            property increments the reference count of the
                                            backdrop widget.
                          WID_DECORATOR --  Retrieves a pointer to the decorator
                                            associated with the popup form.  Retrieving
                                            this property increments the reference count
                                            of the decorator.
                          FID_FADEMS   --  Gets the fadeout time for the backdrop


Properties:
Property        Description
--------        ------------------------------------------------------------
FID_FADEMS:     This property maintains the fadeout time for the backdrop of the popup. If
                WID_BACKDROP is set a fader transition is automatically attached to it, with
                the given fadeout time. The fadeout transition is applied when the popup is
                cancelled. 

                    Property Value:  uint32

FID_ACTIVE:     This property contains the activation state of the popup form -- TRUE when
                the popup is active, FALSE when it is not.  Setting the activation state of
                the popup will trigger the popup 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.                
                             
                    Property Value:  boolean

WID_BACKDROP:   This property contains a pointer to the widget used to render the backdrop for
                the popup.  The backdrop provides a visual effect for the popup, which makes
                it seem as though the popup 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 popups
                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_DECORATOR:  This property contains a pointer to the popup form's decorator.  The decorator
                allows forms that derive from the popup to manage some specialized visual
                characteristic of their display.  For example, a popup form that supports the
                ability to browse through a list of photographs, displaying a thumbnail of the
                current selection in an image viewer, might choose to return a pointer to the
                image viewer in response to queries to get the WID_DECORATOR property, while the 
                list widget used to browse the names of the images might be returned by the
                WID_LIST property.  The list is just a list, while the image viewer decorates
                that list.  This distinction is important in light of the prior example in which
                a pointer to a list widget is returned as the WID_DECORATOR property.

                    Property Value:  IDecorator *
Instantiaion
The popup form is instantiated by passing AEECLSID_PopupForm into ISHELL_CreateInstance.
Cleanup
The popup form is reference counted. When you are done with your reference to the popup form, you should Release that reference.
Default Interface Name
Comment
None
  • Follow