Mac Developer Library

Developer

AppKit Framework Reference NSSegmentedControl Class Reference

Options
Deployment Target:

On This Page
Language:

NSSegmentedControl

Inheritance


Conforms To


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 three tracking modes for segments: select one mode (also known as radio button mode and illustrated by Finder’s view mode selection control), momentary mode (as illustrated by Safari’s toolbar buttons), or select any mode (where any combination of buttons may be on or off)

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

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