IOleInPlaceSiteWindowless::ScrollRect method (ocidl.h)

Article
10/13/2021

Enables an object to scroll an area within its in-place active image on the screen.

Syntax

HRESULT ScrollRect(
  [in] INT     dx,
  [in] INT     dy,
  [in] LPCRECT pRectScroll,
  [in] LPCRECT pRectClip
);

Parameters

[in] dx

The amount to scroll the x-axis.

[in] dy

The amount to scroll the y-axis.

[in] pRectScroll

The rectangle to scroll, in client coordinates of the containing window. A value of NULL indicates the full object.

[in] pRectClip

The rectangle to clip. Only pixels scrolling into this rectangle are drawn. Pixels scrolling out are not. If this parameter is NULL, the rectangle is not clipped.

Return value

This method returns S_OK on success.

Remarks

This method should take in account the fact that the caller may be transparent and that there may be opaque or transparent overlapping objects. See Notes to Implementers below for suggestions on algorithms this method can use.

Notes to Implementers

Containers can implement this method in a variety of ways. However, all of them should account for the possibility that the object requesting scrolling may be transparent or may not have a solid background. Containers should also take into account that there may be overlapping objects.

The simplest way to implement this method consists in simply redrawing the rectangle to scroll.

An added refinement to this simple implementation is to use the ScrollDC function when the object requesting the scroll is opaque, the object has a solid background, and there are no overlapping objects.

More sophisticated implementations can use the following procedure:

Check whether the object is opaque and has a solid background, using IViewObjectEx::GetViewStatus. If not, simply invalidate the rectangle to scroll. An added refinement is to check whether the scrolling rectangle is entirely in the opaque region of a partially transparent object.
Get the window device context.
Clip out the opaque parts of any overlapping object returned by IViewObjectEx::GetRect.
Finally, call the ScrollDC function.
Redraw the previously invalidated transparent parts of any overlapping object.

Regardless of the scrolling and clipping rectangle, only pixels contained in the object's site rectangle will be painted. The area uncovered by the scrolling operation is invalidated and redrawn immediately, before this method returns.

All redraw generated by this method should happen synchronously before this method returns.

This method should automatically hide the caret during the scrolling operation and should move the caret by the scrolling amounts if it is inside the clip rectangle.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	ocidl.h