CFAttributedString Reference

Overview

Instances of CFAttributedString manage character strings and associated sets of attributes (for example, font and kerning information) that apply to individual characters or ranges of characters in the string. CFAttributedString as defined in CoreFoundation provides the basic container functionality, while higher levels provide definitions for standard attributes, their values, and additional behaviors involving these. CFAttributedString represents an immutable string—use CFMutableAttributedString to create and manage an attributed string that can be changed after it has been created.

CFAttributedString is not a “subclass” of CFString; that is, it does not respond to CFString function calls. CFAttributedString conceptually contains a CFString to which it applies attributes. This protects you from ambiguities caused by the semantic differences between simple and attributed string.

Attributes are identified by key/value pairs stored in CFDictionary objects. Keys must be CFString objects, while the corresponding values are CFType objects of an appropriate type. See the attribute constants in NSAttributedString Application Kit Additions Reference for standard attribute names.

On OS X, CFAttributedString is “toll-free bridged” with its Cocoa Foundation counterpart, NSAttributedString. This means that the Core Foundation type is interchangeable in function or method calls with the bridged Foundation object. Therefore, in a method where you see an NSAttributedString * parameter, you can pass in a CFAttributedStringRef, and in a function where you see a CFAttributedStringRef parameter, you can pass in an NSAttributedString instance. This also applies to concrete subclasses of NSAttributedString. See “Toll-Free Bridged Types” for more information on toll-free bridging.

Functions by Task

Creating a CFAttributedString

• CFAttributedStringCreate
• CFAttributedStringCreateCopy
• CFAttributedStringCreateWithSubstring
• CFAttributedStringGetLength
• CFAttributedStringGetString

Accessing Attributes

• CFAttributedStringGetAttribute
• CFAttributedStringGetAttributes
• CFAttributedStringGetAttributeAndLongestEffectiveRange
• CFAttributedStringGetAttributesAndLongestEffectiveRange

Getting Attributed String Properties

• CFAttributedStringGetTypeID

Functions

CFAttributedStringCreate

Creates an attributed string with specified string and attributes.

CFAttributedStringRef CFAttributedStringCreate (
   CFAllocatorRef alloc,
   CFStringRef str,
   CFDictionaryRef attributes
);

CFAttributedStringCreateCopy

Creates an immutable copy of an attributed string.

CFAttributedStringRef CFAttributedStringCreateCopy (
   CFAllocatorRef alloc,
   CFAttributedStringRef aStr
);

CFAttributedStringCreateWithSubstring

Creates a sub-attributed string from the specified range.

CFAttributedStringRef CFAttributedStringCreateWithSubstring (
   CFAllocatorRef alloc,
   CFAttributedStringRef aStr,
   CFRange range
);

CFAttributedStringGetAttribute

Returns the value of a given attribute of an attributed string at a specified location.

CFTypeRef CFAttributedStringGetAttribute (
   CFAttributedStringRef aStr,
   CFIndex loc,
   CFStringRef attrName,
   CFRange *effectiveRange
);

CFAttributedStringGetAttributeAndLongestEffectiveRange

Returns the value of a given attribute of an attributed string at a specified location.

CFTypeRef CFAttributedStringGetAttributeAndLongestEffectiveRange (
   CFAttributedStringRef aStr,
   CFIndex loc,
   CFStringRef attrName,
   CFRange inRange,
   CFRange *longestEffectiveRange
);

CFAttributedStringGetAttributes

Returns the attributes of an attributed string at a specified location.

CFDictionaryRef CFAttributedStringGetAttributes (
   CFAttributedStringRef aStr,
   CFIndex loc,
   CFRange *effectiveRange
);

CFAttributedStringGetAttributesAndLongestEffectiveRange

Returns the attributes of an attributed string at a specified location.

CFDictionaryRef CFAttributedStringGetAttributesAndLongestEffectiveRange (
   CFAttributedStringRef aStr,
   CFIndex loc,
   CFRange inRange,
   CFRange *longestEffectiveRange
);

CFAttributedStringGetLength

Returns the length of the attributed string in characters.

CFIndex CFAttributedStringGetLength (
   CFAttributedStringRef aStr
);

CFAttributedStringGetString

Returns the string for an attributed string.

CFStringRef CFAttributedStringGetString (
   CFAttributedStringRef aStr
);

CFAttributedStringGetTypeID

Returns the type identifier for the CFAttributedString opaque type.

CFTypeID CFAttributedStringGetTypeID (
   void
);

Data Types

CFAttributedStringRef

A reference to a CFAttributedString object.

typedef const struct __CFAttributedString *CFAttributedStringRef;