Developer

API Reference

IContainer_Invalidate()

Brew Release
Brew MP 1.0.2
See Also
-IContainer
-IWidget
-IWidget_Invalidate()
Description
This function will invalidate all or part of a widget within a specific container. The application must specify the container and widget that will be used as the basis for the invalidation region. By default, IContainer_Invalidate() will invalidate the region of the entire widget. However, if the caller wishes to invalidate only a portion of this widget (for example, a widget that possesses many visual attributes, any of which could change independent of the others), a specific rectangle may be identified to limit the invalidation region within the widget, as illustrated below -
                          c o n t a i n e r
                +-----------------------------------+
                |                                   |
                |                                   |
                |                                   |
                |                                   |
                |            w i d g e t            |
                |  +-----------------------------+  |
                |  |                             |  |    # - Portion of the display
                |  |                             |  |        to be invalidated
                |  |    rectangle                |  |
                |  | +-------------+             |  |
                |  | |#############|             |  |
                |  | |#############|             |  |
                |  | +-------------+             |  |
                |  |                             |  |
                |  |                             |  |
                |  |                             |  |
                |  +-----------------------------+  |
                |                                   |
                +-----------------------------------+

When invalidating a widget that lays behind other objects on the display, the container will subtract fully opaque objects that overlap the target widget on the display. However, in doing so, the container will maintain the "rectangleness" of the invalidation region. To illustrate -
       +-------------------------+
       |                         |
       |                         |
       |                         |
       |                         |---------------+
       |                         |               |
       |                         |               |
       |         Widget 1        |               |
       |                         |               |
       +-------------------------+               |
                     |                           |       
                     |                           |       
                     |          Widget 2         |       
                     |                           |       
                     +---------------------------+

In the above example, when widget 2 is to be invalidated, the container will first calculate the rectangle occupied by widget 2, then subtract out the rectangle occupied by widget 1 (which we assume to be fully opaque, for the sake of our example. Geometrically, the resultant region would first appear to look like so -
                                 +---------------+
                                 |               |
                                 |               |
                                 |               |
                                 |               |
                     +-----------+               |
                     |                           |       
                     |       Theoretical         |       
                     |  Invalidation Rectangle   |       
                     |                           |       
                     +---------------------------+

However, the container defines the invalidation region to be the rectangle required to include all portions of the resultant region. Therefore, the actual invalidation rectangle in the above example would be -
                     +---------------------------+
                     |                           |       
                     |                           |       
                     |                           |       
                     |                           |       
                     |                           |       
                     |                           |       
                     |          Actual           |       
                     |  Invalidation Rectangle   |       
                     |                           |       
                     +---------------------------+

In this case, the exact same rectangle as that occupied by the widget to be invalidated.
Looking at a much different example, the effect of subtracting out overlapping opaque widgets becomes a little more obvious -
       +-------------------------+
       |                         |
       |         Widget 1        |
       |                         |
       |         - - - - - - - - |---------------+
       |        :                |               |
       |        :                |               |
       |  +-------------+        |               |
       |  |     :       |        |               |
       +--|     :       |--------+               |
          |     :       |                        |       
          |     :       |                        |       
          |     :       |       Widget 2         |       
          |     :       |                        |       
          |       - - - |------------------------+
          |             |
          |  Widget 3   |
          |             |
          +-------------+

Here, both widgets 1 and 3 overlap widget 2, whose obscured region is shown via a series of dotted lines. After subtracting out the rectangles for the overlapping objects, the theoretical invalidation rectangle for widget 2 becomes -
                                 +---------------+
                                 |               |
                                 |               |
                                 |               |
                                 |               |
                        +--------+               |
                        |                        |       
                        |      Theoretical       |       
                        | Invalidation Rectangle |       
                        |                        |       
                        +------------------------+

The actual invalidation rectangle becomes the following (which is less than the original rectangle specified for widget 2) -
                + - - - +------------------------+
                :       |                        |       
                :       |                        |       
                :       |                        |       
                :       |                        |       
                :       |                        |       
                :       |                        |       
                :       |         Actual         |       
                :       | Invalidation Rectangle |       
                :       |                        |       
                + - - - +------------------------+

Parameters
  • p
    []:
    [in] Pointer to the IContainer interface object that serves as the parent to the widget to invalidate.
  • pw
    []:
    [in] Pointer to the IWidget object to be invalidated, or a constant that implies a particular widget within the container. The constants used to identify a relative position for the widget to be invalidated, are defined as follows. WIDGET_ZTOPMOST - Requests that the widget at the top of the container's widget stack should be invalidated. WIDGET_ZBOTTOMMOST - Requests that the widget at the bottom of the container's widget stack should be invalidated. WIDGET_ZNORMAL - Requests that the widget placed at the container's most normal layout location be invalidated. The base container treats the WIDGET_ZTOPMOST position as the "normal" location.
  • prc
    []:
    [in] Pointer to the rectangle that defines the area to be invalidated. This rectangle is expressed relative to the coordinates of the specified widget. When this parameter is NULL, the interface will use the full extent of the 'pw' widget as the invalidation rectangle.
  • f
    []:
    [in] A set of flags that control the calculation of the invalidation rectangle. The defined validation flags are - ICIF_EXTENT - When this flag is ON, it is an indication that the widget has changed its extent. ICIF_REDRAW - When this flag is ON, it is an indication that the widget has changed its contents, but its preferred extent is still the same. The widget simply wants to be redrawn. ICIF_DEFER - When this flag is ON, it indicates that the widget's layout is disabled, but it is still passing an invalidate up to notify its ancestors that an invalidate occurred but no action was taken as layout was disabled. When RootContainer receives an invalidate with the ICIF_DEFER flag appended, it will not cause a draw to be scheduled.
Interface
Prototype
   void IContainer_Invalidate(IContainer *p, IWidget *pw, const AEERect *prc, uint32 f)
Return
None
Side Effect
None
Comment
Calling IContainer_Invalidate() will trigger the invalidation to travel up through the container's hierarchy, first to its parent, then to its parent, etc. so that the invalidation rectangle may be applied to each object in the chain.
Callers should set the ICIF_EXTENT flag of the 'f' parameter when calling IContainer_Invalidate() following a change to the widget's extent.
  • Follow