Struct Paragraph 

pub struct Paragraph {

    pub runs: Vec<Run>,
    pub alignment: Option<Alignment>,
    pub style_id: Option<String>,
    pub numbering_id: Option<u32>,
    pub numbering_level: u8,
    pub line_spacing: Option<u32>,
    pub space_before: Option<u32>,
    pub space_after: Option<u32>,
    pub shading_color: Option<String>,
    pub border: bool,
    pub keep_with_next: bool,
    pub keep_lines_together: bool,
    pub page_break_before: bool,
    pub tabs: Vec<TabStop>,
    pub contextual_spacing: bool,
}

A paragraph: a sequence of runs, plus paragraph-level formatting.

Fields

runs: Vec<Run>

The runs that make up this paragraph, in order.

alignment: Option<Alignment>

The paragraph’s horizontal alignment, or None to leave it unspecified (inherits from the paragraph style / Word’s default). Overrides the alignment of style_id’s style, if any.

style_id: Option<String>

The id of a paragraph-type Style to apply (w:pStyle), or None to use the document’s default paragraph style. The referenced style must actually be declared in Document.styles for the document to be well-formed — this is not validated when writing.

numbering_id: Option<u32>

The id of a NumberingDefinition to apply (w:numPr/w:numId), making this paragraph an item of that list, or None for a regular paragraph. The referenced definition must actually be declared in Document.numbering_definitions for the document to be well-formed — not validated when writing, same convention as style_id.

numbering_level: u8

Which indent level of numbering_id’s list this paragraph is at (w:numPr/w:ilvl, 0-indexed). Only meaningful when numbering_id is Some; must be within the range of levels the referenced NumberingDefinition actually declares — not validated when writing.

line_spacing: Option<u32>

This paragraph’s line spacing (w:spacing/@line, written together with w:spacing/@lineRule="auto"), or None to leave it unspecified. Unlike space_before/space_after (raw twips), this is in w:spacing’s “auto” units — 240ths of a single line, so 240 is single spacing, 360 is 1.5 lines, 480 is double — matching what Word’s own line-spacing dropdown offers. The twips-based atLeast/exact line-height modes (w:lineRule’s other two values, meant for exact point-based line heights rather than a multiple of the current font) aren’t modeled.

space_before: Option<u32>

Extra space before this paragraph, in twips (w:spacing/@before, ST_TwipsMeasure, twentieths of a point) — raw units, no conversion, matching Run.character_spacing’s precedent. None leaves it unspecified. w:spacing/@beforeAutospacing (letting Word compute it automatically instead) isn’t modeled.

space_after: Option<u32>

Extra space after this paragraph, in twips, mirroring space_before.

shading_color: Option<String>

This paragraph’s background shading color (w:shd/@fill), mirroring Run.shading_color — see that field’s doc comment for the same val/color fixed-pair convention.

border: bool

Whether this paragraph has a border around it (w:pBdr), mirroring Run.text_border — a simple on/off switch with the same fixed appearance (val="single" sz="4" space="0" color="auto"), applied to all four sides (top/left/bottom/right). CT_PBdr’s between (a rule drawn between paragraphs sharing this same border, when several consecutive paragraphs all have it) and bar (a vertical bar in the margin, used for revision-style paragraph marking) aren’t modeled, same scope-reduction posture as text_border not exposing all of CT_Border’s richness.

keep_with_next: bool

Whether this paragraph should stay on the same page as the one following it (w:keepNext, CT_OnOff) — Word moves both to the next page together rather than letting a page break fall between them. Commonly set on heading paragraphs, so a heading never ends up alone at the bottom of a page with its content starting on the next one.

keep_lines_together: bool

Whether every line of this paragraph must stay together on the same page (w:keepLines, CT_OnOff) — prevents the paragraph itself from being split across a page break partway through.

page_break_before: bool

Whether this paragraph always starts on a new page (w:pageBreakBefore, CT_OnOff) — a page break is forced immediately before it, regardless of how much room is left on the current page. Distinct from RunContent::Break(BreakKind::Page), which inserts an explicit page break wherever it appears within a run’s content, mid-paragraph; this is a paragraph-level property instead.

tabs: Vec<TabStop>

This paragraph’s custom tab stops (w:tabs, CT_Tabs), in order. Left empty (the default) to fall back entirely to Word’s own default tab stops (evenly spaced, typically every 720 twips/half inch) — setting even one custom stop here does not disable Word’s defaults beyond it, per ECMA-376.

contextual_spacing: bool

Whether to ignore the spacing above/below this paragraph when the paragraph immediately before/after it shares the same paragraph style (w:contextualSpacing, CT_OnOff) — commonly set on list item styles, so consecutive list items don’t get extra vertical gaps between them even if the style itself sets space_before/ space_after.

Implementations

impl Paragraph

pub fn new() -> Paragraph

Creates an empty paragraph.

Examples found in repository

examples/docx_page_layout.rs (line 62)

fn heading(text: &str, new_page: bool) -> Paragraph {
    Paragraph::new()
        .with_run(Run::new(text).with_bold(true).with_font_size(28))
        .with_page_break_before(new_page)
}

examples/docx_tables.rs (line 93)

fn heading(text: &str, new_page: bool) -> Paragraph {
    Paragraph::new()
        .with_run(Run::new(text).with_bold(true).with_font_size(28))
        .with_page_break_before(new_page)
}

examples/docx_images_and_charts.rs (line 30)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_images_and_charts.docx");
    let image_bytes = std::fs::read(image_fixture_path())?;

    // 2 inches wide, 1.5 inches tall (914,400 EMU per inch).
    let image = Image::new(image_bytes, ImageFormat::Png, 1_828_800, 1_371_600)
        .with_description("Project test image");
    let chart = EmbeddedChart::new(sample_chart_space(), 4_572_000, 2_743_200)
        .with_name("Quarterly revenue");

    let document = Document::new()
        .with_paragraph(heading("An inline image", false))
        .with_paragraph(Paragraph::new().with_run(Run::with_image(image)))
        .with_paragraph(heading("An embedded bar chart", true))
        .with_paragraph(Paragraph::new().with_run(Run::with_chart(chart)));

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

/// A minimal bar chart with literal (not cell-referenced) data — enough to
/// demonstrate embedding, without needing a companion spreadsheet.
fn sample_chart_space() -> ChartSpace {
    let categories = StringData::new()
        .with_point(StringPoint::new(0, "Q1"))
        .with_point(StringPoint::new(1, "Q2"))
        .with_point(StringPoint::new(2, "Q3"));
    let values = NumericData::new()
        .with_point(NumericPoint::new(0, "1200"))
        .with_point(NumericPoint::new(1, "1350"))
        .with_point(NumericPoint::new(2, "980"));

    let series = BarSeries::new(0, 0)
        .with_categories(AxisDataSource::String(StringDataSource::literal(
            categories,
        )))
        .with_values(NumericDataSource::literal(values));

    let bar_chart = BarChart::new(BarDirection::Column, 1, 2).with_series(series);
    let category_axis = CategoryAxis::new(1, AxisPosition::Bottom, 2);
    let value_axis = ValueAxis::new(2, AxisPosition::Left, 1);

    let plot_area = PlotArea::new()
        .with_chart(ChartType::Bar(bar_chart))
        .with_axis(Axis::Category(category_axis))
        .with_axis(Axis::Value(value_axis));

    ChartSpace::new(Chart::new(plot_area))
}

