Mac Developer Library

Developer

AppKit Framework Reference NSSegmentedControl Class Reference

Options
Deployment Target:

On This Page
Language:

NSSegmentedControl

Inheritance


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.3 and later.

An NSSegmentedControl object implements a horizontal button made of multiple segments.

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:

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

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

  • There are four tracking modes for segmented controls:

    1. Select one 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

    2. Select any 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

    3. Momentary mode—where the segment activates when pressed and deactivates when released, as illustrated by the toolbar buttons in Safari

    4. Momentary accelerator mode—where the segment activates when pressed, sends timed or pressure-based (on systems that support pressure sensitivity) actions, and deactivates when released.

  • 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

  • Full keyboard control of the user interface

  • The number of segments in the receiver.

    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 receiver or -1 if no segment is selected.

    Declaration

    Swift

    var selectedSegment: Int

    Objective-C

    @property NSInteger selectedSegment

    Discussion

    If the receiver 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.

    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 receiver 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.

    Spring loading is a feature that allows a user to activate a segment in a segmented control by dragging something over it and force clicking—pressing harder. 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 receiver.

    Declaration

    Swift

    var segmentStyle: NSSegmentStyle

    Objective-C

    @property NSSegmentStyle segmentStyle

    Discussion

    An NSSegmentStyle value that specifies the visual display used by the receiver. 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 segment will activate when pressed and deactivate when released. A momentary segmented control sends an action when first pressed and another action when released. If configured as continuous (see setContinuous:), it also sends actions at repeating intervals until released, at which point it sends its final action.

      While pressed, its selectedSegment value is the index of the active segment. When released, its selectedSegment value is -1.

      This type of button is illustrated by the toolbar buttons in Safari.

      Available in OS X v10.3 and later.

    • MomentaryAccelerator

      NSSegmentSwitchTrackingMomentaryAccelerator

      While pushed, a momentary accelerator segmented control sends repeating actions as pressure changes occur. It stops sending actions when released. A document-based app, for example, might implement a momentary accelerator segmented control in order to allow a user to adjust the speed of flipping through pages with variable pressure. Actions would be sent to the app to indicate when pressure on the control has changed. The app would then determine the amount of pressure currently applied, and adjust navigation speed accordingly.

      A momentary accelerator segmented control sends an action when first pressed and then continues sending actions until released.

      When 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.

      While pressed, selectedSegment value is the index of the active segment and doubleValueForSelectedSegment is a measurement of pressure between 1.0 and approaching 2.0. When released, selectedSegment value is -1 and doubleValueForSelectedSegment is 0.0.

      The behavior of this control type is reliant on a system that supports pressure sensitivity. 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.