Developer

API Reference

IForm

Brew Release
Brew MP 1.0.2
See Also
IHandler Widget Events Form Model Events Model Events FormEvent
Description
IForm is a user interface element that allows applications to easily build screens that share a common look and feel and abide by a standard appearance theme. By utilizing forms and themes, the visual appearance of an application can very easily be modified to support a common user experience across multiple applications. For example, by using forms and themes, all the static widgets of an application can share the same background color or level of transparency. Likewise, each screen in the application can maintain a common visual structure -- title area, content, plus a pair of softkeys.
A single form defines structure, organization and behavior for a single screen. A list of contacts in an address book application, a screen laid out like a questionnaire, or even a popup menu providing simple commands can all be thought of as separate forms. In fact, BREW provides default form implementations for lists, dialogs and popups, while providing the capability for applications to derive their own form implementations.
The base form consists of the following visual characteristics:
   
       +-----------------------------------+
       |               Title               |  <--------  Title area of the form
       +-----------------------------------+
       |                                   |
       |                                   |
       |                                   |
       |                                   |
       |                                   |
       |                                   |
       |                                   |  <--------  Background area of the form
       |                                   |             (occupies the entire extent
       |                                   |              of the display, behind the
       |                                   |              title and softkeys)
       |                                   |
       |                                   |
       +-----------------------------------+
       |    Softkey 1    |    Softkey 2    |  <--------  Softkey area of the form
       +-----------------------------------+

Both the title and softkey areas of the form are optional. If either is missing, the client may claim that area for its own use. The title area of the form, when present, may contain a static text string, an image, or both an image and text. The form may display a pair of softkeys, each generally corresponding to hardware keys placed immediately below the display on the target device. The background provides a backdrop for the content that will be placed onto the form. This backdrop might be as simple as a subtle shading of color, or it could be an elaborate graphic image containing winking dancing girls -- whatever is most appropriate for the content and spirit of the application (it is doubtful that an online "places of worship locator" would use the winking dancing girls). The background area covers the entire extent of the form's root container and will contain a color or background image over which all other form elements will be displayed.
In addition to its visual characteristics, a form also maintains information about its model, its collection of contained widgets, the theme used to render those widgets, and a pointer back to the root form that owns this form. These relationships can be further illustrated, as follows -
   


    +-----------------+                           +-----------------+
    |      Model      | <----+             +----> |      Theme      |
    +-----------------+      |             |      +-----------------+
                             |             |
                             |             |
                        +----|-------------|----+
                        |    |             |    |
                        |    +             +    |
                        |                       |
                        |                       |
                        |         Form          |
                        |                       |
                        |                       |
                        |    +             +    |
                        |    |             |    |
                        +----|-------------|----+
                             |             |
                             |             |
    +-----------------+      |             |      +-----------------+
    |    Root Form    | <----+             +----> |     Widget      |
    +-----------------+                           +-----------------+

The form's model acts as a conduit through which the form is able to notify registered objects of EVT_MDL_FORM_CHANGE events. The form contains a primary widget, which itself is generally a container that will wrap the collection of widgets (text, buttons, images, checkboxes, etc) to be presented on the form. The theme identifies an appearance to be applied to each widget contained within the form. The root form points back to the object that manages the layering of the current stack of forms.
An application may choose to employ one form, or it could define multiple forms that the user navigates as they use the application. In either case, whether there is one form or many, BREW will always maintain the concept of a "root form" -- which is not really a form itself, rather, it is the root entity which organizes all of the forms currently defined by an application. Conceptually, the root form is similar to a window manager in a traditional desktop GUI, handling form activation, managing form layering and arbitrating events to objects contained within the form.
The root form itself is the structure upon which the forms it manages will be built, as illustrated by the diagram below -
                                                   Root  Form      
                                            +----------------------+
                                            |                      |
      +------+            Vector <--------------+  Model           |
      |      |             Model            |                      |
      |      |       +---------------+      |                      |
      |      |       |               |      |      Widgets +-------------------+
   +------+  | <--------+  Form 1    |      |                      |           |
   |      |  |       |               |      |                      |           |
   |      |--+       +---------------+      |   + Root Container   |           |
   |      |          |               |      |   |                  |           |
   |      | <-----------+  Form 2    |      +---|------------------+           |
   |      |          |               |          |                              |
   +------+          +---------------+          |                              |
    Forms            |               |          |                              |
                     |       :       |          |                              |
                                                |                              |
                                                |                              |
                                                |                              V
                                                V                  +------------------------+     
                                       +-----------------+         |                        | 
                                       |                 | <- - - - - +  Title widget       |
                                       +-----------------+         |                        |
                                       |                 |         +------------------------+
                                       |                 |         |                        |
                                       |                 | <- - - - - +  Background widget  |
                                       |                 |         |                        |
                                       |                 |         +------------------------+
                                       +-----------------+         |                        |
                                       |        |        | <- - - - - +  Softkey widget     |
                                       +-----------------+         |                        |
                                                                   +------------------------+

