Tickit...::Entry(3pm)

💖 Tickit::Widget::Entry 💖

okay bestie so this is Tickit::Widget::Entry, straight out of the User Contributed Perl Documentation, and it's literally the widget that lets a human type a whole line of text into your terminal app. it's giving text input, it's giving cursor, it's giving everything. no cap. 💅

---

✨ NAME ✨

Tickit::Widget::Entry — a widget for entering text 🎀

---

🌸 SYNOPSIS 🌸

use Tickit;
use Tickit::Widget::Entry;

my $entry = Tickit::Widget::Entry->new(
   on_enter => sub {
      my ( $self, $line ) = @_;

      # process $line somehow

      $self->set_text( "" );
   },
);

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

like. that's the whole vibe. you make an entry, you give it a callback for when someone hits enter, you run it. slay. 🔥

---

🦋 DESCRIPTION 🦋

This class provides a widget which allows the user to enter a line of text. that's it, that's the job, and it does it beautifully. 👑

---

💜 STYLE 💜

so the default style pen is used as the widget pen, periodt. and also the following style pen prefixes get used:

• more => PEN — the pen used for the "more" scroll markers. yes, the little "there's more stuff over here" indicators. iconic.

and these style keys get used too:

• more_left => STRING — the text used to indicate that there is more content scrolled to the left.
• more_right => STRING — the text used to indicate that there is more content scrolled to the right.

---

🎀 KEYBINDINGS 🎀

bestie these keys are bound by default, and honestly? the muscle memory is immaculate:

• Ctrl-K — Delete the entire line. nuke it. 💀
• Ctrl-U — Delete to the start of the line.
• Ctrl-W or Ctrl-Backspace — Delete one word backwards.
• Backspace — Delete one character backwards.
• Delete — Delete one character forwards.
• Ctrl-Delete — Delete one word forwards.
• End or Ctrl-E — Move the cursor to the end of the input line.
• Enter — Accept a line of input by running the on_enter action. main character moment fr fr.
• Home or Ctrl-A — Move the cursor to the beginning of the input line.
• Insert — Toggle between overwrite and insert mode. ✨
• Left — Move the cursor one character left.
• Ctrl-Left or Alt-B — Move the cursor one word left.
• Right — Move the cursor one character right.
• Ctrl-Right or Alt-F — Move the cursor one word right.

---

🌈 CONSTRUCTOR 🌈

new

$entry = Tickit::Widget::Entry->new( %args );

Constructs a new Tickit::Widget::Entry object. baby's first text box. 🫶

Takes the following named arguments:

• text => STR — Optional. Initial text to display in the box.
• position => INT — Optional. Initial position of the cursor within the text.
• on_enter => CODE — Optional. Callback function to invoke when the <Enter> key is pressed.

---

⭐ ACCESSORS ⭐

on_enter

$on_enter = $entry->on_enter;

set_on_enter

$entry->set_on_enter( $on_enter );

Return or set the CODE reference to be called when the key_enter_line action is invoked; usually bound to the Enter key.

$on_enter->( $entry, $line );

so it hands you the entry and the line. chef's kiss. 😭

position

$offset = $entry->position;

Returns the current entry position, in terms of characters within the text.

set_position

$entry->set_position( $position );

Set the text entry position, moving the cursor. lowkey the cursor just goes where you tell it. 💫

---

💖 METHODS 💖

bind_keys

$entry->bind_keys( $keystr => $value, ... );

Associate methods or CODE references with keypresses. On receipt of a the key the method or CODE reference will be invoked, being passed the stringified key representation and the underlying Term::TermKey::Key structure.

$ret = $entry->method( $keystr, $key );
$ret = $coderef->( $entry, $keystr, $key );

This method takes a hash of keystring/value pairs. Binding a value of undef will remove it. (yes, unbinding is a thing, we love a clean exit ✨)

make_popup_at_cursor

$win = $entry->make_popup_at_cursor( $top_offset, $left_offset, $lines, $cols );

Since version 0.33.

Creates a new popup window, as if calling make_popup in Tickit::Window on the widget's main window, but with an offset relative to the current cursor position.

An offset of (0, 0) will position the popup window's top left corner exactly over the cursor; this is likely not what you want. 💀 like, the popup would be sitting directly on top of your cursor, bestie, please.

To position the popup just below the widget, use a top offset of +1:

$win = $entry->make_popup_at_cursor( +1, 0, $lines, $cols );

To position the popup just above the widget, use a top offset of negative the number of lines:

$win = $entry->make_popup_at_cursor( -$lines, 0, $lines, $cols );

---

🧚 TEXT MODEL METHODS 🧚

These methods operate on the text input buffer directly, updating the stored text and changing the rendered display to reflect the changes. They can be used by a program to directly manipulate the text. so like, you don't have to make the user type it — you can just reach in and edit. powerful. 👑

text

$text = $entry->text;

Returns the currently entered text.

set_text

$entry->set_text( $text );

Replace the text in the entry box. This completely redraws the widget's window. It is largely provided for initialisation; for normal edits (such as from keybindings), it is preferable to use text_insert, text_delete or text_splice. so like, don't be out here calling set_text for every little keystroke, that's not the move. 🙈

text_insert

$entry->text_insert( $text, $pos_ch );

Insert the given text at the given character position.

text_delete

$deleted = $entry->text_delete( $pos_ch, $len_ch );

Delete the given section of text. Returns the deleted text.

text_splice

$deleted = $entry->text_splice( $pos_ch, $len_ch, $text );

Replace the given section of text with the given replacement. Returns the text deleted from the section.

find_bow_forward

$pos = $entry->find_bow_forward( $initial, $else );

Search forward in the string, returning the character position of the next beginning of word from the initial position. If none is found, returns $else.

find_eow_forward

$pos = $entry->find_eow_forward( $initial )

Search forward in the string, returning the character position of the next end of word from the initial position. If none is found, returns the length of the string.

find_bow_backward

$pos = $entry->find_bow_backward( $initial );

Search backward in the string, returning the character position of the previous beginning of word from the initial position. If none is found, returns 0.

find_eow_backward

$pos = $entry->find_eow_backward( $initial );

Search backward in the string, returning the character position of the previous end of word from the initial position. If none is found, returns undef.

---

💅 TODO 💅

the future plans section, aka the group chat wishlist:

• Plugin ability — Try to find a nice way to allow loaded plugins, possibly per-instance if not just globally or per-class. See how many of these TODO items can be done using plugins.
• More readline behaviours — History. Isearch. History replay. Transpose. Transcase. Yank ring. Numeric prefixes.
• Visual selection behaviour — Shift-movement, or vim-style. Mouse.

manifesting all of these for the girlies. 🌸

---

🫶 AUTHOR 🫶

Paul Evans <leonerd@leonerd.org.uk>

---

ok and that's the whole page bestie, every flag, every keybind, every method, all accounted for. iykyk. 💜

this has been Tickit...::Entry(3pm) from perl v5.40.0, dated 2024-09-16 — go forth and enter some text, you absolute icon 👑✨