oracular (3) Tickit::Widget::Entry.3pm.gz
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;
DESCRIPTION
This class provides a widget which allows the user to enter a line of text.
STYLE
The default style pen is used as the widget pen. The following style pen prefixes are also used:
more => PEN
The pen used for the "more" scroll markers
The following style keys are used:
more_left => STRING
more_right => STRING
The text used to indicate that there is more content scrolled to the left or right, respectively
KEYBINDINGS
The following keys are bound by default
• Ctrl-K
Delete the entire line
• 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
• 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.
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 );
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
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.
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 offet of (0, 0) will position the popup window's top left corner exactly over the cursor; this is
likely not what you want.
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.
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".
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
• 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.
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>