Main Content

mlreportgen.dom.PageBorder Class

Namespace: mlreportgen.dom

Page borders for Microsoft Word and PDF page layouts

Since R2021b

Description

Use an object of the mlreportgen.dom.PageBorder class to specify page borders for Microsoft® Word and PDF reports.

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

Class Attributes

ConstructOnLoad
true
HandleCompatible
true

For information on class attributes, see Class Attributes.

Creation

Description

pageBorder = mlreportgen.dom.PageBorder creates a PageBorder object with default properties where all the segments are solid, black, and 0.5 point wide, the top and bottom segments are one point from the page margins, and the left and right segments are four points from the page margins.

pageBorder = mlreportgen.dom.PageBorder(style) specifies the default style for all border segments and sets the Style property to style.

pageBorder = mlreportgen.dom.PageBorder(style,color) also specifies the default color for all border segments and sets the Color property to color.

example

pageBorder = mlreportgen.dom.PageBorder(style,color,width) also specifies the default width for all border segments and sets the Width property to width.

example

pageBorder = mlreportgen.dom.PageBorder(style,color,width,margin) also specifies the default margin for all border segments and sets the Margin property to margin.

Properties

expand all

Default style of the page border segments, specified as one of the values in the table.

Border StyleDescriptionSupported Output TypesSupports PDF
"dashed"Dashed lineyesyes
"dashdotstroked"Line with alternating diagonal dashes and dotyesno
"dashsmallgap"Dashed line with a small gap between dashesyesno
"dotted"Dotted lineyesyes
"dotdash"Line with alternating dots and dashesyesno
"dotdotdash"Line with alternating double dots and a dashyesno
"double"Double lineyesyes
"doublewave"Double wavy lineyesno
"inset"3-D effect lineyesyes
"none"No borderyesyes
"outset"3-D effect lineyesyes
"single"Single lineyes 
"solid"Single linenoyes
"thick"Thick lineyesno
"thickthinlargegap"Dashed line with alternating thick and thin dashes with a large gapyesno
"thickthinmediumgap"Dashed line with alternating thick and thin dashes with a medium gapyesno
"thickthinsmallgap"Dashed line with alternating thick and thin dashes with a small gapyesno
"thinthicklargegap"Dashed line with alternating thin and thick dashes with a large gapyesno
"thinthickmediumgap"Dashed line with alternating thin and thick dashes with a medium gapyesno
"thinthicksmallgap"Dashed line with alternating thin and thick dashes with a small gapyesno
"thinthickthinlargegap"Dashed line with alternating thin and thick dashes with a large gapyesno
"thinthickthinmediumgap"Dashed line with alternating thin and thick dashes with a medium gapyesno
"thinthickthinsmallgap"Dashed line with alternating thin and thick dashes with a small gapyesno
"threedemboss"Embossed effect lineyesno
"threedengrave"Engraved effect lineyesno
"triple"Triple lineyesno
"wave"Wavy lineyesno

Attributes:

NonCopyable
true

Default color of the border segments, specified as a character vector or string scalar that contains the color name or equivalent hexadecimal RGB specification. See https://www.w3.org/TR/2018/REC-css-color-3-20180619/.

Example: "red"

Example: "#FF0000"

Attributes:

NonCopyable
true

Default width of the page border segments, specified as a character vector or string scalar that consists of a number followed by an abbreviation for a unit of measurement. For example, "1pt" specifies one point. Valid abbreviations are:

  • "px" — pixels

  • "cm" — centimeters

  • "in" — inches

  • "mm" — millimeters

  • "pc" — picas

  • "pt" — points

Note

Whether Word honors the Width setting depends on the style specified by the Style property. For example, Word supports only 0.75-point and 1.5-point widths for the wave style. To see the widths that Word supports for a border style, in Word, on the Design tab, under Page Background, select Page Borders. Select a border under Style, then click the Width list to see the available widths.

Example: "0.5pt"

