Reading Formatted Documents

The Application Kit’s extensions to NSAttributedString include two general-purpose methods to create an attributed string by loading text documents in various formats. The document format is specified in an options dictionary containing keys described in “Option keys for importing documents” in NSAttributedString AppKit Additions Reference. If the NSDocumentTypeDocumentOption key is specified, with one of the values defined for NSDocumentTypeDocumentAttribute, the document is interpreted according to the specified format. If the NSDocumentTypeDocumentOption key is not specified, the general methods examine the document and perform a best effort to load it using the appropriate format.

The two general methods for reading formatted documents are:

The Application Kit’s extensions to NSAttributedString also define a number of special-purpose convenience methods to create an attributed string for various common document types. Also, NSMutableAttributedString defines the following methods:

Handling Document Attributes

Attributed strings store attribute information for characters and paragraphs only, but most document formats also support more general attributes of a document, such as paper size and page layout. The NSAttributedString reading and writing methods store these directives in a document attributes dictionary. If the document attributes dictionary passed with a document-reading method is not NULL, it is populated with various document-wide attributes. The document attributes supported vary according to document type. Possible document attribute keys and the values they can take are described in “Document Attributes” in NSAttributedString AppKit Additions Reference.

Writing Formatted Documents

The Application Kit’s extensions to NSAttributedString also define methods to produce data for saving text documents in various formats. These methods take a document attributes dictionary to enable writing out various document-wide attributes, and the attributes supported vary by document type, as described for the document-reading methods.

The first two methods are general, that is, applicable to any supported document type. They require a document attributes dictionary specifying at least the NSDocumentTypeDocumentAttribute to determine the format to be written.

The two general methods for writing formatted documents are:

Use dataFromRange:documentAttributes:error: to create a data object that can be written to a regular file on disk. Use fileWrapperFromRange:documentAttributes:error: when you want to create a directory structure on disk, such as RTFD. The file wrapper method returns a directory file wrapper for those document types for which it is appropriate; otherwise it returns a regular-file file wrapper.

The Application Kit’s extensions to NSAttributedString also define a number of special-purpose convenience methods to produce data for writing various common document types.

Handling Attachments

Attachments, such as embedded images or files, are represented in an attributed string by both a special character and an attribute. The character is identified by the global name NSAttachmentCharacter (U+FFFC, the Unicode replacement character), and indicates the presence of an attachment at its location in the string. The attribute, identified in the string by the attribute name NSAttachmentAttributeName, is an NSTextAttachment object . An NSTextAttachment object contains the data for the attachment itself and an image to display when the string is drawn.

You can use the NSAttributedString method attributedStringWithAttachment: class method to construct an attachment string, which you can then add to a mutable attributed string using appendAttributedString: or insertAttributedString:atIndex:.