The root form relies on a vector model to manage the "form stack". The form stack represents the display order of all the forms that have been created, with the form on the top of the stack being in the foreground of the display. Once that form is popped off the stack, the next form on the stack bubbles up to the top and takes over the display. The root form can manipulate its attached vector model however it chooses, removing forms from within the stack, or creating new forms at a particular place on the stack.
The form stack should never have duplicate forms in it, as properties associated with each form are maintaned by the root form, and can differ depending on whether the form is active (on top of the stack), visible (behind a dialog or popup), or completely hidden.
The vector model that supports the root form stores pointers to those forms that the root form creates. In addition to attaching itself to a vector model, the root form defines the container into which the form elements (title, background and softkeys) will be placed. As a form is popped to top of the stack, the root form retrieves the form pointer, updates the title, softkey, and background widgets, then populates the root container with the contents of the form.
Supported Events: The base form event handler is responsible for accepting and processing various events that identify key presses, manage the form stack and access various form properties.
The events handled by the form interface include:
Event                   Description
-----                   ------------------------------------------------------------
EVT_FORM_POP:           The base form event handler responds to this event by instructing the root
                        form to remove this form from the form stack.

EVT_FORM_CANCEL:        The base form event handler responds to this event by sending an EVT_FORM_POP
                        event back through the form event handling hierarchy.  This gives hooked
                        event handlers an opportunity to handle the event, whereas the event would
                        eventually make it back to the base form event handler where the root form
                        would remove this form from the form stack.

EVT_KEY:                The base form event handler responds to the EVT_KEY if the key is AVK_CLR
                        or the key specified by the FID_CANCELKEY property. It sendings an 
                        EVT_FORM_CANCEL event back through the form event handling hierarchy.  

EVT_WDG_SETPROPERTY:    The base form handler responds to this event by attempting to set 
                        the property identified by the 'wParam' parameter. The 
                        following properties may be set by the base form event handler.
                      
                        WID_FORM       --      Sets the primary widget associated with the form and
                                               sends a form event to listening objects to notify
                                               them that the primary widget has changed.
                        FID_ROOT       --      Sets the root form that will control this form.
                        FID_ACTIVE     --      Sets the activation state of the form.
                        FID_VISIBLE    --      Sets the visible state of the form.
                        FID_THEME_BASENAME --  Sets the theme basename for this form. Setting this 
                                               property will cause an event to be sent out notifying
                                               listening objects that the basename of the form has 
                                               changed.
                        FID_THEME      --      Requests a form to apply the current theme.
                        FID_BACKGROUND --      Sets the background image for the form and sends a form
                                               event to listening objects to notify them that the
                                               background has changed.
                        FID_TITLE      --      Sets the title text of the form and sends a form event
                                               to listening objects to notify them that the title
                                               content has changed.
                        FID_TITLEIMAGE --      Sets the title image of the form and sends a form event
                                               to listening objects to notify them that the title
                                               content has changed.
                        FID_SOFTKEY1   --      Sets the text of the form's left softkey and sends a form
                                               event to listening objects to notify them that the softkey
                                               content has changed.
                        FID_SOFTKEY2   --      Sets the text of the form's right softkey and sends a form
                                               event to listening objects to notify them that the softkey
                                               content has changed.                                               