Attributes:

NonCopyable
true

Default margin of the page border segments, specified as a character vector or string scalar that consists of a number followed by an abbreviation for a unit of measurement. For example, "10pt" specifies ten points. Valid abbreviations are:

  • "px" — pixels

  • "cm" — centimeters

  • "in" — inches

  • "mm" — millimeters

  • "pc" — picas

  • "pt" — points

For PDF documents, the margin of a border segment is the space between the segment and the page margin. For Word documents, the margin of a border segment is the space between the segment and the page margin or between the segment and the edge of the page, depending on the value of the MeasureFrom property.

For Word documents, the Margin value must between 0 points and 31 points, or the equivalent value using other units of measurement.

Example: "10pt"

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

Whether the border position is measured from the edge of the page or the edge of the page margin, which is the edge of the text, specified as "text" or "pageboundary". The "pageboundary" value applies only to Word documents. For a PDF document, the page border is always measured from the page margin.

If the value is "text", the Margin, TopMargin, LeftMargin, BottomMargin, and RightMargin properties specify the distance between a border segment and the page margin. For example, in this Word document, the page margin is one inch and the border is twenty points from the page margin.

Arrow measuring a one-inch page margin stretches from the top page edge to the text. Another arrow for the border margin stretches between the border and the text.

If the value is "pageboundary", the value of the Margin, TopMargin, LeftMargin, BottomMargin, and RightMargin properties specify the distance between the border and the edge of the page. For example, the border is 20 points from the edge of the page in this Word document:

Arrow showing a 20-point border margin stretches between the page border and the page edge.

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

Whether the page border surrounds the header region, specified as true or false. This property applies to PDF documents or to Word documents when the MeasureFrom property is set to "text".

If the value is true, the border surrounds the header. For example, the border surrounds the header in this Word document:

The page header content, "This is the header", is inside the solid black border.

If the value is false, the border does not surround the header. For example, The border does not surround the header in this Word document:

The page header content, "This is the header", is outside of the solid black border.

Note

For Word documents with multiple sections, a false value for the SurroundHeader property, or the equivalent setting in a template, applies to all sections of the document. If you specify that a page border does not surround the header for one section of the document, a page border does not surround the header for any section.

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

Whether the page border surrounds the footer region, specified as true or false. This property applies to PDF documents or to Word documents when the MeasureFrom property is set to "text".

If the value is true, the border surrounds the footer. For example, the border surrounds the footer in this Word document:

The page footer content, "This is the footer", is inside the solid black border.

If the value is false, the border does not surround the footer. For example, the border does not surround the footer in this Word document:

The page footer content, "This is the footer", is outside the solid black border.

Note

For Word documents with multiple sections, a false value for the SurroundFooter property, or the equivalent setting in a template, applies to all sections of the document. If you specify that a page border does not surround the footer for one section of the document, a page border does not surround the footer for any section.

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

Style of the top page border segment, specified as one of the values in the table.

Border StyleDescriptionSupported Output TypesSupports PDF
"dashed"Dashed lineyesyes
"dashdotstroked"Line with alternating diagonal dashes and dotyesno
"dashsmallgap"Dashed line with a small gap between dashesyesno
"dotted"Dotted lineyesyes
"dotdash"Line with alternating dots and dashesyesno
"dotdotdash"Line with alternating double dots and a dashyesno
"double"Double lineyesyes
"doublewave"Double wavy lineyesno
"inset"3-D effect lineyesyes
"none"No borderyesyes
"outset"3-D effect lineyesyes
"single"Single lineyes 
"solid"Single linenoyes
"thick"Thick lineyesno
"thickthinlargegap"Dashed line with alternating thick and thin dashes with a large gapyesno
"thickthinmediumgap"Dashed line with alternating thick and thin dashes with a medium gapyesno
"thickthinsmallgap"Dashed line with alternating thick and thin dashes with a small gapyesno
"thinthicklargegap"Dashed line with alternating thin and thick dashes with a large gapyesno
"thinthickmediumgap"Dashed line with alternating thin and thick dashes with a medium gapyesno
"thinthicksmallgap"Dashed line with alternating thin and thick dashes with a small gapyesno
"thinthickthinlargegap"Dashed line with alternating thin and thick dashes with a large gapyesno
"thinthickthinmediumgap"Dashed line with alternating thin and thick dashes with a medium gapyesno
"thinthickthinsmallgap"Dashed line with alternating thin and thick dashes with a small gapyesno
"threedemboss"Embossed effect lineyesno
"threedengrave"Engraved effect lineyesno
"triple"Triple lineyesno
"wave"Wavy lineyesno

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

