Modal Modes

examples/ide_completions_with_modal.rs

@@ -0,0 +1,137 @@
+// Create a reedline object with tab completions support and modal modes
+// cargo run --example completions
+//
+// "t" [Tab] will allow you to select the completions "test" and "this is the reedline crate"
+// [Enter] to select the chosen alternative
+
+use reedline::{
+    default_emacs_keybindings, DefaultCompleter, DefaultPrompt, DescriptionMode, EditCommand,
+    Emacs, IdeMenu, KeyCode, KeyModifiers, Keybindings, MenuBuilder, Reedline, ReedlineEvent,
+    ReedlineMenu, Signal,
+};
+use std::io;
+
+fn add_menu_keybindings(keybindings: &mut Keybindings) {
+    keybindings.add_binding(
+        KeyModifiers::NONE,
+        KeyCode::Tab,
+        ReedlineEvent::UntilFound(vec![
+            ReedlineEvent::Menu("completion_menu".to_string()),
+            ReedlineEvent::MenuNext,
+        ]),
+    );
+    keybindings.add_binding(
+        KeyModifiers::ALT,
+        KeyCode::Enter,
+        ReedlineEvent::Edit(vec![EditCommand::InsertNewline]),
+    );
+    keybindings.add_binding(
+        KeyModifiers::ALT,
+        KeyCode::Char('f'),
+        ReedlineEvent::Multiple(vec![ReedlineEvent::ForceDeactivate, ReedlineEvent::Enter]),
+    );
+}
+
+fn main() -> io::Result<()> {
+    // Min width of the completion box, including the border
+    let min_completion_width: u16 = 0;
+    // Max width of the completion box, including the border
+    let max_completion_width: u16 = 50;
+    // Max height of the completion box, including the border
+    let max_completion_height: u16 = u16::MAX;
+    // Padding inside of the completion box (on the left and right side)
+    let padding: u16 = 0;
+    // Whether to draw the default border around the completion box
+    let border: bool = false;
+    // Offset of the cursor from the top left corner of the completion box
+    // By default the top left corner is below the cursor
+    let cursor_offset: i16 = 0;
+    // How the description should be aligned
+    let description_mode: DescriptionMode = DescriptionMode::PreferRight;
+    // Min width of the description box, including the border
+    let min_description_width: u16 = 0;
+    // Max width of the description box, including the border
+    let max_description_width: u16 = 50;
+    // Distance between the completion and the description box
+    let description_offset: u16 = 1;
+    // If true, the cursor pos will be corrected, so the suggestions match up with the typed text
+    // ```text
+    // C:\> str
+    //      str join
+    //      str trim
+    //      str split
+    // ```
+    // If a border is being used
+    let correct_cursor_pos: bool = false;
+
+    let commands = vec![
+        "test".into(),
+        "clear".into(),
+        "exit".into(),
+        "history 1".into(),
+        "history 2".into(),
+        "logout".into(),
+        "login".into(),
+        "hello world".into(),
+        "hello world reedline".into(),
+        "hello world something".into(),
+        "hello world another".into(),
+        "hello world 1".into(),
+        "hello world 2".into(),
+        "hello another very large option for hello word that will force one column".into(),
+        "this is the reedline crate".into(),
+        "abaaabas".into(),
+        "abaaacas".into(),
+        "ababac".into(),
+        "abacaxyc".into(),
+        "abadarabc".into(),
+    ];
+
+    let completer = Box::new(DefaultCompleter::new_with_wordlen(commands, 2));
+
+    // Use the interactive menu to select options from the completer
+    let mut ide_menu = IdeMenu::default()
+        .with_name("completion_menu")
+        .with_min_completion_width(min_completion_width)
+        .with_max_completion_width(max_completion_width)
+        .with_max_completion_height(max_completion_height)
+        .with_padding(padding)
+        .with_cursor_offset(cursor_offset)
+        .with_description_mode(description_mode)
+        .with_min_description_width(min_description_width)
+        .with_max_description_width(max_description_width)
+        .with_description_offset(description_offset)
+        .with_correct_cursor_pos(correct_cursor_pos);
+
+    if border {
+        ide_menu = ide_menu.with_default_border();
+    }
+
+    let completion_menu = Box::new(ide_menu);
+
+    let mut keybindings = default_emacs_keybindings();
+    add_menu_keybindings(&mut keybindings);
+
+    let edit_mode = Box::new(Emacs::new(keybindings));
+
+    let mut line_editor = Reedline::create()
+        .with_completer(completer)
+        .with_menu(ReedlineMenu::EngineCompleter(completion_menu))
+        .with_edit_mode(edit_mode)
+        .with_modal_mode(true);
+
+    let prompt = DefaultPrompt::default();
+
+    loop {
+        let sig = line_editor.read_line(&prompt)?;
+        match sig {
+            Signal::Success(buffer) => {
+                println!("We processed: {buffer}");
+            }
+            Signal::CtrlD | Signal::CtrlC => {
+                println!("\nAborted!");
+                break Ok(());
+            }
+        }
+    }
+}

