[TOC] [Prev] [Next] [Bottom]

NSSliderCell

Inherits From:
NSActionCell : NSCell : NSObject

Conforms To:
NSCoding, NSCopying (from NSCell)
NSObject (from NSObject)

Declared In:
AppKit/NSSliderCell.h

Class Description

An NSSliderCell controls the appearance and behavior of an NSSlider, or of a single slider in an NSMatrix. A slider can have tick marks to either side of it. The values represented by the tick marks are determined by the number of tick marks and the minimum and maximum values of the slider; a slider's values can be pegged to the values represented by the tick marks.

You can customize an NSSliderCell to a certain degree, using its set... methods. If these do not allow you sufficient flexibility, you can create a subclass. In that subclass, you can override any of the following methods: knobRectFlipped:, drawBarInside:flipped:, drawKnob:, or prefersTrackingUntilMouseUp.


Method Types

Asking about the cell's behavior
- altIncrementValue
+ prefersTrackingUntilMouseUp
- trackRect
Changing the cell's behavior
- setAltIncrementValue:
Displaying the cell
- knobRectFlipped:
- drawBarInside:flipped:
- drawKnob
- drawKnob:
Asking about the cell's appearance
- knobThickness
- isVertical
- title
- titleCell
- titleFont
- titleColor
Changing the cell's appearance
- setKnobThickness:
- setTitle:
- setTitleCell:
- setTitleColor:
- setTitleFont:
Asking about the value limits
- maxValue
- minValue
Changing the value limits
- setMaxValue:
- setMinValue:
Managing tick marks
- allowsTickMarkValuesOnly
- indexOfTickMarkAtPoint:
- numberOfTickMarks
- rectOfTickMarkAtIndex:
- setAllowsTickMarkValuesOnly:
- setNumberOfTickMarks:
- setTickMarkPosition:
- tickMarkPosition
- tickMarkValueAtIndex:

Class Methods

prefersTrackingUntilMouseUp

+ (BOOL)prefersTrackingUntilMouseUp

