CharacterFormat Class

Namespace:
GemBox.Document
Assembly:
GemBox.Document.dll

Represents a set of formatting properties which shall be applied to a document text.

public sealed class CharacterFormat : Format
Public NotInheritable Class CharacterFormat
    Inherits Format
Inheritance:
System.Object
CharacterFormat
Remarks

GemBox.Document supports a variety of text formatting options like font name, size and color; on / off properties like bold, italic, underline, strikethrough, subscript, superscript and many others.

CharacterFormat can be set on:

For more information about CharacterFormat properties, see character formatting example.

Constructors

CharacterFormat()

Initializes a new instance of the CharacterFormat class.

public CharacterFormat()
Public Sub New

Properties

AllCaps

Gets or sets a value indicating whether to display all characters as capital letters.

public bool AllCaps { get; set; }
Public Property AllCaps As Boolean
Property Value
System.Boolean

true to display all characters as capital letters; otherwise, false.

BackgroundColor

Gets or sets the text background color. HighlightColor overrides BackgroundColor.

public Color BackgroundColor { get; set; }
Public Property BackgroundColor As Color
Property Value
Color

The text background color.

Bold

Gets or sets a value indicating whether all characters in the text of the run are bold.

public bool Bold { get; set; }
Public Property Bold As Boolean
Property Value
System.Boolean

true if all characters in the text of the run are bold; otherwise, false.

Border

Gets or sets the border of the Run that has this CharacterFormat applied to it. Supported only in DOCX and DOC formats.

public SingleBorder Border { get; set; }
Public Property Border As SingleBorder
Property Value
SingleBorder

The border of the Run that has this CharacterFormat applied to it.

Remarks

This value is currently ignored when exporting a document to PDF, XPS, or image formats.

DoubleStrikethrough

Gets or sets a value indicating whether the text of the run shall be displayed with two horizontal lines through each character displayed on the line.

public bool DoubleStrikethrough { get; set; }
Public Property DoubleStrikethrough As Boolean
Property Value
System.Boolean

true if the text of the run shall be displayed with two horizontal lines through each character displayed on the line; otherwise, false.

FontColor

Gets or sets the color which shall be used to display the text of the run.

public Color FontColor { get; set; }
Public Property FontColor As Color
Property Value
Color

The color which shall be used to display the text of the run.

FontName

Gets or sets the name of the font which shall be used to display the text of the run.

public string FontName { get; set; }
Public Property FontName As String
Property Value
System.String

The name of the font which shall be used to display the text of the run.

Remarks

If this property is null or System.String.Empty then theme font will be used (theme font for freshly created document is Calibri).

Fonts

Gets a detailed description of the fonts used to display the text of the run.

public CharacterFonts Fonts { get; }
Public ReadOnly Property Fonts As CharacterFonts
Property Value
CharacterFonts

The detailed description of the fonts used to display the text of the run.

Remarks

This property provides fine-grained support for getting and setting different fonts for different Unicode character ranges in a single run. In the vast majority of cases, a single font is used to display all characters of the run and the FontName property can be used instead.

Hidden

Gets or sets a value indicating whether the text of the run shall be hidden from display at display time in a document.

public bool Hidden { get; set; }
Public Property Hidden As Boolean
Property Value
System.Boolean

true if the text of the run shall be hidden from display at display time in a document; otherwise, false.

HighlightColor

Gets or sets a highlighting color which is applied as a background behind the text of the run. HighlightColor overrides BackgroundColor.

public Color HighlightColor { get; set; }
Public Property HighlightColor As Color
Property Value
Color

A highlighting color which is applied as a background behind the text of the run.

Remarks

Highlighting color must be one of the following:

Italic

Gets or sets a value indicating whether all characters in the text of the run are italic.

public bool Italic { get; set; }
Public Property Italic As Boolean
Property Value
System.Boolean

true if all characters in the text of the run are italic; otherwise, false.

Kerning

Gets or sets the smallest font size which shall have its kerning automatically adjusted. If the Size is smaller than this value, then no font kerning shall be performed. Supported only in DOCX and DOC formats.

public double Kerning { get; set; }
Public Property Kerning As Double
Property Value
System.Double

The smallest font size which shall have its kerning automatically adjusted.

Remarks

This value is currently ignored when exporting a document to PDF, XPS, or image formats.

Language

Gets or sets the language information.

public CultureInfo Language { get; set; }
Public Property Language As CultureInfo
Property Value
System.Globalization.CultureInfo

The System.Globalization.CultureInfo which will be used for defining culture specific formatting.

Remarks

Default value is System.Globalization.CultureInfo.InvariantCulture.

Position

Gets or sets the amount in points by which text shall be raised or lowered for the run in relation to the default baseline of the surrounding non-positioned text.

public double Position { get; set; }
Public Property Position As Double
Property Value
System.Double

The amount in points by which text shall be raised or lowered for the run in relation to the default baseline of the surrounding non-positioned text.

Remarks

If the value is positive, then the parent run shall be raised above the baseline of the surrounding text by the specified number of points. If the value is negative, then the parent run shall be lowered below the baseline of the surrounding text by the specified number of points.

RightToLeft

When true, the contents of this run shall have right-to-left reading order.

public bool RightToLeft { get; set; }
Public Property RightToLeft As Boolean
Property Value
System.Boolean

true if the contents of this run shall have right-to-left reading order.; otherwise, false.

