mlreportgen.dom.PDFPageLayout Class

Namespace: mlreportgen.dom

Page format and layout for section of PDF document

Description

Use an object of the mlreportgen.dom.PDFPageLayout class to define the page format, headers, and footers of a section of a PDF document.

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

This class is only compatible with these MATLAB^® Report Generator™ output types:

• "pdf"

• "pdfa" (since R2025a)

To see what DOM objects you can append mlreportgen.dom.PDFPageLayout objects to, see More About.

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

Class Attributes

HandleCompatible	true
ConstructOnLoad	true

For information on class attributes, see Class Attributes.

Creation

Description

pageLayoutObj = mlreportgen.dom.PDFPageLayout creates a PDFPageLayout object with default property values.

Properties

PageHeaders — Page headers for this layout

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

Page headers for this layout, specified as an array of mlreportgen.dom.PDFPageHeader objects. You can define up to three page headers for a layout, one each for:

• The first page of the section

• Even pages

• Odd pages

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

PageFooters — Page footers for this layout

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

Page footers for this layout, specified as an array of mlreportgen.dom.PDFPageFooter objects. You can define up to three page footers for a layout, one each for:

• The first page of the section

• Even pages

• Odd pages

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Watermark — Watermark to apply to this page layout

[] (default) | mlreportgen.dom.Watermark object

Watermark to apply to this page layout, specified as an mlreportgen.dom.Watermark object.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Hyphenation — Type of hyphenation

0 (false) | 1 (true) | "-" | " "

Type of hyphenation, specified as one of these values:

• 1 (true) — Enable hyphenation and uses "-" for the hyphenation character.

• "-" — Enable hyphenation and uses "-" for the hyphenation character.

• " " — Enable hyphenation and uses a space (" ") for the hyphenation character

• 0 (false) — Disable hyphenation.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | logical | string

PageMargins — Sizes of margins, header, footer, and gutter

mlreportgen.dom.PageMargins object

Sizes of the margins, header, footer, and gutter for this page layout, specified as an mlreportgen.dom.PageMargins object.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

PageSize — Size of pages in layout

mlreportgen.dom.PageSize object

Size of pages in layout, specified as an mlreportgen.dom.PageSize object.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

PageBorder — Page borders for layout

[] (default) | mlreportgen.dom.PageBorder object

Page borders for layout, specified as an mlreportgen.dom.PageBorder object.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

FirstPageNumber — Number of first page in section

[] (default) | integer

Number of the first page in a section, specified as an empty array or as an integer. To continue numbering from the previous section, specify an empty array. For example if the page number of the last page of the previous section is four, the page number of the first page of this layout is five. To start the page numbering of this layout with a specific page number, specify the starting page number as an integer.

Note

Page numbers are rendered only on mlreportgen.dom.Page objects that you append to the document or to any part of the document. To render page numbers in the page headers or footers, assign an mlreportgen.dom.PDFPageHeader object to the PageHeaders property or an mlreportgen.dom.PDFPageFooter object to the PageFooters property. Then append an mlreportgen.dom.Page object to the PDFPageHeader or PDFPageFooter object. For example, see Add and Customize Page Numbers in a PDF Document. Alternatively, you can append mlreportgen.dom.Page objects to the document itself, or to elements in the document, but the page number renders only on the part of the document where you append the Page object.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: int32

PageNumberFormat — Type of page numbering to use

[] (default) | character vector | string scalar

Type of page numbering to use, specified as one of the character vectors or string scalars in the table.

Value	Meaning	Supported in DOCX	Supported in PDF
"a"	Lowercase alphabetic	Yes	Yes
"A"	Uppercase alphabetic	Yes	Yes
"i"	Lowercase Roman numerals	Yes	Yes
"I"	Uppercase Roman numerals	Yes	Yes
"n", "N", "1", "decimal"	Arabic numerals	Yes	Yes
"numberInDash"	Number with dashes on either side	Yes	No
"hebrew1"	Hebrew numerals	Yes	No
"hebrew2"	Hebrew alphabetic	Yes	No
"arabicAlpha"	Arabic alphabetic	Yes	No
"arabicAbjad"	Arabic abjad numerals	Yes	No
"thaiLetters"	Thai letters	Yes	No
"thaiNumbers"	Thai numerals	Yes	No
"thaiCounting"	Thai counting system	Yes	No

Note

Page numbers are rendered only on mlreportgen.dom.Page objects that you append to the document or to any part of the document. To render page numbers in the page headers or footers, assign an mlreportgen.dom.PDFPageHeader object to the PageHeaders property or an mlreportgen.dom.PDFPageFooter object to the PageFooters property. Then append an mlreportgen.dom.Page object to the PDFPageHeader or PDFPageFooter object. For example, see Add and Customize Page Numbers in a PDF Document. Alternatively, you can append mlreportgen.dom.Page objects to the document itself, or to elements in the document, but the page number renders only on the part of the document where you append the Page object.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | string

