Mac Developer Library

Developer

AppKit Framework Reference NSBox Class Reference

Options
Deployment Target:

On This Page
Language:

NSBox

Conforms To


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.

The NSBox class implements simple views that can title themselves and draw a border around their content. These objects are known as boxes. You can use box to group, visually, some number of other views.

Subclassing Notes

An NSBox object is a view that draws a line around its rectangular bounds and that displays a title on or near the line (or might display neither line nor title). You can adjust the style of the line (bezel, grooved, or plain) as well as the placement and font of the title. An NSBox also has a content view to which other views can be added; it thus offers a way for an application to group related views. You could create a custom subclass of NSBox that alters or augments its appearance or that modifies its grouping behavior. For example, you might add color to the lines or background, add a new line style, or have the views in the group automatically snap to an invisible grid when added.

Methods to Override

You must override the drawRect: method (inherited from NSView) if you want to customize the appearance of your NSBox objects. Depending on the visual effect you’re trying to achieve, you may have to invoke super’s implementation first. For example, if you are compositing a small image in a corner of the box, you would invoke the superclass implementation first. If you’re adding a new style of line, you would provide a way to store a request for this line type (such as a boolean instance variable and related accessor methods). Then, in drawRect:, if a request for this line type exists, you would draw the entire view yourself (that is, without calling super). Otherwise, you would invoke the superclass implementation.

If you wish to change grouping behavior or other behavioral characteristics of the NSBox class, consider overriding setContentView:, sizeToFit, or addSubview: (inherited from NSView).

Special Considerations

