To illustrate, consider the following hierarchy of objects in which a display will contain a checkbox, a text entry field and three radio buttons.
+ Object #1 (checkbox widget) + Object #2 (container) | | |---+ Object #3 (text widget) |---+ Object #4 (container) | | |---+ Object #5 (radio button widget) |---+ Object #6 (radio button widget) |---+ Object #7 (radio button widget)
The checkbox is at the top level of the object hierarchy along with a container that acts as the parent to a pair of additional objects, a text widget as well as a second container, object 4. Object 4 is in turn the parent of a group of three radio button widgets. Events sent to object 2 could be dispatched to each of the child objects 3 and 4, and -- since object 4 is another container -- to the three radio button widgets at the bottom of the hierarchy.
In the above example, IWidget_GetParent() on objects 5, 6 and 7 would return a pointer to object 4. Called for objects 3 or 4, IWidget_GetParent() would return object 2. Both object 1 and object 2, being at the top of the hierarchy and without any container serving as a parent, would yield NULL when passed into IWidget_GetParent().
void IWidget_GetParent(IWidget *pif, IContainer **ppwc);
- A pointer to the widget's parent container is returned in 'ppwc', or NULL if the
widget does not have a parent container.