SectionBreak — Section break options

"Next Page" (default) | "Odd Page" | "Even Page"

Section break options, specified as one of these character vectors or string scalars:

• "Next Page" — Start the section on the next page.

• "Odd Page" — Start the section on an odd page.

• "Even Page" — Start the section on an even page.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Data Types: char | string

FootnoteOptions — Document footnote options

[] (default) | mlreportgen.dom.FootnoteOptions object

Document footnote options, specified as an mlreportgen.dom.FootnoteOptions object. The document uses the default value if any property of FootnoteOptions is empty.

Note

This property overrides the footnote options specified by the document to which this page layout belongs.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

EndnoteOptions — Document endnote options

[] (default) | mlreportgen.dom.EndnoteOptions object

Document endnote options, specified as an mlreportgen.dom.EndnoteOptions object. The document uses the default value if any property of EndnoteOptions is empty.

Note

This property overrides the endnote options specified by the document to which this page layout belongs.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

StyleName — This property is ignored

not applicable

The class ignores this property.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Style — Formats to apply to layout

array of DOM format objects

Format specification for this document element, specified as an array of DOM format objects. Formats that do not apply to this element are ignored.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

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

rotate

rotate(pageLayoutObj) switches the orientation of pages between portrait and landscape. The method switches the values of the Height and Width properties of the PageSize object that is associated with the PageSize property of pageLayoutObj. The method also switches the value of the Orientation property of the PageSize object between "portrait" and "landscape". Input Arguments pageLayoutObj — Object to clone, specified as an mlreportgen.dom.PDFPageLayout object

Examples

Change Page Margins of a Document Section

Use the CurrentPageLayout property of a document to access the PDFPageLayout object that represents the layout of the document. Change the left and right margins of the layout by setting the Left and Right properties of the mlreportgen.dom.PageMargins object used by the PDFPageLayout object.

import mlreportgen.dom.*;
d = Document('mydoc','pdf');

open(d);
pageLayoutObj = d.CurrentPageLayout;
pageLayoutObj.PageMargins.Left = '2in';
pageLayoutObj.PageMargins.Right = '2in';
p = Paragraph('Hello World');
append(d,p);

close(d);
rptview(d);

Change the Page Orientation

By default, a PDFPageLayout object specifies a page with an 11-inch height, 8.5-half inch width, and portrait orientation. To change the orientation to landscape, use the rotate method of the PDFPageLayout object. The method updates the property values of the associated mlreportgen.dom.PageSize object so that the height is 8.5 inches, the width is 11 inches, and the orientation is landscape.

import mlreportgen.dom.*;
d = Document('myreport','pdf');
open(d);
 
pageLayoutObj = d.CurrentPageLayout;
rotate(pageLayoutObj);

append(d,'This document has landscape pages');
close(d);
rptview(d);

Add and Customize Page Numbers in a PDF Document

This example shows how to add and customize page numbers in the footer section of a generated PDF document.

Import this namespace so that you do not have to use long, fully qualified class names.

import mlreportgen.dom.*

Create an mlreportgen.dom.Document object of type PDF with a title.

document = Document("my_pdf_w_page_numbers_document","pdf");
heading = Heading(1,"Customize Page Numbers Example");
append(document,heading);

Add content to the document.

append(document,LineBreak);
for pageInd = 1:5
  append(document,sprintf("Content of page number %i",pageInd));
  append(document,PageBreak);
end
append(document,Paragraph("Content of last page"));

Add a page footer to the document by assigning an mlreportgen.dom.PDFPageFooter object to the PageFooters property of the current page layout. Then set the page number format of the current page layout to uppercase Roman numerals.

curLayout = document.CurrentPageLayout;
curLayout.PageFooters = PDFPageFooter();
curLayout.PageNumberFormat = "I";

Append an mlreportgen.dom.Page object to the page footer object.

append(curLayout.PageFooters,Page());

Close and view the document.

close(document);
rptview(document);

More About

Append mlreportgen.dom.PDFPageLayout object to DOM class object

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

• mlreportgen.dom.Container

• mlreportgen.dom.Document

• mlreportgen.dom.DocumentPart

• mlreportgen.dom.Group

• mlreportgen.dom.PDFPageFooter

• mlreportgen.dom.PDFPageHeader

• mlreportgen.dom.Template

• mlreportgen.dom.TemplateDocumentPart (since R2023b)

Version History

Introduced in R2016a

R2024b: Removal of BMP for image output

Report Generator no longer supports BMP (bitmap) as an output image format. This affects snapshots, images from files, and watermarks in both the Report Explorer and the Report, DOM, and PPT APIs. See print for more information.