Skip to main content

PageSetup

office_toolkit::word

Struct PageSetup 

Source 
pub struct PageSetup {
    pub width_twips: u32,
    pub height_twips: u32,
    pub orientation: Orientation,
    pub margin_top_twips: u32,
    pub margin_bottom_twips: u32,
    pub margin_left_twips: u32,
    pub margin_right_twips: u32,
    pub margin_header_twips: u32,
    pub margin_footer_twips: u32,
    pub margin_gutter_twips: u32,
    pub columns: Option<u32>,
}
Expand description

A document’s page setup (w:sectPr’s pgSz/pgMar/cols, CT_PageSz/ CT_PageMar/CT_Columns) — size, orientation, margins, and an optional equal-width multi-column layout. See Document.page_setup’s doc comment for why only one, document-wide page setup is modeled (no mid-document section breaks).

Fields§

§width_twips: u32

The page’s width, in twips (w:pgSz/@w).

§height_twips: u32

The page’s height, in twips (w:pgSz/@h).

§orientation: Orientation

The page’s orientation (w:pgSz/@orient). Note that real Word output also swaps width_twips/height_twips so the page is actually wider than tall for Landscape — this crate does not do that automatically (setting Landscape alone, without also swapping the dimensions, produces a schema-valid but visually portrait-shaped “landscape” page); the caller is responsible for passing dimensions that already match the chosen orientation, same “no hidden magic” convention as the rest of this crate.

§margin_top_twips: u32

The page’s top margin, in twips (w:pgMar/@top).

§margin_bottom_twips: u32

The page’s bottom margin, in twips (w:pgMar/@bottom).

§margin_left_twips: u32

The page’s left margin, in twips (w:pgMar/@left).

§margin_right_twips: u32

The page’s right margin, in twips (w:pgMar/@right).

§margin_header_twips: u32

The distance from the top of the page to the header’s content, in twips (w:pgMar/@header).

§margin_footer_twips: u32

The distance from the bottom of the page to the footer’s content, in twips (w:pgMar/@footer).

§margin_gutter_twips: u32

Extra binding-side margin, in twips (w:pgMar/@gutter) — added to the left margin (or the right, under w:sectPr/@rtlGutter, not modeled here; always left-side).

§columns: Option<u32>

The number of equal-width columns the page’s text flows into (w:cols, CT_Columns), or None to omit w:cols entirely (a single column, Word’s default). When Some, written as w:cols/@num with w:equalWidth="true" and a fixed w:space (DEFAULT_COLUMN_SPACING_TWIPS, matching Word’s own default spacing between columns) — CT_Columns also allows unequal, individually-sized columns via a repeated w:col child, not modeled here, same “equal widths only” scope reduction as Table.column_widths versus per-column-width columns is NOT (Table.column_widths sets individual widths; this only sets a column count, all equal) — kept deliberately simple since the common case (newsletter-style equal columns) doesn’t need more.

Implementations§

Source§

impl PageSetup

Source

pub fn new() -> PageSetup

Creates a page setup with this crate’s previous fixed defaults (A4 portrait, standard margins) — the same as PageSetup::default, spelled out as a constructor for consistency with every other type in this crate.

