Developer

API Reference

IRootForm

Brew Release
Brew MP 1.0.2
Description
IRootForm is the conceptual entity that lends structure and organization to a group of forms. It is the interface that defines the visual components common to a collection of forms, such as the title, background and softkeys -- while also managing the order and relationship each of its children have with one another, i.e. which form is at the top of the display stack, which is next when that form is removed, which is next after that, and so forth.
The root form is responsible for providing the base structure upon which an application's forms will be built, providing the standard interface components that all child forms will leverage, including the background, title and softkey widgets. These interface elements are owned by the root form, with each child form providing the content to be displayed. For example, an application for coffee junkies may provide several different forms -- one for browsing pictures of exotic beans, one that displays help for caffeine addiction, and one for locating your online buddies who can help you score some Indonesian Sumatra. As the user moves from screen to screen the background, title and softkeys could change to reflect the current application context. When looking a the bean list, the title may read "Beans" with a lovely semi transparent picture of a bean displayed in the background. Move to the caffeine page and the background becomes a skull and crossbones with "Caffeine" in the title, and so forth. Each of these screens is a separate form, and though the content of the title, background and softkeys may differ from form to form, these forms share a single instance of the widgets used to present each visual element. The forms provide the content, while the root form provides the structure.
That said, without content, a root form is not really a form at all! It is a skeleton upon which real forms will be built. In addition to the base visual characteristics of background, title and softkeys, the root form is also responsible for providing organization to its child forms. 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 frames 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.
The following APIs are provided by the root form interface to support an object reference counting mechanism allowing form objects to manage their own memory instances.
       IRootForm_AddRef()
       IRootForm_Release()

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

The following API is provided to support event handling to the root form object.
       IRootForm_HandleEvent()

The following APIs are provided to manage activation and deactivation of forms managed by the root form.
       IRootForm_Activate()
       IRootForm_Deactivate()

The following APIs provide the ability to manage and manipulate the current form stack.
       IRootForm_InsertForm()
       IRootForm_RemoveForm()
       IRootForm_GetForm()
       IRootForm_PopForm()
       IRootForm_PushForm()
       IRootForm_IsFormOnStack()
       IRootForm_GetTopForm()
       IRootForm_RemoveFormIfTop()
       IForm_PopSelf()

The following API is provided to resolve form based URL schemes and create an instance of the class ID that will provide the handler for this scheme.
       IRootForm_ResolveForm()

The following API is provided to retrieve the client rectangle exposed by the root form.
       IRootForm_GetClientRect()

Supported Events: The root form processes events in three passes. In the first pass the event will be passed to the root form's form widget -- the root container for every form managed by the root form. This pass gives the common user interface elements such as the title, background and softkey widgets an opportunity to process the event. If the event is not processed by the root container, the root form will attempt to process any property events specifically related to the root form. For example, the root form is responsible for returning the title widget when asked to retrieve the WID_TITLE property. These properties also include those that manage form activation and theme usage. Events not handled during the first or second pass will then be handed off to the top form in the root form's form stack.
The events accepted by the root form interface include.
Event                 Description
-----                 ------------------------------------------------------------
EVT_WDG_SETPROPERTY:  The root 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 root form event handler.
                      
                          FID_ACTIVE     --  Sets the activation state of the topmost form and (on
                                             activation) invalidates the root container.
                          FID_THEME_BASENAME --  Sets the theme base for the root form and sends a form
                                             event to listening objects to notify them that form
                                             elements should be re-rendered using the new theme.
                          FID_THEME      --  Requests a form to apply its current theme. The RootForm
                                             will request all forms on the form stack to apply the 
                                             current theme.
                          FID_THEME_FNAME --  Sets the filename used for applying themes. The file name
                                             is used by the currently installed theme file (IResFile). 
                          FID_BACKGROUND --  Sets the background image to be used by forms managed
                                             by the root form.
                          WID_BACKGROUND --  Sets the background widget to be used by forms managed
                                             by the root form, releasing any existing background
                                             widget and replacing it with the widget pointed to by
                                             'dwParam'.
                          WID_TITLE      --  Sets the title widget to be used by forms managed by
                                             the root form, releasing any existing title widget and
                                             replacing it with the widget pointed to by 'dwParam'.
                          WID_SOFTKEYS   --  Sets the softkey widget to be used by forms managed by
                                             the root form, releasing any existing softkey widget and
                                             replacing it with the widget pointed to by 'dwParam'.
                          FID_DISPLAY    --  Sets the display to be used for the RootForm and all the
                                             forms and widgets it manages. The background, title and 
                                             softkey widget are resized horizontally and vertically to
                                             fit the given display size.

