Resources | Resources |



Root container

Root Container is the highest level container defined for a single display. It manages the drawing of all child widgets.

The root container is derived from the XY container and its content is laid out in absolute (x, y) coordinates, occupying the entire extent of the display. Each display has one root container into which all other objects (including containers) are placed. The root container generally has a more complex container (IConstraintContainer, IPropContainer, etc) as its only child , which is easier to use when creating cohesive UIs. All other widgets would then be placed into this container rather than being inserted directly into the root container.

In addition to handling drawing and invalidation, applications can also query the root container for the touch observer and transition manager. The root container creates these objects dynamically the first time it receives a query for them.

To use widgets, applications should create an instance of root container and attach a canvas to it. The ICanvas interface provides a drawing surface for widgets to draw upon. The root container then draws all the widgets into this attached canvas. Applications that want to enable touch on a widget canvas should enable touch on the root container using the function IWidget_EnableTouch(), which sends the EVT_WDG_ENABLETOUCH event. The root container forwards the event to its children to enable touch in all widgets.

After touch is enabled in the root container, children added to the widget tree of the root container are automatically touch-enabled. These widgets instantiate default touch controllers as appropriate.

The following figure shows an example display of widgets, as well as the hierarchy of the containers and widgets that make up the display. The root container contains a constraint container, which is responsible for managing the layout of a static widget and two softkey widgets.

The root container is the background for everything else appearing on a display, and by default, the root container is created with a white background. This color can be changed by setting the PROP_BGCOLOR for the container by calling the inline function IWidget_SetBGColor().

Using root container

In the following example, the application first creates and sets up the display. It then calls ISHELL_CreateInstance() to create the root container and calls IRootContainer_QueryInterface() to obtain the widget object for use in widget API calls. It also creates a canvas, sets an IDisplay object for the canvas, and sets the canvas to the root container.

   ERR_TRY( ISHELL_CreateInstance(piShell, AEECLSID_DISPLAY,
               (void **)&piDisplay) );

   ERR_TRY( IDISPLAY_GetDeviceBitmap(piDisplay, &pb) );

   {  AEEBitmapInfo biDevice;
      (void) IBITMAP_GetInfo(pb, &biDevice, sizeof(biDevice));
      (void) IBITMAP_Release(pb);
      SETAEERECT(&me->rcContainer, 0, 0, (short), (short);
      // rcClient area starts out equal to rcContainer
      me->rcClient = me->rcContainer;

   ERR_TRY( ISHELL_CreateInstance(piShell, AEECLSID_CRootContainer,
               (void**)&me->picRoot) );
   ERR_TRY( IRootContainer_QueryInterface(me->picRoot, AEEIID_IWidget,
               (void**)&me->piwRoot) );

   ERR_TRY( ISHELL_CreateInstance(piShell, AEECLSID_DisplayCanvas,
               (void**)&piCanvas) );
   ERR_TRY( IDisplayCanvas_SetDisplay(piCanvas, piDisplay) );
   IRootContainer_SetCanvas(me->picRoot, (ICanvas*) (void*) piCanvas,