Developer

API Reference

IPropContainer

Brew Release
Brew MP 1.0.2
See Also
-IContainer
Description
The prop container is derived from the base container object and is used to manage the widgets within a container where those widgets are laid out (in proportion to one another) along the same vertical or horizontal direction. Having derived from the base container, the prop container maintains each of the characteristics common to the container object, while an additional attribute describes the direction of the objects are to be laid out within the container.
Objects are laid out left to right or top to bottom in the order that the widgets appear in the container's widget stack, with the prop container dictating the extent granted to each object. The prop container will determine each object's extent based on that object's proportional value -- a value that is expressed either explicitly of as a ratio component that is measured in relationship to all other objects within that container, or implicitly as a constant that will determine the size of the object independent of other objects held within the container. Therefore, depending on the requirements of each object held in the container, the relative size of the objects within that container may vary as the size of the container changes.
To illustrate, consider for a moment a prop container laid out horizontally that contains one object that MUST maintain a constant width, but two additional objects that don't really care how about their width -- but they do want to be of equal size. On one display, these objects might be laid out as follows.
   
                        Prop Container
   +----------------------------------------------------+
   |+-------------------+ +------------+ +------------+ |
   ||                   | |            | |            | |
   ||                   | |            | |            | |
   ||      Object       | |   Object   | |   Object   | |
   ||   that must be    | | that does  | | that does  | |
   ||   exactly this    | |  not care  | |  not care  | |
   ||      width        | |            | |            | |
   ||                   | |            | |            | |
   ||                   | |            | |            | |
   ||                   | |            | |            | |
   ||                   | |            | |            | |
   |+-------------------+ +------------+ +------------+ |
   +----------------------------------------------------+


The first object has requested that it be displayed using a constant width, no matter what, so it will always be the same horizontal extent. The other two objects will adjust the width of their extent based on whatever space is leftover once the first object has consumed all the space it needs. Again, to illustrate how the objects will adjust depending on the size of the prop container, let's make the container wider and see what happens, okay?
   
                                         Wider Prop Container
   +--------------------------------------------------------------------------------------+
   |+-------------------+ +-----------------------------+ +-----------------------------+ |
   ||                   | |                             | |                             | |
   ||                   | |                             | |                             | |
   ||      Object       | |            Object           | |            Object           | |
   ||   that must be    | |          that does          | |          that does          | |
   ||   exactly this    | |           not care          | |           not care          | |
   ||      width        | |                             | |                             | |
   ||                   | |                             | |                             | |
   ||                   | |                             | |                             | |
   ||                   | |                             | |                             | |
   ||                   | |                             | |                             | |
   |+-------------------+ +-----------------------------+ +-----------------------------+ |
   +--------------------------------------------------------------------------------------+


Oh my, look at that! Each of the objects that were willing to grow to the size of the container have, in fact, grown! And yet, they are still the same size. This is because each of these objects have requested proportions of equal values -- so their ratio would be 1:1 (all things being equal). But what if that were not the case? What if one of those objects wanted to be twice as big as the other "adjustable" object? In that case, that object would set its proportional value to be double that of the other object, resulting in a ratio of 2:1 and a distribution of objects that would look like the following.
   
                                         Wider Prop Container
   +--------------------------------------------------------------------------------------+
   |+-------------------+ +-------------------+ +---------------------------------------+ |
   ||                   | |                   | |                                       | |
   ||                   | |                   | |                                       | |
   ||      Object       | |      Object       | |                 Object                | |
   ||   that must be    | |  of normal size   | |             of double size            | |
   ||   exactly this    | |   at ratio 1:2    | |              at ratio 2:1             | |
   ||      width        | |                   | |                                       | |
   ||                   | |                   | |                                       | |
   ||                   | |                   | |                                       | |
   ||                   | |                   | |                                       | |
   ||                   | |                   | |                                       | |
   |+-------------------+ +-------------------+ +---------------------------------------+ |
   +--------------------------------------------------------------------------------------+


