Brew MP 1.0.2
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.
[in] A pointer to an IRootForm object.
[in] Pointer to the form to be inserted into the form stack.
[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.
- The theme used by the root form will automatically be applied to the form being inserted into