RedisplayPenData
1.0 2.0
Redraws the
pen data in the same manner as originally inked.
BOOL RedisplayPenData( HDC hdc, HPENDATA
hpndt, LPPOINT lpDelta, LPPOINT lpExt,
int nInkWidth, DWORD rgbColor )
Parameters
hdc
Handle to a
device context. The mapping mode should be MM_TEXT.
hpndt
Handle to a
pen data object. The pen data must be scaled to PDTS_DISPLAY or
PDTS_STANDARDSCALE.
lpDelta
An offset, in
logical units, that is subtracted from the pen data points to position the ink.
If lpDelta is NULL, there is no offset.
lpExt
Extent, in
logical units, for scaling. If lpExt is NULL, no scaling is performed.
nInkWidth
Width of the
ink to be drawn, in pixels (1 to 15). If nInkWidth is -1, the strokes are rendered using the original ink
width stored in the stroke header. An ink width of 0 causes the function to
simply return TRUE.
rgbColor
RGB value of
the color to draw the ink. If rgbColor is 0xFFFFFFFF, the strokes are
rendered using the original ink color stored in the stroke header.
Return Value
Returns TRUE
if successful; otherwise FALSE.
Comments
The nInkWidth
and rgbColor values override the pen currently selected for the hdc
device context.
If the
mapping mode of the hdc device context is not MM_TEXT, two problems can
occur:
RedisplayPenData uses TPtoDP to prepare the pen data
points for rendering. After this, the points are in MM_TEXT coordinates; this
assumes an MM_TEXT device context for display. If the device context is in a
different mapping mode, the ink coordinates will not be correct. Even if you
use the ink-scaling functions to bypass this problem, you will still encounter
rounding-error problems between the two scalings.
No matter what scaling is done,
rounding errors occur when converting between modes. These errors cause the ink
to shift slightly when repainted.
For any
rendering into a device context that represents anything other than a display
device context, DrawPenDataEx
should be used. This is because RedisplayPenData makes assumptions that
are not optimal for other devices such as printers or metafiles.
RedisplayPenData provides the ability to re-create original inking
perfectly. To do this, an application can use either of two methods:
After the input session ends
and data is collected into an HPENDATA object, store the current origin
of the window containing the ink. When calling RedisplayPenData to
redraw the ink, supply the origin value in the lpDelta argument, set lpExt
to NULL, and set the mapping mode of the device context to MM_TEXT. Only ink
data with a common window origin can be merged into a single HPENDATA.
In the second method, the
application must call two Pen functions immediately after collecting the data
into an HPENDATA object. The first call to MetricScalePenData converts the pen data to
display coordinates. The second call to OffsetPenData sets the display
coordinates relative to the window containing the original ink. To display, the
application must call RedisplayPenData with lpDelta and lpExt
set to NULL and the mapping mode of the device context set to MM_TEXT. If the
application adopts this method for multiple HPENDATA objects, it can
later merge them to form a single HPENDATA object (up to the 64K limit).
The second
method has the advantages of simplicity and data compression. See the
description of MetricScalePenData for a discussion of the limitations of
converting data to display resolution.
Since the pen
data has the origin of (0,0) based on the upper-left corner of the display,
applications must move from a screen-relative position to a position relative
to the device context. To do this, subtract the origin of the device context
(in screen coordinates) from the object currently residing in screen-coordinate
space.
The lpDelta
parameter enables the application to render ink relative to the window instead
of relative to the screen. An application should call the ClientToScreen function for (0,0) to find
the proper screen coordinates to be placed in the *lpDelta POINT structure. Once this is
done, the pen data is rendered at the appropriate location in window
coordinates. If lpDelta is NULL, no offset for the data is assumed.
The lpExt
argument specifies the extents into which the data should be scaled. If extents
are provided, data is scaled into a rectangle described by lpDelta and lpExt.
The values of x and y in lpExt and lpDelta are in the mapping
mode of the device context into which the data is rendered.
RedisplayPenData displays pen data with a square graphical device interface
(GDI) pen brush for maximum drawing speed. When displaying wide lines of ink,
this optimization can cause the ends of abutting lines to appear blocky. If you
prefer a smoother look to the joints of wide lines at the expense of rendering
speed, draw the ink with DrawPenData, DrawPenDataEx, or DrawPenDataFmt instead of RedisplayPenData.
These functions draw wide lines by flood-filling a region, thus smoothing the
ends.
See Also