fn heading(text: &str, new_page: bool) -> Paragraph {
    Paragraph::new()
        .with_run(Run::new(text).with_bold(true).with_font_size(28))
        .with_page_break_before(new_page)
}

examples/docx_styles_and_lists.rs (line 45)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_styles_and_lists.docx");

    let heading_style = Style::new("Heading1", "Heading 1", StyleKind::Paragraph)
        .with_bold(true)
        .with_font_size(32);
    let emphasis_style = Style::new("StrongEmphasis", "Strong Emphasis", StyleKind::Character)
        .with_bold(true)
        .with_color("C00000");

    let bulleted = NumberingDefinition::bullet(1);
    let numbered = NumberingDefinition::decimal(2);
    let custom = NumberingDefinition::new(
        3,
        vec![
            ListLevel::new(NumberFormat::UpperRoman, "%1.", 720, 360),
            ListLevel::new(NumberFormat::LowerLetter, "%2)", 1440, 360),
        ],
    );

    let document = Document::new()
        .with_style(heading_style)
        .with_style(emphasis_style)
        .with_numbering_definition(bulleted)
        .with_numbering_definition(numbered)
        .with_numbering_definition(custom)
        .with_paragraph(heading("Named paragraph and character styles", false))
        .with_paragraph(
            Paragraph::with_text("This paragraph uses the Heading 1 style.")
                .with_style_id("Heading1"),
        )
        .with_paragraph(
            Paragraph::new()
                .with_run(Run::new("Plain text, then "))
                .with_run(Run::new("some strongly emphasized text").with_style_id("StrongEmphasis"))
                .with_run(Run::new(", then plain text again.")),
        )
        .with_paragraph(heading("Bulleted list", true))
        .with_paragraph(Paragraph::with_text("First item").with_numbering(1, 0))
        .with_paragraph(Paragraph::with_text("Second item").with_numbering(1, 0))
        .with_paragraph(Paragraph::with_text("A sub-item, one level deeper").with_numbering(1, 1))
        .with_paragraph(heading("Numbered list", true))
        .with_paragraph(Paragraph::with_text("First step").with_numbering(2, 0))
        .with_paragraph(Paragraph::with_text("Second step").with_numbering(2, 0))
        .with_paragraph(
            Paragraph::with_text("A sub-step, cumulatively numbered").with_numbering(2, 1),
        )
        .with_paragraph(heading(
            "Custom multi-level list (roman numerals, then letters)",
            true,
        ))
        .with_paragraph(Paragraph::with_text("First top-level item").with_numbering(3, 0))
        .with_paragraph(Paragraph::with_text("A lettered sub-item").with_numbering(3, 1))
        .with_paragraph(Paragraph::with_text("Second top-level item").with_numbering(3, 0));

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

fn heading(text: &str, new_page: bool) -> Paragraph {
    Paragraph::new()
        .with_run(Run::new(text).with_bold(true).with_font_size(28))
        .with_page_break_before(new_page)
}

examples/docx_navigation_and_annotations.rs (line 25)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_navigation_and_annotations.docx");

    let document =
        Document::new()
            .with_paragraph(heading(
                "Hyperlinks: external, and internal to a bookmark",
                false,
            ))
            .with_paragraph(
                Paragraph::new()
                    .with_run(Run::new("Visit the ").with_hyperlink(Hyperlink::External(
                        "https://www.rust-lang.org".to_string(),
                    )))
                    .with_run(Run::new("or jump ").with_hyperlink(Hyperlink::External(
                        "https://www.rust-lang.org".to_string(),
                    )))
                    .with_run(
                        Run::new("down to the bookmark")
                            .with_hyperlink(Hyperlink::Internal("Target".to_string())),
                    ),
            )
            .with_paragraph(
                Paragraph::new()
                    .with_run(Run::new("Here is ").with_bookmark(Bookmark::new(0, "Target")))
                    .with_run(
                        Run::new("the bookmarked text.").with_bookmark(Bookmark::new(0, "Target")),
                    ),
            )
            .with_paragraph(heading("Comments", true))
            .with_paragraph(
                Paragraph::new()
                    .with_run(Run::new("This sentence "))
                    .with_run(Run::new("needs a second look").with_comment(0))
                    .with_run(Run::new(" before it ships.")),
            )
            .with_comment(
                Comment::with_text(0, "Please double-check this claim.")
                    .with_author("Reviewer")
                    .with_initials("RV"),
            )
            .with_paragraph(heading("Footnotes and endnotes", true))
            .with_paragraph(
                Paragraph::with_text("A claim that needs a footnote")
                    .with_run(Run::with_note_reference(NoteReference::Footnote(1)))
                    .with_run(Run::new(", and another that needs an endnote"))
                    .with_run(Run::with_note_reference(NoteReference::Endnote(1))),
            )
            .with_footnote(Note::footnote_with_text(
                1,
                "The footnote's own explanatory text.",
            ))
            .with_endnote(Note::endnote_with_text(
                1,
                "The endnote's own explanatory text.",
            ))
            .with_paragraph(heading("A structured document tag (content control)", true))
            .with_paragraph(Paragraph::with_text("Before the content control:"))
            .with_structured_document_tag(
                StructuredDocumentTag::new()
                    .with_id(42)
                    .with_tag("CustomerName")
                    .with_alias("Customer name")
                    .with_paragraph(Paragraph::with_text("Acme Corp.")),
            );

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

fn heading(text: &str, new_page: bool) -> Paragraph {
    Paragraph::new()
        .with_run(Run::new(text).with_bold(true).with_font_size(28))
        .with_page_break_before(new_page)
}