Scaling

Gets or sets the percentage by which each character shall be expanded or compressed when the character is rendered in the document. Supported only in DOCX and DOC formats.

public int Scaling { get; set; }
Public Property Scaling As Integer
Property Value
System.Int32

The percentage by which each character shall be expanded or compressed when the character is rendered in the document.

Size

Gets or sets the font size (in points) which shall be applied to the text of the run when displayed.

public double Size { get; set; }
Public Property Size As Double
Property Value
System.Double

The font size which shall be applied to the text of the run when displayed.

SmallCaps

Gets or sets a value indicating whether all small letter characters in the text run shall be formatted for display only as their capital letter character equivalents in a font size two points smaller than the actual font size specified for the text.

public bool SmallCaps { get; set; }
Public Property SmallCaps As Boolean
Property Value
System.Boolean

true if all small letter characters in the text run shall be formatted for display only as their capital letter character equivalents in a font size two points smaller than the actual font size specified for the text; otherwise, false.

Spacing

Gets or sets the amount of character pitch in points which shall be added or removed after each character in the run before the following character is rendered in the document.

public double Spacing { get; set; }
Public Property Spacing As Double
Property Value
System.Double

The amount of character pitch in points which shall be added or removed after each character in the run before the following character is rendered in the document.

Strikethrough

Gets or sets a value indicating whether the text of the run shall be displayed with a single horizontal line through the center of the line.

public bool Strikethrough { get; set; }
Public Property Strikethrough As Boolean
Property Value
System.Boolean

true if the text of the run shall be displayed with a single horizontal line through the center of the line; otherwise, false.

Style

Gets or sets the character style.

public CharacterStyle Style { get; set; }
Public Property Style As CharacterStyle
Property Value
CharacterStyle

The character style.

Subscript

Gets or sets a value indicating whether the text of the run shall be repositioned as subscript.

public bool Subscript { get; set; }
Public Property Subscript As Boolean
Property Value
System.Boolean

true if the text of the run shall be repositioned as subscript; otherwise, false.

Superscript

Gets or sets a value indicating whether the text of the run shall be repositioned as superscript.

public bool Superscript { get; set; }
Public Property Superscript As Boolean
Property Value
System.Boolean

true if the text of the run shall be repositioned as superscript; otherwise, false.

UnderlineColor

Gets or sets the color for the underlining on the run.

public Color UnderlineColor { get; set; }
Public Property UnderlineColor As Color
Property Value
Color

The color for the underlining on the run.

UnderlineStyle

Gets or sets the pattern which shall be used to create the underline applied beneath the text in the run.

public UnderlineType UnderlineStyle { get; set; }
Public Property UnderlineStyle As UnderlineType
Property Value
UnderlineType

The pattern which shall be used to create the underline applied beneath the text in the run.

Methods

ClearFormatting()

Clears the formatting.

public override void ClearFormatting()
Public Overrides Sub ClearFormatting
Overrides
Remarks

This method will clear all directly set formatting values. When retrieving formatting value, they can still come from other sources, as explained in formats and styles article.

Clone()

Clones this CharacterFormat instance.

public CharacterFormat Clone()
Public Function Clone As CharacterFormat
Returns
CharacterFormat

Clone(Boolean)

Clones this CharacterFormat.

public CharacterFormat Clone(bool resolveValues)
Public Function Clone(resolveValues As Boolean) As CharacterFormat
Parameters
resolveValues
System.Boolean

If true, the values to be cloned will be fetched from this object's resolved values. This means that even if a property was never explicitly set, this method will look into this format style or in the document's default formats to resolve the values and explicitly set them in the cloned object.

Returns
CharacterFormat

Equals(Object)

Determines whether the specified System.Object is equal to this CharacterFormat instance.

public override bool Equals(object obj)
Public Overrides Function Equals(obj As Object) As Boolean
Parameters
obj
System.Object

The System.Object to compare with this character format instance.

Returns
System.Boolean

true if the specified System.Object is a CharacterFormat and is equal to this CharacterFormat instance; otherwise, false.

Overrides
System.Object.Equals(System.Object)

GetHashCode()

Returns a hash code for this CharacterFormat instance.

public override int GetHashCode()
Public Overrides Function GetHashCode As Integer
Returns
System.Int32

An integer value that specifies a hash value for this CharacterFormat instance.

Overrides
System.Object.GetHashCode()

Operators

Equality(CharacterFormat, CharacterFormat)

Determines whether first and second CharacterFormats are equal.

public static bool operator ==(CharacterFormat first, CharacterFormat second)
Public Shared Operator =(first As CharacterFormat, second As CharacterFormat) As Boolean
Parameters
first
CharacterFormat

The first character format.

second
CharacterFormat

The second character format.

Returns
System.Boolean

true if first and second character formats are equal; otherwise, false.

Inequality(CharacterFormat, CharacterFormat)

Determines whether first and second CharacterFormats are not equal.

public static bool operator !=(CharacterFormat first, CharacterFormat second)
Public Shared Operator <>(first As CharacterFormat, second As CharacterFormat) As Boolean
Parameters
first
CharacterFormat

The first character format.

second
CharacterFormat

The second character format.

Returns
System.Boolean

true if first and second character formats are not equal; otherwise, false.

Inherited Properties

Document

Gets the owner document.

(Inherited from Format)