EVT_WDG_GETPROPERTY:    The base form handler responds to this event by attempting to retrieve the
                        property identified by the 'wParam' parameter.  The following properties may
                        be retrieved by the base form event handler - 
                      
                        WID_FORM       --      Retrieves the primary widget associated with the form, incrementing 
                                               the reference count of the widget.
                        FID_SHELL      --      Retrieves a reference to the IShell object used by the form, 
                                               incrementing the reference count of the IShell object.
                        FID_ROOT       --      Retrieves the root form that will control this form, incrementing 
                                               the reference count of the root form.
                        FID_ACTIVE     --      Retrieves the activation state of the form.
                        FID_VISIBLE    --      Retrieves the visible state of the form
                        FID_THEME_BASE --      Retrieves the theme base used by this form.
                        FID_BACKGROUND --      Retrieves the image this form will use to display its
                                               background, incrementing the reference count of the image.
                        FID_PREFRECT   --      Retrieves the preferred screen rectangle of the form widget. 
                                               Used during activation or showing of the form (FID_ACTIVE, FID_VISIBLE) 
                                               to position and size the widget.
                        FID_ISPOPUP    --      Retrieves TRUE if the form is implemented as a popup, FALSE
                                               if it is not.
                        FID_TITLE      --      Retrieves the title text of the form.
                        FID_TITLEIMAGE --      Retrieves the title image of the form, incrementing 
                                               the reference count of the image.
                        FID_SOFTKEY1   --      Retrieves the text of the form's left softkey.
                        FID_SOFTKEY2   --      Retrieves the text of the form's right softkey.
                        FID_FORMMODEL  --      Retrieves a reference to the form model attached to the form, 
                                               incrementing the reference count of the model.

Properties:



Property Description -------- ------------------------------------------------------------
WID_FORM: This property contains a pointer to the form's primary widget, which serves as the container object for all other widgets contained within the form.
Property Value: IWidget *
WID_TITLE: This property contains a pointer to 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_SOFTKEYS: This property contains a pointer to the root form's softkey widget. Though the root form's softkey widget is commonly implemented as a softkey widget, an application could implement the root form softkey widget using any widget of their choosing.
Property Value: IWidget *
WID_BACKGROUND: This property contains a pointer to the root form's background widget. Generally, an application will choose to implement the background widget as an image widget, which allows the application to place a graphic image into the form's background, or -- since the image widget understands border properties -- create any visual effect inherent in borders (color, shading, transparency, etc) without any image present at all. Though the root form's background widget is commonly implemented as an image widget, an application could implement the root form background widget using any widget of their choosing.
Property Value: IWidget *
WID_DECORATOR: This property contains a pointer to a form's decorator widget for those specialized forms that have derived from the base form. For example, the list form defines a list widget (which derives from the decorator widget) to manage list data in an expected and consistent manner. It is important to note that the decorator widget is provided in _addition_ to the form's primary widget accessed by the WID_FORM property. It is also important to emphasize that the interpretation of the WID_DECORATOR property is at the discretion of a particular form implementation. For example, a specialized 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: IWidget *
WID_PROGRESS: This property contains a pointer to a form's progress widget for those specialized forms that have derived from the base form. For example, the progress dialog is a specialized form that derives from dialogs, popups and -- eventually -- back to forms. The progress dialog defines a progress widget -- typically to popup a quick dialog to illustrate progress for some time consuming operation. The WID_PROGRESS property allows applications to access the progress widget that provides this visual feedback. It is important to note that the progress widget is provided in _addition_ to the form's primary widget accessed by the WID_FORM property.
Property Value: IWidget *
WID_LIST: This property contains a pointer to a form's list widget for those specialized forms that have derived from the base form. For example, the popup menu, which derives from a form presents its menu items using a list widget. This list widget is stored in the WID_LIST property. It is important to note that the list widget is provided in _addition_ to the form's primary widget accessed by the WID_FORM property. Likewise, it is also important to emphasize that the interpretation of the WID_LIST property is at the discretion of a particular form implementation. For example, a specialized form that supports the ability to browse through a list of photographs, displaying a thumbnail of the current selection in an image viewer, might respond to queries for the WID_LIST property by returning a pointer to the list widget used to browse the names of the photos, while a pointer to the image viewer widget might be returned when asked for the WID_DECORATOR property. The list is just a list, while the image viewer decorates that list.
Property Value: IWidget *
WID_LISTITEM: This property contains a pointer to the widget used to render each item contained in a form's list. This is, effectively, the widget wrapped within the form's WID_LIST (or WID__DECORATOR, in the case of list forms) property.
Property Value: IWidget *
WID_CONTAINER: This property contains a pointer to the form's root container, which serves as the container object for all other objects contained within the root form. This will include the title, background and softkey widgets, as will as the primary widget and all widgets it may contain.
Property Value: IContainer *
WID_BACKDROP: This property contains a pointer to the widget used to render a form's backdrop image. Generally, the backdrop is used by those specialized forms that have derived from the base form, such as popups or dialogs. The "backdrop" is distinguished from the "background" as being the visual element that appears to lay behind and beneath the form appearing in the foreground -- again, using a popup dialog that seems to float above the backgro0und display. The backdrop would appear, in this case, as a subtle wash or shadow effect to emphasize that the dialog or popup is "above" the rest of the display. The WID_BACKDROP property allows applications to access the backdrop widget that provides this visual feedback. It is important to note that the backdrop widget is provided in _addition_ to the form's primary widget accessed by the WID_FORM property, as well as the root form's background widget accessed by the WID_BACKGROUND property.
Property Value: IWidget *
WID_STATIC: This property contains a pointer to a form's static widget for those specialized forms that have derived from the base form. For example, the static dialog is a specialized form that derives from dialogs, popups and -- eventually -- back to forms. The static dialog defines a static widget that displays text messages in a popup dialog. The WID_STATIC property allows applications to access the static widget that displays the text for the dialog. It is important to note that the static widget is provided by the specialized form in _addition_ to the form's primary widget accessed by the WID_FORM property.
Property Value: IWidget *
FID_ACTIVE: This property contains the activation state of the form -- TRUE when the form is active, FALSE when it is not. Setting the activation state of the form will trigger the form to invalidate itself and be redrawn. Setting the activation state of the root form will cause only the topmost form on the form stack to be activated or deactivated, and -- on activation -- will further invalidate the root container, causing all the child objects to be redrawn. On activation FID_PREFRECT is requested of the form to get the preferred screen rectangle of the form widget.
Property Value: boolean
FID_VISIBLE: This property contains the visible state of the dialog -- TRUE when the form may be all or partially visible, FALSE when it is not. Setting the visible state of the form may trigger an invalidation if the root form client region has changed.
Usage

