Struct SelectableTable

pub struct SelectableTable<Row, F, Conf>
where
    Row: Clone + Send + Sync,
    F: Eq + Hash + Clone + Ord + Send + Sync + Default + ColumnOperations<Row, F, Conf> + ColumnOrdering<Row>,
    Conf: Default,
{
    pub config: Conf,
    /* private fields */
}

A table structure that hold data for performing selection on drag, sorting, and displaying rows and more.

Type Parameters

• Row - The type representing each row in the table.
• F - A type used to identify columns, often an enum or field type.
• Conf - Configuration type for additional table settings passed by the user. This is made available anytime when creating or modifying rows

Fields

config: Conf

Additional Parameters passed by you, available when creating new rows or header. Can contain anything implementing the Default trait

Implementations

impl<Row, F, Conf> SelectableTable<Row, F, Conf>

where Row: Clone + Send + Sync, F: Eq + Hash + Clone + Ord + Send + Sync + Default + ColumnOperations<Row, F, Conf> + ColumnOrdering<Row>, Conf: Default,

Enables or configures auto-reloading behavior in the table view.

pub const fn auto_reload(self, count: u32) -> Self

Enable automatic row recreation in the UI after a specified number of modifications or new rows.

This function configures the table to automatically recreate its displayed rows when a certain number of new rows or row modifications have been made. Can be useful without having to manually keep track of modifications or when to reload.

Parameters:

• count: The number of updates (inserts or modifications) that will trigger an automatic row recreation.
  • If count is high, the table will refresh less frequently, leading to potentially outdated rows being shown in the UI for longer.
  • If count is too low, frequent row recreation may result in performance overhead.

Considerations:

• Tune the count value based on the expected rate of updates. For instance, if new rows or modifications occur at a rate of 1000 rows per second, a count between 500 and 1000 may offer the best balance between performance and up-to-date display.

Example:

let table = SelectableTable::new(vec![col1, col2, col3])
    .config(my_config).auto_reload(Some(500));

pub const fn set_auto_reload(&mut self, count: Option<u32>)

Manually set the auto-reload threshold. This lets you change the threshold dynamically.

Parameters:

• count: Optionally specify how many updates (new or modified rows) should occur before rows are automatically recreated.
  • If None is provided, auto-reloading is disabled.

Example:

table.set_auto_reload(Some(1000)); // Reload after 1000 updates.
table.set_auto_reload(None); // Disable auto-reloading.

impl<Row, F, Conf> SelectableTable<Row, F, Conf>

where Row: Clone + Send + Sync, F: Eq + Hash + Clone + Ord + Send + Sync + Default + ColumnOperations<Row, F, Conf> + ColumnOrdering<Row>, Conf: Default,

Enables or configures auto-scrolling behavior in the table view.

pub const fn auto_scroll(self) -> Self

Enables auto-scrolling when dragging near the edges of the view.

Returns:

An updated instance of the table with auto-scrolling enabled.

Example:

let table = SelectableTable::new(vec![col1, col2, col3]).auto_scroll()

pub const fn scroll_speed(self, speed: f32) -> Self

Sets the maximum scroll speed for auto-scrolling.

Parameters:

• speed: The maximum scroll speed (in pixels per frame) when auto-scrolling is active.

Returns:

An updated instance of the table with the new scroll speed.

Example:

let table = SelectableTable::new(vec![col1, col2, col3])
    .auto_scroll().scroll_speed(50.0);

pub const fn set_auto_scroll(self, scroll: AutoScroll) -> Self

Configures the auto-scrolling behavior by providing a new AutoScroll instance.

Parameters:

• scroll: A custom AutoScroll instance with defined scroll behavior.

Returns:

An updated instance of the table with the provided AutoScroll configuration.

Example:

let scroll_settings = AutoScroll::new(true).max_speed(50.0);
let table = SelectableTable::new(vec![col1, col2, col3])
    .set_auto_scroll(scroll_settings);

pub const fn update_auto_scroll(&mut self, scroll: AutoScroll)

Updates the table’s auto-scrolling settings with a new AutoScroll instance.

Parameters:

• scroll: The new AutoScroll settings to apply.

This method is used when you need to change the auto-scroll behavior at runtime.

Example:

let new_scroll_settings = AutoScroll::new(true).max_speed(60.0);
table.update_auto_scroll(new_scroll_settings); // Update the auto-scroll settings during runtime

impl<Row, F, Conf> SelectableTable<Row, F, Conf>

where Row: Clone + Send + Sync, F: Eq + Hash + Clone + Ord + Send + Sync + Default + ColumnOperations<Row, F, Conf> + ColumnOrdering<Row>, Conf: Default,

pub fn add_modify_row<Fn>(&mut self, table: Fn) -> Option<i64>

where Fn: FnOnce(&mut HashMap<i64, SelectableRow<Row, F>>) -> Option<Row>,

Modify or add rows to the table. Changes are not immediately reflected in the UI. You must call recreate_rows or recreate_rows_no_unselect to apply these changes visually.