By default, this method returns YES, so that an NSSliderCell continues to track the mouse even after the mouse leaves the cell's tracking rectangle. This means that, once you take hold of a slider's knob (by putting the mouse inside the cell's frame rectangle and pressing the mouse button), you retain control of the knob until you release the mouse button, even if you drag the mouse clear to the other side of the screen.

Never call this method explicitly. Override it if you create a subclass of NSSliderCell that you want to track the mouse differently.


Instance Methods

allowsTickMarkValuesOnly

- (BOOL)allowsTickMarkValuesOnly

Returns whether the receiver fixes its values to those values represented by its tick marks.

See also: - setAllowsTickMarkValuesOnly:


altIncrementValue

- (double)altIncrementValue

Returns the amount that the slider will change its value when the user drags the knob with the Alt key held down.

Unless you call setAltIncrementValue, altIncrementValue returns -1.0, and the slider behaves no differently with the Alt key down than with it up.

See also: - setAltIncrementValue:


drawBarInside:flipped:

- (void)drawBarInside:(NSRect)aRect flipped:(BOOL)flipped

Draws the slider's bar-but not its bezel or knob-in aRect.

flipped indicates whether the cell's control view-that is, the NSSlider or NSMatrix associated with the NSSliderCell-has a flipped coordinate system.

You should never invoke this method explicitly. It's included so that you can override it in a subclass.

See also: - drawKnob:


drawKnob

- (void)drawKnob

Calculates the rectangle in which the knob should be drawn, then invokes drawKnob: to actually draw the knob. Before this message is sent, a lockFocus method must be sent to the cell's control view.

You might invoke this method if you override one of the display methods belonging to NSControl or NSCell.

If you create a subclass of NSSliderCell, don't override this method. Override drawKnob: instead.


drawKnob:

- (void)drawKnob:(NSRect)knobRect

Draws the knob in knobRect. Before this message is sent, a lockFocus message must be sent to the cell's control view.

You should never invoke this method explicitly. It's included so that you can override it in a subclass.


indexOfTickMarkAtPoint:

- (int)indexOfTickMarkAtPoint:(NSPoint)point

Returns the index of the tick mark closest to the location of the slider represented by point. If point is not within the bounding rectangle (plus an extra pixel of space) of any tick mark, the method returns NSNotFound. This method invokes rectOfTickMarkAtIndex: for each tick mark on the slider until it finds a tick mark containing the point.


isVertical

- (int)isVertical

Returns 1 if the slider is vertical, 0 if it's horizontal, and -1 if the orientation can't be determined (for example, if the slider hasn't been displayed yet). A slider is defined as vertical if its height is greater than its width.


knobRectFlipped:

- (NSRect)knobRectFlipped:(BOOL)flipped

Returns the rectangle in which the knob will be drawn, specified in the coordinate system of the NSSlider or NSMatrix with which the NSSliderCell is associated. flipped indicates whether that coordinate system is flipped, a question you can answer by sending NSView's isFlipped message to the NSMatrix or NSSlider.

The knob rectangle depends on where in the slider the knob belongs-that is, it depends on the SliderCell's minimum and maximum values, and on the value which the position of the knob will represent.

You should never invoke this method explicitly. It's included so that you can override it in a subclass.


knobThickness

- (float)knobThickness

Returns the knob's thickness, in pixels. The thickness is defined to be the extent of the knob along the long dimension of the bar. In a vertical slider, then, a knob's thickness is its height; in a horizontal slider, its thickness is its width.

See also: - setKnobThickness:


maxValue

- (double)maxValue

Returns the maximum value that the slider can send to its target. A horizontal slider sends its maximum value when the knob is at the right end of the slider; a vertical slider sends it when the knob is at the top.

See also: - setMaxValue:


minValue

- (double)minValue

Returns the minimum value that the slider can send to its target. A vertical slider sends this value when its knob is at the bottom; a horizontal slider sends it when its knob is all the way to the left.


numberOfTickMarks

- (int)numberOfTickMarks

Returns the number of tick marks associated with the slider. The tick marks assigned to the minimum and maximum values are included.

See also: - setNumberOfTickMarks:


rectOfTickMarkAtIndex:

- (NSRect)rectOfTickMarkAtIndex:(int)index

Returns the bounding rectangle of the tick mark identified by index (the minimum-value tick mark is at index 0). If no tick mark is associated with index, the method raises NSRangeException.

See also: - indexOfTickMarkAtPoint:


setAllowsTickMarkValuesOnly:

- (void)setAllowsTickMarkValuesOnly:(BOOL)flag

Sets whether the receiver's values are fixed to the values represented by the tick marks. For example, if a slider has a minimum value of 0, a maximum value of 100, and five markers, the allowable values are 0, 25, 50, 75, and 100. When users move the slider's knob, it jumps to the tick mark nearest the cursor when the mouse is released. This method has no effect if the slider has no tick marks.

See also: - allowsTickMarkValuesOnly


setAltIncrementValue:

- (void)setAltIncrementValue:(double)increment

Sets the amount by which the NSSliderCell modifies its value when the knob is Alt-dragged. increment should fit the range of values that the slider can represent-for example, if the slider has a minimum value of 5 and a maximum value of 10, increment should be between 0 and 5.

If you don't call this method, the slider behaves the same with the Alt key down as with it up. This is also the result when you call setAltIncrementValue: with an increment of -1.

See also: - maxValue, - minValue


setKnobThickness:

- (void)setKnobThickness:(float)thickness

Lets you set the knob's thickness, measured in pixels. The thickness is defined to be the extent of the knob along the long dimension of the bar. In a vertical slider, then, a knob's thickness is its height; in a horizontal slider, its thickness is its width.

See also: - knobThickness


setMaxValue:

- (void)setMaxValue:(double)aDouble

Sets the maximum value that the slider can send to its target-the value that a horizontal slider will send when its knob is all the way to the right, or that a vertical slider will send when its knob is at the top.

See also: - maxValue


setMinValue:

- (void)setMinValue:(double)aDouble

Sets the minimum value that the slider can send to its target. A horizontal slider sends its minimum value when its knob is all the way to the left; a vertical slider sends its minimum value when its knob is at the bottom.

See also: - minValue


setNumberOfTickMarks:

- (void)setNumberOfTickMarks:(int)numberOfTickMarks

Sets the number of tick marks displayed by the receiver (which include those assigned to the minimum and maximumvalues). By default, this value is zero, and no tick marks appear. The number of tick marks assigned to a slider, along with the slider's minimum and maximum values, determine the values associated with the tick marks.

See also: - numberOfTickMarks


setTickMarkPosition:

- (void)setTickMarkPosition:(NSTickMarkPosition)position

Sets where tick marks appear relative to the receiver. For horizontal sliders, position can be NSTickMarksBelow (the default) or NSTickMarksAbove; for vertical sliders, position can be NSTickMarksLeft (the default) or NSTickMarksRight. This method has no effect if no tick marks have been assigned (that is, numberOfTickMarks returns zero).

See also: - tickMarkPosition


setTitle:

- (void)setTitle:(NSString *)title

Sets the title in the bar behind the slider's knob to title.

See also: - title


setTitleCell:

- (void)setTitleCell:(NSCell *)aCell

Sets the cell used to draw the slider's title. You only need to invoke this method if the default title cell, NSTextFieldCell, doesn't suit your needs-that is, if you want to display the title in a manner that NSTextFieldCell doesn't permit. When you do choose to override the default, aCell should be an instance of a subclass of TextFieldCell.

See also: - titleCell


setTitleColor:

- (void)setTitleColor:(NSColor *)color

Sets the color used to draw the slider's title.

See also: - titleColor


setTitleFont:

- (void)setTitleFont:(NSFont *)font

Sets the font used to draw the slider's title.

See also: - titleFont


- tickMarkPosition

- (NSTickMarkPosition)tickMarkPosition

Returns how the receiver's tick marks are aligned with it: NSTickMarkBelow, NSTickMarkAbove, NSTickMarkLeft, or NSTickMarkRight (the last two are for vertical sliders). The default alignments are NSTickMarkBelow and NSTickMarkLeft.

See also: - setTickMarkPosition:


- tickMarkValueAtIndex:

- (double)tickMarkValueAtIndex:(int)index

Returns the receiver's value represented by the tick mark at index (the minimum-value tick mark has an index of zero).


title

- (NSString *)title

Returns the slider's title. The default title is the empty string ("").

See also: <