The typical usage of a class implementing IForm would be to create an instance of a class that implements IForm, then set any properties desired in order to customize the appearance or behaviour of this instance, such as background image, background color, and the initial model data.
The following APIs are provided by the form interface to support an object reference counting mechanism allowing form objects to manage their own memory instances.
       IForm_AddRef()
       IForm_Release()

The following API is provided to query an object for another API contract from the object in question (in this case, the form interface)
       IForm_QueryInterface()

The following APIs are provided to support event handling to the form object:
       IForm_HandleEvent()
       IForm_SetHandler()
       IForm_SetSelectHandler()

The following APIs are provided to set and retrieve various properties of a form object:
       IForm_SetProperty()
       IForm_GetProperty()

The following APIs are provided to manage activation and deactivation of form objects:
       IForm_Activate()
       IForm_Deactivate()
       IForm_IsActive()

The following APIs are provided to set and retrieve the widget that will act as the parent for all other widget's to be contained in a form -
       IForm_SetWidget()
       IForm_GetWidget()

The following API is provided to retrieve the root form that manages a particular form object -
       IForm_GetRootForm()

The following APIs are provided to retrieve the title, softkey, background, progress and decorator widgets associated with a particular form -
       IForm_GetTitleWidget()
       IForm_GetSoftWidget()
       IForm_GetBGWidget()
       IForm_GetProgressWidget()
       IForm_GetDecoratorWidget()

The following APIs are provided to set the contents of the standard user interface elements (title, softkey, background, etc) associated with a form -- either directly, or by taking the value from a particular resource file -
       IForm_SetRes()
       IForm_SetPtr()
       IForm_SetText()
       IForm_SetResText()
       IForm_SetTitle()
       IForm_SetSoftkey()
       IForm_SetBGImage()
       IForm_SetResBGImage()
       IForm_SetTitleImage()
       IForm_SetResTitleImage()
       IForm_SetProgress()
       IForm_SetSoftkeys()

The following APIs are provided to retrieve the contents of the standard user interface elements (title, softkey, background, etc) associated with a form -
       IForm_GetTextPtr()
       IForm_GetBGImage()
       IForm_GetTitleImage()
       IForm_GetIsPopup()

The following APIs are provided to set and retrieve information about the theme that will be used by the form to customize the appearance of the objects it will display -
       IForm_SetThemeBaseName()
       IForm_GetThemeBaseName()

The following API is provided to retrieve information about the models associated with a form -
       IForm_GetFormModel()
  • Follow