Parameters:

• table: A closure that takes a mutable reference to the rows and optionally returns a new row. If a row is returned, it will be added to the table.

Auto Reload:

• Use auto_reload to automatically refresh the UI after a specified number of row modifications or additions.

Returns

• Option<i64> - The row id that is used internally for the new row

Example:

let new_row_id = table.add_modify_row(|rows| {
    let my_row = rows.get_mut(row_id).unwrap();
    // modify your row as necessary

    let new_row = MyRow {
        // Define your row values
    };
    Some(new_row) // Optionally add a new row
});

pub fn modify_shown_row<Fn>(&mut self, rows: Fn)

where Fn: FnMut(&mut Vec<SelectableRow<Row, F>>, &HashMap<i64, usize>),

Modify only the rows currently displayed in the UI.

This provides direct access to the currently formatted rows for lightweight updates.

Important:

• This does not require calling recreate_rows to reflect changes in the UI.
• Do not delete rows from inside this closure — doing so will cause a panic and break internal assumptions. To safely delete a row, use add_modify_row and then call recreate_rows or recreate_rows_no_unselect.
• Can be used alongside add_modify_row to show updated data immediately. When row recreation happens, the modified data will be preserved as long as it’s updated via add_modify_row.
• Does not contribute toward auto_reload count.

Parameters:

• table: A closure that takes a mutable reference to the currently formatted rows and an index map.

Example:

table.modify_shown_row(|formatted_rows, indexed_ids| {
    let row_id = 0;
    let target_index = indexed_ids.get(&row_id).unwrap();
    let row = formatted_rows.get_mut(*target_index).unwrap();
    // Safely modify row contents here
});

pub fn add_unsorted_row(&mut self, row: Row) -> SelectableRow<Row, F>

Adds a new row to the bottom of the table without applying any sorting logic.

This method inserts the row as-is at the end of the table, assigns it a unique ID, and returns it as a SelectableRow. This does not require calling recreate_rows for the row to appear in the UI.

Parameters:

• row: The data to insert into the table.

Returns:

• SelectableRow<Row, F>: The newly added row wrapped in a SelectableRow.

Example:

let row = Row::new(vec![cell1, cell2, cell3]);
let added_row = table.add_unsorted_row(row);

impl<Row, F, Conf> SelectableTable<Row, F, Conf>

where Row: Clone + Send + Sync, F: Eq + Hash + Clone + Ord + Send + Sync + Default + ColumnOperations<Row, F, Conf> + ColumnOrdering<Row>, Conf: Default,

Functions related to selection of rows and columns

pub fn mark_row_as_selected(&mut self, id: i64, column: Option<Vec<F>>)

Marks a row as selected, optionally selecting specific columns within the row.

If a list of columns is provided, only those columns are marked as selected for the row. If no column list is provided, all columns in the row are marked as selected.

Parameters:

• id: The unique identifier of the row to mark as selected.
• column: An optional list of columns (Vec<F>) to mark as selected within the row. If None, all columns are selected.

Example:

table.mark_row_as_selected(42, Some(vec!["Name", "Age"]));
table.mark_row_as_selected(43, None); // Selects all columns in row 43

pub fn unselect_all(&mut self)

Unselects all currently selected rows and columns.

Clears the selection in both rows and columns, and resets internal tracking of active rows and columns. After this call, there will be no selected rows or columns in the table.

Panics:

This method will panic if the indexed ID or the corresponding row cannot be found.

Example:

table.unselect_all(); // Unselects everything in the table.

pub fn select_all(&mut self)

Selects all rows and columns in the table.

After calling this method, all rows will have all columns selected.

Example:

table.select_all(); // Selects all rows and columns.

pub fn get_selected_rows(&mut self) -> Vec<SelectableRow<Row, F>>

Retrieves the currently selected rows.

This method returns a vector of the rows that have one or more columns selected.

If the select_full_row flag is enabled, it will ensure that all columns are selected for each active row.

Returns:

A Vec of SelectableRow instances that are currently selected.

Example:

let selected_rows = table.get_selected_rows();

pub fn copy_selected_cells(&mut self, ui: &mut Ui)

Copies selected cells to the system clipboard in a tabular format.

This method copies only the selected cells from each row to the clipboard, and ensures that the column widths align for better readability when pasted into a text editor or spreadsheet.

Parameters:

• ui: The UI context used for clipboard interaction.

Example:

table.copy_selected_cells(&mut ui);

pub const fn select_full_row(self) -> Self

Enables the selection of full rows in the table.

After calling this method, selecting any column in a row will result in the entire row being selected.

Returns:

A new instance of the table with full row selection enabled.

Example:

let table = SelectableTable::new(vec![col1, col2, col3])
    .select_full_row();

pub const fn set_select_full_row(&mut self, status: bool)

Sets whether the table should select full rows when a column is selected.

Parameters:

• status: true to enable full row selection, false to disable it.

Example:

table.set_select_full_row(true); // Enable full row selection.