If you are drawing the custom NSBox entirely by yourself, and you want it to look exactly like the superclass object (except for your changes), it may take some effort and time to get the details right.

  • Returns the rectangle in which the receiver’s border is drawn.

    Declaration

    Swift

    var borderRect: NSRect { get }

    Objective-C

    @property(readonly) NSRect borderRect

    Return Value

    The rectangle in which the border of the NSBox is drawn.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the receiver’s box type.

    Declaration

    Swift

    var boxType: NSBoxType

    Objective-C

    @property NSBoxType boxType

    Return Value

    A constant describing the type of box. These constants are described in NSBoxType. By default, the box type of an NSBox is NSBoxPrimary.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – setBoxType:

  • Sets the box type.

    Declaration

    Swift

    var boxType: NSBoxType

    Objective-C

    @property NSBoxType boxType

    Parameters

    boxType

    A constant describing the type of box; this must be a valid box type. These constants are described in NSBoxType.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – boxType

  • Returns the receiver’s border type.

    Declaration

    Swift

    var borderType: NSBorderType

    Objective-C

    @property NSBorderType borderType

    Return Value

    A constant describing the type of border. Border types are defined in NSView.h. Currently, the following border types are defined: NSNoBorder,NSLineBorder,NSBezelBorder, NSGrooveBorder.

    By default, the border type of an NSBox is NSGrooveBorder.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the border type to aType, which must be a valid border type.

    Declaration

    Swift

    var borderType: NSBorderType

    Objective-C

    @property NSBorderType borderType

    Parameters

    aType

    A constant describing the type of border. Border types are defined in NSView.h. Currently, the following border types are defined: NSNoBorder,NSLineBorder,NSBezelBorder, NSGrooveBorder.

    Discussion

    If the size of the new border is different from that of the old border, the content view is resized to absorb the difference, and the box is marked for redisplay.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • isTransparent - isTransparent Available in OS X v10.5 through OS X v10.9

    Indicates whether the receiver is transparent.

    Declaration

    Objective-C

    - (BOOL)isTransparent

    Return Value

    YEStrue when the receiver is transparent, NOfalse otherwise.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.5 through OS X v10.9.

  • Specifies whether the receiver is transparent.

    Declaration

    Swift

    var transparent: Bool

    Objective-C

    @property(getter=isTransparent) BOOL transparent

    Parameters

    transparent

    YEStrue makes the receiver transparent.

    NOfalse makes the receiver opaque.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the receiver’s title.

    Declaration

    Swift

    var title: String

    Objective-C

    @property(copy) NSString *title

    Return Value

    The title of the NSBox. By default, a box’s title is “Title.”

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – setTitle:

  • Sets the title of the box and marks the region of the receiver within the title rectangle as needing display.

    Declaration

    Swift

    var title: String

    Objective-C

    @property(copy) NSString *title

    Parameters

    aString

    The new title of the NSBox. The default title of an NSBox is “Title.” If the size of the new title is different from that of the old title, the content view is resized to absorb the difference.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the font object used to draw the receiver’s title.

    Declaration

    Swift

    var titleFont: NSFont

    Objective-C

    @property(strong) NSFont *titleFont

    Return Value

    The NSFont object used to draw the title.

    Discussion

    By default, the title is drawn using the small system font (obtained using (smallSystemFontSize as the parameter of systemFontOfSize:, both NSFont class methods).

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the font object used to draw the receiver’s title and marks the region of the receiver within the title rectangle as needing display.

    Declaration

    Swift

    var titleFont: NSFont

    Objective-C

    @property(strong) NSFont *titleFont

    Parameters

    aFont

    The NSFont object used to draw the box's title.

    Discussion

    By default, the title is drawn using the small system font (obtained using (smallSystemFontSize as the parameter of systemFontOfSize:, both NSFont class methods). If the size of the new font is different from that of the old font, the content view is resized to absorb the difference.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns a constant representing the title position.

    Declaration

    Swift

    var titlePosition: NSTitlePosition

    Objective-C

    @property NSTitlePosition titlePosition

    Return Value

    A constant representing the position of the receiver's title. See NSTitlePosition for a list of these constants.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the position of the box's title.

    Declaration

    Swift

    var titlePosition: NSTitlePosition

    Objective-C

    @property NSTitlePosition titlePosition

    Parameters

    aPosition

    A constant describing the position of the box's title. These constants are described in NSTitlePosition. The default position is NSAtTop.

    Discussion

    If the new title position changes the size of the box’s border area, the content view is resized to absorb the difference, and the box is marked as needing redisplay.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the title of the receiver with a character denoted as an access key.

    Declaration

    Objective-C

    - (void)setTitleWithMnemonic:(NSString *)stringWithAmpersand

    Discussion

    Mnemonics are not supported in OS X.

    By default, a box’s title is “Title.” The content view is not automatically resized, and the box is not marked for redisplay.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

    See Also

    – setTitleWithMnemonic: (NSCell)

  • Returns the cell used to display the receiver’s title.

    Declaration

    Swift

    var titleCell: AnyObject { get }

    Objective-C

    @property(readonly, strong) id titleCell

    Return Value

    The NSCell object used to display the title.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the rectangle in which the receiver’s title is drawn.

    Declaration

    Swift

    var titleRect: NSRect { get }

    Objective-C

    @property(readonly) NSRect titleRect

    Return Value

    The rectangle in which the title is drawn.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the color of the receiver’s border when the receiver is a custom box with a simple line border.

    Declaration

    Swift

    @NSCopying var borderColor: NSColor

    Objective-C

    @property(copy) NSColor *borderColor

    Return Value

    The receiver’s border color. It must be a custom box—that is, it has a type of NSBoxCustom—and it must have a border style of NSLineBorder.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Specifies the receiver’s border color.

    Declaration

    Swift

    @NSCopying var borderColor: NSColor

    Objective-C

    @property(copy) NSColor *borderColor

    Parameters

    borderColor

    Border color for the receiver.

    Special Considerations

    Functional only when the receiver’s box type (boxType) is NSBoxCustom and its border type (borderType) is NSLineBorder.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

    See Also

    – borderColor

  • Returns the width of the receiver’s border when the receiver is a custom box with a simple line border.

    Declaration

    Swift

    var borderWidth: CGFloat

    Objective-C

    @property CGFloat borderWidth

    Return Value

    The receiver’s border width. It must be a custom box—that is, it has a type of NSBoxCustom—and it must have a border style of NSLineBorder.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Specifies the receiver’s border width.

    Declaration

    Swift

    var borderWidth: CGFloat

    Objective-C

    @property CGFloat borderWidth

    Parameters

    borderWidth

    Border width for the receiver.

    Special Considerations

    Functional only when the receiver’s box type (boxType) is NSBoxCustom and its border type (borderType) is NSLineBorder.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

    See Also

    – borderWidth

  • Returns the radius of the receiver’s corners when the receiver is a custom box with a simple line border.

    Declaration

    Swift

    var cornerRadius: CGFloat

    Objective-C

    @property CGFloat cornerRadius

    Return Value

    The receiver’s corner radius. It must be a custom box—that is, it has a type of NSBoxCustom—and it must have a border style of NSLineBorder.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Specifies the receiver’s corner radius.

    Declaration

    Swift

    var cornerRadius: CGFloat

    Objective-C

    @property CGFloat cornerRadius

    Parameters

    cornerRadius

    Corner radius for the receiver.

    Special Considerations

    Functional only when the receiver’s box type (boxType) is NSBoxCustom and its border type (borderType) is NSLineBorder.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the color of the receiver’s background when the receiver is a custom box with a simple line border.

    Declaration

    Swift

    @NSCopying var fillColor: NSColor

    Objective-C

    @property(copy) NSColor *fillColor

    Return Value

    The receiver’s fill color. It must be a custom box—that is, it has a type of NSBoxCustom—and it must have a border style of NSLineBorder.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Specifies the receiver’s fill color.

    Declaration

    Swift

    @NSCopying var fillColor: NSColor

    Objective-C

    @property(copy) NSColor *fillColor

    Parameters

    fillColor

    Fill color for the receiver.

    Special Considerations

    Functional only when the receiver’s box type (boxType) is NSBoxCustom and its border type (borderType) is NSLineBorder.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

    See Also

    – fillColor

  • Returns the receiver’s content view.

    Declaration

    Swift

    unowned(unsafe) var contentView: AnyObject?

    Objective-C

    @property(assign) id contentView

    Return Value

    The content view of the NSBox object. The content view is created automatically when the box is created and resized as the box is resized (you should never send frame-altering messages directly to a box’s content view). You can replace it with an NSView of your own through the setContentView: method.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the receiver’s content view.

    Declaration

    Swift

    unowned(unsafe) var contentView: AnyObject?

    Objective-C

    @property(assign) id contentView

    Parameters

    aView

    The new content view. The NSView object is resized to fit within the box’s current content area and the box is marked for redisplay.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the distances between the border and the content view.

    Declaration

    Swift

    var contentViewMargins: NSSize

    Objective-C

    @property NSSize contentViewMargins

    Return Value

    The width (the horizontal distance between the innermost edge of the border and the content view) and height (the vertical distance between the innermost edge of the border and the content view) describing the distance between the border and the content view. By default, these are both 5.0 in the box's coordinate system.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the horizontal and vertical distance between the border of the receiver and its content view.

    Declaration

    Swift

    var contentViewMargins: NSSize

    Objective-C

    @property NSSize contentViewMargins

    Parameters

    offsetSize

    The width and height of the offset between the box's border and content view. The horizontal value is applied (reckoned in the box’s coordinate system) fully and equally to the left and right sides of the box. The vertical value is similarly applied to the top and bottom.

    Discussion

    Unlike changing a box’s other attributes, such as its title position or border type, changing the offsets doesn’t automatically resize the content view. In general, you should send a sizeToFit message to the box after changing the size of its offsets. This message causes the content view to remain unchanged while the box is sized to fit around it.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Places the receiver so its content view lies on the specified frame.

    Declaration

    Swift

    func setFrameFromContentFrame(_ contentFrame: NSRect)

    Objective-C

    - (void)setFrameFromContentFrame:(NSRect)contentFrame

    Parameters

    contentFrame

    The rectangle specifying the frame of the box's content view, reckoned in the coordinate system of the box's superview. The box is marked for redisplay.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Resizes and moves the receiver’s content view so it just encloses its subviews.

    Declaration

    Swift

    func sizeToFit()

    Objective-C

    - (void)sizeToFit

    Discussion

    The receiver is then moved and resized to wrap around the content view. The receiver’s width is constrained so its title will be fully displayed.

    You should invoke this method after:

    • Adding a subview (to the content view)

    • Altering the size or location of such a subview

    • Setting the margins around the content view

    The mechanism by which the content view is moved and resized depends on whether the object responds to its own sizeToFit message: If it does respond, then that message is sent, and the content view is expected to be so modified. If the content view doesn’t respond, the box moves and resizes the content view itself.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

Data Types

  • Specify the location of a box’s title with respect to its border.

    Declaration

    Swift

    enum NSTitlePosition : UInt { case NoTitle case AboveTop case AtTop case BelowTop case AboveBottom case AtBottom case BelowBottom }

    Objective-C

    typedef enum _NSTitlePosition { NSNoTitle = 0, NSAboveTop = 1, NSAtTop = 2, NSBelowTop = 3, NSAboveBottom = 4, NSAtBottom = 5, NSBelowBottom = 6 } NSTitlePosition;

    Constants

    • NoTitle

      NSNoTitle

      The box has no title.

      Available in OS X v10.0 and later.

    • AboveTop

      NSAboveTop

      Title positioned above the box’s top border.

      Available in OS X v10.0 and later.

    • AtTop

      NSAtTop

      Title positioned within the box’s top border.

      Available in OS X v10.0 and later.

    • BelowTop

      NSBelowTop

      Title positioned below the box’s top border.

      Available in OS X v10.0 and later.

    • AboveBottom

      NSAboveBottom

      Title positioned above the box’s bottom border.

      Available in OS X v10.0 and later.

    • AtBottom

      NSAtBottom

      Title positioned within the box’s bottom border.

      Available in OS X v10.0 and later.

    • BelowBottom

      NSBelowBottom

      Title positioned below the box’s bottom border.

      Available in OS X v10.0 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • These constants and data type identifies box types, which, in conjunction with a box's border type, define the appearance of the box.

    Declaration

    Swift

    enum NSBoxType : UInt { case Primary case Secondary case Separator case OldStyle case Custom }

    Objective-C

    enum { NSBoxPrimary = 0, NSBoxSecondary = 1, NSBoxSeparator = 2, NSBoxOldStyle = 3, NSBoxCustom = 4 }; typedef NSUInteger NSBoxType;

    Constants

    • Primary

      NSBoxPrimary

      Specifies the primary box appearance. This is the default box type.

      Available in OS X v10.0 and later.

    • Secondary

      NSBoxSecondary

      Specifies the secondary box appearance.

      Available in OS X v10.0 and later.

    • Separator

      NSBoxSeparator

      Specifies that the box is a separator.

      Available in OS X v10.0 and later.

    • OldStyle

      NSBoxOldStyle

      Specifies that the box is an OS X v10.2–style box.

      Available in OS X v10.0 and later.

    • Custom

      NSBoxCustom

      Specifies that the appearance of the box is determined entirely by the by box-configuration methods, without automatically applying Apple human interface guidelines. See “Customizing” for details.

      Available in OS X v10.5 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.