Scroller

Scroller

Inherits From: Control : View : Responder : Object

Declared In: appkit/Scroller.h

Class Description

The Scroller class defines a Control that's used by a ScrollView object to position a document that's too large to be displayed in its entirety within a View. A Scroller 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 Scroller class, a small increment is referred to as a "line increment" (even if the Scroller 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 a Scroller, you can specify either a vertical or a horizontal orientation.
As a Control, a Scroller handles mouse events and sends action messages to its target (usually its parent ScrollView) to implement user-controlled scrolling. The Scroller must also respond to messages from a ScrollView to represent changes in document positioning.
Scroller is a public class primarily for programmers who decide not to use a ScrollView 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 Scroller with initFrame:. Then, you use setTarget: (Control) to set the object that will receive messages from the Scroller, and you use setAction: (Control) to specify the message that will be sent to the target by the Scroller. When your target receives a message from the Scroller, it will probably need to query the Scroller using the hitPart and floatValue methods to determine what action to take.
The Scroller class has several constants referring to the parts of a Scroller. A scroll button with an up arrow (or left arrow, if the Scroller 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 a Scroller are as follows:

Constant Refers To

NX_NOPART No part of the Scroller

NX_KNOB The knob

NX_DECPAGE The button that decrements a page (up, left arrow)

NX_INCPAGE The button that increments a page (down, right arrow)

NX_DECLINE The button that decrements a line (up, left arrow)

NX_INCLINE The button that increments a line (down, right arrow)

NX_KNOBSLOT or The bar

NX_JUMP

Instance Variables

float curValue;
float perCent;
int hitPart;
id target;
SEL action;
struct _sFlags{
unsigned int isHoriz:1;
unsigned int arrowsLoc:2;
unsigned int partsUsable:2;
} sFlags;

curValue The position of the knob, from 0.0 (top or left position) to 1.0.

perCent The fraction of the bar the knob fills, from 0.0 to 1.0.

hitPart Which part got the last mouse-down event.

target The target of the Scroller.

action The action sent to Scroller's target.

sFlags.isHoriz True if this is a horizontal Scroller.

sFlags.arrowsLoc The location of the scroll buttons within the Scroller.

sFlags.partsUsable The parts of the Scroller that are currently displayed.

Method Types

Initializing a Scroller initFrame:

Laying out the Scroller calcRect:forPart:

checkSpaceForParts
setArrowsPosition:

Setting Scroller values floatValue

setFloatValue:
setFloatValue::

Resizing the Scroller sizeTo::

Displaying drawArrow::

drawKnob
drawParts
drawSelf::
highlight:

Target and action setAction:

action
setTarget:
target

Handling events acceptsFirstMouse

hitPart
mouseDown:
testPart:
trackKnob:
trackScrollButtons:

Archiving awake

read:
write:

Instance Methods

acceptsFirstMouse

(BOOL)acceptsFirstMouse

Overrides inherited methods to ensure that the Scroller will receive the mouse-down event that made its window the key window. Returns YES.

action

(SEL)action

Returns the action of the Scroller--in other words, the selector for the method the Scroller will invoke when it receives a mouse-down event.
See also: target, setAction:

awake

awake

Overrides Object's awake method to perform additional initialization. After a Scroller has been read from an archive file, it will receive this message. You should not invoke this method directly. Returns self.
See also: read

calcRect:forPart:

(NXRect *)calcRect:(NXRect *)aRect forPart:(int)partCode

Calculates the rectangle (in the Scroller's drawing coordinates) that encloses a particular part of the Scroller. This rectangle is returned in aRect. partCode is NX_DECPAGE, NX_KNOB, NX_INCPAGE, NX_DECLINE, NX_INCLINE, or NX_KNOBSLOT. This method is useful if you override the drawArrow:: or drawKnob method. Returns aRect (the pointer you passed it).
See also: drawArrow::, drawKnob

checkSpaceForParts

checkSpaceForParts

Checks to see if there is enough room in the Scroller to display the knob and buttons and sets sFlags.partsUsable to one of the following values:

Value Meaning

NX_SCROLLERNOPARTS Scroller has no usable parts, only the bar.

NX_SCROLLERONLYARROWS Scroller has only scroll buttons.

NX_SCROLLERALLPARTS Scroller has all parts.

This method is used by sizeTo::; you should not invoke this method yourself. Returns self.
See also: sizeTo::

drawArrow::

drawArrow:(BOOL)upOrLeft :(BOOL)highlight

Draws a scroll button. If upOrLeft is NO, this method draws the down or right scroll button (NX_INCLINE), depending on whether the Scroller is oriented vertically or horizontally. If upOrLeft is YES, this method draws the up or left scroll button (NX_DECLINE). The highlight state is determined by highlight. If highlight is YES, the button is drawn highlighted, otherwise it's drawn normally. This method is invoked by drawSelf:: and mouse-down events. It's a public method so that you can override it; you should not invoke it directly. Returns self.
See also: drawKnob, calcRect:forPart:

drawKnob

drawKnob

Draws the knob. Don't send this message directly; it's invoked by drawSelf:: and mouse-down events. Returns self.
See also: drawArrow::, calcRect:forPart:

drawParts

drawParts

This method caches images for the various graphic entities composing the Scroller. It's invoked only once by the first of either initFrame: or awake. You may want to override this method if you alter the look of the Scroller, but you should not invoke it directly. Returns self.

drawSelf::

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

This method draws the Scroller. It's used by the display methods, and you should not invoke it directly. rects is an array of rectangles that need to be covered, with the first one being the union of the subsequent rectangles. rectCount is the number of elements in this array. Returns self.
See also: display::: (View)

floatValue

(float)floatValue

Returns the position of the knob, a value in range 0.0 to 1.0. A value of 0.0 indicates that the knob is at the top or left position within the bar, depending on the Scroller's orientation.
See also: setFloatValue::

highlight:

highlight:(BOOL)flag

This method highlights or unhighlights the scroll button that the user clicked on. The Scroller invokes this method while tracking the mouse, and you should not invoke it directly. If flag is YES, the button is drawn highlighted, otherwise it's drawn normally. Returns self.
See also: drawArrow::

hitPart

(int)hitPart

Returns the part of the Scroller that is causing the current action, typically the part that received a mouse-down event. See the Scroller class description for possible values. This method is typically invoked by the ScrollView to determine what action to take when the ScrollView receives an action message from the Scroller.
See also: action

initFrame:

initFrame:(const NXRect *)frameRect

Initializes a newly allocated Scroller with frame frameRect, which cannot be NULL. If frameRect's width is greater than its height, a horizontal Scroller is created; otherwise, a vertical Scroller is created. The Scroller is initially disabled. If the Scroller is a subview of a ScrollView, its width and height are reset automatically by the ScrollView's tile method; in this case, the width of vertical Scrollers and the height of horizontal Scrollers are set to NX_SCROLLERWIDTH. This method is the designated initializer for the Scroller class. Returns self.
See also: setEnabled: (Control), tile (ScrollView)

mouseDown:

mouseDown:(NXEvent *)theEvent

This method acts as a dispatcher when a mouse-down event occurs in the Scroller. It determines what part of the Scroller was clicked, and invokes the appropriate methods (such as trackKnob: or trackScrollButtons:). You should not invoke this method directly. Returns self.

read:

read:(NXTypedStream *)stream

Reads the Scroller from the typed stream stream, and sets all aspects of its state. Returns self.
See also: write:, awake

setAction:

setAction:(SEL)aSelector

Sets the action of the Scroller. When the user manipulates the Scroller, the Scroller sends its action message to its target, which (if it's a ScrollView) will then query the Scroller to determine how to respond. Returns self.
See also: setTarget:, action

setArrowsPosition:

setArrowsPosition:(int)where

Sets the location of the scroll buttons within the Scroller to where, or inhibits their display, as follows:

Value Meaning

NX_SCROLLARROWSMAXEND Buttons at bottom or right

NX_SCROLLARROWSMINEND Buttons at top or left

NX_SCROLLARROWSNONE No buttons

Returns self.

setFloatValue:

setFloatValue:(float)aFloat

Sets the position of the knob to aFloat, which is a value between 0.0 and 1.0. This method is the same as setFloatValue:: except it doesn't change the size of the knob. Returns self.
See also: setFloatValue::, floatValue

setFloatValue::

setFloatValue:(float)aFloat :(float)knobProportion

Sets the position and size of the knob. Sets the position within the bar to aFloat, which is a value between 0.0 and 1.0. A value of 0.0 positions and displays the knob at the top or left of the bar, depending on the orientation of the Scroller. The size of the knob is determined by knobProportion, which is a value between 0.0 and 1.0. A value of 0.0 sets the knob to a predefined minimum size, and a value of 1.0 makes the knob fill the bar. Returns self.
See also: setFloatValue:, floatValue

setTarget:

setTarget:anObject

Sets the target of the Scroller to anObject. The Scroller's target receives the action message set by setAction: when the user manipulates the Scroller. Returns self.
See also: target, setAction:

sizeTo::

sizeTo:(NXCoord)width :(NXCoord)height

Overrides the default View method so the Scroller can check which parts can be drawn. This method is typically invoked by tile (ScrollView), which sets the Scroller to a constant width (or height, if the Scroller is horizontal) of NX_SCROLLERWIDTH. Returns self.
See also: checkSpaceForParts, tile (ScrollView)

target

target

Returns the Scroller's target.
See also: setTarget:, action

testPart:

(int)testPart:(const NXPoint *)thePoint

Returns the part of the Scroller that lies under thePoint. See the Scroller class description for possible values.

trackKnob:

trackKnob:(NXEvent *)theEvent

Tracks the knob and sends action messages to the Scroller's target. This method is invoked when the Scroller receives a mouse-down event in the knob. You should not invoke this method directly. Returns self.
See also: mouseDown:, action, target

trackScrollButtons:

trackScrollButtons:(NXEvent *)theEvent

Tracks the scroll buttons and sends action messages to the Scroller's target. This method is invoked when the Scroller receives a mouse-down event in a scroll button. You should not invoke this method directly. Returns self.
See also: mouseDown:, action, target

write:

write:(NXTypedStream *)stream

Writes the Scroller to the typed stream stream, saving all aspects of its state. Returns self.
See also: read:

	Inherits From:	Control : View : Responder : Object

	Declared In:	appkit/Scroller.h

	Constant	Refers To

	NX_NOPART	No part of the Scroller
	NX_KNOB	The knob
	NX_DECPAGE	The button that decrements a page (up, left arrow)
	NX_INCPAGE	The button that increments a page (down, right arrow)
	NX_DECLINE	The button that decrements a line (up, left arrow)
	NX_INCLINE	The button that increments a line (down, right arrow)
	NX_KNOBSLOT or	The bar
	NX_JUMP

	curValue	The position of the knob, from 0.0 (top or left position) to 1.0.

	perCent	The fraction of the bar the knob fills, from 0.0 to 1.0.

	hitPart	Which part got the last mouse-down event.

	target	The target of the Scroller.

	action	The action sent to Scroller's target.

	sFlags.isHoriz	True if this is a horizontal Scroller.

	sFlags.arrowsLoc	The location of the scroll buttons within the Scroller.

	sFlags.partsUsable	The parts of the Scroller that are currently displayed.

	Initializing a Scroller	initFrame:

	Laying out the Scroller	calcRect:forPart:

	Value	Meaning

	NX_SCROLLERNOPARTS	Scroller has no usable parts, only the bar.
	NX_SCROLLERONLYARROWS	Scroller has only scroll buttons.
	NX_SCROLLERALLPARTS	Scroller has all parts.

	Value	Meaning

	NX_SCROLLARROWSMAXEND	Buttons at bottom or right
	NX_SCROLLARROWSMINEND	Buttons at top or left
	NX_SCROLLARROWSNONE	No buttons