src/engine.rs

@@ -113,6 +113,8 @@ pub struct Reedline {
     history_cursor_on_excluded: bool,
     input_mode: InputMode,
 
+    modal_mode: bool,
+
     // State of the painter after a `ReedlineEvent::ExecuteHostCommand` was requested, used after
     // execution to decide if we can re-use the previous prompt or paint a new one.
     suspended_state: Option<PainterSuspendedState>,
@@ -219,6 +221,7 @@ impl Reedline {
             history_excluded_item: None,
             history_cursor_on_excluded: false,
             input_mode: InputMode::Regular,
+            modal_mode: false,
             suspended_state: None,
             painter,
             transient_prompt: None,
@@ -537,6 +540,12 @@ impl Reedline {
         self
     }
 
+    /// A builder which configures the modal mode for your instance of the Reedline engine
+    pub fn with_modal_mode(mut self, modal: bool) -> Self {
+        self.modal_mode = modal;
+        self
+    }
+
     /// A builder that enables reedline changing the cursor shape based on the current edit mode.
     /// The current implementation sets the cursor shape when drawing the prompt.
     /// Do not use this if the cursor shape is set elsewhere, e.g. in the terminal settings or by ansi escape sequences.
@@ -858,6 +867,7 @@ impl Reedline {
                 self.painter.clear_scrollback()?;
                 Ok(EventStatus::Handled)
             }
+            ReedlineEvent::ForceDeactivate => Ok(EventStatus::Handled), // Not sure what to do here
             ReedlineEvent::Enter
             | ReedlineEvent::HistoryHintComplete
             | ReedlineEvent::Submit
@@ -1093,13 +1103,24 @@ impl Reedline {
                 self.painter.clear_scrollback()?;
                 Ok(EventStatus::Handled)
             }
+            ReedlineEvent::ForceDeactivate => {
+                for menu in self.menus.iter_mut() {
+                    if menu.is_active() {
+                        menu.replace_in_buffer(&mut self.editor);
+                        menu.menu_event(MenuEvent::Deactivate(false));
+
+                        return Ok(EventStatus::Handled);
+                    }
+                }
+                Ok(EventStatus::Handled)
+            }
             ReedlineEvent::Enter | ReedlineEvent::Submit | ReedlineEvent::SubmitOrNewline
                 if self.menus.iter().any(|menu| menu.is_active()) =>
             {
                 for menu in self.menus.iter_mut() {
                     if menu.is_active() {
                         menu.replace_in_buffer(&mut self.editor);
-                        menu.menu_event(MenuEvent::Deactivate);
+                        menu.menu_event(MenuEvent::Deactivate(self.modal_mode));
 
                         return Ok(EventStatus::Handled);
                     }
@@ -1161,7 +1182,7 @@ impl Reedline {
                             Some(&EditCommand::Backspace)
                             | Some(&EditCommand::BackspaceWord)
                             | Some(&EditCommand::MoveToLineStart { select: false }) => {
-                                menu.menu_event(MenuEvent::Deactivate)
+                                menu.menu_event(MenuEvent::Deactivate(self.modal_mode))
                             }
                             _ => {
                                 menu.menu_event(MenuEvent::Edit(self.quick_completions));
@@ -1189,7 +1210,7 @@ impl Reedline {
                         }
                     }
                     if self.editor.line_buffer().get_buffer().is_empty() {
-                        menu.menu_event(MenuEvent::Deactivate);
+                        menu.menu_event(MenuEvent::Deactivate(self.modal_mode));
                     } else {
                         menu.menu_event(MenuEvent::Edit(self.quick_completions));
                     }
@@ -1279,7 +1300,7 @@ impl Reedline {
     fn deactivate_menus(&mut self) {
         self.menus
             .iter_mut()
-            .for_each(|menu| menu.menu_event(MenuEvent::Deactivate));
+            .for_each(|menu| menu.menu_event(MenuEvent::Deactivate(self.modal_mode)));
     }
 
     fn previous_history(&mut self) {

src/enums.rs

@@ -569,6 +569,9 @@ pub enum ReedlineEvent {
     /// Submit at the end of the *complete* text, otherwise newline
     SubmitOrNewline,
 
+    /// Force deactivate - used for modal menus
+    ForceDeactivate,
+
     /// Esc event
     Esc,
 
@@ -659,6 +662,7 @@ impl Display for ReedlineEvent {
             ReedlineEvent::Enter => write!(f, "Enter"),
             ReedlineEvent::Submit => write!(f, "Submit"),
             ReedlineEvent::SubmitOrNewline => write!(f, "SubmitOrNewline"),
+            ReedlineEvent::ForceDeactivate => write!(f, "ForceDeactivate"),
             ReedlineEvent::Esc => write!(f, "Esc"),
             ReedlineEvent::Mouse => write!(f, "Mouse"),
             ReedlineEvent::Resize(_, _) => write!(f, "Resize <int> <int>"),

src/menu/columnar_menu.rs

@@ -475,9 +475,11 @@ impl Menu for ColumnarMenu {
     fn menu_event(&mut self, event: MenuEvent) {
         match &event {
             MenuEvent::Activate(_) => self.active = true,
-            MenuEvent::Deactivate => {
-                self.active = false;
-                self.input = None;
+            MenuEvent::Deactivate(modal_mode) => {
+                if !modal_mode {
+                    self.active = false;
+                    self.input = None;
+                }
             }
             _ => {}
         }
@@ -530,7 +532,11 @@ impl Menu for ColumnarMenu {
                         self.update_values(editor, completer);
                     }
                 }
-                MenuEvent::Deactivate => self.active = false,
+                MenuEvent::Deactivate(modal_mode) => {
+                    if !modal_mode {
+                        self.active = false;
+                    }
+                }
                 MenuEvent::Edit(updated) => {
                     self.reset_position();
 

src/menu/description_menu.rs

@@ -429,10 +429,12 @@ impl Menu for DescriptionMenu {
     fn menu_event(&mut self, event: MenuEvent) {
         match &event {
             MenuEvent::Activate(_) => self.active = true,
-            MenuEvent::Deactivate => {
-                self.active = false;
-                self.input = None;
-                self.values = Vec::new();
+            MenuEvent::Deactivate(modal_mode) => {
+                if !modal_mode {
+                    self.active = false;
+                    self.input = None;
+                    self.values = Vec::new();
+                }
             }
             _ => {}
         };
@@ -468,7 +470,11 @@ impl Menu for DescriptionMenu {
                     self.input = Some(editor.get_buffer().to_string());
                     self.update_values(editor, completer);
                 }
-                MenuEvent::Deactivate => self.active = false,
+                MenuEvent::Deactivate(modal_mode) => {
+                    if !modal_mode {
+                        self.active = false;
+                    }
+                }
                 MenuEvent::Edit(_) => {
                     self.reset_position();
                     self.update_values(editor, completer);

src/menu/ide_menu.rs

@@ -617,9 +617,11 @@ impl Menu for IdeMenu {
     fn menu_event(&mut self, event: MenuEvent) {
         match &event {
             MenuEvent::Activate(_) => self.active = true,
-            MenuEvent::Deactivate => {
-                self.active = false;
-                self.input = None;
+            MenuEvent::Deactivate(modal_mode) => {
+                if !modal_mode {
+                    self.active = false;
+                    self.input = None;
+                }
             }
             _ => {}
         }
@@ -671,7 +673,11 @@ impl Menu for IdeMenu {
                         self.update_values(editor, completer);
                     }
                 }
-                MenuEvent::Deactivate => self.active = false,
+                MenuEvent::Deactivate(modal_mode) => {
+                    if !modal_mode {
+                        self.active = false;
+                    }
+                }
                 MenuEvent::Edit(updated) => {
                     self.reset_position();
 

src/menu/list_menu.rs

@@ -334,9 +334,11 @@ impl Menu for ListMenu {
     fn menu_event(&mut self, event: MenuEvent) {
         match &event {
             MenuEvent::Activate(_) => self.active = true,
-            MenuEvent::Deactivate => {
-                self.active = false;
-                self.input = None;
+            MenuEvent::Deactivate(modal_mode) => {
+                if !modal_mode {
+                    self.active = false;
+                    self.input = None;
+                }
             }
             _ => {}
         }
@@ -435,9 +437,11 @@ impl Menu for ListMenu {
                         full: false,
                     });
                 }
-                MenuEvent::Deactivate => {
-                    self.active = false;
-                    self.input = None;
+                MenuEvent::Deactivate(modal_mode) => {
+                    if !modal_mode {
+                        self.active = false;
+                        self.input = None;
+                    }
                 }
                 MenuEvent::Edit(_) => {
                     self.update_values(editor, completer);

src/menu/mod.rs

@@ -49,7 +49,7 @@ pub enum MenuEvent {
     /// have already being updated. This is true when the option `quick_completions` is true
     Activate(bool),
     /// Deactivation event
-    Deactivate,
+    Deactivate(bool),
     /// Line buffer edit event. When the bool is true it means that the values
     /// have already being updated. This is true when the option `quick_completions` is true
     Edit(bool),