Struct Run 

pub struct Run {

    pub content: RunContent,
    pub bold: bool,
    pub italic: bool,
    pub underline: Option<UnderlineStyle>,
    pub underline_color: Option<String>,
    pub color: Option<String>,
    pub font_size: Option<u16>,
    pub font_family: Option<String>,
    pub highlight: Option<Highlight>,
    pub strike: bool,
    pub vertical_align: Option<VerticalAlign>,
    pub small_caps: bool,
    pub all_caps: bool,
    pub shading_color: Option<String>,
    pub text_border: bool,
    pub character_spacing: Option<i16>,
    pub vertical_position: Option<i16>,
    pub hidden: bool,
    pub style_id: Option<String>,
    pub hyperlink: Option<Hyperlink>,
    pub comment_ids: Vec<u32>,
    pub bookmarks: Vec<Bookmark>,
}

A run: a contiguous span of content (text, an inline image, or a field) sharing the same formatting.

Fields

content: RunContent

The run’s content.

bold: bool

Whether the run is bold (<w:b/>, WordprocessingML CT_RPr). Meaningful for RunContent::Text and RunContent::Field; ignored when writing an image run.

italic: bool

Whether the run is italic (<w:i/>).

underline: Option<UnderlineStyle>

The run’s underline style (<w:u w:val="..">, CT_Underline), or None for no underline. See UnderlineStyle’s doc comment for the full palette of styles (ST_Underline).

underline_color: Option<String>

The color of underline’s line (w:u’s color attribute), as a plain 6-digit RGB hex string, or None to leave it unset (matches the text color — visually the same outcome as CT_Underline’s other color choice, the literal string "auto", which isn’t modeled separately, same convention as Run.color). Only meaningful when underline is Some; theme-relative colors (w:themeColor/w:themeTint/w:themeShade) aren’t modeled either, same scope limit as color itself.

color: Option<String>

