Methods Index

CScroller

Heritage

Superclass: CVirtualFrame

Subclasses: CListBox

Description

CScroller attaches scrollbars to the visible area of the virtual frame; it is a virtual frame with scrollbars. Objects nested inside a scroller scroll automatically as the user manipulates the scrollbars. When users drag or size objects inside a scroller, the contents scroll automatically as the object is dragged beyond the visible borders.

Usage

Create a CScroller object, initialize it, and place objects inside it (see CVirtualFrame). You must call the initializer prior to using the CScroller object in order to establish the following:

Whether vertical scrollbars are to be attached
Whether horizontal scrollbars are to be attached
Step size: number of units to scroll per scrolling event
Page size: number of units to scroll per thumb scrolling event
Whether thumbtracking is to be used: scroll contents as the user drags the thumb; if this feature is not desired, the contents are scrolled upon release of a thumb drag

Environment

The scroller border is drawn with the pen; you can set the pen color, pattern, and width. The scroller background is drawn with the brush. The brush pattern has been disabled and is always PAT_SOLID, even if you give it another setting. You can define the brush color, however. The color of the scrollbars is system-defined.

Protected Data Members

NScrollBar *itsHScrollBar; Horizontal scrollbar
NScrollBar *itsVScrollBar; Vertical scrollbar
BOOLEAN itUsesWinScrollBars Flag used to determine whether scroller uses XVT window's scrollbars
BOOLEAN itIsThumbtracking; Whether thumbtracking is supported
CPoint* itsIntViewOrigin Internal origin (scrolling offset)
static RWOrdered itsUpdateViewList Views that need update after scrolling event.


`NScrollBar`	`*itsHScrollBar;`	Horizontal scrollbar
`NScrollBar`	`*itsVScrollBar;`	Vertical scrollbar
`BOOLEAN`	`itUsesWinScrollBars`	Flag used to determine whether scroller uses XVT window's scrollbars
`BOOLEAN`	`itIsThumbtracking;`	Whether thumbtracking is supported
`CPoint*`	`itsIntViewOrigin`	Internal origin (scrolling offset)
`static RWOrdered`	`itsUpdateViewList`	Views that need update after scrolling event.

Public Methods

Constructor, Destructor, and Initializer Methods

CScroller(CSubview* theEnclosure, 
	const CRect& theRegion,
	UNITS theVirtualWidth = 0,
	UNITS theVirtualHeight = 0);

A constructor. A constructor. theEnclosure is a pointer to the subview that will contain the scroller. theRegion is a coordinate location, local to the enclosure, that is used to place the scroller. The parameters theVirtualWidth and theVirtualHeight together define the size of the virtual area enclosing the scroller.

On MS-Windows, the maximum value for theVirtualHeight or theVirtualWidth is 32767.

CScroller(CWindow* theScrollableWindow, 
	UNITS theVirtualWidth = 0,
	UNITS theVirtualHeight = 0);

A constructor. theScrollableWindow is a window with scrollbars that will contain the scroller. The scroller will occupy the entire window's client area and will be operated using the window's scrollbars. The parameters theVirtualWidth and theVirtualHeight together define the size of the virtual area enclosing the scroller.

On MS-Windows, the maximum value for theVirtualHeight or theVirtualWidth is 32767.

CScroller(const CScroller& theScroller);

A copy constructor that duplicates the attributes, but not the contents, of a scroller. That is, it copies the scroller but does not do a deep copy of any views nested within it.

CScroller& operator=(const CScroller& theScroller);

An assignment operator that duplicates the attributes, but not the contents, of a scroller. That is, it copies the scroller but does not do a deep copy of any views nested within it.

virtual ~CScroller(void);

The destructor. It cleans up after the scroller and deletes any views nested within it.

BOOLEAN IScroller(
	BOOLEAN hasHorizontalScrollBar	= TRUE, 
	BOOLEAN hasVerticalScrollBar	= TRUE,
	BOOLEAN isThumbTracking 	= FALSE,
	UNITS theLineIncrement 	= 10, 
	UNITS thePageIncrement 	= 50,
	BOOLEAN isVisible 	= TRUE,
long theGlue		= NULLSTICKY);

The initializer. It allows you to specify whether the scroller has a horizontal scrollbar, whether it has a vertical scrollbar, and whether it dynamically tracks the scrollbar's thumb. theLineIncrement specifies the number of pixels to scroll for a line increment; similarly, thePageIncrement specifies the number of pixels to scroll for a page increment. Like all initializers for classes in the CSubview hierarchy, this initializer takes a visibility state and a glue type.

Scroller Utilities

virtual void SetHIncrements(UNITS theLineIncrement, UNITS thePageIncrement);

Sets the horizontal increments of the scroller, in units, for both line increments and page increments.

virtual void SetVIncrements(UNITS theLineIncrement, UNITS thePageIncrement);

Sets the vertical increments of the scroller, in units, for both line increments and page increments.

virtual UNITS GetHLineIncrement(void) const;

Returns the number of units that have been set for a horizontal line increment.

virtual UNITS GetVLineIncrement(void) const;

Returns the number of units that have been set for a vertical line increment.

virtual UNITS GetHPageIncrement(void) const;

Returns the number of units that have been set for a horizontal page increment.

virtual UNITS GetVPageIncrement(void) const;

Returns the number of units that have been set for a vertical page increment.

virtual void SetThumbtracking(BOOLEAN isThumbTracking);

