Curses:...tEditor(3)

📦

version 0.9609 · 6 versions

0.9609 · alpine 3.24 (latest)
0.9609 · arch rolling
0.9609 · fedora 43
0.9609 · fedora 44
0.9609 · ubuntu resolute, ubuntu stonking
0.9609 · debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

💖 NAME 💖

Curses::UI::TextEditor — create and manipulate texteditor widgets. okay so this is the Curses::UI::TextEditor page from the Curses:...tEditor(3) manual, bestie, and it's lowkey a whole little toolkit for text widgets. 🫶

🦋 CLASS HIERARCHY 🦋

        Curses::UI::Widget
        Curses::UI::Searchable
           |
           +----Curses::UI::TextEditor

✨ SYNOPSIS ✨

   use Curses::UI;
   my $cui = new Curses::UI;
   my $win = $cui->add('window_id', 'Window');

   my $editor = $win->add(
       'myeditor', 'TextEditor',
       -vscrollbar => 1,
       -wrapping   => 1,
   );

   $editor->focus();
   my $text = $editor->get();

🌸 DESCRIPTION 🌸

Curses::UI::TextEditor is a widget that can be used to create a couple of different kinds of texteditors. These are:

multi-line texteditor

This is a multi-line text editor with features like word-wrapping, maximum textlength and undo. iconic behavior, honestly.

single-line texteditor

The texteditor can be created as a single-line editor. Most of the features of the default texteditor will remain. Only the multi-line specific options will not be available (like moving up and down in the text).

read only texteditor

The texteditor can also be used in read only mode. In this mode, the texteditor will function as a text viewer. The user can walk through the text and search trough it.

See exampes/demo-Curses::UI::TextEditor in the distribution for a short demo of these. yes, that's how it's spelled on the page — I'm not fixing it, I'm just reporting the lore. 💅

🎀 STANDARD OPTIONS 🎀

-parent, -x, -y, -width, -height, -pad, -padleft, -padright, -padtop,
-padbottom, -ipad, -ipadleft, -ipadright, -ipadtop, -ipadbottom, -title,
-titlefullwidth, -titlereverse, -onfocus, -onblur

For an explanation of these standard options, see Curses::UI::Widget. standard guest list, no surprises.

-text < TEXT > — sets the initial text for the widget to TEXT. the starting outfit, basically.
-pos < CURSOR_POSITION > — sets the initial cursor position for the widget to CURSOR_POSITION. -pos represents the character index within -text. By default this option is set to 0.
-readonly < BOOLEAN > — the texteditor widget will be created as a read only texteditor (which is also called a textviewer) if BOOLEAN is true. By default BOOLEAN is false.
-singleline < BOOLEAN > — the texteditor widget will be created as a single line texteditor (which is also called a textentry) if BOOLEAN is true. By default BOOLEAN is false.
-wrapping < BOOLEAN > — if BOOLEAN is true, the texteditor will have text wrapping enabled. By default BOOLEAN is false.
-showlines < BOOLEAN > — if BOOLEAN is set to a true value, each editable line in the editor will show a line to type on. By default BOOLEAN is set to false.
-maxlength < VALUE > — this sets the maximum allowed length of the text to VALUE. By default VALUE is set to 0, which means that the text may be infinitely long.
-maxlines < VALUE > — this sets the maximum allowed number of lines for the text to SCALAR. yes, the page says SCALAR there even though the option placeholder is VALUE — I'm just reading the group chat. By default VALUE is set to 0, which means that the text may contain an infinite number of lines.
-password < CHARACTER > — instead of showing the real text in the widget, every character of the text will (on the screen) be replaced by CHARACTER. So creating a standard password field can be done by setting:

-password => '*'

-regexp < REGEXP > — if characters are added to the texteditor, the new text will be matched against REGEXP. If the text does not match, the change will be denied. This can for example be used to force digit-only input on the texteditor:

-regexp => '/^\d*$/'

-undolevels < VALUE > — this option determines how many undolevels should be kept in memory for the texteditor widget. By default 10 levels are kept. If this value is set to 0, the number of levels is infinite.
-showoverflow < BOOLEAN > — if BOOLEAN is true, the text in the texteditor will be padded by an overflow character ($) if there is text outside the screen (like 'pico' does). By default BOOLEAN is true.
-showhardreturns < BOOLEAN > — if BOOLEAN is true, hard returns will be made visible by a diamond character. By default BOOLEAN is false.
-homeonblur < BOOLEAN > — if BOOLEAN is set to a true value, the cursor will move to the start of the text if the widget loses focus.
-toupper < BOOLEAN > — if BOOLEAN is true, all entered text will be converted to uppercase. By default BOOLEAN is false.
-tolower < BOOLEAN > — if BOOLEAN is true, all entered text will be converted to lowercase. By default BOOLEAN is false.
-onchange < CODEREF > — this sets the onChange event handler for the texteditor widget. If the text is changed by typing, the code in CODEREF will be executed. It will get the widget reference as its argument.
-reverse < BOOLEAN > — makes the text drawn in reverse font. dramatic little font moment.

