Mac Developer Library

Developer

Foundation Framework Reference NSAttributedString Class Reference

Options
Deployment Target:

On This Page
Language:

NSAttributedString

An NSAttributedString object manages character strings and associated sets of attributes (for example, font and kerning) that apply to individual characters or ranges of characters in the string. An association of characters and their attributes is called an attributed string. The cluster’s two public classes, NSAttributedString and NSMutableAttributedString, declare the programmatic interface for read-only attributed strings and modifiable attributed strings, respectively.

An attributed string identifies attributes by name, using an NSDictionary object to store a value under the given name. You can assign any attribute name/value pair you wish to a range of characters—it is up to your application to interpret custom attributes (see Attributed String Programming Guide). If you are using attributed strings with the Core Text framework, you can also use the attribute keys defined by that framework.

You use attributed strings with any APIs that accept them, such as Core Text. The AppKit and UIKit frameworks also provide a subclass of NSMutableAttributedString, called NSTextStorage, to provide the storage for the extended text-handling system. In iOS 6 and later you can use attributed strings to display formatted text in text views, text fields, and some other controls. Both AppKit and UIKit also define extensions to the basic attributed string interface that allows you to draw their contents in the current graphic context.

The default font for NSAttributedString objects is Helvetica 12-point, which may differ from the default system font for the platform. Thus, you might want to create new strings with non-default attributes suitable for your application. You can also use the NSParagraphStyle class and its subclass NSMutableParagraphStyle to encapsulate the paragraph or ruler attributes used by the NSAttributedString classes.

Be aware that comparisons of NSAttributedString objects using the isEqual: method look for exact equality. The comparison includes both a character-by-character string equality check and an equality check of all attributes. Such a comparison is not likely to yield a match if the string has many attributes, such as attachments, lists, and tables, for example.