Color of the top border segment, specified as a character vector or string scalar that contains the color name or equivalent hexadecimal RGB specification. See https://www.w3.org/TR/2018/REC-css-color-3-20180619/.

Example: "red"

Example: "#FF0000"

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

Width of the top border segment, specified as a character vector or string scalar that consists of a number followed by an abbreviation for a unit of measurement. For example, "1pt" specifies one point. Valid abbreviations are:

  • "px" — pixels

  • "cm" — centimeters

  • "in" — inches

  • "mm" — millimeters

  • "pc" — picas

  • "pt" — points

Note

Whether Word honors the TopWidth setting depends on the style specified by the TopStyle property. For example, Word supports only 0.75-point and 1.5-point widths for the wave style. To see the widths that Word supports for a border style, in Word, on the Design tab, under Page Background, select Page Borders. Select a border under Style, then click the Width list to see the available widths.

Example: "1pt"

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

Margin of the top border segment, specified as a character vector or string scalar that consists of a number followed by an abbreviation for a unit of measurement. For example, "10pt" specifies ten points. Valid abbreviations are:

  • "px" — pixels

  • "cm" — centimeters

  • "in" — inches

  • "mm" — millimeters

  • "pc" — picas

  • "pt" — points

For PDF documents, the margin of a border segment is the space between the segment and the page margin. For Word documents, the margin of a border segment is the space between the segment and the page margin or between the segment and the edge of the page, depending on the value of the MeasureFrom property.

For Word documents, the TopMargin value must between 0 points and 31 points, or the equivalent value using other units of measurement.

Example: "10pt"

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

Style of the left border segment, specified as one of the values in the table.

Border StyleDescriptionSupported Output TypesSupports PDF
"dashed"Dashed lineyesyes
"dashdotstroked"Line with alternating diagonal dashes and dotyesno
"dashsmallgap"Dashed line with a small gap between dashesyesno
"dotted"Dotted lineyesyes
"dotdash"Line with alternating dots and dashesyesno
"dotdotdash"Line with alternating double dots and a dashyesno
"double"Double lineyesyes
"doublewave"Double wavy lineyesno
"inset"3-D effect lineyesyes
"none"No borderyesyes
"outset"3-D effect lineyesyes
"single"Single lineyes 
"solid"Single linenoyes
"thick"Thick lineyesno
"thickthinlargegap"Dashed line with alternating thick and thin dashes with a large gapyesno
"thickthinmediumgap"Dashed line with alternating thick and thin dashes with a medium gapyesno
"thickthinsmallgap"Dashed line with alternating thick and thin dashes with a small gapyesno
"thinthicklargegap"Dashed line with alternating thin and thick dashes with a large gapyesno
"thinthickmediumgap"Dashed line with alternating thin and thick dashes with a medium gapyesno
"thinthicksmallgap"Dashed line with alternating thin and thick dashes with a small gapyesno
"thinthickthinlargegap"Dashed line with alternating thin and thick dashes with a large gapyesno
"thinthickthinmediumgap"Dashed line with alternating thin and thick dashes with a medium gapyesno
"thinthickthinsmallgap"Dashed line with alternating thin and thick dashes with a small gapyesno
"threedemboss"Embossed effect lineyesno
"threedengrave"Engraved effect lineyesno
"triple"Triple lineyesno
"wave"Wavy lineyesno

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

