wpCnrInsertObject
This instance method inserts a record into a container control window.
Syntax
_wpCnrInsertObject(somSelf, hwndCnr, pptlIcon, preccParent, pRecInsert)
Parameters
- somSelf (WPObject *) - input
- Pointer to the object on which the method is being invoked.
- Points to an object of class WPObject.
- hwndCnr (HWND) - input
- Handle of container control window.
- NULLHANDLE: A pop-up request is made on the 'whitespace' of an open view.
- other: The handle of the container requesting the pop-up menu.
- pptlIcon (PPOINTL) - input
- Initial icon position in the container control window.
- preccParent (PMINIRECORDCORE) - input
- Pointer to the parent record.
- preccParent specifies the record of the immediate parent of the record being inserted. This parameter should be set to NULL if the record has no parent or if tree view is not supported.
- pRecInsert (PRECORDINSERT) - input
- Record position.
- This parameter specifies how this record is to be inserted relative to other records in the same container.
- NULL: Insert a record into the next available position.
- Other: Insert a record into the position specified by pRecInsert.
Returns
- pRecord (PMINIRECORDCORE) - returns
- Pointer to the inserted record.
- A return value of NULL indicates that an error occurred.
Remarks
This method inserts an object into a container control window (WC_CONTAINER). These container windows can be created by an application or by the system (such as those in folders and Settings notebooks). Objects inserted using this method automatically inherit the default Workplace Shell behavior, such as context menus, and drag and drop capabilities. When an object is inserted into a container, the Workplace Shell adds a USAGE_RECORD item to the object's in-use list. There will be one USAGE_RECORD item for each view (container control window) that the object is inserted into. See wpAddToObjUseList for more information on an object's in-use list. This method sends the CM_INSERTRECORD message to the container control window. wpCnrRemoveObject should be called to remove each record before the container window is destroyed. The OBJECT_FROM_PREC (prec) macro can be used to obtain a pointer to the object (WPObject *) associated with a given MINIRECORDCORE structure that was inserted using wpCnrInsertObject. The USER_FROM_PREC(prec) macro can be used to access the application-definable 32-bit field within the MINIRECORDCORE structure created when an object is put into a list control using wpCnrInsertObject.
Usage
This method is used to give Workplace Shell object behavior (such as context menu support) to records inserted directly into a WC_CONTAINER container control window. To remove the record from the container, a call should be made to wpCnrRemoveObject.
How to Override
This method is generally not overridden.
Example Code
#define INCL_WINWORKPLACE
#include <os2.h>
WPObject *somSelf; /* Pointer to the object on which the method is being invoked. */
HWND hwndCnr; /* Handle of container control window. */
PPOINTL pptlIcon; /* Initial icon position in the container control window. */
PMINIRECORDCORE preccParent; /* Pointer to the parent record. */
PRECORDINSERT pRecInsert; /* Record position. */
PMINIRECORDCORE pRecord; /* Pointer to the inserted record. */
pRecord = _wpCnrInsertObject(somSelf, hwndCnr,
pptlIcon, preccParent, pRecInsert);