The NSAttributedString class is “toll-free bridged” with its Core Foundation counterpart, CFAttributedStringRef. See Toll-Free Bridging for more information.

  • Returns an NSAttributedString object initialized with the characters of a given string and no attribute information.

    Declaration

    Swift

    init(string str: String)

    Objective-C

    - (instancetype)initWithString:(NSString *)aString

    Parameters

    aString

    The characters for the new object.

    Return Value

    An NSAttributedString object initialized with the characters of aString and no attribute information The returned object might be different than the original receiver.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns an NSAttributedString object initialized with a given string and attributes.

    Declaration

    Swift

    init(string str: String, attributes attrs: [String : AnyObject]?)

    Objective-C

    - (instancetype)initWithString:(NSString *)aString attributes:(NSDictionary<NSString *,id> *)attributes

    Parameters

    aString

    The string for the new attributed string.

    attributes

    The attributes for the new attributed string. For a list of attributes that you can include in this dictionary, see Character Attributes.

    Discussion

    Returns an NSAttributedString object initialized with the characters of aString and the attributes of attributes. The returned object might be different from the original receiver.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns an NSAttributedString object initialized with the characters and attributes of another given attributed string.

    Declaration

    Swift

    init(attributedString attrStr: NSAttributedString)

    Objective-C

    - (instancetype)initWithAttributedString:(NSAttributedString *)attributedString

    Parameters

    attributedString

    An attributed string.

    Return Value

    An NSAttributedString object initialized with the characters and attributes of attributedString. The returned object might be different than the original receiver.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Initializes and returns a new attributed string object from the data contained in the given data object.

    Declaration

    Swift

    init(data data: NSData, options options: [String : AnyObject], documentAttributes dict: AutoreleasingUnsafeMutablePointer<NSDictionary?>) throws

    Objective-C

    - (instancetype)initWithData:(NSData *)data options:(NSDictionary<NSString *,id> *)options documentAttributes:(NSDictionary<NSString *,id> * _Nullable *)dict error:(NSError * _Nullable *)error

    Parameters

    data

    The data from which to create the string.

    options

    Document attributes for interpreting the document contents. NSDocumentTypeDocumentAttribute, NSCharacterEncodingDocumentAttribute, and NSDefaultAttributesDocumentAttribute are supported option keys. If you pass an empty dictionary, the method examines the data to attempt to determine the appropriate attributes.

    dict

    An in-out dictionary containing document-level attributes described in Document Attributes. May be NULL, in which case no document attributes are returned.

    error

    An in-out variable containing an encountered error, if any.

    Return Value

    Returns an initialized attributed string object, or nil if the data can’t be decoded.

    Discussion

    The HTML importer should not be called from a background thread (that is, the options dictionary includes NSDocumentTypeDocumentAttribute with a value of NSHTMLTextDocumentType). It will try to synchronize with the main thread, fail, and time out. Calling it from the main thread works (but can still time out if the HTML contains references to external resources, which should be avoided at all costs). The HTML import mechanism is meant for implementing something like markdown (that is, text styles, colors, and so on), not for general HTML import.

    Availability

    Available in OS X v10.0 and later.

  • Initializes and returns a new NSAttributedString object from Microsoft Word format data contained in the given NSData object.

    Declaration

    Swift

    init?(docFormat data: NSData, documentAttributes dict: AutoreleasingUnsafeMutablePointer<NSDictionary?>)

    Objective-C

    - (instancetype)initWithDocFormat:(NSData *)data documentAttributes:(NSDictionary<NSString *,id> * _Nullable *)docAttributes

    Parameters

    data

    The data from which to create the string.

    docAttributes

    An in-out dictionary containing document-level attributes described in Document Attributes. May be NULL, in which case no document attributes are returned.

    Return Value

    Returns an initialized object, or nil if the data can’t be decoded.

    Availability

    Available in OS X v10.3 and later.

  • Initializes and returns a new NSAttributedString object from HTML contained in the given data object.

    Declaration

    Swift

    init?(HTML data: NSData, documentAttributes dict: AutoreleasingUnsafeMutablePointer<NSDictionary?>)

    Objective-C

    - (instancetype)initWithHTML:(NSData *)data documentAttributes:(NSDictionary<NSString *,id> * _Nullable *)docAttributes

    Parameters

    data

    The data in HTML format from which to create the attributed string.

    docAttributes

    An in-out dictionary containing document-level attributes described in Document Attributes. May be NULL, in which case no document attributes are returned.

    Return Value

    Returns an initialized object, or nil if the data can’t be decoded.

    Availability

    Available in OS X v10.0 and later.

  • Initializes and returns a new NSAttributedString object from the HTML contained in the given object and base URL.

    Declaration

    Swift

    init?(HTML data: NSData, baseURL base: NSURL, documentAttributes dict: AutoreleasingUnsafeMutablePointer<NSDictionary?>)

    Objective-C

    - (instancetype)initWithHTML:(NSData *)data baseURL:(NSURL *)aURL documentAttributes:(NSDictionary<NSString *,id> * _Nullable *)docAttributes

    Parameters

    data

    The data in HTML format from which to create the attributed string.

    aURL

    An NSURL that represents the base URL for all links within the HTML.

    docAttributes

    An in-out dictionary containing document-level attributes described in Document Attributes. May be NULL, in which case no document attributes are returned.

    Return Value

    Returns an initialized object, or nil if the data can’t be decoded.

    Availability

    Available in OS X v10.0 and later.

  • Initializes and returns a new attributed string object from HTML contained in the given data object.

    Declaration

    Swift

    init?(HTML data: NSData, options options: [NSObject : AnyObject], documentAttributes dict: AutoreleasingUnsafeMutablePointer<NSDictionary?>)

    Objective-C

    - (instancetype)initWithHTML:(NSData *)data options:(NSDictionary *)options documentAttributes:(NSDictionary<NSString *,id> * _Nullable *)dict

    Parameters

    data

    The data in HTML format from which to create the attributed string.

    options

    Specifies how the document should be loaded. Contains values described in Option keys for importing documents.

    dict

    An in-out dictionary containing document-level attributes described in Document Attributes. May be NULL, in which case no document attributes are returned.

    Return Value

    Returns an initialized object, or nil if the data can’t be decoded.

    Availability

    Available in OS X v10.3 and later.

  • Initializes a new attributed string object by decoding the stream of RTF commands and data contained in the given data object.

    Declaration

    Swift

    init?(RTF data: NSData, documentAttributes dict: AutoreleasingUnsafeMutablePointer<NSDictionary?>)

    Objective-C

    - (instancetype)initWithRTF:(NSData *)rtfData documentAttributes:(NSDictionary<NSString *,id> * _Nullable *)docAttributes

    Parameters

    rtfData

    The data containing RTF content.

    docAttributes

    An in-out dictionary containing document-level attributes described in Document Attributes. May be NULL, in which case no document attributes are returned.

    Return Value

    Returns an initialized object, or nil if the data can’t be decoded.

    Discussion

    Also returns by reference in docAttributes a dictionary containing document-level attributes described in Document Attributes. docAttributes may be NULL, in which case no document attributes are returned. Returns an initialized object, or nil if rtfData can’t be decoded.

    Availability

    Available in OS X v10.0 and later.

  • Initializes a new attributed string object by decoding the stream of RTFD commands and data contained in the given data object.

    Declaration

    Swift

    init?(RTFD data: NSData, documentAttributes dict: AutoreleasingUnsafeMutablePointer<NSDictionary?>)

    Objective-C

    - (instancetype)initWithRTFD:(NSData *)rtfdData documentAttributes:(NSDictionary<NSString *,id> * _Nullable *)docAttributes

    Parameters

    rtfdData

    The data containing the RTFD content.

    docAttributes

    An in-out dictionary containing document-level attributes described in Document Attributes. May be NULL, in which case no document attributes are returned.

    Return Value

    Returns an initialized object, or nil if the data can’t be decoded.

    Availability

    Available in OS X v10.0 and later.

  • Initializes a new attributed string object from the specified file wrapper containing an RTFD document.

    Declaration

    Swift

    init?(RTFDFileWrapper wrapper: NSFileWrapper, documentAttributes dict: AutoreleasingUnsafeMutablePointer<NSDictionary?>)

    Objective-C

    - (instancetype)initWithRTFDFileWrapper:(NSFileWrapper *)wrapper documentAttributes:(NSDictionary<NSString *,id> * _Nullable *)docAttributes

    Parameters

    wrapper

    The NSFileWrapper containing the RTFD document.

    docAttributes

    An in-out dictionary containing document-level attributes described in Document Attributes. May be NULL, in which case no document attributes are returned.

    Return Value

    Returns an initialized object, or nil if the data can’t be decoded.

    Discussion

    Also returns by reference in docAttributes a dictionary containing document-level attributes described in Document Attributes. docAttributes may be NULL, in which case no document attributes are returned. Returns an initialized object, or nil if wrapper can’t be interpreted as an RTFD document.

    Availability

    Available in OS X v10.0 and later.

  • Initializes a new NSAttributedString object from the contents of the given URL.

    Declaration

    Swift

    init(URL url: NSURL, options options: [String : AnyObject], documentAttributes dict: AutoreleasingUnsafeMutablePointer<NSDictionary?>) throws

    Objective-C

    - (instancetype)initWithURL:(NSURL *)url options:(NSDictionary<NSString *,id> *)options documentAttributes:(NSDictionary<NSString *,id> * _Nullable *)docAttributes error:(NSError * _Nullable *)error

    Parameters

    url

    An NSURL object specifying the document to load.

    options

    Specifies how the document should be loaded. Contains values described in Option keys for importing documents.

    docAttributes

    An in-out dictionary containing document-level attributes described in Document Attributes. May be NULL, in which case no document attributes are returned.

    error

    An in-out parameter that returns an error if the method returns nil.

    Return Value

    Returns an initialized object, or nil if the data can’t be decoded.

    Discussion

    Filter services can be used to convert the file into a format recognized by Cocoa. The options dictionary specifies how the document should be loaded and can contain the values described in Option keys for importing documents.

    If NSDocumentTypeDocumentOption is specified, the document is treated as being in the specified format. If NSDocumentTypeDocumentOption is not specified, the method examines the document and loads it using whatever format it seems to contain.

    Also returns by reference in dict a dictionary containing document-level attributes described in Document Attributes. The dict parameter may be nil, in which case no document attributes are returned. Returns an initialized object, or nil if the file at url can’t be decoded, after setting error to point to an NSError object that encapsulates the reason why the attributed string object could not be created.

    Availability

    Available in OS X v10.11 and later.

  • Creates an attributed string with an attachment.

    Declaration

    Swift

    init(attachment attachment: NSTextAttachment)

    Objective-C

    + (NSAttributedString *)attributedStringWithAttachment:(NSTextAttachment *)attachment

    Parameters

    attachment

    The attachment.

    Return Value

    An attributed string containing the attachment.

    Discussion

    This is a convenience method for creating an attributed string containing an attachment using NSAttachmentCharacter as the base character.

    Availability

    Available in OS X v10.0 and later.

  • The character contents of the receiver as an NSString object. (read-only)

    Declaration

    Swift

    var string: String { get }

    Objective-C

    @property(readonly, copy) NSString *string

    Discussion

    Attachment characters are not removed from the value of this property.

    For performance reasons, this property returns the current backing store of the attributed string object. If you want to maintain a snapshot of this as you manipulate the returned string, you should make a copy of the appropriate substring.

    This primitive property must guarantee efficient access to an attributed string’s characters; subclasses should implement it to execute in O(1) time.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • The length of the receiver’s string object. (read-only)

    Declaration

    Swift

    var length: Int { get }

    Objective-C

    @property(readonly) NSUInteger length

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

    See Also

    length (NSString)
    size (NSAttributedString)

  • Returns the attributes for the character at a given index.

    Declaration

    Swift

    func attributesAtIndex(_ location: Int, effectiveRange range: NSRangePointer) -> [String : AnyObject]

    Objective-C

    - (NSDictionary<NSString *,id> *)attributesAtIndex:(NSUInteger)index effectiveRange:(NSRangePointer)aRange

    Parameters

    index

    The index for which to return attributes. This value must lie within the bounds of the receiver.

    aRange

    Upon return, the range over which the attributes and values are the same as those at index. This range isn’t necessarily the maximum range covered, and its extent is implementation-dependent. If you need the maximum range, use attributesAtIndex:longestEffectiveRange:inRange:. If you don't need this value, pass NULL.

    Return Value

    The attributes for the character at index.

    Discussion

    Raises an NSRangeException if index lies beyond the end of the receiver’s characters.

    For a list of possible attributes, see Character Attributes.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the attributes for the character at a given index, and by reference the range over which the attributes apply.

    Declaration

    Swift

    func attributesAtIndex(_ location: Int, longestEffectiveRange range: NSRangePointer, inRange rangeLimit: NSRange) -> [String : AnyObject]

    Objective-C

    - (NSDictionary<NSString *,id> *)attributesAtIndex:(NSUInteger)index longestEffectiveRange:(NSRangePointer)aRange inRange:(NSRange)rangeLimit

    Parameters

    index

    The index for which to return attributes. This value must not exceed the bounds of the receiver.

    aRange

    If non-NULL, upon return contains the maximum range over which the attributes and values are the same as those at index, clipped to rangeLimit.

    rangeLimit

    The range over which to search for continuous presence of the attributes at index. This value must not exceed the bounds of the receiver.

    Discussion

    Raises an NSRangeException if index or any part of rangeLimit lies beyond the end of the receiver’s characters.

    If you don’t need the range information, it’s far more efficient to use the attributesAtIndex:effectiveRange: method to retrieve the attribute value.

    For a list of possible attributes, see Character Attributes.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the value for an attribute with a given name of the character at a given index, and by reference the range over which the attribute applies.

    Declaration

    Swift

    func attribute(_ attrName: String, atIndex location: Int, effectiveRange range: NSRangePointer) -> AnyObject?

    Objective-C

    - (id)attribute:(NSString *)attributeName atIndex:(NSUInteger)index effectiveRange:(NSRangePointer)aRange

    Parameters

    attributeName

    The name of an attribute.

    index

    The index for which to return attributes. This value must not exceed the bounds of the receiver.

    aRange

    If non-NULL:

    • If the named attribute exists at index, upon return aRange contains a range over which the named attribute’s value applies.

    • If the named attribute does not exist at index, upon return aRange contains the range over which the attribute does not exist.

    The range isn’t necessarily the maximum range covered by attributeName, and its extent is implementation-dependent. If you need the maximum range, use attribute:atIndex:longestEffectiveRange:inRange:. If you don't need this value, pass NULL.

    Return Value

    The value for the attribute named attributeName of the character at index, or nil if there is no such attribute.

    Discussion

    For a list of possible attributes, see Character Attributes.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns the value for the attribute with a given name of the character at a given index, and by reference the range over which the attribute applies.

    Declaration

    Swift

    func attribute(_ attrName: String, atIndex location: Int, longestEffectiveRange range: NSRangePointer, inRange rangeLimit: NSRange) -> AnyObject?

    Objective-C

    - (id)attribute:(NSString *)attributeName atIndex:(NSUInteger)index longestEffectiveRange:(NSRangePointer)aRange inRange:(NSRange)rangeLimit

    Parameters

    attributeName

    The name of an attribute.

    index

    The index at which to test for attributeName.

    aRange

    If non-NULL:

    • If the named attribute exists at index, upon return aRange contains the full range over which the value of the named attribute is the same as that at index, clipped to rangeLimit.

    • If the named attribute does not exist at index, upon return aRange contains the full range over which the attribute does not exist, clipped to rangeLimit.

    If you don't need this value, pass NULL.

    rangeLimit

    The range over which to search for continuous presence of attributeName. This value must not exceed the bounds of the receiver.

    Return Value

    The value for the attribute named attributeName of the character at index, or nil if there is no such attribute.

    Discussion

    Raises an NSRangeException if index or any part of rangeLimit lies beyond the end of the receiver’s characters.

    If you don’t need the longest effective range, it’s far more efficient to use the attribute:atIndex:effectiveRange: method to retrieve the attribute value.

    For a list of possible attributes, see Character Attributes.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value that indicates whether the receiver is equal to another given attributed string.

    Declaration

    Swift

    func isEqualToAttributedString(_ other: NSAttributedString) -> Bool

    Objective-C

    - (BOOL)isEqualToAttributedString:(NSAttributedString *)otherString

    Parameters

    otherString

    The attributed string with which to compare the receiver.

    Return Value

    YEStrue if the receiver is equal to otherString, otherwise NOfalse.

    Discussion

    Attributed strings must match in both characters and attributes to be equal.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Returns an NSAttributedString object consisting of the characters and attributes within a given range in the receiver.

    Declaration

    Swift

    func attributedSubstringFromRange(_ range: NSRange) -> NSAttributedString

    Objective-C

    - (NSAttributedString *)attributedSubstringFromRange:(NSRange)aRange

    Parameters

    aRange

    The range from which to create a new attributed string. aRange must lie within the bounds of the receiver.

    Return Value

    An NSAttributedString object consisting of the characters and attributes within aRange in the receiver.

    Discussion

    Raises an NSRangeException if any part of aRange lies beyond the end of the receiver’s characters. This method treats the length of the string as a valid range value that returns an empty string.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.0 and later.

  • Executes the block for the specified attribute run in the specified range.

    Declaration

    Swift

    func enumerateAttribute(_ attrName: String, inRange enumerationRange: NSRange, options opts: NSAttributedStringEnumerationOptions, usingBlock block: (AnyObject?, NSRange, UnsafeMutablePointer<ObjCBool>) -> Void)

    Objective-C

    - (void)enumerateAttribute:(NSString *)attrName inRange:(NSRange)enumerationRange options:(NSAttributedStringEnumerationOptions)opts usingBlock:(void (^)(id value, NSRange range, BOOL *stop))block

    Parameters

    attrName

    The name of an attribute.

    enumerationRange

    If non-NULL, contains the maximum range over which the attributes and values are enumerated, clipped to enumerationRange.

    opts

    The options used by the enumeration. The values can be combined using C-bitwise OR. The values are described in NSAttributedStringEnumerationOptions.

    block

    The block to apply to ranges of the attribute in the attributed string.

    The block takes three arguments:

    value

    The attrName value.

    range

    An NSRange indicating the run of the attribute.

    stop

    A reference to a Boolean value. The block can set the value to YEStrue to stop further processing of the set. The stop argument is an out-only argument. You should only ever set this Boolean to YEStrue within the block.

    Discussion

    If this method is sent to an instance of NSMutableAttributedString, mutation (deletion, addition, or change) is allowed, as long as it is within the range provided to the block; after a mutation, the enumeration continues with the range immediately following the processed range, after the length of the processed range is adjusted for the mutation. (The enumerator basically assumes any change in length occurs in the specified range.)

    For example, if block is called with a range starting at location N, and the block deletes all the characters in the supplied range, the next call will also pass N as the index of the range.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

  • Executes the block for each attribute in the range.

    Declaration

    Swift

    func enumerateAttributesInRange(_ enumerationRange: NSRange, options opts: NSAttributedStringEnumerationOptions, usingBlock block: ([String : AnyObject], NSRange, UnsafeMutablePointer<ObjCBool>) -> Void)

    Objective-C

    - (void)enumerateAttributesInRange:(NSRange)enumerationRange options:(NSAttributedStringEnumerationOptions)opts usingBlock:(void (^)(NSDictionary<NSString *,id> *attrs, NSRange range, BOOL *stop))block

    Parameters

    enumerationRange

    If non-NULL, contains the maximum range over which the attributes and values are enumerated, clipped to enumerationRange.

    opts

    The options used by the enumeration. The values can be combined using C-bitwise OR. The values are described in NSAttributedStringEnumerationOptions.

    block

    The block to apply to ranges of the attribute in the attributed string.

    The block takes three arguments:

    attrs

    The attributes for the range.

    range

    The run of the attributes.

    stop

    A reference to a Boolean value. The block can set the value to YEStrue to stop further processing of the set. The stop argument is an out-only argument. You should only ever set this Boolean to YEStrue within the block.

    Discussion

    If this method is sent to an instance of NSMutableAttributedString, mutation (deletion, addition, or change) is allowed, as long as it is within the range provided to the block; after a mutation, the enumeration continues with the range immediately following the processed range, after the length of the processed range is adjusted for the mutation. (The enumerator basically assumes any change in length occurs in the specified range.)

    For example, if block is called with a range starting at location N, and the block deletes all the characters in the supplied range, the next call will also pass N as the index of the range.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

  • Returns the range of characters that form a word (or other linguistic unit) surrounding the given index, taking language characteristics into account.

    Declaration

    Swift

    func doubleClickAtIndex(_ location: Int) -> NSRange

    Objective-C

    - (NSRange)doubleClickAtIndex:(NSUInteger)index

    Parameters

    index

    The index in the attributed string.

    Return Value

    Returns the range of characters that form a word (or other linguistic unit) surrounding the given index, taking language characteristics into account.

    Discussion

    Raises an NSRangeException if index lies beyond the end of the receiver’s characters.

    Availability

    Available in OS X v10.0 and later.

  • Returns the appropriate line break when the character at the index won’t fit on the same line as the character at the beginning of the range.

    Declaration

    Swift

    func lineBreakBeforeIndex(_ location: Int, withinRange aRange: NSRange) -> Int

    Objective-C

    - (NSUInteger)lineBreakBeforeIndex:(NSUInteger)index withinRange:(NSRange)aRange

    Parameters

    index

    The index in the attributed string.

    aRange

    The range.

    Return Value

    Returns the index of the closest character before index within aRange, that can be placed on a new line when laying out text. Returns NSNotFound if no line break is possible before index.

    Discussion

    Raises an NSRangeException if index or any part of aRange lies beyond the end of the receiver’s characters.

    Availability

    Available in OS X v10.0 and later.

  • Returns the index of the closest character before the given index, and within the given range, that can be placed on a new line by hyphenating.

    Declaration

    Swift

    func lineBreakByHyphenatingBeforeIndex(_ location: Int, withinRange aRange: NSRange) -> Int

    Objective-C

    - (NSUInteger)lineBreakByHyphenatingBeforeIndex:(NSUInteger)location withinRange:(NSRange)aRange

    Parameters

    location

    The location in the attributed string.

    aRange

    The range.

    Return Value

    Returns the index of the closest character before index within aRange, that can be placed on a new line by hyphenating. Returns NSNotFound if no line break by hyphenation is possible before index.

    Discussion

    In other words, during text layout, finds the appropriate line break by hyphenation (the character index at which the hyphen glyph should be inserted) when the character at index won’t fit on the same line as the character at the beginning of aRange.

    Raises an NSRangeException if index or any part of aRange lies beyond the end of the receiver’s characters.

    Availability

    Available in OS X v10.3 and later.

  • Returns the index of the first character of the word after or before the given index.

    Declaration

    Swift

    func nextWordFromIndex(_ location: Int, forward isForward: Bool) -> Int

    Objective-C

    - (NSUInteger)nextWordFromIndex:(NSUInteger)index forward:(BOOL)flag

    Parameters

    index

    The index in the attribute string.

    flag

    YEStrue if the search should be forward, otherwise NOfalse.

    Return Value

    YEStrue if this is the first character after index that begins a word; if flag is NOfalse, it’s the first character before index that begins a word, whether index is located within a word or not.

    Discussion

    If index lies at either end of the string and the search direction would progress past that end, it’s returned unchanged.

    This method is intended for moving the insertion point during editing, not for linguistic analysis or parsing of text.

    Raises an NSRangeException if index lies beyond the end of the receiver’s characters.

    Availability

    Available in OS X v10.0 and later.

  • Draws the attributed string starting at the specified point in the current graphics context.

    Declaration

    Swift

    func drawAtPoint(_ point: NSPoint)

    Objective-C

    - (void)drawAtPoint:(NSPoint)point

    Parameters

    point

    The point in the current graphics context where you want to start drawing the string. The coordinate system of the graphics context is usually defined by the view in which you are drawing.

    Discussion

    This method draws the entire string starting at the specified point. This method draws the line using the attributes specified in the attributed string itself. If newline characters are present in the string, those characters are honored and cause subsequent text to be placed on the next line underneath the starting point.

    There must be either a focused view or an active graphics context when you call this method.

    Availability

    Available in OS X v10.0 and later.

  • Draws the attributed string inside the specified bounding rectangle in the current graphics context.

    Declaration

    Swift

    func drawInRect(_ rect: NSRect)

    Objective-C

    - (void)drawInRect:(NSRect)rect

    Parameters

    rect

    The bounding rectangle in which to draw the string. In AppKit, the origin is normally in the lower-left corner of the drawing area, but the origin is in the upper-left corner if the focused view is flipped.

    Discussion

    This method draws as much of the string as it can inside the specified rectangle, wrapping the string text as needed to make it fit. If the string is too long to fit inside the rectangle, the method renders as much as possible and clips the rest. It is possible for a portion of a glyph to appear outside the area of rect if the image bounding box of the particular glyph exceeds its typographic bounding box. Text is drawn according to its line sweep direction; for example, Arabic text begins at the right edge and is potentially clipped on the left.

    Layout always occurs from top to bottom. AppKit automatically adjusts the initial drawing point whether or not the view is flipped. For example, if the rect argument is {0.0, 0.0, 100.0, 100.0}, the text origin is {0.0, 0.0} when the view coordinates are flipped and {0.0, 100.0} when the view is not flipped.

    This method draws the line using the attributes specified in the attributed string itself. If newline characters are present in the string, those characters are honored and cause subsequent text to be placed on the next line underneath the starting point.

    There must be either a focused view or an active graphics context when you call this method.

    Availability

    Available in OS X v10.0 and later.

    See Also

    lockFocus (NSView)
    – drawAtPoint:

  • Draws the attributed string in the specified bounding rectangle using the provided options.

    Declaration

    Swift

    func drawWithRect(_ rect: NSRect, options options: NSStringDrawingOptions, context context: NSStringDrawingContext?)

    Objective-C

    - (void)drawWithRect:(NSRect)rect options:(NSStringDrawingOptions)options context:(NSStringDrawingContext *)context

    Parameters

    rect

    The bounding rectangle in which to draw the string.

    options

    Additional drawing options to apply to the string during rendering. For a list of possible values, see NSStringDrawingOptions.

    context

    A context object with information about how to adjust the font tracking and scaling information. On return, the specified object contains information about the actual values used to render the string. This parameter may be nil.

    Discussion

    If NSStringDrawingUsesLineFragmentOrigin is specified in options, it wraps the string text as needed to make it fit. If the string is too big to fit completely inside the rectangle, the method scales the font or adjusts the letter spacing to make the string fit within the given bounds.

    If NSStringDrawingUsesLineFragmentOrigin is not specified in options, the origin of the rectangle is the baseline of the only line. The text will be displayed above the rectangle and not inside of it. For example, if you specify a rectangle starting at 0,0 and draw the string ‘juxtaposed’, only the descenders of the ‘j’ and ‘p’ will be seen. The rest of the text will be on the top edge of the rectangle.

    This method draws the line using the attributes specified in the attributed string itself. If newline characters are present in the string, those characters are honored and cause subsequent text to be placed on the next line underneath the starting point.

    There must be either an active graphics context when you call this method.

    Special Considerations

    This method uses the baseline origin by default, so it renders the string as a single line. To render the string in multiple lines, specify NSStringDrawingUsesLineFragmentOrigin in options.

    Availability

    Available in OS X v10.11 and later.

  • Returns the size required to draw the string.

    Declaration

    Swift

    func size() -> NSSize

    Objective-C

    - (NSSize)size

    Return Value

    The minimum size required to draw the entire contents of the string.

    Discussion

    You can use this method prior to drawing to compute how much space is required to draw the string.

    This method may return fractional sizes. When setting the size of your view, use the ceil function to round fractional values up to the nearest whole number.

    Availability

    Available in OS X v10.0 and later.

  • Returns the bounding rectangle required to draw the string.

    Declaration

    Swift

    func boundingRectWithSize(_ size: NSSize, options options: NSStringDrawingOptions, context context: NSStringDrawingContext?) -> NSRect

    Objective-C

    - (NSRect)boundingRectWithSize:(NSSize)size options:(NSStringDrawingOptions)options context:(NSStringDrawingContext *)context

    Parameters

    size

    The width and height constraints to apply when computing the string’s bounding rectangle.

    options

    Additional drawing options to apply to the string during rendering. For a list of possible values, see NSStringDrawingOptions.

    context

    A context object with information about how to adjust the font tracking and scaling information. On return, the specified object contains information about the actual values used to render the string. This parameter may be nil.

    Return Value

    A rectangle whose size component indicates the width and height required to draw the entire contents of the string.

    Discussion

    You can use this method to compute the space required to draw the string. The constraints you specify in the size parameter are a guide for the renderer for how to size the string. However, the actual bounding rectangle returned by this method can be larger than the constraints if additional space is needed to render the entire string. Typically, the renderer preserves the width constraint and adjusts the height constraint as needed.

    In iOS 7 and later, this method returns fractional sizes (in the size component of the returned rectangle); to use a returned size to size views, you must use raise its value to the nearest higher integer using the ceil function.

    Special Considerations

    To calculate the bounding rectangle, this method uses the baseline origin by default, so it behaves as a single line. To render the string in multiple lines, specify NSStringDrawingUsesLineFragmentOrigin in options.

    Availability

    Available in OS X v10.11 and later.

  • Returns a Boolean value that indicates if the attributed string contains a property configured in the specified range.

    Declaration

    Swift

    func containsAttachmentsInRange(_ range: NSRange) -> Bool

    Objective-C

    - (BOOL)containsAttachmentsInRange:(NSRange)range

    Parameters

    range

    The range.

    Return Value

    YEStrue if the attributed string contains a property configured as NSAttachmentAttributeName with NSAttachmentCharacter in range; otherwise, NOfalse.

    Availability

    Available in OS X v10.11 and later.

  • Returns an array of UTI strings identifying the file types supported by the receiver, either directly or through a user-installed filter service.

    Declaration

    Swift

    class func textTypes() -> [String]

    Objective-C

    + (NSArray<NSString *> *)textTypes

    Return Value

    An array of NSString objects, each of which contains a UTI identifying a supported file type.

    Discussion

    The returned list includes UTIs all file types supported by the receiver plus those that can be opened by the receiver after being converted by a user-installed filter service. You can use the returned UTI strings with any method that supports UTIs.

    Availability

    Available in OS X v10.5 and later.

  • Returns an array of UTI strings identifying the file types supported directly by the receiver.

    Declaration

    Swift

    class func textUnfilteredTypes() -> [String]

    Objective-C

    + (NSArray<NSString *> *)textUnfilteredTypes

    Return Value

    An array of NSString objects, each of which contains a UTI identifying a supported file type.

    Discussion

    The returned list includes UTI strings only for those file types that are supported directly by the receiver. It does not include types that are supported through user-installed filter services. You can use the returned UTI strings with any method that supports UTIs.

    Availability

    Available in OS X v10.5 and later.

  • + textFileTypes (OS X v10.5)

    Returns an array of strings representing those file types that can be loaded as text.

    Deprecation Statement

    Use textTypes instead.

    Declaration

    Objective-C

    + (NSArray *)textFileTypes

    Return Value

    An array of NSString objects, containing file extensions and HFS file types. By default, the list returned by this method includes “txt”, “rtf”, “rtfd”, and “html”.

    Discussion

    This list includes all file types supported by text classes, plus those types that can be converted to supported file types through a user-installed filter service. The array returned by this method may be passed directly to the runModalForTypes: method of NSOpenPanel.

    When creating a subclass of NSAttributedString that accepts text data from non-default file types, override textUnfilteredTypes to notify NSAttributedString of the file types your class supports.

    Availability

    Available in OS X v10.1 and later.

    Deprecated in OS X v10.5.

  • Returns an array of strings representing those file types that can be loaded as a text.

    Deprecation Statement

    Use textUnfilteredTypes instead.

    Declaration

    Objective-C

    + (NSArray *)textUnfilteredFileTypes

    Return Value

    An array of NSString objects, consisting of all file types supported by text classes, but does not include those types that can be converted to supported file types through a user-installed filter service.

    Discussion

    This list consists of all file types supported by text classes, but does not include those types that can be converted to supported file types through a user-installed filter service. In OS X, the array returned by this method may be passed directly to the runModalForTypes: method of NSOpenPanel.

    Availability

    Available in OS X v10.1 and later.

    Deprecated in OS X v10.5.

  • Returns an array of pasteboard types that can be loaded as text.

    Deprecation Statement

    Use textTypes instead.

    Declaration

    Objective-C

    + (NSArray *)textPasteboardTypes

    Return Value

    An array of NSString objects, containing the pasteboard types supported by text classes and those that can be converted to supported pasteboard types through a user-installed filter service.

    Discussion

    By default, the list returned by this method includes NSHTMLPboardType, NSRTFPboardType, NSRTFDPboardType, and NSStringPboardType.

    When creating a subclass of NSAttributedString that accepts text data from non-default pasteboard types, override textUnfilteredPasteboardTypes to notify NSAttributedString of the pasteboard types your class supports.

    Availability

    Available in OS X v10.1 and later.

    Deprecated in OS X v10.5.

  • Returns an array of pasteboard types that can be loaded as text.

    Deprecation Statement

    Use textUnfilteredTypes instead.

    Declaration

    Objective-C

    + (NSArray *)textUnfilteredPasteboardTypes

    Return Value

    An array of NSString objects, pasteboard types supported by text classes.

    Discussion

    This list consists of all pasteboard types supported by text classes, but does not include those that can be converted to supported pasteboard types through a user-installed filter service.

    Availability

    Available in OS X v10.1 and later.

    Deprecated in OS X v10.5.

  • Initializes a new attribute string object from RTF or RTFD data contained in the file at the given path.

    Deprecation Statement

    Use initWithURL:options:documentAttributes:error: instead.

    Declaration

    Swift

    init?(path path: String, documentAttributes dict: AutoreleasingUnsafeMutablePointer<NSDictionary?>)

    Objective-C

    - (instancetype)initWithPath:(NSString *)path documentAttributes:(NSDictionary * _Nullable *)docAttributes

    Parameters

    path

    The path to an RTF or RTFD file.

    docAttributes

    An in-out dictionary containing document-level attributes described in Document Attributes. May be NULL, in which case no document attributes are returned.

    Return Value

    Returns an initialized object, or nil if the data can’t be decoded.

    Discussion

    The contents of path will be examined to best load the file in whatever format it’s in. Filter services can be used to convert the file into a format recognized by Cocoa. Also returns by reference in docAttributes a dictionary containing document-level attributes described in Document Attributes. docAttributes may be NULL, in which case no document attributes are returned. Returns an initialized object, or nil if the file at path can’t be decoded.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.11.

  • Initializes a new attributed string object from the data at the given URL.

    Deprecation Statement

    Use initWithURL:options:documentAttributes:error: instead.

    Declaration

    Swift

    init?(URL url: NSURL, documentAttributes dict: AutoreleasingUnsafeMutablePointer<NSDictionary?>)

    Objective-C

    - (instancetype)initWithURL:(NSURL *)aURL documentAttributes:(NSDictionary * _Nullable *)docAttributes

    Parameters

    aURL

    An NSURL object specifying the document to load.

    docAttributes

    An in-out dictionary containing document-level attributes described in Document Attributes. May be NULL, in which case no document attributes are returned.

    Return Value

    Returns an initialized object, or nil if the data can’t be decoded.

    Discussion

    The contents of aURL are examined to best load the file in whatever format it’s in. Filter services can be used to convert the file into a format recognized by Cocoa. Also returns by reference in docAttributes a dictionary containing document-level attributes described in Document Attributes. docAttributes may be NULL, in which case no document attributes are returned. Returns an initialized object, or nil if the file at path can’t be decoded.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.11.

  • Returns whether the attribute string contains any attachment attributes.

    Deprecation Statement

    Use containsAttachmentsInRange: instead.

    Declaration

    Swift

    var containsAttachments: Bool { get }

    Objective-C

    @property(readonly) BOOL containsAttachments

    Return Value

    YES if the attributed string contains any attachment attributes, otherwise NO.

    Discussion

    This method checks only for attachment attributes, not for NSAttachmentCharacter.

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.11.

  • Returns a URL, either from a link attribute or from text at the given location that appears to be a URL string, for use in automatic link detection.

    Deprecation Statement

    Use an NSDataDetector object instead.

    Declaration

    Swift

    func URLAtIndex(_ location: Int, effectiveRange effectiveRange: NSRangePointer) -> NSURL?

    Objective-C

    - (NSURL *)URLAtIndex:(NSUInteger)location effectiveRange:(NSRangePointer)effectiveRange

    Parameters

    location

    The character index in the string at which the method checks for a link.

    effectiveRange

    The actual range covered by the link attribute or URL string, or of non-URL text if no apparent URL is found.

    Return Value

    The URL found at location.

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.11.

  • Draws the receiver with the specified options, within the given rectangle in the current graphics context.

    Deprecation Statement

    Use drawWithRect:options:context: instead.

    Declaration

    Swift

    func drawWithRect(_ rect: NSRect, options options: NSStringDrawingOptions)

    Objective-C

    - (void)drawWithRect:(NSRect)rect options:(NSStringDrawingOptions)options

    Parameters

    rect

    The rectangle specifies the rendering origin in the current graphics context.

    options

    The string drawing options. See String Drawing Options for the available options.

    Discussion

    The rect argument's origin field specifies the rendering origin. The point is interpreted as the baseline origin by default. With NSStringDrawingUsesLineFragmentOrigin, it is interpreted as the upper left corner of the line fragment rect. 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.

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.11.

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

    Deprecation Statement

    Use boundingRectWithSize:options:context: instead.

    Declaration

    Swift

    func boundingRectWithSize(_ size: NSSize, options options: NSStringDrawingOptions) -> NSRect

    Objective-C

    - (NSRect)boundingRectWithSize:(NSSize)size options:(NSStringDrawingOptions)options

    Parameters

    size

    The size of the rectangle to draw in.

    options

    The string drawing options. See String Drawing Options for the possible values.

    Return Value

    The bounding rectangle in the current graphics context.

    Discussion

    The origin of the rectangle returned from this method is the first glyph origin.

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.11.

  • These constants describe the options available to the enumerateAttribute:inRange:options:usingBlock: and enumerateAttributesInRange:options:usingBlock: methods.

    Declaration

    Swift

    struct NSAttributedStringEnumerationOptions : OptionSetType { init(rawValue rawValue: UInt) static var Reverse: NSAttributedStringEnumerationOptions { get } static var LongestEffectiveRangeNotRequired: NSAttributedStringEnumerationOptions { get } }

    Objective-C

    enum { NSAttributedStringEnumerationReverse = (1UL << 1), NSAttributedStringEnumerationLongestEffectiveRangeNotRequired = (1UL << 20) }; typedef NSUInteger NSAttributedStringEnumerationOptions;

    Constants

    • Reverse

      NSAttributedStringEnumerationReverse

      Causes the enumeration to occur in reverse.

      Available in OS X v10.6 and later.

    • LongestEffectiveRangeNotRequired

      NSAttributedStringEnumerationLongestEffectiveRangeNotRequired

      If NSAttributedStringEnumerationLongestEffectiveRangeNotRequired option is supplied, then the longest effective range computation is not performed; the blocks may be invoked with consecutive attribute runs that have the same value.

      Available in OS X v10.6 and later.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.6 and later.

  • Constants for specifying both the NSUnderlineStyleAttributeName and NSStrikethroughStyleAttributeName attributes of an attributed string.

    Declaration

    Swift

    enum NSUnderlineStyle : Int { case StyleNone case StyleSingle case StyleThick case StyleDouble static var PatternSolid: NSUnderlineStyle { get } case PatternDot case PatternDash case PatternDashDot case PatternDashDotDot case ByWord }

    Objective-C

    typedef enum NSUnderlineStyle : NSInteger { NSUnderlineStyleNone = 0x00, NSUnderlineStyleSingle = 0x01, NSUnderlineStyleThick = 0x02, NSUnderlineStyleDouble = 0x09, NSUnderlinePatternSolid = 0x0000, NSUnderlinePatternDot = 0x0100, NSUnderlinePatternDash = 0x0200, NSUnderlinePatternDashDot = 0x0300, NSUnderlinePatternDashDotDot = 0x0400, NSUnderlineByWord = 0x8000 } NSUnderlineStyle;

    Constants

    • styleNone

      NSUnderlineStyleNone

      Do not draw a line.

      Available in OS X v10.0 and later.

    • styleSingle

      NSUnderlineStyleSingle

      Draw a single line.

      Available in OS X v10.0 and later.

    • styleThick

      NSUnderlineStyleThick

      Draw a thick line.

      Available in OS X v10.0 and later.

    • styleDouble

      NSUnderlineStyleDouble

      Draw a double line.

      Available in OS X v10.0 and later.

    • patternSolid

      NSUnderlinePatternSolid

      Draw a solid line.

      Available in OS X v10.0 and later.

    • patternDot

      NSUnderlinePatternDot

      Draw a line of dots.

      Available in OS X v10.0 and later.

    • patternDash

      NSUnderlinePatternDash

      Draw a line of dashes.

      Available in OS X v10.0 and later.

    • patternDashDot

      NSUnderlinePatternDashDot

      Draw a line of alternating dashes and dots.

      Available in OS X v10.0 and later.

    • patternDashDotDot

      NSUnderlinePatternDashDotDot

      Draw a line of alternating dashes and two dots.

      Available in OS X v10.0 and later.

    • byWord

      NSUnderlineByWord

      Draw the line only underneath or through words, not whitespace.

      Available in OS X v10.0 and later.

    Discussion

    The style, pattern, and optionally by-word mask are OR'd together to produce the value for NSUnderlineStyleAttributeName and NSStrikethroughStyleAttributeName.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.11 and later.

  • Options for specifying writing direction used with NSWritingDirectionAttributeName.

    Declaration

    Swift

    enum NSWritingDirectionFormatType : Int { case Embedding case Override }

    Objective-C

    typedef enum NSWritingDirectionFormatType : NSInteger { NSWritingDirectionEmbedding = (0 << 1), NSWritingDirectionOverride = (1 << 1) } NSWritingDirectionFormatType;

    Constants

    • embedding

      NSWritingDirectionEmbedding

      Text is embedded in text with another writing direction. For example, an English quotation in the middle of an Arabic sentence could be marked as being embedded left-to-right text.

      Available in OS X v10.11 and later.

    • override

      NSWritingDirectionOverride

      Enables character types with inherent directionality to be overridden when required for special cases, such as for part numbers made of mixed English, digits, and Hebrew letters to be written from right to left.

      Available in OS X v10.11 and later.

    Discussion

    You can use the logical OR operator to combine these constants with NSWritingDirectionLeftToRight or NSWritingDirectionRightToLeft when used with NSWritingDirectionAttributeName to specify formatting controls defined by the Unicode Bidirectional Algorithm in Unicode Standard Annex #9.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.11 and later.

  • Attributes that you can apply to text in an attributed string.

    Declaration

    Swift

    let NSAttachmentAttributeName: String let NSBackgroundColorAttributeName: String let NSBaselineOffsetAttributeName: String let NSCursorAttributeName: String let NSExpansionAttributeName: String let NSFontAttributeName: String let NSForegroundColorAttributeName: String let NSKernAttributeName: String let NSLigatureAttributeName: String let NSLinkAttributeName: String let NSMarkedClauseSegmentAttributeName: String let NSObliquenessAttributeName: String let NSParagraphStyleAttributeName: String let NSShadowAttributeName: String let NSSpellingStateAttributeName: String let NSStrikethroughColorAttributeName: String let NSStrikethroughStyleAttributeName: String let NSStrokeColorAttributeName: String let NSStrokeWidthAttributeName: String let NSSuperscriptAttributeName: String let NSTextAlternativesAttributeName: String let NSTextEffectAttributeName: String let NSToolTipAttributeName: String let NSUnderlineColorAttributeName: String let NSUnderlineStyleAttributeName: String let NSVerticalGlyphFormAttributeName: String let NSWritingDirectionAttributeName: String

    Objective-C

    NSString *const NSAttachmentAttributeName; NSString *const NSBackgroundColorAttributeName; NSString *const NSBaselineOffsetAttributeName; NSString *NSCursorAttributeName; NSString *const NSExpansionAttributeName; NSString *const NSFontAttributeName; NSString *const NSForegroundColorAttributeName; NSString *const NSKernAttributeName; NSString *const NSLigatureAttributeName; NSString *const NSLinkAttributeName; NSString *NSMarkedClauseSegmentAttributeName; NSString *const NSObliquenessAttributeName; NSString *const NSParagraphStyleAttributeName; NSString *const NSShadowAttributeName; NSString *NSSpellingStateAttributeName; NSString *const NSStrikethroughColorAttributeName; NSString *const NSStrikethroughStyleAttributeName; NSString *const NSStrokeColorAttributeName; NSString *const NSStrokeWidthAttributeName; NSString *NSSuperscriptAttributeName; NSString *const NSTextAlternativesAttributeName; NSString *const NSTextEffectAttributeName; NSString *NSToolTipAttributeName; NSString *const NSUnderlineColorAttributeName; NSString *const NSUnderlineStyleAttributeName; NSString *const NSVerticalGlyphFormAttributeName; NSString *const NSWritingDirectionAttributeName;

    Constants

    • NSAttachmentAttributeName

      NSAttachmentAttributeName

      The value of this attribute is an NSTextAttachment object. The default value of this property is nil, indicating no attachment.

      Available in OS X v10.0 and later.

    • NSBackgroundColorAttributeName

      NSBackgroundColorAttributeName

      The value of this attribute is a UIColor object. Use this attribute to specify the color of the background area behind the text. If you do not specify this attribute, no background color is drawn.

      Available in OS X v10.0 and later.

    • NSBaselineOffsetAttributeName

      NSBaselineOffsetAttributeName

      The value of this attribute is an NSNumber object containing a floating point value indicating the character’s offset from the baseline, in points. The default value is 0.

      Available in OS X v10.0 and later.

    • NSCursorAttributeName

      NSCursorAttributeName

      The value of this attribute is an NSCursor object. The default value is the cursor returned by the IBeamCursor method

      Available in OS X v10.3 and later.

    • NSExpansionAttributeName

      NSExpansionAttributeName

      The value of this attribute is an NSNumber object containing a floating point value indicating the log of the expansion factor to be applied to glyphs. The default value is 0, indicating no expansion.

      Available in OS X v10.0 and later.

    • NSFontAttributeName

      NSFontAttributeName

      The value of this attribute is a UIFont object. Use this attribute to change the font for a range of text. If you do not specify this attribute, the string uses a 12-point Helvetica(Neue) font by default.

      Available in OS X v10.0 and later.

    • NSForegroundColorAttributeName

      NSForegroundColorAttributeName

      The value of this attribute is a UIColor object. Use this attribute to specify the color of the text during rendering. If you do not specify this attribute, the text is rendered in black.

      Available in OS X v10.0 and later.

    • NSKernAttributeName

      NSKernAttributeName

      The value of this attribute is an NSNumber object containing a floating-point value. This value specifies the number of points by which to adjust kern-pair characters. Kerning prevents unwanted space from occurring between specific characters and depends on the font. The value 0 means kerning is disabled. The default value for this attribute is 0.

      Available in OS X v10.0 and later.

    • NSLigatureAttributeName

      NSLigatureAttributeName

      The value of this attribute is an NSNumber object containing an integer. Ligatures cause specific character combinations to be rendered using a single custom glyph that corresponds to those characters. The value 0 indicates no ligatures. The value 1 indicates the use of the default ligatures. The value 2 indicates the use of all ligatures. The default value for this attribute is 1. (Value 2 is unsupported on iOS.)

      Available in OS X v10.0 and later.

    • NSLinkAttributeName

      NSLinkAttributeName

      The value of this attribute is and NSURL object (preferred) or an NSString object. The default value of this property is nil, indicating no link.

      Available in OS X v10.0 and later.

    • NSMarkedClauseSegmentAttributeName

      NSMarkedClauseSegmentAttributeName

      The value of this attribute is an NSNumber object containing an integer, as an index in marked text indicating clause segments

      Available in OS X v10.5 and later.

    • NSObliquenessAttributeName

      NSObliquenessAttributeName

      The value of this attribute is an NSNumber object containing a floating point value indicating skew to be applied to glyphs. The default value is 0, indicating no skew.

      Available in OS X v10.0 and later.

    • NSParagraphStyleAttributeName

      NSParagraphStyleAttributeName

      The value of this attribute is an NSParagraphStyle object. Use this attribute to apply multiple attributes to a range of text. If you do not specify this attribute, the string uses the default paragraph attributes, as returned by the defaultParagraphStyle method of NSParagraphStyle.

      Available in OS X v10.0 and later.

    • NSShadowAttributeName

      NSShadowAttributeName

      The value of this attribute is an NSShadow object. The default value of this property is nil.

      Available in OS X v10.0 and later.

    • NSSpellingStateAttributeName

      NSSpellingStateAttributeName

      The value of this attribute is an integer. Defaults to 0, indicating no grammar or spelling error.

      This key is available in OS X v10.2 and later, but its interpretation changed in OS X v10.5. Previously, any non-zero value caused the spelling indicator to be displayed. For OS X v10.5 and later, the (integer) value is treated as being composed of the spelling and grammar flags. See NSSpellingStateAttributeName Flags for possible values.

      Available in OS X v10.5 and later.

    • NSStrikethroughColorAttributeName

      NSStrikethroughColorAttributeName

      The value of this attribute is a UIColor object. The default value is nil, indicating same as foreground color.

      Available in OS X v10.0 and later.

    • NSStrikethroughStyleAttributeName

      NSStrikethroughStyleAttributeName

      The value of this attribute is an NSNumber object containing an integer. This value indicates whether the text has a line through it and corresponds to one of the constants described in NSUnderlineStyle. The default value for this attribute is NSUnderlineStyleNone.

      Available in OS X v10.0 and later.

    • NSStrokeColorAttributeName

      NSStrokeColorAttributeName

      The value of this parameter is a UIColor object. If it is not defined (which is the case by default), it is assumed to be the same as the value of NSForegroundColorAttributeName; otherwise, it describes the outline color. For more details, see Drawing attributed strings that are both filled and stroked.

      Available in OS X v10.0 and later.

    • NSStrokeWidthAttributeName

      NSStrokeWidthAttributeName

      The value of this attribute is an NSNumber object containing a floating-point value. This value represents the amount to change the stroke width and is specified as a percentage of the font point size. Specify 0 (the default) for no additional changes. Specify positive values to change the stroke width alone. Specify negative values to stroke and fill the text. For example, a typical value for outlined text would be 3.0.

      Available in OS X v10.0 and later.

    • NSSuperscriptAttributeName

      NSSuperscriptAttributeName

      The value of this attribute is an NSNumber object containing an integer. The default value is 0.

      Available in OS X v10.0 and later.

    • NSTextAlternativesAttributeName

      NSTextAlternativesAttributeName

      The value of this attribute is an NSTextAlternatives object representing alternatives for a string that may be presented to the user.

      Available in OS X v10.8 and later.

    • NSTextEffectAttributeName

      NSTextEffectAttributeName

      The value of this attribute is an NSString object. Use this attribute to specify a text effect, such as NSTextEffectLetterpressStyle. The default value of this property is nil, indicating no text effect.

      Available in OS X v10.10 and later.

    • NSToolTipAttributeName

      NSToolTipAttributeName

      The value of this attribute is an NSString object containing the tooltip text. The default value is nil, indicating no tooltip is available.

      Available in OS X v10.3 and later.

    • NSUnderlineColorAttributeName

      NSUnderlineColorAttributeName

      The value of this attribute is a UIColor object. The default value is nil, indicating same as foreground color.

      Available in OS X v10.0 and later.

    • NSUnderlineStyleAttributeName

      NSUnderlineStyleAttributeName

      The value of this attribute is an NSNumber object containing an integer. This value indicates whether the text is underlined and corresponds to one of the constants described in NSUnderlineStyle. The default value for this attribute is NSUnderlineStyleNone.

      Available in OS X v10.0 and later.

    • NSVerticalGlyphFormAttributeName

      NSVerticalGlyphFormAttributeName

      The value of this attribute is an NSNumber object containing an integer. The value 0 indicates horizontal text. The value 1 indicates vertical text. In iOS, horizontal text is always used and specifying a different value is undefined.

      Available in OS X v10.7 and later.

    • NSWritingDirectionAttributeName

      NSWritingDirectionAttributeName

      The value of this attribute is an NSArray object containing NSNumber objects representing the nested levels of writing direction overrides, in order from outermost to innermost.

      This attribute provides a means to override the default bidirectional text algorithm, equivalent to using the Unicode bidi control characters LRE, RLE, LRO, or RLO paired with PDF, but as a higher-level attribute. (See Unicode Standard Annex #9 for information about the Unicode bidi formatting codes.) The NSWritingDirectionAttributeName constant is a character-level attribute that provides a higher-level alternative to the inclusion of explicit bidirectional control characters in text. It is the NSAttributedString equivalent of the HTML markup using bdo element with the dir attribute.

      The values of the NSNumber objects should be 0, 1, 2, or 3, for LRE, RLE, LRO, or RLO respectively, and combinations of NSWritingDirectionLeftToRight and NSWritingDirectionRightToLeft with NSTextWritingDirectionEmbedding or NSTextWritingDirectionOverride, as shown in Table 1.

      Table 1Values of NSWritingDirectionAttributeName and equivalent markup

      Array NSNumber Values

      Unicode Control Characters

      Writing Direction Constants

      0

      LRE

      NSWritingDirectionLeftToRight | NSTextWritingDirectionEmbedding

      1

      RLE

      NSWritingDirectionRightToLeft | NSTextWritingDirectionEmbedding

      2

      LRO

      NSWritingDirectionLeftToRight | NSTextWritingDirectionOverride

      3

      RLO

      NSWritingDirectionRightToLeft | NSTextWritingDirectionOverride

      Available in OS X v10.6 and later.

  • This object provides a means to override the standard glyph generation.

    Declaration

    Swift

    let NSGlyphInfoAttributeName: String

    Objective-C

    NSString *NSGlyphInfoAttributeName;

    Constants

    • NSGlyphInfoAttributeName

      NSGlyphInfoAttributeName

      The name of an NSGlyphInfo object.

      The NSLayoutManager object assigns the glyph specified by this glyph info to the entire attribute range, provided that its contents match the specified base string, and that the specified glyph is available in the font specified by NSFontAttributeName.

      Available in OS X v10.2 and later.

  • The character shape feature type (kCharacterShapeType) is used when a single font contains different appearances for the same character shape, and these shapes are not traditionally treated as swashes. It is needed for languages such as Chinese that have both traditional and simplified character sets.

    Declaration

    Swift

    let NSCharacterShapeAttributeName: String

    Objective-C

    NSString *NSCharacterShapeAttributeName;

    Constants

    • NSCharacterShapeAttributeName

      NSCharacterShapeAttributeName

      An integer value. The value is interpreted as Apple Type Services kCharacterShapeType selector + 1.

      The default value is 0 (disable). 1 is kTraditionalCharactersSelector, and so on. Refer to <ATS/SFNTLayoutTypes.h> and Font Features in ATSUI Programming Guide for additional information.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.11.

  • The following values can be returned for the NSDocumentTypeDocumentAttribute key in the document attributes dictionary.

    Declaration

    Swift

    let NSPlainTextDocumentType: String let NSRTFTextDocumentType: String let NSRTFDTextDocumentType: String let NSMacSimpleTextDocumentType: String let NSHTMLTextDocumentType: String let NSDocFormatTextDocumentType: String let NSWordMLTextDocumentType: String let NSWebArchiveTextDocumentType: String let NSOfficeOpenXMLTextDocumentType: String let NSOpenDocumentTextDocumentType: String

    Objective-C

    NSString *NSPlainTextDocumentType; NSString *NSRTFTextDocumentType; NSString *NSRTFDTextDocumentType; NSString *NSMacSimpleTextDocumentType; NSString *NSHTMLTextDocumentType; NSString *NSDocFormatTextDocumentType; NSString *NSWordMLTextDocumentType; NSString *NSOfficeOpenXMLTextDocumentType; NSString *NSWebArchiveTextDocumentType; NSString *NSOpenDocumentTextDocumentType;

    Constants

    • NSPlainTextDocumentType

      NSPlainTextDocumentType

      Plain text document.

      Available in OS X v10.0 and later.

    • NSRTFTextDocumentType

      NSRTFTextDocumentType

      Rich text format document.

      Available in OS X v10.0 and later.

    • NSRTFDTextDocumentType

      NSRTFDTextDocumentType

      Rich text format with attachments document.

      Available in OS X v10.0 and later.

    • NSMacSimpleTextDocumentType

      NSMacSimpleTextDocumentType

      Macintosh SimpleText document.

      Available in OS X v10.0 and later.

    • NSHTMLTextDocumentType

      NSHTMLTextDocumentType

      Hypertext Markup Language (HTML) document.

      Available in OS X v10.0 and later.

    • NSDocFormatTextDocumentType

      NSDocFormatTextDocumentType

      Microsoft Word document.

      Available in OS X v10.3 and later.

    • NSWordMLTextDocumentType

      NSWordMLTextDocumentType

      Microsoft Word XML (WordML schema) document.

      Available in OS X v10.3 and later.

    • NSWebArchiveTextDocumentType

      NSWebArchiveTextDocumentType

      Web Kit WebArchive document.

      Available in OS X v10.4 and later.

    • NSOfficeOpenXMLTextDocumentType

      NSOfficeOpenXMLTextDocumentType

      ECMA Office Open XML text document format.

      Available in OS X v10.5 and later.

    • NSOpenDocumentTextDocumentType

      NSOpenDocumentTextDocumentType

      OASIS Open Document text document format.

      Available in OS X v10.5 and later.

    Discussion

    See also NSDocumentTypeDocumentOption.

  • The init... methods can return a dictionary with the following document-wide attributes (attribute identifiers available on OS X v10.4 and later; use actual string value keys for earlier systems):

    Declaration

    Swift

    let NSAuthorDocumentAttribute: String let NSBackgroundColorDocumentAttribute: String let NSBottomMarginDocumentAttribute: String let NSCategoryDocumentAttribute: String let NSCharacterEncodingDocumentAttribute: String let NSCocoaVersionDocumentAttribute: String let NSCompanyDocumentAttribute: String let NSCommentDocumentAttribute: String let NSConvertedDocumentAttribute: String let NSCopyrightDocumentAttribute: String let NSCreationTimeDocumentAttribute: String let NSDefaultAttributesDocumentAttribute: String let NSDefaultTabIntervalDocumentAttribute: String let NSDocumentTypeDocumentAttribute: String let NSEditorDocumentAttribute: String let NSFileTypeDocumentAttribute: String let NSFileTypeDocumentOption: String let NSHyphenationFactorDocumentAttribute: String let NSKeywordsDocumentAttribute: String let NSLeftMarginDocumentAttribute: String let NSManagerDocumentAttribute: String let NSModificationTimeDocumentAttribute: String let NSPaperSizeDocumentAttribute: String let NSReadOnlyDocumentAttribute: String let NSRightMarginDocumentAttribute: String let NSSubjectDocumentAttribute: String let NSTextLayoutSectionsAttribute: String let NSTitleDocumentAttribute: String let NSTopMarginDocumentAttribute: String let NSUsesScreenFontsDocumentAttribute: String let NSViewModeDocumentAttribute: String let NSViewSizeDocumentAttribute: String let NSViewZoomDocumentAttribute: String

    Objective-C

    NSString *NSAuthorDocumentAttribute; NSString *NSBackgroundColorDocumentAttribute; NSString *NSBottomMarginDocumentAttribute; NSString *NSCategoryDocumentAttribute; NSString *NSCharacterEncodingDocumentAttribute; NSString *NSCocoaVersionDocumentAttribute; NSString *NSCommentDocumentAttribute; NSString *NSCompanyDocumentAttribute; NSString *NSConvertedDocumentAttribute; NSString *NSCopyrightDocumentAttribute; NSString *NSCreationTimeDocumentAttribute; NSString *const NSDefaultAttributesDocumentAttribute; NSString *NSDefaultTabIntervalDocumentAttribute; NSString *NSDocumentTypeDocumentAttribute; NSString *NSEditorDocumentAttribute; NSString *NSFileTypeDocumentAttribute; NSString *NSFileTypeDocumentOption; NSString *NSHyphenationFactorDocumentAttribute; NSString *NSKeywordsDocumentAttribute; NSString *NSLeftMarginDocumentAttribute; NSString *NSManagerDocumentAttribute; NSString *NSModificationTimeDocumentAttribute; NSString *NSPaperSizeDocumentAttribute; NSString *NSReadOnlyDocumentAttribute; NSString *NSRightMarginDocumentAttribute; NSString *NSSubjectDocumentAttribute; NSString *const NSTextLayoutSectionsAttribute; NSString *NSTitleDocumentAttribute; NSString *NSTopMarginDocumentAttribute; NSString *NSUsesScreenFontsDocumentAttribute; NSString *NSViewModeDocumentAttribute; NSString *NSViewSizeDocumentAttribute; NSString *NSViewZoomDocumentAttribute;

    Constants

    • NSAuthorDocumentAttribute

      NSAuthorDocumentAttribute

      The value of this attribute is an NSString object containing author name.

      Available in OS X v10.4 and later.

    • NSBackgroundColorDocumentAttribute

      NSBackgroundColorDocumentAttribute

      The value of this attribute is an NSColor object representing the document-wide page background color.

      OS X v10.3 and earlier string constant is @"BackgroundColor".

      For applications linked on versions prior to OS X v10.5, HTML import sets the NSBackgroundColorDocumentAttribute to [NSColor whiteColor] in cases in which the HTML does not specify a background color. For applications linked on OS X v10.5 and later, no NSBackgroundColorDocumentAttribute is set in these cases.

      Available in OS X v10.0 and later.

    • NSBottomMarginDocumentAttribute

      NSBottomMarginDocumentAttribute

      The value of this attribute is an NSNumber object containing a float, in points.

      OS X v10.3 and earlier string constant is @"BottomMargin".

      Available in OS X v10.4 and later.

    • NSCategoryDocumentAttribute

      NSCategoryDocumentAttribute

      The value of this attribute is an NSString object containing the document’s category.

      Available in OS X v10.6 and later.

    • NSCharacterEncodingDocumentAttribute

      NSCharacterEncodingDocumentAttribute

      The value of this attribute is an NSNumber object containing integer specifying NSStringEncoding for the file; default for plain text is the default encoding. This key in options can specify the string encoding for reading the data. Upon return, the document attributes can contain the actual encoding used. For writing methods, this value is used for generating the plain text data.

      OS X v10.3 and earlier string constant is @"CharacterEncoding".

      Available in OS X v10.0 and later.

    • NSCocoaVersionDocumentAttribute

      NSCocoaVersionDocumentAttribute

      The value of this attribute is an NSNumber object containing a float. For RTF files only, stores the version of Cocoa with which the file was created. Absence of this value indicates RTF file not created by Cocoa or its predecessors.

      Values less than 100 are pre–OS X; 100 is OS X v10.0 or v10.1; 102 is OS X v10.2 and 10.3; values greater than 102 correspond to values of NSAppKitVersionNumber on OS X v10.4 and later.

      OS X v10.3 and earlier string constant is @"CocoaRTFVersion".

      Available in OS X v10.4 and later.

    • NSCompanyDocumentAttribute

      NSCompanyDocumentAttribute

      The value of this attribute is an NSString object containing company or organization name.

      Available in OS X v10.4 and later.

    • NSCommentDocumentAttribute

      NSCommentDocumentAttribute

      The value of this attribute is an NSString object containing document comments.

      Available in OS X v10.4 and later.

    • NSConvertedDocumentAttribute

      NSConvertedDocumentAttribute

      The value of this attribute is an NSNumber object containing an int. Indicates whether the file was converted by a filter service.

      If missing or 0, the file was originally in the format specified by document type. If negative, the file was originally in the format specified by document type, but the conversion to NSAttributedString may have been lossy. If 1 or more, it was converted to this type by a filter service.

      OS X v10.3 and earlier string constant is @"Converted".

      Available in OS X v10.4 and later.

    • NSCopyrightDocumentAttribute

      NSCopyrightDocumentAttribute

      The value of this attribute is an NSString object containing document copyright info.

      Available in OS X v10.4 and later.

    • NSCreationTimeDocumentAttribute

      NSCreationTimeDocumentAttribute

      The value of this attribute is an NSDate object containing the creation date of the document; note that this is not the file system creation date of the file, but of the document.

      Available in OS X v10.4 and later.

    • NSDefaultAttributesDocumentAttribute

      NSDefaultAttributesDocumentAttribute

      The value of this attribute is an NSDictionary object containing attributes to be applied to plain files. Used by reader methods. This key in options can specify the default attributes applied to the entire document contents. Upon return, the document attributes can contain this key indicating the actual attributes used. @"DefaultAttributes"

      Available in OS X v10.11 and later.

    • NSDefaultTabIntervalDocumentAttribute

      NSDefaultTabIntervalDocumentAttribute

      The value of this attribute is an NSNumber object containing a float. Represents the document-wide default tab stop interval.

      OS X v10.3 and earlier string constant is @"DefaultTabInterval".

      Available in OS X v10.0 and later.

    • NSDocumentTypeDocumentAttribute

      NSDocumentTypeDocumentAttribute

      The value of this attribute is one of the document types declared in Document Types. For reader methods, this key in options can specify the document type for interpreting the contents. Upon return, the document attributes can contain this key for indicating the actual format used to read the contents. For write methods, this key specifies the format for generating the data. @"DocumentType",

      Available in OS X v10.0 and later.

    • NSEditorDocumentAttribute

      NSEditorDocumentAttribute

      The value of this attribute is an NSString object containing name of person who last edited the document.

      Available in OS X v10.4 and later.

    • NSFileTypeDocumentAttribute

      NSFileTypeDocumentAttribute

      The value of this attribute is an NSString object indicating which document type was used to interpret the document, specified as a UTI; for reading, this is available along with NSDocumentTypeDocumentAttribute, but for writing the two are mutually exclusive.

      Available in OS X v10.6 and later.

    • NSFileTypeDocumentOption

      NSFileTypeDocumentOption

      The value of this attribute is an NSString object indicating a document type to be forced when loading the document, specified as a UTI string; mutually exclusive with NSDocumentTypeDocumentOption.

      Available in OS X v10.6 and later.

    • NSHyphenationFactorDocumentAttribute

      NSHyphenationFactorDocumentAttribute

      The value of this attribute is an NSNumber object containing a float; 0 = off, 1 = full hyphenation.

      OS X v10.3 and earlier string constant is @"HyphenationFactor".

      Available in OS X v10.0 and later.

    • NSKeywordsDocumentAttribute

      NSKeywordsDocumentAttribute

      The value of this attribute is an NSArray object containing NSString objects, containing keywords.

      Available in OS X v10.4 and later.

    • NSLeftMarginDocumentAttribute

      NSLeftMarginDocumentAttribute

      The value of this attribute is an NSNumber object containing a float, in points.

      OS X v10.3 and earlier string constant is @"LeftMargin".

      Available in OS X v10.4 and later.

    • NSManagerDocumentAttribute

      NSManagerDocumentAttribute

      The value of this attribute is an NSString object containing the name of the author's manager.

      Available in OS X v10.5 and later.

    • NSModificationTimeDocumentAttribute

      NSModificationTimeDocumentAttribute

      The value of this attribute is an NSDate object containing the modification date of the document contents.

      Available in OS X v10.4 and later.

    • NSPaperSizeDocumentAttribute

      NSPaperSizeDocumentAttribute

      The value of this attribute is an NSValue object containing NSSize.

      OS X v10.3 and earlier string constant is @"PaperSize".

      Available in OS X v10.0 and later.

    • NSReadOnlyDocumentAttribute

      NSReadOnlyDocumentAttribute

      The value of this attribute is an NSNumber object containing an integer. If missing or 0 or negative, not read only; 1 or more, read only.

      Note that this has nothing to do with the file system protection on the file, but instead can affect how the file should be displayed to the user.

      OS X v10.3 and earlier string constant is @"ReadOnly".

      Available in OS X v10.0 and later.

    • NSRightMarginDocumentAttribute

      NSRightMarginDocumentAttribute

      The value of this attribute is an NSNumber object containing a float, in points.

      OS X v10.3 and earlier string constant is @"RightMargin".

      Available in OS X v10.4 and later.

    • NSSubjectDocumentAttribute

      NSSubjectDocumentAttribute

      The value of this attribute is an NSString object containing subject of document.

      Available in OS X v10.4 and later.

    • NSTextLayoutSectionsAttribute

      NSTextLayoutSectionsAttribute

      An NSArray containing NSDictionary objects, each dictionary describing a layout orientation section. The dictionary can have two attributes: NSTextLayoutSectionOrientation and NSTextLayoutSectionRange. When there is a gap between sections, it's assumed to have NSTextLayoutOrientationHorizontal.

      Available in OS X v10.7 and later.

    • NSTitleDocumentAttribute

      NSTitleDocumentAttribute

      The value of this attribute is an NSString object containing document title.

      Available in OS X v10.4 and later.

    • NSTopMarginDocumentAttribute

      NSTopMarginDocumentAttribute

      The value of this attribute is an NSNumber object containing a float, in points.

      OS X v10.3 and earlier string constant is @"TopMargin".

      Available in OS X v10.4 and later.

    • NSUsesScreenFontsDocumentAttribute

      NSUsesScreenFontsDocumentAttribute

      The value of this attribute is an NSNumber object containing a Boolean; this attribute corresponds to the usesScreenFonts method of NSLayoutManager; if absent, follows the system default setting

      Available in OS X v10.8 and later.

      Deprecated in OS X v10.11.

    • NSViewModeDocumentAttribute

      NSViewModeDocumentAttribute

      The value of this attribute is an NSValue object containing an int; 0 = normal; 1 = page layout (use value of @"PaperSize").

      OS X v10.3 and earlier string constant is @"ViewMode".

      Available in OS X v10.0 and later.

    • NSViewSizeDocumentAttribute

      NSViewSizeDocumentAttribute

      The value of this attribute is an NSValue object containing NSSize.

      OS X v10.3 and earlier string constant is @"ViewSize".

      Available in OS X v10.0 and later.

    • NSViewZoomDocumentAttribute

      NSViewZoomDocumentAttribute

      The value of this attribute is an NSValue object containing a float. 100 = 100% zoom.

      OS X v10.3 and earlier string constant is @"ViewZoom".

      Available in OS X v10.0 and later.

  • These document-wide attributes provide control over the form of generated HTML—you use them only for writing HTML

    Declaration

    Swift

    let NSExcludedElementsDocumentAttribute: String let NSTextEncodingNameDocumentAttribute: String let NSPrefixSpacesDocumentAttribute: String

    Objective-C

    NSString *NSExcludedElementsDocumentAttribute; NSString *NSTextEncodingNameDocumentAttribute; NSString *NSPrefixSpacesDocumentAttribute;

    Constants

    • NSExcludedElementsDocumentAttribute

      NSExcludedElementsDocumentAttribute

      An NSArray object containing NSString objects, representing HTML elements not to be used in generated HTML.

      Available in OS X v10.4 and later.

    • NSTextEncodingNameDocumentAttribute

      NSTextEncodingNameDocumentAttribute

      An NSString object containing the name, IANA or otherwise, of a text encoding to be used; mutually exclusive with NSCharacterEncodingDocumentAttribute.

      Available in OS X v10.4 and later.

    • NSPrefixSpacesDocumentAttribute

      NSPrefixSpacesDocumentAttribute

      An NSNumber object containing an integer (default 0) representing the number of spaces per level by which to indent certain nested HTML elements.

      Available in OS X v10.4 and later.

    Discussion

    NSExcludedElementsDocumentAttribute allows control over the tags used. The recognized values in the NSExcludedElementsDocumentAttribute array are (case-insensitive) HTML tags, plus DOCTYPE (representing a doctype declaration) and XML (representing an XML declaration). By default, if this attribute is not present, the excluded elements will be those deprecated in HTML 4 (APPLET, BASEFONT, CENTER, DIR, FONT, ISINDEX, MENU, S, STRIKE, and U) plus XML. If XML is on the list, HTML forms are used; if XML is not on the list, XHTML forms are used where there is a distinction. Either NSCharacterEncodingDocumentAttribute or NSTextEncodingNameDocumentAttribute may be used to control the encoding used for generated HTML; character entities are used for characters not representable in the specified encoding. NSPrefixSpacesDocumentAttribute allows some control over formatting.

  • Declaration

    Swift

    let NSCharacterEncodingDocumentOption: String let NSBaseURLDocumentOption: String let NSDefaultAttributesDocumentOption: String let NSDocumentTypeDocumentOption: String let NSTextEncodingNameDocumentOption: String let NSTimeoutDocumentOption: String let NSWebPreferencesDocumentOption: String let NSWebResourceLoadDelegateDocumentOption: String let NSTextSizeMultiplierDocumentOption: String

    Objective-C

    NSString *NSBaseURLDocumentOption; NSString *NSCharacterEncodingDocumentOption; NSString *NSDefaultAttributesDocumentOption; NSString *NSDocumentTypeDocumentOption; NSString *NSTextEncodingNameDocumentOption; NSString *NSTextSizeMultiplierDocumentOption; NSString *NSTimeoutDocumentOption; NSString *NSWebPreferencesDocumentOption; NSString *NSWebResourceLoadDelegateDocumentOption;

    Constants

    • NSCharacterEncodingDocumentOption

      NSCharacterEncodingDocumentOption

      For plain text documents; NSNumber containing the unsigned int NSStringEncoding to override any encoding specified in an HTML document. Previous string constant was @"CharacterEncoding".

      Available in OS X v10.4 and later.

    • NSBaseURLDocumentOption

      NSBaseURLDocumentOption

      For HTML documents; NSURL containing base URL. Previous string constant was @"BaseURL"

      Available in OS X v10.4 and later.

    • NSDefaultAttributesDocumentOption

      NSDefaultAttributesDocumentOption

      For plain text documents; NSDictionary containing attributes to be applied to plain files. Previous string constant was @"DefaultAttributes".

      Available in OS X v10.4 and later.

    • NSDocumentTypeDocumentOption

      NSDocumentTypeDocumentOption

      One of the document types described in Document Types, indicating a document type to be forced when loading the document. Previous string constant was @"DocumentType".

      Available in OS X v10.4 and later.

    • NSTextEncodingNameDocumentOption

      NSTextEncodingNameDocumentOption

      NSString containing the name, IANA or otherwise, of a text encoding to override any encoding specified in an HTML document. Mutually exclusive with @"CharacterEncoding". Previous string constant was @"TextEncodingName".

      Available in OS X v10.4 and later.

    • NSTimeoutDocumentOption

      NSTimeoutDocumentOption

      NSNumber containing float. Time in seconds to wait for a document to finish loading. Previous string constant was @"Timeout".

      Available in OS X v10.4 and later.

    • NSWebPreferencesDocumentOption

      NSWebPreferencesDocumentOption

      WebPreferences; for HTML only, specifies a WebPreferences object. If not present, a default set of preferences is used. Previous string constant was @"WebPreferences".

      Available in OS X v10.4 and later.

    • NSWebResourceLoadDelegateDocumentOption

      NSWebResourceLoadDelegateDocumentOption

      NSObject; for HTML only, specifies an object to serve as the web resource loading delegate.

      If not present, a default delegate is used that permits the loading of subsidiary resources but does not respond to authentication challenges. Previous string constant was @"WebResourceLoadDelegate".

      Available in OS X v10.4 and later.

    • NSTextSizeMultiplierDocumentOption

      NSTextSizeMultiplierDocumentOption

      Specifies a scale factor for font sizes. NSNumber containing float, default 1.0; for HTML only, corresponding to WebView's textSizeMultiplier.

      There is no textual equivalent for OS X v10.3.

      Available in OS X v10.4 and later.

    Discussion

    In OS X v10.3, the options key @"UseWebKit" specifies that WebKit–based HTML importing be used (and must be specified for the other options to be recognized). In OS X v10.4 and later, WebKit is always used for HTML documents, and all of the options except @"UseWebKit" are recognized (attribute identifiers are available on OS X v10.4 and later; use actual string value keys for OS X v10.3):

  • These constants are used by NSTextLayoutSectionsAttribute.

    Declaration

    Swift

    let NSTextLayoutSectionOrientation: String let NSTextLayoutSectionRange: String

    Objective-C

    NSString *NSTextLayoutSectionOrientation; NSString *NSTextLayoutSectionRange;

    Constants

    • NSTextLayoutSectionOrientation

      NSTextLayoutSectionOrientation

      An NSNumber object containing an NSTextLayoutOrientation value. The default value is NSTextLayoutOrientationHorizontal.

      Available in OS X v10.7 and later.

    • NSTextLayoutSectionRange

      NSTextLayoutSectionRange

      An NSValue object containing an NSRange representing a character range. The default value is a range covering the entire string.

      Available in OS X v10.7 and later.

  • This constant is used by NSTextEffectAttributeName.

    Declaration

    Swift

    let NSTextEffectLetterpressStyle: String

    Objective-C

    NSString *const NSTextEffectLetterpressStyle;

    Constants

    • NSTextEffectLetterpressStyle

      NSTextEffectLetterpressStyle

      A graphical text effect giving glyphs the appearance of letterpress printing, in which type is pressed into the paper.

      Available in OS X v10.10 and later.

  • These constants control the display of the spelling and grammar indicators on text, highlighting portions of the text that are flagged for spelling or grammar issues. These regions are denoted by a temporary attribute on the layout manager, using the NSSpellingStateAttributeName key.

    Declaration

    Swift

    var NSSpellingStateSpellingFlag: Int { get } var NSSpellingStateGrammarFlag: Int { get }

    Objective-C

    enum { NSSpellingStateSpellingFlag = (1 << 0), NSSpellingStateGrammarFlag = (1 << 1) };

    Constants

    • NSSpellingStateSpellingFlag

      NSSpellingStateSpellingFlag

      Flag for spelling issues.

      Available in OS X v10.5 and later.

    • NSSpellingStateGrammarFlag

      NSSpellingStateGrammarFlag

      Flag for grammar issues.

      Available in OS X v10.5 and later.

  • These constants define the underline mask.

    Use NSStrikethroughStyleAttributeName instead.

    Declaration

    Objective-C

    enum { NSNoUnderlineStyle = 0, NSSingleUnderlineStyle }; NSUInteger NSUnderlineStrikethroughMask;

    Constants

    • NSNoUnderlineStyle

      Deprecated. Use NSUnderlineStyleNone instead.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    • NSSingleUnderlineStyle

      Deprecated. Use NSUnderlineStyleSingle instead.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

  • This constant defines the underlining style for NSUnderlineStyleAttributeName and NSStrikethroughStyleAttributeName.

    Declaration

    Swift

    var NSUnderlineByWordMask: Int

    Objective-C

    unsigned NSUnderlineByWordMask;

    Constants

    • NSUnderlineByWordMask

      NSUnderlineByWordMask

      Draw the underline only underneath words, not underneath whitespace.

      Use the NSUnderlineByWord constant instead.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.11.

    Discussion

    Use this constant with the desired underline style to create the given effect. For example, to get a thick underline only underneath words, set NSUnderlineStyleAttribute to (NSUnderlineStyleThick | NSUnderlineByWordMask). Also see NSUnderlineStyle.