DrawPenData
1.0 2.0
Displays the
pen data in an HPENDATA object as a trail of visible ink.
void DrawPenData( HDC hdc, LPRECT lprect,
HPENDATA hpndt )
Parameters
hdc
Handle to a
device context. This parameter can also be the handle of a metafile.
lprect
Bounding
rectangle of ink, in client coordinates. Can be NULL.
hpndt
Handle to a
pen data object.
Return Value
This function
does not return a value. If hpndt is NULL, DrawPenData does
nothing.
Comments
DrawPenData draws the pen data in the specified device context
using the GDI Polyline
function. The current settings in the device context rather than the ink
characteristics determine how the data is rendered. This means the ink width
and color specified in the PENDATAHEADER structure have no effect on how DrawPenData
renders the ink. To alter the display characteristics of the ink, an
application must call the appropriate Windows GDI functions to set the GDI
drawing pen (not to be confused with the real pen).
The
application using DrawPenData must either scale the data points or set
the mapping appropriately if lprect is NULL.
If lprect
is not NULL, the points are scaled into lprect as the drawing is done.
Internally, nondestructive calls to the SetViewportExtEx, SetViewPortOrg, SetWindowOrg,
and SetWindowExtEx
functions are used to render the pen data in the device context within the
bounds of the provided rectangle. An application must compute the proper pen
width (if it is other than 1) before calling this function with a valid lprect
parameter to account for the scaling that occurs.
DrawPenData draws the ink in the rectangle relative to the
upper-left corner of the window. It ignores any changes that have been made to
the origin of the device context by previous calls to the SetWindowOrg
or SetViewportOrgEx
functions. If the origin has changed, the rectangle passed to DrawPenData
must be offset by the appropriate amount.
If the ink is
to be drawn with a width of greater than 1 pixel, the width of the currently
selected pen must be set to achieve the desired result. The width must be set
in client coordinates if a mapping mode is set in the device context. For
example, if the mapping mode has been set to MM_HIENGLISH, the pen width must
be set to a number appropriate for the desired width in MM_HIENGLISH units to
preserve the proper scale of the ink. This scaling is only an issue when the
ink width is greater than 1.
The rendering
of the ink data produced by DrawPenData generally does not exactly match
the rendering produced by the display driver when the data was first collected.
This discrepancy results because DrawPenData and the Polyline function use different
algorithms to draw the data. The difference is an occasional off by one error
that appears as a shifting of some pixels around the edges, depending on the
rounding done by Polyline. An application that requires an exact
replication of the original ink rendering should call the RedisplayPenData function.
The DrawPenDataEx function allows more
control when drawing the contents of pen structures.
See Also