Dialogs are a specialized type of form and, as such, support each of the user interface elements commonly found within the context of a form -- a title area, a content area, and a pair of softkeys. The dialog class expands on these common UI elements by providing additional widget and form capabilities. Notably, a dialog may possess it's own background, backdrop and title widgets -- all independent of widgets managed by the root form. The title and background widget allows a dialog to be displayed with a title and background that is different than that displayed on the form the dialog will overlay. The backdrop widget is used by the dialog to create the visual effect of the dialog floating over the top of the display's topmost form.
Though the dialog class is simple, applications may use the dialog title and the root form's softkeys to guide quick interactions with the user. Take, for example, the following example of a dialog from an application used to purchase tickets to rock concerts:
+-----------------------------------+ | Purchase Tickets | +-----------------------------------+ | | | | | A service charge of | | | | $4,000,000 | | | | will be charged to your credit | | card. | | | | Do you approve this charge? | | | | | +-----------------------------------+ | Approve | Cancel | +-----------------------------------+
This dialog includes a title, content text and a pair of softkeys. The application could attach an event handler to the dialog to process the user's selection of "Approve" or "Cancel" from the softkeys, thereby tying together the form content and actions taken on behalf of the user into one nice, neat package.
The base dialog form is automatically sized to fit, centered, within the form's root container. The dialog will be displayed with a transparent backdrop to create the effect of the dialog floating above other forms on the display. Specific subclasses of the base dialog may size, position and alter the default characteristics of the base dialog in any manner that they so choose.
The base dialog form is created with the following default characteristics:
Position: Centered within root container Border width: 0 Shadow: 1 pixel Background color: RGB_WHITE Foreground Color: RGB_BLACK Selected Background Color: Light grey Background image alignment: Bottom right (if a background image is present) Backdrop Border width: 0 Backdrop Background color: RGB_WHITE Backdrop Transparency: 70 (roughly 30% transparent, 70% opaque) Title border width: 1 pixel Title border color: Dark grey Title padding: 4 pixels on the left
Like popup menus, dialogs are wrapped within a fader widget to provide an effect of the dialog gradually emerging onto the display, then gradually fading from the display when it is removed.
After a dialog is created, the default characteristics listed above, or any other characteristic native to dialogs, popups or forms, may be overridden. For example, the dialog could choose to display its message in white text over an image of the beautiful green grass in the outfield at Petco Park.
Once created, the dialog will remain on screen indefinitely -- or until the user explicitly dismisses the dialog by pressing any key mapped to an EVT_FORM_CANCEL event. An application may implicitly remove the dialog by sending an EVT_FORM_CANCEL event to the dialog itself; for example, if an application wishes to display a dialog to provide visual feedback while a lengthy operation is in progress ("Connecting..."), then automatically dismisses the dialog once the operation completes. Such an application would initiate an EVT_FORM_CANCEL event upon completing its time consuming task. As described below under Supported Events, a dialog respond to this event by initiating its fade effect, then automatically removing itself from the form stack.
Supported Events: The base dialog processes events in two passes. In the first pass, the dialog will attempt to process events itself -- providing a mechanisms for handling dialog cancellation and property event handling. Events not handled during the first pass are then passed on to the base popup event handler.
The base dialog form handles the following events:
Event Description ----- ------------------------------------------------------------ EVT_FORM_CANCEL: The dialog is being instructed to remove itself from the form stack and will comply by initiating its fade out transition. Dialogs fade for a period of 200 ms prior to being popped off the form stack. This time period is not currently configurable. Though EVT_FORM_CANCEL is handled by the base dialog event handler, the event will still be passed down to the popup event handler for further processing. EVT_WDG_SETPROPERTY: The dialog form responds to this event by attempting to set the property identified by the 'wParam' parameter. The dialog form allows the following properties to be set: FID_ACTIVE -- Sets the activation state of the dialog. FID_VISIBLE -- Sets the visible state of the dialog FID_TITLE -- Sets the text to be displayed in the dialog's title widget. This event is then passed to the base form, which then notifies other objects that the title widget has changed. FID_THEME -- Sets the theme file to be used by this dialog, applying the metrics of that theme to the form elements and contents. FID_BACKGROUND -- Sets the image to be displayed in the dialog's background image. WID_BACKDROP -- Sets the widget used to render the dialog's backdrop effect. These properties are discussed below in greater detail. EVT_WDG_GETPROPERTY: The dialog 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 dialog form allows the following properties to be retrieved: WID_TITLE -- Retrieves a pointer to the dialog title widget. Retrieving this property increments the reference count of the title widget. WID_BACKDROP -- Retrieves a pointer to the widget used by dialog to render its backdrop effect. Retrieving this property increments the reference count of the backdrop widget. These properties are discussed below in greater detail.
Property Description -------- ------------------------------------------------------------ FID_ACTIVE: This property contains the activation state of the dialog -- TRUE when the dialog is active, FALSE when it is not. Setting the activation state of the dialog will trigger the dialog to invalidate itself and be redrawn. Property Value: boolean FID_VISIBLE: This property contains the visible state of the dialog -- TRUE when the dialog may be all or partially visible, FALSE when it is not. Setting the visible state of the dialog may trigger an invalidation if the root form client region has changed. Property Value: boolean FID_ROOT: This property contains a pointer to the root form that manages the dialog. The root form controls the stacking order for a collection of forms and manages where the dialog will be placed relative to other forms. Property Value: IRootForm * FID_TITLE: This property contains a pointer to the text that will be displayed in the dialog's title widget (which is different than the root form's title widget). The text will be displayed by itself if the dialog title widget has been implemented as a static widget, or along with a graphic image if the widget is an image static widget. Though the value of the property is a pointer to an AECHAR, the property value must be set via a pointer to a FormRes data structure, which identifies the property value as either a resource file reference or as a direct pointer to the string to be displayed by the title widget. Property Value: AECHAR * FID_THEME: This property identifies the name of the theme file to be used by a particular dialog. Upon setting the theme file, BREW will load and apply the theme to the dialog. Property Value: char * FID_BACKGROUND: This property contains a pointer to the image that will be displayed in the dialog's background widget (which is different than the root form's background widget). Though the value of the property is a pointer to an IImage, the property value must be set via a pointer to a FormRes data structure identifying the property value as either a resource file reference or as a direct pointer to the IImage to be displayed by the background widget. Property Value: IImage * WID_BACKDROP: This property contains a pointer to the widget used to render the backdrop for the dialog. The backdrop provides a visual effect for the dialog, which makes it seem as though the dialog 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 dialogs 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_TITLE: This property contains a pointer to the dialog's title widget -- which is not the same as the root form's title widget. Generally, an application will choose to implement the title widget as a static, image or image static widget to produce the root form's title banner. An application could, however, implement the title widget using any widget of their choosing. Property Value: IWidget * WID_FORM: This property contains a pointer to the dialog's primary widget, which by default is an instance of TitleWidget (AEECLSID_TitleWidget). If this widget is replaced, it should maintain the properties of a TitleWidget, responding to PROP_TITLEWIDGET which a dialog uses to set title properties. Property Value: IWidget *