ITextServices::TxDraw method (textserv.h)

Article
11/19/2022

Draws the text services object.

Syntax

HRESULT TxDraw(
  [in] DWORD           dwDrawAspect,
       LONG            lindex,
  [in] void            *pvAspect,
  [in] DVTARGETDEVICE  *ptd,
  [in] HDC             hdcDraw,
  [in] HDC             hicTargetDev,
  [in] LPCRECTL        lprcBounds,
  [in] LPCRECTL        lprcWBounds,
  [in] LPRECT          lprcUpdate,
       BOOL(* )(DWORD) pfnContinue,
       DWORD           dwContinue,
       LONG            lViewId
);

Parameters

[in] dwDrawAspect

Type: DWORD

Specifies the aspect to be drawn, that is, how the object is to be represented. Draw aspect can be one of the following values.

Value	Meaning
DVASPECT_CONTENT	Renders a screen image of the text content to the hdcDraw device context. The hicTargetDev and ptd parameters give information on the target device context if any (usually a printer).
DVASPECT_DOCPRINT	Renders the object to the hdcDraw device context as though it were printed to a printer. Thus, the text services object can optimize for the printer (for example, not painting the background color, if white). Also, certain screen-specific elements (such as the selection) should not be rendered. ITextServices::TxDraw should render the lprcBounds rectangle, starting at the current scrolling position.

Value

Meaning

DVASPECT_CONTENT

Renders a screen image of the text content to the hdcDraw device context.

The hicTargetDev and ptd parameters give information on the target device context if any (usually a printer).

DVASPECT_DOCPRINT

Renders the object to the hdcDraw device context as though it were printed to a printer. Thus, the text services object can optimize for the printer (for example, not painting the background color, if white). Also, certain screen-specific elements (such as the selection) should not be rendered.

ITextServices::TxDraw should render the lprcBounds rectangle, starting at the current scrolling position.

lindex

Type: LONG

Not supported.

[in] pvAspect

Type: void*

Information for drawing optimizations.

[in] ptd

Type: DVTARGETDEVICE*

The target device.

[in] hdcDraw

Type: HDC

Rendering device context.

[in] hicTargetDev

Type: HDC

Target information context.

[in] lprcBounds

Type: LPCRECTL

The bounding (client) rectangle.

[in] lprcWBounds

Type: LPCRECTL

The clipping rectangle for metafiles.

[in] lprcUpdate

Type: LPRECT

The update region inside lprcBounds.

pfnContinue

Type: BOOL CALLBACK*

Not supported.

dwContinue

Type: DWORD

Parameter to pass to continue function.

lViewId

Type: LONG

Specifies the view to draw.

Value	Meaning
TXTVIEW_ACTIVE	Draw the inplace active view.
TXTVIEW_INACTIVE	Draw a view other than the inplace active view; for example, a print preview.

Return value

Type: HRESULT

The return value is typically S_OK.

Remarks

This method renders the text services object. It accepts the same parameters as the corresponding IViewObject::Draw method in OLE, with the extra lprcUpdate and the lViewId parameters. It can be used while the host is in-place active or inactive.

The lprcBounds parameter gives the rectangle to render, also called the client rectangle. This rectangle represents the position and extent of the entire image of the text services object to be drawn. It is expressed in the logical coordinate system of hdcDraw. If lprcBounds is NULL then the control must be active. In this case, the text services object should render the in-place active view (that is, the client rectangle that can be obtained by calling TxGetClientRect on the host).

If the lprcUpdate parameter is not NULL, it gives the rectangle to update inside that client rectangle, in the logical coordinate system of hdcDraw. If lprcUpdate is NULL, the entire client rectangle should be painted.

The text services object should render with the appropriate zoom factor, which can be obtained from the client rectangle and the native size given by TxGetExtent. For a discussion of the zoom factor, see TxGetExtent.

General comments on OLE hosts and ITextServices::TxDraw (also for ITextServices::OnTxSetCursor, and ITextServices::TxQueryHitPoint):

An OLE host can call the ITextServices::TxDraw method at any time with any rendering device context or client rectangle. An OLE object that is inactive only retains an extent. To get the rectangle in which to render, the host calls the IViewObject::Draw method. This rectangle is valid only for the scope of that method. Thus, the same control can be rendered consecutively in different rectangles and different device contexts, for example, because it is displayed simultaneously in different views on the screen.

Normally, the client rectangle and device context passed to ITextServices::TxDraw should not be cached, because this would force the text services object to recalculate lines for every draw, which would impede performance. Instead, the text services object could cache the information that is computed for a specific client rectangle and device context (such as line breaks). On the next call to ITextServices::TxDraw, however, the validity of the cached information should be checked before it gets used, and updated information should be regenerated, if necessary.

Also, take great care when the control is in-place active. This problem is even more complex since ITextServices::TxDraw can still be called to render other views than the one that is in-place active. In other words, the client rectangle passed to ITextServices::TxDraw may not be the same as the active one (passed to ITextServices::OnTxInPlaceActivate and obtained through TxGetClientRect on the host).

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	textserv.h
DLL	Msftedit.dll