Examples found in repository?
examples/docx_page_layout.rs (line 18)
15fn main() -> office_toolkit::Result<()> {
16    let path = output_path("docx_page_layout.docx");
17
18    let page_setup = PageSetup::new()
19        .with_size_twips(16_838, 11_906) // A4 landscape, in twentieths of a point
20        .with_orientation(Orientation::Landscape)
21        .with_margins_twips(1_440, 1_440, 1_800, 1_800) // top, bottom, left, right
22        .with_header_footer_margins_twips(720, 720)
23        .with_gutter_twips(0)
24        .with_columns(2);
25
26    let default_header =
27        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default header — every page"));
28    let default_footer =
29        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default footer — every page"));
30    let first_header = HeaderFooter::new()
31        .with_paragraph(Paragraph::with_text("First-page header — cover page only"));
32    let even_header = HeaderFooter::new().with_paragraph(Paragraph::with_text("Even-page header"));
33
34    let document = Document::new()
35        .with_page_setup(page_setup)
36        .with_header(default_header)
37        .with_footer(default_footer)
38        .with_header_first(first_header)
39        .with_header_even(even_header)
40        .with_paragraph(heading("Page setup: A4 landscape, custom margins, two columns", false))
41        .with_paragraph(Paragraph::with_text(
42            "This document is landscape A4, with wider left/right margins than top/bottom, and its body text \
43             flows in two columns. Look at the page in Word's Layout view to see the effect.",
44        ))
45        .with_paragraph(heading("Headers and footers", true))
46        .with_paragraph(Paragraph::with_text(
47            "Page 1 (this page) uses the first-page header, since \"different first page\" headers are set. \
48             Every other page uses the default header shown above, and every page uses the default footer.",
49        ))
50        .with_paragraph(heading("A third page, to see the default header again", true))
51        .with_paragraph(Paragraph::with_text(
52            "If Word is configured to show even/odd pages differently, this page alternates between the \
53             default and even-page header depending on whether it lands on an even or odd page number.",
54        ));
55
56    document.save_to_file(&path)?;
57    println!("Wrote {}", path.display());
58    Ok(())
59}
Source

pub fn with_size_twips(self, width_twips: u32, height_twips: u32) -> PageSetup

Sets the page’s width/height, in twips, and returns it for chaining.

Examples found in repository?
examples/docx_page_layout.rs (line 19)
15fn main() -> office_toolkit::Result<()> {
16    let path = output_path("docx_page_layout.docx");
17
18    let page_setup = PageSetup::new()
19        .with_size_twips(16_838, 11_906) // A4 landscape, in twentieths of a point
20        .with_orientation(Orientation::Landscape)
21        .with_margins_twips(1_440, 1_440, 1_800, 1_800) // top, bottom, left, right
22        .with_header_footer_margins_twips(720, 720)
23        .with_gutter_twips(0)
24        .with_columns(2);
25
26    let default_header =
27        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default header — every page"));
28    let default_footer =
29        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default footer — every page"));
30    let first_header = HeaderFooter::new()
31        .with_paragraph(Paragraph::with_text("First-page header — cover page only"));
32    let even_header = HeaderFooter::new().with_paragraph(Paragraph::with_text("Even-page header"));
33
34    let document = Document::new()
35        .with_page_setup(page_setup)
36        .with_header(default_header)
37        .with_footer(default_footer)
38        .with_header_first(first_header)
39        .with_header_even(even_header)
40        .with_paragraph(heading("Page setup: A4 landscape, custom margins, two columns", false))
41        .with_paragraph(Paragraph::with_text(
42            "This document is landscape A4, with wider left/right margins than top/bottom, and its body text \
43             flows in two columns. Look at the page in Word's Layout view to see the effect.",
44        ))
45        .with_paragraph(heading("Headers and footers", true))
46        .with_paragraph(Paragraph::with_text(
47            "Page 1 (this page) uses the first-page header, since \"different first page\" headers are set. \
48             Every other page uses the default header shown above, and every page uses the default footer.",
49        ))
50        .with_paragraph(heading("A third page, to see the default header again", true))
51        .with_paragraph(Paragraph::with_text(
52            "If Word is configured to show even/odd pages differently, this page alternates between the \
53             default and even-page header depending on whether it lands on an even or odd page number.",
54        ));
55
56    document.save_to_file(&path)?;
57    println!("Wrote {}", path.display());
58    Ok(())
59}
Source

pub fn with_orientation(self, orientation: Orientation) -> PageSetup

Sets the page’s orientation and returns it for chaining. See orientation’s doc comment — does not swap width_twips/ height_twips automatically.

