rat_ftable/
lib.rs

1#![doc = include_str!("../readme.md")]
2
3mod cellselection;
4pub mod edit;
5mod noselection;
6mod rowselection;
7mod rowsetselection;
8mod table;
9pub mod textdata;
10mod util;
11
12use crate::textdata::Row;
13use ratatui_core::buffer::Buffer;
14use ratatui_core::layout::{Constraint, Rect};
15use ratatui_core::style::Style;
16
17/// Render-context for rendering a table-cell.
18#[derive(Debug)]
19pub struct TableContext {
20    /// Focus flag is set.
21    pub focus: bool,
22
23    /// Cell is selected.
24    pub selected_cell: bool,
25    /// Row of the cell is selected.
26    pub selected_row: bool,
27    /// Column of the cell is selected.
28    pub selected_column: bool,
29
30    /// Base style
31    pub style: Style,
32    /// Row style if any.
33    pub row_style: Option<Style>,
34    /// Selection style if any.
35    pub select_style: Option<Style>,
36
37    /// Spacing after the cell. It's guaranteed that this
38    /// is writeable in the buffer given to render_cell.
39    pub space_area: Rect,
40    /// Total area for the current row.
41    pub row_area: Rect,
42
43    /// Construct with `..Default::default()`
44    pub non_exhaustive: NonExhaustive,
45}
46
47///
48/// Trait for accessing the table-data by the Table.
49///
50/// This trait is suitable if the underlying data is some sort
51/// of vec/slice.
52pub trait TableData<'a> {
53    /// Size of the data.
54    fn rows(&self) -> usize;
55
56    /// Header can be obtained from here.
57    /// Alternative to setting on Table.
58    fn header(&self) -> Option<Row<'a>> {
59        None
60    }
61
62    /// Footer can be obtained from here.
63    /// Alternative to setting on Table.
64    fn footer(&self) -> Option<Row<'a>> {
65        None
66    }
67
68    /// Row height.
69    #[allow(unused_variables)]
70    fn row_height(&self, row: usize) -> u16 {
71        1
72    }
73
74    /// Row style.
75    #[allow(unused_variables)]
76    fn row_style(&self, row: usize) -> Option<Style> {
77        None
78    }
79
80    /// Column constraints.
81    fn widths(&self) -> Vec<Constraint> {
82        Vec::default()
83    }
84
85    /// Render the cell given by column/row.
86    /// * ctx - a lot of context data.
87    fn render_cell(
88        &self,
89        ctx: &TableContext,
90        column: usize,
91        row: usize,
92        area: Rect,
93        buf: &mut Buffer,
94    );
95}
96
97impl<'a> TableData<'a> for Box<dyn TableData<'a> + 'a> {
98    fn rows(&self) -> usize {
99        (**self).rows()
100    }
101
102    fn header(&self) -> Option<Row<'a>> {
103        (**self).header()
104    }
105
106    fn footer(&self) -> Option<Row<'a>> {
107        (**self).footer()
108    }
109
110    fn row_height(&self, row: usize) -> u16 {
111        (**self).row_height(row)
112    }
113
114    fn row_style(&self, row: usize) -> Option<Style> {
115        (**self).row_style(row)
116    }
117
118    fn widths(&self) -> Vec<Constraint> {
119        (**self).widths()
120    }
121
122    fn render_cell(
123        &self,
124        ctx: &TableContext,
125        column: usize,
126        row: usize,
127        area: Rect,
128        buf: &mut Buffer,
129    ) {
130        (**self).render_cell(ctx, column, row, area, buf)
131    }
132}
133
134/// Trait for accessing the table-data by the Table.
135///
136/// This trait is suitable if the underlying data is an iterator.
137pub trait TableDataIter<'a> {
138    /// StatefulWidgetRef needs a clone of the iterator for every render.
139    /// For StatefulWidget this is not needed at all. So this defaults to
140    /// None and warns at runtime.
141    fn cloned(&self) -> Option<Box<dyn TableDataIter<'a> + 'a>> {
142        None
143    }
144
145    /// Returns the number of rows, if known.
146    ///
147    /// If they are not known, all items will be iterated to
148    /// calculate things as the length of the table. Which will
149    /// be slower if you have many items.
150    ///
151    /// See [Table::no_row_count]
152    fn rows(&self) -> Option<usize>;
153
154    /// Header can be obtained from here.
155    /// Alternative to setting on Table.
156    fn header(&self) -> Option<Row<'a>> {
157        None
158    }
159
160    /// Footer can be obtained from here.
161    /// Alternative to setting on Table.
162    fn footer(&self) -> Option<Row<'a>> {
163        None
164    }
165
166    /// Skips to the nth item, returns true if such an item exists.
167    /// nth(0) == next()
168    fn nth(&mut self, n: usize) -> bool;
169
170    /// Row height for the current item.
171    fn row_height(&self) -> u16 {
172        1
173    }
174
175    /// Row style for the current line.
176    fn row_style(&self) -> Option<Style> {
177        None
178    }
179
180    /// Column constraints.
181    fn widths(&self) -> Vec<Constraint> {
182        Vec::default()
183    }
184
185    /// Render the cell for the current line.
186    /// * ctx - a lot of context data.
187    fn render_cell(&self, ctx: &TableContext, column: usize, area: Rect, buf: &mut Buffer);
188}
189
190/// Trait for the different selection models used by Table.
191pub trait TableSelection {
192    /// Number of rows selected.
193    fn count(&self) -> usize;
194
195    /// Row is selected. This can be separate from `is_selected_cell`.
196    fn is_selected_row(&self, row: usize) -> bool;
197
198    /// Column is selected. This can be separate from `is_selected_cell`.
199    fn is_selected_column(&self, column: usize) -> bool;
200
201    /// Specific cell is selected.
202    fn is_selected_cell(&self, column: usize, row: usize) -> bool;
203
204    /// Selection lead, or the sole selected index.
205    fn lead_selection(&self) -> Option<(usize, usize)>;
206
207    /// Validate the selected row against the number of rows.
208    #[allow(unused_variables)]
209    fn validate_rows(&mut self, rows: usize) {}
210
211    /// Validate the selected column against the number of columns.
212    #[allow(unused_variables)]
213    fn validate_cols(&mut self, cols: usize) {}
214
215    /// Correct the selection for added items.
216    #[allow(unused_variables)]
217    fn items_added(&mut self, pos: usize, n: usize) {}
218
219    /// Correct the selection for removed items.
220    #[allow(unused_variables)]
221    fn items_removed(&mut self, pos: usize, n: usize, rows: usize) {}
222}
223
224use crate::_private::NonExhaustive;
225
226pub use table::{Table, TableState, TableStyle, handle_doubleclick_events};
227
228/// Different selection models for Table.
229pub mod selection {
230    pub use crate::cellselection::CellSelection;
231    pub mod cellselection {
232        pub use crate::cellselection::{handle_events, handle_mouse_events};
233    }
234    pub use crate::noselection::NoSelection;
235    pub mod noselection {
236        pub use crate::noselection::{handle_events, handle_mouse_events};
237    }
238    pub use crate::rowselection::RowSelection;
239    pub mod rowselection {
240        pub use crate::rowselection::{handle_events, handle_mouse_events};
241    }
242    pub use crate::rowsetselection::RowSetSelection;
243    pub mod rowsetselection {
244        pub use crate::rowsetselection::{handle_events, handle_mouse_events};
245    }
246}
247
248/// Eventhandling.
249pub mod event {
250    pub use rat_event::*;
251
252    /// Result value for event-handling.
253    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
254    #[non_exhaustive]
255    pub enum TableOutcome {
256        /// The given event was not handled at all.
257        Continue,
258        /// The event was handled, no repaint necessary.
259        Unchanged,
260        /// The event was handled, repaint necessary.
261        Changed,
262        /// The selection has changed.
263        Selected,
264    }
265
266    impl ConsumedEvent for TableOutcome {
267        fn is_consumed(&self) -> bool {
268            *self != TableOutcome::Continue
269        }
270    }
271
272    impl From<TableOutcome> for Outcome {
273        fn from(value: TableOutcome) -> Self {
274            match value {
275                TableOutcome::Continue => Outcome::Continue,
276                TableOutcome::Unchanged => Outcome::Unchanged,
277                TableOutcome::Changed => Outcome::Changed,
278                TableOutcome::Selected => Outcome::Changed,
279            }
280        }
281    }
282
283    /// Result type for double-click event-handling.
284    #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
285    pub enum DoubleClickOutcome {
286        /// The given event has not been used at all.
287        Continue,
288        /// The event has been recognized, but the result was nil.
289        /// Further processing for this event may stop.
290        Unchanged,
291        /// The event has been recognized and there is some change
292        /// due to it.
293        /// Further processing for this event may stop.
294        /// Rendering the ui is advised.
295        Changed,
296        /// Double click occurred. Contains (column, row)
297        ClickClick(usize, usize),
298    }
299
300    impl From<DoubleClickOutcome> for Outcome {
301        fn from(value: DoubleClickOutcome) -> Self {
302            match value {
303                DoubleClickOutcome::Continue => Outcome::Continue,
304                DoubleClickOutcome::Unchanged => Outcome::Unchanged,
305                DoubleClickOutcome::Changed => Outcome::Changed,
306                DoubleClickOutcome::ClickClick(_, _) => Outcome::Changed,
307            }
308        }
309    }
310
311    impl From<Outcome> for DoubleClickOutcome {
312        fn from(value: Outcome) -> Self {
313            match value {
314                Outcome::Continue => DoubleClickOutcome::Continue,
315                Outcome::Unchanged => DoubleClickOutcome::Unchanged,
316                Outcome::Changed => DoubleClickOutcome::Changed,
317            }
318        }
319    }
320
321    impl ConsumedEvent for DoubleClickOutcome {
322        fn is_consumed(&self) -> bool {
323            !matches!(self, DoubleClickOutcome::Continue)
324        }
325    }
326
327    /// Result type for the [edit](crate::edit) widgets.
328    #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
329    pub enum EditOutcome {
330        /// The given event has not been used at all.
331        Continue,
332        /// The event has been recognized, but the result was nil.
333        /// Further processing for this event may stop.
334        Unchanged,
335        /// The event has been recognized and there is some change
336        /// due to it.
337        /// Further processing for this event may stop.
338        /// Rendering the ui is advised.
339        Changed,
340        /// Cancel an ongoing edit.
341        Cancel,
342        /// Commit the current edit.
343        Commit,
344        /// Commit the edit, append a new line.
345        CommitAndAppend,
346        /// Commit the edit, edit next line.
347        CommitAndEdit,
348        /// Insert an item at the selection.
349        Insert,
350        /// Remove the item at the selection.
351        Remove,
352        /// Edit the item at the selection.
353        Edit,
354        /// Append an item after last row.
355        /// Might want to start the edit too.
356        Append,
357    }
358
359    impl From<Outcome> for EditOutcome {
360        fn from(value: Outcome) -> Self {
361            match value {
362                Outcome::Continue => EditOutcome::Continue,
363                Outcome::Unchanged => EditOutcome::Unchanged,
364                Outcome::Changed => EditOutcome::Changed,
365            }
366        }
367    }
368
369    impl From<EditOutcome> for Outcome {
370        fn from(value: EditOutcome) -> Self {
371            match value {
372                EditOutcome::Continue => Outcome::Continue,
373                EditOutcome::Unchanged => Outcome::Unchanged,
374                EditOutcome::Changed => Outcome::Changed,
375                EditOutcome::Insert => Outcome::Unchanged,
376                EditOutcome::Remove => Outcome::Unchanged,
377                EditOutcome::Edit => Outcome::Unchanged,
378                EditOutcome::Append => Outcome::Unchanged,
379                EditOutcome::Cancel => Outcome::Unchanged,
380                EditOutcome::Commit => Outcome::Unchanged,
381                EditOutcome::CommitAndAppend => Outcome::Unchanged,
382                EditOutcome::CommitAndEdit => Outcome::Unchanged,
383            }
384        }
385    }
386
387    impl ConsumedEvent for EditOutcome {
388        fn is_consumed(&self) -> bool {
389            !matches!(self, EditOutcome::Continue)
390        }
391    }
392}
393
394mod _private {
395    #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
396    pub struct NonExhaustive;
397}
rat_ftable/lib.rs

rat_ftable/
lib.rs
