mlreportgen.dom.Paragraph class

Package: mlreportgen.dom
Superclasses:

Formatted block of text (paragraph)

Description

Use a mlreportgen.dom.Paragraph object to define a paragraph. You can append document elements, such as an image, to a paragraph.

Construction

paragraphObj = Paragraph(text) creates a paragraph containing a mlreportgen.dom.Text object with the text specified by text.

paragraphObj = Paragraph(text,styleName) creates a paragraph having that specified style. The style specified by styleName must be defined in the template used for the document element to which this paragraph is appended.

paragraphObj = Paragraph(docElementObj) creates a paragraph containing the document element specified by docElementObj (for example, an image).

Input Arguments

text — Paragraph text

character vector

Paragraph text, specified as a character vector.

styleName — Style for the paragraph

character vector

The name of a style, specified as a character vector. The style must be defined in the template used to create the document to which this paragraph is appended.

docElementObj — Document element to include in the new paragraph

a DOM object

A DOM object to include in a paragraph. You can specify these DOM objects:

• mlreportgen.dom.ExternalLink

• mlreportgen.dom.Image

• mlreportgen.dom.InternalLink

• mlreportgen.dom.Text

• mlreportgen.dom.LinkTarget

Output Arguments

paragraphObj — Paragraph

mlreportgen.dom.Paragraph object

Paragraph, represented by an mlreportgen.dom.Paragraph object.

Properties

BackgroundColor — Background color

character vector

Background color, specified as either:

• The name of a color. The name must be a CSS color name. See https://www.crockford.com/wrrrld/color.html.

• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade of blue.

Bold — Option to use bold for text

[] (default) | logical value

To make text bold, set this property to true or 1. If this property is empty and the StyleName property for this document element specifies a style sheet style, the weight of the text is determined by that style. Setting the Bold property adds a corresponding mlreportgen.dom.Bold format object to the Style property of this document element. Removing the Bold property setting removes the object.

Data Types: logical

Color — Text color

character vector

Text color, specified as either:

• The name of a color. The name must be a CSS color name. See https://www.crockford.com/wrrrld/color.html.

• A hexadecimal RGB (truecolor) value as #RRGGBB. For example, #0000ff is a shade of blue.

Children — Children of this paragraph

array of mlreportgen.dom.Element objects

This read-only property lists children elements, such as an image (mlreportgen.dom.Image) object, that the paragraph contains.

CustomAttributes — Custom attributes of document element

array of mlreportgen.dom.CustomAttribute objects

The output format must support the custom attributes of this document element.

FirstLineIndent — Indentation amount for first line of paragraph

character vector

Amount by which to indent the first line of this paragraph relative to succeeding lines. To create a hanging indent, in which all the lines are indented except for the first line, use a negative number.

Specify the value in the form valueUnits, where Units is an abbreviation for the units. Use one of these abbreviations for the units.

• px — pixels (default)

• cm — centimeters

• in — inches

• mm — millimeters

• pc — picas

• pt — points

FontFamilyName — Name of font family for text

character vector

The name of a font family.

To specify substitutions for this font, do not set this property. Instead create and add a mlreportgen.dom.FontFamily object to the Style property of this document element.

Setting the FontFamilyName property adds a corresponding mlreportGen.dom.FontFamily format object to the Style property for this document element. Setting the FontFamilyName property is the same as setting the FontName property of mlreportgen.dom.FontFamily. Removing the FontFamilyName property setting removes the object.

FontSize — Font size for paragraph text

character vector

Setting the FontSize property adds a corresponding mlreportGen.dom.FontSize format object to the Style property for this document element. Removing the FontSize property setting removes the object.

Specify the font size in the form valueUnits, where Units is an abbreviation for the units. Use one of these abbreviations:

• px — pixels (default)

• cm — centimeters

• in — inches

• mm — millimeters

• pc — picas

• pt — points

HAlign — Horizontal alignment of this paragraph

character vector

Horizontal alignment for a paragraph, relative to page margins or table cell borders, specified as one of these values.

Value	Description	Supported Output Types
'center'	Center the paragraph	All output types
'distribute'	Distribute all characters equally	Word
'justify'	Align left side of paragraph on left side of page, and right side of paragraph on the right side of the page	All output types
'KashidaHigh'	Use widest Kashida length	Word
'KashidaLow'	Use lowest Kashida length	Word
'KashidaMedium'	Use medium Kashida length	Word
'left'	Align paragraph left	All output types
'right'	Align paragraph right	All output types
'ThaiDistribute'	Thai language justification	Word

Id — ID for document element

character vector

ID for this document element, specified as a character vector. The DOM generates a session-unique ID when it creates the document element. You can specify your own ID.

Italic — Option to use italics for text

[] (default) | logical value

To use italics for text, set this property to true. If this property is empty and the StyleName property for this document element specifies a style sheet style, the slant of the text is determined by that style. Setting the Italic property adds a corresponding mlreportgen.dom.Italic format object to the Style property of this document element. Removing the Italic property setting removes the object.

Data Types: logical