The run’s text color (<w:color w:val="..">, CT_Color), as a plain 6-digit RGB hex string (no leading #, e.g. "FF0000"), or None to leave it unset (inherits from the paragraph/character style, or Word’s own default — visually the same outcome as CT_Color’s other val choice, the literal string "auto", which isn’t modeled separately since omitting the element entirely already achieves it). Theme-relative colors (w:themeColor/w:themeTint/ w:themeShade, CT_Color’s other attributes) aren’t modeled either — same scope limit as Theme itself, which only lets a document’s theme be set, not referenced from formatting.

font_size: Option<u16>

The run’s font size in whole points (e.g. 12), or None to leave it unset. Written as <w:sz w:val="..">/<w:szCs w:val=".."> (CT_HpsMeasure, in half-points — 24 for a 12pt run — the writer does the doubling), both set to the same value since complex-script sizing isn’t modeled separately. WordprocessingML’s w:sz actually allows half-point granularity (e.g. 10.5pt), but only whole points are modeled here — no real need for finer granularity has come up.

font_family: Option<String>

The run’s font family/typeface (e.g. "Calibri"), or None to leave it unset. Written as <w:rFonts w:ascii=".." w:hAnsi=".."> (CT_Fonts), both set to the same value; w:eastAsia/w:cs (East Asian / complex-script typefaces) aren’t modeled, same scope limit as FontScheme’s Latin-only typefaces.

highlight: Option<Highlight>

The run’s highlight color (<w:highlight w:val="..">, CT_Highlight — a fixed “highlighter” palette, distinct from color), or None for no highlighting. See Highlight’s doc comment.

strike: bool

Whether the run is struck through (<w:strike/>, CT_OnOff) — a single horizontal line through the text. WordprocessingML also defines w:dstrike (double strikethrough), not modeled here.

vertical_align: Option<VerticalAlign>

The run’s vertical alignment (<w:vertAlign w:val="..">, CT_VerticalAlignRun) — superscript or subscript, or None for the normal baseline position. See VerticalAlign’s doc comment.

small_caps: bool

Whether lowercase letters in the run are displayed as small capital letters (<w:smallCaps/>, CT_OnOff) — a display-only effect, the underlying text isn’t changed. Distinct from all_caps, which affects lowercase AND uppercase letters the same way.

all_caps: bool

Whether all characters in the run are displayed as capital letters (<w:caps/>, CT_OnOff) — like small_caps, a display-only effect. small_caps and all_caps are mutually exclusive in practice (Word’s UI won’t let both apply to the same text at once), but that isn’t enforced here — setting both just lets all_caps visually win, matching real Word rendering.

shading_color: Option<String>

The run’s background shading color (<w:shd w:val="clear" w:color="auto" w:fill="..">, CT_Shd), as a plain 6-digit RGB hex string, or None for no shading. Unlike highlight’s fixed 16-color “highlighter” palette, this is an arbitrary color, closer to a text background fill — val/color (the shading pattern and its foreground color) are always written as the fixed "clear"/"auto" pair for a plain solid fill, matching this crate’s convention for schema-mandatory-but-out-of-scope attributes (see Theme’s fmtScheme); patterned shading (crosshatch, stripes, etc.) and w:themeFill aren’t modeled.

text_border: bool

Whether the run has a border around its text (<w:bdr w:val="single" w:sz="4" w:space="0" w:color="auto"/>, CT_Border) — a simple on/off flag rather than exposing CT_Border’s full richness (border style, width, spacing, color, shadow, frame effect), since this property is niche enough that a single sensible fixed appearance (thin single black line, no gap) covers the common case; broader configurability can be added later if a real need comes up, same posture as strike not modeling w:dstrike.

character_spacing: Option<i16>

Character spacing adjustment (<w:spacing w:val="..">, CT_SignedTwipsMeasure), in twips (twentieths of a point) — positive expands letter spacing, negative condenses it — or None to leave it unset.

vertical_position: Option<i16>

The run’s vertical position, raised or lowered from the normal baseline (<w:position w:val="..">, CT_SignedHpsMeasure), in half-points — positive raises, negative lowers — or None to leave it at the baseline. Distinct from vertical_align (superscript/subscript): position shifts the baseline without shrinking the font size, vertical_align does both together.

hidden: bool

Whether the run’s text is hidden (<w:vanish/>, CT_OnOff) — present in the document but not displayed or printed by default (Word’s Home > Show/Hide formatting marks toggle reveals it).

style_id: Option<String>

The id of a character-type Style to apply (w:rStyle), or None. Like Paragraph.style_id, not validated against Document.styles when writing.

hyperlink: Option<Hyperlink>

A hyperlink to apply to this run (w:hyperlink), or None. See Hyperlink’s doc comment for how this reconciles with the underlying XML, where a hyperlink actually wraps a run rather than being one of its properties.

comment_ids: Vec<u32>

The ids of the Comments (Document.comments) whose range covers this run — usually empty, usually a single id, but a run can fall inside several overlapping comment ranges at once (real Word documents do have overlapping comments), hence a Vec rather than an Option<u32>.

Strictly, in the underlying XML, a comment range is not a run property either: w:commentRangeStart/w:commentRangeEnd (CT_MarkupRange) are empty siblings of w:r marking where a range starts/ends, and w:commentReference (the balloon anchor mark) is its own run placed right after the matching w:commentRangeEnd — none of which the caller has to place by hand here, unlike NoteReference. The writer derives all three automatically: consecutive runs sharing an id become one w:commentRangeStart/w:commentRangeEnd pair spanning them (not one pair per run — that would emit the same id’s start/end repeatedly, breaking the pairing CT_MarkupRange’s doc comment describes), with the matching w:commentReference written immediately after the range closes (see write_paragraph in writer.rs). Only comment ranges within a single paragraph are supported — WordprocessingML does allow a range to span several paragraphs or even wrap a whole table (“cross structure” annotations, ECMA-376 §2.13.4), out of scope for now, the same kind of deliberate scope limit as header/footer’s “default”-only variant.

bookmarks: Vec<Bookmark>

The Bookmarks whose range covers this run — same range-tracking convention as comment_ids, but each bookmark’s id/name pair travels directly with the run rather than being centralized in a separate Document-level list: unlike a comment reference (which only ever needs an id, since the name/author/date lives in word/comments.xml, a whole separate part), w:bookmarkStart carries its w:name right there on the inline marker itself, so there is no separate part write_paragraph would need to consult.

Strictly, in the underlying XML, a bookmark range is not a run property either — w:bookmarkStart/w:bookmarkEnd (CT_Bookmark/ CT_MarkupRange) are empty siblings of w:r, members of the same EG_PContent choice group as w:commentRangeStart/ commentRangeEnd, so the writer derives them the same way: runs sharing a bookmark id (repeated by the caller on each one, same asymmetry as comment_ids) become one w:bookmarkStart/ w:bookmarkEnd pair spanning them. Only bookmark ranges within a single paragraph are supported (not a range spanning several paragraphs, nor a zero-width “point” bookmark with no run content at all) — same deliberate scope limit as comment_ids.

Implementations

impl Run

pub fn new(text: impl Into<String>) -> Run

Creates a text run with the given text and no formatting.

Examples found in repository

examples/docx_images_and_charts.rs (line 71)

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 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_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 (line 26)

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_image(image: Image) -> Run

Creates a run containing a single inline image.

Examples found in repository

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(())
}

