CreatePenDataEx 

2.0     

Creates a PENDATA structure with specified OEM data subsets.

HPENDATA CreatePenDataEx( LPPENINFO lppeninfo, UINT uScale, UINT fuOptions, UINT gmemFlags )

Parameters

lppeninfo

Address of tablet information to be inserted into the PENINFO3BE5AL5 structure in the pen data header. If this parameter is NULL, the current tablet settings are retrieved from the hardware instead. If there is no tablet, the pendata will not have an embedded PENINFO section and the wPndts member in PENDATAHEADER1AOCX0 will have the PDTS_NOPENINFO flag set.

uScale

Data-scaling metric value. This parameter can be one of the following values:

fuOptions

Storage and trim options. If this parameter is 0, no timing, PDK_, or OEM data is stored. If it is CPD_DEFAULT, everything but user data is stored.

Otherwise, this parameter can explicitly specify subsets of OEM and other data. To do so, the parameter should be a combination of one of the CPD_USER values that allocate extra storage and any collection of PHW_ constants. (These values should be combined using the bitwise-OR operator.)

The following table lists the PHW_ values for the fuOptions parameter:

gmemFlags

Flag that specifies whether GlobalAllocF12W9. should create a shared memory object or not 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 handle to the HPENDATA object if successful; otherwise, returns NULL.

Comments

CreatePenDataEx is an extension of CreatePenData1AOBT. that allows a more detailed specification of what is stored in each stroke of the pen data.

The fuOptions parameter is typically specified as CPD_DEFAULT to request collection and storage of all information generated by the tablet, including x-y data, absolute stroke timing information, and all available OEM data. The OEM data set that is actually stored in the pen data is the minimum set that satisfies both the request and what is physically available from the tablet (that is, intersection set).

If lppeninfo is NULL, and if there is no tablet on the system (that is, if the SendDriverMessage function fails), the pen data that is created will not have any hardware or OEM information and a default sampling rate of 100Hz will be used. This case is similar to removing PENINFO3BE5AL5 from the header using TrimPenData232HBFD with a parameter of TPD_PENINFO.

A value of 0 for fuOptions is used to indicate that only coordinate data is required. While recognition of this type of pen data may suffer, this provides the least complicated type of pen data.

PHW_ bits can be specified to indicate which OEM values or per-point PDK_ pen state information is to be collected. Note that, except for PHW_PDK, which is always valid, this is only a request; if the hardware does not support certain types of OEM data, that data will be absent.

The uScale parameter specifies scaling values that are also used in the MetricScalePenData9GBK.JC function and in the PENDATAHEADER1AOCX0 structure member wPndts. The scaling values do not behave in the same way as the Windows scaling units with similar names. For example, a 1-inch line in MM_HIENGLISH will not necessarily be an inch long on the screen, because GDI does not know the size of the monitor. However, with PDTS_HIENGLISH in MetricScalePenData, a line drawn an inch long is actually an inch long.

See Also