ExtractPenDataStrokes

2.0

Creates a new HPENDATA object that is a subset of an existing object.

int ExtractPenDataStrokes( HPENDATA hpndt, UINT fuExtract, LPARAM lParam, LPHPENDATA lphpndtNew, UINT gmemFlags )

Parameters
hpndt

Handle to an existing pen data object.

fuExtract

Extraction options and modifiers. This value can be a combination of one of the principal EPDS_ options, with an optional comparison modifier, if appropriate, and the optional EPDS_REMOVE modifier. The flags should be combined using the bitwise-OR operator.

The following table gives the principal options. These options specify what the new pen data object will be based on.

Constant	Description
EPDS_INKSET	Based on a handle to an inkset. The EPDS_GT, EPDS_GTE, EPDS_LT, and EPDS_LTE comparison operators are ignored, because extraction is based on matching the inkset. (However, EPDS_NOT creates a pen data set with all stroke/inkset intersections that do not match the provided inkset.)
EPDS_PENTIP	Based on complete pen-tip characteristics.
EPDS_SELECT	Based on selected strokes.
EPDS_STROKEINDEX	Based on index.
EPDS_TIPCOLOR	Based on pen-tip color.
EPDS_TIPWIDTH	Based on pen-tip width.
EPDS_TIPNIB	Based on pen tip nib style.
EPDS_USER	Based on user-specific value. The following table gives the optional comparison modifiers and the optional removal modifier:
EPDS_LT	Less than comparison: extract all strokes with attribute less than the value specified in lParam.
EPDS_LTE	Less than or equal comparison: extract all strokes with attributes less than or equal to the value specified in lParam.
EPDS_GT	Greater than comparison: extract all strokes with attributes greater than the value specified in lParam.
EPDS_GTE	Greater than or equal comparison: extract all strokes with attributes greater than or equal to the value specified in lParam.
Constant	Description
EPDS_NOT	Negative comparison (alias EPDS_NE): extract all strokes with attributes not equal to the value specified by lParam. If combined with other EPDS_ constants, reverses the constant meaning (for example, EPDS_NE \| EPDS_LT \| EPDS_GT means not less than or not greater than). If lParam is EPDS_SELECT, EPDS_NOT means extract all unselected strokes.
EPDS_REMOVE	Remove matching strokes from source. If this flag is added, any strokes matching the criteria for extraction are removed from the source pen data.

lParam

Meaning is dependent on the value of the fuExtract parameter, as follows:

Constant	Description
EPDS_INKSET	lParam is a handle to an inkset.
EPDS_PENTIP	lParam is a pointer to a PENTIP structure to compare. Only equal or not-equal matches are supported. EPDS_LT, for example, is ignored.
EPDS_SELECT	lParam is not used and should be set to 0.
EPDS_STROKEINDEX	lParam is a zero-based stroke index to compare.
EPDS_TIPCOLOR	lParam is a pen tip color to compare.
EPDS_TIPNIB	lParam is a pen tip nib style to compare. Only equal or not-equal matches are supported.
EPDS_TIPWIDTH	lParam is a pen tip width to compare.
EPDS_USER	lParam is a user-specific value to compare, cast to a double-word value.

lphpndtNew

Address of a pen data handle if one is to be created; otherwise, NULL.

gmemFlags

Flag that specifies whether or not the Windows GlobalAlloc function should create a shared memory object when the pen data object is created. This should be either 0 or GMEM_DDESHARE. The GMEM_MOVEABLE and GMEM_ZEROINIT flags are added to this value, and other GMEM_ flags are ignored.

Return Value
Returns the number of strokes that match the comparison criteria if successful, or a negative error value. (The return value can be 0. The maximum is the largest integer value.) The error value can be one of the following:

Constant	Description
PDR_COMPRESSED	Pen data is compressed.
PDR_ERROR	Parameter or other unspecified error.
PDR_INKSETERR	Invalid inkset and EPDS_INKSET specified.
PDR_MEMERR	Memory error.
PDR_NA	Option not available.
PDR_PNDTERR	Invalid pendata.
PDR_STRKINDEXERR	Invalid stroke index.
PDR_USERDATAERR	EPDS_USER was specified but there is no per-stroke user data.
PDR_VERSIONERR	Could not convert old pendata.

Comments
ExtractPenDataStrokes extracts strokes from an existing pen data object, optionally creating a new pen data object made up of the extracted strokes. The extraction can be a copy or move process; that is, the source pen data object can remain the same or contain only the remaining strokes not moved to the new structure. Modifier flags in fuExtract specify how the value in lParam compares with attributes of the pen data strokes (equal by default, greater than, less than, or none of these three).

If lphpndtNew is NULL, no pen data object is created. This is useful for modifying the original pen data object hpndt (when EPDS_REMOVE specified), or simply for determining a return value without modifying or creating a pen data object. If lphpndtNew is not NULL, the flags specified by gmemFlags are passed to the GlobalAlloc function when memory for the pen data memory block is created.

If EPDS_REMOVE is specified, any strokes with an attribute matching the comparison criteria are removed from the source pen data object, regardless of whether a new pen data is created. In the case of inksets, this may actually generate more strokes if there are multiple intersections with the inkset within any one stroke.

Example
To create an HPENDATA object consisting only of selected strokes:

ExtractPenDataStrokes( hpndt, EPDS_SELECT, 0, &hpndtDst, 0 );

To return the count of selected strokes:

ExtractPenDataStrokes( hpndt, EPDS_SELECT, 0, NULL, 0 );

To delete all but the selected strokes from the source:

ExtractPenDataStrokes( hpndt, EPDS_NOT | EPDS_SELECT | EPDS_REMOVE,

0, NULL, 0 );

To copy strokes 0 through 10 inclusive to a new HPENDATA object:

ExtractPenDataStrokes( hpndt, EPDS_LTE | EPDS_STROKE, 10,

&hpndtDst, 0 );

To move all but blue strokes to a separate HPENDATA object:

ExtractPenDataStrokes( hpndt, EPDS_NOT | EPDS_TIPCOLOR | EPDS_REMOVE,

RGB_BLUE, &hpndtDst, 0 );