examples/docx_text_formatting.rs (line 21)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_text_formatting.docx");

    let document = Document::new()
        .with_paragraph(heading("Docx text formatting — bold, italic, underline, strike", false))
        .with_paragraph(Paragraph::new().with_run(Run::new("Bold text.").with_bold(true)))
        .with_paragraph(Paragraph::new().with_run(Run::new("Italic text.").with_italic(true)))
        .with_paragraph(Paragraph::new().with_run(Run::new("Single underline.").with_underline(UnderlineStyle::Single)))
        .with_paragraph(Paragraph::new().with_run(Run::new("Wavy underline.").with_underline(UnderlineStyle::Wave)))
        .with_paragraph(Paragraph::new().with_run(Run::new("Strikethrough text.").with_strike(true)))
        .with_paragraph(heading("Colors and highlight", true))
        .with_paragraph(Paragraph::new().with_run(Run::new("Red text on the default background.").with_color("FF0000")))
        .with_paragraph(Paragraph::new().with_run(Run::new("Text highlighted in yellow.").with_highlight(Highlight::Yellow)))
        .with_paragraph(
            Paragraph::new()
                .with_run(Run::new("Larger, custom font.").with_font_size(32).with_font_family("Georgia")),
        )
        .with_paragraph(heading("Superscript and subscript", true))
        .with_paragraph(
            Paragraph::new()
                .with_run(Run::new("Water is H"))
                .with_run(Run::new("2").with_vertical_align(VerticalAlign::Subscript))
                .with_run(Run::new("O.")),
        )
        .with_paragraph(
            Paragraph::new()
                .with_run(Run::new("Squared: x"))
                .with_run(Run::new("2").with_vertical_align(VerticalAlign::Superscript))
                .with_run(Run::new(".")),
        )
        .with_paragraph(heading("Small caps, all caps, character spacing", true))
        .with_paragraph(Paragraph::new().with_run(Run::new("rendered in small caps").with_small_caps(true)))
        .with_paragraph(Paragraph::new().with_run(Run::new("rendered in all caps").with_all_caps(true)))
        .with_paragraph(Paragraph::new().with_run(Run::new("Widely spaced letters.").with_character_spacing(120)))
        .with_paragraph(heading("Paragraph alignment", true))
        .with_paragraph(Paragraph::with_text("Left-aligned (the default).").with_alignment(Alignment::Left))
        .with_paragraph(Paragraph::with_text("Centered.").with_alignment(Alignment::Center))
        .with_paragraph(Paragraph::with_text("Right-aligned.").with_alignment(Alignment::Right))
        .with_paragraph(
            Paragraph::with_text(
                "Justified: this line is long enough for Word to stretch the spacing between words so both edges line up.",
            )
            .with_alignment(Alignment::Justify),
        )
        .with_paragraph(heading("Tab stops", true))
        .with_paragraph(
            Paragraph::new()
                .with_tab(TabStop::new(1_440).with_alignment(TabStopAlignment::Center))
                .with_tab(TabStop::new(2_880).with_alignment(TabStopAlignment::Right).with_leader(TabLeader::Dot))
                .with_run(Run::new("Left\tCentered\tRight, dot leader")),
        );

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

/// A bold section heading, optionally starting a new page — used to give
/// each feature group its own page in the rendered document.
fn heading(text: &str, new_page: bool) -> Paragraph {
    Paragraph::new()
        .with_run(Run::new(text).with_bold(true).with_font_size(28))
        .with_page_break_before(new_page)
}

pub fn with_text(text: impl Into<String>) -> Paragraph

Creates a paragraph containing a single run with the given text.

Examples found in repository

examples/hello_world_docx.rs (line 16)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("hello_world.docx");

    // `Document` and `Paragraph` both come from `office_toolkit::prelude`.
    let document = Document::new().with_paragraph(Paragraph::with_text("Hello, world!"));
    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());

    // Read the file back to confirm it is a valid .docx.
    let reopened = Document::open_file(&path)?;
    let text = reopened
        .paragraphs()
        .next()
        .map(|paragraph| paragraph.text());
    println!("Read back: {text:?}");

    Ok(())
}

examples/docx_theme.rs (line 17)

fn main() -> office_toolkit::Result<()> {
    let default_theme_document = Document::new()
        .with_theme(Theme::office_default())
        .with_paragraph(Paragraph::with_text("Office's built-in default theme."))
        .with_paragraph(Paragraph::with_text(
            "Cambria for headings, Calibri for body text, the classic Office palette.",
        ));
    let default_path = output_path("docx_theme_default.docx");
    default_theme_document.save_to_file(&default_path)?;
    println!("Wrote {}", default_path.display());

    // A custom, branded theme: a dark navy/orange palette and a different
    // heading/body font pairing.
    let custom_colors = ColorScheme::new(
        "1B1B1B", "FFFFFF", "0A2540", "F5F5F5", "0A2540", "E8622C", "2E86AB", "6FB98F", "F4A259",
        "8E4585", "1155CC", "6B3FA0",
    );
    let custom_fonts = FontScheme::new("Georgia", "Verdana");
    let custom_theme_document = Document::new()
        .with_theme(Theme::new("Custom Brand", custom_colors, custom_fonts))
        .with_paragraph(Paragraph::with_text("A custom, branded theme."))
        .with_paragraph(Paragraph::with_text(
            "Georgia for headings, Verdana for body text, a navy/orange palette.",
        ));
    let custom_path = output_path("docx_theme_custom.docx");
    custom_theme_document.save_to_file(&custom_path)?;
    println!("Wrote {}", custom_path.display());

    Ok(())
}

examples/docx_metadata_and_protection.rs (lines 37-40)

fn main() -> office_toolkit::Result<()> {
    let properties = DocumentProperties::new()
        .with_title("Quarterly Report")
        .with_subject("Q3 results")
        .with_creator("Jane Doe")
        .with_keywords("finance, quarterly, report")
        .with_description("An example document showing document properties.")
        .with_category("Finance")
        .with_content_status("Draft");
    let extended_properties = ExtendedProperties::new()
        .with_company("Acme Corp.")
        .with_manager("Jane Manager");

    let metadata_document = Document::new()
        .with_properties(properties)
        .with_extended_properties(extended_properties)
        .with_custom_property("ProjectCode", CustomPropertyValue::Text("Q3-2026".to_string()))
        .with_custom_property("Budget", CustomPropertyValue::Number(125_000.0))
        .with_custom_property("Approved", CustomPropertyValue::Bool(false))
        .with_custom_property("RevisionCount", CustomPropertyValue::Int(3))
        .with_track_changes(true)
        .with_paragraph(Paragraph::with_text(
            "This document carries standard properties (title/author/subject/...), four custom properties, \
             and has track changes turned on — check File > Info in Word to see them.",
        ));
    let metadata_path = output_path("docx_metadata.docx");
    metadata_document.save_to_file(&metadata_path)?;
    println!("Wrote {}", metadata_path.display());

    let protected_document = Document::new()
        .with_protection(ProtectionKind::ReadOnly)
        .with_paragraph(Paragraph::with_text(
            "This document is protected as read-only — Word will ask for a password before allowing edits.",
        ));
    let protected_path = output_path("docx_protected.docx");
    protected_document.save_to_file(&protected_path)?;
    println!("Wrote {}", protected_path.display());

    Ok(())
}

