mlreportgen.dom.Text Class

Namespace: mlreportgen.dom

Text object

Description

Use an object of the mlreportgen.dom.Text class to include text in a document.

To see what DOM objects you can append an mlreportgen.dom.Text object to, see Append mlreportgen.dom.Text object to DOM class object.

The mlreportgen.dom.Text class is a handle class.

Class Attributes

HandleCompatible	true
ConstructOnLoad	true

Creation

Description

textObj = mlreportgen.dom.Text creates an empty Text object.

textObj = mlreportgen.dom.Text(text) creates a Text object that contains the specified text and sets the Content property to text.

textObj = mlreportgen.dom.Text(text,styleName) also specifies the style and sets the StyleName property to styleName. You must define the style in the style sheet in the template of the document to which you append this Text object.

Properties

Content — Text contained by this document element

"" (default) | character vector | string scalar

Text contained by this document element, specified as a character vector or string scalar.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | string

FontFamilyName — Name of font family for text

[] | character vector | string scalar

Name of a font family to use for text, specified as a character vector or string scalar. To specify substitutions for the font, do not specify the font family by setting this property. Instead, create and add an mlreportgen.dom.FontFamily object to the Style property.

Setting the FontFamilyName property adds a corresponding mlreportgen.dom.FontFamily format object to the Style property. Setting the FontFamilyName property is the same as setting the FontName property of an mlreportgen.dom.FontFamily object. Setting the FontFamilyName property to an empty value removes the object.

Example: "Courier New"

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | string

FontSize — Font size for document element

[] (default) | character vector | string scalar

Font size for document element specified as a character vector or string scalar that contains a number followed by an abbreviation for a unit of measurement. For example, "12pt" specifies twelve points. Valid abbreviations are:

• "px" — Pixels

• "cm" — Centimeters

• "in" — Inches

• "mm" — Millimeters

• "pc" — Picas

• "pt" — Points

Setting the FontSize property adds a corresponding mlreportgen.dom.FontSize format object to the Style property. Setting the FontSize property to an empty value removes the object.

Example: "12pt"

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | string

BackgroundColor — Background color

[] (default) | character vector | string scalar

Background color, specified as a character vector or string scalar that contains a CSS color name, hexadecimal RGB value, or decimal RGB value.

Format	Value
CSS color name	Specify a CSS color name. For a list of CSS color names, see https://www.w3.org/wiki/CSS/Properties/color/keywords.
Hexadecimal RGB value	Use the format "#RRGGBB". Use # as the first character and two-digit hexadecimal numbers for the red, green, and blue values. You can use uppercase or lowercase letters.
Decimal RGB color value	Use the format "rgb(r,g,b)", where r, g, and b are comma-separated positive integers that specify the red, green, and blue values, respectively. Each value range must be between 0 and 255.

Setting the BackgroundColor property adds a mlreportgen.dom.BackgroundColor format object to the Style property. Setting the BackgroundColor property to an empty value removes the object.

Example: "red" specifies a red color using a CSS color name.

Example: "#0000ff" specifies a blue color using a hexadecimal RGB value.

Example: "rgb(128,0,128)" specifies a purple color using a decimal RGB color value.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | string

Color — Document element object color

[] (default) | character vector | string scalar

Document element object color, specified as a character vector or string scalar that contains a CSS color name, hexadecimal RGB value, or decimal RGB value.

Format	Value
CSS color name	Specify a CSS color name. For a list of CSS color names, see https://www.w3.org/wiki/CSS/Properties/color/keywords.
Hexadecimal RGB value	Use the format "#RRGGBB". Use # as the first character and two-digit hexadecimal numbers for the red, green, and blue values. You can use uppercase or lowercase letters.
Decimal RGB color value	Use the format "rgb(r,g,b)", where r, g, and b are comma-separated positive integers that specify the red, green, and blue values, respectively. Each value range must be between 0 and 255.

Setting the Color property adds a corresponding mlreportgen.dom.Color format object to the Style property. Setting the Color property to an empty value removes the object.

Example: "red" specifies a red color using a CSS color name.

Example: "#0000ff" specifies a blue color using a hexadecimal RGB value.

Example: "rgb(128,0,128)" specifies a purple color using a decimal RGB color value.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | string

Bold — Whether to use bold for document element

[] (default) | 1 (true) | 0 (false)

Whether to use bold for this document element, specified as a logical 1 (true) or 0 (false). When you specify:

• 1 (true) — Render document element in bold text.

• 0 (false) — Render document element in regular weight.

Note

Setting the Bold property adds a corresponding mlreportgen.dom.Bold format object to the Style property. Setting the Bold property to an empty value removes the object.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: logical

Italic — Whether to use italic for document element