pub fn get_total_selected_rows(&mut self) -> usize

Returns the total number of currently selected rows.

Returns:

• usize: The number of selected rows.

Example:

let selected_count = table.get_total_selected_rows();
println!("{} rows selected", selected_count);

impl<Row, F, Conf> SelectableTable<Row, F, Conf>

where Row: Clone + Send + Sync, F: Eq + Hash + Clone + Ord + Send + Sync + Default + ColumnOperations<Row, F, Conf> + ColumnOrdering<Row>, Conf: Default,

pub fn new(columns: Vec<F>) -> Self

Creates a new SelectableTable with the provided columns in a specified order.

Parameters:

• columns: A Vec<F> representing the columns. Columns must be passed in the correct order (e.g., 1 to 10).

Returns:

• A new instance of SelectableTable.

Example:

let table = SelectableTable::new(vec![col1, col2, col3]);

pub fn set_config(&mut self, conf: Conf)

Updates the table’s configuration with the given conf.

Parameters:

• conf: The new configuration of type Conf, which is user-defined and allows passing data to help with row/table modification.

Example:

table.set_config(my_config);

pub fn config(self, conf: Conf) -> Self

Sets a configuration in a builder-style pattern.

Parameters:

• conf: A configuration of type Conf. The user can pass any data to help with row creation or modification.

Returns:

• The updated SelectableTable with the new configuration applied.

Example:

let table = SelectableTable::new(vec![col1, col2, col3]).config(my_config);

pub fn clear_all_rows(&mut self)

Clears all rows from the table, including the displayed ones

Example:

table.clear_all_rows();

pub fn show_ui<Fn>(&mut self, ui: &mut Ui, table_builder: Fn)

where Fn: FnOnce(TableBuilder<'_>) -> TableBuilder<'_>,

Displays the UI for the table and uses the provided TableBuilder for creating the table UI.

Parameters:

• ui: The UI context where the table will be rendered.
• table_builder: A closure that receives and modifies the TableBuilder.

Example:

table.show_ui(ui, |builder| builder.column(column1));

pub fn recreate_rows(&mut self)

Recreates the rows shown in the UI for the next frame load.

Important:

• Any direct modifications made using modify_shown_row will be cleared when this is called. To preserve changes, use add_modify_row to update row data instead.

Performance:

• Should be used sparingly for large datasets, as frequent calls can lead to performance issues.
• Consider calling after every X number of row updates, depending on update frequency, or use auto_reload for automatic reload.

Example:

table.recreate_rows();

pub fn recreate_rows_no_unselect(&mut self)

Recreates the rows shown in the UI for the next frame load.

This function refreshes the internal row state by clearing and re-sorting the rows similar to recreate_rows, but it preserves the currently selected rows and re-applies the active column selection to them.

Useful when the UI needs to be refreshed without resetting user interaction state.

Important:

• Any direct modifications made to formatted_rows using modify_shown_row will be cleared when this is called. To preserve changes, use add_modify_row to update row data instead.

Performance:

• Should be used sparingly for large datasets, as frequent calls can lead to performance issues.
• Consider calling after every X number of row updates, depending on update frequency, or use auto_reload for automatic reload.

Example:

table.recreate_rows_no_unselect();

pub const fn total_displayed_rows(&self) -> usize

Returns the total number of rows currently being displayed in the UI.

Returns:

• usize: The number of rows that are formatted and ready for display.

pub fn total_rows(&self) -> usize

Returns the total number of rows in the table (both displayed and non-displayed).

Returns:

• usize: The total number of rows stored in the table, regardless of whether they are being displayed or not.

pub const fn get_displayed_rows(&self) -> &Vec<SelectableRow<Row, F>>

Provides a reference to the rows currently being displayed in the UI.

Returns:

• &Vec<SelectableRow<Row, F>>: A reference to the vector of formatted rows ready for display.

pub const fn get_all_rows(&self) -> &HashMap<i64, SelectableRow<Row, F>>

Provides a reference to all rows in the table, regardless of whether they are displayed.

Returns:

• &HashMap<i64, SelectableRow<Row, F>>: A reference to the entire collection of rows in the table.

pub const fn serial_column(self) -> Self

Adds a serial column to the table.

The serial column is automatically generated and displayed at the very left of the table. It shows the row number (starting from 1) for each row.

Returns:

• Self: The modified table with the serial column enabled.

Example:

let table = SelectableTable::new(vec![col1, col2, col3])
    .config(my_config).serial_column();

pub const fn horizontal_scroll(self) -> Self

Add a horizontal scrollbar to the table

Returns:

• Self: The modified table with the serial column enabled.

Example:

let table = SelectableTable::new(vec![col1, col2, col3])
    .horizontal_scroll();

pub const fn row_height(self, height: f32) -> Self

Sets the height rows in the table.

Parameters:

• height: The desired height for each row in logical points.

Returns:

• Self: The modified table with the specified row height applied.

Example:

let table = SelectableTable::new(vec![col1, col2, col3])
    .row_height(24.0);