[LLDB][GUI] Add initial searcher support

[OmarEmaraDev]

Summary

This patch adds a new type of reusable UI components. Searcher Windows
contain a text field to enter a search keyword and a list of scrollable
matches are presented. The target match can be selected and executed
which invokes a user callback to do something with the match.

This patch also adds one searcher delegate, which wraps the common
command completion searchers for simple use cases.

[OmarEmaraDev]

An example searcher window for source files:

[clayborg]

I like the look of this. It seems we would want this kind of auto complete in many fields that we already have, like the file or directory dialogs to start with.

My main question is do we need a full window for this, or can be paint a window that is just the search results? My thinking is that the right arrow key could be used to auto complete a text field if we are at the end of the input. If we have a file dialog and you type "~/" and then RIGHT arrow, it would be great if this window could appear right at the correct location and not look like a complete new window, but just a popup window that augments an existing Field (not necessarily a text field!) right below with minimal bordering so that it blends into the current form. You can select things using the up and down arrows, press enter to update the text, or keep typing to filter more.

Maybe we can:

• Maybe we add a "SearcherWindowDelegate *m_search_window;" member to FormDelegate so that this helper UI can appear when needed for any FieldDelegate that requests/needs it
  • "m_search_window" can be set to a non NULL value when one of the FieldDelegates in the FormDelegate asks for auto completion and provides a SearcherDelegate to use and a pointer to the FieldDelegate itself so that the SearcherWindowDelegate can be positioned correctly
  • If "m_search_window" is NULL, then never show this UI
  • If "m_search_window" is not NULL, then some keys get sent to the searcher delegate before or after the field gets them so it can do the choices UI
    • if the user hits ENTER, then the Field is asked to update its value via some API in FieldDelegate, and the GUI for the matches disappears and m_search_window is freed and set to NULL again

We should hook up at least one of the FieldDelegate objects so that it uses this functionality so we can play with it in this patch to make sure it works.

Let me know if you had other plans for this window and how it would be used.

lldb/source/Core/IOHandlerCursesGUI.cpp

3675

Should we be doing just like any other dialog that we have created and be constructing these items on the fly?

m_text_field = AddTextField("Search", "", true);

It seems the matches could use a modified ChoicesField for the matches? Are you currently drawing the choices (matches) manually?

3718

Seems like this could be done using a ChoicesField no instead of drawing manually?

3814

Is this a new text field itself, or designed to be a reference to an existing text field?

[OmarEmaraDev]

@clayborg I was planning on getting to field completion later as part of a global "context window" feature. There are reasons why I need this as a full separate window for now. Imminently, I am creating an operator that changes the file in the sources window so that breakpoints can be inserted manually. So once the user press Ctrl+F, a search window will appear where the user can choose a source file to navigate to. This will require a custom searcher, and not the common searcher implemented above, which I will add in a following patch. What do you think?

lldb/source/Core/IOHandlerCursesGUI.cpp

3675

AddTextField is part of form delegates, I don't think implementing this as a form is a good idea as they are functionally distinct.

I am drawing choices manually because the duplicated code is not really a lot and I like to be able to control the style of the drawing. But I guess we can reimplemented that using a choices field.

3814

A new instance of a text field.

[OmarEmaraDev]

lldb/source/Core/IOHandlerCursesGUI.cpp

3675

One thing to note is that text representation of matches are lazily computed in this window but not in the choices field, which gives an advantage. We can probably add support for lazy computation in the choice field, but it may not be worth it at the moment.

[clayborg]

In D108545#2962017, @OmarEmaraDev wrote:

@clayborg I was planning on getting to field completion later as part of a global "context window" feature. There are reasons why I need this as a full separate window for now. Imminently, I am creating an operator that changes the file in the sources window so that breakpoints can be inserted manually. So once the user press Ctrl+F, a search window will appear where the user can choose a source file to navigate to.

Pressing CTRL+F can and should bring up a dialog window right? The user will search for something, and finalize with some action. So this seems like perfect use for dialog windows and the fields and forms you have already created.

This will require a custom searcher, and not the common searcher implemented above, which I will add in a following patch. What do you think?

See comments above, but I do think this is a perfect usage for dialog windows:

• user presses CTRL+F and dialog comes up
  • user selects a file and presses OPT+ENTER to finalize the action and source view updates
  • user presses escape and dismisses the dialog

lldb/source/Core/IOHandlerCursesGUI.cpp

3675

But this does seem like the perfect use for a dialog window: user presses CTRL+F, dialog shows up and allows user to select something, and then press OPT+ENTER to update the source view. Is there a reason you think this should be a window and not a dialog?

If we re-use the ChoicesField, you can just update the choices with a delegate any time the choices should change and repaint the windows right?

3814