[] (default) | 1 (true) | 0 (false)

Whether to use italic for document element, specified as a logical 1 (true) or 0 (false). When you specify:

• 1 (true) — Render document element in italic text.

• 0 (false) — Render document element in straight text.

Note

Setting the Italic property adds a corresponding mlreportgen.dom.Italic format object to the Style property. Setting the Italic property to an empty value removes the object.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: logical

Strike — Text strikethrough

[] (default) | "none" | "single" | "double"

Text strikethrough, specified as one of these values:

• "none" — No strikethrough

• "single" — Single line

• "double" — Double line (for Word reports only)

Setting the Strike property adds a corresponding mlreportgen.dom.Strike format object to the Style property for this document element. Setting the Strike property to an empty value removes the object.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | string

Underline — Type of underline

[] (default) | "single" | "none" | ...

Type of underline, specified as one of the values in this table.

Underline value	Description	Supported Output Types
"single"	Single line	All
"words"	Underline all characters except spaces	Word
"double"	Double line	Word
"thick"	Thick line	Word
"dotted"	Dotted line	Word
"dottedHeavy"	Thick dotted line	Word
"dash"	Dashed line	Word
"dashedHeavy"	Line with heavy dashes	Word
"dashLong"	Line with long dashes	Word
"dashLongHeavy"	Line with heavy long dashes	Word
"dotDash"	Dot-dash line	Word
"dashDotHeavy"	Heavy dash-dot line	Word
"dotDotDash"	Dot-dot-dash line	Word
"dashDotDotHeavy"	Line with heavy dashes and two dots between the dashes	Word
"wave"	Wavy line	Word
"wavyHeavy"	Heavy wavy	Word
"wavyDouble"	Double wavy line	Word
"none"	No underline	All

To specify both the color and the type of the underline, do not set the Underline property. Instead, set the Style property to include an mlreportgen.dom.Underline format object that specifies the underline type and color.

Setting the Underline property adds a corresponding mlreportgen.dom.Underline format object to the Style property. Setting the Underline property to an empty value removes the object.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | string

WhiteSpace — How to treat white space in text

[] (default) | "normal" | "nowrap" | ...

How to treat white space and line breaks in text, specified as one of the values in this table. The WhiteSpace property does not apply when the Type property of the Document object is PDF.

Value	Description	Supported Output Types
"normal"	For HTML and PDF, this value removes spaces at the beginning and the end of text. Multiple spaces in the text collapse to a single space. For Microsoft® Word, this value removes spaces at the beginning and end of text.	All
"nowrap"	Sequences of white space collapse into a single white space. Text never wraps to the next line.	HTML
"pre"	Preserves white space. Text wraps only on line breaks. Acts like the <pre> tag in HTML.	HTML and PDF
"preserve"	Same as "pre".	All
"pre-line"	Sequences of white space collapse into a single white space. Text wraps when necessary and on line breaks.	HTML and PDF
"pre-wrap"	Preserves white space. Text wraps when necessary and on line breaks.	HTML and PDF

Setting the WhiteSpace property adds a corresponding mlreportgen.dom.WhiteSpace format object to the Style property. Setting the WhiteSpace property to an empty value removes the object.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | string

StyleName — Name of stylesheet-defined style

[] (default) | character vector | string scalar

Name of stylesheet-defined style, specified as a character vector or string scalar. The style name is the name of a style specified in the style sheet of the document or document part to which this element is appended. The specified style defines the appearance of this element in the output document unless the formats specified by the Style property of this element override it. To learn more about using style sheets, see Use Style Sheet Styles.

Note

Microsoft Word reports ignore style names that are not defined in the document template. For more information on Microsoft Word templates, see Templates for DOM API Report Programs.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | string

Style — Format specification

{} (default) | cell array of DOM format objects

Format specification for this document element object, specified as a cell array of DOM format objects. The formats specified by this property override corresponding formats specified by the StyleName property of this element. Formats that do not apply to this document element object are ignored.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: cell

CustomAttributes — Custom attributes of document element

[] (default) | array of mlreportgen.dom.CustomAttribute objects

Custom attributes of the document element, specified as an array of mlreportgen.dom.CustomAttribute objects. The custom attributes must be supported by the output format of the document element to which this object is appended.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Parent — Parent of this object

document element object

Parent of this object, specified as a document element object. A document element must have only one parent.

Attributes:

GetAccess	public
SetAccess	private
NonCopyable	true

Children — Children of this object

array of document element objects

Children of this object, specified as an array of document element objects. This property contains the document element objects appended using the append method.

Attributes:

GetAccess	public
SetAccess	private
NonCopyable	true

Tag — Tag

character vector | string scalar

