Struct Note

pub struct Note { /* private fields */ }

The Note struct represents a worksheet note object.

A Note is a post-it style message that is revealed when the user hovers over a worksheet cell. The presence of a Note is indicated by a small red triangle in the upper right-hand corner of the cell.

The above file was created using the following code:

use rust_xlsxwriter::{Note, Workbook, XlsxError};

fn main() -> Result<(), XlsxError> {
    // Create a new Excel file object.
    let mut workbook = Workbook::new();

    // Add a worksheet to the workbook.
    let worksheet = workbook.add_worksheet();

    // Widen the first column for clarity.
    worksheet.set_column_width(0, 16)?;

    // Write some data.
    let party_items = [
        "Invitations",
        "Doors",
        "Flowers",
        "Champagne",
        "Menu",
        "Peter",
    ];
    worksheet.write_column(0, 0, party_items)?;

    // Create a new worksheet Note.
    let note = Note::new("I will get the flowers myself").set_author("Clarissa Dalloway");

    // Add the note to a cell.
    worksheet.insert_note(2, 0, &note)?;

    // Save the file to disk.
    workbook.save("notes.xlsx")?;

    Ok(())
}

Notes are used in conjunction with the Worksheet::insert_note() method.

In versions of Excel prior to Office 365, Notes were referred to as “Comments”. The name “Comment” is now used for a newer style threaded comment, and “Note” is used for the older non-threaded version. See the Microsoft docs on The difference between threaded comments and notes.

Note, the newer Threaded Comments are unlikely to be added to rust_xlsxwriter due to the fact that the feature relies on company specific metadata to identify the comment author.

Implementations

impl Note

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

Create a new Note object to represent an Excel cell note.

The text of the Note is added in the constructor.

Parameters

• text: The text that will appear in the note.

Examples

The following example demonstrates adding a note to a worksheet cell.

    // Create a new note.
    let note = Note::new("Some text for the note");

    // Add the note to a worksheet cell.
    worksheet.insert_note(2, 0, &note)?;

Output file:

pub fn set_author(self, name: impl Into<String>) -> Note

Set the note author name.

The author name appears in two places: at the start of the note text in bold and at the bottom of the worksheet in the status bar.

If no name is specified, the default name “Author” will be applied to the note.

You can also set the default author name for all notes in a worksheet via the Worksheet::set_default_note_author() method.

Parameters

• name: The note author name. Must be less than or equal to the Excel limit of 52 characters.

Examples

The following example demonstrates adding a note to a worksheet cell. This example also sets the author name.

    // Create a new note.
    let note = Note::new("Some text for the note").set_author("Rust");

    // Add the note to a worksheet cell.
    worksheet.insert_note(2, 0, &note)?;

Output file:

pub fn add_author_prefix(self, enable: bool) -> Note

Prefix the note text with the author name.

By default Excel, and rust_xlsxwriter, prefixes the author name to the note text (see the previous examples). If you prefer to have the note text without the author name you can use this option to turn it off.

Parameters

• enable: Turn the property on/off. It is on by default.

Examples

The following example demonstrates adding a note to a worksheet cell. This example turns off the author name in the note.

    // Create a new note.
    let note = Note::new("Some text for the note")
        .add_author_prefix(false)
        .set_author("Rust"); // This is ignored in the Note.

    // Add the note to a worksheet cell.
    worksheet.insert_note(2, 0, &note)?;

Output file:

pub fn reset_text(&mut self, text: impl Into<String>) -> &mut Note

Reset the text in the note.

In general, the text of the note is set in the Note::new() constructor, but if required, you can use the reset_text() method to reset the text for a note. This allows a single Note instance to be used multiple times and avoids the small overhead of creating a new instance each time.

Parameters

• text: The text for the note.

Examples