Sets the thumbtracking for the scroller, taking a BOOLEAN value of TRUE or FALSE.

virtual BOOLEAN IsThumbtracking(void) const;

Returns a BOOLEAN value of TRUE if the scroller supports dynamic thumbtracking and FALSE if it does not.

static BOOLEAN RegisterForUpdate(CView* theView);

Internal method used by views that change size during scroll events.

Inherited Horizontal and Vertical Scrolling Methods

The following two methods are called when a scrollbar receives a scrolling event. The event propagates from the scrollbar to the CScroller object. theEventType designates the kind of scroll: line up, line down, page up, or page down (the terms "up" and "down" are used for both horizontal and vertical scrolling, though the effects are different for horizontal scrolling). theThumbPosition is the numerical value for placement of the thumb when either thumb repositioning or dynamic thumb tracking is used. This method responds to the scrollbar event by scrolling the views contained inside the scroller.

virtual void VScroll(SCROLL_CONTROL theEventType, UNITS theThumbPosition);

A method called when a scrollbar receives a vertical scroll event.

virtual void HScroll(SCROLL_CONTROL theEventType, UNITS theThumbPosition);

A method called when a scrollbar receives a horizontal scroll event.

Inherited Utilities

virtual void ScrollViews)const CPoint& theNewOrigin);

An overridden method that scrolls the views contained in the scroller.

virtual CPoint AutoScroll(UNITS horizontalChange, UNITS verticalChange);

Overrides the AutoScroll method on CView. The scroller receives this event when the user drags one of its subviews towards the outside of the scroller. The dragging produces an autoscroll event because the subview is being dragged outside of its bounds. theHorizontalChange takes a number of pixels. If the number is zero (0), no autoscrolling occurs; if the number is positive, the view scrolls to the right; if it is negative, the view scrolls to the left. theVerticalChange also takes a number of pixels. If the number is zero (0), no autoscrolling occurs; if the number is positive, the view scrolls downward; if it is negative, the view scrolls upward.

virtual void Key(const CKey& the key);

Handles a keystroke. If the scroller has keyboard focus when the keyboard is activated, this method is called automatically.

virtual void AddSubview(const CView* theSubview);

An overridden method that adds a pointer to a CSubview object to the contents of the virtual frame. This method ensures that the virtual region of the frame is large enough to include the newly added object, sizing it when necessary.

virtual CPoint GetGlobalOrigin(void) const;

Returns the scroller's origin (starting point), relative to the window.

virtual CRect GetClippedFrame(void) const;

Views are clipped to their enclosures, so portions of a view may not be visible. This method returns a region (CRect) with the coordinates of the visible portion of a clipped view. Usually, you will call GetClippedFrame before you call DoDraw

DoDraw

Draw

GetClippedFrame

CRect

Overridden Methods

The following methods have been overridden to operate on CScroller and its scrollbars:

virtual void Size(const CRect& theRect);

Sizes the scroller according to the coordinates of theRect. The reset region could be in a different location and have completely different dimensions-a new width or a new height. The coordinates of the region, theRect, are relative to the enclosure-like the coordinates of the region that is passed in when a view is instantiated.

virtual void Draw(const CRect& theClipping);

Overrides CView::Draw

virtual void DoDraw(
	const CRect& theClippingRegion = MAXRect);

Overrides CSubview::DoDraw

The scroller refreshes (draws) itself and notifies each of its subviews to do the same. theClippingRegion is the part of the scroller that needs to be refreshed and is in global, window-relative coordinates; if it is set to MAXRect, the entire scroller is drawn. This method is automatically called after an E_UPDATE event.

virtual void PrintDraw(
	const CRect& theClipping = MAXRect);

Does any drawing that should be sent to the printer. Only the views that fit in the scroller's visible frame are printed.

For more information on this method, see CView::PrintDraw.

virtual void SetOrigin(const CPoint& theDeltaPoint);

Takes the current origin of the CScroller and adds theDeltaPoint to it.

virtual void Show();

Makes the CScroller and its scrollbars visible.

virtual void Hide();

Makes the CScroller and its scrollbars invisible.

virtual void Enable();

Enables the CScroller and its scrollbars to receive events.

virtual void Disable();

Disables the CScroller and its scrollbars, so that they do not receive events.

virtual void SetEnvironment( 
	const CEnvironment& theEnvironment, 
	BOOLEAN isUpdate);

Sets the environment for the CScroller and its scrollbars, using theNewEnvironment. For more information, see the CView::SetEnvironment method

virtual void SetEnclosure(CSubview* theEnclosure);

Moves the CScroller's scrollbars, along with the CScroller, to a new enclosure. This method is overridden from CSubview.

Protected Methods

Inherited Methods

virtual void AdjustScrollBars(void);

An internal method to properly adjust the position and size of the scroll thumb. This method is called automatically when the scrollbar setting needs to be changed.

Other Methods

CRect GetInitialFrame(CSubview* theEnclosure, 
	const CRect& theRegion,
	BOOLEAN hasHorizontalScrollBar,
	BOOLEAN hasVerticalScrollBar) const;

Internal method that returns the initial size of the viewable scrolling region.

CRect GetInnerFrame(void) const;

Internal method that returns the size of the viewable scrolling region.

static RWOrdered & GetUpdateViewList(void);

Internal method used to keep track of views needing update messages.

static void ProcessViewUpdate(void);

Internal method used to update views that may change size during scroll events.

[Classes] [Prev] [Next] [Methods]

support@xvt.com