iOS Developer Library

Developer

CoreMedia Framework Reference CMTextMarkup Reference

Options
Deployment Target:

On This Page
Language:

CMTextMarkup Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import CoreMedia

Objective-C

@import CoreMedia;

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

  • Attributed string keys used by Core Media.

    Declaration

    Swift

    let kCMTextMarkupAttribute_ForegroundColorARGB: CFString! let kCMTextMarkupAttribute_BackgroundColorARGB: CFString! let kCMTextMarkupAttribute_CharacterBackgroundColorARGB: CFString! let kCMTextMarkupAttribute_BoldStyle: CFString! let kCMTextMarkupAttribute_ItalicStyle: CFString! let kCMTextMarkupAttribute_UnderlineStyle: CFString! let kCMTextMarkupAttribute_FontFamilyName: CFString! let kCMTextMarkupAttribute_GenericFontFamilyName: CFString! let kCMTextMarkupAttribute_BaseFontSizePercentageRelativeToVideoHeight: CFString! let kCMTextMarkupAttribute_RelativeFontSize: CFString! let kCMTextMarkupAttribute_VerticalLayout: CFString! let kCMTextMarkupAttribute_Alignment: CFString! let kCMTextMarkupAttribute_TextPositionPercentageRelativeToWritingDirection: CFString! let kCMTextMarkupAttribute_OrthogonalLinePositionPercentageRelativeToWritingDirection: CFString! let kCMTextMarkupAttribute_WritingDirectionSizePercentage: CFString! let kCMTextMarkupAttribute_CharacterEdgeStyle: CFString!

    Objective-C

    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

      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.

    • kCMTextMarkupAttribute_BackgroundColorARGB

      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.

    • kCMTextMarkupAttribute_CharacterBackgroundColorARGB

      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.

    • kCMTextMarkupAttribute_BoldStyle

      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.

    • kCMTextMarkupAttribute_ItalicStyle

      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.

    • kCMTextMarkupAttribute_UnderlineStyle

      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.

    • kCMTextMarkupAttribute_FontFamilyName

      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.

    • kCMTextMarkupAttribute_GenericFontFamilyName

      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.

    • kCMTextMarkupAttribute_BaseFontSizePercentageRelativeToVideoHeight

      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.

    • kCMTextMarkupAttribute_RelativeFontSize

      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.

    • kCMTextMarkupAttribute_VerticalLayout

      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.

    • kCMTextMarkupAttribute_Alignment

      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.

    • kCMTextMarkupAttribute_TextPositionPercentageRelativeToWritingDirection

      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.

    • kCMTextMarkupAttribute_OrthogonalLinePositionPercentageRelativeToWritingDirection

      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.

    • kCMTextMarkupAttribute_WritingDirectionSizePercentage

      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.

    • kCMTextMarkupAttribute_CharacterEdgeStyle

      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.

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

    Declaration

    Swift

    let kCMTextMarkupGenericFontName_Default: CFString! let kCMTextMarkupGenericFontName_Serif: CFString! let kCMTextMarkupGenericFontName_SansSerif: CFString! let kCMTextMarkupGenericFontName_Monospace: CFString! let kCMTextMarkupGenericFontName_ProportionalSerif: CFString! let kCMTextMarkupGenericFontName_ProportionalSansSerif: CFString! let kCMTextMarkupGenericFontName_MonospaceSerif: CFString! let kCMTextMarkupGenericFontName_MonospaceSansSerif: CFString! let kCMTextMarkupGenericFontName_Casual: CFString! let kCMTextMarkupGenericFontName_Cursive: CFString! let kCMTextMarkupGenericFontName_Fantasy: CFString! let kCMTextMarkupGenericFontName_SmallCapital: CFString!

    Objective-C

    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

      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.

    • kCMTextMarkupGenericFontName_Serif

      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.

    • kCMTextMarkupGenericFontName_SansSerif

      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.

    • kCMTextMarkupGenericFontName_Monospace

      kCMTextMarkupGenericFontName_Monospace

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

      Available in iOS 7.0 and later.

    • kCMTextMarkupGenericFontName_ProportionalSerif

      kCMTextMarkupGenericFontName_ProportionalSerif

      The generic font name indicating a proportional font with serifs.

      Available in iOS 7.0 and later.

    • kCMTextMarkupGenericFontName_ProportionalSansSerif

      kCMTextMarkupGenericFontName_ProportionalSansSerif

      The generic font name indicating a proportional font without serifs.

      Available in iOS 7.0 and later.

    • kCMTextMarkupGenericFontName_MonospaceSerif

      kCMTextMarkupGenericFontName_MonospaceSerif

      The generic font name indicating a monospaced font with serifs.

      Available in iOS 7.0 and later.

    • kCMTextMarkupGenericFontName_MonospaceSansSerif

      kCMTextMarkupGenericFontName_MonospaceSansSerif

      The generic font name indicating a monospaced font without serifs.

      Available in iOS 7.0 and later.

    • kCMTextMarkupGenericFontName_Casual

      kCMTextMarkupGenericFontName_Casual

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

      Available in iOS 7.0 and later.

    • kCMTextMarkupGenericFontName_Cursive

      kCMTextMarkupGenericFontName_Cursive

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

      Available in iOS 7.0 and later.

    • kCMTextMarkupGenericFontName_Fantasy

      kCMTextMarkupGenericFontName_Fantasy

      The generic font name indicating a "fantasy" font.

      Available in iOS 7.0 and later.

    • kCMTextMarkupGenericFontName_SmallCapital

      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.

    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.)

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

    Declaration

    Swift

    let kCMTextVerticalLayout_LeftToRight: CFString! let kCMTextVerticalLayout_RightToLeft: CFString!

    Objective-C

    const CFStringRef kCMTextVerticalLayout_LeftToRight; const CFStringRef kCMTextVerticalLayout_RightToLeft;

    Constants

    • kCMTextVerticalLayout_LeftToRight

      kCMTextVerticalLayout_LeftToRight

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

      Available in iOS 7.0 and later.

    • kCMTextVerticalLayout_RightToLeft

      kCMTextVerticalLayout_RightToLeft

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

      Available in iOS 7.0 and later.

    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.

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

    Declaration

    Swift

    let kCMTextMarkupAlignmentType_Start: CFString! let kCMTextMarkupAlignmentType_Middle: CFString! let kCMTextMarkupAlignmentType_End: CFString! let kCMTextMarkupAlignmentType_Left: CFString! let kCMTextMarkupAlignmentType_Right: CFString!

    Objective-C

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

    Constants

    • kCMTextMarkupAlignmentType_Start

      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.

    • kCMTextMarkupAlignmentType_Middle

      kCMTextMarkupAlignmentType_Middle

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

      Available in iOS 7.0 and later.

    • kCMTextMarkupAlignmentType_End

      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.

    • kCMTextMarkupAlignmentType_Left

      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.

    • kCMTextMarkupAlignmentType_Right

      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.

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

    Declaration

    Swift

    let kCMTextMarkupCharacterEdgeStyle_None: CFString! let kCMTextMarkupCharacterEdgeStyle_Raised: CFString! let kCMTextMarkupCharacterEdgeStyle_Depressed: CFString! let kCMTextMarkupCharacterEdgeStyle_Uniform: CFString! let kCMTextMarkupCharacterEdgeStyle_DropShadow: CFString!

    Objective-C

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

    Constants

    • kCMTextMarkupCharacterEdgeStyle_None

      kCMTextMarkupCharacterEdgeStyle_None

      Specifies no edge style.

      Available in iOS 7.0 and later.

    • kCMTextMarkupCharacterEdgeStyle_Raised

      kCMTextMarkupCharacterEdgeStyle_Raised

      Specifies a raised edge style.

      Available in iOS 7.0 and later.

    • kCMTextMarkupCharacterEdgeStyle_Depressed

      kCMTextMarkupCharacterEdgeStyle_Depressed

      Specifies a depressed edge style.

      Available in iOS 7.0 and later.

    • kCMTextMarkupCharacterEdgeStyle_Uniform

      kCMTextMarkupCharacterEdgeStyle_Uniform

      Specifies a uniform border around the character.

      Available in iOS 7.0 and later.

    • kCMTextMarkupCharacterEdgeStyle_DropShadow

      kCMTextMarkupCharacterEdgeStyle_DropShadow

      Specifies a drop shadow.

      Available in iOS 7.0 and later.

    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).