CMTextMarkup Reference

Framework
CoreMedia.framework
Declared in
CMTextMarkup.h

Overview

This document describes text markup related attributes that Core Media responds to.

Core Media includes support for legible media streams such as subtitles, captions and text. In some cases, clients may need to specify style information to control the rendering. In other cases, information about the text and applied styling may be communicated from Core Media to the client. To carry this information, Core Media defines a set of attributes that may be used in dictionaries that Core Media uses. These attributes can also be used as CFAttributedString attributes.

Constants

Text Markup Attributes

Attributed string keys used by Core Media.

const CFStringRef kCMTextMarkupAttribute_ForegroundColorARGB;
const CFStringRef kCMTextMarkupAttribute_BackgroundColorARGB;
const CFStringRef kCMTextMarkupAttribute_CharacterBackgroundColorARGB;
const CFStringRef kCMTextMarkupAttribute_BoldStyle;
const CFStringRef kCMTextMarkupAttribute_ItalicStyle;
const CFStringRef kCMTextMarkupAttribute_UnderlineStyle;
const CFStringRef kCMTextMarkupAttribute_FontFamilyName;
const CFStringRef kCMTextMarkupAttribute_GenericFontFamilyName;
const CFStringRef kCMTextMarkupAttribute_BaseFontSizePercentageRelativeToVideoHeight;
const CFStringRef kCMTextMarkupAttribute_RelativeFontSize;
const CFStringRef kCMTextMarkupAttribute_VerticalLayout;
const CFStringRef kCMTextMarkupAttribute_Alignment;
const CFStringRef kCMTextMarkupAttribute_TextPositionPercentageRelativeToWritingDirection;
const CFStringRef kCMTextMarkupAttribute_OrthogonalLinePositionPercentageRelativeToWritingDirection;
const CFStringRef kCMTextMarkupAttribute_WritingDirectionSizePercentage;
const CFStringRef kCMTextMarkupAttribute_CharacterEdgeStyle;
Constants
kCMTextMarkupAttribute_ForegroundColorARGB

The foreground color for text.

Value must be a CFArray of 4 CFNumbers representing alpha, red, green, and blue fields with values between 0.0 and 1.0. The red, green and blue components are interpreted in the sRGB color space. The alpha indicates the opacity from 0.0 for transparent to 1.0 for 100% opaque.

Available in iOS 6.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupAttribute_BackgroundColorARGB

The background color for the shape holding the text.

Value must be a CFArray of 4 CFNumbers representing alpha, red, green, and blue fields with values between 0.0 and 1.0. The red, green and blue components are interpreted in the sRGB color space. The alpha indicates the opacity from 0.0 for transparent to 1.0 for 100% opaque.

The color applies to the geometry (for example, a box) containing the text. The container's background color may have an alpha of 0 so it is not displayed even though the text is displayed. The color behind individual characters is optionally controllable with the kCMTextMarkupAttribute_CharacterBackgroundColorARGB attribute.

If used, this attribute must be applied to the entire attributed string.

Available in iOS 6.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupAttribute_CharacterBackgroundColorARGB

The background color behind individual text characters.

Value must be a CFArray of 4 CFNumbers representing alpha, red, green, and blue fields with values between 0.0 and 1.0. The red, green and blue components are interpreted in the sRGB color space. The alpha indicates the opacity from 0.0 for transparent to 1.0 for 100% opaque.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupAttribute_BoldStyle

Specifies a bold text style.

Value must be a CFBoolean. The default is kCFBooleanFalse. If this attribute is kCFBooleanTrue, the text will be drawn with a bold style. Other styles such as italic may or may not be used as well.

Available in iOS 6.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupAttribute_ItalicStyle

Specifies an italic text style.

Value must be a CFBoolean. The default is kCFBooleanFalse. If this attribute is kCFBooleanTrue, the text will be rendered with an italic style. Other styles such as bold may or may not be used as well.

Available in iOS 6.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupAttribute_UnderlineStyle

Specifies an underlined text style.

Value must be a CFBoolean. The default is kCFBooleanFalse. If this attribute is kCFBooleanTrue, the text will be rendered with an underline. Other styles such as bold may or may not be used as well.

Available in iOS 6.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupAttribute_FontFamilyName

The name of the font.

Value must be a CFString holding the family name of an installed font (for example, "Helvetica") that is used to render and/or measure text.

When vended by legible output, an attributed string will have at most one of kCMTextMarkupAttribute_FontFamilyName or kCMTextMarkupAttribute_GenericFontFamilyName associated with each character.

Available in iOS 6.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupAttribute_GenericFontFamilyName

The attribute holding a generic font family identifier.

Value must be one of the CFString constants in “Generic Font Names.” Generic fonts must be mapped to the family name of an installed font before rendering and/or measuring text (see Media Accessibility Function Reference).

When vended by legible output, an attributed string will have at most one of kCMTextMarkupAttribute_FontFamilyName or kCMTextMarkupAttribute_GenericFontFamilyName associated with each character.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupAttribute_BaseFontSizePercentageRelativeToVideoHeight