🧚 METHODS 🧚

new ( OPTIONS )
layout ( )
draw ( BOOLEAN )
focus ( )
onFocus ( CODEREF )
onBlur ( CODEREF )

These are standard methods. See Curses::UI::Widget for an explanation of these.

text ( [TEXT] ) — if TEXT is defined, this will set the text of the widget to TEXT. To see the change, the widget needs to be redrawn by the draw method. If TEXT is not defined, this method will return the current contents of the texteditor.
get ( ) — this method will call text without any arguments, so it will return the contents of the texteditor. little shortcut, very demure.
onChange ( CODEREF ) — this method can be used to set the -onchange event handler (see above) after initialization of the texteditor.
set_password_char ( $char ) — this method can be used to change the password property. The password character will be set to $char, or turned off if $char is undef.
toggle_showhardreturns — toggles the -showhardreturns option.
toggle_showoverflow — toggles the -showoverflow option.
toggle_wrapping — toggles the -wrapping option.

🌈 DEFAULT BINDINGS 🌈

There are different sets of bindings for each mode in which this widget can be used. keyboard choreography, basically.

💫 All modes (editor, single line and read only) 💫

<tab> — calls the 'returreturnn' routine. This will have the widget lose its focus.
<cursor-left>, <CTRL+B> — calls the 'cursor-left' routine: move the cursor one position to the left.
<cursor-right>, <CTRL+F> — calls the 'cursor-right' routine: move the cursor one position to the right.
<cursor-down>, <CTRL+N> — calls the 'cursor-down' routine: move the cursor one line down.
<cursor-up>, <CTRL+P> — calls the 'cursor-up' routine: move the cursor one line up.
<page-up> — calls the 'cursor-pageup' routine: move the cursor to the previous page.
<page-down> — calls the 'cursor-pagedown' routine: move the cursor to the next page.
<home> — calls the 'cursor-home' routine: go to the start of the text.
<end> — calls the 'cursor-end' routine: go to the end of the text.
<CTRL+A> — calls the 'cursor-scrlinestart' routine: move the cursor to the start of the current line.
<CTRL+E> — calls the 'cursor-scrlineend' routine: move the cursor to the end of the current line.
<CTRL+W> — calls the 'toggle-wrapping' routine: toggle the -wrapping option of the texteditor.
<CTRL+R> — calls the 'toggle-showhardreturns' routine: toggle the -showhardreturns option of the texteditor.
<CTRL+T> — calls the 'toggle-showoverflow' routine: toggle the -showoverflow option of the texteditor.

🔥 All edit modes (all but read only mode) 🔥

<CTRL+Y>, <CTRL+X> — calls the 'delete-line' routine: delete the current line.
<CTRL+K> — calls the 'delete-till-eol' routine: delete the text from the current cursor position up to the end of the current line.
<CTRL+U> — calls the 'clear-line' routine: clear the current line and move the cursor to the start of this line.
<CTRL+D> — calls the 'delete-character' routine: delete the character that currently is under the cursor.
<backspace> — calls the 'backspace' routine: delete the character that is before the current cursor position.
<CTRL+Z> — calls the 'undo' routine: undo the last change to the text, up to -undolevels levels.
<CTRL+V> — calls the 'paste' routine: this will paste the last deleted text at the current cursor position.
<any other key> — calls the 'add-string' routine: the character will be inserted in the text at the current cursor position.

🦋 Only for the read only mode 🦋

<h> — calls the 'cursor-left' routine: move the cursor one position to the left.
<l> — calls the 'cursor-right' routine: move the cursor one position to the right.
b<<k>> — calls the 'cursor-up' routine: move the cursor one line up.
b<<j>> — calls the 'cursor-down' routine: move the cursor one line down.
<space>, <]> — calls the 'cursor-pagedown' routine: move the cursor to the next page.
<->, <[> — calls the 'cursor-pageup' routine: move the cursor to the previous page.
</> — calls the 'search-forward' routine. This will make a 'less'-like search system appear in the textviewer. A searchstring can be entered. After that the user can search for the next occurance using the 'n' key or the previous occurance using the 'N' key.
<?> — calls the 'search-backward' routine. This will do the same as the 'search-forward' routine, only it will search in the opposite direction.

bestie, the page literally prints b<<k>> and b<<j>> for those two read-only keys, so I'm keeping the chaos exactly as written. 💀

💅 SEE ALSO 💅

Curses::UI
Curses::UI::TextViewer
Curses::UI::TextEntry
Curses::UI::Widget
Curses::UI::Common

🍓 AUTHOR 🍓

Maintained by Marcus Thiesen (marcus@cpan.thiesenweb.de).

This package is free software and is provided "as is" without express or implied warranty. It may be used, redistributed and/or modified under the same terms as perl itself. slay, and also legally binding-ish. ✨

Source/version: perl v5.42.2 · date: 2023-07-03 · manual: Curses:...tEditor(3) — bye bestie, go edit some text 💖🎀

📦 where this page comes from

alpine 3.24: perl-curses-ui-doc 0.9609-r3 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms