Developer

API Reference

IWidget_RemoveFlags()

Brew Release
Brew MP 1.0.2
See Also
Error Codes IWidget IWidget_SetFlags IWidget_GetFlags IWidget_AddFlags Widget Events
Description
This helper function allows the application to disable specific flags in a widget without disabling any of the flags already set. Unlike IWidget_SetFlags(pif, 0), this routine switches only the specified flags off while leaving all others enabled.
The application should pass the set of flags to be disabled as a logically OR'ed set in the 'dwFlagsToRemove' parameter. This will cause the flags to be switched off internally, leaving the other flags untouched in their prior state.
This helper function retrieves the set of flags that are enabled in the current widget using IWidget_GetFlags(), strips out the set of flags to be disabled, then uses IWidget_SetFlags() to turn them off while leaving the others switched on. If the widget doesn't support the PROP_FLAGS parameter, an error code will be returned. To determine if a specific type of widget supports PROP_FLAGS and what flags can be set, refer to that widget's documentation.
For example, the Text Widget defines and understands the TWF_MULTILINE, TWF_VERTICALNAV and TWF_PASSWORD flags. Each of these causes a text widget to behave differently. To tell a multiline text widget to no longer allow vertical navigation, an application may call
   IWidget_RemoveFlags(pTextWidget, TWF_VERTICALNAV);

This is equivalent to the following, which disables vertical navigation but retains the multiline behavior:
   IWidget_GetFlags(pTextWidget, &dwCurFlags);
   dwCurFlags &= ~TWF_VERTICALNAV;
   IWidget_SetFlags(pTextWidget, dwCurFlags);
Parameters
  • pif
    []:
    [in] Pointer to the IWidget interface object.
  • dwFlagsToRemove
    []:
    [in] Set of logically ORed flags to turn off in the widget.
Interface
Prototype
   int IWidget_RemoveFlags(IWidget *pif, uint32 dwFlagsToRemove);
Return
AEE_SUCCESS : The widget was able to handle the event, and only the specified flags were disabled. AEE_EFAILED : The widget was unable to handle the event, and the widget's flags remain unchanged
Side Effect
Depending on the widget implementation and what flags were unset, the widget's behavior will change. Refer to the widget's documentation to see what specific flags it supports and what effect they have.
Comment
IWidget_SetFlags(pif, 0) may be used to turn off all flags in a widget. Use this routine to quickly disable specific flags rather than all of them. IWidget_RemoveFlags(pif, dwFlags) is equivalent to:
   IWidget_GetFlags(pif, &dwCurFlags);
   dwCurFlags &= ~dwFlags;
   IWidget_SetFlags(pif, dwCurFlags);
Use IWidget_AddFlags() to switch on specific flags.
  • Follow