Mac Developer Library

Developer

AppKit Framework Reference NSSegmentedControl Class Reference

Options
Deployment Target:

On This Page
Language:

NSSegmentedControl

Inheritance


  • NSObject
  • NSResponder
  • NSView
  • NSControl
  • NSSegmentedControl

Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.3 and later.

An NSSegmentedControl object implements a linear set of two or more segments, each of which functions as a button.

The NSSegmentedControl class uses an NSSegmentedCell class to implement much of the control's functionality. Most methods in NSSegmentedControl are simply cover methods that call the corresponding method in NSSegmentedCell. The methods of NSSegmentedCell that do not have covers relate to accessing and setting values for tags and tool tips, programatically setting the key segment, and establishing the mode of the control.

The features of a segmented control include the following:

  • A segment can have an image, text (label), menu, tooltip, and tag.

  • A segmented control can contain images or text, but not both.

  • Either the control or individual segments can be enabled or disabled.

  • Segmented controls have four tracking modes, described in NSSegmentSwitchTracking. You use these modes with the trackingMode property.

  • Each segment can be either a fixed width or autosized to fit the contents.

  • If a segment has text and is marked as autosizing, then the text may be truncated so that the control completely fits.

  • If an image is too large to fit in a segment, it is clipped.

  • If Full Keyboard Access is enabled in System Preferences > Keyboard, the keyboard may be used to move between and select segments.

  • The number of segments in the control.

    Declaration

    Swift

    var segmentCount: Int

    Objective-C

    @property NSInteger segmentCount

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • The index of the selected segment of the control, or -1 if no segment is selected.

    Declaration

    Swift

    var selectedSegment: Int

    Objective-C

    @property NSInteger selectedSegment

    Discussion

    If the control allows multiple selections, this property contains the most recently selected segment. If the index is out of bounds, an NSRangeException is raised.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Selects the segment with the specified tag.

    Declaration

    Swift

    func selectSegmentWithTag(_ tag: Int) -> Bool

    Objective-C

    - (BOOL)selectSegmentWithTag:(NSInteger)tag

    Parameters

    tag

    The tag associated with the desired segment. A tag is an integer value that can be assigned to a segment as a way of identifying it without knowing its position in the control.

    Return Value

    YEStrue if the segment was selected successfully; otherwise, NOfalse.

    Discussion

    Typically, you use Interface Builder to specify the tag for each segment. You may also set this value programmatically using the setTag:forSegment: method of NSSegmentedCell.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

    See Also

    setTag:forSegment: (NSSegmentedCell)

  • Sets the width of the specified segment.

    Declaration

    Swift

    func setWidth(_ width: CGFloat, forSegment segment: Int)

    Objective-C

    - (void)setWidth:(CGFloat)width forSegment:(NSInteger)segment

    Parameters

    width

    The width of the segment, measured in points. Specify the value 0 if you want the segment to be sized to fit the available space automatically.

    segment

    The index of the segment whose width you want to set. This method raises an NSRangeException if the index is out of bounds.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns the width of the specified segment.

    Declaration

    Swift

    func widthForSegment(_ segment: Int) -> CGFloat

    Objective-C

    - (CGFloat)widthForSegment:(NSInteger)segment

    Parameters

    segment

    The index of the segment whose width you want to get. This method raises an NSRangeException if the index is out of bounds.

    Return Value

    The width of the segment, measured in points, or 0 if the segment is sized to fit the available space automatically.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Sets the image for the specified segment.

    Declaration

    Swift

    func setImage(_ image: NSImage?, forSegment segment: Int)

    Objective-C

    - (void)setImage:(NSImage *)image forSegment:(NSInteger)segment

    Parameters

    image

    The image to apply to the segment or nil if you want to clear the existing image. Images are not scaled to fit inside a segment. If the image is larger than the available space, it is clipped.

    segment

    The index of the segment whose image you want to set. This method raises an NSRangeException if the index is out of bounds.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns the image associated with the specified segment.

    Declaration

    Swift

    func imageForSegment(_ segment: Int) -> NSImage?

    Objective-C

    - (NSImage *)imageForSegment:(NSInteger)segment

    Parameters

    segment

    The index of the segment whose image you want to get. This method raises an NSRangeException if the index is out of bounds.

    Return Value

    The image associated with the segment; otherwise, nil.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Sets the label for the specified segment.

    Declaration

    Swift

    func setLabel(_ label: String, forSegment segment: Int)

    Objective-C

    - (void)setLabel:(NSString *)label forSegment:(NSInteger)segment

    Parameters

    label

    The label you want to display in the segment. If the width of the string is greater than the width of the segment, the string's text is truncated during drawing.

    segment

    The index of the segment whose label you want to set. This method raises an NSRangeException if the index is out of bounds.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns the label of the specified segment.

    Declaration

    Swift

    func labelForSegment(_ segment: Int) -> String?

    Objective-C

    - (NSString *)labelForSegment:(NSInteger)segment

    Parameters

    segment

    The index of the segment whose label you want to get. This method raises an NSRangeException if the index is out of bounds.

    Return Value

    The label of the segment. The returned string contains the entire text of the label, even if that text is normally truncated during drawing.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Sets the menu for the specified segment.

    Declaration

    Swift

    func setMenu(_ menu: NSMenu?, forSegment segment: Int)

    Objective-C

    - (void)setMenu:(NSMenu *)menu forSegment:(NSInteger)segment

    Parameters

    menu

    The menu you want to add to the segment or nil to clear the current menu.

    segment

    The index of the segment whose menu you want to set. This method raises an NSRangeException if the index is out of bounds.

    Discussion

    Adding a menu to a segment allows that segment to be used as a pop-up button. Note that if the segment has only a menu, the menu is displayed when the user clicks the segment. If the segment has both a menu and an action, the action is triggered when the user clicks and the menu is displayed when the user clicks and holds.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns the menu for the specified segment.

    Declaration

    Swift

    func menuForSegment(_ segment: Int) -> NSMenu?

    Objective-C

    - (NSMenu *)menuForSegment:(NSInteger)segment

    Parameters

    segment

    The index of the segment whose menu you want to get. This method raises an NSRangeException if the index is out of bounds.

    Return Value

    The menu associated with the segment; otherwise, nil.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Sets the selection state of the specified segment.

    Declaration

    Swift

    func setSelected(_ flag: Bool, forSegment segment: Int)

    Objective-C

    - (void)setSelected:(BOOL)flag forSegment:(NSInteger)segment

    Parameters

    flag

    YEStrue if you want to select the segment; otherwise, NOfalse.

    segment

    The index of the segment whose selection state you want to set. This method raises an NSRangeException if the index is out of bounds.

    Discussion

    If the control allows only a single selection, this method deselects any other selected segments.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns a Boolean value indicating whether the specified segment is selected.

    Declaration

    Swift

    func isSelectedForSegment(_ segment: Int) -> Bool

    Objective-C

    - (BOOL)isSelectedForSegment:(NSInteger)segment

    Parameters

    segment

    The index of the segment whose selection state you want to get. This method raises an NSRangeException if the index is out of bounds.

    Return Value

    YEStrue if the segment is selected; otherwise, NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Sets the enabled state of the specified segment

    Declaration

    Swift

    func setEnabled(_ flag: Bool, forSegment segment: Int)

    Objective-C

    - (void)setEnabled:(BOOL)flag forSegment:(NSInteger)segment

    Parameters

    flag

    YEStrue to enable the segment; otherwise, NOfalse to disable it.

    segment

    The index of the segment you want to enable or disable. This method raises an NSRangeException if the index is out of bounds.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns a Boolean value indicating whether the specified segment is enabled.

    Declaration

    Swift

    func isEnabledForSegment(_ segment: Int) -> Bool

    Objective-C

    - (BOOL)isEnabledForSegment:(NSInteger)segment

    Parameters

    segment

    The index of the segment whose enabled state you want to get. This method raises an NSRangeException if the index is out of bounds.

    Return Value

    YEStrue if the segment is enabled; otherwise, NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • A Boolean value that indicates whether spring loading is enabled for the control.

    Declaration

    Swift

    var springLoaded: Bool

    Objective-C

    @property(getter=isSpringLoaded) BOOL springLoaded

    Discussion

    The value of this property is YEStrue if spring loading is enabled for the control, and NOfalse if it is not. The default is NOfalse.

    On pressure-sensitive systems, such as systems with the Force Touch trackpad, spring loading is a feature that allows a user to activate a segment in a segmented control by dragging selected items over it and force clicking—pressing harder—without dropping the selected items. The user can then continue dragging the items, possibly to perform additional actions.

    A practical example of this feature can be found in the Calendar app. A selected calendar event can be dragged over the day, week, month, or year segments in the toolbar. Force clicking on a segment switches the calendar view without releasing the selected event. The event can then be dropped at the desired location in the new calendar view.

    When spring loading is enabled on a segmented control and a user drags something over a segment, the segment highlights to indicate that it responds to force clicking. In this situation, if the user presses harder, additional highlighting occurs to indicate that the segment was activated.

    On systems that don’t support pressure sensitivity, simply hovering over the segment for a short period of time is sufficient to activate the segment.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10.3 and later.

  • The visual style used to display the control.

    Declaration

    Swift

    var segmentStyle: NSSegmentStyle

    Objective-C

    @property NSSegmentStyle segmentStyle

    Discussion

    An NSSegmentStyle value that specifies the visual display used by the control. For possible values, see NSSegmentStyle.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Sets the scaling mode used to display the specified segment’s image.

    Declaration

    Swift

    func setImageScaling(_ scaling: NSImageScaling, forSegment segment: Int)

    Objective-C

    - (void)setImageScaling:(NSImageScaling)scaling forSegment:(NSInteger)segment

    Parameters

    scaling

    One of the image scaling constants. For a list of possible values, see NSImageScaling.

    segment

    The index of the segment whose enabled state you want to get. This method raises an NSRangeException if the index is out of bounds.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the scaling mode used to display the specified segment’s image.

    Declaration

    Swift

    func imageScalingForSegment(_ segment: Int) -> NSImageScaling

    Objective-C

    - (NSImageScaling)imageScalingForSegment:(NSInteger)segment

    Parameters

    segment

    The index of the segment whose enabled state you want to get. This method raises an NSRangeException if the index is out of bounds.

    Return Value

    One of the image scaling constants. For a list of possible values, see NSImageScaling. The default value is NSImageScaleProportionallyDown.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • The following constants specify the type of tracking behavior a segmented control exhibits. They are used by trackingMode.

    Declaration

    Swift

    enum NSSegmentSwitchTracking : UInt { case SelectOne case SelectAny case Momentary case MomentaryAccelerator }

    Objective-C

    enum { NSSegmentSwitchTrackingSelectOne = 0, NSSegmentSwitchTrackingSelectAny = 1, NSSegmentSwitchTrackingMomentary = 2, NSSegmentSwitchTrackingMomentaryAccelerator = 3, }; typedef NSInteger NSSegmentSwitchTracking;

    Constants

    • SelectOne

      NSSegmentSwitchTrackingSelectOne

      Only one segment in the control can be selected at a time.

      This mode functions as a radio button and is illustrated by the view selection control in Finder, which allows you to toggle between icon view, list view, column view, and Cover Flow.

      Available in OS X v10.3 and later.

    • SelectAny

      NSSegmentSwitchTrackingSelectAny

      One or more segment cells in the control can be selected at a time.

      This mode functions as a set of checkboxes, where any combination of segments may be on or off, and is illustrated by the font format selection control in Pages, which allows you to apply bold, italics, and underline to the selected text.

      Available in OS X v10.3 and later.

    • Momentary

      NSSegmentSwitchTrackingMomentary

      A momentary segmented control sends an action when the user clicks a segment, and another action when the user releases the segment. If configured as continuous (see setContinuous:), the control also sends actions at repeating intervals until the user releases the segment, at which point the control sends its final action.

      When the user clicks a segment, the selectedSegment value is the index of the active segment. When the user releases the segment, the selectedSegment value is -1.

      This type of control is illustrated by the navigation segmented control in the Safari toolbar. When you click the back segment, for example, the previous webpage is displayed. This particular control is not configured as continuous. If it were, clicking and holding on the back segment would continue cycling through previous webpages until the segment is released.

      Available in OS X v10.3 and later.

    • MomentaryAccelerator

      NSSegmentSwitchTrackingMomentaryAccelerator

      On pressure-sensitive systems, when the user force clicks a segment, a momentary accelerator segmented control sends repeating actions as pressure changes occur. The control stops sending actions when the user releases pressure. A document-based app, for example, might implement a momentary accelerator segmented control in order to allow a user to adjust the speed of paging by using variable pressure. In this example, actions are sent to the app to indicate when pressure on the control has changed. The app then determines the amount of pressure currently applied, and adjusts navigation speed accordingly.

      When the control is configured as continuous (see setContinuous:), the interval between repeating actions automatically adjusts to match the applied pressure. As the user presses harder, actions are sent more rapidly. As the user reduces pressure, actions slow down. As such, the user has direct control over how fast actions are sent. Continuous momentary accelerator segmented controls are intended for continuously advancing through a series of discrete objects, such as photos in an album or pages in a book.

      When configured as noncontinuous, actions are sent whenever a change in pressure occurs. Noncontinuous momentary accelerator segmented controls are intended for adjusting the speed of navigation, such as playback speed in a media player, based on pressure. Once the control is released, a final action is sent.

      When the user force clicks a segment in the control, selectedSegment value is the index of the active segment, and doubleValueForSelectedSegment is a measurement of pressure between 1.0 and approaching 2.0. When the user releases pressure, selectedSegment value is -1 and doubleValueForSelectedSegment is 0.0.

      On a system that doesn’t support pressure sensitivity, a momentary accelerator segmented control control behaves like a control of type NSSegmentSwitchTrackingMomentary.

      Available in OS X v10.10.3 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • The following constants specify the visual style used to display the segmented control. They are used by segmentStyle.

    Declaration

    Swift

    enum NSSegmentStyle : Int { case Automatic case Rounded case RoundRect case TexturedSquare case SmallSquare case Separated case TexturedRounded case Capsule }

    Objective-C

    enum { NSSegmentStyleAutomatic = 0, NSSegmentStyleRounded = 1, NSSegmentStyleTexturedRounded = 2, NSSegmentStyleRoundRect = 3, NSSegmentStyleTexturedSquare = 4, NSSegmentStyleCapsule = 5, NSSegmentStyleSmallSquare = 6, NSSegmentStyleSeparated = 8, }; typedef NSInteger NSSegmentStyle;

    Constants

    • Automatic

      NSSegmentStyleAutomatic

      The appearance of the segmented control is automatically determined based on the type of window in which the control is displayed and the position within the window.

      Available in OS X v10.5 and later.

    • Rounded

      NSSegmentStyleRounded

      The control is displayed using the rounded style.

      Available in OS X v10.5 and later.

    • TexturedRounded

      NSSegmentStyleTexturedRounded

      The control is displayed using the textured rounded style. In OS X v10.7 and later, this style uses the artwork defined for NSSegmentStyleTexturedSquare, so you should specify NSSegmentStyleTexturedSquare instead.

      Available in OS X v10.5 and later.

    • RoundRect

      NSSegmentStyleRoundRect

      The control is displayed using the round rect style.

      Available in OS X v10.5 and later.

    • TexturedSquare

      NSSegmentStyleTexturedSquare

      The control is displayed using the textured square style.

      Available in OS X v10.5 and later.

    • Capsule

      NSSegmentStyleCapsule

      The control is displayed using the capsule style. In OS X v10.7 and later, this style uses the artwork defined for NSSegmentStyleTexturedSquare, so you should specify NSSegmentStyleTexturedSquare instead.

      Available in OS X v10.5 and later.

    • SmallSquare

      NSSegmentStyleSmallSquare

      The control is displayed using the small square style.

      Available in OS X v10.5 and later.

    • Separated

      NSSegmentStyleSeparated

      The segments in the control are displayed very close to each other but not touching. For example, Safari in OS X v10.10 and later uses this style for the previous and next page segmented control.

      Available in OS X v10.10 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.