Developer Documentation
PATH  Mac OS X Documentation > Application Kit Reference: Objective-C


[Previous] [Class List] [Next]

NSSlider


Inherits from: NSControl : NSView : NSResponder : NSObject
Conforms to: NSCoding
(from NSResponder)
NSObject (from NSObject)
Declared in: AppKit/NSSlider.h




Class Description


An NSSlider displays a range of values for something in the application. An indicator, or knob, notes the current setting. The user can move the knob in the slider's bar to change the setting. If the slider is vertical, its minimum is at its bottom; if it is horizontal, its minimum is at its left.

The minimum and maximum can be obtained with the minValue and maxValue methods, and set with the setMinValue: and setMaxValue: methods. To read the value represented by the current position of the knob, you use an NSControl method like floatValue; conversely, to send a value to the slider, you use a NSControl method like setFloatValue:.

By default, an NSSlider is a continuous NSControl: while the user drags the slider's knob, the slider sends its action message continuously. If, instead, you want the slider to reserve its action message until the mouse is released, invoke setContinuous: (an NSControl method) with an argument of NO.

In its bar, an NSSlider can display an image, a title, or both. The title can be drawn in any color and any font. However, because a title in the bar may be obscured by the slider knob, you will more often label a slider by placing an NSTextField near it.

An NSSlider 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.

Like most NSControls, NSSlider relies heavily on a related cell class, NSSliderCell. For more information, see the NSSliderCell class specification.

Don't use an NSSlider when an NSScroller would be better. A scroller represents the relative position of the visible portion of a view and lets the user choose which portion to view. A slider represents a range of values for something in the application and lets the user choose a setting.


Method Types


Asking about the slider's appearance
- altIncrementValue
- image
- knobThickness
- isVertical
Changing the slider's appearance
- setAltIncrementValue:
- setImage:
- setKnobThickness:
Asking about the slider's title
- title
- titleCell
- titleColor
- titleFont
Changing the slider's title
- setTitle:
- setTitleCell:
- setTitleColor:
- setTitleFont:
Asking about the value limits
- maxValue
- minValue
Changing the value limits
- setMaxValue:
- setMinValue:
Handling mouse-down events
- acceptsFirstMouse:
Managing tick marks
- allowsTickMarkValuesOnly
- closestTickMarkValueToValue:
- indexOfTickMarkAtPoint:
- numberOfTickMarks
- rectOfTickMarkAtIndex:
- setAllowsTickMarkValuesOnly:
- setNumberOfTickMarks:
- setTickMarkPosition:
- tickMarkPosition
- tickMarkValueAtIndex:


Instance Methods



acceptsFirstMouse:

- (BOOL)acceptsFirstMouse:(NSEvent *)mouseDownEvent

Returns YES by default, so a single mouse-down event can simultaneously activate the window and take hold of the slider's knob.

If you want the slider to wait for its own mouse-down event, you must override this method.



allowsTickMarkValuesOnly

- (BOOL)allowsTickMarkValuesOnly

Returns whether the receiver fixes its values to those values represented by its tick marks. In its implementation of this method, the receiving NSSlider simply invokes the method of the same name of its NSSliderCell.

See Also: - setAllowsTickMarkValuesOnly:



altIncrementValue

- (double)altIncrementValue

Returns the amount 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:



closestTickMarkValueToValue:

- (double)closestTickMarkValueToValue:(double)aValue

Returns the value of the tick mark closest to aValue. In its implementation of this method, the receiving NSSlider simply invokes the method of the same name of its NSSliderCell.

See Also: - indexOfTickMarkAtPoint:



image

- (NSImage *)image

Returns the image the slider displays in its bar, or nil if no image has been set.

See Also: - setImage:



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. In its implementation of this method, the receiving NSSlider simply invokes the method of the same name of its NSSliderCell. This method invokes rectOfTickMarkAtIndex: for each tick mark on the slider until it finds a tick mark containing the point.

See Also: - closestTickMarkValueToValue:



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.

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, a knob's thickness is its width.

See Also: - setKnobThickness:



maxValue

- (double)maxValue

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

See Also: - setMaxValue:



minValue

- (double)minValue

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

See Also: - setMinValue:



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. In its implementation of this method, the receiving NSSlider simply invokes the method of the same name of its NSSliderCell.

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. In its implementation of this method, the receiving NSSlider simply invokes the method of the same name of its NSSliderCell.

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. In its implementation of this method, the receiving NSSlider simply invokes the method of the same name of its NSSliderCell.

See Also: - allowsTickMarkValuesOnly



setAltIncrementValue:

- (void)setAltIncrementValue:(double)increment

Sets the amount by which the NSSliderCell modifies its value when the user Alt-drags the knob. increment must fit the range of values 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 increment is outside that range, the value is unchanged.

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



setImage:

- (void)setImage:(NSImage *)barImage

Sets the image the slider displays in the bar behind its knob. The slider may scale and distort barImage to fit inside the bar.

The knob may cover part of the image. If you want the image to be visible all the time, you're better off placing it near the slider.

See Also: - setImage:



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, a knob's thickness is its height; in a horizontal slider, a knob's thickness is its width.

See Also: - knobThickness



setMaxValue:

- (void)setMaxValue:(double)maxValue

Sets the maximum value the slider can send to its target. A horizontal slider sends its maximum value when its knob is all the way to the right; a vertical slider sends its maximum value when its knob is at the top.

See Also: - maxValue



setMinValue:

- (void)setMinValue:(double)minValue

Sets the minimum value 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 maximum values). 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. In its implementation of this method, the receiving NSSlider simply invokes the method of the same name of its NSSliderCell.

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). In its implementation of this method, the receiving NSSlider simply invokes the method of the same name of its NSSliderCell.

See Also: - tickMarkPosition



setTitle:

- (void)setTitle:(NSString *)barTitle

Sets the title the slider displays in the bar behind its knob.

The knob may cover part or all of the title. If you want the title to be visible all the time, you're better off placing a label near the slider.

See Also: - title



setTitleCell:

- (void)setTitleCell:(NSCell *)titleCell

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, you want to display the title in a manner that NSTextFieldCell doesn't permit. When you do choose to override the default, titleCell should be an instance of a subclass of NSTextFieldCell.

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. Possible values are NSTickMarkBelow, NSTickMarkAbove, NSTickMarkLeft, or NSTickMarkRight (the last two are for vertical sliders). The default alignments are NSTickMarkBelow and NSTickMarkLeft. In its implementation of this method, the receiving NSSlider simply invokes the method of the same name of its NSSliderCell.

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). In its implementation of this method, the receiving NSSlider simply invokes the method of the same name of its NSSliderCell.

title

- (NSString *)title

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

See Also: - setTitle:



titleCell

- (id)titleCell

Returns the cell used to draw the title. The default is an NSTextFieldCell.

See Also: - setTitleCell:



titleColor

- (NSColor *)titleColor

Returns the color used to draw the slider's title. The default color is NSColor's controlTextColor.

See Also: - setTitleColor:



titleFont

- (NSFont *)titleFont

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

See Also: - setTitleFont:




[Previous] [Next]