Inherits from: NSView : NSResponder : NSObject
Package: com.apple.yellow.application
Interface Builder | |
- initWithFrame: | Designated initializer. |
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 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 true
, 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
- frameSizeForContentSize:hasHorizontalScroller:hasVerticalScroller:borderType:
- Determining component sizes
- contentSize
- documentVisibleRect
- Managing graphic attributes
- setBackgroundColor
- backgroundColor
- 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
- isRulerVisible
- toggleRuler
- Setting scrolling behavior
- setLineScroll
- lineScroll
- setPageScroll
- pageScroll
- setScrollsDynamically
- scrollsDynamically
- Updating display after scrolling
- reflectScrolledClipView
- Arranging components
- tile
public NSScrollView(NSRect aRect)
public static NSSize contentSizeForFrameSize(NSSize frameSize, boolean hFlag, boolean vFlag, int borderType)
true
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)
public static NSSize frameSizeForContentSize(NSSize contentSize, boolean hFlag , boolean vFlag, int borderType)
true
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, + scrollerWidth (NSScroller)
public static Class rulerViewClass()
See Also: setRulerViewClass
public static 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
public NSColor backgroundColor()
See Also: setBackgroundColor, - backgroundColor (NSClipView)
public int borderType()
public NSSize contentSize()
See Also: contentSizeForFrameSize
public NSClipView contentView()
See Also: setContentView, documentView
public NSCursor documentCursor()
See Also: setDocumentCursor, - documentCursor (NSClipView)
public NSView documentView()
See Also: setDocumentView, - documentView (NSClipView)
public NSRect documentVisibleRect()
See Also: - documentVisibleRect (NSClipView) - visibleRect (NSView)
public boolean hasHorizontalRuler()
true
if
the receiver maintains a horizontal ruler view, false
if
it doesn't. Display of rulers is controlled
using the setRulersVisible method.See Also: horizontalRulerView, setHasHorizontalRuler, hasVerticalRuler, rulerViewClass
public boolean hasHorizontalScroller()
true
if
the receiver displays a horizontal scroller, false
if
it doesn't.See Also: horizontalScroller, setHasHorizontalScroller, hasVerticalScroller
public boolean hasVerticalRuler()
true
if
the receiver maintains a vertical ruler view, false
if
it doesn't. Display of rulers is controlled
using the setRulersVisible method.See Also: verticalRulerView, setHasVerticalRuler, hasHorizontalRuler, rulerViewClass
public boolean hasVerticalScroller()
true
if
the receiver displays a vertical scroller, false
if
it doesn't.See Also: verticalScroller, setHasVerticalScroller, hasHorizontalScroller
public float horizontalLineScroll()
See Also: setHorizontalLineScroll, verticalLineScroll, setLineScroll, horizontalPageScroll
public 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
public NSRulerView horizontalRulerView()
null
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
public NSScroller horizontalScroller()
null
if the receiver has none.public boolean isRulerVisible()
Returns true
if
the receiver was set to show rulers using setRulersVisible (whether or not
it has rulers at all), false
if it
was set to hide them.
See Also: toggleRuler
public 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
public 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
public 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
public boolean rulersVisible()
true
if
the receiver was set to show rulers using setRulersVisible (whether or not
it has rulers at all), false
if it
was set to hide them.See Also: hasHorizontalRuler, hasVerticalRuler
public boolean scrollsDynamically()
true
if
the receiver redraws its document view while tracking the knob, false
if
it redraws only when the scroller knob is released. NSScrollView
scrolls dynamically by default.See Also: setScrollsDynamically
public void setBackgroundColor(NSColor aColor)
See Also: backgroundColor, - setBackgroundColor: (NSClipView)
public void setBorderType(int borderType)
NSView.NoBorder
NSView.BezelBorder
NSView.GrooveBorder
See Also: borderType
public void setContentView(NSClipView aView)
See Also: contentView, setDocumentView
public void setDocumentCursor(NSCursor aCursor)
See Also: documentCursor
public void setDocumentView(NSView aView)
See Also: documentView, - setDocumentView: (NSClipView)
public void setHasHorizontalRuler(boolean flag)
true
,
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
public void setHasHorizontalScroller(boolean flag)
true
,
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
public void setHasVerticalRuler(boolean flag)
true
,
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
public void setHasVerticalScroller(boolean flag)
true
, 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
public void setHorizontalLineScroll(float aFloat)
See Also: lineScroll, setPageScroll
public 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
public void setHorizontalRulerView(NSRulerView aRulerView)
See Also: horizontalRulerView, setHasHorizontalRuler, setVerticalRulerView, setRulersVisible
public void setHorizontalScroller(NSScroller aScroller)
true
.See Also: horizontalScroller, setVerticalScroller
public void setLineScroll(float aFloat)
As part of its implementation, this method calls setVerticalLineScroll and setHorizontalLineScroll.
See Also: verticalLineScroll, horizontalLineScroll
public 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
public void setRulersVisible(boolean flag)
true
,
the receiver displays its rulers (creating them if needed). If flag is false
,
the receiver doesn't display its rulers.See Also: rulersVisible, hasHorizontalRuler, hasVerticalRuler
public void setScrollsDynamically(boolean flag)
true
it
does, if flag is false
it
redraws only when the scroller knob is released. NSScrollView scrolls
dynamically by default.See Also: scrollsDynamically
public void setVerticalLineScroll(float aFloat)
See Also: verticalLineScroll, setHorizontalLineScroll, lineScroll, setVerticalPageScroll
public 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
public void setVerticalRulerView(NSRulerView aRulerView)
See Also: verticalRulerView, setHasVerticalRuler, setHorizontalRulerView, setRulersVisible
public void setVerticalScroller(NSScroller aScroller)
true
.See Also: verticalScroller, setHorizontalScroller
public void tile()
public void toggleRuler(Object sender)
This action method shows or hides the ruler, if the receiver is enclosed in a scroll view.
See Also: isRulerVisible
public float verticalLineScroll()
See Also: setVerticalLineScroll, horizontalLineScroll, setLineScroll, verticalPageScroll
public 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
public NSRulerView verticalRulerView()
null
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
public NSScroller verticalScroller()
null
if the receiver has none.See Also: hasVerticalScroller, setVerticalScroller, horizontalScroller