examples/docx_page_layout.rs (line 27)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_page_layout.docx");

    let page_setup = PageSetup::new()
        .with_size_twips(16_838, 11_906) // A4 landscape, in twentieths of a point
        .with_orientation(Orientation::Landscape)
        .with_margins_twips(1_440, 1_440, 1_800, 1_800) // top, bottom, left, right
        .with_header_footer_margins_twips(720, 720)
        .with_gutter_twips(0)
        .with_columns(2);

    let default_header =
        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default header — every page"));
    let default_footer =
        HeaderFooter::new().with_paragraph(Paragraph::with_text("Default footer — every page"));
    let first_header = HeaderFooter::new()
        .with_paragraph(Paragraph::with_text("First-page header — cover page only"));
    let even_header = HeaderFooter::new().with_paragraph(Paragraph::with_text("Even-page header"));

    let document = Document::new()
        .with_page_setup(page_setup)
        .with_header(default_header)
        .with_footer(default_footer)
        .with_header_first(first_header)
        .with_header_even(even_header)
        .with_paragraph(heading("Page setup: A4 landscape, custom margins, two columns", false))
        .with_paragraph(Paragraph::with_text(
            "This document is landscape A4, with wider left/right margins than top/bottom, and its body text \
             flows in two columns. Look at the page in Word's Layout view to see the effect.",
        ))
        .with_paragraph(heading("Headers and footers", true))
        .with_paragraph(Paragraph::with_text(
            "Page 1 (this page) uses the first-page header, since \"different first page\" headers are set. \
             Every other page uses the default header shown above, and every page uses the default footer.",
        ))
        .with_paragraph(heading("A third page, to see the default header again", true))
        .with_paragraph(Paragraph::with_text(
            "If Word is configured to show even/odd pages differently, this page alternates between the \
             default and even-page header depending on whether it lands on an even or odd page number.",
        ));

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

examples/docx_styles_and_lists.rs (line 41)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_styles_and_lists.docx");

    let heading_style = Style::new("Heading1", "Heading 1", StyleKind::Paragraph)
        .with_bold(true)
        .with_font_size(32);
    let emphasis_style = Style::new("StrongEmphasis", "Strong Emphasis", StyleKind::Character)
        .with_bold(true)
        .with_color("C00000");

    let bulleted = NumberingDefinition::bullet(1);
    let numbered = NumberingDefinition::decimal(2);
    let custom = NumberingDefinition::new(
        3,
        vec![
            ListLevel::new(NumberFormat::UpperRoman, "%1.", 720, 360),
            ListLevel::new(NumberFormat::LowerLetter, "%2)", 1440, 360),
        ],
    );

    let document = Document::new()
        .with_style(heading_style)
        .with_style(emphasis_style)
        .with_numbering_definition(bulleted)
        .with_numbering_definition(numbered)
        .with_numbering_definition(custom)
        .with_paragraph(heading("Named paragraph and character styles", false))
        .with_paragraph(
            Paragraph::with_text("This paragraph uses the Heading 1 style.")
                .with_style_id("Heading1"),
        )
        .with_paragraph(
            Paragraph::new()
                .with_run(Run::new("Plain text, then "))
                .with_run(Run::new("some strongly emphasized text").with_style_id("StrongEmphasis"))
                .with_run(Run::new(", then plain text again.")),
        )
        .with_paragraph(heading("Bulleted list", true))
        .with_paragraph(Paragraph::with_text("First item").with_numbering(1, 0))
        .with_paragraph(Paragraph::with_text("Second item").with_numbering(1, 0))
        .with_paragraph(Paragraph::with_text("A sub-item, one level deeper").with_numbering(1, 1))
        .with_paragraph(heading("Numbered list", true))
        .with_paragraph(Paragraph::with_text("First step").with_numbering(2, 0))
        .with_paragraph(Paragraph::with_text("Second step").with_numbering(2, 0))
        .with_paragraph(
            Paragraph::with_text("A sub-step, cumulatively numbered").with_numbering(2, 1),
        )
        .with_paragraph(heading(
            "Custom multi-level list (roman numerals, then letters)",
            true,
        ))
        .with_paragraph(Paragraph::with_text("First top-level item").with_numbering(3, 0))
        .with_paragraph(Paragraph::with_text("A lettered sub-item").with_numbering(3, 1))
        .with_paragraph(Paragraph::with_text("Second top-level item").with_numbering(3, 0));

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

examples/docx_navigation_and_annotations.rs (line 58)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_navigation_and_annotations.docx");

    let document =
        Document::new()
            .with_paragraph(heading(
                "Hyperlinks: external, and internal to a bookmark",
                false,
            ))
            .with_paragraph(
                Paragraph::new()
                    .with_run(Run::new("Visit the ").with_hyperlink(Hyperlink::External(
                        "https://www.rust-lang.org".to_string(),
                    )))
                    .with_run(Run::new("or jump ").with_hyperlink(Hyperlink::External(
                        "https://www.rust-lang.org".to_string(),
                    )))
                    .with_run(
                        Run::new("down to the bookmark")
                            .with_hyperlink(Hyperlink::Internal("Target".to_string())),
                    ),
            )
            .with_paragraph(
                Paragraph::new()
                    .with_run(Run::new("Here is ").with_bookmark(Bookmark::new(0, "Target")))
                    .with_run(
                        Run::new("the bookmarked text.").with_bookmark(Bookmark::new(0, "Target")),
                    ),
            )
            .with_paragraph(heading("Comments", true))
            .with_paragraph(
                Paragraph::new()
                    .with_run(Run::new("This sentence "))
                    .with_run(Run::new("needs a second look").with_comment(0))
                    .with_run(Run::new(" before it ships.")),
            )
            .with_comment(
                Comment::with_text(0, "Please double-check this claim.")
                    .with_author("Reviewer")
                    .with_initials("RV"),
            )
            .with_paragraph(heading("Footnotes and endnotes", true))
            .with_paragraph(
                Paragraph::with_text("A claim that needs a footnote")
                    .with_run(Run::with_note_reference(NoteReference::Footnote(1)))
                    .with_run(Run::new(", and another that needs an endnote"))
                    .with_run(Run::with_note_reference(NoteReference::Endnote(1))),
            )
            .with_footnote(Note::footnote_with_text(
                1,
                "The footnote's own explanatory text.",
            ))
            .with_endnote(Note::endnote_with_text(
                1,
                "The endnote's own explanatory text.",
            ))
            .with_paragraph(heading("A structured document tag (content control)", true))
            .with_paragraph(Paragraph::with_text("Before the content control:"))
            .with_structured_document_tag(
                StructuredDocumentTag::new()
                    .with_id(42)
                    .with_tag("CustomerName")
                    .with_alias("Customer name")
                    .with_paragraph(Paragraph::with_text("Acme Corp.")),
            );

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

Additional examples can be found in:

• examples/docx_text_formatting.rs

pub fn with_run(self, run: Run) -> Paragraph

Appends a run and returns the paragraph for chaining.

Examples found in repository

examples/docx_page_layout.rs (line 63)

fn heading(text: &str, new_page: bool) -> Paragraph {
    Paragraph::new()
        .with_run(Run::new(text).with_bold(true).with_font_size(28))
        .with_page_break_before(new_page)
}

examples/docx_tables.rs (line 94)

