CM FILTER

This message filters the contents of a container so that a subset of the container items is viewable.

Syntax

param1
PFN pfnFilter;   /* Pointer to an application-supplied filter function. */

param2
PVOID pStorage;  /* Application use. */

Parameters

pfnFilter (PFN) - Input

Pointer to an application-supplied filter function.

pStorage (PVOID) - Input

Available for application use.

Returns

rc (BOOL) - returns

Success indicator.

TRUE: A subset was successfully created.

FALSE: An error occurred. The WinGetLastError function may return the following errors:

PMERR_NO_FILTERED_ITEMS

PMERR_INSUFFICIENT_MEMORY.

Remarks

Filtering is enabled by setting the CRA_FILTERED attribute of container records that are to be excluded from the viewable subset.

The pfnFilter parameter points to an application-provided function that determines whether a record is to be included in the viewable subset. The pfnFilter parameter must be declared as:

BOOL PFN pfnFilter (
                    PRECORDCORE p,
                    PVOID pStorage);

where p points to a RECORDCORE structure that describes the container record to be tested. The pfnFilter parameter returns TRUE if the record is to be included in the viewable subset, or FALSE if it is to be excluded. The container sets the CRA_FILTERED attribute for the record based on the return from the pfnFilter parameter.

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.

If the CRA_FILTERED attribute is set for the record, the record is not visible. If the CCS_AUTOPOSITION style bit is set and the container is showing the icon view, the container records are arranged when a record is filtered out.

The CM_FILTER message supports only one level of filtering.

It is the application's responsibility to provide a National Language Support-enabled (NLS-enabled) function for the pfnFilter parameter.

If the pfnFilter parameter value is NULL, a container is returned to an unfiltered state. If functions such as inserting a record into a container, arranging the records, or sorting the records are performed on a container whose records have been filtered, the effect of these functions remains if the container records are later unfiltered.

All messages act on the entire container. For example, a record that is filtered and is removed from the container will be removed from the container entirely; it is not present in the container when the container records are unfiltered.

Default Processing

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