Examples found in repository?
examples/docx_page_layout.rs (line 20)
15fn main() -> office_toolkit::Result<()> {
16    let path = output_path("docx_page_layout.docx");
17
18    let page_setup = PageSetup::new()
19        .with_size_twips(16_838, 11_906) // A4 landscape, in twentieths of a point
20        .with_orientation(Orientation::Landscape)
21        .with_margins_twips(1_440, 1_440, 1_800, 1_800) // top, bottom, left, right
22        .with_header_footer_margins_twips(720, 720)
23        .with_gutter_twips(0)
24        .with_columns(2);
25
26    let default_header =
27        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default header — every page"));
28    let default_footer =
29        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default footer — every page"));
30    let first_header = HeaderFooter::new()
31        .with_paragraph(Paragraph::with_text("First-page header — cover page only"));
32    let even_header = HeaderFooter::new().with_paragraph(Paragraph::with_text("Even-page header"));
33
34    let document = Document::new()
35        .with_page_setup(page_setup)
36        .with_header(default_header)
37        .with_footer(default_footer)
38        .with_header_first(first_header)
39        .with_header_even(even_header)
40        .with_paragraph(heading("Page setup: A4 landscape, custom margins, two columns", false))
41        .with_paragraph(Paragraph::with_text(
42            "This document is landscape A4, with wider left/right margins than top/bottom, and its body text \
43             flows in two columns. Look at the page in Word's Layout view to see the effect.",
44        ))
45        .with_paragraph(heading("Headers and footers", true))
46        .with_paragraph(Paragraph::with_text(
47            "Page 1 (this page) uses the first-page header, since \"different first page\" headers are set. \
48             Every other page uses the default header shown above, and every page uses the default footer.",
49        ))
50        .with_paragraph(heading("A third page, to see the default header again", true))
51        .with_paragraph(Paragraph::with_text(
52            "If Word is configured to show even/odd pages differently, this page alternates between the \
53             default and even-page header depending on whether it lands on an even or odd page number.",
54        ));
55
56    document.save_to_file(&path)?;
57    println!("Wrote {}", path.display());
58    Ok(())
59}
Source

pub fn with_margins_twips( self, top: u32, bottom: u32, left: u32, right: u32, ) -> PageSetup

Sets the page’s top/bottom/left/right margins, in twips, and returns it for chaining.

Examples found in repository?
examples/docx_page_layout.rs (line 21)
15fn main() -> office_toolkit::Result<()> {
16    let path = output_path("docx_page_layout.docx");
17
18    let page_setup = PageSetup::new()
19        .with_size_twips(16_838, 11_906) // A4 landscape, in twentieths of a point
20        .with_orientation(Orientation::Landscape)
21        .with_margins_twips(1_440, 1_440, 1_800, 1_800) // top, bottom, left, right
22        .with_header_footer_margins_twips(720, 720)
23        .with_gutter_twips(0)
24        .with_columns(2);
25
26    let default_header =
27        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default header — every page"));
28    let default_footer =
29        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default footer — every page"));
30    let first_header = HeaderFooter::new()
31        .with_paragraph(Paragraph::with_text("First-page header — cover page only"));
32    let even_header = HeaderFooter::new().with_paragraph(Paragraph::with_text("Even-page header"));
33
34    let document = Document::new()
35        .with_page_setup(page_setup)
36        .with_header(default_header)
37        .with_footer(default_footer)
38        .with_header_first(first_header)
39        .with_header_even(even_header)
40        .with_paragraph(heading("Page setup: A4 landscape, custom margins, two columns", false))
41        .with_paragraph(Paragraph::with_text(
42            "This document is landscape A4, with wider left/right margins than top/bottom, and its body text \
43             flows in two columns. Look at the page in Word's Layout view to see the effect.",
44        ))
45        .with_paragraph(heading("Headers and footers", true))
46        .with_paragraph(Paragraph::with_text(
47            "Page 1 (this page) uses the first-page header, since \"different first page\" headers are set. \
48             Every other page uses the default header shown above, and every page uses the default footer.",
49        ))
50        .with_paragraph(heading("A third page, to see the default header again", true))
51        .with_paragraph(Paragraph::with_text(
52            "If Word is configured to show even/odd pages differently, this page alternates between the \
53             default and even-page header depending on whether it lands on an even or odd page number.",
54        ));
55
56    document.save_to_file(&path)?;
57    println!("Wrote {}", path.display());
58    Ok(())
59}

