Excel.PageLayout class

Package:

excel

Represents layout and print settings that are not dependent on any printer-specific implementation. These settings include margins, orientation, page numbering, title rows, and print area.

Extends

OfficeExtension.ClientObject

Remarks

[Api set: ExcelApi 1.9]

Properties

blackAndWhite	The worksheet's black and white print option.
bottomMargin	The worksheet's bottom page margin to use for printing in points.
centerHorizontally	The worksheet's center horizontally flag. This flag determines whether the worksheet will be centered horizontally when it's printed.
centerVertically	The worksheet's center vertically flag. This flag determines whether the worksheet will be centered vertically when it's printed.
context	The request context associated with the object. This connects the add-in's process to the Office host application's process.
draftMode	The worksheet's draft mode option. If true, the sheet will be printed without graphics.
firstPageNumber	The worksheet's first page number to print. A null value represents "auto" page numbering.
footerMargin	The worksheet's footer margin, in points, for use when printing.
headerMargin	The worksheet's header margin, in points, for use when printing.
headersFooters	Header and footer configuration for the worksheet.
leftMargin	The worksheet's left margin, in points, for use when printing.
orientation	The worksheet's orientation of the page.
paperSize	The worksheet's paper size of the page.
printComments	Specifies if the worksheet's comments should be displayed when printing.
printErrors	The worksheet's print errors option.
printGridlines	Specifies if the worksheet's gridlines will be printed.
printHeadings	Specifies if the worksheet's headings will be printed.
printOrder	The worksheet's page print order option. This specifies the order to use for processing the page number printed.
rightMargin	The worksheet's right margin, in points, for use when printing.
topMargin	The worksheet's top margin, in points, for use when printing.
zoom	The worksheet's print zoom options. The PageLayoutZoomOptions object must be set as a JSON object (use x.zoom = {...} instead of x.zoom.scale = ...).

Methods

getPrintArea()	Gets the RangeAreas object, comprising one or more rectangular ranges, that represents the print area for the worksheet. If there is no print area, an ItemNotFound error will be thrown.
getPrintAreaOrNullObject()	Gets the RangeAreas object, comprising one or more rectangular ranges, that represents the print area for the worksheet. If there is no print area, then this method returns an object with its isNullObject property set to true. For further information, see *OrNullObject methods and properties.
getPrintTitleColumns()	Gets the range object representing the title columns.
getPrintTitleColumnsOrNullObject()	Gets the range object representing the title columns. If not set, then this method returns an object with its isNullObject property set to true. For further information, see *OrNullObject methods and properties.
getPrintTitleRows()	Gets the range object representing the title rows.
getPrintTitleRowsOrNullObject()	Gets the range object representing the title rows. If not set, then this method returns an object with its isNullObject property set to true. For further information, see *OrNullObject methods and properties.
load(options)	Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(propertyNames)	Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
load(propertyNamesAndPaths)	Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.
set(properties, options)	Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type.
set(properties)	Sets multiple properties on the object at the same time, based on an existing loaded object.
setPrintArea(printArea)	Sets the worksheet's print area.
setPrintMargins(unit, marginOptions)	Sets the worksheet's page margins with units.
setPrintMargins(unit, marginOptions)	Sets the worksheet's page margins with units.
setPrintTitleColumns(printTitleColumns)	Sets the columns that contain the cells to be repeated at the left of each page of the worksheet for printing.
setPrintTitleRows(printTitleRows)	Sets the rows that contain the cells to be repeated at the top of each page of the worksheet for printing.
toJSON()	Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringify, in turn, calls the toJSON method of the object that's passed to it.) Whereas the original Excel.PageLayout object is an API object, the toJSON method returns a plain JavaScript object (typed as Excel.Interfaces.PageLayoutData) that contains shallow copies of any loaded child properties from the original object.

Property Details

blackAndWhite

The worksheet's black and white print option.

blackAndWhite: boolean;

Property Value

boolean

Remarks

