Mac Developer Library

Developer

AppKit Framework Reference NSString Application Kit Additions Reference

Options
Deployment Target:

On This Page
Language:

NSString

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.

The Application Kit adds three methods to the NSString class to support drawing string objects directly in an NSView instance: drawAtPoint:withAttributes:, drawInRect:withAttributes:, and sizeWithAttributes:.

The Application Kit adds similar methods to the NSAttributedString class, described in NSAttributedString AppKit Additions Reference. The two drawing methods draw a string object with a single set of attributes that apply to the entire string. To draw a string with multiple attributes, such as multiple text fonts, you must use an attributed string.

  • Draws the receiver with the font and other display characteristics of the given attributes, at the specified point in the currently focused view.

    Declaration

    Swift

    func drawAtPoint(_ aPoint: NSPoint, withAttributes attributes: [NSObject : AnyObject]?)

    Objective-C

    - (void)drawAtPoint:(NSPoint)aPoint withAttributes:(NSDictionary *)attributes

    Parameters

    aPoint

    The origin for the bounding box for drawing the string. If the focused view is flipped, the origin is the upper-left corner of the drawing bounding box; otherwise, the origin is the lower-left corner.

    attributes

    A dictionary of text attributes to be applied to the string. These are the same attributes that can be applied to an NSAttributedString object, but in the case of NSString objects, the attributes apply to the entire string, rather than ranges within the string.

    Discussion

    The width (height for vertical layout) of the rendering area is unlimited, unlike drawInRect:withAttributes:, which uses a bounding rectangle. As a result, this method renders the text in a single line.

    You should only invoke this method when an NSView object has focus.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Draws the receiver with the font and other display characteristics of the given attributes, within the specified rectangle in the currently focused NSView.

    Declaration

    Swift

    func drawInRect(_ aRect: NSRect, withAttributes attributes: [NSObject : AnyObject]?)

    Objective-C

    - (void)drawInRect:(NSRect)aRect withAttributes:(NSDictionary *)attributes

    Parameters

    aRect

    The rectangle in which to draw the string.

    attributes

    A dictionary of text attributes to be applied to the string. These are the same attributes that can be applied to an NSAttributedString object, but in the case of NSString objects, the attributes apply to the entire string, rather than ranges within the string.

    Discussion

    The rendering area is bounded by aRect, unlike drawAtPoint:withAttributes:, which has an unlimited width. As a result, this method renders the text in multiple lines.

    You should only invoke this method when an NSView object has focus.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Draws the receiver with the specified options and other display characteristics of the given attributes, within the specified rectangle in the current graphics context.

    Declaration

    Swift

    func drawWithRect(_ rect: NSRect, options options: NSStringDrawingOptions, attributes attributes: [NSObject : AnyObject]?)

    Objective-C

    - (void)drawWithRect:(NSRect)rect options:(NSStringDrawingOptions)options attributes:(NSDictionary *)attributes

    Parameters

    rect

    The rectangle in which to draw the string.

    options

    String drawing options.

    attributes

    A dictionary of text attributes to be applied to the string. These are the same attributes that can be applied to an NSAttributedString object, but in the case of NSString objects, the attributes apply to the entire string, rather than ranges within the string.

    Discussion

    This method works in single-line, baseline rendering configuration by default. That is, the rect argument's origin field specifies the rendering origin, and that point is interpreted as the baseline origin by default. If the string drawing option NSStringDrawingUsesLineFragmentOrigin is specified, origin is interpreted as the upper left corner of the line fragment rectangle, and the method behaves in multiline configuration.

    The size field specifies the text container size. The width part of the size field specifies the maximum line fragment width if larger than 0.0. The height defines the maximum size that can be occupied with text if larger than 0.0 and NSStringDrawingUsesLineFragmentOrigin is specified. If NSStringDrawingUsesLineFragmentOrigin is not specified, height is ignored and considered to be single-line rendering (NSLineBreakByWordWrapping and NSLineBreakByCharWrapping are treated as NSLineBreakByClipping).

    You should only invoke this method when there is a current graphics context.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns the bounding box size the receiver occupies when drawn with the given attributes.

    Declaration

    Swift

    func sizeWithAttributes(_ attributes: [NSObject : AnyObject]?) -> NSSize

    Objective-C

    - (NSSize)sizeWithAttributes:(NSDictionary *)attributes

    Parameters

    attributes

    A dictionary of text attributes to be applied to the string. These are the same attributes that can be applied to an NSAttributedString object, but in the case of NSString objects, the attributes apply to the entire string, rather than ranges within the string.

    Return Value

    The bounding box size the receiver occupies when drawn with attributes.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Calculates and returns the bounding rect for the receiver drawn using the given options and display characteristics, within the specified rectangle in the current graphics context.

    Declaration

    Swift

    func boundingRectWithSize(_ size: NSSize, options options: NSStringDrawingOptions, attributes attributes: [NSObject : AnyObject]?) -> NSRect

    Objective-C

    - (NSRect)boundingRectWithSize:(NSSize)size options:(NSStringDrawingOptions)options attributes:(NSDictionary *)attributes

    Parameters

    size

    The size of the rectangle to draw in.

    options

    String drawing options.

    attributes

    A dictionary of text attributes to be applied to the string. These are the same attributes that can be applied to an NSAttributedString object, but in the case of NSString objects, the attributes apply to the entire string, rather than ranges within the string.

    Return Value

    The bounding rect for the receiver drawn using the given options and display characteristics. The rect origin returned from this method is the first glyph origin.

    Special Considerations

    This method works in single-line, baseline rendering configuration by default. If the string drawing option NSStringDrawingUsesLineFragmentOrigin is specified, the method behaves in multiline configuration.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • The following constants are provided as rendering options for a string when it is drawn.

    Declaration

    Swift

    struct NSStringDrawingOptions : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var TruncatesLastVisibleLine: NSStringDrawingOptions { get } static var UsesLineFragmentOrigin: NSStringDrawingOptions { get } static var UsesFontLeading: NSStringDrawingOptions { get } static var DisableScreenFontSubstitution: NSStringDrawingOptions { get } static var UsesDeviceMetrics: NSStringDrawingOptions { get } static var OneShot: NSStringDrawingOptions { get } }

    Objective-C

    enum { NSStringDrawingUsesLineFragmentOrigin = (1 << 0), NSStringDrawingUsesFontLeading = (1 << 1), NSStringDrawingDisableScreenFontSubstitution = (1 << 2), NSStringDrawingUsesDeviceMetrics = (1 << 3), NSStringDrawingOneShot = (1 << 4), NSStringDrawingTruncatesLastVisibleLine = (1 << 5) }; typedef NSInteger NSStringDrawingOptions;

    Constants

    • UsesLineFragmentOrigin

      NSStringDrawingUsesLineFragmentOrigin

      The specified origin is the line fragment origin, not the baseline origin.

      Available in OS X v10.4 and later.

    • UsesFontLeading

      NSStringDrawingUsesFontLeading

      Uses the font leading for calculating line heights.

      Available in OS X v10.4 and later.

    • DisableScreenFontSubstitution

      NSStringDrawingDisableScreenFontSubstitution

      Disable screen font substitution (equivalent to [NSLayoutManager setUsesScreenFonts:NO]).

      Available in OS X v10.4 and later.

    • UsesDeviceMetrics

      NSStringDrawingUsesDeviceMetrics

      Uses image glyph bounds instead of typographic bounds.

      Available in OS X v10.4 and later.

    • OneShot

      NSStringDrawingOneShot

      Suppresses caching layout information.

      Available in OS X v10.4 and later.

    • TruncatesLastVisibleLine

      NSStringDrawingTruncatesLastVisibleLine

      Truncates and adds the ellipsis character to the last visible line if the text doesn't fit into the bounds specified.

      This option is ignored if NSStringDrawingUsesLineFragmentOrigin is not also set. In addition, the line break mode must be either NSLineBreakByWordWrapping or NSLineBreakByCharWrapping for this option to take effect. The line break mode can be specified in a paragraph style passed in the attributes dictionary argument of the drawing methods.

      Available in OS X v10.5 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.