Tickit...roller(3pm)

💖 Tickit::Widget::Scroller — the perl(3pm) page, but make it cute ✨

okay so bestie, welcome to the Tickit::Widget::Scroller manual — that's the 3pm one, from the User Contributed Perl Documentation corner of the world. this is a widget that displays a scrollable collection of items, and honestly? it's giving main character energy. let's get into it 🫶

---

✨ NAME ✨

Tickit::Widget::Scroller — a widget displaying a scrollable collection of items 💅

---

🌸 SYNOPSIS 🌸

use Tickit;
use Tickit::Widget::Scroller;
use Tickit::Widget::Scroller::Item::Text;

my $tickit = Tickit->new;

my $scroller = Tickit::Widget::Scroller->new;

$scroller->push(
   Tickit::Widget::Scroller::Item::Text->new( "Hello world" ),
   Tickit::Widget::Scroller::Item::Text->new( "Here are some lines" ),
   map { Tickit::Widget::Scroller::Item::Text->new( "<Line $_>" ) } 1 .. 50,
);

$tickit->set_root_widget( $scroller );

$tickit->run

look at her. fifty lines of text and one little widget holding it all together. iconic. 🎀

---

🦋 DESCRIPTION 🦋

This class provides a widget which displays a scrollable list of items. The view of the items is scrollable, able to display only a part of the list. like, you got a whole vibe going on but the terminal window is smol, so you scroll. it's fine. we cope.

A Scroller widget stores a list of instances implementing the Tickit::Widget::Scroller::Item interface.

---

💜 STYLE 💜

The default style pen is used as the widget pen.

The following style pen prefixes are used:

• indicator => PEN — the pen used for the scroll position indicators at the top or bottom of the display ✨

---

🎀 KEYBINDINGS 🎀

The following keys are bound:

• Down — scroll one line down ⬇️
• Up — scroll one line up ⬆️
• PageDown — scroll half a window down 📄⬇️
• PageUp — scroll half a window up 📄⬆️
• Ctrl-Home — scroll to the top 🔝
• Ctrl-End — scroll to the bottom 🔚

no cap, that's the whole keyboard situation. periodt.

---

🌈 CONSTRUCTOR 🌈

🧚 new

$scroller = Tickit::Widget::Scroller->new( %args )

Constructs a new Tickit::Widget::Scroller object. The new object will start with an empty list of items. brand new, zero items, a blank canvas, fresh start energy ✨

Takes the following named arguments:

• gravity => STRING — Optional. If given the value "bottom", resize events and the "push" method will attempt to preserve the item at the bottom of the screen. Otherwise, will preserve the top. so like... which end is the anchor? your call bestie 💅
• **gen_top_indicator => CODE** / **gen_bottom_indicator=> CODE** — Optional. Generator functions for the top and bottom indicators. See also"set_gen_top_indicator"and"set_gen_bottom_indicator"`. 🎀

---

💖 METHODS 💖

🌸 on_scrolled / set_on_scrolled

$on_scrolled = $scroller->on_scrolled;

$scroller->set_on_scrolled( $on_scrolled );

Return or set the CODE reference to be called when the scroll position is adjusted.

$on_scrolled->( $scroller, $delta );

This is invoked by the "scroll" method, including the "scroll_to", "scroll_to_top" and "scroll_to_bottom". In normal cases it will be given the delta offset that "scroll" itself was invoked with, though this may be clipped if this would scroll past the beginning or end of the display. so if you try to scroll past the edge, you get the trimmed-down delta. it's giving honesty. 😌

🦋 items

$count = $scroller->items;

Since version 0.31.

In scalar context, returns the number of items currently stored in the Scroller. The behaviour of this method in non-scalar context is currently unspecified. ⚠️ so like, don't be weird about it, okay? scalar context only. iykyk

🎀 push

$scroller->push( @items );

Append the given items to the end of the list.

If the Scroller is already at the tail (that is, the last line of the last item is on display) and the gravity mode is "bottom", the newly added items will be displayed, possibly by scrolling downward if required. While the scroller isn't adjusted by using any of the "scroll" methods, it will remain following the tail of the items, scrolling itself downwards as more are added. it literally just keeps following the bottom like a loyal bestie 🫶

🧚 unshift

$scroller->unshift( @items );

Prepend the given items to the beginning of the list.

If the Scroller is already at the head (that is, the first line of the first item is on display) and the gravity mode is "top", the newly added items will be displayed, possibly by scrolling upward if required. While the scroller isn't adjusted by using any of the "scroll" methods, it will remain following the head of the items, scrolling itself upwards as more are added. same energy, opposite direction ⬆️

💅 shift

@items = $scroller->shift( $count );

Remove the given number of items from the start of the list and returns them.

If any of the items are on display, the Scroller will be scrolled upwards an amount sufficient to close the gap, ensuring the first remaining item is now at the top of the display.

The returned items may be re-used by adding them back into the scroller again either by "push" or "unshift", or may be discarded. recycle era ♻️

🌈 pop

@items = $scroller->pop( $count );

Remove the given number of items from the end of the list and returns them.

If any of the items are on display, the Scroller will be scrolled downwards an amount sufficient to close the gap, ensuring the last remaining item is now at the bottom of the display.

The returned items may be re-used by adding them back into the scroller again either by "push" or "unshift", or may be discarded. same deal, other end 💅

✨ scroll

$scroller->scroll( $delta );

Move the display up or down by the given $delta amount; with positive moving down. This will be a physical count of displayed lines; if some items occupy multiple lines, then fewer items may be scrolled than lines. so heads up: it counts lines, not items. a multi-line item eats more than one tick of the delta. don't get confused bestie 😭

💜 scroll_to

$scroller->scroll_to( $line, $item_or_idx, $itemline );

Moves the display up or down so that display line $line contains line $itemline of the item; which may be given by object reference or index number. Any of these counts may be negative to count backwards from the display lines, items, or lines within the item. negatives = counting from the end, as always 🌀

🎀 scroll_to_top

$scroller->scroll_to_top( $item_or_idx, $itemline );

Shortcut for "scroll_to" to set the top line of display; where $line is 0. If $itemline is undefined, it will be passed as 0. If $item_or_idx is also undefined, it will be passed as 0. Calling this method with no arguments, therefore scrolls to the very top of the display. zero args, zero problems, straight to the top 🔝

🌸 scroll_to_bottom

$scroller->scroll_to_bottom( $item_or_idx, $itemline );

Shortcut for "scroll_to" to set the bottom line of display; where $line is -1. If $itemline is undefined, it will be passed as -1. If $item_or_idx is also undefined, it will be passed as -1. Calling this method with no arguments, therefore scrolls to the very bottom of the display. negative numbers, downward spiral, but make it intentional 🔚

🦋 scroll_to_visible

$scroller->scroll_to_visible( $item_or_idx, $itemline, %opts );

Since version 0.33.

If the requested line of the requested item is already visible on the display, this method does nothing. Otherwise, it scrolls up or down by the smallest amount possible so that it becomes visible. If the line was previously above then it scrolls just sufficient to bring that line to the top-most of the display. If it was below, it scrolls to bring it to the bottom-most. minimum effort, maximum results. that's the vibe ✨

If the optional "margin" named argument it set to a value larger than zero, it causes that number of the top-most and bottom-most lines not to count for purposes of visibility or scrolling. so the edges get a lil buffer zone 🎀

🧚 line2item

$itemidx = $scroller->line2item( $line );

( $itemidx, $itemline ) = $scroller->line2item( $line );

Returns the item index currently on display at the given line of the window. In list context, also returns the line number within item. If no window has been set, or there is no item on display at that line, undef or an empty list are returned. $line may be negative to count backward from the last line on display; the last line taking -1. yeah, -1 is the last line. always has been. 💀

💜 item2line

$line = $scroller->item2line( $item_or_idx, $itemline );

( $line, $offscreen ) = $scroller->item2line( $item_or_idx, $itemline, $count_offscreen );

Returns the display line in the window of the given line of the item at the given index. $item_or_idx may be an item directly, a non-negative integer to give its index, or a negative to count backwards from the last item. $itemline may be negative to count backward from the last line of the item.

In list context, also returns a value describing the offscreen nature of the item. For items fully on display, this value is undef. If the given line of the given item is not on display because it is scrolled off either the top or bottom of the window, this value will be either "above" or "below" respectively. If $count_offscreen is true, then the returned $line value will always be defined, even if the item line is offscreen. This will be negative for items "above", and a value equal or greater than the number of lines in the scroller's window for items "below". the offscreen lore is deep but we respect it 🫡

🌈 lines_above

$count = $scroller->lines_above;

Returns the number of lines of content above the scrolled display. ⬆️

🌈 lines_below

$count = $scroller->lines_below;

Returns the number of lines of content below the scrolled display. ⬇️

🎀 set_gen_top_indicator / set_gen_bottom_indicator

$scroller->set_gen_top_indicator( $method );

$scroller->set_gen_bottom_indicator( $method );

Accessors for the generators for the top and bottom indicator text. If set, each should be a CODE reference or method name on the scroller which will be invoked after any operation that changes the contents of the window, such as scrolling or adding or removing items. It should return a text string which, if defined and non-empty, will be displayed in an indicator window. This will be a small one-line window displayed at the top right or bottom right corner of the Scroller's window.

$text = $scroller->$method();

The ability to pass method names allows subclasses to easily implement custom logic as methods without having to capture a closure. subclass girlies stay winning 👑

💅 update_indicators

$scroller->update_indicators;

Calls any defined generators for indicator text, and updates the indicator windows with the returned text. This may be useful if the functions would return different text now. like, force a lil refresh, why not 💅

---

💀 TODO 💀

• Abstract away the "item storage model" out of the actual widget. Implement more storage models, such as database-driven ones.. more dynamic.

(yeah bestie, the double period is in the original. we don't fix, we preserve 😌)

---

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk> — the icon, the legend 💖

---

and that's the whole page, fr fr. this beauty is from perl v5.38.2, dated 2024-08-10, and yes, it's still Tickit...roller(3pm) at heart. go build something scrollable, bestie 🦋✨🎀