Developer

API Reference

IRootContainer

Brew Release
Brew MP 1.0.2
See Also
- IContainer Interface
- ICardContainer Interface
- IConstraintContainer Interface
- IPropContainer Interface
- IXYContainer Interface
Description
The root container is derived from the XY container object and is the highest level container object defined for a single display. Each display will have, at its base, one and only one root container, into which all other objects (including containers) will be placed. The root container is laid out in absolute (x, y) coordinates, occupying the entire extent of the display. It is at the base of all other drawing. To illustrate the relationship of the root container to other containers and objects placed on a display, consider the following illustration:
   +---------------------------------------------+
   | Root Container                              |
   | +-----------------------------------------+ |
   | | Constraint Container                    | |
   | | +-------------------------------------+ | |  + Root Container
   | | |            Static Widget            | | |    ----+---------
   | | +-------------------------------------+ | |        |
   | |                                         | |        + Constraint Container
   | |                                         | |          ----+---------------
   | |                                         | |              |
   | |                                         | |              + Static Widget
   | |                                         | |              |
   | |                                         | |              + Softkey Widget
   | |                                         | |              |
   | |                                         | |              + Softkey Widget
   | |                                         | |
   | |                                         | |
   | |                                         | |
   | |                                         | |
   | | +-------------------------------------+ | |
   | | |  Softkey Widget  |  Softkey Widget  | | |
   | | +-------------------------------------+ | |
   | +-----------------------------------------+ | <------ Same extent as the display
   +---------------------------------------------+

Here, the root container is the grand daddy of all objects. It is king, ruler, and omnipotent despot. It is at the base of every other object to be shown on the display. Within the root container, a constraint container has been created which is responsible for managing the layout of a static widget and two softkeys. The object hierarchy is illustrated to the right of the diagram, with the root container at the base, and all other objects being "contained" within this root container.
As the ultimate background for everything else appearing on a display, the root container is created with a white background, though this color may be changed by setting the PROP_BGCOLOR for the container.
Supported Events: The root container processes events in two passes. The root container will first attempt to process property events involving the containers background color. All other events will be passed to the base container event handler where border, focus and widget events will all be processed.
The root container will accept the following events:
Event                 Description
-----                 ------------------------------------------------------------
EVT_WDG_SETPROPERTY:  The root container responds to this event by attempting to set the
                      property identified by the 'wParam' parameter.  The root container
                      allows the following properties to be set:

                          PROP_BGCOLOR  --  Sets the background color that will be used to
                                            render the background of the container.

                      These properties are discussed below in greater detail.

EVT_WDG_GETPROPERTY:  The root container responds to this event by attempting to retrieve the
                      property identified by the 'wParam' parameter.  The root container allows
                      the following properties to be retrieved, returning the value of the
                      property in the pointer pointed to by 'dwParam':

                          PROP_BGCOLOR  --  Gets the background color that will be used to
                                            render the background of the container.
                           
                          PROP_EX       --  RootContainer supports an extended property
                                            PROPEX_SCREEN.

                      These properties are discussed below in greater detail.


Properties: Property Description -------- ------------------------------------------------------------
PROP_BGCOLOR: This property contains the color the root container will use to draw its background.
Property Value: RGBVAL
PROPEX_SCREEN: This property contains the location of canvas to which RootContainer draws on screen. This property is supported as GetOnly Property via PROP_EX.
Property Value: AEERect*.
Only x and y members of the AEERect structure are modified.
Required Model: None
Model Data: None
Usage
See IContainer usage.
The Root Container is generally only instantiated once for any given module as it lives on a high perch at the top of any widget tree (It's good to be king). It also generally only has one child widget as its sibling interfaces such as IConstraintContainer and IPropContainer are generally much more capable of dealing with impressive issues such as phones with different view ratios and pixel counts. No matter how many children a root container has, the first step is generally to attach a Canvas to the root container so that it has somewhere to draw all those wonderful widgets you are going to take the time to attach into the widget tree.
Comment
None
  • Follow