Copyright ©1995 by NeXT Computer, Inc.  All Rights Reserved.

ClipView

	Inherits From:	View : Responder : Object
	Declared In:	appkit/ClipView.h

Class Description

A ClipView object lets you scroll a document that may be larger than the ClipView's frame rectangle, clipping the visible portion of the document to the frame.  The document, which must be a View object, is called the ClipView's document view.  A ClipView's document view, which is set through the setDocView: method, is the ClipView's only subview.  You can set the cursor that's displayed when the mouse enters a ClipView's frame (in other words, when it's poised over the document view) through the setDocCursor: method. When the ClipView is instructed to scroll its document view, it copies as much of the previously visible document as possible, unless it received a setCopyOnScroll:NO message.  The ClipView then sends its document view a message to either display or mark as invalid the newly exposed region(s) of the ClipView.  By default it will invoke the document view's display:: method, but if the ClipView received a setDisplayOnScroll:NO message, it will invoke the document view's invalidate:: method. The ClipView sends its superview (usually a ScrollView) a reflectScroll: message whenever the relationship between the ClipView and the document view has changed.  This allows the superview to update itself to reflect the change--for example, the ScrollView class uses this method to change the position of its scrollers when the user causes the document to autoscroll. You don't normally use the ClipView class directly; it's provided primarily as the scrolling machinery for the ScrollView class. However, you might use the ClipView class to implement a class similar to ScrollView.

Instance Variables

float backgroundGray; id docView; id cursor;

	backgroundGray	The gray value used to fill the ClipView's background.
	docView	The ClipView's document view.
	cursor	The cursor that's used within the ClipView's frame.

Method Types

Initializing the class

+ initialize

Initializing and freeing a ClipView

initFrame:

free

Modifying the frame rectangle

moveTo::

rotateTo: sizeTo::

Modifying the coordinate system

rotate:

scale:: setDrawOrigin:: setDrawRotation: setDrawSize:: translate::

Managing component Views

docView

setDocView: getDocRect: getDocVisibleRect: resetCursorRects setDocCursor:

Modifying graphic attributes and displaying

backgroundGray setBackgroundGray: backgroundColor setBackgroundColor: drawSelf::

Scrolling

autoscroll:

constrainScroll: rawScroll: setCopyOnScroll: setDisplayOnScroll:

Coordinating with other Views

descendantFlipped:

descendantFrameChanged:

Archiving

awake

read: write:

Class Methods

initialize

+ initialize Sets the current version of the ClipView class.  You never invoke this method directly; it's sent for you when the application starts.  Returns self.

Instance Methods

autoscroll:

autoscroll:(NXEvent *)theEvent

Performs automatic scrolling of the document.  You never invoke this method directly; instead, the ClipView's document view should send autoscroll: to itself while inside a modal event loop initiated by a mouse-down event when the mouse is dragged outside the ClipView's frame.  The View class implements autoscroll: to forward the message to the View's superview; thus is the message forwarded to the ClipView. Returns nil if no scrolling occurs; otherwise returns self. See also:  autoscroll: (View)

awake

awake

You never invoke this method directly; it's invoked automatically after the ClipView has been read from an archive file. Returns self.

backgroundColor

(NXColor)backgroundColor

Returns the color of the ClipView's background.  If the background gray value has been set but no color has been set, the color equivalent of the background gray value is returned.  If neither value has been set, the background color of the ClipView's window is returned. See also:  backgroundGray, setBackgroundColor:, setBackgroundGray:, backgroundColor (Window), NXConvertGrayToColor()

backgroundGray

(float)backgroundGray

Returns the gray value of the ClipView's background.  If no value has been set, the gray value of the ClipView's window is returned. See also:  backgroundColor, setBackgroundGray:, backgroundGray (Window)

constrainScroll:

constrainScroll:(NXPoint *)newOrigin

Ensures that the document view is not scrolled to an undesirable position.  This method is invoked by the private method that all scrolling messages go through before it invokes rawScroll: or scrollClip:to:.  The default implementation keeps as much of the document view visible as possible.  You may want to override this method to provide alternate constraining behavior. newOrigin is the desired new origin of the ClipView's bounds rectangle, given in ClipView's coordinate system.  Returns self. See also:  rawScroll:

descendantFlipped:

descendantFlipped:sender

Changes the ClipView's coordinate system orientation (unflipped or flipped) to match that of the document view.  You never invoke this method directly; it's invoked automatically when the document view's orientation changes.  Returns self.

descendantFrameChanged:

descendantFrameChanged:sender

Notifies the ClipView that its document view has been resized or moved.  The ClipView may then scroll and/or redisplay the document view, and the ClipView may also notify its superview to reflect the changes in the scroll position.  You never invoke this method directly, nor should you override it in a subclass.  Returns self. See also:  moveTo:: (View), sizeTo:: (View), reflectScroll: (ScrollView), notifyAncestorWhenFrameChanged: (View), setDocView:

docView

docView

Returns the ClipView's document view. See also:  setDocView:

drawSelf::

drawSelf:(const NXRect *)rects :(int)rectCount

Overrides View's drawSelf:: method to fill the portions of the ClipView that aren't covered by opaque portions of the document view.  If a color value has been set and the ClipView is drawing itself on a color screen, the ClipView draws its background with the color value, otherwise it draws its background using its gray value.  Returns self. See also:  backgroundColor:, backgroundGray:, drawSelf:: (View)

free

free

Frees the ClipView and its subviews.

getDocRect:

getDocRect:(NXRect *)aRect

Returns, by reference in aRect, the smallest rectangle that encloses both the document view's frame and the ClipView's frame. The origin of the rectangle is always set to that of the document view's frame. The document rectangle is used in conjunction with the ClipView's bounds rectangle to determine values for any indicators of relative position and size between the ClipView and the document view.  The ScrollView uses these rectangles to set the size and position of the Scrollers' knobs.  Returns self. See also:  reflectScroll: (ScrollView)

getDocVisibleRect:

getDocVisibleRect:(NXRect *)aRect

Returns, by reference in aRect, the portion of the document view that's visible within the ClipView.  The visible rectangle is given in the document view's coordinate system.  Note that this rectangle doesn't reflect the effects of any clipping that may occur above the ClipView itself.  To get the portion of the document view that's guaranteed to be visible, send it a getVisibleRect: message.  Returns self. See also:  getVisibleRect: (View)

initFrame:

initFrame:(const NXRect *)frameRect

Initializes the ClipView, which must be a newly allocated ClipView instance.  The ClipView's frame rectangle is made equivalent to that pointed to by frameRect.  This method is the designated initializer for the ClipView class, and can be used to initialize a ClipView allocated from your own zone.  By default, clipping is enabled, and the ClipView is set to opaque.  A ClipView is initialized without a document view.  Returns self.

moveTo::

moveTo:(NXCoord)x :(NXCoord)y

Moves the origin of the ClipView's frame rectangle to (x, y) in its superview's coordinates.  Returns self.

rawScroll:

rawScroll:(const NXPoint *)newOrigin

Performs scrolling of the document view.  This method sets the ClipView's bounds rectangle origin to newOrigin.  Then it copies as much of the previously visible document as possible, unless it received a setCopyOnScroll:NO message.  It then sends its document view a message to either display or invalidate the newly exposed region(s) of the ClipView.  By default it will invoke the document view's display:: method, but if the ClipView received a setDisplayOnScroll:NO message, it will invoke the document view's invalidate:: method.  The rawScroll: method doesn't send a reflectScroll: message to its superview; that message is sent by the method that invokes rawScroll:.  Note also that while the ClipView provides clipping to its frame, it doesn't clip to the update rectangles. This method is used by a private method through which all scrolling passes, and is invoked if the ClipView's superview does not implement the scrollClip:to: method.  If the ClipView's superview does implement scrollClip:to:, that method should invoke rawScroll:.  This mechanism is provided so that the ClipView's superview can coordinate scrolling of multiple tiled ClipViews. (Note that ScrollView doesn't implement the scrollClip:to: method.)  Returns self.

read:

read:(NXTypedStream *)stream

Reads the ClipView and its document view from the typed stream stream.  Returns self. See also:  write:

resetCursorRects

resetCursorRects

Resets the cursor rectangle for the document view to the bounds of the ClipView.  Returns self. See also:  setDocCursor:, addCursorRect:cursor: (View)

rotate:

rotate:(NXCoord)angle

Disables rotation of the ClipView's coordinate system.  You also should not rotate the ClipView's document view, nor should you install a ClipView as a subview of a rotated view.  The proper way to rotate objects in the document view is to perform the rotation in your document view's drawSelf:: method.  Returns self.

rotateTo:

rotateTo:(NXCoord)angle

Disables rotation of the ClipView's frame rectangle.  This method also disables ClipView's inherited rotateBy: method. Returns self. See also:  rotate:

scale::

scale:(NXCoord)x :(NXCoord)y

Rescales the ClipView's coordinate system by a factor of x for its x-axis, and by a factor of y for its y-axis.  Since the document view's coordinate system is measured relative to the ClipView's coordinate system, the document view is redisplayed and a reflectScroll: message may be sent to the ClipView's superview.  Returns self. See also:  reflectScroll: (ScrollView)

setBackgroundColor:

setBackgroundColor:(NXColor)color

Sets the color of the ClipView's background.  This color is used to fill the area inside the ClipView that's not covered by opaque portions of the document view.  If no background gray has been set for the ClipView, this method sets it to the gray component of the color.  Returns self. See also:  backgroundColor, backgroundGray, setBackgroundGray, NXGrayComponent()

setBackgroundGray:

setBackgroundGray:(float)value

Sets the gray value of the ClipView's background.  This gray is used to fill the area inside the ClipView that's not covered by opaque portions of the document view.  value must lie in the range from 0.0 (black) to 1.0 (white).  Returns self. See also:  backgroundColor, backgroundGray, setBackgroundColor

setCopyOnScroll:

setCopyOnScroll:(BOOL)flag

Determines whether visible portions of the document view will be copied when scrolling occurs.  If flag is YES, scrolling will copy as much of the document as possible to scroll the View, allowing the document view to update only the newly exposed portions of itself.  If flag is NO, the document view is responsible for redrawing its entire visible portion.  This should only rarely be changed from the default value (YES).  Returns self.

setDisplayOnScroll:

setDisplayOnScroll:(BOOL)flag

Determines whether the results of scrolling will be immediately displayed.  If flag is YES, the results of scrolling will be immediately displayed.  If flag is NO, the ClipView is marked as invalid but isn't displayed.  This should only rarely be changed from the default setting of YES.  Returns self. See also:  rawScroll:, display:: (View), invalidate:: (View)

setDocCursor:

setDocCursor:anObj

Sets the cursor to be used inside the ClipView's bounds.  anObj should be an NXCursor object.  Returns the old cursor.

setDocView:

setDocView:aView

Sets aView as the ClipView's document view.  A ClipView can have only one document view; invoking this method removes the previous document view, if any.  This method initializes the document view with notifyAncestorWhenFrameChanged:YES and notifyWhenFlipped:YES messages.  The origin of the document view's frame is initially set to be coincident with the origin of the ClipView's bounds.  If the ClipView is contained within a ScrollView, you should send the ScrollView the setDocView: message and have the ScrollView pass this message on to the ClipView.  Returns the old document view, or nil if there was none. See also:  setDocView: (ScrollView)

setDrawOrigin::

setDrawOrigin:(NXCoord)x :(NXCoord)y

Overrides the View method so that changes in the ClipView's coordinate system are reflected in the displayed document view. This method may redisplay the document view, and a reflectScroll: message may be sent to the ClipView's superview. Returns self. See also:  setDrawOrigin:: (View)

setDrawRotation:

setDrawRotation:(NXCoord)angle

Disables rotation of the ClipView's coordinate system.  The proper way to rotate objects in the document view is to perform the rotation in your document view's drawSelf:: method.  Returns self. See also:  rotate:

setDrawSize::

setDrawSize:(NXCoord)width :(NXCoord)height

Overrides the View method so that rescaling of the ClipView's coordinate system is reflected in the displayed document view. This method may redisplay the document view, and a reflectScroll: message may be sent to the ClipView's superview. Returns self. See also:  setDrawSize:: (View)

sizeTo::

sizeTo:(NXCoord)width :(NXCoord)height

Overrides the View method so that resizing of the ClipView's frame rectangle is reflected in the displayed document view. This method may redisplay the document view, and a reflectScroll: message may be sent to the ClipView's superview. Returns self. See also:  sizeTo:: (View)

translate::

translate:(NXCoord)x :(NXCoord)y

Overrides the View method so that translation of the ClipView's coordinate system is reflected in the displayed document view. This method may redisplay the document view, and a reflectScroll: message may be sent to the ClipView's superview. Returns self. See also:  translate:: (View)

write:

write:(NXTypedStream *)stream

Writes the  ClipView and its document view to the typed stream stream.  Returns self. See also:  read:

Methods Implemented by a ClipView's Superview

reflectScroll:

reflectScroll:aClipView

Notifies the ClipView's superview that either the ClipView's bounds rectangle or the document view's frame rectangle has changed, and that any indicators of the scroll position need to be adjusted.  ScrollView implements this method to update its Scroller.

scrollClip:to:

scrollClip:aClipView to:(const NXPoint *)newOrigin

Notifies the ClipView's superview that the ClipView needs to set its bounds rectangle origin to newOrigin.  The ClipView's superview should then send the ClipView the rawScroll: message.  This mechanism is provided so that the ClipView's superview can coordinate scrolling of multiple tiled ClipViews.  Note that the default delegate is the ClipView's ScrollView, and doesn't respond to this method. See also:  rawScroll: (ClipView)