Tried all methods, couldn't make the frame scrollable

[zozowell]

Hey @ArthurSonzogni,

sorry for pinging you directly, I appreciate any guide on this topic. I've been trying to make a scrollable frame, basically to implement a log view. I tried everything I can found from the web in the past 2 days, now I despaired...

I tried the snippet you shared here. But it doesn't work on my MacOS, I tested with both Alacitty, and Terminal.app terminals, without tmux in mid. I couldn't find a clear document about it, none an example in the source code. From what I read, it sounds that the vscroll_indicator | frame decorator should just work, but it doesn't. Should I have to write my own viewport transformation logic in the render function?

Thanks in advance for any suggestions.

I tried a lot of implementation, but this is a simple one based on your snippet:

// Copyright 2022 Arthur Sonzogni. All rights reserved.
// Use of this source code is governed by the MIT license that can be found in
// the LICENSE file.
#include <memory>  // for allocator, __shared_ptr_access, shared_ptr
#include <string>  // for to_string, operator+
 
#include "ftxui/component/component.hpp"       // for Button, Renderer, Vertical
#include "ftxui/component/component_base.hpp"  // for ComponentBase
#include "ftxui/component/screen_interactive.hpp"  // for ScreenInteractive
#include "ftxui/dom/elements.hpp"  // for operator|, text, Element, hbox, separator, size, vbox, border, frame, vscroll_indicator, HEIGHT, LESS_THAN
 
using namespace ftxui;

Component MakeOne() {
  class Impl : public ComponentBase {
    Element Render() {
      auto element = text("Hello!");

      if (Focused()) {
        element = focus(element);
        element |= inverted;
      } else if (Active()) {
        element = select(element);
        element |= inverted;
      }

      return element;
    }

    bool Focusable() const final { return true; }
  };

  return Make<Impl>();
}

int main() {
  auto container = Container::Vertical({});
  for (int i = 0 ;i < 30; i++) {
    container->Add(MakeOne());
  }

  auto screen = ScreenInteractive::FitComponent();

  auto renderer = Renderer(container, [&] {
    return container->Render()
      | vscroll_indicator
      | frame
      | size(HEIGHT, LESS_THAN, 20)
      | border;
  });

  auto component = CatchEvent(container, [&](Event event) {
    if (event == Event::Character('q')) {
      screen.Exit();
      return true;
    }
    return false;
  });
 
  screen.Loop(component);
 
  return 0;
}

scrolltest.mov

[zozowell]

OK, after looking into the code a bit, I realized that I misunderstood the power of these decorators. As well, they are order sensitive... which is not obviously mentioned in the doc (or I missed it), but it's unfortunately true.

• vscroll_indicator, it just does the scroll indicator drawing, instead of supporting the scroll (i.e. the mouse event), I have to write my own event handling to make it "scroll" along the element margin. It is drawn in proportion of the inner element dimension v.s. outer box dimension. So, if the inner elements' size is smaller than outer box, it will not shows up at all.
• frame, it's the crux to make the box become a "viewport" of the inner element, when the inner element has a larger required dimensions than the box, the instead of trimming it, the frame will keep the correct real element size in the requirement. So, the vscroll_indicator must be applied BEFORE frame, otherwise, it doesn't work.
• To make the viewport move, you must change the "focus" of the frame. By default it focus on the top, so anything passed the boundary of its box will be trimmed off. The focus move is not happening automatically, you need to either:
  • set the frame child as focused.
  • or, use the decorator focusPosition(x, y)
    And most importantly, they must happen before the frame element calculate the requirements.

One gist I learnt, which is very helpful to decide the order of decorator is bare in mind this:

The box setting is cascading from root node to leaf nodes.
The requirement calculation propagates from leaves to root.

Here is a simple example to indicate the scroll indicator move, haven't added the event handling though:

#include "ftxui/component/component.hpp"       // for Button, Renderer, Vertical
#include "ftxui/component/screen_interactive.hpp"  // for ScreenInteractive
#include "ftxui/dom/elements.hpp"  // for operator|, text, Element, hbox, separator, size, vbox, border, frame, vscroll_indicator, HEIGHT, LESS_THAN
 
using namespace ftxui;

int main() {
  auto screen = ScreenInteractive::FixedSize(10, 12);
  auto slogon = Renderer([] {
      return vbox({
          text("0000000000"),
          text("1111111111"),
          text("2222222222"),
          text("3333333333"),
          text("4444444444"),
          text("5555555555"),
          text("6666666666"),
          text("7777777777"),
          text("8888888888"),  
          text("9999999999"),
          text("aaaaaaaaaa"),
          text("bbbbbbbbbb"),
          text("cccccccccc"),
          text("dddddddddd"),
          text("eeeeeeeeee"),
          text("ffffffffff"),
          text("gggggggggg"),
          text("hhhhhhhhhh"),  
          text("iiiiiiiiii"),
          text("jjjjjjjjjj"),
          text("kkkkkkkkkk"),
          text("llllllllll"),
          }) | vscroll_indicator | focusPosition(0, 10) | frame | border;
      });

  screen.Loop(slogon);

  return 0;
}

[ArthurSonzogni]

Thanks @zozowell!

That's a very good understanding. Scrolling is a source of common misunderstanding. I wonder if we couldn't use your message as a starting point to a new page of documentation. I could a be a new markdown file in in /doc/scrolling.md or doxygen /// comments starting with /// @page scrolling in the frame.cpp file.

Would you like to submit a PR?

[zozowell]

@ArthurSonzogni, yeah, happy to, but needs some times.