NSSlider Class Reference

Inherits from
NSControl : NSView : NSResponder : NSObject
Conforms to
NSAnimatablePropertyContainer (NSView)
NSUserInterfaceItemIdentification (NSView)
NSDraggingDestination (NSView)
NSCoding (NSResponder)
NSObject (NSObject)
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.0 and later.
Companion guide
Slider Programming Topics
Declared in
NSSlider.h
Related sample code

Overview

An NSSlider object displays a range of values for something in the application. Sliders can be vertical or horizontal bars or circular dials. An indicator, or knob, notes the current setting. The user can move the knob in the slider’s bar—or rotate the knob in a circular slider—to change the setting.

The NSSlider class uses the NSSliderCell class to implement its user interface.

Tasks

Asking About the Slider’s Appearance

Changing the Slider’s Appearance

Asking About the Slider’s Title

Changing the Slider’s Title

Asking About the Value Limits

Changing the Value Limits

Handling Mouse-down Events

Managing Tick Marks

Instance Methods

acceptsFirstMouse:

Returns a Boolean value indicating whether the slider accepts a single mouse-down event that simultaneously activates the window and takes hold of the slider’s knob.

- (BOOL)acceptsFirstMouse:(NSEvent *)mouseDownEvent
Parameters
mouseDownEvent

The mouse-down event.

Return Value

YES if the receiver accepts the first mouse-down event; otherwise, NO. Returns YES by default.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSSlider.h

allowsTickMarkValuesOnly

Returns a Boolean value indicating whether the receiver fixes its values to those values represented by its tick marks.

- (BOOL)allowsTickMarkValuesOnly
Return Value

YES if the slider fixes its values to the values represented by its tick marks; otherwise, NO.

Discussion

In its implementation of this method, the receiving NSSlider object simply invokes the method of the same name of its NSSliderCell object.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSlider.h

altIncrementValue

Returns the amount by which the receiver changes its value when the user Option–drags the slider knob.

- (double)altIncrementValue
Return Value

The amount by which the value changes when the user drags the slider knob with the Option key held down. Unless you call setAltIncrementValue:, altIncrementValue returns –1.0, and the receiver behaves no differently with the Option key down than with it up.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSlider.h

closestTickMarkValueToValue:

Returns the value of the tick mark closest to the specified value.

- (double)closestTickMarkValueToValue:(double)aValue
Parameters
aValue

The value for which to return the closest tick mark.

Return Value

The value of the tick mark closest to aValue.

Discussion

In its implementation of this method, the receiver simply invokes the method of the same name of its NSSliderCell instance.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSlider.h

image

This method has been deprecated. Returns nil.

- (NSImage *)image
Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSlider.h

indexOfTickMarkAtPoint:

Returns the index of the tick mark closest to the location of the receiver represented by the given point.

- (NSInteger)indexOfTickMarkAtPoint:(NSPoint)point
Parameters
point

The point representing the location for which to retrieve the tick mark.

Return Value

The index of the tick mark closest to the location specified by point. If point is not within the bounding rectangle (plus an extra pixel of space) of any tick mark, the method returns NSNotFound.

Discussion

In its implementation of this method, the receiving NSSlider instance simply invokes the method of the same name of its NSSliderCell instance. This method invokes rectOfTickMarkAtIndex: for each tick mark on the slider until it finds a tick mark containing the point.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSlider.h

isVertical

Returns an integer indicating the orientation (horizontal or vertical) of the slider.

- (NSInteger)isVertical
Return Value

1 if the receiver 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.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSSlider.h

knobThickness

Returns the knob’s thickness, in pixels.

- (CGFloat)knobThickness
Return Value

The thickness of the slider knob. 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.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSlider.h

maxValue

Returns the maximum value the receiver can send to its target.

- (double)maxValue
Return Value

The slider's maximum value. 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.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSSlider.h

minValue

Returns the minimum value the receiver can send to its target.

- (double)minValue
Return Value

The slider's minimum value. 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.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSSlider.h

numberOfTickMarks

Returns the number of tick marks associated with the receiver.

- (NSInteger)numberOfTickMarks
Return Value

The number of the slider's tick marks.The tick marks assigned to the minimum and maximum values are included. In its implementation of this method, the receiving NNSSlider instance simply invokes the method of the same name of its NSSliderCell instance.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSlider.h

rectOfTickMarkAtIndex:

Returns the bounding rectangle of the tick mark at the given index.

- (NSRect)rectOfTickMarkAtIndex:(NSInteger)index
Parameters
index

The index of the tick mark for which to retrieve the bounds. The minimum-value tick mark is at index 0.

Return Value

The bounding rectangle of the specified tick mark.

Discussion

If no tick mark is associated with index, the method raises NSRangeException. In its implementation of this method, the receiving NSSlider instance simply invokes the method of the same name of its NSSliderCell instance.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSlider.h

setAllowsTickMarkValuesOnly:

Sets whether the receiver’s values are fixed to the values represented by the tick marks.

- (void)setAllowsTickMarkValuesOnly:(BOOL)flag
Parameters
flag

YES if the slider's values should be fixed to the values represented by its tick marks; otherwise NO. 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 button is released.

Discussion

This method has no effect if the slider has no tick marks. In its implementation of this method, the receiving NSSlider instance simply invokes the method of the same name of its NSSliderCell instance.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSlider.h

setAltIncrementValue:

Sets the amount by which the NSSliderCell modifies its value when the user Option-drags the knob.

- (void)setAltIncrementValue:(double)increment
Parameters
increment

The amount by which the slider's value changes when the user Option–drags its knob. This value 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.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSlider.h

setImage:

This method has been deprecated. Sets the image the receiver displays in the bar behind its knob.

- (void)setImage:(NSImage *)barImage
Parameters
barImage

The image to set.

Discussion

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.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSlider.h

setKnobThickness:

This method has been deprecated. Lets you set the knob’s thickness, measured in pixels.

- (void)setKnobThickness:(CGFloat)thickness
Parameters
thickness

The thickness of the knob. 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.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSlider.h

setMaxValue:

Sets the maximum value the receiver can send to its target.

- (void)setMaxValue:(double)maxValue
Parameters
maxValue

The maximum value of the slider. 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.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSSlider.h

setMinValue:

Sets the minimum value the receiver can send to its target

- (void)setMinValue:(double)minValue
Parameters
minValue

The minimum value of the slider. 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.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSSlider.h

setNumberOfTickMarks:

Sets the number of tick marks displayed by the receiver.

- (void)setNumberOfTickMarks:(NSInteger)numberOfTickMarks
Parameters
numberOfTickMarks

The number of tick marks (including those assigned to the minimum and maximum values) displayed by the slider. By default, this value is 0, and no tick marks appear. The number of tick marks assigned to a slider, along with the slider’s minimum and maximum values, determines the values associated with the tick marks.

Discussion

In its implementation of this method, the receiving NSSlider instance simply invokes the method of the same name of its NSSliderCell instance.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSlider.h

setTickMarkPosition:

Sets where tick marks appear relative to the receiver.

- (void)setTickMarkPosition:(NSTickMarkPosition)position
Parameters
position

A constant indicating the position of the tick marks. For horizontal sliders, this can be NSTickMarkBelow (the default) or NSTickMarkAbove; for vertical sliders, this can be NSTickMarkLeft (the default) or NSTickMarkRight.

Discussion

This method has no effect if no tick marks have been assigned (that is, numberOfTickMarks returns 0). In its implementation of this method, the receiving NSSlider instance simply invokes the method of the same name of its NSSliderCell instance.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSlider.h

setTitle:

This method has been deprecated. Sets the title the receiver displays in the bar behind its knob.

- (void)setTitle:(NSString *)barTitle
Parameters
barTitle

The slider's title. 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.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSlider.h

setTitleCell:

This method has been deprecated. Sets the cell used to draw the receiver’s title.

- (void)setTitleCell:(NSCell *)titleCell
Parameters
titleCell

The cell used to draw the title.

Discussion

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.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSlider.h

setTitleColor:

This method has been deprecated. Sets the color used to draw the receiver’s title.

- (void)setTitleColor:(NSColor *)color
Parameters
color

The title color.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSlider.h

setTitleFont:

This method has been deprecated. Sets the font used to draw the receiver’s title.

- (void)setTitleFont:(NSFont *)font
Parameters
font

The title font.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSlider.h

tickMarkPosition

Returns how the receiver’s tick marks are aligned with it.

- (NSTickMarkPosition)tickMarkPosition
Return Value

A constant indicating the position of the tick marks. Possible values are NSTickMarkBelow, NSTickMarkAbove, NSTickMarkLeft, and NSTickMarkRight (the last two are for vertical sliders). The default alignments are NSTickMarkBelow and NSTickMarkLeft.

Discussion

In its implementation of this method, the receiving NSSlider instance simply invokes the method of the same name of its NSSliderCell instance.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSlider.h

tickMarkValueAtIndex:

Returns the receiver’s value represented by the tick mark at the specified index.

- (double)tickMarkValueAtIndex:(NSInteger)index
Parameters
index

The index of the tick mark for which to return the value. The minimum-value tick mark has an index of 0.

Return Value

The value of the specified tick mark.

Discussion

In its implementation of this method, the receiving NSSlider instance simply invokes the method of the same name of its NSSliderCell instance.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSSlider.h

title

Returns the receiver’s title.

- (NSString *)title
Return Value

The title. The default title is the empty string (@"").

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSlider.h

titleCell

This method has been deprecated. Returns nil.

- (id)titleCell
Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSlider.h

titleColor

This method has been deprecated. Returns nil.

- (NSColor *)titleColor
Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSlider.h

titleFont

This method has been deprecated. Returns nil.

- (NSFont *)titleFont
Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSlider.h


© 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-05-23)

Did this document help you? Yes It's good, but... Not helpful...