Color of the left border segment, specified as a character vector or string scalar that contains the color name or equivalent hexadecimal RGB specification. See https://www.w3.org/TR/2018/REC-css-color-3-20180619/.

Example: "red"

Example: "#FF0000"

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

Width of the left border segment, specified as a character vector or string scalar that consists of a number followed by an abbreviation for a unit of measurement. For example, "1pt" specifies one point. Valid abbreviations are:

  • "px" — pixels

  • "cm" — centimeters

  • "in" — inches

  • "mm" — millimeters

  • "pc" — picas

  • "pt" — points

Note

Whether Word honors the LeftWidth setting depends on the style specified by the LeftStyle property. For example, Word supports only 0.75-point and 1.5-point widths for the wave style. To see the widths that Word supports for a border style, in Word, on the Design tab, under Page Background, select Page Borders. Select a border under Style, then click the Width list to see the available widths.

Example: "1pt"

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

Margin of the left border segment, specified as a character vector or string scalar that consists of a number followed by an abbreviation for a unit of measurement. For example, "10pt" specifies ten points. Valid abbreviations are:

  • "px" — pixels

  • "cm" — centimeters

  • "in" — inches

  • "mm" — millimeters

  • "pc" — picas

  • "pt" — points

For PDF documents, the margin of a border segment is the space between the segment and the page margin. For Word documents, the margin of a border segment is the space between the segment and the page margin or between the segment and the edge of the page, depending on the value of the MeasureFrom property.

For Word documents, the LeftMargin value must between 0 points and 31 points, or the equivalent value using other units of measurement.

Example: "10pt"

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

Style of the bottom border segment, specified as one of the values in the table.

Border StyleDescriptionSupported Output TypesSupports PDF
"dashed"Dashed lineyesyes
"dashdotstroked"Line with alternating diagonal dashes and dotyesno
"dashsmallgap"Dashed line with a small gap between dashesyesno
"dotted"Dotted lineyesyes
"dotdash"Line with alternating dots and dashesyesno
"dotdotdash"Line with alternating double dots and a dashyesno
"double"Double lineyesyes
"doublewave"Double wavy lineyesno
"inset"3-D effect lineyesyes
"none"No borderyesyes
"outset"3-D effect lineyesyes
"single"Single lineyes 
"solid"Single linenoyes
"thick"Thick lineyesno
"thickthinlargegap"Dashed line with alternating thick and thin dashes with a large gapyesno
"thickthinmediumgap"Dashed line with alternating thick and thin dashes with a medium gapyesno
"thickthinsmallgap"Dashed line with alternating thick and thin dashes with a small gapyesno
"thinthicklargegap"Dashed line with alternating thin and thick dashes with a large gapyesno
"thinthickmediumgap"Dashed line with alternating thin and thick dashes with a medium gapyesno
"thinthicksmallgap"Dashed line with alternating thin and thick dashes with a small gapyesno
"thinthickthinlargegap"Dashed line with alternating thin and thick dashes with a large gapyesno
"thinthickthinmediumgap"Dashed line with alternating thin and thick dashes with a medium gapyesno
"thinthickthinsmallgap"Dashed line with alternating thin and thick dashes with a small gapyesno
"threedemboss"Embossed effect lineyesno
"threedengrave"Engraved effect lineyesno
"triple"Triple lineyesno
"wave"Wavy lineyesno

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

Color of the bottom border segment, specified as a character vector or string scalar that contains the color name or equivalent hexadecimal RGB specification. See https://www.w3.org/TR/2018/REC-css-color-3-20180619/.

Example: "red"

Example: "#FF0000"

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

