Developer

API Reference

IConstraintContainer

Brew Release
Brew MP 1.0.2
Description
The constraint container is derived from the base container object and is used to manage the widgets within a container where those widgets are laid out relative to either the container itself, or to each of the other objects held in the container. Objects are laid out in the order that the widgets appear in the container's widget stack, with the position of each object determined by the set of constraint elements -- one element per object coordinate. Constraint elements describe the location of a particular object coordinate, relative to the placement of the object's parent, the previous visible object in the constraint container's widget stack, or the object's existing or preferred size. For example, the left coordinate of an object may be described as being "2 pixels from the right coordinate of the previous object", or, the bottom of an object might be described as "0 pixels from the bottom coordinate of the object's parent". As the size and location of the constraint container changes, so do the sizes and locations of the objects held within. Likewise, as objects are added or removed from the container, or as individual constraint points are modified, the dimensions and placement of other objects will change.
For example, an application may wish to layout a pair of pushbuttons, side-by-side and anchored to the bottom of the display, like the following.
                    :   
   |                :                 |
   |                                  |
   |            Container             |
   |                                  |
   |+---------------++---------------+|
   ||   button 1    ||   button 2    ||
   |+---------------++---------------+|
   +----------------------------------+

Regardless of the dimensions of the container, the objects within will always be sized according to the defined layout for these objects, relative to the positions of other objects, or the constraint container itself. So, for example, if the constraint container in the above example were to change size, button1 and button 2 could maintain their relative size and position, like the following.
                              :             
   |                          :                           |
   |                                                      |
   |                 Constraint Container                 |
   |                                                      |
   |+-------------------------++-------------------------+|
   ||        button 1         ||        button 2         ||
   |+-------------------------++-------------------------+|
   +------------------------------------------------------+

The constraint container provides a loose vocabulary for defining the points of constraint for determining a widget's size or position. These points of constraint allow an object's size or position to be expressed in terms relative to the size or position to another object. Continuing the above example, the bottom of button 1 could be defined to be "0 pixels from the bottom of its parent", and its right side could be defined to be "50% of the parent's width".
In defining a point of constraint, each constant identifies the object from which relevance should be established -- this object being the parent of the object whose position is being determined, the object prior to that object, or the object itself. Consider a constraint container that is to manage a pushbutton, a checkbox, two radio buttons and a bitmap -- all created in exactly that order. The figure below illustrates the relationship between the container and each of the widgets created inside.
   
   Constraint
    Container ---+                              NULL <---+
                 |                                       |
                 |---- pushbutton      +---- previous ---+ <---+
                 |                                             |
                 |---- checkbox        +---- previous ---------+ <---+
                 |                                                   |
                 |---- radio button 1  +---- previous ---------------+ <---+
                 |                                                         |
                 |---- radio button 2  +---- previous ---------------------+ <---+
                 |                                                               |
                 +---- bitmap          +---- previous ---------------------------+


The constraint container is the parent of each of the 5 widgets. The widgets themselves are stored as a linked list of widgets, with a pointer back to the previous widget. Therefore, since the pushbutton is the first widget created, the previous widget is NULL. The checkbox, being created next, points back to the pushbutton, the first radio button points to the checkbox, the second radio button to the first, and so on. To declare, in the above example, that the checkbox is to be positioned relative to the top of the previous object, would be to indicate that it is to be positioned relative to the pushbutton, since the pushbutton is the object declared previous to the checkbox in the linked list.
Note, however, that objects are always laid out relative to other VISIBLE objects. So, if a constraint point has been defined relative to the previous object, and that object is invisible, BREW will traverse over the widget stack until it finds the first visible widget, and base the constraint point on that widget's layout. In the above example, let's say that the top of the bitmap widget is to be laid out relative to the bottom of the previous widget -- ordinarily, the second radio button. Now, let's say that both of the radio buttons are invisible. In this case, the previous visible object would be the checkbox, and the top of the bitmap widget will be laid out relative to the checkbox, rather than either radio button.
Supported Events: The constraint container passes all received events to the base container's event handler, where border, focus and widget events will be processed (see the description of supported events in AEEContainer.h for more information). If, in the process of handling the event, the constraint container's client rectangle changes, the layout of objects within the container will be rearranged to accommodate the new container size.
Usage
The developers can use constraint container object whenever they would like to have the position of the objects within the container be laid out based on their constraints relative to the parent, previous visible object, or the center of the container. To insert widgets in a container use ICONSTRAINTCONTAINER_Insert() where the type of the constraint that one would use for inserting a widget should be specified in WidgetConstraint. To remove the inserted widgets one can use ICONSTRAINTCONTAINER_Remove().
See usage of IContainer.
Comment
None
  • Follow