Struct UserModel 

pub struct UserModel<'a> { /* private fields */ }

A wrapper around Model for a spreadsheet end user.

UserModel is a wrapper around Model with undo/redo history, diffs, automatic evaluation and view management.

A diff in this context (or more correctly a user diff) is a change created by a user.

Automatic evaluation means that actions like setting a value on a cell or deleting a column will evaluate the model if needed.

It is meant to be used by UI applications like Web IronCalc or TironCalc.

Examples

let mut model = UserModel::new_empty("model", "en", "UTC", "en")?;
model.set_user_input(0, 1, 1, "=1+1")?;
assert_eq!(model.get_formatted_cell_value(0, 1, 1)?, "2");
model.undo()?;
assert_eq!(model.get_formatted_cell_value(0, 1, 1)?, "");
model.redo()?;
assert_eq!(model.get_formatted_cell_value(0, 1, 1)?, "2");

Implementations

impl<'a> UserModel<'a>

pub fn auto_fill_rows( &mut self, source_area: &Area, to_row: i32, ) -> Result<(), String>

Fills the cells from source_area until to_row. This simulates the user clicking on the cell outline handle and dragging it downwards (or upwards)

pub fn auto_fill_columns( &mut self, source_area: &Area, to_column: i32, ) -> Result<(), String>

Fills the cells from source_area until to_column. This simulates the user clicking on the cell outline handle and dragging it to the right (or to the left)

impl<'a> UserModel<'a>

pub fn set_area_with_border( &mut self, range: &Area, border_area: &BorderArea, ) -> Result<(), String>

Sets the border in an area of cells. When setting the border we need to check if the adjacent cells have a “heavier” border If that is the case we need to change it

impl<'a> UserModel<'a>

pub fn copy_to_clipboard(&self) -> Result<Clipboard, String>

Returns a copy of the selected area

pub fn paste_from_clipboard( &mut self, source_sheet: u32, source_range: (i32, i32, i32, i32), clipboard: &ClipboardData, is_cut: bool, ) -> Result<(), String>

Paste text that we copied

pub fn paste_csv_string(&mut self, area: &Area, csv: &str) -> Result<(), String>

Paste a csv-string into the model

impl<'a> UserModel<'a>