The base font size expressed as a percentage of the video height.

Value must be a non-negative CFNumber. This is a number holding a percentage of the height of the video frame. For example, a value of 5 indicates that the base font size should be 5% of the height of the video.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupAttribute_RelativeFontSize

The font size expressed as a percentage of the current default font size.

Value must be a non-negative CFNumber. This is a number holding a percentage of the size of the calculated default font size. A value of 120 indicates 20% larger than the default font size. A value of 80 indicates 80% of the default font size. The default value of 100 indicates no size difference.

Available in iOS 6.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupAttribute_VerticalLayout

The kind of vertical layout of the text block.

Value must be one of the CFString constants in “Vertical Layout Constants” indicating the progression direction for new vertical lines of text. If this attribute is present, it indicates the writing direction is vertical. The attribute value indicates whether new vertical text lines are added from left to right or from right to left. If this attribute is missing, the writing direction is horizontal.

If used, this attribute must be applied to the entire attributed string.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupAttribute_Alignment

The alignment of text in the writing direction of the first line of text.

Value must be one of the CFString constants in “Alignment Type Constants” indicating the alignment in the writing direction of the first line of text of the cue. The writing direction is indicated by the value (or absence) of the kCMTextMarkupAttribute_VerticalLayout attribute. The default value of this attribute is kCMTextMarkupAlignmentType_Middle.

If used, this attribute must be applied to the entire attributed string.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupAttribute_TextPositionPercentageRelativeToWritingDirection

The placement of the block of text specified as a percentage in the writing direction.

Value must be a non-negative CFNumber. This is a number expressing the position of the center of the text in the writing direction as a percentage of the video dimensions in the writing direction. For horizontal cues, this is the horizontal position. For vertical, it is the vertical position. The percentage is calculated from the edge of the frame where the text begins (so for left-to-right English, it is the left edge).

If used, this attribute must be applied to the entire attributed string.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupAttribute_OrthogonalLinePositionPercentageRelativeToWritingDirection

The placement of the block of text's first line specified as a percentage in the direction orthogonal to the writing direction.

Value must be a non-negative CFNumber. This is a number expressing the position of the center of the cue relative to the writing direction. The line position is orthogonal (or perpendicular) to the writing direction (that is, for a horizontal writing direction, it is vertical and for a vertical writing direction, is is horizontal). This attribute expresses the line position as a percentage of the dimensions of the video frame in the relevant direction. For example, 0% is the top of the video frame and 100% is the bottom of the video frame for horizontal writing layout.

If used, this attribute must be applied to the entire attributed string.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupAttribute_WritingDirectionSizePercentage

The dimension (width or height) of the bounding box containing the text expressed as a percentage.

Value must be a non-negative CFNumber. This is a number expressing the width of the bounding box for text layout as a percentage of the video frame's dimension in the writing direction. For a horizontal writing direction, it is the width. For a vertical writing direction, it is the height.

If used, this attribute must be applied to the entire attributed string.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupAttribute_CharacterEdgeStyle

Specifies alternative shapes for edges of characters.

Value must be one of the CFString constants in “Character Edge Style Constants” that control the shape of the edges of drawn characters. The default value is kCMTextMarkupCharacterEdgeStyle_None.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

Generic Font Names

Values for the kCMTextMarkupAttribute_GenericFontFamilyName attribute specifying fonts by their general properties.

const CFStringRef kCMTextMarkupGenericFontName_Default;
const CFStringRef kCMTextMarkupGenericFontName_Serif;
const CFStringRef kCMTextMarkupGenericFontName_SansSerif;
const CFStringRef kCMTextMarkupGenericFontName_Monospace;
const CFStringRef kCMTextMarkupGenericFontName_ProportionalSerif;
const CFStringRef kCMTextMarkupGenericFontName_ProportionalSansSerif;
const CFStringRef kCMTextMarkupGenericFontName_MonospaceSerif;
const CFStringRef kCMTextMarkupGenericFontName_MonospaceSansSerif;
const CFStringRef kCMTextMarkupGenericFontName_Casual;
const CFStringRef kCMTextMarkupGenericFontName_Cursive;
const CFStringRef kCMTextMarkupGenericFontName_Fantasy;
const CFStringRef kCMTextMarkupGenericFontName_SmallCapital;
Constants
kCMTextMarkupGenericFontName_Default

The generic font name indicating the default font. The default font may also be chosen if no font family is specified.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupGenericFontName_Serif

The generic font name indicating a font with serifs (for example, Times New Roman). The font may be proportional or monospaced.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupGenericFontName_SansSerif

The generic font name indicating a font without serifs (for example, Helvetica). The font may be proportional or monospaced.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupGenericFontName_Monospace

The generic font name indicating a monospaced font (for example, Courier), with or without serifs.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupGenericFontName_ProportionalSerif

The generic font name indicating a proportional font with serifs.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupGenericFontName_ProportionalSansSerif