Sets the header/footer margins, in twips, and returns it for chaining.

Examples found in repository?
examples/docx_page_layout.rs (line 22)
15fn main() -> office_toolkit::Result<()> {
16    let path = output_path("docx_page_layout.docx");
17
18    let page_setup = PageSetup::new()
19        .with_size_twips(16_838, 11_906) // A4 landscape, in twentieths of a point
20        .with_orientation(Orientation::Landscape)
21        .with_margins_twips(1_440, 1_440, 1_800, 1_800) // top, bottom, left, right
22        .with_header_footer_margins_twips(720, 720)
23        .with_gutter_twips(0)
24        .with_columns(2);
25
26    let default_header =
27        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default header — every page"));
28    let default_footer =
29        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default footer — every page"));
30    let first_header = HeaderFooter::new()
31        .with_paragraph(Paragraph::with_text("First-page header — cover page only"));
32    let even_header = HeaderFooter::new().with_paragraph(Paragraph::with_text("Even-page header"));
33
34    let document = Document::new()
35        .with_page_setup(page_setup)
36        .with_header(default_header)
37        .with_footer(default_footer)
38        .with_header_first(first_header)
39        .with_header_even(even_header)
40        .with_paragraph(heading("Page setup: A4 landscape, custom margins, two columns", false))
41        .with_paragraph(Paragraph::with_text(
42            "This document is landscape A4, with wider left/right margins than top/bottom, and its body text \
43             flows in two columns. Look at the page in Word's Layout view to see the effect.",
44        ))
45        .with_paragraph(heading("Headers and footers", true))
46        .with_paragraph(Paragraph::with_text(
47            "Page 1 (this page) uses the first-page header, since \"different first page\" headers are set. \
48             Every other page uses the default header shown above, and every page uses the default footer.",
49        ))
50        .with_paragraph(heading("A third page, to see the default header again", true))
51        .with_paragraph(Paragraph::with_text(
52            "If Word is configured to show even/odd pages differently, this page alternates between the \
53             default and even-page header depending on whether it lands on an even or odd page number.",
54        ));
55
56    document.save_to_file(&path)?;
57    println!("Wrote {}", path.display());
58    Ok(())
59}
Source

pub fn with_gutter_twips(self, gutter: u32) -> PageSetup

Sets the binding-side gutter margin, in twips, and returns it for chaining.

Examples found in repository?
examples/docx_page_layout.rs (line 23)
15fn main() -> office_toolkit::Result<()> {
16    let path = output_path("docx_page_layout.docx");
17
18    let page_setup = PageSetup::new()
19        .with_size_twips(16_838, 11_906) // A4 landscape, in twentieths of a point
20        .with_orientation(Orientation::Landscape)
21        .with_margins_twips(1_440, 1_440, 1_800, 1_800) // top, bottom, left, right
22        .with_header_footer_margins_twips(720, 720)
23        .with_gutter_twips(0)
24        .with_columns(2);
25
26    let default_header =
27        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default header — every page"));
28    let default_footer =
29        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default footer — every page"));
30    let first_header = HeaderFooter::new()
31        .with_paragraph(Paragraph::with_text("First-page header — cover page only"));
32    let even_header = HeaderFooter::new().with_paragraph(Paragraph::with_text("Even-page header"));
33
34    let document = Document::new()
35        .with_page_setup(page_setup)
36        .with_header(default_header)
37        .with_footer(default_footer)
38        .with_header_first(first_header)
39        .with_header_even(even_header)
40        .with_paragraph(heading("Page setup: A4 landscape, custom margins, two columns", false))
41        .with_paragraph(Paragraph::with_text(
42            "This document is landscape A4, with wider left/right margins than top/bottom, and its body text \
43             flows in two columns. Look at the page in Word's Layout view to see the effect.",
44        ))
45        .with_paragraph(heading("Headers and footers", true))
46        .with_paragraph(Paragraph::with_text(
47            "Page 1 (this page) uses the first-page header, since \"different first page\" headers are set. \
48             Every other page uses the default header shown above, and every page uses the default footer.",
49        ))
50        .with_paragraph(heading("A third page, to see the default header again", true))
51        .with_paragraph(Paragraph::with_text(
52            "If Word is configured to show even/odd pages differently, this page alternates between the \
53             default and even-page header depending on whether it lands on an even or odd page number.",
54        ));
55
56    document.save_to_file(&path)?;
57    println!("Wrote {}", path.display());
58    Ok(())
59}
Source