Tag, specified as a character vector or string scalar. The DOM API generates a session-unique tag as part of the creation of this object. The generated tag has the form CLASS:ID, where CLASS is the object class and ID is the value of the Id property of the object. Use this value to help identify where an issue occurs during document generation.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | string

Id — Object identifier

character vector | string scalar

Object identifier, specified as a character vector or string scalar. The DOM API generates a session-unique identifier when it creates the document element object.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | string

Methods

Public Methods

Method	Purpose
append	customElementObjOut = append(classObj,customElementObj) appends a CustomElement object to the mlreportgen.dom.Text object. Input Arguments classObj — Class object to append custom element to, specified as an mlreportgen.dom.Text object. customElementObjOut — Appended custom element, specified as an CustomElement object. Return Values customElementObjOut — Custom element object copy, returned as an CustomElement object. Note You may only use CustomElement objects in PDF and Word reports. For more information on how to use custom elements, see mlreportgen.dom.CustomElement.
clone	copiedObj = clone(soureceObj) returns a copy of the mlreportgen.dom.Text object specified by soureceObj. The copy includes the children of the source object, but not the parent. Note Do not append the same object to a document more than once. Use clone to create a copy when you want to reuse the same content elsewhere in a document. Input Arguments soureceObj — Object to clone, specified as an mlreportgen.dom.Text object Return Values copiedObj— Object copy, returned as an mlreportgen.dom.Text object For more information, see the equivalent method for the mlreportgen.dom.Paragraph class, clone.

Examples

Format Paragraph Text by Using Separate Text Objects

In this example, you format a paragraph by using two separate mlreportgen.dom.Text objects so that each piece of text can have its own style. The first Text object underlines and bolds the text. The second Text object uses the default style.

Import the DOM API namespace so that you do not have to use long, fully qualified names.

import mlreportgen.dom.*

Create a Document object.

d = Document("mydoc","html");

Create a Paragraph object.

para = Paragraph();

Create a Text object for the text that you want to bold and underline. Append the Text object to the Paragraph object,

paraTitle = Text("Results:");
paraTitle.Bold = true;
paraTitle.Underline = "single";
append(para,paraTitle);

Create a Text object for the rest of the text in the paragraph and append the Text object to the Paragraph object.

paraContent = Text(" Study 1");
append(para,paraContent);
append(d,para);

Close and view the report.

close(d);
rptview(d);

Here is the generated paragragh:

More About

Append content to mlreportgen.dom.Text object

You can append an mlreportgen.dom.CustomElement object to an mlreportgen.dom.Text object.

append(classObj,customElementObj);

Append mlreportgen.dom.Text object to DOM class object

You can append an mlreportgen.dom.Text object to these DOM class objects:

• mlreportgen.dom.Container

• mlreportgen.dom.CustomElement

• mlreportgen.dom.Document

• mlreportgen.dom.DocumentPart

• mlreportgen.dom.DOCXPageFooter

• mlreportgen.dom.DOCXPageHeader

• mlreportgen.dom.EmbeddedObject

• mlreportgen.dom.Endnote (since R2024a)

• mlreportgen.dom.ExternalLink

• mlreportgen.dom.Footnote (since R2024a)

• mlreportgen.dom.Group

• mlreportgen.dom.Heading

• mlreportgen.dom.Heading1

• mlreportgen.dom.Heading2

• mlreportgen.dom.Heading3

• mlreportgen.dom.Heading4

• mlreportgen.dom.Heading5

• mlreportgen.dom.Heading6

• mlreportgen.dom.HTMLPage (since R2024a)

• mlreportgen.dom.InternalLink

• mlreportgen.dom.LinkTarget

• mlreportgen.dom.ListItem

• mlreportgen.dom.OrderedList

• mlreportgen.dom.Paragraph

• mlreportgen.dom.PDFPageFooter

• mlreportgen.dom.PDFPageHeader

• mlreportgen.dom.Preformatted

• mlreportgen.dom.TableEntry

• mlreportgen.dom.TableHeaderEntry

• mlreportgen.dom.Template

• mlreportgen.dom.TemplateDocumentPart (since R2023b)

• mlreportgen.dom.UnorderedList

Tips

• When you append mlreportgen.dom.Text objects in documents, the object content appends differently depending on the document format. In HTML documents, the content appends in the same line. In PDF and DOCX documents, the content appends in separate lines. To append the content in the same line, create a mlreportgen.dom.Paragraph object, append the content to the paragraph object by using the append method, then append the paragraph object to the document object.

Version History

Introduced in R2014b

R2026a: Append datetime arrays to Text objects

You can append datetime arrays to Text objects. Use this approach to add datetime arrays to report elements outside of tables. You can then append the Text object to other supporting DOM objects as normal. The resulting report shows the point in time stored in the array.