OuterLeftMargin — Left indentation for paragraph

character vector

Space between the left outer boundary of this paragraph and the left inner boundary of its container. This is equivalent to the left indentation property of a Microsoft^® Word paragraph.

To indent a paragraph from both the left and right margin of a page, do not set this property. Instead, add to the Style property of this paragraph a mlreportgen.dom.OuterMargin object specifying the left and right indentations.

Setting the OuterLeftMargin property adds a corresponding mlreportGen.dom.OuterMargin format object to the Style property for this document element. Removing the OuterLeftMargin property setting removes the object.

The value has the form valueUnits, where Units is an abbreviation for the units. Use one of these abbreviations for the units:

• px — pixels (default)

• cm — centimeters

• in — inches

• mm — millimeters

• pc — picas

• pt — points

OutlineLevel — Outline level of this paragraph

[] (default) | numeric value

Setting the OutlineLevel property causes this paragraph to be included in automatically generated outlines, such as a table of contents. The value specifies the level of the paragraph in the table of contents. For example, to make a paragraph appear as a Heading 1 (Word) or h1 (HTML), set OutlineLevel to 1.

Data Types: int32

Parent — Parent of document element

DOM object

This read-only property lists the parent of this document element.

Strike — Text strikethrough

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

Text strikethrough, specified as one of these values:

• 'none' — Do not use strikethrough.

• 'single' — Use a single line for strikethrough.

• 'double' — Use a double line for strikethrough for Word documents.

Setting the Strike property adds a corresponding mlreportGen.dom.Strike format object to the Style property for this document element. Removing the Strike property setting removes the object.

Style — Paragraph formatting

cell array of format objects

A cell array of DOM format objects that specifies the formats for this paragraph style.

StyleName — Paragraph style name

character vector

The style specified by StyleName must be defined in the template used to create the document element to which this paragraph is appended.

Tag — Tag for document element

character vector

Tag for document element, specified as a character vector.

A session-unique ID is generated as part of document element creation. The generated tag has the form CLASS:ID, where CLASS is the class of the element and ID is the value of the Id property of the object. You can specify a tag to replace the generated tag.

For example, to make it easier to identify where an issue occurred during document generation, you can specify your own tag value.

Underline — Type of underline, if any, for text

[] (default) | character vector

You can specify one of the following types of underlines.

Border Value	Description	Supported Output Types
'dash'	Dashed underline	Word
'dashedHeavy'	Line with heavy dashes	Word
'dashLong'	Line with long dashes	Word
'dashLongHeavy'	Line with heavy long dashes	Word
'dashDotDotHeavy'	Line with heavy dashes with two dots between the dashes	Word
'dashDotHeavy'	Heavy dash-dot line	Word
'dotted'	Dotted line	Word
'dottedHeavy'	Thick dotted line	Word
'dotDash'	Dot-dash line	Word
'dotDotDash'	Dot-dot-dash line	Word
'dashDotHeavy'	Heavy dot-dash line	Word
'double'	Double line	Word
'none'	Do not use underlining	All output types
'single'	Single line	All output types
'thick'	Thick line	Word
'wave'	Wavy line	Word
'waveyDouble'	Double wavy line	Word
'waveyHeavy'	Heavy wavy	Word
'words'	Underline non-space characters only	Word

If this property is empty and StyleName property of this document element specifies a style sheet style, the type of underline is determined by that style.

To specify the color as well as the type of the underline, do not set the Underline property. Instead, set the Style property of this document element to include an mlreportgen.dom.Underline format object that specifies the desired underline type and color.

Setting the Underline property adds a corresponding mlreportgen.dom.Underline format object to the Style property for this document element. Removing the Underline property setting removes the object.

WhiteSpace — White space and line breaks in text

[] (default) | character vector

To specify how to handle white space, use one of these values.

Value	Description	Supported Output Types
'normal' (default)	For HTML and PDF, removes spaces at beginning and end of text. Multiple spaces within the text collapse to single space. For Word, removes spaces at beginning and end of text.	All output types
'nowrap'	Sequences of white space collapse into a single white space. Text never wraps to the next line.	HTML
'preserve'	Preserves spaces and line feeds. Acts like the <pre> tag in HTML.	All output types
'pre'	Preserves white space. Text wraps only on line breaks. Acts like the <pre> tag in HTML.	HTML and PDF
'pre-line'	Sequences of white space collapse into a single white space. Text wraps.	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 WhiteSpace format object to Style property. Removing the WhiteSpace property setting removes the WhiteSpace object.

Methods

Method	Purpose
append	Append text, images, links, link targets, or custom elements to paragraph.
clone	Copy paragraph.

Examples

Add Paragraphs

Add a paragraph with text and another with an external link.

import mlreportgen.dom.*
doc = Document('mydoc','html');

p1 = Paragraph('This will be bold text');
p1.Bold = true;
link = ExternalLink('https://www.mathworks.com/', 'MathWorks');
p2 = Paragraph(link);
p2.BackgroundColor = 'yellow';
append(doc,p1);
append(doc,p2);

close(doc);
rptview('mydoc','html');