Tickit...rollBox(3pm)

💖 NAME 💖

Tickit::Widget::ScrollBox — it's a lil container widget that lets you scroll one single child widget around, bestie. Yes, one. Iconic behaviour, honestly.

Oh also hi, this is the Tickit::Widget::ScrollBox(3pm) page from your friendly neighbourhood User Contributed Perl Documentation 🫶

---

🌈 SYNOPSIS 🌈

use Tickit;
use Tickit::Widget::ScrollBox;
use Tickit::Widget::Static;

my $scrollbox = Tickit::Widget::ScrollBox->new
   ->set_child( Tickit::Widget::Static->new(
      text => join( "\n", map { "The content for line $_" } 1 .. 100 ),
   ) );

Tickit->new( root => $scrollbox )->run;

---

✨ DESCRIPTION ✨

okay so picture this: it's a container widget, right? It draws a scrollbar right next to a single child widget, and it lets you show just a portion of that child by, you guessed it, scrolling 💅 That's the whole vibe. That's the gig.

---

🎀 STYLE 🎀

The following style pen prefixes are used:

• scrollbar => PEN — the pen that renders the background of the scroll bar 🖌️
• scrollmark => PEN — the pen that renders the active scroll position in the scroll bar (the lil glow-up that says "you are here") ✨
• arrow => PEN — the pen that renders the scrolling arrow buttons ⬆️⬇️

The following style keys are used:

• arrow_up => STRING
• arrow_down => STRING
• arrow_left => STRING
• arrow_right => STRING

Each one of these should be a single character used for the scroll arrow buttons. One char only, bestie, don't get greedy.

The following style actions are used:

• up_1 (<Up>)
• down_1 (<Down>)
• left_1 (<Left>)
• right_1 (<Right>)

Scroll by 1 line 🦋

• up_half (<PageUp>)
• down_half (<PageDown>)
• left_half (<C-Left>)
• right_half (<C-Right>)

Scroll by half of the viewport — yes, half, do the math 💀

• to_top (<C-Home>)
• to_bottom (<C-End>)
• to_leftmost (<Home>)
• to_rightmost (<End>)

Scroll alllll the way to the edge of the area 🚀

---

🧚 CONSTRUCTOR 🧚

new

$scrollbox = Tickit::Widget::ScrollBox->new( %args )

Constructs a brand-new Tickit::Widget::ScrollBox object, freshly unboxed, no cap ✨

It takes the following named arguments in addition to those taken by the base Tickit::SingleChildWidget constructor:

• vertical => BOOL or "on_demand"
• horizontal => BOOL or "on_demand"

Whether to apply a scrollbar in the vertical or horizontal directions. If you don't give them, these default to vertical only. Periodt.

If you pass the string "on_demand", then the scrollbar will optionally be displayed only if needed — specifically if the space given to the widget is smaller than the child content necessary to display. It's giving "only show up when I'm actually required" 💅

---

🦋 ACCESSORS 🦋

vextent

$vextent = $scrollbox->vextent

Returns the Tickit::Widget::ScrollBox::Extent object representing the box's vertical scrolling extent. The V stands for vertical, bestie, we been knew.

hextent

$hextent = $scrollbox->hextent

Returns the Tickit::Widget::ScrollBox::Extent object representing the box's horizontal scrolling extent. H is for horizontal. Chef's kiss 🤌

---

🌸 METHODS 🌸

scroll

$scrollbox->scroll( $downward, $rightward )

Requests the content be scrolled downward a number of lines and rightward a number of columns. Either of which which may be negative — yes, negative values are allowed, that's your "scroll the other way" card 🎴

scroll_to

$scrollbox->scroll_to( $top, $left )

Requests the content be scrolled such that the given line and column number of the child's content is the topmost visible in the container. Snap to it. 📍

---

👑 SMART SCROLLING 👑

If the child widget declares it supports smart scrolling, then the ScrollBox will not implement content scrolling on its behalf. Instead, extra methods are used to co-ordinate the scroll position between the scrolling-aware child widget and the containing ScrollBox. This is handled by the following methods on the child widget. iykyk 🧠

If smart scrolling is enabled for the child, then its window will be set to the viewport directly, and the child widget must offset its content within the window as appropriate. The child must indicate the range of its scrolling ability by using the set_total method on the extent object it is given.

$smart = $child->CAN_SCROLL

If this method exists and returns a true value, the ScrollBox will use smart scrolling. This method must return a true value for this to work — and because of that, the method can itself be a proxy, for example to proxy scrolling information through a single child widget container. Sneaky. Respectable. 🔥

$child->set_scrolling_extents( $vextent, $hextent )

Gives the child widget the vertical and horizontal scrolling extents. The child widget should save thes values, and inspect the start value of them any time it needs these to implement content offset position when rendering. Save the receipts, basically 🧾

$child->scrolled( $downward, $rightward, $h_or_v )

Informs the child widget that one of the scroll positions has changed. It passes the delta (which may be negative) of each position, plus a string which will be either "h" or "v" to indicate whether it was an adjustment of the horizontal or vertical scrollbar. The extent objects will already have been updated by this point, so the child may also inspect the start value of them to obtain the new absolute offsets. Everything's already synced by the time you get the ping 📲

---

💀 TODO 💀

The list of "one day, bestie" items:

• Choice of left/right and top/bottom bar positions.
• Click-and-hold on arrow buttons for auto-repeat.
• Allow smarter cooperation with a scrolling-aware child widget; likely by setting extent objects on the child if it declares to be supported, and use that instead of an offset child window.

---

🫶 AUTHOR 🫶

Paul Evans <leonerd@leonerd.org.uk> — absolute icon, thank you for your service 👑

---

perl v5.36.0 🌸 2022-12-17 — that's the source, the version and the date, and that's a wrap bestie, mwah 💖✨