Mac Developer Library

Developer

AppKit Framework Reference NSBox Class Reference

Options
Deployment Target:

On This Page
Language:

NSBox

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 contentView, 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.

  • The rectangle in which the receiver’s border is drawn. (read-only)

    Declaration

    Swift

    var borderRect: NSRect { get }

    Objective-C

    @property(readonly) NSRect borderRect

    Availability

    Available in OS X v10.0 and later.

  • The receiver’s box type.

    Declaration

    Swift

    var boxType: NSBoxType

    Objective-C

    @property NSBoxType boxType

    Discussion

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

    Availability

    Available in OS X v10.0 and later.

  • The receiver’s border type.

    Declaration

    Swift

    var borderType: NSBorderType

    Objective-C

    @property NSBorderType borderType

    Discussion

    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.

    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.

    Availability

    Available in OS X v10.0 and later.

  • A Boolean value that indicates whether the receiver is transparent.

    Declaration

    Swift

    var transparent: Bool

    Objective-C

    @property(getter=isTransparent) BOOL transparent

    Discussion

    YEStrue when the receiver is transparent, NOfalse otherwise.

    Availability

    Available in OS X v10.5 and later.

  • The receiver’s title.

    Declaration

    Swift

    var title: String

    Objective-C

    @property(copy) NSString *title

    Discussion

    The title of the NSBox. By default, a box’s title 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.

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var titleFont: NSFont

    Objective-C

    @property(strong) NSFont *titleFont

    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.

    Availability

    Available in OS X v10.0 and later.

  • A constant representing the title position.

    Declaration

    Swift

    var titlePosition: NSTitlePosition

    Objective-C

    @property NSTitlePosition titlePosition

    Discussion

    A constant representing the position of the receiver's title. See NSTitlePosition for a list of these constants. 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.

    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.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

    See Also

    – setTitleWithMnemonic: (NSCell)

  • The cell used to display the receiver’s title. (read-only)

    Declaration

    Swift

    var titleCell: AnyObject { get }

    Objective-C

    @property(readonly, strong) id titleCell

    Availability

    Available in OS X v10.0 and later.

  • The rectangle in which the receiver’s title is drawn. (read-only)

    Declaration

    Swift

    var titleRect: NSRect { get }

    Objective-C

    @property(readonly) NSRect titleRect

    Availability

    Available in OS X v10.0 and later.

  • 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

    Discussion

    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.

    Special Considerations

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

    Availability

    Available in OS X v10.5 and later.

  • 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

    Discussion

    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.

    Special Considerations

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

    Availability

    Available in OS X v10.5 and later.

  • 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

    Discussion

    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.

    Special Considerations

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

    Availability

    Available in OS X v10.5 and later.

  • 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

    Discussion

    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.

    Special Considerations

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

    Availability

    Available in OS X v10.5 and later.

  • The receiver’s content view.

    Declaration

    Swift

    unowned(unsafe) var contentView: NSView?

    Objective-C

    @property(assign) __kindof NSView *contentView

    Discussion

    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.

    Availability

    Available in OS X v10.0 and later.

  • The distances between the border and the content view.

    Declaration

    Swift

    var contentViewMargins: NSSize

    Objective-C

    @property NSSize contentViewMargins

    Discussion

    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.

    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.

    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.

    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.

    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.