Developer

API Reference

AllUIWidgetsIRootForm_GetForm()

IRootForm_GetForm()

COMMENTS (0)

See Below
Brew Release
Brew MP 1.0.2
See Also
IRootForm IForm
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.
Parameters
  • 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
IRootForm
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
Comment
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

  • Follow