EVT_WDG_GETPROPERTY:    The root 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 root form event handler.
                      
                            FID_THEME_FNAME --  Retrieves the name of the theme file used by the root form.
                                                The string is not copied and should not be freed by the caller.
                            FID_THEME_BASENAME --  Retrieves the theme base used by the root form.
                            FID_THEME_FILE --  Retrieves the current theme file from the RootForm. 
                                               Note that this property can only be retrieved at this time.
                            FID_SHELL      --  Retrieves a reference to the IShell object used by the root
                                               form, incrementing the reference count of the IShell object.
                            WID_TITLE      --  Retrieves a pointer to the root form's title widget, incrementing 
                                               the reference count of the title widget.
                            WID_SOFTKEYS   --  Retrieves a pointer to the root form's softkey widget, incrementing 
                                               the reference count of the softkey widget.
                            WID_BACKGROUND --  Retrieves a pointer to the root form's background widget, incrementing 
                                               the reference count of the background widget.
                            WID_FORM       --  Retrieves the primary widget associated with the root
                                               form, incrementing the reference count of the widget.  Typically 
                                               (though not necessarily), this is the root form's root container.
                            WID_CONTAINER  --  Retrieves the root container, incrementing 
                                               the reference count of the root container.

Properties:
Property            Description
--------            ------------------------------------------------------------
WID_FORM:           This property contains a pointer to the root form's primary widget, which -- in most
                    cases -- will be the root container for all forms managed by the root form.  An
                    application could, however, choose to wrap the root container in another widget
                    (for example, in a border widget) and the WID_FORM property will point to this
                    parent widget.
                             
                        Property Value:  IWidget *
                                    
WID_CONTAINER:      This property contains a pointer to the root form's root container -- the container
                    that serves as the parent for each of the base UI elements provided by the root
                    form (background, title and softkey widgets).
                             
                        Property Value:  IContainer *
                                    
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.

                    Note: If set, it should be done prior to setting FID_TITLE on
                    the active form as this value will not be copied over to the new widget.                    
                              
                        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 an softkey widget, an
                    application could implement the root form softkey widget using any widget of their
                    choosing.

                    Note: If set, it should be done prior to setting FID_SOFTKEY1 or FID_SOFTKEY2 on
                    the active form as these values will not be copied over to the new widget.

                        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 *

FID_ACTIVE:         This property contains the activation state of the root form -- TRUE when the root
                    form is active, FALSE when it is not.  Setting the activation state of the root
                    form will trigger a like event to be sent to the topmost form -- providing an
                    opportunity for the form at the top of the form stack to activate or deactivate its
                    contents.  On activation, the roof form will further invalidate the root container,
                    causing all the child objects to be redrawn.
                             
                        Property Value:  boolean

FID_THEME:          This property has applies the current theme, as indicated by the current themefile, 
                    to the RootForm and all forms on the form stack. This will also trigger an update to 
                    the UI elements managed by the RootForm, such as the title, softkeys and background.
                    This property can only be set. 

                        Property Value: None

FID_DISPLAY:        This property specifies the display to be used for drawing the RootForm, the forms it 
                    manages and all the widgets they contain.
                    This property can only be set.
                             
                        Property Value:  IDisplay *


FID_THEME_FNAME:    This property identifies the name of the theme file to be used by the root form.
                    Setting FID_THEME_FNAME property will set the theme file to be used by the root 
                    form and each of the forms on the form stack and will also trigger an update of 
                    the root form's common UI elements, which will be redrawn using the new theme metrics.  
                             
                        Property Value:  char *

FID_THEME_BASENAME: This property specifies a string that identifies the base location within a theme file 
                    for the RootForm to locate properties. Most, if not all UI elements managed by the RootForm 
                    are themed through the currently activated Form, but there may be UI elements that are globally 
                    themed by the RootForm.  Setting this property will fire a formmodel event notifying 
                    listening objects that the basename of the form has changed.
                             
                        Property Value:  char *

FID_THEME_FILE:     This property retrieves the currently used themefile from the RootForm. The object referred to 
                    is an IResFile interface to reflect the named and numbered resources available for theming. 
                    Note that this form property is currently only retrievable and can not be set.
                             
                        Property Value:  IResFile *

FID_SHELL:          This property contains a reference to the IShell object used by the root form.  The
                    property returns a pointer to the IShell instance in the 'dwParam' parameter passed
                    to the root form with the EVT_WDG_GETPROPERTY event.
                              
                    Forms do not support attempts to set the FID_SHELL property.

                        Property Value:  IShell *

FID_BACKGROUND:     This property contains a pointer to a FormRes data structure which will contain either
                    a reference to a resource containing the background image, or it will contain a pointer
                    to where the IImage is currently loaded into memory.  The root form does not support
                    the ability to retrieve the FID_BACKGROUND property.
                             
                        Property Value:  FormRes *
Usage
See IRootForm Description.
  • Follow