CM INSERTRECORD

This message inserts one or more RECORDCORE structures into a container control.

Note

; If the CCS_MINIRECORDCORE style bit is specified when a container is created, then MINIRECORDCORE should be used instead of RECORDCORE, and PMINIRECORDCORE should be used instead of PRECORDCORE in all applicable data structures and messages.

Syntax

param1
PRECORDCORE pRecord;      /* Pointer to the RECORDCORE structure or structures to insert.  */

param2
PRECORDINSERT pRecordInsert; /* Pointer to the RECORDINSERT data structure. */

Parameters

pRecord (PRECORDCORE) - Input

Pointer to the RECORDCORE structure or structures to insert.

If you set the pRecord field to a specific PRECORDCORE (rather than to CMA_FIRST or CMA_END), you must set the parent to NULL. If you do not do this and are inserting at the top level in tree view, the application will trap in PMCTLS.DLL.

pRecordInsert (PRECORDINSERT) - Input

Pointer to the RECORDINSERT data structure.

Returns

cRecords (ULONG) - returns

Number of structures.

0: The RECORDCORE structure was not inserted. The WinGetLastError function may return the following errors:

PMERR_INVALID_PARAMETERS

PMERR_INSUFFICIENT_MEMORY

PMERR_RECORD_CURRENTLY_INSERTED

Other: The number of RECORDCORE structures in the container.

Remarks

The pRecordInsert parameter is used to insert RECORDCORE structures into the container. The pRecordOrder and pRecordParent fields of the RECORDINSERT data structure are used to place each record into the container in order, relative to the other records. If the CMA_FIRST or CMA_END attributes are specified, records are inserted before the first child or after the last child of the record specified in the pRecordParent field. If the value of the pRecordParent field is NULL, the record or records are inserted before the first record or after the last record, respectively, at the root level. Otherwise, if the value of the pRecordOrder field is a pointer to a record, the record or records to be inserted are placed after this record.

A z-ordering of the records is maintained by the container control. The zOrder field of the RECORDINSERT data structure is used to specify the record's z-order in the container, relative to the other records. The CMA_TOP attribute is used to place the record at the end of the z-order list, while the CMA_BOTTOM attribute places the record at the beginning of the z-order list. Z-ordering is used for the icon view only.

If the value of the cRecordsInsert field of the RECORDINSERT data structure is greater than 1, a linked list of RECORDCORE structures is inserted in the order specified by the pRecordOrder, pRecordParent, and zOrder fields. Here, the pRecord parameter points to the first RECORDCORE structure of a linked list of structures.

If one RECORDCORE structure is to be inserted, the cRecordsInsert field has a value of 1 and the pRecord parameter points to the RECORDCORE structure to be inserted.

When containers display the icon view, the coordinates specified by the RECORDCORE structure's ptlIcon field are used to position inserted container records in the container's workspace. If the coordinates are not specified and the CCS_AUTOPOSITION style bit is not set, all of the inserted container records are positioned at (0,0) and a CM_ARRANGE message must be sent to position them elsewhere. If the CCS_AUTOPOSITION style bit is set, the container records are positioned without the CM_ARRANGE message being sent.

After the container records have been inserted:

• If the fInvalidateRecord field of the RECORDINSERT data structure is FALSE, the CM_INVALIDATERECORD message must be sent to update the display with the inserted records. If the current view is the icon view and either the CCS_AUTOPOSITION style bit is set or the fInvalidateRecord field is TRUE, the view is updated without the CM_INVALIDATERECORD message being sent.
• The preccNextRecord, flRecordAttr, and ptlIcon fields of the external RECORDCORE structure are not updated as changes occur within the container. However, if records are shared among multiple containers, the flRecordAttr and ptlIcon fields are modified internally. See the PM Programming Guide for more information about the modification of these fields.

If the CCS_VERIFYPOINTERS style bit is set and the pRecord parameter contains a pointer to a RECORDCORE structure that is currently inserted, the PMERR_RECORD_CURRENTLY_INSERTED error is set and no RECORDCORE structures are inserted.

If the RECORDCORE structures are sorted on insertion, the pRecordOrder and zOrder fields are ignored.

Default Processing

The default window procedure does not expect to receive this message and therefore takes no action on it other than to return 0.