pub fn with_chart(chart: EmbeddedChart) -> Run

Creates a run containing a single embedded chart.

Examples found in repository

examples/docx_images_and_charts.rs (line 32)

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(())
}

pub fn with_field(field: Field) -> Run

Creates a run containing a single field (e.g. a page number).

pub fn with_break(kind: BreakKind) -> Run

Creates a run whose content is a single explicit break (w:br, page/column/line). See BreakKind’s doc comment.

pub fn with_carriage_return() -> Run

Creates a run whose content is a single carriage return (w:cr). See RunContent::CarriageReturn’s doc comment for how this differs from with_break(BreakKind::TextWrapping).

pub fn text(&self) -> Option<&str>

This run’s text, or None if it is an image, chart, field, note, break or carriage return run.

pub fn image(&self) -> Option<&Image>

This run’s image, or None if it isn’t an image run.

pub fn chart(&self) -> Option<&EmbeddedChart>

This run’s chart, or None if it isn’t a chart run.

pub fn field(&self) -> Option<Field>

This run’s field, or None if it isn’t a field run.

pub fn with_bold(self, bold: bool) -> Run

Sets whether the run is bold and returns it for chaining.

Examples found in repository

examples/docx_images_and_charts.rs (line 71)

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 88)

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 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_styles_and_lists.rs (line 75)

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_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_italic(self, italic: bool) -> Run

Sets whether the run is italic and returns it for chaining.

Examples found in repository

examples/docx_text_formatting.rs (line 22)

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_underline(self, underline: UnderlineStyle) -> Run

Sets the run’s underline style and returns it for chaining.

Examples found in repository

examples/docx_text_formatting.rs (line 23)

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_underline_color(self, underline_color: impl Into<String>) -> Run