Notice in each of the above horizontal layout examples that the vertical extent of each object extends to be the full height of the prop container. When laying out the objects within a container, the prop container applies its layout algorithm only in the direction of the container's layout, and will provide an "opposite direction" extent that is the maximum value that the container will accommodate. So, when laying out objects in the horizontal direction, the vertical extent of each object will be set to the vertical extent of the container. Likewise, when laying out objects in the vertical direction, the horizontal extent of each object will be set to the horizontal extent of the container.
Next, let's look at an example of a vertical prop container layout that illustrates how fixed and proportional objects can be mixed within the same container. This container will include three objects of a fixed vertical extent, as well as two variable height objects that will all be of equal proportions.
         Order the objects will be laid out
        ------------------------------------
           1. Set height object
           2. Variable height object (1:1 ratio)
           3. Set height object
           4. Variable height object (1:1 ratio)
           5. Set height object


When laid out by the prop container, the 1st, 3rd and 5th objects all require a set amount of space, regardless of the size of the container. The 2nd and 4th objects get what space is left after the set objects have had their space reservations filled, and will divide that space equally. All five objects will still appear in the container in the order that they are managed by the container's object stack, but will be sized as follows.
   
            Prop Container                          Smaller Container
   +-------------------------------+        +-------------------------------+
   |+-----------------------------+|        |+-----------------------------+|
   ||                             ||        ||                             ||
   ||          Object #1          ||        ||          Object #1          ||
   ||                             ||        ||                             ||
   |+-----------------------------+|        |+-----------------------------+|
   |+-----------------------------+|        |+-----------------------------+|
   ||                             ||        ||          Object #2          ||
   ||                             ||        |+-----------------------------+|
   ||                             ||        |+-----------------------------+|
   ||                             ||        ||                             ||
   ||          Object #2          ||        ||          Object #3          ||
   ||                             ||        ||                             ||
   ||                             ||        |+-----------------------------+|
   ||                             ||        |+-----------------------------+|
   ||                             ||        ||          Object #4          ||
   |+-----------------------------+|        |+-----------------------------+|
   |+-----------------------------+|        |+-----------------------------+|
   ||                             ||        ||          Object #5          ||
   ||          Object #3          ||        |+-----------------------------+|
   ||                             ||        +-------------------------------+
   |+-----------------------------+|
   |+-----------------------------+|
   ||                             ||
   ||                             ||
   ||                             ||
   ||                             ||
   ||          Object #4          ||
   ||                             ||
   ||                             ||
   ||                             ||
   ||                             ||
   |+-----------------------------+|
   |+-----------------------------+|
   ||          Object #5          ||
   |+-----------------------------+|
   +-------------------------------+

Note in the above example that the three set objects (1, 3 and 5) all maintain the same vertical extent when the container size is made smaller, while the variable size objects (2 and 4) maintain their 1:1 relational ratio, but require a smaller vertical extent in the smaller prop container.
Once granted an extent by the prop container, it is then up to each object to draw itself within the space it has been allotted, which will depend on the drawing and layout capabilities of that particular object.
Supported Events: The prop container processes events in two passes. The prop container first passes all events to the base container, which will handle events relating to the container's focus. Events not handled during this first pass will then be handled by the prop container itself.
The prop container will accept the following events.
Event                 Description
-----                 ------------------------------------------------------------
EVT_WDG_SETPROPERTY:  The prop container responds to this event by attempting to set the
                      property identified by the 'wParam' parameter.  The prop container
                      allows the following properties to be set.

                          PROP_LAYOUTSTYLE  --  Sets the direction that objects managed by
                                                the container should be laid out.

                      These properties are discussed below in greater detail.

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

                          PROP_LAYOUTSTYLE  --  Gets the direction that objects managed by
                                                the container should be laid out.

                      These properties are discussed below in greater detail.


Properties:
Property           Description
--------           ------------------------------------------------------------
PROP_LAYOUTSTYLE:  This property contains one of two constants that specify the layout direction
                   for objects managed by the prop container.  When objects are to be laid out
                   from top to bottom, the property will be stored as LAYOUT_VERT.  Containers
                   that lay out their objects from left to right specify LAYOUT_HORZ as the
                   property value.  The default value of this property is LAYOUT_VERT.

                       Property Value:  int

Required Model: None
Model Data: None
Usage

See IContainer usage.
Comment
None
  • Follow