[Api set: ExcelApi 1.9]

bottomMargin

The worksheet's bottom page margin to use for printing in points.

bottomMargin: number;

Property Value

number

Remarks

[Api set: ExcelApi 1.9]

centerHorizontally

The worksheet's center horizontally flag. This flag determines whether the worksheet will be centered horizontally when it's printed.

centerHorizontally: boolean;

Property Value

boolean

Remarks

[Api set: ExcelApi 1.9]

centerVertically

The worksheet's center vertically flag. This flag determines whether the worksheet will be centered vertically when it's printed.

centerVertically: boolean;

Property Value

boolean

Remarks

[Api set: ExcelApi 1.9]

context

The request context associated with the object. This connects the add-in's process to the Office host application's process.

context: RequestContext;

Property Value

Excel.RequestContext

draftMode

The worksheet's draft mode option. If true, the sheet will be printed without graphics.

draftMode: boolean;

Property Value

boolean

Remarks

[Api set: ExcelApi 1.9]

firstPageNumber

The worksheet's first page number to print. A null value represents "auto" page numbering.

firstPageNumber: number | "";

Property Value

number | ""

Remarks

[Api set: ExcelApi 1.9]

footerMargin

The worksheet's footer margin, in points, for use when printing.

footerMargin: number;

Property Value

number

Remarks

[Api set: ExcelApi 1.9]

headerMargin

The worksheet's header margin, in points, for use when printing.

headerMargin: number;

Property Value

number

Remarks

[Api set: ExcelApi 1.9]

headersFooters

Header and footer configuration for the worksheet.

readonly headersFooters: Excel.HeaderFooterGroup;

Property Value

Excel.HeaderFooterGroup

Remarks

[Api set: ExcelApi 1.9]

leftMargin

The worksheet's left margin, in points, for use when printing.

leftMargin: number;

Property Value

number

Remarks

[Api set: ExcelApi 1.9]

orientation

The worksheet's orientation of the page.

orientation: Excel.PageOrientation | "Portrait" | "Landscape";

Property Value

Excel.PageOrientation | "Portrait" | "Landscape"

Remarks

[Api set: ExcelApi 1.9]

paperSize

The worksheet's paper size of the page.

paperSize: Excel.PaperType | "Letter" | "LetterSmall" | "Tabloid" | "Ledger" | "Legal" | "Statement" | "Executive" | "A3" | "A4" | "A4Small" | "A5" | "B4" | "B5" | "Folio" | "Quatro" | "Paper10x14" | "Paper11x17" | "Note" | "Envelope9" | "Envelope10" | "Envelope11" | "Envelope12" | "Envelope14" | "Csheet" | "Dsheet" | "Esheet" | "EnvelopeDL" | "EnvelopeC5" | "EnvelopeC3" | "EnvelopeC4" | "EnvelopeC6" | "EnvelopeC65" | "EnvelopeB4" | "EnvelopeB5" | "EnvelopeB6" | "EnvelopeItaly" | "EnvelopeMonarch" | "EnvelopePersonal" | "FanfoldUS" | "FanfoldStdGerman" | "FanfoldLegalGerman";

Property Value

Excel.PaperType | "Letter" | "LetterSmall" | "Tabloid" | "Ledger" | "Legal" | "Statement" | "Executive" | "A3" | "A4" | "A4Small" | "A5" | "B4" | "B5" | "Folio" | "Quatro" | "Paper10x14" | "Paper11x17" | "Note" | "Envelope9" | "Envelope10" | "Envelope11" | "Envelope12" | "Envelope14" | "Csheet" | "Dsheet" | "Esheet" | "EnvelopeDL" | "EnvelopeC5" | "EnvelopeC3" | "EnvelopeC4" | "EnvelopeC6" | "EnvelopeC65" | "EnvelopeB4" | "EnvelopeB5" | "EnvelopeB6" | "EnvelopeItaly" | "EnvelopeMonarch" | "EnvelopePersonal" | "FanfoldUS" | "FanfoldStdGerman" | "FanfoldLegalGerman"

