Formatted Documents and Attributed Strings
The Application Kit’s extensions to NSAttributedString
add support for reading and writing text formatting commands and document attributes for a number of popular markup languages, including the following:
HTML
RTF and RTFD
Microsoft Word
Word XML
WebKit WebArchive
ECMA Office Open XML
OASIS Open Document
These document formats are represented by the values returned for the NSDocumentTypeDocumentAttribute
key in the document attributes dictionary when reading and writing text documents. For all of these languages, files representing documents include both the text to be displayed and interspersed formatting commands. Programs that display the documents interpret the commands to format the text. Formatting commands or “tags” represent such formatting elements as paragraphs, headings, line breaks, images, hyperlinks, and so on. In addition, some commands represent document-wide attributes, such as paper size, margins, background color, and so on.
For additional information specific to RTF and RTFD, see RTF Files and Attributed Strings.
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:
.
Copyright © 1997, 2014 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2014-02-11