Sets the color of the run’s underline (a 6-digit RGB hex string, no leading #) and returns it for chaining. Only meaningful once with_underline has also been called.

pub fn with_color(self, color: impl Into<String>) -> Run

Sets the run’s text color (a 6-digit RGB hex string, no leading #) and returns it for chaining.

Examples found in repository

examples/docx_text_formatting.rs (line 27)

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_font_size(self, font_size: u16) -> Run

Sets the run’s font size in whole points and returns it for chaining.

Examples found in repository

examples/docx_images_and_charts.rs (line 71)

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 88)

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 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_styles_and_lists.rs (line 75)

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_text_formatting.rs (line 31)

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_font_family(self, font_family: impl Into<String>) -> Run

Sets the run’s font family/typeface and returns it for chaining.

Examples found in repository

examples/docx_text_formatting.rs (line 31)

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_highlight(self, highlight: Highlight) -> Run

Sets the run’s highlight color and returns it for chaining.

Examples found in repository

examples/docx_text_formatting.rs (line 28)

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_strike(self, strike: bool) -> Run

Sets whether the run is struck through and returns it for chaining.

Examples found in repository

examples/docx_text_formatting.rs (line 25)

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_vertical_align(self, vertical_align: VerticalAlign) -> Run

Sets the run’s vertical alignment (superscript/subscript) and returns it for chaining.

Examples found in repository

examples/docx_text_formatting.rs (line 37)

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_small_caps(self, small_caps: bool) -> Run

Sets whether the run is displayed as small caps and returns it for chaining.

Examples found in repository

examples/docx_text_formatting.rs (line 47)

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_all_caps(self, all_caps: bool) -> Run

Sets whether the run is displayed as all caps and returns it for chaining.

Examples found in repository

examples/docx_text_formatting.rs (line 48)

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_shading_color(self, shading_color: impl Into<String>) -> Run

Sets the run’s background shading color (a 6-digit RGB hex string, no leading #) and returns it for chaining.

pub fn with_text_border(self, text_border: bool) -> Run

Sets whether the run has a border around its text and returns it for chaining.

pub fn with_character_spacing(self, character_spacing: i16) -> Run

Sets the run’s character spacing adjustment, in twips, and returns it for chaining.

Examples found in repository

examples/docx_text_formatting.rs (line 49)

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_vertical_position(self, vertical_position: i16) -> Run

Sets the run’s vertical position, raised or lowered from the baseline, in half-points, and returns it for chaining.

pub fn with_hidden(self, hidden: bool) -> Run

Sets whether the run’s text is hidden and returns it for chaining.

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

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

Examples found in repository

examples/docx_styles_and_lists.rs (line 47)

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_hyperlink(self, hyperlink: Hyperlink) -> Run

Sets the hyperlink to apply to this run and returns it for chaining.

Examples found in repository

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(())
}

pub fn with_comment(self, comment_id: u32) -> Run

Marks this run as falling inside the given Comment’s range (see comment_ids‘s doc comment) and returns it for chaining. Call repeatedly to place a run inside several overlapping comments’ ranges at once.

Examples found in repository

examples/docx_navigation_and_annotations.rs (line 48)

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(())
}

pub fn with_bookmark(self, bookmark: Bookmark) -> Run

Marks this run as falling inside the given Bookmark’s range (see bookmarks‘s doc comment) and returns it for chaining. Call repeatedly to place a run inside several overlapping bookmarks’ ranges at once, or on consecutive runs to span a bookmark across more than one run — repeat the exact same Bookmark (same id, same name) on every run the bookmark should cover.

Examples found in repository

examples/docx_navigation_and_annotations.rs (line 39)

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(())
}

pub fn with_note_reference(reference: NoteReference) -> Run

Creates a run referencing a footnote/endnote (<w:footnoteReference>/ <w:endnoteReference>), to be placed in the document body.

Word always renders this reference in the “FootnoteReference”/ “EndnoteReference” built-in character style (a superscript number) — real Word documents rely on Word’s own built-in latent style definitions for these well-known style ids, with no need to declare a matching Style in Document.styles, so this constructor sets style_id accordingly. Override it afterwards (with_style_id) if a different style is genuinely needed.

Examples found in repository

examples/docx_navigation_and_annotations.rs (line 59)

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(())
}

pub fn with_note_marker(kind: NoteKind) -> Run

Creates a run rendering a footnote/endnote’s own number marker (<w:footnoteRef/>/<w:endnoteRef/>) — meant to be the first run of the note’s own first paragraph (see Note::footnote_with_text/ Note::endnote_with_text for a convenience that builds this automatically). Sets style_id the same way Run::with_note_reference does, for the same reason.

Trait Implementations

impl Clone for Run

fn clone(&self) -> Run

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Run

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

Formats the value using the given formatter.

impl Default for Run

fn default() -> Run

Returns the “default value” for a type.

impl PartialEq for Run

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for Run