Remarks

[Api set: ExcelApi 1.9]

printComments

Specifies if the worksheet's comments should be displayed when printing.

printComments: Excel.PrintComments | "NoComments" | "EndSheet" | "InPlace";

Property Value

Excel.PrintComments | "NoComments" | "EndSheet" | "InPlace"

Remarks

[Api set: ExcelApi 1.9]

printErrors

The worksheet's print errors option.

printErrors: Excel.PrintErrorType | "AsDisplayed" | "Blank" | "Dash" | "NotAvailable";

Property Value

Excel.PrintErrorType | "AsDisplayed" | "Blank" | "Dash" | "NotAvailable"

Remarks

[Api set: ExcelApi 1.9]

printGridlines

Specifies if the worksheet's gridlines will be printed.

printGridlines: boolean;

Property Value

boolean

Remarks

[Api set: ExcelApi 1.9]

printHeadings

Specifies if the worksheet's headings will be printed.

printHeadings: boolean;

Property Value

boolean

Remarks

[Api set: ExcelApi 1.9]

printOrder

The worksheet's page print order option. This specifies the order to use for processing the page number printed.

printOrder: Excel.PrintOrder | "DownThenOver" | "OverThenDown";

Property Value

Excel.PrintOrder | "DownThenOver" | "OverThenDown"

Remarks

[Api set: ExcelApi 1.9]

rightMargin

The worksheet's right margin, in points, for use when printing.

rightMargin: number;

Property Value

number

Remarks

[Api set: ExcelApi 1.9]

topMargin

The worksheet's top margin, in points, for use when printing.

topMargin: number;

Property Value

number

Remarks

[Api set: ExcelApi 1.9]

zoom

The worksheet's print zoom options. The PageLayoutZoomOptions object must be set as a JSON object (use x.zoom = {...} instead of x.zoom.scale = ...).

zoom: Excel.PageLayoutZoomOptions;

Property Value

Excel.PageLayoutZoomOptions

Remarks

[Api set: ExcelApi 1.9]

Method Details

getPrintArea()

Gets the RangeAreas object, comprising one or more rectangular ranges, that represents the print area for the worksheet. If there is no print area, an ItemNotFound error will be thrown.

getPrintArea(): Excel.RangeAreas;

Returns

Excel.RangeAreas

Remarks

[Api set: ExcelApi 1.9]

getPrintAreaOrNullObject()

Gets the RangeAreas object, comprising one or more rectangular ranges, that represents the print area for the worksheet. If there is no print area, then this method returns an object with its isNullObject property set to true. For further information, see *OrNullObject methods and properties.

getPrintAreaOrNullObject(): Excel.RangeAreas;

Returns

Excel.RangeAreas

Remarks

[Api set: ExcelApi 1.9]

getPrintTitleColumns()

Gets the range object representing the title columns.

getPrintTitleColumns(): Excel.Range;

Returns

Excel.Range

Remarks

[Api set: ExcelApi 1.9]

getPrintTitleColumnsOrNullObject()

Gets the range object representing the title columns. If not set, then this method returns an object with its isNullObject property set to true. For further information, see *OrNullObject methods and properties.

getPrintTitleColumnsOrNullObject(): Excel.Range;

Returns

Excel.Range

Remarks

[Api set: ExcelApi 1.9]

getPrintTitleRows()

Gets the range object representing the title rows.

getPrintTitleRows(): Excel.Range;

Returns

Excel.Range

Remarks

[Api set: ExcelApi 1.9]

getPrintTitleRowsOrNullObject()

Gets the range object representing the title rows. If not set, then this method returns an object with its isNullObject property set to true. For further information, see *OrNullObject methods and properties.

getPrintTitleRowsOrNullObject(): Excel.Range;

Returns

Excel.Range

Remarks

[Api set: ExcelApi 1.9]

