Mac Developer Library

Developer

AppKit Framework Reference NSAttributedString AppKit Additions Reference

Options
Deployment Target:

On This Page
Language:

NSAttributedString

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.

The Application Kit extends Foundation’s NSAttributedString class by adding support for RTF, RTFD, and HTML (with or without attachments), graphics attributes (including font and ruler attributes), methods for drawing attributed strings, and methods for calculating significant linguistic units.

  • Creates an attributed string with an attachment.

    Declaration

    Swift

    init(attachment attachment: NSTextAttachment) -> NSAttributedString

    Objective-C

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

    Parameters

    attachment

    The attachment.

    Return Value

    An attributed string containing the attachment.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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: [NSObject : AnyObject]?, documentAttributes docAttributes: AutoreleasingUnsafeMutablePointer<NSDictionary?>, error error: NSErrorPointer)

    Objective-C

    - (instancetype)initWithData:(NSData *)data options:(NSDictionary *)options documentAttributes:(NSDictionary **)docAttributes error:(NSError **)error

    Parameters

    data

    The data from which to create the string.

    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

    If the options dictionary contains NSDocumentTypeDocumentOption, 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 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 docAttributes: AutoreleasingUnsafeMutablePointer<NSDictionary?>)

    Objective-C

    - (instancetype)initWithDocFormat:(NSData *)data documentAttributes:(NSDictionary **)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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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 docAttributes: AutoreleasingUnsafeMutablePointer<NSDictionary?>)

    Objective-C

    - (instancetype)initWithHTML:(NSData *)data documentAttributes:(NSDictionary **)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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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 aURL: NSURL, documentAttributes docAttributes: AutoreleasingUnsafeMutablePointer<NSDictionary?>)

    Objective-C

    - (instancetype)initWithHTML:(NSData *)data baseURL:(NSURL *)aURL documentAttributes:(NSDictionary **)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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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 **)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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

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

    Objective-C

    - (instancetype)initWithPath:(NSString *)path documentAttributes:(NSDictionary **)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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 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 rtfData: NSData, documentAttributes docAttributes: AutoreleasingUnsafeMutablePointer<NSDictionary?>)

    Objective-C

    - (instancetype)initWithRTF:(NSData *)rtfData documentAttributes:(NSDictionary **)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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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 rtfdData: NSData, documentAttributes docAttributes: AutoreleasingUnsafeMutablePointer<NSDictionary?>)

    Objective-C

    - (instancetype)initWithRTFD:(NSData *)rtfdData documentAttributes:(NSDictionary **)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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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 docAttributes: AutoreleasingUnsafeMutablePointer<NSDictionary?>)

    Objective-C

    - (instancetype)initWithRTFDFileWrapper:(NSFileWrapper *)wrapper documentAttributes:(NSDictionary **)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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    init?(URL aURL: NSURL, documentAttributes docAttributes: AutoreleasingUnsafeMutablePointer<NSDictionary?>)

    Objective-C

    - (instancetype)initWithURL:(NSURL *)aURL documentAttributes:(NSDictionary **)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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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: [NSObject : AnyObject]?, documentAttributes docAttributes: AutoreleasingUnsafeMutablePointer<NSDictionary?>, error error: NSErrorPointer)

    Objective-C

    - (instancetype)initWithURL:(NSURL *)url options:(NSDictionary *)options documentAttributes:(NSDictionary **)docAttributes error:(NSError **)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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns whether the attribute string contains any attachment attributes.

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the font attributes in effect for the character at the given location.

    Declaration

    Swift

    func fontAttributesInRange(_ aRange: NSRange) -> [NSObject : AnyObject]

    Objective-C

    - (NSDictionary *)fontAttributesInRange:(NSRange)aRange

    Parameters

    aRange

    The range.

    Return Value

    A dictionary containing the font attributes for the range.

    Discussion

    The dictionary attributes are all those listed in “Standard Attributes”, except NSLinkAttributeName, NSParagraphStyleAttributeName, and NSAttachmentAttributeName.

    Use this method to obtain font attributes that are to be copied or pasted with “copy font” operations.

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the ruler (paragraph) attributes in effect for the characters within the given range.

    Declaration

    Swift

    func rulerAttributesInRange(_ aRange: NSRange) -> [NSObject : AnyObject]?

    Objective-C

    - (NSDictionary *)rulerAttributesInRange:(NSRange)aRange

    Parameters

    aRange

    The range.

    Return Value

    A dictionary containing the ruler attributes in the range.

    Discussion

    The only ruler attribute currently defined is that named by NSParagraphStyleAttributeName. Use this method to obtain attributes that are to be copied or pasted with “copy ruler” operations.

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 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(_ index: 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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(_ index: 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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(_ index: Int, forward flag: 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns an data object that contains a text stream corresponding to the characters and attributes within the given range.

    Declaration

    Swift

    func dataFromRange(_ range: NSRange, documentAttributes docAttributes: [NSObject : AnyObject], error error: NSErrorPointer) -> NSData?

    Objective-C

    - (NSData *)dataFromRange:(NSRange)range documentAttributes:(NSDictionary *)docAttributes error:(NSError **)error

    Parameters

    range

    The range.

    docAttributes

    A required dictionary specifying the document attributes. The dictionary contains values from Document Types and must at least contain NSDocumentTypeDocumentAttribute.

    error

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

    Return Value

    Returns the data for the attributed string, or nil if failure. When nil, error encapsulates the error information.

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns an NSFileWrapper object that contains a text stream corresponding to the characters and attributes within the given range.

    Declaration

    Swift

    func fileWrapperFromRange(_ range: NSRange, documentAttributes docAttributes: [NSObject : AnyObject], error error: NSErrorPointer) -> NSFileWrapper?

    Objective-C

    - (NSFileWrapper *)fileWrapperFromRange:(NSRange)range documentAttributes:(NSDictionary *)docAttributes error:(NSError **)error

    Parameters

    range

    The range.

    docAttributes

    A required dictionary specifying the document attributes. The dictionary contains values from Document Types and must at least contain NSDocumentTypeDocumentAttribute.

    error

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

    Return Value

    Returns a file wrapper for the appropriate document type, or nil if failure. When nil, error encapsulates the error information.

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns a data object that contains a Microsoft Word–format stream corresponding to the characters and attributes within the specified range.

    Declaration

    Swift

    func docFormatFromRange(_ range: NSRange, documentAttributes docAttributes: [NSObject : AnyObject]?) -> NSData?

    Objective-C

    - (NSData *)docFormatFromRange:(NSRange)range documentAttributes:(NSDictionary *)docAttributes

    Parameters

    range

    The range.

    docAttributes

    A required dictionary specifying the document attributes. The dictionary contains values from Document Types and must at least contain NSDocumentTypeDocumentAttribute. If there are no document-level attributes, dict can be nil.

    Return Value

    Returns a data object containing the attributed string as a Microsoft Word doc file..

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Returns an NSData object that contains an RTF stream corresponding to the characters and attributes within the given range, omitting all attachment attributes.

    Declaration

    Swift

    func RTFFromRange(_ aRange: NSRange, documentAttributes docAttributes: [NSObject : AnyObject]?) -> NSData?

    Objective-C

    - (NSData *)RTFFromRange:(NSRange)aRange documentAttributes:(NSDictionary *)docAttributes

    Parameters

    aRange

    The range.

    docAttributes

    A required dictionary specifying the document attributes. The dictionary contains values from Document Types and must at least contain NSDocumentTypeDocumentAttribute. If there are no document-level attributes, dict can be nil.

    Return Value

    A data object containing an RTF stream for the attributed string..

    Discussion

    Writes the document-level attributes in docAttributes, as explained in RTF Files and Attributed Strings.

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

    When writing data to the pasteboard, you can use the NSData object as the first argument to the NSPasteboard method setData:forType:, with a second argument of NSRTFPboardType. Although this method strips attachments, it leaves the attachment characters in the text itself. The NSText method RTFFromRange:, on the other hand, does strip attachment characters when extracting RTF.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns an data object that contains an RTFD stream corresponding to the characters and attributes within the range.

    Declaration

    Swift

    func RTFDFromRange(_ aRange: NSRange, documentAttributes docAttributes: [NSObject : AnyObject]?) -> NSData?

    Objective-C

    - (NSData *)RTFDFromRange:(NSRange)aRange documentAttributes:(NSDictionary *)docAttributes

    Parameters

    aRange

    The range.

    docAttributes

    A required dictionary specifying the document attributes. The dictionary contains values from Document Types and must at least contain NSDocumentTypeDocumentAttribute. If there are no document-level attributes, dict can be nil.

    Return Value

    A data object containing the RTFD stream containing the characters and attributes.

    Discussion

    Writes the document-level attributes in docAttributes, as explained in RTF Files and Attributed Strings.

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

    When writing data to the pasteboard, you can use the NSData object as the first argument to the NSPasteboard method setData:forType:, with a second argument of NSRTFDPboardType.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns an NSFileWrapper object that contains an RTFD document corresponding to the characters and attributes within the given range.

    Declaration

    Swift

    func RTFDFileWrapperFromRange(_ aRange: NSRange, documentAttributes docAttributes: [NSObject : AnyObject]?) -> NSFileWrapper?

    Objective-C

    - (NSFileWrapper *)RTFDFileWrapperFromRange:(NSRange)aRange documentAttributes:(NSDictionary *)docAttributes

    Parameters

    aRange

    The range.

    docAttributes

    A required dictionary specifying the document attributes. The dictionary contains values from Document Types and must at least contain NSDocumentTypeDocumentAttribute. If there are no document-level attributes, dict can be nil.

    Return Value

    A file wrapper containing the RTFD data.

    Discussion

    The file wrapper also includes the document-level attributes in docAttributes, as explained in RTF Files and Attributed Strings.

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

    You can save the file wrapper using the NSFileWrapper method writeToFile:atomically:updateFilenames:.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Draws the receiver with its font and other display attributes at the given point in the currently focused view.

    Declaration

    Swift

    func drawAtPoint(_ point: NSPoint)

    Objective-C

    - (void)drawAtPoint:(NSPoint)point

    Parameters

    point

    The point in the current view to draw the text.

    Discussion

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

    Don’t invoke this method when no NSView is focused.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Draws the attributed string within the given rectangle in the currently view, clipping the text layout to this rectangle.

    Declaration

    Swift

    func drawInRect(_ rect: NSRect)

    Objective-C

    - (void)drawInRect:(NSRect)rect

    Parameters

    rect

    The rectangle in which to draw.

    Discussion

    Text is drawn within rect according to its line sweep direction; for example, Arabic text will begin at the right edge and potentially be clipped on the left.

    The rect parameter determines how many glyphs are typeset within the width of a line, but it’s 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.

    If the focus view is flipped, the text origin is set at the upper-left corner of the drawing bounding box; otherwise the origin is set at the lower-left corner. For text rendering, whether the view coordinates are flipped or not doesn't affect the flow of line layout, which goes from top to bottom. However, it affects the interpretation of the text origin. So, 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 not.

    Don’t invoke this method when no NSView is focused.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    lockFocus (NSView)
    – drawAtPoint:

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

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

    See Also

    – drawAtPoint: (NSView)
    lockFocus

  • Returns the bounding box of the marks that the receiver draws.

    Declaration

    Swift

    var size: NSSize { get }

    Objective-C

    @property(readonly) NSSize size

    Return Value

    Returns the size of the bounding box of the drawn attributed string.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

    See Also

    – drawInRect:

  • 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() -> [AnyObject]

    Objective-C

    + (NSArray *)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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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() -> [AnyObject]

    Objective-C

    + (NSArray *)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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • 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 NSOpenPanel method runModalForTypes:.

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

    Import Statement

    Objective-C

    @import AppKit;

    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. The array returned by this method may be passed directly to NSOpenPanel method runModalForTypes:.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.1 and later.

    Deprecated in OS X v10.5.

    See Also

    + textFileTypes

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

    Import Statement

    Objective-C

    @import AppKit;

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.1 and later.

    Deprecated in OS X v10.5.

  • Attributed strings support the following standard attributes for text. If the key is not in the dictionary, then use the default values described below.

    Declaration

    Swift

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

    Objective-C

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

    Constants

    • NSFontAttributeName

      NSFontAttributeName

      NSFont

      Default Helvetica 12-point

      Available in OS X v10.0 and later.

    • NSParagraphStyleAttributeName

      NSParagraphStyleAttributeName

      NSParagraphStyle

      Default as returned by the NSParagraphStyle method defaultParagraphStyle

      Available in OS X v10.0 and later.

    • NSForegroundColorAttributeName

      NSForegroundColorAttributeName

      NSColor

      Default blackColor

      Available in OS X v10.0 and later.

    • NSUnderlineStyleAttributeName

      NSUnderlineStyleAttributeName

      NSNumber containing integer

      Default 0, no underline. See “Underlining Patterns”, “Underlining Styles”, and “Underline Masks” for mask values.

      Available in OS X v10.0 and later.

    • NSSuperscriptAttributeName

      NSSuperscriptAttributeName

      NSNumber containing integer

      Default 0

      Available in OS X v10.0 and later.

    • NSBackgroundColorAttributeName

      NSBackgroundColorAttributeName

      NSColor

      Default nil, no background

      Available in OS X v10.0 and later.

    • NSAttachmentAttributeName

      NSAttachmentAttributeName

      NSTextAttachment

      Default nil, no attachment

      Available in OS X v10.0 and later.

    • NSLigatureAttributeName

      NSLigatureAttributeName

      NSNumber containing integer

      Default 1, standard ligatures; 0, no ligatures; 2, all ligatures

      Available in OS X v10.0 and later.

    • NSBaselineOffsetAttributeName

      NSBaselineOffsetAttributeName

      NSNumber containing floating point value, as points offset from baseline

      Default 0.0

      Available in OS X v10.0 and later.

    • NSKernAttributeName

      NSKernAttributeName

      NSNumber containing floating point value, as points by which to modify default kerning

      Default nil, use default kerning specified in font file; 0.0, kerning off; non-zero, points by which to modify default kerning

      Available in OS X v10.0 and later.

    • NSLinkAttributeName

      NSLinkAttributeName

      NSURL (preferred) or NSString

      Default nil, no link

      Available in OS X v10.0 and later.

    • NSStrokeWidthAttributeName

      NSStrokeWidthAttributeName

      NSNumber containing floating point value, as percent of font point size

      Default 0, no stroke; positive, stroke alone; negative, stroke and fill (a typical value for outlined text would be 3.0)

      Available in OS X v10.3 and later.

    • NSStrokeColorAttributeName

      NSStrokeColorAttributeName

      NSColor

      Default nil, same as foreground color

      Available in OS X v10.3 and later.

    • NSUnderlineColorAttributeName

      NSUnderlineColorAttributeName

      NSColor

      Default nil, same as foreground color

      Available in OS X v10.3 and later.

    • NSStrikethroughStyleAttributeName

      NSStrikethroughStyleAttributeName

      NSNumber containing integer

      Default 0, no strikethrough. See “Underlining Patterns”, “Underlining Styles”, and “Underline Masks” for mask values.

      Available in OS X v10.3 and later.

    • NSStrikethroughColorAttributeName

      NSStrikethroughColorAttributeName

      NSColor

      Default nil, same as foreground color

      Available in OS X v10.3 and later.

    • NSShadowAttributeName

      NSShadowAttributeName

      NSShadow

      Default nil, no shadow

      Available in OS X v10.3 and later.

    • NSObliquenessAttributeName

      NSObliquenessAttributeName

      NSNumber containing floating point value, as skew to be applied to glyphs

      Default 0.0, no skew

      Available in OS X v10.3 and later.

    • NSExpansionAttributeName

      NSExpansionAttributeName

      NSNumber containing floating point value, as log of expansion factor to be applied to glyphs

      Default 0.0, no expansion

      Available in OS X v10.3 and later.

    • NSCursorAttributeName

      NSCursorAttributeName

      NSCursor

      Default as returned by the NSCursor method IBeamCursor

      Available in OS X v10.3 and later.

    • NSToolTipAttributeName

      NSToolTipAttributeName

      NSString

      Default nil, no tooltip

      Available in OS X v10.3 and later.

    • NSMarkedClauseSegmentAttributeName

      NSMarkedClauseSegmentAttributeName

      NSNumber containing an integer, as an index in marked text indicating clause segments

      Available in OS X v10.5 and later.

    • NSWritingDirectionAttributeName

      NSWritingDirectionAttributeName

      An NSArray of NSNumber objects.

      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 value of NSWritingDirectionAttributeName is an NSArray of NSNumber objects. The array represents nested embeddings or overrides, in order from outermost to innermost.

      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

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

    • NSVerticalGlyphFormAttributeName

      NSVerticalGlyphFormAttributeName

      An NSNumber containing an integer value, 0 means horizontal text and 1 indicates vertical text. If no value specified, it's interpreted to determine the setting based on higher-level vertical orientation settings such as NSTextLayoutOrientation . The behavior for any other value is undefined.

      Available in OS X v10.7 and later.

    • NSTextAlternativesAttributeName

      NSTextAlternativesAttributeName

      An NSTextAlternatives object. Used primarily as a temporary attribute, with primaryString equal to the substring for the range to which it is attached, and alternativeStrings representing alternatives for that string that may be presented to the user.

      Available in OS X v10.8 and later.

  • These constants define underlining style values for NSUnderlineStyleAttributeName and NSStrikethroughStyleAttributeName.

    Declaration

    Swift

    var NSUnderlineStyleNone: Int { get } var NSUnderlineStyleSingle: Int { get } var NSUnderlineStyleThick: Int { get } var NSUnderlineStyleDouble: Int { get }

    Objective-C

    enum { NSUnderlineStyleNone = 0x00, NSUnderlineStyleSingle = 0x01, NSUnderlineStyleThick = 0x02, NSUnderlineStyleDouble = 0x09 };

    Constants

    • NSUnderlineStyleNone

      NSUnderlineStyleNone

      Do not draw an underline.

      Available in OS X v10.3 and later.

    • NSUnderlineStyleSingle

      NSUnderlineStyleSingle

      Draw an underline consisting of a single line.

      Available in OS X v10.3 and later.

    • NSUnderlineStyleThick

      NSUnderlineStyleThick

      Draw an underline consisting of a thick line.

      Available in OS X v10.3 and later.

    • NSUnderlineStyleDouble

      NSUnderlineStyleDouble

      Draw an underline consisting of a double line.

      Available in OS X v10.3 and later.

    Discussion

    See also “Underline Masks” and “Underlining Patterns”. The style, pattern, and optionally by-word mask are OR'd together to produce the value for NSUnderlineStyleAttributeName and NSStrikethroughStyleAttributeName.

  • These constants define underlining pattern values for NSUnderlineStyleAttributeName and NSStrikethroughStyleAttributeName.

    Declaration

    Swift

    var NSUnderlinePatternSolid: Int { get } var NSUnderlinePatternDot: Int { get } var NSUnderlinePatternDash: Int { get } var NSUnderlinePatternDashDot: Int { get } var NSUnderlinePatternDashDotDot: Int { get }

    Objective-C

    enum { NSUnderlinePatternSolid = 0x0000, NSUnderlinePatternDot = 0x0100, NSUnderlinePatternDash = 0x0200, NSUnderlinePatternDashDot = 0x0300, NSUnderlinePatternDashDotDot = 0x0400 };

    Constants

    • NSUnderlinePatternSolid

      NSUnderlinePatternSolid

      Draw a solid underline.

      Available in OS X v10.3 and later.

    • NSUnderlinePatternDot

      NSUnderlinePatternDot

      Draw an underline using a pattern of dots.

      Available in OS X v10.3 and later.

    • NSUnderlinePatternDash

      NSUnderlinePatternDash

      Draw an underline using a pattern of dashes.

      Available in OS X v10.3 and later.

    • NSUnderlinePatternDashDot

      NSUnderlinePatternDashDot

      Draw an underline using a pattern of alternating dashes and dots.

      Available in OS X v10.3 and later.

    • NSUnderlinePatternDashDotDot

      NSUnderlinePatternDashDotDot

      Draw an underline using a pattern of a dash followed by two dots.

      Available in OS X v10.3 and later.

    Discussion

    See also “Underline Masks” and “Underlining Styles”. The style, pattern, and optionally by-word mask are OR'd together to produce the value for NSUnderlineStyleAttributeName and NSStrikethroughStyleAttributeName.

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

      Available in OS X v10.0 and later.

    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 Underlining Styles and Underlining Patterns.

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

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

  • 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 NSPaperSizeDocumentAttribute: String let NSLeftMarginDocumentAttribute: String let NSRightMarginDocumentAttribute: String let NSTopMarginDocumentAttribute: String let NSBottomMarginDocumentAttribute: String let NSHyphenationFactorDocumentAttribute: String let NSDocumentTypeDocumentAttribute: String let NSCharacterEncodingDocumentAttribute: String let NSViewSizeDocumentAttribute: String let NSViewZoomDocumentAttribute: String let NSViewModeDocumentAttribute: String let NSBackgroundColorDocumentAttribute: String let NSCocoaVersionDocumentAttribute: String let NSReadOnlyDocumentAttribute: String let NSConvertedDocumentAttribute: String let NSDefaultTabIntervalDocumentAttribute: String let NSTitleDocumentAttribute: String let NSUsesScreenFontsDocumentAttribute: String let NSCompanyDocumentAttribute: String let NSCopyrightDocumentAttribute: String let NSSubjectDocumentAttribute: String let NSAuthorDocumentAttribute: String let NSKeywordsDocumentAttribute: String let NSCommentDocumentAttribute: String let NSEditorDocumentAttribute: String let NSCreationTimeDocumentAttribute: String let NSModificationTimeDocumentAttribute: String let NSManagerDocumentAttribute: String let NSCategoryDocumentAttribute: String let NSFileTypeDocumentAttribute: String let NSFileTypeDocumentOption: String

    Objective-C

    NSString *NSAuthorDocumentAttribute; NSString *NSBackgroundColorDocumentAttribute; NSString *NSBottomMarginDocumentAttribute; NSString *NSCharacterEncodingDocumentAttribute; NSString *NSCategoryDocumentAttribute; NSString *NSCocoaVersionDocumentAttribute; NSString *NSCommentDocumentAttribute; NSString *NSCompanyDocumentAttribute; NSString *NSConvertedDocumentAttribute; NSString *NSCopyrightDocumentAttribute; NSString *NSCreationTimeDocumentAttribute; 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 *NSTitleDocumentAttribute; NSString *NSUsesScreenFontsDocumentAttribute; NSString *NSTopMarginDocumentAttribute; NSString *NSViewModeDocumentAttribute; NSString *NSViewSizeDocumentAttribute; NSString *NSViewZoomDocumentAttribute;

    Constants

    • NSPaperSizeDocumentAttribute

      NSPaperSizeDocumentAttribute

      NSValue, containing NSSize.

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

      Available in OS X v10.4 and later.

    • NSLeftMarginDocumentAttribute

      NSLeftMarginDocumentAttribute

      NSNumber, containing a float, in points.

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

      Available in OS X v10.4 and later.

    • NSRightMarginDocumentAttribute

      NSRightMarginDocumentAttribute

      NSNumber, containing a float, in points.

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

      Available in OS X v10.4 and later.

    • NSTopMarginDocumentAttribute

      NSTopMarginDocumentAttribute

      NSNumber, containing a float, in points.

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

      Available in OS X v10.4 and later.

    • NSBottomMarginDocumentAttribute

      NSBottomMarginDocumentAttribute

      NSNumber, containing a float, in points.

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

      Available in OS X v10.4 and later.

    • NSHyphenationFactorDocumentAttribute

      NSHyphenationFactorDocumentAttribute

      NSNumber, containing a float; 0 = off, 1 = full hyphenation.

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

      Available in OS X v10.4 and later.

    • NSDocumentTypeDocumentAttribute

      NSDocumentTypeDocumentAttribute

      How the document was interpreted; one of the values in Document Types.

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

      Available in OS X v10.4 and later.

    • NSCharacterEncodingDocumentAttribute

      NSCharacterEncodingDocumentAttribute

      NSNumber, containing an int specifying the NSStringEncoding for the file; for reading and writing plain text files and writing HTML; default for plain text is the default encoding; default for HTML is UTF-8.

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

      Available in OS X v10.4 and later.

    • NSViewSizeDocumentAttribute

      NSViewSizeDocumentAttribute

      NSValue, containing NSSize.

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

      Available in OS X v10.4 and later.

    • NSViewZoomDocumentAttribute

      NSViewZoomDocumentAttribute

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

      NSValue, containing a float; 100 = 100% zoom.

      Available in OS X v10.4 and later.

    • NSViewModeDocumentAttribute

      NSViewModeDocumentAttribute

      NSValue, 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.4 and later.

    • NSBackgroundColorDocumentAttribute

      NSBackgroundColorDocumentAttribute

      NSColor, 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.4 and later.

    • NSCocoaVersionDocumentAttribute

      NSCocoaVersionDocumentAttribute

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

    • NSReadOnlyDocumentAttribute

      NSReadOnlyDocumentAttribute

      NSNumber, containing int. 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.4 and later.

    • NSConvertedDocumentAttribute

      NSConvertedDocumentAttribute

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

    • NSDefaultTabIntervalDocumentAttribute

      NSDefaultTabIntervalDocumentAttribute

      NSNumber 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.4 and later.

    • NSTitleDocumentAttribute

      NSTitleDocumentAttribute

      NSString containing document title.

      Available in OS X v10.4 and later.

    • NSUsesScreenFontsDocumentAttribute

      NSUsesScreenFontsDocumentAttribute

      A boolean NSNumber; this attribute corresponds to the NSLayoutManager usesScreenFonts method; if absent, follows the system default setting

      Available in OS X v10.8 and later.

    • NSCompanyDocumentAttribute

      NSCompanyDocumentAttribute

      NSString containing company or organization name.

      Available in OS X v10.4 and later.

    • NSCopyrightDocumentAttribute

      NSCopyrightDocumentAttribute

      NSString containing document copyright info.

      Available in OS X v10.4 and later.

    • NSSubjectDocumentAttribute

      NSSubjectDocumentAttribute

      NSString containing subject of document.

      Available in OS X v10.4 and later.

    • NSAuthorDocumentAttribute

      NSAuthorDocumentAttribute

      NSString containing author name.

      Available in OS X v10.4 and later.

    • NSKeywordsDocumentAttribute

      NSKeywordsDocumentAttribute

      NSArray of NSString, containing keywords.

      Available in OS X v10.4 and later.

    • NSCommentDocumentAttribute

      NSCommentDocumentAttribute

      NSString containing document comments.

      Available in OS X v10.4 and later.

    • NSEditorDocumentAttribute

      NSEditorDocumentAttribute

      NSString containing name of person who last edited the document.

      Available in OS X v10.4 and later.

    • NSCreationTimeDocumentAttribute

      NSCreationTimeDocumentAttribute

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

    • NSModificationTimeDocumentAttribute

      NSModificationTimeDocumentAttribute

      NSDate containing the modification date of the document contents.

      Available in OS X v10.4 and later.

    • NSManagerDocumentAttribute

      NSManagerDocumentAttribute

      NSString containing the name of the author's manager.

      Available in OS X v10.5 and later.

    • NSCategoryDocumentAttribute

      NSCategoryDocumentAttribute

      NSString containing the document’s category.

      Available in OS X v10.6 and later.

    • NSFileTypeDocumentAttribute

      NSFileTypeDocumentAttribute

      NSString 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

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

  • 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 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):

  • This constant is used as, and recognized only as, a temporary attribute. It indicates that spelling and/or grammar indicators should be shown for the specified characters.

    Declaration

    Swift

    let NSSpellingStateAttributeName: String

    Objective-C

    NSString *NSSpellingStateAttributeName;

    Constants

    • NSSpellingStateAttributeName

      NSSpellingStateAttributeName

      An integer value. 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.

  • This constant specifies the layout orientation section attribute for persistence.

    Declaration

    Swift

    let NSTextLayoutSectionsAttribute: String

    Objective-C

    NSString *NSTextLayoutSectionsAttribute;

    Constants

  • These constants are used as by the NSLayoutOrientationSectionsAttribute.

    Declaration

    Swift

    let NSTextLayoutSectionOrientation: String let NSTextLayoutSectionRange: String

    Objective-C

    NSString *NSTextLayoutSectionOrientation; NSString *NSTextLayoutSectionRange;

    Constants

    • NSTextLayoutSectionOrientation

      NSTextLayoutSectionOrientation

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

      Available in OS X v10.7 and later.

    • NSTextLayoutSectionRange

      NSTextLayoutSectionRange

      An NSValue 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.

  • 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

    Swift

    var NSNoUnderlineStyle: Int { get } var NSSingleUnderlineStyle: Int { get }

    Objective-C

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

    Constants

    • NSNoUnderlineStyle

      NSNoUnderlineStyle

      Deprecated. Use NSUnderlineStyleNone instead.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    • NSSingleUnderlineStyle

      NSSingleUnderlineStyle

      Deprecated. Use NSUnderlineStyleSingle instead.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.