Width of the bottom border segment, specified as a character vector or string scalar that consists of a number followed by an abbreviation for a unit of measurement. For example, "1pt" specifies one point. Valid abbreviations are:

  • "px" — pixels

  • "cm" — centimeters

  • "in" — inches

  • "mm" — millimeters

  • "pc" — picas

  • "pt" — points

Note

Whether Word honors the BottomWidth setting depends on the style specified by the BottomStyle property. For example, Word supports only 0.75-point and 1.5-point widths for the wave style. To see the widths that Word supports for a border style, in Word, on the Design tab, under Page Background, select Page Borders. Select a border under Style, then click the Width list to see the available widths.

Example: "1pt"

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

Margin of the bottom border segment, specified as a character vector or string scalar that consists of a number followed by an abbreviation for a unit of measurement. For example, "10pt" specifies ten points. Valid abbreviations are:

  • "px" — pixels

  • "cm" — centimeters

  • "in" — inches

  • "mm" — millimeters

  • "pc" — picas

  • "pt" — points

For PDF documents, the margin of a border segment is the space between the segment and the page margin. For Word documents, the margin of a border segment is the space between the segment and the page margin or between the segment and the edge of the page, depending on the value of the MeasureFrom property.

For Word documents, the BottomMargin value must between 0 points and 31 points, or the equivalent value using other units of measurement.

Example: "10pt"

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

Style of the right border segment, specified as one of the values in the table.

Border StyleDescriptionSupported Output TypesSupports PDF
"dashed"Dashed lineyesyes
"dashdotstroked"Line with alternating diagonal dashes and dotyesno
"dashsmallgap"Dashed line with a small gap between dashesyesno
"dotted"Dotted lineyesyes
"dotdash"Line with alternating dots and dashesyesno
"dotdotdash"Line with alternating double dots and a dashyesno
"double"Double lineyesyes
"doublewave"Double wavy lineyesno
"inset"3-D effect lineyesyes
"none"No borderyesyes
"outset"3-D effect lineyesyes
"single"Single lineyes 
"solid"Single linenoyes
"thick"Thick lineyesno
"thickthinlargegap"Dashed line with alternating thick and thin dashes with a large gapyesno
"thickthinmediumgap"Dashed line with alternating thick and thin dashes with a medium gapyesno
"thickthinsmallgap"Dashed line with alternating thick and thin dashes with a small gapyesno
"thinthicklargegap"Dashed line with alternating thin and thick dashes with a large gapyesno
"thinthickmediumgap"Dashed line with alternating thin and thick dashes with a medium gapyesno
"thinthicksmallgap"Dashed line with alternating thin and thick dashes with a small gapyesno
"thinthickthinlargegap"Dashed line with alternating thin and thick dashes with a large gapyesno
"thinthickthinmediumgap"Dashed line with alternating thin and thick dashes with a medium gapyesno
"thinthickthinsmallgap"Dashed line with alternating thin and thick dashes with a small gapyesno
"threedemboss"Embossed effect lineyesno
"threedengrave"Engraved effect lineyesno
"triple"Triple lineyesno
"wave"Wavy lineyesno

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

Color of the right border segment, specified as a character vector or string scalar that contains the color name or equivalent hexadecimal RGB specification. See https://www.w3.org/TR/2018/REC-css-color-3-20180619/.

Example: "red"

Example: "#FF0000"

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

Width of the right border segment, specified as a character vector or string scalar that consists of a number followed by an abbreviation for a unit of measurement. For example, "1pt" specifies one point. Valid abbreviations are:

  • "px" — pixels

  • "cm" — centimeters

  • "in" — inches

  • "mm" — millimeters

  • "pc" — picas

  • "pt" — points

Note

Whether Word honors the RightWidth setting depends on the style specified by the RightStyle property. For example, Word supports only 0.75-point and 1.5-point widths for the wave style. To see the widths that Word supports for a border style, in Word, on the Design tab, under Page Background, select Page Borders. Select a border under Style, then click the Width list to see the available widths.

Example: "1pt"

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

