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
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 *