Developer

API Reference

IRootForm_InsertForm()

Brew Release
Brew MP 1.0.2
See Also
IRootForm IForm IRootForm_PopForm() IRootForm_PushForm() IRootForm_RemoveForm()
Description
This function allows an application to insert a form at a specific position within the root form's form stack. Most applications can sufficiently manage the layering of forms by using the more convenient IRootForm_PopForm() and IRootForm_PushForm() functions, to place and remove forms from the form stack. Applications that wish to exercise greater control over the ordering of forms on the form stack can used IRootForm_Insert() to place forms at very specific locations. For example, when displaying a popup, an application could place a new form just below the popup by calling IRootForm_InsertForm(), thereby maintaining the effect of the popup floating above the primary display content. Ordinarily, the new form would have been placed above the popup.
The root form will be updated if the inserted form is visible, either at the top of the stack or at a position that is above the topmost visible form -- again, for example, when the new form is inserted behind a popup.
Parameters
  • pif
    []:
    [in] A pointer to an IRootForm object.
  • f
    []:
    [in] Pointer to the form to be inserted into the form stack.
  • pr
    []:
    [in] Pointer to a position within the form stack where the new form will be inserted. The new form will be inserted immediately before the form pointed to by 'pr'. The insertion location may be passed as a constant that identifies a relative position within the form stack, as follows. FORM_DEFAULT - Allow BREW to place the inserted form at its default location. When inserting a form, this places the new form at the top of the form stack. FORM_LAST - The new form should be inserted at the last form on the form stack -- i.e. this places the form at the top of the form stack as the most recent form. FORM_FIRST - The new form should be inserted at the first form on the form stack -- i.e. this places the form at the bottom of the form stack as the oldest form.

Interface
Prototype
   int IRootForm_InsertForm(IRootForm *pif, IForm *f, IForm *pr);
Return
   
   AEE_SUCCESS   --  Form was successfully inserted into the form stack.
   AEE_EBADPARM  --  Form pointer passed in 'pr' either does not exist, or refers to a form
                     that is not in the root form's form stack.
   AEE_ENOMEMORY --  Form stack could not grow to accommodate a new form.

Side Effect
The theme used by the root form will automatically be applied to the form being inserted into the stack.
Comment
A form should not be inserted if it already exists in the form stack.
  • Follow