fn heading(text: &str, new_page: bool) -> Paragraph {
    Paragraph::new()
        .with_run(Run::new(text).with_bold(true).with_font_size(28))
        .with_page_break_before(new_page)
}

examples/docx_images_and_charts.rs (line 30)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_images_and_charts.docx");
    let image_bytes = std::fs::read(image_fixture_path())?;

    // 2 inches wide, 1.5 inches tall (914,400 EMU per inch).
    let image = Image::new(image_bytes, ImageFormat::Png, 1_828_800, 1_371_600)
        .with_description("Project test image");
    let chart = EmbeddedChart::new(sample_chart_space(), 4_572_000, 2_743_200)
        .with_name("Quarterly revenue");

    let document = Document::new()
        .with_paragraph(heading("An inline image", false))
        .with_paragraph(Paragraph::new().with_run(Run::with_image(image)))
        .with_paragraph(heading("An embedded bar chart", true))
        .with_paragraph(Paragraph::new().with_run(Run::with_chart(chart)));

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

/// A minimal bar chart with literal (not cell-referenced) data — enough to
/// demonstrate embedding, without needing a companion spreadsheet.
fn sample_chart_space() -> ChartSpace {
    let categories = StringData::new()
        .with_point(StringPoint::new(0, "Q1"))
        .with_point(StringPoint::new(1, "Q2"))
        .with_point(StringPoint::new(2, "Q3"));
    let values = NumericData::new()
        .with_point(NumericPoint::new(0, "1200"))
        .with_point(NumericPoint::new(1, "1350"))
        .with_point(NumericPoint::new(2, "980"));

    let series = BarSeries::new(0, 0)
        .with_categories(AxisDataSource::String(StringDataSource::literal(
            categories,
        )))
        .with_values(NumericDataSource::literal(values));

    let bar_chart = BarChart::new(BarDirection::Column, 1, 2).with_series(series);
    let category_axis = CategoryAxis::new(1, AxisPosition::Bottom, 2);
    let value_axis = ValueAxis::new(2, AxisPosition::Left, 1);

    let plot_area = PlotArea::new()
        .with_chart(ChartType::Bar(bar_chart))
        .with_axis(Axis::Category(category_axis))
        .with_axis(Axis::Value(value_axis));

    ChartSpace::new(Chart::new(plot_area))
}

fn heading(text: &str, new_page: bool) -> Paragraph {
    Paragraph::new()
        .with_run(Run::new(text).with_bold(true).with_font_size(28))
        .with_page_break_before(new_page)
}

examples/docx_styles_and_lists.rs (line 46)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_styles_and_lists.docx");

    let heading_style = Style::new("Heading1", "Heading 1", StyleKind::Paragraph)
        .with_bold(true)
        .with_font_size(32);
    let emphasis_style = Style::new("StrongEmphasis", "Strong Emphasis", StyleKind::Character)
        .with_bold(true)
        .with_color("C00000");

    let bulleted = NumberingDefinition::bullet(1);
    let numbered = NumberingDefinition::decimal(2);
    let custom = NumberingDefinition::new(
        3,
        vec![
            ListLevel::new(NumberFormat::UpperRoman, "%1.", 720, 360),
            ListLevel::new(NumberFormat::LowerLetter, "%2)", 1440, 360),
        ],
    );

    let document = Document::new()
        .with_style(heading_style)
        .with_style(emphasis_style)
        .with_numbering_definition(bulleted)
        .with_numbering_definition(numbered)
        .with_numbering_definition(custom)
        .with_paragraph(heading("Named paragraph and character styles", false))
        .with_paragraph(
            Paragraph::with_text("This paragraph uses the Heading 1 style.")
                .with_style_id("Heading1"),
        )
        .with_paragraph(
            Paragraph::new()
                .with_run(Run::new("Plain text, then "))
                .with_run(Run::new("some strongly emphasized text").with_style_id("StrongEmphasis"))
                .with_run(Run::new(", then plain text again.")),
        )
        .with_paragraph(heading("Bulleted list", true))
        .with_paragraph(Paragraph::with_text("First item").with_numbering(1, 0))
        .with_paragraph(Paragraph::with_text("Second item").with_numbering(1, 0))
        .with_paragraph(Paragraph::with_text("A sub-item, one level deeper").with_numbering(1, 1))
        .with_paragraph(heading("Numbered list", true))
        .with_paragraph(Paragraph::with_text("First step").with_numbering(2, 0))
        .with_paragraph(Paragraph::with_text("Second step").with_numbering(2, 0))
        .with_paragraph(
            Paragraph::with_text("A sub-step, cumulatively numbered").with_numbering(2, 1),
        )
        .with_paragraph(heading(
            "Custom multi-level list (roman numerals, then letters)",
            true,
        ))
        .with_paragraph(Paragraph::with_text("First top-level item").with_numbering(3, 0))
        .with_paragraph(Paragraph::with_text("A lettered sub-item").with_numbering(3, 1))
        .with_paragraph(Paragraph::with_text("Second top-level item").with_numbering(3, 0));

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

fn heading(text: &str, new_page: bool) -> Paragraph {
    Paragraph::new()
        .with_run(Run::new(text).with_bold(true).with_font_size(28))
        .with_page_break_before(new_page)
}

examples/docx_navigation_and_annotations.rs (lines 26-28)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_navigation_and_annotations.docx");

    let document =
        Document::new()
            .with_paragraph(heading(
                "Hyperlinks: external, and internal to a bookmark",
                false,
            ))
            .with_paragraph(
                Paragraph::new()
                    .with_run(Run::new("Visit the ").with_hyperlink(Hyperlink::External(
                        "https://www.rust-lang.org".to_string(),
                    )))
                    .with_run(Run::new("or jump ").with_hyperlink(Hyperlink::External(
                        "https://www.rust-lang.org".to_string(),
                    )))
                    .with_run(
                        Run::new("down to the bookmark")
                            .with_hyperlink(Hyperlink::Internal("Target".to_string())),
                    ),
            )
            .with_paragraph(
                Paragraph::new()
                    .with_run(Run::new("Here is ").with_bookmark(Bookmark::new(0, "Target")))
                    .with_run(
                        Run::new("the bookmarked text.").with_bookmark(Bookmark::new(0, "Target")),
                    ),
            )
            .with_paragraph(heading("Comments", true))
            .with_paragraph(
                Paragraph::new()
                    .with_run(Run::new("This sentence "))
                    .with_run(Run::new("needs a second look").with_comment(0))
                    .with_run(Run::new(" before it ships.")),
            )
            .with_comment(
                Comment::with_text(0, "Please double-check this claim.")
                    .with_author("Reviewer")
                    .with_initials("RV"),
            )
            .with_paragraph(heading("Footnotes and endnotes", true))
            .with_paragraph(
                Paragraph::with_text("A claim that needs a footnote")
                    .with_run(Run::with_note_reference(NoteReference::Footnote(1)))
                    .with_run(Run::new(", and another that needs an endnote"))
                    .with_run(Run::with_note_reference(NoteReference::Endnote(1))),
            )
            .with_footnote(Note::footnote_with_text(
                1,
                "The footnote's own explanatory text.",
            ))
            .with_endnote(Note::endnote_with_text(
                1,
                "The endnote's own explanatory text.",
            ))
            .with_paragraph(heading("A structured document tag (content control)", true))
            .with_paragraph(Paragraph::with_text("Before the content control:"))
            .with_structured_document_tag(
                StructuredDocumentTag::new()
                    .with_id(42)
                    .with_tag("CustomerName")
                    .with_alias("Customer name")
                    .with_paragraph(Paragraph::with_text("Acme Corp.")),
            );

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

