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 TPtoDP3BE5AI5 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, DrawPenDataEx232HAFD 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 MetricScalePenData9GBK.JC converts the pen data to display coordinates. The second call to OffsetPenData9GBK.JD 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 ClientToScreen91X_84 function for (0,0) to find the proper screen coordinates to be placed in the *lpDelta POINT44VP0_ 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 DrawPenData232HAEC, DrawPenDataEx232HAFD, or DrawPenDataFmt1AOBV6 instead of RedisplayPenData. These functions draw wide lines by flood-filling a region, thus smoothing the ends.

See Also

DrawPenData