Developer

API Reference

IPropContainer_SetProp()

Brew Release
Brew MP 1.0.2
See Also
- IPropContainer Interface
- IWidget Interface
- WidgetProp
- IPropContainer_GetProp()
Description
This function will change the proportional or visible attributes of a given widget, and will optionally relocate that widget to a different location in the prop container's widget stack. The new proportion and visibility attributes are passed to the function in a WidgetProp structure, pointed to by the 'pProp' parameter. The widget to receive the new attributes may be specified explicitly by its widget pointer, or implicitly by a constant that identifies the widget's relative position within the container's widget stack. The 'pb' parameter controls whether or not the widget's location in the stack will move. Passing the constant WIDGET_ZNORMAL leaves the widget where it currently stands, without altering the order of the stack. Passing WIDGET_ZTOPMOST or WIDGET_ZBOTTOMMOST will move the widget to the top or bottom of the stack, while passing an explicit widget pointer will move the target widget to the stack location before the widget passed in 'pb'.
Parameters
  • p
    []:
    A pointer to an IPropContainer object.
  • pw
    []:
    Identifies the widget in the prop container's widget stack that will be the target of the proportion change and (optionally) relocation. This widget may be expressed explicitly as a widget pointer, or implicitly as a constant that identifies a relative position within the widget stack, as follows. WIDGET_ZNORMAL - The target widget is the default widget, which BREW interprets to be the widget at the top of the widget stack. WIDGET_ZTOPMOST - The target widget is the widget at the top of the widget stack. WIDGET_ZBOTTOMMOST - The target widget is the widget at the bottom of the widget stack.
  • pb
    []:
    Identifies a widget in the prop container's widget stack that will serve as the relocation spot for the target widget. When this parameter is passed as an explicit pointer to a widget in the container's widget stack, the target widget will be moved to the stack location that is _before_ this widget. The new location for the target widget may be passed implicitly as a relative location in the stack by passing any of the following constants. WIDGET_ZNORMAL - Specifies that the target widget should NOT be moved and should instead remain at its current location in the widget stack. WIDGET_ZTOPMOST - The target widget should be moved to the top of the widget stack. WIDGET_ZBOTTOMMOST - The target widget should be moved to the bottom of the widget stack.
  • pProp
    []:
    Pointer to a WidgetProp data structure, containing the new proportional value for the target widget, as well as its visibility attribute.

Prototype
   int IPropContainer_SetProp(IPropContainer *p, IWidget *pw, IWidget *pb, const WidgetProp *pProp);
Return
   
   AEE_SUCCESS   --  The proportional attributes of the widget were successfully changed.
   AEE_EBADPARM  --  The widget pointers passed in 'pw' and/or 'pb' either do not exist, or
                 refer to widgets that are not in the prop container's widget stack.

Side Effect
Calling IPropContainer_SetProp() will cause the prop container to adjust the object layout to accommodate the changed proportions or ordering of the objects in the container's widget stack.
Comment
If IPropContainer_SetProp() is being called to change the location of the widget within the prop container's widget stack without changing the proportional attributes of the widget, the caller MUST still pass in a pointer to the correct proportional attributes in the 'pProp' parameter. In such cases, the application should first call IPropContainer_GetProp() to retrieve the current proportional attributes, then call IPropContainer_SetProp() passing back the results received from IPropContainer_GetProp().
  • Follow