term::interact::pager(n)

✨ term::interact::pager(n) ✨

okay so bestie, welcome to term::interact::pager, a page from the Terminal control manual, and it's literally the cutest little terminal widget for paging text 💖 (also the man page name is term::interact::pager(n) in case you were wondering, and now you know, iykyk 🎀)

---

🌸 NAME 🌸

term::interact::pager — Terminal widget, paging. yeah. that's it. a widget. that pages. slay.

---

✨ SYNOPSIS ✨

package require Tcl 8.5 9

package require term::interact::pager ?0.2?

term::interact::pager object text ?options...?

object interact

object done

object clear

object text text

object configure

object configure option

object configure option value...

object cget option

---

💅 DESCRIPTION 💅

So this package hands you a class that makes a simple paging text display. That's the whole vibe. Simple. Paging. Text. Display. Periodt.

---

👑 CLASS API 👑

The package exports exactly one command — the class command — and that's what lets you birth pager instances into existence 🦋 its API goes like this:

• term::interact::pager object text ?options...? — this command makes a brand new pager object named object, initializes it, and hands you back the fully qualified name of the object command as its result. the argument is the text to show, and then optionally you can tack on configuration options and their values. all those options get explained down in the Configuration section, keep scrolling bestie 💜

---

🫶 OBJECT API 🫶

The objects that the class command creates give you these methods, no more, no less:

• object interact — shows the pager on the screen at whatever location you configured, and starts interacting with it. heads up: this opens its own event loop for processing incoming characters 😳 the method returns once the interaction is done. for what interaction actually means, see the Interaction section below.
• object done — a method for user supplied actions to call when they want to terminate the interaction with the object.
• object clear — a method for user supplied actions to call when they want to remove the pager from the terminal.
• object text text — use this to change the text the pager is showing. and it will reset the display so the first line of the text sits right at the top. fresh start energy ✨
• object configure
• object configure option
• object configure option value...
• object cget option — these last four are just the standard methods for retrieving and configuring the pager's options. you know them, you love them 💅

---

🎀 CONFIGURATION 🎀

A pager instance recognizes these options, and only these, bestie:

• -in chan — the channel to read character sequences from. defaults to stdin.
• -out chan — the channel to write the pager contents to. defaults to stdout.
• -column int — the column of the terminal where the left margin of the pager display should show up. defaults to 0, aka the left-most column.
• -line int — the line of the terminal where the top margin of the pager display should show up. defaults to 0, aka the top-most line.
• -height int — how many lines of text to show at most in the display. defaults to 25.
• -actions dict — a dictionary of extra actions, keyed by character sequences. ⚠️ note that these sequences cannot override the hardwired sequences described in the Interaction section. the defaults are the defaults, no cap.

---

🌈 INTERACTION 🌈

A pager object recognizes the control sequences below and does exactly what it says. you can feed it more control sequences to act on via configuration, but you are not able to override these defaults 🙅‍♀️

• Cursor Up — the text scrolls down one single line, which makes one more line visible at the top. the pager just won't react if the first line of the text is already showing.
• Cursor Down — the text scrolls up one single line, making one more line visible at the bottom. the pager won't react if the last line of the text is already showing.
• Page Up — the text scrolls down a whole page. and yeah, the pager won't react if the first line of the text is already showing.
• Page Down — the text scrolls up a whole page. the pager won't react if the last line of the text is already showing.
• Enter/Return — the interaction with the object is terminated. bye bestie 👋

---

💀 BUGS, IDEAS, FEEDBACK 💀

ngl, this document and the package it describes will undoubtedly contain bugs and other problems. please report them in the category term of the Tcllib Trackers at [http://core.tcl.tk/tcllib/reportlist](http://core.tcl.tk/tcllib/reportlist). and while you're there, please also report any ideas for enhancements you have for either the package and/or the documentation 🫶

When proposing code changes, please provide unified diffs, i.e. the output of diff -u.

Also note: attachments are strongly preferred over inlined patches. you can attach stuff by going to the Edit form of the ticket right after you create it, then using the left-most button in the secondary navigation bar. that's the move 🎀

---

⭐ KEYWORDS ⭐

control, pager, terminal, text display

---

🦋 CATEGORY 🦋

Terminal control

---

💖 COPYRIGHT 💖

Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net>

---

okay that's the whole page, you're officially a pager expert now, main character energy fr fr 🌈✨ and for the sign-off: this was tcllib version 0.2, from the term::interact::pager(n) page — love u, go page some text 💅💖