IROOTFORM_GETFORM()
Brew Release
Brew MP 1.0.2
Description
This function provides facilities that allow an application to retrieve forms
stored in the root form's form stack. The function may be instructed to
return the form at the beginning of the form stack, or from some position
relative to another form in the form stack -- for example, returning the form
that appears before or after another form in the stack. An application can
easily iterate over all of the forms in the form stack by repeatedly calling
IRootForm_GetForm() and passing in the form pointer returned from the
previous call.
Params
pif
[]:
[in] A pointer to an IRootForm object.
pr
[]:
[in] Pointer to a form in the form stack that will be a reference point for the form
to be retrieved. For example, if 'pr' points to the second form on the stack and
the application is requesting the "next" form on the stack, the function will
return a pointer to the third form.
When 'pr' is NULL, the function will return either the first form on the stack
(i.e., the bottom form) or the last form on the stack (i.e., the top form), depending
on the value of 'n'. When 'pr' is NULL and 'n' is TRUE, IRootForm_GetForm() will
return the first form. When 'pr' is NULL and 'n' is FALSE, IRootForm_GetForm()
will return the last form.
n
[]:
[in] Specifies whether the function should retrieve the next form on the stack, or the
previous form on the stack -- always relative to the form pointer passed in 'pr'.
When 'n' is TRUE the function will retrieve the next form on the stack (i.e., the
form closer to the top of the stack). When 'n' is FALSE the function will retrieve
the previous form on the stack (i.e. the form closer to the bottom of the stack).
w
[]:
[in] Specifies whether or not the function should wrap when attempting to retrieve the
next form from the top of the stack, or the previous form from the bottom of the
stack. When 'w' is TRUE, the function will wrap at either end of the stack,
otherwise the function will return NULL indicating that there are no more forms to
be retrieved.
Interface
Prototype
IForm *IRootForm_GetForm(IRootForm *pif, IForm *pr, boolean n, boolean w);
Return
- A pointer to a form in the form stack, or NULL when there is no form to be
returned.
Side Effect
- None
Comments
Though IRootForm_GetForm() function returns a pointer to a form, the function
does not add a reference to the returned IForm for the caller.
An application may iterate over the entire form stack -- from bottom to
top -- with the following code.
IForm *pForm = NULL;
while (pForm = IRootForm_GetForm (pRootForm, pForm, TRUE, FALSE)) {
//
// Do fancy stuff with the form pointer returned in pForm
//
}
// Drops out of the loop once IRootForm_GetForm() returns NULL
COMMENTS (0)
See Below