Developer

API Reference

AEECLSID_PropContainer

Brew Release
Brew MP 1.0.2
See Also
IPropContainer interface IContainer interface
Description
Each class and interface within the widget framework is identified by a unique ID. These IDs are used throughout the framework to distinguish between various types of objects, such as containers and widgets. The prop container supports both an interface and the creation of class object instances. The prop container interface or a new instance of the prop container class object may be created by calling ISHELL_CreateInstance() and passing in the desired class id of the object. The object that is created is, itself, a container and may utilize those APIs defined for either the container or prop container interfaces.
The prop container recognizes the following set of class and interface IDs.
Instantiaion
A new instance of a Prop Container class may be created by calling ISHELL_CreateInstance() and passing in AEECLSID_PropContainer.
Cleanup
The Prop Container object is reference counted. When you are done with a reference, release it. When the reference count reaches 0, any prop container specific cleanup will be performed.
Default Interface Name
Other Interfaces
Definition
Identifier               Definition
----------               -----------------------------------
AEECLSID_PropContainer:  Identifies the class ID of the prop container
AEEIID_IPropContainer:   Identifies the interface ID of the prop container

   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 this:
   
                                         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 to 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.
  • Follow