Add example to filter characters inputted in an input field (#763)

Co-authored-by: ArthurSonzogni <sonzogniarthur@gmail.com>

doc/mainpage.md

@@ -633,6 +633,26 @@ Produced by: `ftxui::Input()` from "ftxui/component/component.hpp"
 <script id="asciicast-223719" src="https://asciinema.org/a/223719.js" async></script>
 @endhtmlonly
 
+### Filtered input
+
+On can filter out the characters received by the input component, using
+`ftxui::CatchEvent`.
+
+```cpp
+std::string phone_number;
+Component input = Input(&phone_number, "phone number");
+
+// Filter out non-digit characters.
+input |= CatchEvent([&](Event event) {
+  return event.is_character() && !std::isdigit(event.character()[0]);
+});
+
+// Filter out characters past the 10th one.
+input |= CatchEvent([&](Event event) {
+  return event.is_character() && phone_number.size() >= 10;
+});
+```
+
 ## Menu {#component-menu}
 
 Defines a menu object. It contains a list of entries, one of them is selected.

examples/component/input.cpp

@@ -15,30 +15,50 @@
 int main() {
   using namespace ftxui;
 
+  // The data:
   std::string first_name;
   std::string last_name;
   std::string password;
+  std::string phoneNumber;
 
+  // The basic input components:
   Component input_first_name = Input(&first_name, "first name");
   Component input_last_name = Input(&last_name, "last name");
 
+  // The password input component:
   InputOption password_option;
   password_option.password = true;
   Component input_password = Input(&password, "password", password_option);
 
+  // The phone number input component:
+  // We are using `CatchEvent` to filter out non-digit characters.
+  Component input_phone_number = Input(&phoneNumber, "phone number");
+  input_phone_number |= CatchEvent([&](Event event) {
+    return event.is_character() && !std::isdigit(event.character()[0]);
+  });
+  input_phone_number |= CatchEvent([&](Event event) {
+    return event.is_character() && phoneNumber.size() > 10;
+  });
+
+  // The component tree:
   auto component = Container::Vertical({
       input_first_name,
       input_last_name,
       input_password,
+      input_phone_number,
   });
 
+  // Tweak how the component tree is rendered:
   auto renderer = Renderer(component, [&] {
     return vbox({
-               text("Hello " + first_name + " " + last_name),
-               separator(),
                hbox(text(" First name : "), input_first_name->Render()),
                hbox(text(" Last name  : "), input_last_name->Render()),
                hbox(text(" Password   : "), input_password->Render()),
+               hbox(text(" Phone num  : "), input_phone_number->Render()),
+               separator(),
+               text("Hello " + first_name + " " + last_name),
+               text("Your password is " + password),
+               text("Your phone number is " + phoneNumber),
            }) |
            border;
   });