pub fn from_model(model: Model<'_>) -> UserModel<'_>

Creates a user model from an existing model

pub fn new_empty( name: &'a str, locale_id: &'a str, timezone: &'a str, language_id: &'a str, ) -> Result<UserModel<'a>, String>

Creates a new UserModel.

See also:

• Model::new_empty

pub fn from_bytes( s: &[u8], language_id: &'a str, ) -> Result<UserModel<'a>, String>

Creates a model from it’s internal representation

See also:

• Model::from_bytes

pub fn to_bytes(&self) -> Vec<u8>

Returns the internal representation of a model

See also:

• Model::to_bytes

pub fn get_model(&self) -> &Model<'_>

Returns the internal model

pub fn get_name(&self) -> String

Returns the workbook name

pub fn set_name(&mut self, name: &str)

Sets the name of a workbook

pub fn undo(&mut self) -> Result<(), String>

Undoes last change if any, places the change in the redo list and evaluates the model if needed

See also:

• UserModel::redo

pub fn redo(&mut self) -> Result<(), String>

Redoes the last undone change, places the change in the undo list and evaluates the model if needed

See also:

• UserModel::redo

pub fn can_undo(&self) -> bool

Returns true if there are items to be undone

pub fn can_redo(&self) -> bool

Returns true if there are items to be redone

pub fn pause_evaluation(&mut self)

Pauses automatic evaluation.

See also:

• UserModel::evaluate
• UserModel::resume_evaluation

pub fn resume_evaluation(&mut self)

Resumes automatic evaluation.

See also:

• UserModel::evaluate
• UserModel::pause_evaluation

pub fn evaluate(&mut self)

Forces an evaluation of the model

See also:

• Model::evaluate
• UserModel::pause_evaluation

pub fn flush_send_queue(&mut self) -> Vec<u8>

Returns the list of pending diffs and removes them from the queue

This is used together with apply_external_diffs to keep two remote models in sync.

See also:

• UserModel::apply_external_diffs

pub fn apply_external_diffs( &mut self, diff_list_str: &[u8], ) -> Result<(), String>

This are external diffs that need to be applied to the model

This is used together with flush_send_queue to keep two remote models in sync

See also:

• UserModel::flush_send_queue

pub fn set_user_input( &mut self, sheet: u32, row: i32, column: i32, value: &str, ) -> Result<(), String>

Set the input in a cell

See also:

• Model::set_user_input

pub fn get_cell_content( &self, sheet: u32, row: i32, column: i32, ) -> Result<String, String>

Returns the content of a cell

See also:

• Model::get_localized_cell_content

pub fn formula_completion( &mut self, sheet: u32, row: i32, column: i32, formula: &str, cursor: usize, ) -> Result<CompletionContext, String>

Returns completion information for a formula being edited in a cell.

formula is the raw cell input (it may start with =) and cursor is a char offset into it.

See also:

• Model::formula_completion

pub fn cycle_reference( &self, value: &str, start: usize, end: usize, ) -> Result<(String, i32, i32), String>

Cycles the references touched by the cursor through the four absolute/relative states, Excel F4 style: A1 -> $A$1 -> A$1 -> $A1 -> A1. Returns the new text together with the new cursor start and end.

See also:

• Model::cycle_reference

pub fn get_formatted_cell_value( &self, sheet: u32, row: i32, column: i32, ) -> Result<String, String>

Returns the formatted value of a cell

See also:

• Model::get_formatted_cell_value

pub fn get_cell_type( &self, sheet: u32, row: i32, column: i32, ) -> Result<CellType, String>

Returns the type of the cell

See also

• Model::get_cell_type

pub fn new_sheet(&mut self) -> Result<(), String>

Adds new sheet

See also:

• Model::new_sheet

pub fn duplicate_sheet(&mut self, sheet: u32) -> Result<(), String>

Duplicates a sheet by index, placing the copy right after it and selecting it.

See also:

• Model::duplicate_sheet

pub fn delete_sheet(&mut self, sheet: u32) -> Result<(), String>

Deletes sheet by index

See also:

• Model::delete_sheet

pub fn rename_sheet(&mut self, sheet: u32, new_name: &str) -> Result<(), String>

Renames a sheet by index

See also:

• Model::rename_sheet_by_index

pub fn move_sheet( &mut self, sheet_index: u32, new_index: u32, ) -> Result<(), String>

Moves the worksheet at sheet_index to new_index within the workbook, shifting the other sheets to accommodate. The moved worksheet ends up at exactly new_index.

The reorder is undoable/redoable, and the new order is preserved when the workbook is saved. Cross-sheet formula references stay valid across the move (sheet order is a position, not an identity — references key off the sheet name/id). The selection follows the same sheet across the move.

Moving a sheet to its current position is a no-op (no history entry). Fails if either index is out of range.

See also:

• Model::move_sheet

pub fn hide_sheet(&mut self, sheet: u32) -> Result<(), String>

Hides sheet by index

See also:

• Model::set_sheet_state
• UserModel::unhide_sheet

pub fn unhide_sheet(&mut self, sheet: u32) -> Result<(), String>

Un hides sheet by index

See also:

• Model::set_sheet_state
• UserModel::hide_sheet

pub fn set_sheet_color( &mut self, sheet: u32, color: &Color, ) -> Result<(), String>

Sets sheet color

Note: an empty string will remove the color

See also

• Model::set_sheet_color
• UserModel::get_worksheets_properties

pub fn range_clear_all(&mut self, range: &Area) -> Result<(), String>

Removes cells contents and style

See also:

• Model::range_clear_all

pub fn range_clear_contents(&mut self, range: &Area) -> Result<(), String>

Deletes the content in cells, but keeps the style

See also:

• Model::range_clear_contents

pub fn range_clear_formatting(&mut self, range: &Area) -> Result<(), String>

Removes cells styles and formatting, but keeps the content

See also:

• UserModel::range_clear_all
• UserModel::range_clear_contents

pub fn insert_rows( &mut self, sheet: u32, row: i32, row_count: i32, ) -> Result<(), String>

Inserts row_count blank rows starting at row (both 0-based).

Parameters

• sheet – worksheet index.
• row – first row to insert.
• row_count – number of rows (> 0).

History: the method pushes row_count Diff::InsertRow items all using the same row index. Replaying those diffs (undo / redo) is therefore immune to the row-shifts that happen after each individual insertion.

See also Model::insert_rows.

pub fn insert_columns( &mut self, sheet: u32, column: i32, column_count: i32, ) -> Result<(), String>

Inserts column_count blank columns starting at column (0-based).

Parameters

• sheet – worksheet index.
• column – first column to insert.
• column_count – number of columns (> 0).

History: pushes one Diff::InsertColumn per inserted column, all with the same column value, preventing index drift when the diffs are reapplied.

See also Model::insert_columns.

pub fn delete_rows( &mut self, sheet: u32, row: i32, row_count: i32, ) -> Result<(), String>

Deletes row_count rows starting at row.

History: a Diff::DeleteRow is created for each row, ordered bottom → top. Undo therefore recreates rows from top → bottom and redo removes them bottom → top, avoiding index drift.

See also Model::delete_rows.

pub fn delete_columns( &mut self, sheet: u32, column: i32, column_count: i32, ) -> Result<(), String>

Deletes column_count columns starting at column.

History: pushes one Diff::DeleteColumn per column, right → left, so replaying the list is always safe with respect to index shifts.

See also Model::delete_columns.

pub fn move_columns_action( &mut self, sheet: u32, column: i32, column_count: i32, delta: i32, ) -> Result<(), String>

Moves a column horizontally and adjusts formulas

pub fn move_rows_action( &mut self, sheet: u32, row: i32, row_count: i32, delta: i32, ) -> Result<(), String>

Moves a group of rows vertically and adjusts formulas

pub fn set_columns_width( &mut self, sheet: u32, column_start: i32, column_end: i32, width: f64, ) -> Result<(), String>

Sets the width of a group of columns in a single diff list

See also:

• Model::set_column_width

pub fn set_columns_hidden( &mut self, sheet: u32, column_start: i32, column_end: i32, hidden: bool, ) -> Result<(), String>

Sets the hidden state of a range of columns in a single diff list See also:

• Model::set_column_hidden

pub fn set_rows_hidden( &mut self, sheet: u32, row_start: i32, row_end: i32, hidden: bool, ) -> Result<(), String>

Sets the hidden state of a range of rows in a single diff list

• Model::set_row_hidden

pub fn set_rows_height( &mut self, sheet: u32, row_start: i32, row_end: i32, height: f64, ) -> Result<(), String>

Sets the height of a range of rows in a single diff list

See also:

• Model::set_row_height

pub fn get_row_height(&self, sheet: u32, row: i32) -> Result<f64, String>

Gets the height of a row

See also:

• Model::get_row_height

pub fn get_column_width(&self, sheet: u32, column: i32) -> Result<f64, String>

Gets the width of a column

See also:

• Model::get_column_width

pub fn get_frozen_rows_count(&self, sheet: u32) -> Result<i32, String>

Returns the number of frozen rows in the sheet

See also:

• Model::get_frozen_rows_count()

pub fn get_frozen_columns_count(&self, sheet: u32) -> Result<i32, String>

Returns the number of frozen columns in the sheet

See also:

• Model::get_frozen_columns_count()

pub fn set_frozen_rows_count( &mut self, sheet: u32, frozen_rows: i32, ) -> Result<(), String>

Sets the number of frozen rows in sheet

See also:

• Model::set_frozen_rows()

pub fn set_frozen_columns_count( &mut self, sheet: u32, frozen_columns: i32, ) -> Result<(), String>

Sets the number of frozen columns in sheet

See also:

• Model::set_frozen_columns()

pub fn on_paste_styles(&mut self, styles: &[Vec<Style>]) -> Result<(), String>

Paste styles in the selected area

pub fn update_range_style( &mut self, range: &Area, style_path: &str, value: &str, ) -> Result<(), String>

Updates the range with a cell style. See also:

• Model::set_cell_style

pub fn get_cell_style( &self, sheet: u32, row: i32, column: i32, ) -> Result<Style, String>

Returns the style for a cell

Cells share a border, so the left border of B1 is the right border of A1 In the object structure the borders of the cells might be difference, We always pick the “heaviest” border.

See also:

• Model::get_style_for_cell

pub fn get_extended_cell_style( &self, sheet: u32, row: i32, column: i32, ) -> Result<ExtendedStyle, String>

Returns the full extended style for a cell, including any conditional formatting overlay.

Identical border-adjacency logic as Self::get_cell_style but applied to the CF-overlaid style. Use this when you need icon-set or data-bar decorations in addition to the base style.

pub fn get_worksheets_properties(&self) -> Vec<SheetProperties>

Returns information about the sheets

See also:

• Model::get_worksheets_properties

pub fn set_theme(&mut self, theme: Theme)

Sets the workbook theme.

pub fn get_theme(&self) -> Theme

Returns the current workbook theme.

pub fn resolve_color(&self, color: &Color) -> String

Resolves a Color value to a CSS hex string using the current workbook theme. Returns an empty string for Color::None.

pub fn set_show_grid_lines( &mut self, sheet: u32, show_grid_lines: bool, ) -> Result<(), String>

Set the gid lines in the worksheet to visible (true) or hidden (false)

pub fn get_show_grid_lines(&self, sheet: u32) -> Result<bool, String>

Returns true in the grid lines for

pub fn get_last_non_empty_in_row_before_column( &self, sheet: u32, row: i32, column: i32, ) -> Result<Option<i32>, String>

Returns the largest column in the row less than a column whose cell has a non empty value. If there are none it returns None. This is useful when rendering a part of a worksheet to know which cells spill over

pub fn get_first_non_empty_in_row_after_column( &self, sheet: u32, row: i32, column: i32, ) -> Result<Option<i32>, String>

Returns the smallest column in the row larger than “column” whose cell has a non empty value. If there are none it returns None. This is useful when rendering a part of a worksheet to know which cells spill over

pub fn get_cell_array_structure( &self, sheet: u32, row: i32, column: i32, ) -> Result<CellArrayStructure, String>

Returns the geometric structure of a cell

pub fn set_user_array_formula( &mut self, sheet: u32, row: i32, column: i32, width: i32, height: i32, formula: &str, ) -> Result<(), String>

Sets an array formula in the given range.

pub fn get_defined_name_list(&self) -> Vec<(String, Option<u32>, String)>

Returns the list of defined names

pub fn delete_defined_name( &mut self, name: &str, scope: Option<u32>, ) -> Result<(), String>

Delete an existing defined name

pub fn new_defined_name( &mut self, name: &str, scope: Option<u32>, formula: &str, ) -> Result<(), String>

Create a new defined name

pub fn update_defined_name( &mut self, name: &str, scope: Option<u32>, new_name: &str, new_scope: Option<u32>, new_formula: &str, ) -> Result<(), String>

Updates a defined name

pub fn is_valid_defined_name( &mut self, name: &str, scope: Option<u32>, formula: &str, ) -> Result<Option<u32>, String>

validates a new defined name

pub fn set_timezone(&mut self, timezone: &str) -> Result<(), String>

Sets the timezone for the model

pub fn set_locale(&mut self, locale: &str) -> Result<(), String>

Sets the locale for the model

pub fn get_timezone(&self) -> String

Gets the timezone of the model

pub fn get_locale(&self) -> String

Gets the locale of the model

pub fn get_language(&self) -> String

Get the language for the model

pub fn set_language(&mut self, language: &str) -> Result<(), String>

Sets the language for the model

pub fn get_fmt_settings(&self) -> FmtSettings

Gets the formatting settings for the model

impl<'a> UserModel<'a>

pub fn get_conditional_formatting_list( &self, sheet: u32, ) -> Result<Vec<ConditionalFormattingView>, String>

Returns all CF rules for the given sheet, sorted by priority descending.

Each entry carries its storage index; see crate::Model::get_conditional_formatting_list.

pub fn get_dxf_for_conditional_formatting( &self, sheet: u32, index: u32, ) -> Result<Option<Dxf>, String>

Returns the differential format (Dxf) for the CF rule at index on sheet, or None if the rule type has no associated dxf (e.g. ColorScale, DataBar).

pub fn add_conditional_formatting( &mut self, sheet: u32, range: &str, rule: CfRuleInput, ) -> Result<(), String>

Adds a new CF rule to sheet.

pub fn delete_conditional_formatting( &mut self, sheet: u32, index: u32, ) -> Result<(), String>

Removes the CF rule at index from sheet.

pub fn update_conditional_formatting( &mut self, sheet: u32, index: u32, new_range: &str, new_rule: CfRuleInput, ) -> Result<(), String>

Replaces the range and rule of the CF entry at index on sheet.

pub fn raise_conditional_formatting_priority( &mut self, sheet: u32, index: u32, ) -> Result<(), String>

Raises the priority of the CF rule at index on sheet by swapping its priority with the next-higher-priority rule. No-op if it is already the highest-priority rule.

pub fn lower_conditional_formatting_priority( &mut self, sheet: u32, index: u32, ) -> Result<(), String>

Lowers the priority of the CF rule at index on sheet by swapping its priority with the next-lower-priority rule. No-op if it is already the lowest-priority rule.

impl<'a> UserModel<'a>

pub fn get_named_style_list(&self) -> Vec<String>

Returns the list of all named style names.

pub fn get_named_style(&self, name: &str) -> Result<Style, String>

Returns the Style associated with the named style.

pub fn create_named_style( &mut self, name: &str, style: &Style, includes: StyleIncludes, ) -> Result<(), String>

Creates a new named style. includes selects which formatting categories the style carries (Excel’s “Style Includes” checkboxes); use StyleIncludes::default() for a full style. Fails if a style with that name already exists.

pub fn delete_named_style(&mut self, name: &str) -> Result<(), String>

Deletes a named style. Fails if the style does not exist or is built-in. Cells that used this style keep their formatting.

pub fn update_named_style( &mut self, name: &str, new_name: &str, style: &Style, includes: StyleIncludes, ) -> Result<(), String>

Updates the formatting, the included categories and optionally the name of a named style. All cells, rows, and columns using the style pick up the new formatting. Fails if the style does not exist, is built-in, or if new_name is already taken.

pub fn get_named_style_includes( &self, name: &str, ) -> Result<StyleIncludes, String>

Returns which formatting categories the named style includes.

pub fn get_builtin_named_styles(&self) -> Vec<(String, Style)>

Returns all Excel built-in named styles as (name, Style) pairs. These are static definitions that are not stored in the workbook until a user applies one.

pub fn on_apply_named_style(&mut self, name: &str) -> Result<(), String>

Applies a named style (custom or built-in) to the current selection.

If the style is not in the model but is a known built-in, it is first added to the model’s style table, then applied to every cell in the selection with undo support.

impl<'a> UserModel<'a>

pub fn get_selected_sheet(&self) -> u32

Returns the selected sheet index

pub fn get_selected_cell(&self) -> (u32, i32, i32)

Returns the selected cell

pub fn get_selected_view(&self) -> SelectedView

Returns selected view

pub fn set_selected_sheet(&mut self, sheet: u32) -> Result<(), String>

Sets the the selected sheet

pub fn set_selected_cell(&mut self, row: i32, column: i32) -> Result<(), String>

Sets the selected cell for the current view. Note that this also sets the selected range

pub fn set_selected_range( &mut self, start_row: i32, start_column: i32, end_row: i32, end_column: i32, ) -> Result<(), String>

Sets the selected range. Note that the selected cell must be in the selected range.

pub fn on_expand_selected_range(&mut self, key: &str) -> Result<(), String>

The selected range is expanded with the keyboard

pub fn set_top_left_visible_cell( &mut self, top_row: i32, left_column: i32, ) -> Result<(), String>

Sets the value of the first visible cell

pub fn set_window_width(&mut self, window_width: f64)

Sets the width of the window

pub fn get_window_width(&mut self) -> Result<i64, String>

Gets the width of the window

pub fn set_window_height(&mut self, window_height: f64)

Sets the height of the window

pub fn get_window_height(&mut self) -> Result<i64, String>

Gets the height of the window

pub fn on_arrow_right(&mut self) -> Result<(), String>

User presses right arrow

pub fn on_arrow_left(&mut self) -> Result<(), String>

User presses left arrow

pub fn on_arrow_up(&mut self) -> Result<(), String>

User presses up arrow key

pub fn on_arrow_down(&mut self) -> Result<(), String>

User presses down arrow key

pub fn get_scroll_x(&self) -> Result<f64, String>

Returns the x-coordinate of the cell in the top left corner

pub fn get_scroll_y(&self) -> Result<f64, String>

Returns the y-coordinate of the cell in the top left corner

pub fn on_page_down(&mut self) -> Result<(), String>

User presses page down. The top_row is now the first row that is not fully visible

pub fn on_page_up(&mut self) -> Result<(), String>

On page up. tis needs to be the inverse of page down

pub fn on_area_selecting( &mut self, target_row: i32, target_column: i32, ) -> Result<(), String>

We extend the selection to cell (target_row, target_column)

pub fn on_navigate_to_edge_in_direction( &mut self, direction: NavigationDirection, ) -> Result<(), String>

User navigates to the edge in the given direction

Trait Implementations

impl<'a> Debug for UserModel<'a>

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

Formats the value using the given formatter.