- Inherits from:
- NSView : NSResponder : NSObject
- Conforms to:
- NSCoding
- (NSResponder)
- NSObject (NSObject)
Declared in:
- AppKit/NSScrollView.h
An NSScrollView allows the user to scroll a document view that's too large to display in its entirety. In addition to the document view, it displays horizontal and vertical scrollers and rulers (depending on which it's configured to have).
Interface Builder |
setDocumentView: | Sets the cursor used over the document view. |
setLineScroll: | Sets the amount by which the document view moves during scrolling. |
setRulersVisible: | Displays or hides rulers. |
The NSScrollView class is the central coordinator for the Application Kit's scrolling machinery, composed of this class, NSClipView, and NSScroller. An NSScrollView displays a portion of a document view that's too large to be displayed whole, and provides NSScrollers that allow the user to move the document view within the NSScrollView. An NSScrollView can be configured with a vertical scroller, a horizontal scroller, or both. In addition to the basic accoutrements, an NSScrollView keeps a cursor that it sets whenever the mouse is over its document view, and maintains both horizontal and vertical ruler objects that can be hidden and displayed.
An NSScrollView encloses its document view within an NSClipView, using this view to actually position and monitor the document view. Because the NSClipView manages the content of the NSScrollView, it's also called the content view. The content view positions the document view by altering its bounds rectangle, which determines where the document view's frame lies. The content view also monitors changes in the document view's size and notifies the NSScrollView so that the scrollers can be updated to reflect the new size. The documentView and contentView methods return an NSScrollView's major component views.
NSScrollView defines three levels of scrolling: by line, by page, and direct. Scrolling by line moves the document view by a small amount, typically when the user clicks the scroll buttons of a scroller. Scrolling by page moves the document view by a larger amount, typically near the size of the content view, when the user Alternate-clicks the scroll buttons, and in the slot of the scroller. You set these amounts using setLineScroll: and setPageScroll:, respectively (Interface Builder also lets you set these directly). Direct scrolling moves the document view to the position of the scroller's knob as the user drags it. This either displays the document view continuously as it scrolls or displays it only when the user releases the mouse, as configured with the setScrollsDynamically: method.
When created programmatically, an NSScrollView has no scrollers.
You can set them up using the setHasVerticalScroller: and setHasHorizontalScroller: methods
with an argument of YES
, which cause
the NSScrollView to allocate and maintain instances of the NSScroller
class. You can substitute specialized scrollers using the setVerticalScroller: and setHorizontalScroller: methods.
Note that in any case you must use the setHas... methods
to make sure the NSScrollView displays its scrollers.
NSView contains a few additional methods for scrolling a document programmatically. To scroll a specific point to the upper left corner of the view, use scrollPoint:. To scroll a specific area into view, use scrollRectToVisible:. To scroll automatically as the user drags something outside the window, use autoscroll:.
An NSScrollView can be set to hold both horizontal and vertical rulers using the setHasHorizontalRuler: and setHasVerticalRuler: methods. These allocate instances of the NSRulerView class, but unlike with scrollers don't immediately display the rulers. To do this, use the setRulersVisible: method. You can substitute custom ruler objects using setHorizontalRulerView: and setVerticalRulerView:, and to customize the rulers for all instances of NSScrollView you can set the class used with setRulerViewClass:. This causes all subsequent rulers created by NSScrollViews to be of the class you specify.
An NSScrollView's rulers don't automatically establish the document view as their client. The document view itself (or a subview) is responsible, as its selection and other state changes, for retrieving the rulers using NSScrollView's horizontalRulerView and verticalRulerView methods and for establishing itself as the client using NSRulerView's setClientView: method.
As indicated above, an NSScrollView's document view is actually positioned by the content view, which sets its bounds rectangle in such a way that the document view's frame moves relative to it. However, the action sequence between the scrollers and the NSScrollView and the manner in which scrolling is performed involve a bit more detail than this.
Scrolling typically occurs because of user actions on an NSScroller object, which sends the NSScrollView a private action message telling it to scroll based on the NSScroller's state. This process is described in the class description for the NSScroller class under " "Interaction with a Container View" ." If you plan to implement your own kind of scrolling view or scroller object, you should read that section.
NSClipView's scrollToPoint: is the method that actually scrolls the document view. It essentially translates the origin of the content view's bounds rectangle, but it also optimizes redisplay by copying as much of the rendered document view as remains visible, and only asking the document view to draw newly exposed regions. This usually improves scrolling performance, but may not always be appropriate behavior. You can turn it off using NSClipView's setCopiesOnScroll: method. If you do leave copy-on-scroll active, be sure to scroll the document view programmatically using scrollToPoint: rather than translateOriginToPoint:.
Whether the document view scrolls explicitly through a user action or an NSClipView message, or implicitly through a setFrame: or other such message, the content view monitors it closely. Whenever the document view's frame or bounds rectangle changes, it informs the NSScrollView of the change with a reflectScrolledClipView: message. This method updates the NSScroller objects to reflect the position and size of the visible portion of the document view. You may find on occasion that you need to invoke this method explicitly when manipulating the document view directly.
In addition to user-driven and programmatic scrolling, you can program any NSView to automatically scroll when the user drags the mouse outside the enclosing NSClipView. This allows the user to drag an item in order to move it, and have the document view automatically shift itself in the appropriate direction when the user drags the item past the visible area. NSClipView's autoscroll: method takes an NSEvent object of the mouse-dragged type and scrolls its document view in the opposite direction from the mouse location, making the portion of the document view that would be under the mouse become visible. NSView also implements autoscroll: to forward the message to its superview. This allows any NSView to simply send the message to itself during a mouse-dragging loop without checking whether it's contained in an NSClipView (though it does need to check whether the mouse is outside of its visible portion, as returned by visibleRect).
- Calculating layout
- + contentSizeForFrameSize:hasHorizontalScroller:hasVerticalScroller:borderType:
- + frameSizeForContentSize:hasHorizontalScroller:hasVerticalScroller:borderType:
- Determining component sizes
- - contentSize
- - documentVisibleRect
- Managing graphic attributes
- - setBackgroundColor:
- - backgroundColor
- - drawsBackground
- - setDrawsBackground:
- - setBorderType:
- - borderType
- Managing the scrolled views
- - setContentView:
- - contentView
- - setDocumentView:
- - documentView
- - setDocumentCursor:
- Managing scrollers
- - setHorizontalScroller:
- - horizontalScroller
- - setHasHorizontalScroller:
- - hasHorizontalScroller
- - setVerticalScroller:
- - verticalScroller
- - setHasVerticalScroller:
- - hasVerticalScroller
- Managing rulers
- + setRulerViewClass:
- + rulerViewClass
- - setHasHorizontalRuler:
- - hasHorizontalRuler
- - setHorizontalRulerView:
- - horizontalRulerView
- - setHasVerticalRuler:
- - hasVerticalRuler
- - setVerticalRulerView:
- - verticalRulerView
- - setRulersVisible:
- - rulersVisible
- Setting scrolling behavior
- - setLineScroll:
- - lineScroll
- - setPageScroll:
- - pageScroll
- - setScrollsDynamically:
- - scrollsDynamically
- Updating display after scrolling
- - reflectScrolledClipView:
- Arranging components
- - tile
+ (NSSize)contentSizeForFrameSize:(NSSize)frameSize
hasHorizontalScroller:(BOOL)hFlag
hasVerticalScroller:(BOOL)vFlag
borderType:(NSBorderType)borderType
YES
then the content
size is reduced in the appropriate dimension by the width of an
NSScroller. borderType indicates
the appearance of the NSScrollView's edge, which also affects
the content size; see the description of setBorderType: for a list of possible
values.For an existing NSScrollView, you can simply use the contentSize method.
See Also: + frameSizeForContentSize:hasHorizontalScroller:hasVerticalScroller:borderType:, + scrollerWidth (NSScroller)
+ (NSSize)frameSizeForContentSize:(NSSize)contentSize
hasHorizontalScroller:(BOOL)hFlag
hasVerticalScroller:(BOOL)vFlag
borderType:(NSBorderType)borderType
YES
then the frame
size is increased in the appropriate dimension by the width of an
NSScroller. borderType indicates
the appearance of the NSScrollView's edge, which also affects
the frame size; see the description of setBorderType: for a list of possible
values.For an existing NSScrollView, you can simply use the frame method and extract its size.
See Also: + contentSizeForFrameSize:hasHorizontalScroller:hasVerticalScroller:borderType:, + scrollerWidth (NSScroller)
+ (Class)rulerViewClass
See Also: + setRulerViewClass:
+ (void)setRulerViewClass:(Class)aClass
This method simply sets a global variable private to NSScrollView. Subclasses of NSScrollView should override both this method and rulerViewClass to store their ruler view classes in private variables.
See Also: + rulerViewClass
- (NSColor *)backgroundColor
See Also: - setBackgroundColor:, - backgroundColor (NSClipView)
- (NSBorderType)borderType
- (NSSize)contentSize
See Also: + contentSizeForFrameSize:hasHorizontalScroller:hasVerticalScroller:borderType:
- (NSClipView *)contentView
See Also: - setContentView:, - documentView
- (NSCursor *)documentCursor
See Also: - setDocumentCursor:, - documentCursor (NSClipView)
- (id)documentView
See Also: - setDocumentView:, - documentView (NSClipView)
- (NSRect)documentVisibleRect
See Also: - documentVisibleRect (NSClipView), - visibleRect (NSView)
- (BOOL)drawsBackground
- (BOOL)hasHorizontalRuler
YES
if
the receiver maintains a horizontal ruler view, NO
if
it doesn't. Display of rulers is controlled
using the setRulersVisible: method.See Also: - horizontalRulerView, - setHasHorizontalRuler:, - hasVerticalRuler, + rulerViewClass
- (BOOL)hasHorizontalScroller
YES
if
the receiver displays a horizontal scroller, NO
if
it doesn't.See Also: - horizontalScroller, - setHasHorizontalScroller:, - hasVerticalScroller
- (BOOL)hasVerticalRuler
YES
if
the receiver maintains a vertical ruler view, NO
if
it doesn't. Display of rulers is controlled
using the setRulersVisible: method.See Also: - verticalRulerView, - setHasVerticalRuler:, - hasHorizontalRuler, + rulerViewClass
- (BOOL)hasVerticalScroller
YES
if
the receiver displays a vertical scroller, NO
if
it doesn't.See Also: - verticalScroller, - setHasVerticalScroller:, - hasHorizontalScroller
- (float)horizontalLineScroll
See Also: - setHorizontalLineScroll:, - verticalLineScroll, - setLineScroll:, - horizontalPageScroll
- (float)horizontalPageScroll
This amount expresses the context that remains when the receiver scrolls by one page, allowing the user to orient himself to the new display. It differs from the line scroll amount, which indicates how far the document view moves. The page scroll amount is the amount common to the content view before and after the document view is scrolled by one page.
See Also: - setHorizontalPageScroll:, - verticalPageScroll, - setPageScroll:, - horizontalLineScroll
- (NSRulerView *)horizontalRulerView
nil
if the receiver has none. If
the receiver is set to display a horizontal ruler view and doesn't yet
have one, this method creates an instance of the ruler view class
set using the class method setRulerViewClass:.
Display of rulers is controlled using the setRulersVisible: method.See Also: - hasHorizontalRuler, - verticalRulerView
- (NSScroller *)horizontalScroller
nil
if the receiver has none.- (float)lineScroll
Note that a scroll view can have two different line scroll amounts: verticalLineScroll and horizontalLineScroll. Use this method only if you can be sure they're both the same; for example, you always use setLineScroll:, which sets both amounts to the same value.
See Also: - setLineScroll:, - verticalPageScroll, - horizontalPageScroll
- (float)pageScroll
This amount expresses the context that remains when the receiver scrolls by one page, allowing the user to orient himself to the new display. It differs from the line scroll amount, which indicates how far the document view moves. The page scroll amount is the amount common to the content view before and after the document view is scrolled by one page.
Note that a scroll view can have two different page scroll amounts: verticalPageScroll and horizontalPageScroll. Use this method only if you can be sure they're both the same; for example, you always use setPageScroll:, which sets both amounts to the same value.
See Also: - setPageScroll:, - verticalLineScroll, - horizontalLineScroll
- (void)reflectScrolledClipView:(NSClipView
*)aClipView
This method is invoked automatically during scrolling and when an NSClipView's relationship to its document view changes; you should rarely need to invoke it yourself, but may wish to override it for custom updating or other behavior.
See Also: - contentView, - documentView
- (BOOL)rulersVisible
YES
if
the receiver was set to show rulers using setRulersVisible: (whether or not
it has rulers at all), NO
if it was
set to hide them.See Also: - hasHorizontalRuler, - hasVerticalRuler
- (BOOL)scrollsDynamically
YES
if
the receiver redraws its document view while tracking the knob, NO
if
it redraws only when the scroller knob is released. NSScrollView
scrolls dynamically by default.See Also: - setScrollsDynamically:
- (void)setBackgroundColor:(NSColor
*)aColor
See Also: - backgroundColor, - setBackgroundColor: (NSClipView)
- (void)setBorderType:(NSBorderType)borderType
NSNoBorder
NSBezelBorder
NSGrooveBorder
See Also: - borderType
- (void)setContentView:(NSClipView
*)aView
See Also: - contentView, - setDocumentView:
- (void)setDocumentCursor:(NSCursor
*)aCursor
See Also: - documentCursor
- (void)setDocumentView:(NSView
*)aView
See Also: - documentView, - setDocumentView: (NSClipView)
- (void)setDrawsBackground:(BOOL)flag
- (void)setHasHorizontalRuler:(BOOL)flag
YES
,
the receiver allocates a horizontal ruler the first time it's
needed. Display of rulers is handled independently with the setRulersVisible: method.See Also: - hasHorizontalRuler, - horizontalRulerView, - setHasVerticalRuler:
- (void)setHasHorizontalScroller:(BOOL)flag
YES
,
the receiver allocates and displays a horizontal scroller as needed.
An NSScrollView by default has neither a horizontal nor a vertical
scroller.See Also: - hasHorizontalScroller, - horizontalScroller, - setHasVerticalScroller:
- (void)setHasVerticalRuler:(BOOL)flag
YES
,
the receiver allocates a vertical ruler the first time it's needed.
Display of rulers is handled independently with the setRulersVisible: method.See Also: - hasVerticalRuler, - verticalRulerView, - setHasHorizontalRuler:, - setRulersVisible:
- (void)setHasVerticalScroller:(BOOL)flag
YES
,
the receiver allocates and displays a vertical scroller as needed.
An NSScrollView by default has neither a vertical nor a horizontal scroller.See Also: - hasVerticalScroller, - verticalScroller, - setHasHorizontalScroller:
- (void)setHorizontalLineScroll:(float)aFloat
See Also: - lineScroll, - setPageScroll:
- (void)setHorizontalPageScroll:(float)aFloat
This amount expresses the context that remains when the receiver scrolls by one page, allowing the user to orient himself to the new display. It differs from the line scroll amount, which indicates how far the document view moves. The page scroll amount is the amount common to the content view before and after the document view is scrolled by one page. Thus, setting the page scroll amount to 0.0 implies that the entire visible portion of the document view is replaced when a page scroll occurs.
See Also: - pageScroll, - setLineScroll:
- (void)setHorizontalRulerView:(NSRulerView
*)aRulerView
See Also: - horizontalRulerView, - setHasHorizontalRuler:, - setVerticalRulerView:, - setRulersVisible:
- (void)setHorizontalScroller:(NSScroller
*)aScroller
YES
.See Also: - horizontalScroller, - setVerticalScroller:
- (void)setLineScroll:(float)aFloat
As part of its implementation, this method calls setVerticalLineScroll: and setHorizontalLineScroll:.
See Also: - verticalLineScroll, - horizontalLineScroll
- (void)setPageScroll:(float)aFloat
This amount expresses the context that remains when the receiver scrolls by one page, allowing the user to orient himself to the new display. It differs from the line scroll amount, which indicates how far the document view moves. The page scroll amount is the amount common to the content view before and after the document view is scrolled by one page. Thus, setting the page scroll amount to 0.0 implies that the entire visible portion of the document view is replaced when a page scroll occurs.
As part of its implementation, this method calls setVerticalPageScroll: and setHorizontalPageScroll:.
See Also: - verticalPageScroll, - verticalLineScroll
- (void)setRulersVisible:(BOOL)flag
YES
,
the receiver displays its rulers (creating them if needed). If flag is NO
,
the receiver doesn't display its rulers.See Also: - rulersVisible, - hasHorizontalRuler, - hasVerticalRuler
- (void)setScrollsDynamically:(BOOL)flag
YES
it
does, if flag is NO
it
redraws only when the scroller knob is released. NSScrollView scrolls dynamically
by default.See Also: - scrollsDynamically
- (void)setVerticalLineScroll:(float)aFloat
See Also: - verticalLineScroll, - setHorizontalLineScroll:, - lineScroll, - setVerticalPageScroll:
- (void)setVerticalPageScroll:(float)aFloat
This amount expresses the context that remains when the receiver scrolls by one page, allowing the user to orient himself to the new display. It differs from the line scroll amount, which indicates how far the document view moves. The page scroll amount is the amount common to the content view before and after the document view is scrolled by one page. Thus, setting the page scroll amount to 0.0 implies that the entire visible portion of the document view is replaced when a page scroll occurs.
See Also: - verticalPageScroll, - setHorizontalPageScroll:, - pageScroll, - setVerticalLineScroll:
- (void)setVerticalRulerView:(NSRulerView
*)aRulerView
See Also: - verticalRulerView, - setHasVerticalRuler:, - setHorizontalRulerView:, - setRulersVisible:
- (void)setVerticalScroller:(NSScroller
*)aScroller
YES
.See Also: - verticalScroller, - setHorizontalScroller:
- (void)tile
- (float)verticalLineScroll
See Also: - setVerticalLineScroll:, - horizontalLineScroll, - setLineScroll:, - verticalPageScroll
- (float)verticalPageScroll
This amount expresses the context that remains when the receiver scrolls by one page, allowing the user to orient himself to the new display. It differs from the line scroll amount, which indicates how far the document view moves. The page scroll amount is the amount common to the content view before and after the document view is scrolled by one page.
See Also: - setVerticalPageScroll:, - horizontalPageScroll, - setPageScroll:, - verticalLineScroll
- (NSRulerView *)verticalRulerView
nil
if the receiver has none. If
the receiver is set to display a vertical ruler view and doesn't
yet have one, this method creates an instance of the ruler view
class set using the class method setRulerViewClass:. Display of rulers
is controlled using the setRulersVisible: method.See Also: - hasVerticalRuler, - horizontalRulerView
- (NSScroller *)verticalScroller
nil
if the receiver has none.See Also: - hasVerticalScroller, - setVerticalScroller:, - horizontalScroller