Inherits From:
NSView : NSResponder : NSObject
Conforms To:
NSCoding (NSResponder)
NSObject (NSObject)
Declared In:
AppKit/NSScrollView.h
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 on some platforms 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.
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 setHorizontalRuler:
and setVerticalRuler:
, 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 verticalRuler
methods and for establishing itself as the client using NSRulerView's setClientView:
method.
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.
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
).contentSizeForFrameSize:
(NSSize)frameSizehasHorizontalScroller:
(BOOL)hFlaghasVerticalScroller:
(BOOL)vFlagborderType:
(NSBorderType)borderType
Returns the size of a content view for an NSScrollView whose frame size is frameSize. hFlag and vFlag indicate whether a horizontal or vertical scroller, respectively, is present. If the flag is 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)
frameSizeForContentSize:
(NSSize)contentSizehasHorizontalScroller:
(BOOL)hFlaghasVerticalScroller:
(BOOL)vFlagborderType:
(NSBorderType)borderType
Returns the frame size of an NSScrollView that contains a content view whose size is contentSize. hFlag and vFlag indicate whether a horizontal or vertical scroller, respectively, is present. If the flag is 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)
rulerViewClass
Returns the default class to be used for ruler objects in NSScrollViews. This is normally NSRulerView.
See also:
+ setRulerViewClass:
setRulerViewClass:
(Class)aClass
Sets the default class to be used for ruler objects in NSScrollViews to aClass. This is normally NSRulerView, but you can use this method to set it to a custom subclass of NSRulerView.
rulerViewClass
to store their ruler view classes in private
variables.
See also:
+ rulerViewClass
backgroundColor
Returns the content view's background color.
See also:
- setBackgroundColor:
, - backgroundColor
(NSClipView)
borderType
Returns a value that represents the type of border surrounding the receiver; see the description of setBorderType:
for a list of possible values.
contentSize
Returns the size of the receiver's content view.
See also:
+ contentSizeForFrameSize:hasHorizontalScroller:hasVerticalScroller:borderType:
contentView
Returns the receiver's content view, the view that clips the document view.
See also:
- setContentView:
, - documentView
documentCursor
Returns the content view's document cursor.
See also:
- setDocumentCursor:
, - documentCursor
(NSClipView)
documentView
Returns the view that the receiver scrolls within its content view.
See also:
- setDocumentView:
, - documentView
(NSClipView)
documentVisibleRect
Returns the portion of the document view, in its own coordinate system, that's visible through the receiver's content view.
See also:
- documentVisibleRect
(NSClipView), - visibleRect
(NSView)
hasHorizontalRuler
Returns 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
hasHorizontalScroller
Returns YES if the receiver displays a horizontal scroller, NO if it doesn't.
See also:
- horizontalScroller
, - setHasHorizontalScroller:
, - hasVerticalScroller
hasVerticalRuler
Returns 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
hasVerticalScroller
Returns YES if the receiver displays a vertical scroller, NO if it doesn't.
See also:
- verticalScroller
, - setHasVerticalScroller:
, - hasHorizontalScroller
horizontalRulerView
Returns the receiver's horizontal ruler view, whether or not the receiver is currently displaying it, or 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
horizontalScroller
Returns the receiver's horizontal scroller, whether or not the receiver is currently displaying it, or nil
if the receiver has none.
isRulerVisible
<<forthcoming>>
See also:
- toggleRuler:r
lineScroll
Returns the amount by which the receiver scrolls itself when scrolling line-by-line, expressed in the content view's coordinate system. This amount is used when the user clicks the scroll arrows without holding a modifier key.
See also:
- setLineScroll:
, - pageScroll
pageScroll
Returns the amount of the document view kept visible when scrolling page-by-page, expressed in the content view's coordinate system. This amount is used when the user clicks the scroll arrows while holding the Alternate key.
- setLineScroll:
, - pageScroll
reflectScrolledClipView:
(NSClipView *)aClipView
If aClipView is the receiver's content view, adjusts the receiver's scrollers to reflect the size and positioning of its document view. Does nothing if aClipView is any other view object (in particular, if it's an NSClipView that isn't the content view).
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
rulersVisible
Returns 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
scrollsDynamically
Returns 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:
setBackgroundColor:
(NSColor *)aColor
Sets the color of the content view's background to aColor. This color is used to paint areas inside the content view that aren't covered by the document view.
See also:
- backgroundColor
, - setBackgroundColor:
(NSClipView)
setBorderType:
(NSBorderType)borderType
Sets the border type of the receiver to borderType, which may be one of:
NSNoBorder
NSLineBorder
NSBezelBorder
NSGrooveBorder
See also:
- borderType
setContentView:
(NSClipView *)aView
Sets the receiver's content view, the view that clips the document view, to aView. aView's document view, if any, also becomes the receiver's document view, while the original content view's document view remains with it.
See also:
- contentView
, - setDocumentView:
setDocumentCursor:
(NSCursor *)aCursor
Sets the cursor used when the mouse is over the content view to aCursor, by sending setDocumentCursor:
to the content view.
See also:
- documentCursor
setDocumentView:
(NSView *)aView
Sets the receiver's document view to aView.
See also:
- documentView
, - setDocumentView:
(NSClipView)
setHasHorizontalRuler:
(BOOL)flag
Determines whether the receiver keeps a horizontal ruler object. If flag is 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:
setHasHorizontalScroller:
(BOOL)flag
Determines whether the receiver keeps a horizontal scroller. If flag is 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:
setHasVerticalRuler:
(BOOL)flag
Determines whether the receiver keeps a vertical ruler object. If flag is 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:
setHasVerticalScroller:
(BOOL)flag
Determines whether the receiver keeps a vertical scroller. If flag is 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:
setHorizontalRulerView:
(NSRulerView *)aRulerView
Sets the receiver's horizontal ruler view to aRulerView. You can use this method to override the default ruler class set using the class method setRulerViewClass:
. Display of rulers is controlled using the setRulersVisible:
method.
See also:
- horizontalRulerView
,- setHasHorizontalRuler:
, - setVerticalRulerView:
,
- setRulersVisible:
setHorizontalScroller:
(NSScroller *)aScroller
Sets the receiver's horizontal scroller to aScroller, establishing the appropriate target-action relationships between them. To make sure the scroller is visible, invoke the setHasHorizontalScroller:
method with an argument of YES.
See also:
- horizontalScroller
, - setVerticalScroller:
setLineScroll:
(float)aFloat
Sets the amount by which the receiver scrolls itself when scrolling line-by-line to aFloat, expressed in the content view's coordinate system. This is the amount used when the user clicks the scroll arrows without holding a modifier key. When displaying text in an NSScrollView, for example, you might set this to the height of a single line of text in the default font.
See also:
- lineScroll
, - setPageScroll:
setPageScroll:
(float)aFloat
Sets the amount of the document view kept visible when scrolling page-by-page to aFloat, expressed in the content view's coordinate system. This amount is used when the user clicks the scroll arrows while holding the Alternate key.
- pageScroll
, - setLineScroll:
setRulersVisible:
(BOOL)flag
Determines whether the receiver displays its rulers. If flag is 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
setScrollsDynamically:
(BOOL)flag
Determines whether the receiver redraws its document view while scrolling continuously. If flag is YES it does, if flag is NO it redraws only when the scroller knob is released. NSScrollView scrolls dynamically by default.
See also:
- scrollsDynamically
setVerticalRulerView:
(NSRulerView *)aRulerView
Sets the receiver's vertical ruler view to aRulerView. You can use this method to override the default ruler class set using the class method setRulerViewClass:
. Display of rulers is controlled using the setRulersVisible:
method.
See also:
- verticalRulerView
, - setHasVerticalRuler:
, - setHorizontalRulerView:
,
- setRulersVisible:
setVerticalScroller:
(NSScroller *)aScroller
Sets the receiver's vertical scroller to aScroller, establishing the appropriate target-action relationships between them. To make sure the scroller is visible, invoke the setHasVerticalScroller:
method with an argument of YES.
See also:
- verticalScroller
, - setHorizontalScroller:
tile
Lays out the components of the receiver: the content view, the scrollers, and the ruler views. You rarely need to invoke this method, but subclasses may override it to manage additional components.
toggleRuler:
(id)sender
<<forthcoming>>
See also:
- isRulerVisible
verticalRulerView
Returns the receiver's vertical ruler view, whether or not the receiver is currently displaying it, or 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
verticalScroller
Returns the receiver's vertical scroller, whether or not the receiver is currently displaying it, or nil
if the receiver has none.
See also:
- hasVerticalScroller
, - setVerticalScroller:
, - horizontalScroller