load(options)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(options?: Excel.Interfaces.PageLayoutLoadOptions): Excel.PageLayout;

Parameters

options

Excel.Interfaces.PageLayoutLoadOptions

Provides options for which properties of the object to load.

Returns

Excel.PageLayout

load(propertyNames)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(propertyNames?: string | string[]): Excel.PageLayout;

Parameters

propertyNames

string | string[]

A comma-delimited string or an array of strings that specify the properties to load.

Returns

Excel.PageLayout

load(propertyNamesAndPaths)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): Excel.PageLayout;

Parameters

propertyNamesAndPaths

{ select?: string; expand?: string; }

propertyNamesAndPaths.select is a comma-delimited string that specifies the properties to load, and propertyNamesAndPaths.expand is a comma-delimited string that specifies the navigation properties to load.

Returns

Excel.PageLayout

set(properties, options)

Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type.

set(properties: Interfaces.PageLayoutUpdateData, options?: OfficeExtension.UpdateOptions): void;

Parameters

properties

Excel.Interfaces.PageLayoutUpdateData

A JavaScript object with properties that are structured isomorphically to the properties of the object on which the method is called.

options

OfficeExtension.UpdateOptions

Provides an option to suppress errors if the properties object tries to set any read-only properties.

Returns

void

set(properties)

Sets multiple properties on the object at the same time, based on an existing loaded object.

set(properties: Excel.PageLayout): void;

Parameters

properties

Excel.PageLayout

Returns

void

setPrintArea(printArea)

Sets the worksheet's print area.

setPrintArea(printArea: Range | RangeAreas | string): void;

Parameters

printArea

Excel.Range | Excel.RangeAreas | string

The range or ranges of the content to print.

Returns

void

Remarks

[Api set: ExcelApi 1.9]

setPrintMargins(unit, marginOptions)

Sets the worksheet's page margins with units.

setPrintMargins(unit: Excel.PrintMarginUnit, marginOptions: Excel.PageLayoutMarginOptions): void;

Parameters

unit

Excel.PrintMarginUnit

Measurement unit for the margins provided.

marginOptions

Excel.PageLayoutMarginOptions

Margin values to set. Margins not provided remain unchanged.

Returns

void

Remarks

[Api set: ExcelApi 1.9]

setPrintMargins(unit, marginOptions)

Sets the worksheet's page margins with units.

setPrintMargins(unit: "Points" | "Inches" | "Centimeters", marginOptions: Excel.PageLayoutMarginOptions): void;

Parameters

unit

"Points" | "Inches" | "Centimeters"

Measurement unit for the margins provided.

marginOptions

Excel.PageLayoutMarginOptions

Margin values to set. Margins not provided remain unchanged.

Returns

void

Remarks

[Api set: ExcelApi 1.9]

setPrintTitleColumns(printTitleColumns)

Sets the columns that contain the cells to be repeated at the left of each page of the worksheet for printing.

setPrintTitleColumns(printTitleColumns: Range | string): void;

Parameters

printTitleColumns

Excel.Range | string

The columns to be repeated to the left of each page. The range must span the entire column to be valid.

Returns

void

Remarks

[Api set: ExcelApi 1.9]

setPrintTitleRows(printTitleRows)

Sets the rows that contain the cells to be repeated at the top of each page of the worksheet for printing.

setPrintTitleRows(printTitleRows: Range | string): void;

Parameters

printTitleRows

Excel.Range | string

The rows to be repeated at the top of each page. The range must span the entire row to be valid.

Returns

void

Remarks

[Api set: ExcelApi 1.9]

toJSON()

Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringify, in turn, calls the toJSON method of the object that's passed to it.) Whereas the original Excel.PageLayout object is an API object, the toJSON method returns a plain JavaScript object (typed as Excel.Interfaces.PageLayoutData) that contains shallow copies of any loaded child properties from the original object.

toJSON(): Excel.Interfaces.PageLayoutData;

Returns

Excel.Interfaces.PageLayoutData