Margin of the right border segment, specified as a character vector or string scalar that consists of a number followed by an abbreviation for a unit of measurement. For example, "10pt" specifies ten points. Valid abbreviations are:

  • "px" — pixels

  • "cm" — centimeters

  • "in" — inches

  • "mm" — millimeters

  • "pc" — picas

  • "pt" — points

For PDF documents, the margin of a border segment is the space between the segment and the page margin. For Word documents, the margin of a border segment is the space between the segment and the page margin or between the segment and the edge of the page, depending on the value of the MeasureFrom property.

For Word documents, the RightMargin value must between 0 points and 31 points, or the equivalent value using other units of measurement.

Example: "10pt"

Attributes:

GetAccess
public
SetAccess
public
NonCopyable
true

Tag for mlreportgen.dom.PageBorder object, 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. Specify your own tag value to help you identify where to look when an issue occurs during document generation.

Attributes:

NonCopyable
true

Data Types: char | string

Object identifier for mlreportgen.dom.PageBorder object, specified as a character vector or string scalar. The DOM API generates a session-unique identifier when it creates the document element object. You can specify your own value for Id.

Attributes:

NonCopyable
true

Data Types: char | string

Examples

collapse all

This example generates a Microsoft Word document that has solid, red, 0.5-point borders positioned 20 points from the page boundary.

pic2a.png

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

import mlreportgen.dom.*;

Create a Word document.

d = Document("myDocument","docx");
open(d);

Create a PageBorder object and specify the border style, color, and width.

pageBorder = PageBorder("solid","red","0.5pt");

Specify that the border position is relative to the page boundary and specify the margin between the page boundary and the border.

pageBorder.MeasureFrom ="pageboundary";
pageBorder.Margin = "20pt";

Set the PageBorder property of the layout associated with the document to the PageBorder object.

d.CurrentPageLayout.PageBorder = pageBorder;

Add text to the document. Close and view the document.

append(d,"The solid, red, 0.5-point border is 20 points from the page boundary.");
close(d);
rptview(d);

This example generates a PDF document that has solid, red, 0.5-point borders positioned 20 points from the page margins.

pic3a.png

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

import mlreportgen.dom.*;

Create a PDF document.

d = Document("myDocument","pdf");
open(d);

Create a PageBorder object and specify the style, color, width, and margin for all border segments. For PDF Documents, the margin of a border segment specifies the distance between the segment and the page margin.

pageBorder = PageBorder("solid","red","0.5pt","20pt");

Set the PageBorder property of the layout associated with the document to the PageBorder object.

d.CurrentPageLayout.PageBorder = pageBorder;

Add text to the document. Close and view the document.

append(d,"The solid, red, 0.5-point border segments are twenty points from the margins.");
close(d);
rptview(d);

This example uses the Report API to generate a Word or PDF report that has red page borders on the title page and blue page borders on the other sections of the report.

Import the Report API and DOM API packages so that you do not have to use long, fully qualified class names.

import mlreportgen.report.*;
import mlreportgen.dom.*;

Create a Word report and specify solid, blue, 0.5-point default borders for all pages of the report. For a PDF report, replace "docx" with "pdf".

rpt = Report("myreport","docx");
rpt.Layout.PageBorder = PageBorder("solid","blue","0.5pt");

Create a title page and specify solid, red, 0.5-point borders for the title page. Append the title page to the report.

tp = TitlePage("Title","My Report");
tp.Layout.PageBorder = PageBorder("solid","red","0.5pt");
append(rpt,tp);

Create a chapter and append it to the report.

ch = Chapter("My Chapter");
append(rpt,ch);

Close and view the report.

close(rpt);
rptview(rpt);

In the generated report, the title page has red borders as specified by the title page reporter layout.

titlepageborder1.png

The chapter pages have the default blue borders because the chapter reporter layout did not specify page borders.

chapterpageborder1.png

Version History

Introduced in R2021b