CScrollView Class

Article
01/08/2013

A CView with scrolling capabilities.

class CScrollView : public CView

Members

Protected Constructors

Name	Description
CScrollView::CScrollView	Constructs a CScrollView object.

Public Methods

Name	Description
CScrollView::CheckScrollBars	Indicates whether the scroll view has horizontal and vertical scroll bars.
CScrollView::FillOutsideRect	Fills the area of a view outside the scrolling area.
CScrollView::GetDeviceScrollPosition	Gets the current scroll position in device units.
CScrollView::GetDeviceScrollSizes	Gets the current mapping mode, the total size, and the line and page sizes of the scrollable view. Sizes are in device units.
CScrollView::GetScrollPosition	Gets the current scroll position in logical units.
CScrollView::GetTotalSize	Gets the total size of the scroll view in logical units.
CScrollView::ResizeParentToFit	Causes the size of the view to dictate the size of its frame.
CScrollView::ScrollToPosition	Scrolls the view to a given point, specified in logical units.
CScrollView::SetScaleToFitSize	Puts the scroll view into scale-to-fit mode.
CScrollView::SetScrollSizes	Sets the scroll view's mapping mode, total size, and horizontal and vertical scroll amounts.

Remarks

You can handle standard scrolling yourself in any class derived from CView by overriding the message-mapped OnHScroll and OnVScroll member functions. But CScrollView adds the following features to its CView capabilities:

It manages window and viewport sizes and mapping modes.
It scrolls automatically in response to scroll-bar messages.
It scrolls automatically in response to messages from the keyboard, a non-scrolling mouse, or the IntelliMouse wheel.

To scroll automatically in response to messages from the keyboard, add a WM_KEYDOWN message, and test for VK_DOWN, VK_PREV and call SetScrollPos.

You can handle mouse wheel scrolling yourself by overriding the message-mapped OnMouseWheel and OnRegisteredMouseWheel member functions. As they are for CScrollView, these member functions support the recommended behaviour for WM_MOUSEWHEEL, the wheel rotation message.

To take advantage of automatic scrolling, derive your view class from CScrollView instead of from CView. When the view is first created, if you want to calculate the size of the scrollable view based on the size of the document, call the SetScrollSizes member function from your override of either CView::OnInitialUpdate or CView::OnUpdate. (You must write your own code to query the size of the document. For an example, see the Scribble sample.)

The call to the SetScrollSizes member function sets the view's mapping mode, the total dimensions of the scroll view, and the amounts to scroll horizontally and vertically. All sizes are in logical units. The logical size of the view is usually calculated from data stored in the document, but in some cases you may want to specify a fixed size. For examples of both approaches, see CScrollView::SetScrollSizes.

You specify the amounts to scroll horizontally and vertically in logical units. By default, if the user clicks a scroll bar shaft outside of the scroll box, CScrollView scrolls a "page." If the user clicks a scroll arrow at either end of a scroll bar, CScrollView scrolls a "line." By default, a page is 1/10 of the total size of the view; a line is 1/10 of the page size. Override these default values by passing custom sizes in the SetScrollSizes member function. For example, you might set the horizontal size to some fraction of the width of the total size and the vertical size to the height of a line in the current font.

Instead of scrolling, CScrollView can automatically scale the view to the current window size. In this mode, the view has no scroll bars and the logical view is stretched or shrunk to exactly fit the window's client area. To use this scale-to-fit capability, call CScrollView::SetScaleToFitSize. (Call either SetScaleToFitSize or SetScrollSizes, but not both.)

Before the OnDraw member function of your derived view class is called, CScrollView automatically adjusts the viewport origin for the CPaintDC device-context object that it passes to OnDraw.

To adjust the viewport origin for the scrolling window, CScrollView overrides CView::OnPrepareDC. This adjustment is automatic for the CPaintDC device context that CScrollView passes to OnDraw, but you must call CScrollView::OnPrepareDC yourself for any other device contexts you use, such as a CClientDC. You can override CScrollView::OnPrepareDC to set the pen, background color, and other drawing attributes, but call the base class to do scaling.

Scroll bars can appear in three places relative to a view, as shown in the following cases:

Standard window-style scroll bars can be set for the view using the WS_HSCROLL and WS_VSCROLL Windows Styles.
Scroll-bar controls can also be added to the frame containing the view, in which case the framework forwards WM_HSCROLL and WM_VSCROLL messages from the frame window to the currently active view.
The framework also forwards scroll messages from a CSplitterWnd splitter control to the currently active splitter pane (a view). When placed in a CSplitterWnd with shared scroll bars, a CScrollView object will use the shared ones rather than creating its own.