Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

NSScroller 

Inherits From:	NSControl : NSView : NSResponder : NSObject

Conforms To:	NSCoding (NSResponder)
NSObject (NSObject)

Declared In:	AppKit/NSScroller.h 

Class Description

The NSScroller class defines a control that's used by an NSScrollView object to position a document that's too large to be displayed in its entirety within an NSView. An NSScroller is typically represented on the screen by a bar, a knob, and two scroll buttons, although it may contain only some of these. The knob indicates both the position within the document and the amount displayed relative to the size of the document. The bar is the rectangular region that the knob slides within. The scroll buttons allow the user to scroll in small increments by clicking, or in large increments by Alternate-clicking. In discussions of the NSScroller class, a small increment is referred to as a ªline incrementº (even if the NSScroller is oriented horizontally), and a large increment is referred to as a ªpage increment,º although a page increment actually advances the document by one windowful. When you create an NSScroller, you can specify either a vertical or a horizontal orientation.

As an NSControl, an NSScroller handles mouse events and sends action messages to its target (usually its parent NSScrollView) to implement user-controlled scrolling. The NSScroller must also respond to messages from an NSScrollView to represent changes in document positioning.

NSScroller is a public class primarily for programmers who decide not to use an NSScrollView but want to present a consistent user interface. Its use is not encouraged except in cases where the porting of an existing application is made more straightforward. In these situations, you initialize a newly created NSScroller by calling initWithFrame:. Then, you use setTarget: (NSControl) to set the object that will receive messages from the NSScroller, and you use setAction: (NSControl) to specify the message that will be sent to the target by the NSScroller. When your target receives a message from the NSScroller, it will probably need to query the NSScroller using the hitPart and floatValue (NSControl) methods to determine what action to take.

The NSScroller class has several constants referring to the parts of an NSScroller. A scroll button with an up arrow (or left arrow, if the NSScroller is oriented horizontally) is known as a ªdecrement lineº button if it receives a normal click, and as a ªdecrement pageº button if it receives an Alternate-click. Similarly, a scroll button with a down or right arrow functions as both an ªincrement lineº button and an ªincrement pageº button. The constants defining the parts of an NSScroller are as follows:

Constant	Refers To

NSScrollerNoPart	No part of the NSScroller
NSScrollerKnob	The knob
NSScrollerDecrementPage	The button that decrements a windowful (up or left arrow)
NSScrollerIncrementPage	The button that increments a windowful (down or right arrow)
NSScrollerDecrementLine	The button that decrements a windowful (up or left arrow)
NSScrollerIncrementLine	The button that increments a windowful (down or right arrow)
NSScrollerKnobSlot 	The bar

The following constants are used in the setArrowsPosition: method to set the position of the scroll buttons within the scroller:

Constant	Meaning

NSScrollerArrowsMaxEnd	Scroll buttons are placed at the bottom or right end of the scroller.
NSScrollerArrowsMinEnd	Scroll buttons are placed at the top or left part of the scroller.
NSScrollerArrowsNone	The scroller doesn't have scroll buttons.

An NSScroller can be made too small for all its parts to be displayed. The usableParts method returns one of the following constants to indicate whether such a condition is present:

Constant	Meaning

NSNoScrollerParts	Scroller has no usable parts, only the bar.
NSOnlyScrollerArrows	Scroller has only scroll buttons.
NSAllScrollerParts	Scroller has all parts.

The following constants are used as values for the first argument of the drawArrow:highlight: method, to indicate which scroll button is to be drawn:

Constant	Meaning

NSScrollerIncrementArrow	The scroll button that scrolls forward.
NSScrollerDecrementArrow	The scroll button that scrolls backward.

Laying out the NSScroller 

+ (float)scrollerWidth	Returns the width of the scoller, a constant value.

- (NSScrollArrowPosition)arrowsPosition	Returns the position of scroll arrows in the NSScroller.

- (void)checkSpaceForParts	Checks for room for knob and scroll buttons.

- (NSRect)rectForPart:(NSScrollerPart)partCode	Gets the rectangle that encloses partCode.

- (void)setArrowsPosition:(NSScrollArrowPosition)where
	Sets position of scroll arrows in the NSScroller.

- (NSUsableScrollerParts)usableParts	Indicates which parts of the scroller can be displayed, given the NSScroller's current size.

Setting the NSScroller's Values

- (float)knobProportion	Returns the ratio of the knob's length to the NSScroller's length.	 

- (void)setFloatValue:(float)aFloat	 Sets the NSScroller's value, repositioning the 
knobProportion:(float)ratio 		 knob according to aFloat and resizing it according to ratio. Both arguments are clipped to the range from 0.0 to 1.0, inclusive.

Displaying 

- (void)drawArrow:(NSScrollerArrow)whichButton	 
highlight:(BOOL)flag	Draws highlighted and unhighlighted arrows.

- (void)drawKnob	Draws the knob.

- (void)drawParts	Caches bitmaps for knob and scroll arrows.

- (void)highlight:(BOOL)flag	Highlights scroll button that's under mouse.

Handling Events 

- (NSScrollerPart)hitPart	Returns the part of the NSScroller object that received mouse-down.

- (NSScrollerPart)testPart:(NSPoint)thePoint	Returns the part of the NSScroller that's under thePoint. 

- (void)trackKnob:(NSEvent *)theEvent	Invoked in response to mouse-down events on the knob.

- (void)trackScrollButtons:(NSEvent *)theEvent	Invoked in response to mouse-down events on buttons.