wpAddToObjUseList
This instance method is called to add an item type to an object's in-use list.
Syntax
_wpAddToObjUseList(somSelf, pUseItem)
Parameters
- somSelf (WPObject *) - input
- Pointer to the object on which the method is being invoked.
- Points to an object of class WPObject.
- pUseItem (PUSEITEM) - input
- Pointer to a USEITEM structure.
Returns
- rc (BOOL) - returns
- Success indicator.
- TRUE: Successful completion.
- FALSE: Error occurred.
Remarks
This method will add a specified item type to an object's in-use (USEITEM) list. Every workplace object in the system has an in-use list. The in-use list is a linked list of USEITEM structures which provides the object with important information such as the number of container (WC_CONTAINER) windows it has been inserted into. It also provides the number of open views (contents, help, and settings) of itself that already exist and how much memory it has allocated. The USEITEM structure consists of an item type and a pointer to the next USEITEM structure and is followed immediately by an item type-specific structure.
Usage
The following types of items can be added to the use list:
- USAGE_MEMORY This item specifies a block of memory allocated for this object through the use of the wpAllocMem method. Items of this type add a MEMORYITEM structure to the end of the USEITEM structure.
- USAGE_OPENVIEW When a view of an object is opened, one of these items is added to the in-use list. If multiple, concurrent views are not enabled for this object, the USAGE_OPENVIEW items are used by the system to automatically switch to the open view when the user chooses to open the same view again. This behavior is controlled by the application by calling the wpOpen or the wpSwitchTo method. This item is also used by the system to update the title bar text and switch-entry text when the user changes the object title. If this type is specified, the in-use emphasis bit is turned on for all inserted records for this object. Items of this type concatenate a VIEWITEM structure to the end of the USEITEM structure.
- USAGE_RECORD For every view (WC_CONTAINER) window that the object is inserted into, there is one of these items on its in-use list. This enables an object to refresh its appearance in all views at the same time. Items of this type add a RECORDITEM structure to the end of the USEITEM structure.
Example Code
#define INCL_WINWORKPLACE #include <os2.h> WPObject *somSelf; /* Pointer to the object on which the method is being invoked. */ PUSEITEM pUseItem; /* Pointer to a USEITEM structure. */ BOOL rc; /* Success indicator. */ rc = _wpAddToObjUseList(somSelf, pUseItem);