The following example demonstrates adding a note to a worksheet cell. This example reuses the Note object and resets the text.

    // Create a new note.
    let mut note = Note::new("Some text for the note");

    // Add the note to a worksheet cell.
    worksheet.insert_note(2, 0, &note)?;

    // Reuse the Note with different text.
    note.reset_text("Some other text");

    // Add the note to another worksheet cell.
    worksheet.insert_note(4, 0, &note)?;

Output file:

pub fn set_width(self, width: u32) -> Note

Set the width of the note in pixels.

The default width of an Excel note is 128 pixels.

Parameters

• width: The note width in pixels.

Examples

The following example demonstrates adding a note to a worksheet cell. This example also changes the note dimensions.

    // Create a new note.
    let note = Note::new("Some text for the note")
        .set_width(200)
        .set_height(200);

    // Add the note to a worksheet cell.
    worksheet.insert_note(2, 0, &note)?;

Output file:

pub fn set_height(self, height: u32) -> Note

Set the height of the note in pixels.

The default height of an Excel note is 74 pixels. See the example above.

Parameters

• height: The note height in pixels.

pub fn set_visible(self, enable: bool) -> Note

Make the note visible when the file loads.

By default Excel hides cell notes until the user mouses over the parent cell. However, if required you can make the note visible without requiring an interaction from the user.

You can also make all notes in a worksheet visible via the Worksheet::show_all_notes() method.

Parameters

• enable: Turn the property on/off. It is off by default.

Examples

The following example demonstrates adding a note to a worksheet cell. This example makes the note visible by default.

    // Create a new note.
    let note = Note::new("Some text for the note").set_visible(true);

    // Add the note to a worksheet cell.
    worksheet.insert_note(2, 0, &note)?;

Output file:

pub fn set_background_color(self, color: impl Into<Color>) -> Note

Set the background color for the note.

The default background color for a Note is #FFFFE1. If required this method can be used to set it to a different RGB color.

Parameters

• color: The background color property defined by a Color enum value or a type that can convert Into a Color. Only the Color::Name and Color::RGB() variants are supported. Theme style colors aren’t support by Excel for Notes.

Examples

The following example demonstrates adding a note to a worksheet cell. This example also sets the background color.

    // Create a new note.
    let note = Note::new("Some text for the note").set_background_color("#80ff80");

    // Add the note to a worksheet cell.
    worksheet.insert_note(2, 0, &note)?;

Output file:

pub fn set_font_name(self, font_name: impl Into<String>) -> Note

Set the font name for the note.

Set the font for a cell note. Excel can only display fonts that are installed on the system that it is running on. Therefore it is generally best to use standard Excel fonts.

Parameters

• font_name: The font name for the note.

pub fn set_font_size<T>(self, font_size: T) -> Note

where T: Into<f64>,

Set the font size for the note.

Set the font size of the cell format. The size is generally an integer value but Excel allows x.5 values (hence the property is a f64 or types that can convert Into a f64).

Parameters

• font_size: The font size for the note.

pub fn set_alt_text(self, alt_text: impl Into<String>) -> Note

Set the alt text for the note to help accessibility.

The alt text is used with screen readers to help people with visual disabilities.

See the following Microsoft documentation on Everything you need to know to write effective alt text.

Parameters

• alt_text: The alt text string to add to the note.

pub fn set_object_movement(self, option: ObjectMovement) -> Note

Set the object movement options for a worksheet note.

Set the option to define how an note will behave in Excel if the cells under the note are moved, deleted, or have their size changed. In Excel the options are:

1. Move and size with cells.
2. Move but don’t size with cells.
3. Don’t move or size with cells.

These values are defined in the ObjectMovement enum.

The ObjectMovement enum also provides an additional option to “Move and size with cells - after the note is inserted” to allow notes to be hidden in rows or columns. In Excel this equates to option 1 above but the internal note position calculations are handled differently.

Parameters

• option: An note/object positioning behavior defined by the ObjectMovement enum.

Trait Implementations

impl Clone for Note

fn clone(&self) -> Note

Returns a duplicate of the value.

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

Performs copy-assignment from source.