Core Text String Attributes Reference

Overview

This reference document describes the attributes to which Core Text responds when the attributes are placed in a CFAttributedString object.

Constants

String Attribute Name Constants

These constants represent string attribute names.

const CFStringRef kCTCharacterShapeAttributeName;
const CFStringRef kCTFontAttributeName;
const CFStringRef kCTKernAttributeName;
const CFStringRef kCTLigatureAttributeName;
const CFStringRef kCTForegroundColorAttributeName;
const CFStringRef kCTForegroundColorFromContextAttributeName;
const CFStringRef kCTParagraphStyleAttributeName;
const CFStringRef kCTStrokeWidthAttributeName;
const CFStringRef kCTStrokeColorAttributeName;
const CFStringRef kCTSuperscriptAttributeName;
const CFStringRef kCTUnderlineColorAttributeName;
const CFStringRef kCTUnderlineStyleAttributeName;
const CFStringRef kCTVerticalFormsAttributeName;
const CFStringRef kCTGlyphInfoAttributeName;
const CFStringRef kCTRunDelegateAttributeName

Constants

kCTCharacterShapeAttributeName

Controls glyph selection. Value must be a CFNumberRef object. Default is value is 0 (disabled). A non-zero value is interpreted as Apple Type Services kCharacterShapeType selector + 1 (see <ATS/SFNTLayoutTypes.h> for selectors). For example, an attribute value of 1 corresponds to kTraditionalCharactersSelector.

Available in iOS 3.2 and later.

Declared in CTStringAttributes.h.

kCTFontAttributeName

The font of the text to which this attribute applies. The value associated with this attribute must be a CTFont object. Default is Helvetica 12.

Available in iOS 3.2 and later.

Declared in CTStringAttributes.h.

kCTKernAttributeName

The amount to kern the next character. The value associated with this attribute must be a CFNumber float. Default is standard kerning. The kerning attribute indicates how many points the following character should be shifted from its default offset as defined by the current character's font in points: a positive kern indicates a shift farther away from and a negative kern indicates a shift closer to the current character. If this attribute is not present, standard kerning is used. If this attribute is set to 0.0, no kerning is done at all.

Available in iOS 3.2 and later.

Declared in CTStringAttributes.h.

kCTLigatureAttributeName

The type of ligatures to use. The value associated with this attribute must be a CFNumber object. Default is an integer value of 1. The ligature attribute determines what kinds of ligatures should be used when displaying the string. A value of 0 indicates that only ligatures essential for proper rendering of text should be used. A value of 1 indicates that standard ligatures should be used, and 2 indicates that all available ligatures should be used. Which ligatures are standard depends on the script and possibly the font. Arabic text, for example, requires ligatures for many character sequences but has a rich set of additional ligatures that combine characters. English text has no essential ligatures, and typically has only two standard ligatures, those for "fi" and "fl"—all others are considered more advanced or fancy.

Available in iOS 3.2 and later.

Declared in CTStringAttributes.h.

kCTForegroundColorAttributeName

The foreground color of the text to which this attribute applies. The value associated with this attribute must be a CGColor object. Default value is black.

Available in iOS 3.2 and later.

Declared in CTStringAttributes.h.

kCTForegroundColorFromContextAttributeName

Sets a foreground color using the context's fill color. Value must be a CFBooleanRef object. Default is false. The reason this exists is because an NSAttributedString object defaults to a black color if no color attribute is set. This forces Core Text to set the color in the context. This attribute allows developers to sidestep this, making Core Text set nothing but font information in the CGContext. If set, this attribute also determines the color used by kCTUnderlineStyleAttributeName, in which case it overrides the foreground color.

Available in iOS 3.2 and later.

Declared in CTStringAttributes.h.

kCTParagraphStyleAttributeName

The paragraph style of the text to which this attribute applies. A paragraph style object is used to specify things like line alignment, tab rulers, writing direction, and so on. Value must be a CTParagraphStyle object. Default is an empty CTParagraphStyle object. See CTParagraphStyle Reference for more information.

Available in iOS 3.2 and later.

Declared in CTStringAttributes.h.

kCTStrokeWidthAttributeName

The stroke width. Value must be a CFNumberRef object. Default value is 0.0, or no stroke. This attribute, interpreted as a percentage of font point size, controls the text drawing mode: positive values effect drawing with stroke only; negative values are for stroke and fill. A typical value for outlined text is 3.0.

Available in iOS 3.2 and later.

Declared in CTStringAttributes.h.