fn heading(text: &str, new_page: bool) -> Paragraph {
    Paragraph::new()
        .with_run(Run::new(text).with_bold(true).with_font_size(28))
        .with_page_break_before(new_page)
}

examples/docx_text_formatting.rs (line 21)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_text_formatting.docx");

    let document = Document::new()
        .with_paragraph(heading("Docx text formatting — bold, italic, underline, strike", false))
        .with_paragraph(Paragraph::new().with_run(Run::new("Bold text.").with_bold(true)))
        .with_paragraph(Paragraph::new().with_run(Run::new("Italic text.").with_italic(true)))
        .with_paragraph(Paragraph::new().with_run(Run::new("Single underline.").with_underline(UnderlineStyle::Single)))
        .with_paragraph(Paragraph::new().with_run(Run::new("Wavy underline.").with_underline(UnderlineStyle::Wave)))
        .with_paragraph(Paragraph::new().with_run(Run::new("Strikethrough text.").with_strike(true)))
        .with_paragraph(heading("Colors and highlight", true))
        .with_paragraph(Paragraph::new().with_run(Run::new("Red text on the default background.").with_color("FF0000")))
        .with_paragraph(Paragraph::new().with_run(Run::new("Text highlighted in yellow.").with_highlight(Highlight::Yellow)))
        .with_paragraph(
            Paragraph::new()
                .with_run(Run::new("Larger, custom font.").with_font_size(32).with_font_family("Georgia")),
        )
        .with_paragraph(heading("Superscript and subscript", true))
        .with_paragraph(
            Paragraph::new()
                .with_run(Run::new("Water is H"))
                .with_run(Run::new("2").with_vertical_align(VerticalAlign::Subscript))
                .with_run(Run::new("O.")),
        )
        .with_paragraph(
            Paragraph::new()
                .with_run(Run::new("Squared: x"))
                .with_run(Run::new("2").with_vertical_align(VerticalAlign::Superscript))
                .with_run(Run::new(".")),
        )
        .with_paragraph(heading("Small caps, all caps, character spacing", true))
        .with_paragraph(Paragraph::new().with_run(Run::new("rendered in small caps").with_small_caps(true)))
        .with_paragraph(Paragraph::new().with_run(Run::new("rendered in all caps").with_all_caps(true)))
        .with_paragraph(Paragraph::new().with_run(Run::new("Widely spaced letters.").with_character_spacing(120)))
        .with_paragraph(heading("Paragraph alignment", true))
        .with_paragraph(Paragraph::with_text("Left-aligned (the default).").with_alignment(Alignment::Left))
        .with_paragraph(Paragraph::with_text("Centered.").with_alignment(Alignment::Center))
        .with_paragraph(Paragraph::with_text("Right-aligned.").with_alignment(Alignment::Right))
        .with_paragraph(
            Paragraph::with_text(
                "Justified: this line is long enough for Word to stretch the spacing between words so both edges line up.",
            )
            .with_alignment(Alignment::Justify),
        )
        .with_paragraph(heading("Tab stops", true))
        .with_paragraph(
            Paragraph::new()
                .with_tab(TabStop::new(1_440).with_alignment(TabStopAlignment::Center))
                .with_tab(TabStop::new(2_880).with_alignment(TabStopAlignment::Right).with_leader(TabLeader::Dot))
                .with_run(Run::new("Left\tCentered\tRight, dot leader")),
        );

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

/// A bold section heading, optionally starting a new page — used to give
/// each feature group its own page in the rendered document.
fn heading(text: &str, new_page: bool) -> Paragraph {
    Paragraph::new()
        .with_run(Run::new(text).with_bold(true).with_font_size(28))
        .with_page_break_before(new_page)
}

pub fn with_alignment(self, alignment: Alignment) -> Paragraph

Sets the paragraph’s alignment and returns it for chaining.

Examples found in repository

examples/docx_text_formatting.rs (line 51)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_text_formatting.docx");

    let document = Document::new()
        .with_paragraph(heading("Docx text formatting — bold, italic, underline, strike", false))
        .with_paragraph(Paragraph::new().with_run(Run::new("Bold text.").with_bold(true)))
        .with_paragraph(Paragraph::new().with_run(Run::new("Italic text.").with_italic(true)))
        .with_paragraph(Paragraph::new().with_run(Run::new("Single underline.").with_underline(UnderlineStyle::Single)))
        .with_paragraph(Paragraph::new().with_run(Run::new("Wavy underline.").with_underline(UnderlineStyle::Wave)))
        .with_paragraph(Paragraph::new().with_run(Run::new("Strikethrough text.").with_strike(true)))
        .with_paragraph(heading("Colors and highlight", true))
        .with_paragraph(Paragraph::new().with_run(Run::new("Red text on the default background.").with_color("FF0000")))
        .with_paragraph(Paragraph::new().with_run(Run::new("Text highlighted in yellow.").with_highlight(Highlight::Yellow)))
        .with_paragraph(
            Paragraph::new()
                .with_run(Run::new("Larger, custom font.").with_font_size(32).with_font_family("Georgia")),
        )
        .with_paragraph(heading("Superscript and subscript", true))
        .with_paragraph(
            Paragraph::new()
                .with_run(Run::new("Water is H"))
                .with_run(Run::new("2").with_vertical_align(VerticalAlign::Subscript))
                .with_run(Run::new("O.")),
        )
        .with_paragraph(
            Paragraph::new()
                .with_run(Run::new("Squared: x"))
                .with_run(Run::new("2").with_vertical_align(VerticalAlign::Superscript))
                .with_run(Run::new(".")),
        )
        .with_paragraph(heading("Small caps, all caps, character spacing", true))
        .with_paragraph(Paragraph::new().with_run(Run::new("rendered in small caps").with_small_caps(true)))
        .with_paragraph(Paragraph::new().with_run(Run::new("rendered in all caps").with_all_caps(true)))
        .with_paragraph(Paragraph::new().with_run(Run::new("Widely spaced letters.").with_character_spacing(120)))
        .with_paragraph(heading("Paragraph alignment", true))
        .with_paragraph(Paragraph::with_text("Left-aligned (the default).").with_alignment(Alignment::Left))
        .with_paragraph(Paragraph::with_text("Centered.").with_alignment(Alignment::Center))
        .with_paragraph(Paragraph::with_text("Right-aligned.").with_alignment(Alignment::Right))
        .with_paragraph(
            Paragraph::with_text(
                "Justified: this line is long enough for Word to stretch the spacing between words so both edges line up.",
            )
            .with_alignment(Alignment::Justify),
        )
        .with_paragraph(heading("Tab stops", true))
        .with_paragraph(
            Paragraph::new()
                .with_tab(TabStop::new(1_440).with_alignment(TabStopAlignment::Center))
                .with_tab(TabStop::new(2_880).with_alignment(TabStopAlignment::Right).with_leader(TabLeader::Dot))
                .with_run(Run::new("Left\tCentered\tRight, dot leader")),
        );

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