pub fn with_columns(self, columns: u32) -> PageSetup

Sets the number of equal-width columns and returns it for chaining. See columns’s doc comment.

Examples found in repository?
examples/docx_page_layout.rs (line 24)
15fn main() -> office_toolkit::Result<()> {
16    let path = output_path("docx_page_layout.docx");
17
18    let page_setup = PageSetup::new()
19        .with_size_twips(16_838, 11_906) // A4 landscape, in twentieths of a point
20        .with_orientation(Orientation::Landscape)
21        .with_margins_twips(1_440, 1_440, 1_800, 1_800) // top, bottom, left, right
22        .with_header_footer_margins_twips(720, 720)
23        .with_gutter_twips(0)
24        .with_columns(2);
25
26    let default_header =
27        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default header — every page"));
28    let default_footer =
29        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default footer — every page"));
30    let first_header = HeaderFooter::new()
31        .with_paragraph(Paragraph::with_text("First-page header — cover page only"));
32    let even_header = HeaderFooter::new().with_paragraph(Paragraph::with_text("Even-page header"));
33
34    let document = Document::new()
35        .with_page_setup(page_setup)
36        .with_header(default_header)
37        .with_footer(default_footer)
38        .with_header_first(first_header)
39        .with_header_even(even_header)
40        .with_paragraph(heading("Page setup: A4 landscape, custom margins, two columns", false))
41        .with_paragraph(Paragraph::with_text(
42            "This document is landscape A4, with wider left/right margins than top/bottom, and its body text \
43             flows in two columns. Look at the page in Word's Layout view to see the effect.",
44        ))
45        .with_paragraph(heading("Headers and footers", true))
46        .with_paragraph(Paragraph::with_text(
47            "Page 1 (this page) uses the first-page header, since \"different first page\" headers are set. \
48             Every other page uses the default header shown above, and every page uses the default footer.",
49        ))
50        .with_paragraph(heading("A third page, to see the default header again", true))
51        .with_paragraph(Paragraph::with_text(
52            "If Word is configured to show even/odd pages differently, this page alternates between the \
53             default and even-page header depending on whether it lands on an even or odd page number.",
54        ));
55
56    document.save_to_file(&path)?;
57    println!("Wrote {}", path.display());
58    Ok(())
59}

Trait Implementations§

Source§

impl Clone for PageSetup

Source§

fn clone(&self) -> PageSetup

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Copy for PageSetup

Source§

impl Debug for PageSetup

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more
Source§

impl Default for PageSetup

Source§

fn default() -> PageSetup

A4 portrait with the standard margins this crate has always written (fixed since) — preserves old behavior exactly for a Document that doesn’t set page_setup explicitly.

Source§

impl Eq for PageSetup

Source§

impl PartialEq for PageSetup

Source§

fn eq(&self, other: &PageSetup) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl StructuralPartialEq for PageSetup

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

Source§

fn equivalent(&self, key: &K) -> bool

Checks if this value is equivalent to the given key. Read more
Source§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

Source§

fn equivalent(&self, key: &K) -> bool

Compare self to key and return true if they are equal.
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.