kCTStrokeColorAttributeName

The stroke color. Value must be a CGColorRef object. Default is the foreground color.

Available in iOS 3.2 and later.

Declared in CTStringAttributes.h.

kCTSuperscriptAttributeName

Controls vertical text positioning. Value must be a CFNumberRef object. Default is integer value 0. If supported by the specified font, a value of 1 enables superscripting and a value of -1 enables subscripting.

Available in iOS 3.2 and later.

Declared in CTStringAttributes.h.

kCTUnderlineColorAttributeName

The underline color. Value must be a CGColorRef object. Default is the foreground color.

Available in iOS 3.2 and later.

Declared in CTStringAttributes.h.

kCTUnderlineStyleAttributeName

The style of underlining, to be applied at render time, for the text to which this attribute applies. Value must be a CFNumber object. Default is kCTUnderlineStyleNone. Set a value of something other than kCTUnderlineStyleNone to draw an underline. In addition, the constants listed in “CTUnderlineStyleModifiers” can be used to modify the look of the underline. The underline color is determined by the text's foreground color.

Available in iOS 3.2 and later.

Declared in CTStringAttributes.h.

kCTVerticalFormsAttributeName

The orientation of the glyphs in the text to which this attribute applies. Value must be a CFBoolean object. Default is False. A value of False indicates that horizontal glyph forms are to be used; True indicates that vertical glyph forms are to be used.

Available in iOS 3.2 and later.

Declared in CTStringAttributes.h.

kCTGlyphInfoAttributeName

The glyph info object to apply to the text associated with this attribute. Value must be a CTGlyphInfo object. The glyph specified by this CTGlyphInfo object is assigned 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 kCTFontAttributeName. See CTGlyphInfo Reference for more information.

Available in iOS 3.2 and later.

Declared in CTStringAttributes.h.

kCTRunDelegateAttributeName

The run-delegate object to apply to an attribute range of the string. The value must be a CTRunDelegate object. The run delegate controls such typographic traits as glyph ascent, descent, and width. The values returned by the embedded run delegate apply to each glyph resulting from the text in that range. Because an embedded object is only a display-time modification, you should avoid applying this attribute to a range of text with complex behavior, such as text having a change of writing direction or having combining marks. It is thus recommended you apply this attribute to a range containing the single character U+FFFC. See CTRunDelegate Reference for more information.

Available in iOS 3.2 and later.

Declared in CTStringAttributes.h.

CTUnderlineStyle

Underline style specifiers.

enum{
kCTUnderlineStyleNone = 0x00,
kCTUnderlineStyleSingle = 0x01,
kCTUnderlineStyleThick = 0x02,
kCTUnderlineStyleDouble = 0x09
};
typedef int32_t CTUnderlineStyle;

Constants

kCTUnderlineStyleNone

Do not draw an underline.

Available in iOS 3.2 and later.

Declared in CTStringAttributes.h.

kCTUnderlineStyleSingle

Draw an underline consisting of a single line.

Available in iOS 3.2 and later.

Declared in CTStringAttributes.h.

kCTUnderlineStyleThick

Draw an underline consisting of a thick line.

Available in iOS 3.2 and later.

Declared in CTStringAttributes.h.

kCTUnderlineStyleDouble

Draw an underline consisting of a double line.

Available in iOS 3.2 and later.

Declared in CTStringAttributes.h.

CTUnderlineStyleModifiers

Underline style modifiers.

enum{
kCTUnderlinePatternSolid = 0x0000,
kCTUnderlinePatternDot = 0x0100,
kCTUnderlinePatternDash = 0x0200,
kCTUnderlinePatternDashDot = 0x0300,
kCTUnderlinePatternDashDotDot = 0x0400
};
typedef int32_t CTUnderlineStyleModifiers;

Constants

kCTUnderlinePatternSolid

Draw a solid underline.

Available in iOS 3.2 and later.

Declared in CTStringAttributes.h.

kCTUnderlinePatternDot

Draw an underline using a pattern of dots.

Available in iOS 3.2 and later.

Declared in CTStringAttributes.h.

kCTUnderlinePatternDash

Draw an underline using a pattern of dashes.

Available in iOS 3.2 and later.

Declared in CTStringAttributes.h.

kCTUnderlinePatternDashDot

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

Available in iOS 3.2 and later.

Declared in CTStringAttributes.h.

kCTUnderlinePatternDashDotDot

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

Available in iOS 3.2 and later.

Declared in CTStringAttributes.h.