The generic font name indicating a proportional font without serifs.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupGenericFontName_MonospaceSerif

The generic font name indicating a monospaced font with serifs.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupGenericFontName_MonospaceSansSerif

The generic font name indicating a monospaced font without serifs.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupGenericFontName_Casual

The generic font name indicating a "casual" font (for example, Dom or Impress).

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupGenericFontName_Cursive

The generic font name indicating a cursive font (for example, Coronet or Marigold).

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupGenericFontName_Fantasy

The generic font name indicating a "fantasy" font.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupGenericFontName_SmallCapital

The generic font name indicating a font with lowercase letters set as small capitals (for example, Engravers Gothic).

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

Discussion

Some media formats allow the specification of font family names to be used to style text they carry. Sometimes, an external specification such as CSS be used to style the text carried by the media format. In either case, the specification may be concrete, indicating an installed platform font (e.g., "Times New Roman", Helvetica). It may be abstract, indicating a category of font to use (e.g., serif, sans-serif). This abstract designation is often termed a "generic font family".

The Media Accessibility framework can map eight categories of abstract fonts to an installed font. Users may choose to override each of these categories to a different installed font. (See “Media Accessibility Function Reference”.)

Vertical Layout Constants

Values for the kCMTextMarkupAttribute_VerticalLayout attribute indicating the layout of vertical text.

const CFStringRef kCMTextVerticalLayout_LeftToRight;
const CFStringRef kCMTextVerticalLayout_RightToLeft;
Constants
kCMTextVerticalLayout_LeftToRight

Newly added vertical lines are added from the left toward the right.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextVerticalLayout_RightToLeft

Newly added vertical lines are added from the right toward the left.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

Discussion

The presence of this attribute indicates that the writing direction for text is vertical. If this attribute is not present, text should be laid out horizontally.

Alignment Type Constants

Values for the kCMTextMarkupAttribute_Alignment attribute indicating the alignment of text within its writing direction.

const CFStringRef kCMTextMarkupAlignmentType_Start;
const CFStringRef kCMTextMarkupAlignmentType_Middle;
const CFStringRef kCMTextMarkupAlignmentType_End;
const CFStringRef kCMTextMarkupAlignmentType_Left;
const CFStringRef kCMTextMarkupAlignmentType_Right;
Constants
kCMTextMarkupAlignmentType_Start

The text is visually aligned at its starting side.

For horizontally written text, the alignment is left for left-to-right text and right for right-to-left text. For vertical text, alignment is always at the top.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupAlignmentType_Middle

The text is visually center-aligned (that is, aligned between its starting and ending sides).

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupAlignmentType_End

The text is visually aligned at its ending side.

For horizontally written text, the alignment is right for left-to-right text and left for right-to-left text. For vertical text, alignment is always at the bottom.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupAlignmentType_Left

For horizontally written text, the text alignment is always visually left-aligned (that is, left-to-right and right-to-left are treated uniformly). For vertical text, this is equivalent to kCMTextMarkupAlignmentType_Start.

While readers should be prepared to account for kCMTextMarkupAlignmentType_Left being equivalent to kCMTextMarkupAlignmentType_Start for vertical text, authors are discouraged from using kCMTextMarkupAlignmentType_Left for vertical text.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupAlignmentType_Right

For horizontally written text, the text alignment is always visually right-aligned (that is, left-to-right and right-to-left are treated uniformly). For vertical text, this is equivalent to kCMTextMarkupAlignmentType_End.

While readers should be prepared to account for kCMTextMarkupAlignmentType_Right being equivalent to kCMTextMarkupAlignmentType_End for vertical text, authors are discouraged from using kCMTextMarkupAlignmentType_Right for vertical text.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

Character Edge Style Constants

Values for the kCMTextMarkupAttribute_CharacterEdgeStyle attribute controlling the visual style for character edges.

const CFStringRef kCMTextMarkupCharacterEdgeStyle_None;
const CFStringRef kCMTextMarkupCharacterEdgeStyle_Raised;
const CFStringRef kCMTextMarkupCharacterEdgeStyle_Depressed;
const CFStringRef kCMTextMarkupCharacterEdgeStyle_Uniform;
const CFStringRef kCMTextMarkupCharacterEdgeStyle_DropShadow;
Constants
kCMTextMarkupCharacterEdgeStyle_None

Specifies no edge style.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupCharacterEdgeStyle_Raised

Specifies a raised edge style.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupCharacterEdgeStyle_Depressed

Specifies a depressed edge style.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupCharacterEdgeStyle_Uniform

Specifies a uniform border around the character.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

kCMTextMarkupCharacterEdgeStyle_DropShadow

Specifies a drop shadow.

Available in iOS 7.0 and later.

Declared in CMTextMarkup.h.

Discussion

A value other than kCMTextMarkupCharacterEdgeStyle_None indicates that text should be drawn using an alternative shape for edges of characters. These correspond to text edge styles available with Media Accessibility preferences (see “Media Accessibility Function Reference”).