mlreportgen.dom.Heading class

Package: mlreportgen.dom
Superclasses:

Heading paragraph using variable level

Description

Create a heading paragraph at a particular level or whose level is calculated during report generation.

Tip

Use this class if you need to determine the heading level at runtime. Otherwise, you can use the Heading1, Heading2, etc. classes to avoid having to set the level explicitly.

Construction

headingObj = Heading(level) creates an empty heading at the specified level.

headingObj = Heading(level,text) creates the specified level heading containing the specified text.

headingObj = Heading(level,text,styleName) creates the specified level heading containing the specified text and using the specified style.

headingObj = Heading(level,domObj) creates the specified level heading containing the specified DOM object.

Input Arguments

expand all

Heading level, specified as a numeric value or variable. Use a variable to use a value calculated during report generation to determine the level number.

Data Types: double

Text to use for the heading, specified as a character vector.

The style specified by styleName must specify a paragraph style defined in the template used to create the document to which this heading is appended.

DOM object to include in the heading, specified as any of these DOM object types:

  • ExternalLink

  • Image

  • InternalLink

  • LinkTarget

  • Text

Output Arguments

expand all

Heading paragraph, represented by an mlreportgen.dom.Heading object.

Properties

expand all

Background color, specified as a character vector or string scalar that consists of a CSS color name (see https://www.crockford.com/wrrrld/color.html) or a hexadecimal RGB (truecolor) value in the form #RRGGBB.

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

Example: 'blue'

Example: '#0000ff'

Whether to use bold for text, specified as a numeric or logical 1 (true) or 0 (false). To make text bold, set Bold to true or 1.

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.

Text color, specified as a character vector or string scalar that consists of a CSS color name (see https://www.crockford.com/wrrrld/color.html) or a hexadecimal RGB (truecolor) value in the form #RRGGBB.

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: 'blue'

Example: '#0000ff'

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

Indentation amount for the fist line of this paragraph, specified as a character vector or string scalar that consists of number followed by an abbreviation for a unit of measurement. For example, '0.5in' specifies one-half inch. Valid abbreviations are:

  • px — pixels (default)

  • cm — centimeters

  • in — inches

  • mm — millimeters

  • pc — picas

  • pt — points

The indentation amount is the amount by which to indent the first line of this paragraph relative to the succeeding lines. To create a hanging indent where all of the lines are indented except for the first line, use a negative number.

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

Example: '0.5in'

Name of a font family to use for text, specified as a character vector or string scalar.

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.

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.

Example: 'Courier New'

Font size for text, 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

  • px — pixels

Horizontal alignment for this paragraph, relative to page margins or table cell borders, specified as one of the values in this table.

ValueDescriptionSupported Output Types

'center'

Center the paragraph

All

'distribute'

Distribute all characters equally

Word

'justify'

Align left side of paragraph on left side of page or table entry, and right side of paragraph on the right side of the page or table entry.

All

'KashidaHigh'

Use widest Kashida length.

Kashida is a type of justification used for some cursive scripts, such as Arabic and Persian.

Word

'KashidaLow'

Use lowest Kashida length

Word

'KashidaMedium'

Use medium Kashida length

Word

'left'

Align paragraph left

All

'right'

Align paragraph right

All

'ThaiDistribute'

Thai language justification

Word

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

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

Whether to use italic for text, specified as a numeric or logical 1 (true) or 0 (false). To make text italic, set Italic to true or 1.

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.

Left indentation in the form valueUnits. Units is an abbreviation for the units. Valid abbreviations are:

  • px — pixels (default)

  • cm — centimeters

  • in — inches

  • mm — millimeters

  • pc — picas

  • pt — points

Outline level of the paragraph, specified as an integer. 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 outline. For example, to make a paragraph appear at the top level in an outline, set the OutlineLevel property to 1.

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

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.

An array of mlreportgen.dom.DOCXSection objects that specifies the format for the text.

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

Data Types: char

Tag for this document element, specified as a character vector.

The DOM generates a session-unique tag when it creates the document element. Structure the tag as class:id, where class is the class of the element and id is the value of the Id property. You can specify a tag to replace the generated tag. Specifying your own tag can make it easier to identify where an issue occurred during document generation.

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

Underline valueDescriptionSupported 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 with two dots between the dashes

Word

'wave'

Wavy line

Word

'wavyHeavy'

Heavy wavy

Word

'wavyDouble'

Double wavy line

Word

'none'

No underline

All

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.

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.

How to treat white space in text, specified as one of the values in this table.

ValueDescriptionSupported 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 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

'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

'preserve'

Same as 'pre'.All

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.

Methods

Method

Purpose

append

Use Heading.append similar to how you use Paragraph.append.

Append content to heading.

clone

Use Heading.clone similar to how you use Paragraph.clone.

Copy heading.