API Reference


Brew Release
Brew MP 1.0.2
See Also
- IContainer
- IWidget
- IWidget_MoveFocus
The grid container is derived from the base container object and is used to manage widgets. As the name suggests, grid container lays widgets out in a grid format. Each column and row has a configurable properties which can be set to change the appearance of grid container. This is done by setting the values of the GridDescriptors.
Let's start with an example of a grid container in action. Assume you wish to create an application that lets users browse action figures from Star Wars Episode III: Revenge of the Sith. We'll use a grid container to hold images of the figures, each contained in their own Image Widget. Assume each Image Widget has both an unselected image and a selected image. We will switch to the selected image when the image widget has focus.
                             Grid Container
   | +------------------+ +------------------+ +------------------+ |
   | | Mace Windu       | | Anakin Skywalker | | Queen Amidala    | |
   | |                  | |                  | |                  | | 
   | | with lightsaber  | | with lightsaber  | | with bizarre food| | 
   | | and detachable   | | to cut Windu's   | | craving action.  | |
   | | hand plus whistle| | hand off and 200 | | She's expecting  | |
   | | to call for alien| | Stormtroopers to | | Luke and Leia    | |       
   | | Jedi help        | | do his fighting  | | Skywalker soon.  | |   
   | +------------------+ +------------------+ +------------------+ |
   |                                                                |
   | +------------------+ +------------------+ +------------------+ |
   | | Random Lame      | | Boba Fett        | | Jek Porkins      | |
   | | Alien Jedi       | |                  | |                  | | 
   | |                  | | with pubescent   | | "No, I'm alright,| | 
   | | wearing a red    | | voice, Jango     | | I'm alright...   | |
   | | shirt with a     | | Fett's empty     | | oh I'm really    | |
   | | bullseye painted | | helmet, and the  | | alright."        | |
   | | on it            | | Fett family curse| | (Flashback humor)| |
   | +------------------+ +------------------+ +------------------+ |

The grid container will lay the contained widgets out in a grid as shown above. Hopefully, the vivid descriptions above helped you picture the figures in all their splendor. To set up a grid container like the one above, we need to perform the following steps:
   1. ISHELL_CreateInstance(piMyShell, AEECLSID_GridContainer, &picMyGridContainer)
   2. IGridContainer_QueryInterface(picMyGridContainer, AEEIID_IWidget, &piwMyGridContainer)
   3. Using the widget interface to grid container, set the extent to the desired
      size you want the container to be.  
   4. Insert the grid container into the root container (so it draws to the screen)
      using IRootContainer_Insert(picMyRoot, piwMyGridContainer, WIDGET_ZNORMAL, &myWidgetPos)
   5. Insert six Image Widgets containing the images of our Star Wars figures
   6. Create an array of GridDescriptors that describe the properties of each row and column.
      We would then create an array of GridDescriptors (one for each row, so 3 in this case).
      Each GridDescriptor would be set to the following values -
         myGridDescriptor.iFlag = CELL_SIZE_TO_FIT;
         myGridDescriptor.iValue = 0;  //ignored for this flag (see Cell types)
         myGridDescriptor.iPaddingBefore = 2;
         myGridDescriptor.iPaddingAfter = 2;
      We are building a pretty simple grid container, so each row descriptor will be
      the same.  
   7. Call IGridContainer_SetGridDescriptors(picMyGridContainer, pDesc, &iSize, pDesc, &iSize)
      where pDesc is our array of length iSize containing initialized GridDescriptors to
      describe each row and column.  We are reusing the same pDesc array and iSize value
      because we want our rows and columns to be identical in size and behavior. 

Grid container knows which widget inside the container has focus. By default the upper leftmost widget has focus. To explicitly set focus to a different widget, say for example the last widget, call:
   IWidget_MoveFocus(me->piwMyGridContainer, (IWidget*)WIDGET_FOCUS_LAST);

In order to support advanced focus changing behavior, override grid container's event handler using IWIDGET_SetHandler.
Supported Events: The grid container processes events in two passes. The grid 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 grid container itself.
The grid container will accept the following events:
Event                 Description
-----                 ------------------------------------------------------------
EVT_WDG_GETPROPERTY:  The grid container responds to this event by attempting to retrieve the
                      property identified by the 'wParam' parameter.  The grid container allows
                      the following properties to be retrieved, returning the value of the
                      property in the pointer pointed to by 'dwParam' -

                          PROP_ROWS        --  Gets the number of rows

                          PROP_COLS        --  Gets the number of columns

                      These properties are discussed below in greater detail.


Property           Description
--------           ------------------------------------------------------------

PROP_ROWS:          This is a "get only" property and will return the number of rows in 
                    the grid container.  In order to set the number of rows, see
                      Property Value: uint32

PROP_COLS:          This is a "get only" property and will return the number of columns in 
                    the grid container.  In order to set the number of columns, see
                      Property Value: uint32  

Required Model: None
Model Data: None
See IContainer usage. Inaddition to IContainer methods, IGridContainer provides methods to get/set grid descriptors through IGridContainer_GetGridDescriptors() and IGridContainer_SetGridDescriptors(), set/get visibility of the container through IGridContainer_SetVisibility() and IGridContainer_GetVisibility().
  • Follow