Yeah, the main questions is if this should be a FormDelegate or not. See other comments.

[OmarEmaraDev]

@clayborg I see a number of issues with using forms directly:

• The user will have to bother with form navigation. If we have a text field and a choice field, the user will have to switch between them using Tab and Shift+Tab in order to explore, rectify, and select a match. This is significantly more work then just typing without worry, selecting using arrow keys, and executing using enter.
• Not all users will use the OPT+Enter keys, it is likely that once the user sees a button that says "Select", the user will try to navigate to that button ignoring the tip in the windows border. Which is more work than just pressing enter.
• Updating the choices will require that we materialize all choices into text, this can work for the common completion searcher, but other searchers will require actual processing that might slow down the update process. The searcher window only materialize the match that it draws, so it can draw things much faster. We could update the choices field to accept a callback to compute its contents, but this will complicate the code, so it is worth considering if this is really needed.
• Practically all search dialogs work in a manner similar to the searcher window, like browser search bar, editor search dialogs, and the like. I don't recall seeing a search dialog that is implemented as a form.
• We want the ability to do custom styling. One thing I was considering is coloring the matched substring a different color, if we use a choice field, then we give up on custom styling.

[clayborg]

Ok, sounds like you have thought this through.

lldb/source/Core/IOHandlerCursesGUI.cpp

protected:
   FileFieldDelegate *m_standard_input_field;
   FileFieldDelegate *m_standard_output_field;
   FileFieldDelegate *m_standard_error_field;
 
   BooleanFieldDelegate *m_show_inherited_environment_field;
   EnvironmentVariableListFieldDelegate *m_inherited_environment_field;
 };
 