pub fn with_style_id(self, style_id: impl Into<String>) -> Paragraph

Sets the paragraph style to apply (by id) and returns it for chaining.

Examples found in repository

examples/docx_styles_and_lists.rs (line 42)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_styles_and_lists.docx");

    let heading_style = Style::new("Heading1", "Heading 1", StyleKind::Paragraph)
        .with_bold(true)
        .with_font_size(32);
    let emphasis_style = Style::new("StrongEmphasis", "Strong Emphasis", StyleKind::Character)
        .with_bold(true)
        .with_color("C00000");

    let bulleted = NumberingDefinition::bullet(1);
    let numbered = NumberingDefinition::decimal(2);
    let custom = NumberingDefinition::new(
        3,
        vec![
            ListLevel::new(NumberFormat::UpperRoman, "%1.", 720, 360),
            ListLevel::new(NumberFormat::LowerLetter, "%2)", 1440, 360),
        ],
    );

    let document = Document::new()
        .with_style(heading_style)
        .with_style(emphasis_style)
        .with_numbering_definition(bulleted)
        .with_numbering_definition(numbered)
        .with_numbering_definition(custom)
        .with_paragraph(heading("Named paragraph and character styles", false))
        .with_paragraph(
            Paragraph::with_text("This paragraph uses the Heading 1 style.")
                .with_style_id("Heading1"),
        )
        .with_paragraph(
            Paragraph::new()
                .with_run(Run::new("Plain text, then "))
                .with_run(Run::new("some strongly emphasized text").with_style_id("StrongEmphasis"))
                .with_run(Run::new(", then plain text again.")),
        )
        .with_paragraph(heading("Bulleted list", true))
        .with_paragraph(Paragraph::with_text("First item").with_numbering(1, 0))
        .with_paragraph(Paragraph::with_text("Second item").with_numbering(1, 0))
        .with_paragraph(Paragraph::with_text("A sub-item, one level deeper").with_numbering(1, 1))
        .with_paragraph(heading("Numbered list", true))
        .with_paragraph(Paragraph::with_text("First step").with_numbering(2, 0))
        .with_paragraph(Paragraph::with_text("Second step").with_numbering(2, 0))
        .with_paragraph(
            Paragraph::with_text("A sub-step, cumulatively numbered").with_numbering(2, 1),
        )
        .with_paragraph(heading(
            "Custom multi-level list (roman numerals, then letters)",
            true,
        ))
        .with_paragraph(Paragraph::with_text("First top-level item").with_numbering(3, 0))
        .with_paragraph(Paragraph::with_text("A lettered sub-item").with_numbering(3, 1))
        .with_paragraph(Paragraph::with_text("Second top-level item").with_numbering(3, 0));

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

pub fn with_numbering(self, numbering_id: u32, level: u8) -> Paragraph

Makes this paragraph an item of numbering_id’s list, at the given indent level (0-indexed), and returns it for chaining.

Examples found in repository

examples/docx_styles_and_lists.rs (line 51)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_styles_and_lists.docx");

    let heading_style = Style::new("Heading1", "Heading 1", StyleKind::Paragraph)
        .with_bold(true)
        .with_font_size(32);
    let emphasis_style = Style::new("StrongEmphasis", "Strong Emphasis", StyleKind::Character)
        .with_bold(true)
        .with_color("C00000");

    let bulleted = NumberingDefinition::bullet(1);
    let numbered = NumberingDefinition::decimal(2);
    let custom = NumberingDefinition::new(
        3,
        vec![
            ListLevel::new(NumberFormat::UpperRoman, "%1.", 720, 360),
            ListLevel::new(NumberFormat::LowerLetter, "%2)", 1440, 360),
        ],
    );

    let document = Document::new()
        .with_style(heading_style)
        .with_style(emphasis_style)
        .with_numbering_definition(bulleted)
        .with_numbering_definition(numbered)
        .with_numbering_definition(custom)
        .with_paragraph(heading("Named paragraph and character styles", false))
        .with_paragraph(
            Paragraph::with_text("This paragraph uses the Heading 1 style.")
                .with_style_id("Heading1"),
        )
        .with_paragraph(
            Paragraph::new()
                .with_run(Run::new("Plain text, then "))
                .with_run(Run::new("some strongly emphasized text").with_style_id("StrongEmphasis"))
                .with_run(Run::new(", then plain text again.")),
        )
        .with_paragraph(heading("Bulleted list", true))
        .with_paragraph(Paragraph::with_text("First item").with_numbering(1, 0))
        .with_paragraph(Paragraph::with_text("Second item").with_numbering(1, 0))
        .with_paragraph(Paragraph::with_text("A sub-item, one level deeper").with_numbering(1, 1))
        .with_paragraph(heading("Numbered list", true))
        .with_paragraph(Paragraph::with_text("First step").with_numbering(2, 0))
        .with_paragraph(Paragraph::with_text("Second step").with_numbering(2, 0))
        .with_paragraph(
            Paragraph::with_text("A sub-step, cumulatively numbered").with_numbering(2, 1),
        )
        .with_paragraph(heading(
            "Custom multi-level list (roman numerals, then letters)",
            true,
        ))
        .with_paragraph(Paragraph::with_text("First top-level item").with_numbering(3, 0))
        .with_paragraph(Paragraph::with_text("A lettered sub-item").with_numbering(3, 1))
        .with_paragraph(Paragraph::with_text("Second top-level item").with_numbering(3, 0));

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

pub fn with_line_spacing(self, line_spacing: u32) -> Paragraph

Sets the paragraph’s line spacing (in w:spacing’s “auto” units — 240 is single, 360 is 1.5 lines, 480 is double) and returns it for chaining.

pub fn with_space_before(self, space_before: u32) -> Paragraph

Sets extra space before this paragraph, in twips, and returns it for chaining.

pub fn with_space_after(self, space_after: u32) -> Paragraph

Sets extra space after this paragraph, in twips, and returns it for chaining.

pub fn with_shading_color(self, shading_color: impl Into<String>) -> Paragraph

Sets the paragraph’s background shading color and returns it for chaining.

