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 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 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,

Functions related to selection of rows and columns

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 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.

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 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 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.

Important:

• This does not require calling recreate_rows to reflect changes.
• Should not be used when rows are frequently recreated, as data might be lost.
• 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();
/* modify rows */

});

pub fn recreate_rows(&mut self)

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

Performance:

• Should be used sparingly for large datasets as frequent calls can lead to performance issues.
• Consider calling after every X amount row updates, based on how frequently new rows are being added or use auto_scroll for automatic reload.

Example:

table.recreate_rows();

pub 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();