+////////////
+// Searchers
+////////////
+
+class SearcherDelegate {
+public:
+  SearcherDelegate() {}
+
+  virtual ~SearcherDelegate() = default;
+
+  virtual int GetNumberOfMatches() = 0;
+
+  // Get the string that will be displayed for the match at the input index.
+  virtual const std::string &GetMatchTextAtIndex(int index) = 0;
+
+  // Update the matches of the search. This is executed every time the text
+  // field handles an event.
+  virtual void UpdateMatches(const std::string &text) = 0;
+
+  // Execute the user callback given the index of some match. This is executed
+  // once the user selects a match.
+  virtual void ExecuteCallback(int match_index) = 0;
+};
+
+typedef std::shared_ptr<SearcherDelegate> SearcherDelegateSP;
+
+class SearcherWindowDelegate : public WindowDelegate {
+public:
+  SearcherWindowDelegate(SearcherDelegateSP &delegate_sp)
+      : m_delegate_sp(delegate_sp), m_text_field("Search", "", false),
+        m_selected_match(0), m_first_visible_match(0) {
+    ;
+  }
+
+  // A completion window is padded by one character from all sides. A text field
+  // is first drawn for inputting the searcher request, then a list of matches
+  // are displayed in a scrollable list.
+  //
+  // ___<Searcher Window Name>____________________________
+  // |                                                   |
+  // | __[Search]_______________________________________ |
+  // | |                                               | |
+  // | |_______________________________________________| |
+  // | - Match 1.                                        |
+  // | - Match 2.                                        |
+  // | - ...                                             |
+  // |                                                   |
+  // |____________________________[Press Esc to Cancel]__|
+  //
+
+  // Get the index of the last visible match. Assuming at least one match
+  // exists.
+  int GetLastVisibleMatch(int height) {
+    int index = m_first_visible_match + height;
+    return std::min(index, m_delegate_sp->GetNumberOfMatches()) - 1;
+  }
+
+  int GetNumberOfVisibleMatches(int height) {
+    return GetLastVisibleMatch(height) - m_first_visible_match + 1;
+  }
+
+  void UpdateScrolling(Surface &surface) {
+    if (m_selected_match < m_first_visible_match) {
+      m_first_visible_match = m_selected_match;
+      return;
+    }
+
+    int height = surface.GetHeight();
+    int last_visible_match = GetLastVisibleMatch(height);
+    if (m_selected_match > last_visible_match) {
+      m_first_visible_match = m_selected_match - height + 1;
+    }
+  }
+
+  void DrawMatches(Surface &surface) {
+    if (m_delegate_sp->GetNumberOfMatches() == 0)
+      return;
+
+    UpdateScrolling(surface);
+
+    int count = GetNumberOfVisibleMatches(surface.GetHeight());
+    for (int i = 0; i < count; i++) {
+      surface.MoveCursor(1, i);
+      int current_match = m_first_visible_match + i;
+      if (current_match == m_selected_match)
+        surface.AttributeOn(A_REVERSE);
+      surface.PutCString(
+          m_delegate_sp->GetMatchTextAtIndex(current_match).c_str());
+      if (current_match == m_selected_match)
+        surface.AttributeOff(A_REVERSE);
+    }
+  }
+
+  void DrawContent(Surface &surface) {
+    Rect content_bounds = surface.GetFrame();
+    Rect text_field_bounds, matchs_bounds;
+    content_bounds.HorizontalSplit(m_text_field.FieldDelegateGetHeight(),
+                                   text_field_bounds, matchs_bounds);
+    Surface text_field_surface = surface.SubSurface(text_field_bounds);
+    Surface matches_surface = surface.SubSurface(matchs_bounds);
+
+    m_text_field.FieldDelegateDraw(text_field_surface, true);
+    DrawMatches(matches_surface);
+  }
+
+  bool WindowDelegateDraw(Window &window, bool force) override {
+    window.Erase();
+
+    window.DrawTitleBox(window.GetName(), "Press Esc to Cancel");
+
+    Rect content_bounds = window.GetFrame();
+    content_bounds.Inset(2, 2);
+    Surface content_surface = window.SubSurface(content_bounds);
+
+    DrawContent(content_surface);
+    return true;
+  }
+
+  void SelectNext() {
+    if (m_selected_match != m_delegate_sp->GetNumberOfMatches() - 1)
+      m_selected_match++;
+    return;
+  }
+
+  void SelectPrevious() {
+    if (m_selected_match != 0)
+      m_selected_match--;
+    return;
+  }
+
+  void ExecuteCallback(Window &window) {
+    m_delegate_sp->ExecuteCallback(m_selected_match);
+    window.GetParent()->RemoveSubWindow(&window);
+  }
+
+  void UpdateMatches() {
+    m_delegate_sp->UpdateMatches(m_text_field.GetText());
+    m_selected_match = 0;
+  }
+
+  HandleCharResult WindowDelegateHandleChar(Window &window, int key) override {
+    switch (key) {
+    case '\r':
+    case '\n':
+    case KEY_ENTER:
+      ExecuteCallback(window);
+      return eKeyHandled;
+    case '\t':
+    case KEY_DOWN:
+      SelectNext();
+      return eKeyHandled;
+    case KEY_SHIFT_TAB:
+    case KEY_UP:
+      SelectPrevious();
+      return eKeyHandled;
+    case KEY_ESCAPE:
+      window.GetParent()->RemoveSubWindow(&window);
+      return eKeyHandled;
+    default:
+      break;
+    }
+
+    if (m_text_field.FieldDelegateHandleChar(key) == eKeyHandled)
+      UpdateMatches();
+
+    return eKeyHandled;
+  }
+
+protected:
+  SearcherDelegateSP m_delegate_sp;
+  TextFieldDelegate m_text_field;
+  // The index of the currently selected match.
+  int m_selected_match;
+  // The index of the first visible match.
+  int m_first_visible_match;
+};
+
+//////////////////////////////
+// Searcher Delegate Instances
+//////////////////////////////
+
+// This is a searcher delegate wrapper around CommandCompletions common
+// callbacks. The callbacks are only given the match string. The completion_mask
+// can be a combination of CommonCompletionTypes.
+class CommonCompletionSearcherDelegate : public SearcherDelegate {
+public:
+  typedef std::function<void(const std::string &)> CallbackType;
+
+  CommonCompletionSearcherDelegate(Debugger &debugger, uint32_t completion_mask,
+                                   CallbackType callback)
+      : m_debugger(debugger), m_completion_mask(completion_mask),
+        m_callback(callback) {}
+
+  int GetNumberOfMatches() override { return m_matches.GetSize(); }
+
+  const std::string &GetMatchTextAtIndex(int index) override {
+    return m_matches[index];
+  }
+
+  void UpdateMatches(const std::string &text) override {
+    CompletionResult result;
+    CompletionRequest request(text.c_str(), text.size(), result);
+    CommandCompletions::InvokeCommonCompletionCallbacks(
+        m_debugger.GetCommandInterpreter(), m_completion_mask, request,
+        nullptr);
+    result.GetMatches(m_matches);
+  }
+
+  void ExecuteCallback(int match_index) override {
+    m_callback(m_matches[match_index]);
+  }
+
+protected:
+  Debugger &m_debugger;
+  // A compound mask from CommonCompletionTypes.
+  uint32_t m_completion_mask;
+  // A callback to execute once the user selects a match. The match is passed to
+  // the callback as a string.
+  CallbackType m_callback;
+  StringList m_matches;
+};
+
+////////
+// Menus
+////////
+
 class MenuDelegate {
 public:
   virtual ~MenuDelegate() = default;
 
   virtual MenuActionResult MenuDelegateAction(Menu &menu) = 0;
 };
 
 class Menu : public WindowDelegate {