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::buffer::Buffer;
14use ratatui::layout::{Constraint, Rect};
15use ratatui::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 rowss 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
208use crate::_private::NonExhaustive;
209
210pub use table::{handle_doubleclick_events, Table, TableState, TableStyle};
211
212/// Different selection models for Table.
213pub mod selection {
214    pub use crate::cellselection::CellSelection;
215    pub mod cellselection {
216        pub use crate::cellselection::{handle_events, handle_mouse_events};
217    }
218    pub use crate::noselection::NoSelection;
219    pub mod noselection {
220        pub use crate::noselection::{handle_events, handle_mouse_events};
221    }
222    pub use crate::rowselection::RowSelection;
223    pub mod rowselection {
224        pub use crate::rowselection::{handle_events, handle_mouse_events};
225    }
226    pub use crate::rowsetselection::RowSetSelection;
227    pub mod rowsetselection {
228        pub use crate::rowsetselection::{handle_events, handle_mouse_events};
229    }
230}
231
232/// Eventhandling.
233pub mod event {
234    pub use rat_event::*;
235
236    /// Result value for event-handling.
237    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
238    #[non_exhaustive]
239    pub enum TableOutcome {
240        /// The given event was not handled at all.
241        Continue,
242        /// The event was handled, no repaint necessary.
243        Unchanged,
244        /// The event was handled, repaint necessary.
245        Changed,
246        /// The selection has changed.
247        Selected,
248    }
249
250    impl ConsumedEvent for TableOutcome {
251        fn is_consumed(&self) -> bool {
252            *self != TableOutcome::Continue
253        }
254    }
255
256    impl From<TableOutcome> for Outcome {
257        fn from(value: TableOutcome) -> Self {
258            match value {
259                TableOutcome::Continue => Outcome::Continue,
260                TableOutcome::Unchanged => Outcome::Unchanged,
261                TableOutcome::Changed => Outcome::Changed,
262                TableOutcome::Selected => Outcome::Changed,
263            }
264        }
265    }
266
267    /// Result type for double-click event-handling.
268    #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
269    pub enum DoubleClickOutcome {
270        /// The given event has not been used at all.
271        Continue,
272        /// The event has been recognized, but the result was nil.
273        /// Further processing for this event may stop.
274        Unchanged,
275        /// The event has been recognized and there is some change
276        /// due to it.
277        /// Further processing for this event may stop.
278        /// Rendering the ui is advised.
279        Changed,
280        /// Double click occurred. Contains (column, row)
281        ClickClick(usize, usize),
282    }
283
284    impl From<DoubleClickOutcome> for Outcome {
285        fn from(value: DoubleClickOutcome) -> Self {
286            match value {
287                DoubleClickOutcome::Continue => Outcome::Continue,
288                DoubleClickOutcome::Unchanged => Outcome::Unchanged,
289                DoubleClickOutcome::Changed => Outcome::Changed,
290                DoubleClickOutcome::ClickClick(_, _) => Outcome::Changed,
291            }
292        }
293    }
294
295    impl From<Outcome> for DoubleClickOutcome {
296        fn from(value: Outcome) -> Self {
297            match value {
298                Outcome::Continue => DoubleClickOutcome::Continue,
299                Outcome::Unchanged => DoubleClickOutcome::Unchanged,
300                Outcome::Changed => DoubleClickOutcome::Changed,
301            }
302        }
303    }
304
305    impl ConsumedEvent for DoubleClickOutcome {
306        fn is_consumed(&self) -> bool {
307            !matches!(self, DoubleClickOutcome::Continue)
308        }
309    }
310
311    /// Result type for the [edit](crate::edit) widgets.
312    #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
313    pub enum EditOutcome {
314        /// The given event has not been used at all.
315        Continue,
316        /// The event has been recognized, but the result was nil.
317        /// Further processing for this event may stop.
318        Unchanged,
319        /// The event has been recognized and there is some change
320        /// due to it.
321        /// Further processing for this event may stop.
322        /// Rendering the ui is advised.
323        Changed,
324        /// Cancel an ongoing edit.
325        Cancel,
326        /// Commit the current edit.
327        Commit,
328        /// Commit the edit, append a new line.
329        CommitAndAppend,
330        /// Commit the edit, edit next line.
331        CommitAndEdit,
332        /// Insert an item at the selection.
333        Insert,
334        /// Remove the item at the selection.
335        Remove,
336        /// Edit the item at the selection.
337        Edit,
338        /// Append an item after last row.
339        /// Might want to start the edit too.
340        Append,
341    }
342
343    impl From<Outcome> for EditOutcome {
344        fn from(value: Outcome) -> Self {
345            match value {
346                Outcome::Continue => EditOutcome::Continue,
347                Outcome::Unchanged => EditOutcome::Unchanged,
348                Outcome::Changed => EditOutcome::Changed,
349            }
350        }
351    }
352
353    impl From<EditOutcome> for Outcome {
354        fn from(value: EditOutcome) -> Self {
355            match value {
356                EditOutcome::Continue => Outcome::Continue,
357                EditOutcome::Unchanged => Outcome::Unchanged,
358                EditOutcome::Changed => Outcome::Changed,
359                EditOutcome::Insert => Outcome::Unchanged,
360                EditOutcome::Remove => Outcome::Unchanged,
361                EditOutcome::Edit => Outcome::Unchanged,
362                EditOutcome::Append => Outcome::Unchanged,
363                EditOutcome::Cancel => Outcome::Unchanged,
364                EditOutcome::Commit => Outcome::Unchanged,
365                EditOutcome::CommitAndAppend => Outcome::Unchanged,
366                EditOutcome::CommitAndEdit => Outcome::Unchanged,
367            }
368        }
369    }
370
371    impl ConsumedEvent for EditOutcome {
372        fn is_consumed(&self) -> bool {
373            !matches!(self, EditOutcome::Continue)
374        }
375    }
376}
377
378mod _private {
379    #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
380    pub struct NonExhaustive;
381}
rat_ftable/lib.rs

rat_ftable/
lib.rs