pub fn with_border(self, border: bool) -> Paragraph

Sets whether this paragraph has a border around it and returns it for chaining.

pub fn with_keep_with_next(self, keep_with_next: bool) -> Paragraph

Sets whether this paragraph stays on the same page as the one following it and returns it for chaining. See keep_with_next’s doc comment.

pub fn with_keep_lines_together(self, keep_lines_together: bool) -> Paragraph

Sets whether every line of this paragraph must stay together on the same page and returns it for chaining. See keep_lines_together’s doc comment.

pub fn with_page_break_before(self, page_break_before: bool) -> Paragraph

Sets whether this paragraph always starts on a new page and returns it for chaining. See page_break_before’s doc comment.

Examples found in repository

examples/docx_images_and_charts.rs (line 72)

fn heading(text: &str, new_page: bool) -> Paragraph {
    Paragraph::new()
        .with_run(Run::new(text).with_bold(true).with_font_size(28))
        .with_page_break_before(new_page)
}

examples/docx_navigation_and_annotations.rs (line 89)

fn heading(text: &str, new_page: bool) -> Paragraph {
    Paragraph::new()
        .with_run(Run::new(text).with_bold(true).with_font_size(28))
        .with_page_break_before(new_page)
}

examples/docx_page_layout.rs (line 64)

fn heading(text: &str, new_page: bool) -> Paragraph {
    Paragraph::new()
        .with_run(Run::new(text).with_bold(true).with_font_size(28))
        .with_page_break_before(new_page)
}

examples/docx_styles_and_lists.rs (line 76)

fn heading(text: &str, new_page: bool) -> Paragraph {
    Paragraph::new()
        .with_run(Run::new(text).with_bold(true).with_font_size(28))
        .with_page_break_before(new_page)
}

examples/docx_tables.rs (line 95)

fn heading(text: &str, new_page: bool) -> Paragraph {
    Paragraph::new()
        .with_run(Run::new(text).with_bold(true).with_font_size(28))
        .with_page_break_before(new_page)
}

examples/docx_text_formatting.rs (line 78)

fn heading(text: &str, new_page: bool) -> Paragraph {
    Paragraph::new()
        .with_run(Run::new(text).with_bold(true).with_font_size(28))
        .with_page_break_before(new_page)
}

pub fn with_tab(self, tab: TabStop) -> Paragraph

Appends a custom tab stop and returns the paragraph for chaining.

Examples found in repository

examples/docx_text_formatting.rs (line 63)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("docx_text_formatting.docx");

    let document = Document::new()
        .with_paragraph(heading("Docx text formatting — bold, italic, underline, strike", false))
        .with_paragraph(Paragraph::new().with_run(Run::new("Bold text.").with_bold(true)))
        .with_paragraph(Paragraph::new().with_run(Run::new("Italic text.").with_italic(true)))
        .with_paragraph(Paragraph::new().with_run(Run::new("Single underline.").with_underline(UnderlineStyle::Single)))
        .with_paragraph(Paragraph::new().with_run(Run::new("Wavy underline.").with_underline(UnderlineStyle::Wave)))
        .with_paragraph(Paragraph::new().with_run(Run::new("Strikethrough text.").with_strike(true)))
        .with_paragraph(heading("Colors and highlight", true))
        .with_paragraph(Paragraph::new().with_run(Run::new("Red text on the default background.").with_color("FF0000")))
        .with_paragraph(Paragraph::new().with_run(Run::new("Text highlighted in yellow.").with_highlight(Highlight::Yellow)))
        .with_paragraph(
            Paragraph::new()
                .with_run(Run::new("Larger, custom font.").with_font_size(32).with_font_family("Georgia")),
        )
        .with_paragraph(heading("Superscript and subscript", true))
        .with_paragraph(
            Paragraph::new()
                .with_run(Run::new("Water is H"))
                .with_run(Run::new("2").with_vertical_align(VerticalAlign::Subscript))
                .with_run(Run::new("O.")),
        )
        .with_paragraph(
            Paragraph::new()
                .with_run(Run::new("Squared: x"))
                .with_run(Run::new("2").with_vertical_align(VerticalAlign::Superscript))
                .with_run(Run::new(".")),
        )
        .with_paragraph(heading("Small caps, all caps, character spacing", true))
        .with_paragraph(Paragraph::new().with_run(Run::new("rendered in small caps").with_small_caps(true)))
        .with_paragraph(Paragraph::new().with_run(Run::new("rendered in all caps").with_all_caps(true)))
        .with_paragraph(Paragraph::new().with_run(Run::new("Widely spaced letters.").with_character_spacing(120)))
        .with_paragraph(heading("Paragraph alignment", true))
        .with_paragraph(Paragraph::with_text("Left-aligned (the default).").with_alignment(Alignment::Left))
        .with_paragraph(Paragraph::with_text("Centered.").with_alignment(Alignment::Center))
        .with_paragraph(Paragraph::with_text("Right-aligned.").with_alignment(Alignment::Right))
        .with_paragraph(
            Paragraph::with_text(
                "Justified: this line is long enough for Word to stretch the spacing between words so both edges line up.",
            )
            .with_alignment(Alignment::Justify),
        )
        .with_paragraph(heading("Tab stops", true))
        .with_paragraph(
            Paragraph::new()
                .with_tab(TabStop::new(1_440).with_alignment(TabStopAlignment::Center))
                .with_tab(TabStop::new(2_880).with_alignment(TabStopAlignment::Right).with_leader(TabLeader::Dot))
                .with_run(Run::new("Left\tCentered\tRight, dot leader")),
        );

    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());
    Ok(())
}

pub fn with_contextual_spacing(self, contextual_spacing: bool) -> Paragraph

Sets whether to ignore spacing above/below this paragraph when adjacent to a paragraph of the same style, and returns it for chaining. See contextual_spacing’s doc comment.

pub fn text(&self) -> String

The paragraph’s text: the concatenation of its text runs’ text. Image and field runs contribute nothing (not even a placeholder character).

Examples found in repository

examples/hello_world_docx.rs (line 25)

fn main() -> office_toolkit::Result<()> {
    let path = output_path("hello_world.docx");

    // `Document` and `Paragraph` both come from `office_toolkit::prelude`.
    let document = Document::new().with_paragraph(Paragraph::with_text("Hello, world!"));
    document.save_to_file(&path)?;
    println!("Wrote {}", path.display());

    // Read the file back to confirm it is a valid .docx.
    let reopened = Document::open_file(&path)?;
    let text = reopened
        .paragraphs()
        .next()
        .map(|paragraph| paragraph.text());
    println!("Read back: {text:?}");

    Ok(())
}

Trait Implementations

impl Clone for Paragraph

fn clone(&self) -> Paragraph

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Paragraph

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

Formats the value using the given formatter.

impl Default for Paragraph

fn default() -> Paragraph

Returns the “default value” for a type.

impl PartialEq for Paragraph

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for Paragraph