Single line interactive text editor. More...

#include <senf/Utils/Termlib/Editor.hh>

Inheritance diagram for senf::term::LineEditor:

Public Types
typedef boost::function< void(LineEditor &)>	KeyBinding
	Type of a key binding function. More...

typedef boost::function< void(std::string const &)>	AcceptCallback
	Callback function type. More...

Public Types inherited from senf::term::BaseEditor
typedef KeyParser::keycode_t	keycode_t

Public Member Functions
	LineEditor (AbstractTerminal &terminal, AcceptCallback cb)
	Create a LineEditor. More...

Public Member Functions inherited from senf::term::BaseEditor
	BaseEditor (AbstractTerminal &terminal)

void	newline ()
	Move to beginning of a new, empty line. More...

void	toColumn (unsigned c)
	Move cursor to column `c`. More...

void	put (char ch)
	Write `ch` at current column. More...

void	put (std::string const &text)
	Write text starting at current column. More...

void	clearLine ()
	Clear current line and move cursor to first column. More...

void	setBold ()
	Set bold char display. More...

void	setNormal ()
	Set normal char display. More...

void	maybeClrScr ()
	Clear screen if possible. More...

void	toLine (unsigned l)
	Move to relative display line l. More...

void	reset ()
	Reset display area to single line. More...

unsigned	currentColumn () const
	Return number of current column. More...

unsigned	currentLine () const
	Return number of current relative line. More...

unsigned	width () const
	Return current screen width. More...

unsigned	height () const
	Return current screen height. More...

Public Member Functions inherited from senf::term::AbstractTerminal::Callbacks
virtual	~Callbacks ()

Static Public Attributes
static unsigned const	MAX_HISTORY_SIZE = 1024u

Static Public Attributes inherited from senf::term::BaseEditor
static unsigned const	DEFAULT_KEY_TIMEOUT_MS = 500u

Overall edit control
void	show ()
	Enable editor widget. More...

void	hide ()
	Disable editor widget. More...

void	accept ()
	Accept current user input and call the accept callback. More...

void	clear ()
	Clear editor buffer. More...

void	redisplay ()
	Mark the editor buffer for redisplay. More...

void	forceRedisplay ()
	Redisplay the editor buffer now. More...

void	prompt (std::string const &text)
	Set prompt string. More...

Cursor and display movement
void	gotoChar (unsigned n)
	Move cursor to position n. More...

void	scrollTo (unsigned n)
	Move position to beginning of display line. More...

Text manipulation
void	deleteChar (unsigned n=1)
	Delete n characters at point. More...

void	insert (char ch)
	Insert ch at point. More...

void	insert (std::string const &text)
	Insert text at point. More...

void	set (std::string const &text, unsigned pos=0u)
	Set edit buffer contents. More...

History
void	pushHistory (std::string const &text, bool accept=false)
	Add string text to history. More...

void	prevHistory ()
	Switch to previous history entry. More...

void	nextHistory ()
	Switch to next history entry. More...

Aux Display
void	auxDisplay (unsigned line, std::string const &text)
	Display text on aux display line line. More...

unsigned	maxAuxDisplayHeight ()
	Get maximum height of the aux display area. More...

void	clearAuxDisplay ()
	Clear the aux display area. More...

Get information
std::string const &	text ()
	Get current editor buffer contents. More...

unsigned	point ()
	Get current cursor position. More...

unsigned	displayPos ()
	Get current display position. More...

keycode_t	lastKey ()
	Get last key code received. More...

Key bindings
void	defineKey (keycode_t key, KeyBinding binding)
	Bind key key to binding. More...

void	unsetKey (keycode_t key)
	Remove all bindings for key. More...

Additional Inherited Members

Detailed Description

Single line interactive text editor.

LineEditor implements a single-line input widget on an arbitrary AbstractTerminal.

It supports all the customary editing functions
It is possible to arbitrarily assign functions to keys via a key map
LineEditor has builtin TAB completion support
The LineEditor has a built-in history
The LineEditor supports an arbitrary auxiliary display area below the input line
The LineEditor has hide() / show() support to allow editing to be temporarily interrupted.

The LineEditor will query the user for an input line. When the user accepts a line, LineEditor will call a user callback function. After the callback has been called, the editor is disabled. To accept a new input line, call show().

The editor key map

    Keys are defined in the keymap using defineKey(). The default bindings are:

    <table class="senf">
    <tr><td>\c Return</td>    <td>bindings::accept</td></tr>
    <tr><td>\c Right</td>     <td>bindings::forwardChar</td></tr>
    <tr><td>\c Left</td>      <td>bindings::backwardChar</td></tr>
    <tr><td>\c Up</td>        <td>bindings::prevHistory</td></tr>
    <tr><td>\c Down</td>      <td>bindings::nextHistory</td></tr>
    <tr><td>\c Backspace</td> <td>bindings::backwardDeleteChar</td></tr>
    <tr><td>\c Delete</td>    <td>bindings::deleteChar</td></tr>
    <tr><td>\c Home</td>      <td>bindings::beginningOfLine</td></tr>
    <tr><td>\c End</td>       <td>bindings::endOfLine</td></tr>
    <tr><td>\c Ctrl-K</td>    <td>bindings::deleteToEndOfLine</td></tr>
    <tr><td>\c Ctrl-A</td>    <td>bindings::beginningOfLine</td></tr>
    <tr><td>\c Ctrl-E</td>    <td>bindings::endOfLine</td></tr>
    <tr><td>\c Ctrl-D</td>    <td>bindings::deleteChar</td></tr>
    <tr><td>\c Ctrl-C</td>    <td>bindings::restartEdit</td></tr>
    <tr><td>\c Ctrl-L</td>    <td>bindings::clearScreen</td></tr>
    </table>

    See the senf::term::bindings namespace for a list of all default provided key binding
    functions.

Completion support

    Completion support is provided by senf::term::bindings::complete(). To use the completer,
    you need to implement a completion function and pass it as second argument to
    bindings::complete():

void myCompleter(senf::term::LineEditor & editor, unsigned & b, unsigned & e,
                 std::string & prefix, std::vector<std::string> & completions)
{
    // Get text to complete
    std::string text (editor.text().substr(b, e-b));
    // Return possible completions in 'completions' array
    completions.push_back( ... );
}
senf::term::LineEditor editor (...);
editor.defineKey(senf::term::KeyParser::TAB,
                 boost::bind(&senf::term::bindings::complete, _1, &myCompleter));

    When \c myCompleter is a class member, use senf::membind() and pass this instead of \c
    &myCompleter to \c boost::bind() and thus to senf::term::bindings::complete.

    The completion protocol is as follows: When completion is desired, the completer function is
    called. \a b and \a e are set to 0 and <tt>editor.point()</tt> respectively. \a prefix and
    \a completions are empty.

    \li the completer may restrict the to-be-completed string to any subrange by changing \a b
        and \a e accordingly.
    \li If there is an initial substring which applies to \e all completions but should not be
        listed in the list of completions, assign this value to \a prefix.
    \li Add all possible completions to the \a completions vector not including the \a prefix.
    \li The completion result is taken from the size of the \a completions vector \e only: If
        this vector is empty, completion failed (even if \a prefix is set), a single entry in \a
        completions (even if it is the empty string) signals a unique completion.

The aux display area

    The auxiliary display area is accessed using auxDisplay() and clearAuxDisplay(). The aux
    display area is \e cleared \e before each new key is processed. Therefore it is only
    temporary. The aux display area however will survive hide() / show().

Temporarily disabling the editor

    Calling hide() will temporarily disable the editor. All editor display will be
    removed. Calling show() will redisplay the editor in it's current state including the aux
    display area.

Definition at line 202 of file Editor.hh.

Member Typedef Documentation

◆ AcceptCallback

typedef boost::function<void (std::string const &)> senf::term::LineEditor::AcceptCallback

Callback function type.

Definition at line 210 of file Editor.hh.

◆ KeyBinding

typedef boost::function<void (LineEditor&)> senf::term::LineEditor::KeyBinding

Type of a key binding function.

Definition at line 209 of file Editor.hh.

Constructor & Destructor Documentation

◆ LineEditor()

senf::term::LineEditor::LineEditor	(	AbstractTerminal &	terminal,
		AcceptCallback	cb
	)

Create a LineEditor.

Parameters

[in]	terminal	abstract terminal interface
[in]	cb	callback to call for complete input line

Definition at line 271 of file Editor.cc.

Member Function Documentation

◆ accept()

void senf::term::LineEditor::accept ( )

Accept current user input and call the accept callback.

Definition at line 338 of file Editor.cc.

◆ auxDisplay()

void senf::term::LineEditor::auxDisplay	(	unsigned	line,
		std::string const &	text
	)

Display text on aux display line line.

Definition at line 463 of file Editor.cc.

◆ clear()

void senf::term::LineEditor::clear ( )

Clear editor buffer.

Definition at line 348 of file Editor.cc.

◆ clearAuxDisplay()

void senf::term::LineEditor::clearAuxDisplay ( )

Clear the aux display area.

Definition at line 478 of file Editor.cc.

◆ defineKey()

void senf::term::LineEditor::defineKey	(	keycode_t	key,
		KeyBinding	binding
	)

Bind key key to binding.

Definition at line 504 of file Editor.cc.

◆ deleteChar()

void senf::term::LineEditor::deleteChar ( unsigned n = 1 )

Delete n characters at point.

Definition at line 405 of file Editor.cc.

◆ displayPos()

unsigned senf::term::LineEditor::displayPos ( )

Get current display position.

Definition at line 494 of file Editor.cc.

◆ forceRedisplay()

void senf::term::LineEditor::forceRedisplay ( )

Redisplay the editor buffer now.

Definition at line 359 of file Editor.cc.

◆ gotoChar()

void senf::term::LineEditor::gotoChar ( unsigned n )

Move cursor to position n.

Definition at line 381 of file Editor.cc.

◆ hide()

void senf::term::LineEditor::hide ( )

Disable editor widget.

Definition at line 329 of file Editor.cc.

◆ insert() [1/2]

void senf::term::LineEditor::insert ( char ch )

Insert ch at point.

Definition at line 413 of file Editor.cc.

◆ insert() [2/2]

void senf::term::LineEditor::insert ( std::string const & text )

Insert text at point.

Definition at line 420 of file Editor.cc.

◆ lastKey()

senf::term::LineEditor::keycode_t senf::term::LineEditor::lastKey ( )

Get last key code received.

Definition at line 499 of file Editor.cc.

◆ maxAuxDisplayHeight()

unsigned senf::term::LineEditor::maxAuxDisplayHeight ( )

Get maximum height of the aux display area.

Definition at line 473 of file Editor.cc.

◆ nextHistory()

void senf::term::LineEditor::nextHistory ( )

Switch to next history entry.

Definition at line 449 of file Editor.cc.

◆ point()

unsigned senf::term::LineEditor::point ( )

Get current cursor position.

Definition at line 489 of file Editor.cc.

◆ prevHistory()

void senf::term::LineEditor::prevHistory ( )

Switch to previous history entry.

Definition at line 440 of file Editor.cc.

◆ prompt()

void senf::term::LineEditor::prompt ( std::string const & text )

Set prompt string.

Definition at line 293 of file Editor.cc.

◆ pushHistory()

void senf::term::LineEditor::pushHistory	(	std::string const &	text,
		bool	accept = `false`
	)

Add string text to history.

Definition at line 427 of file Editor.cc.

◆ redisplay()

void senf::term::LineEditor::redisplay ( )

Mark the editor buffer for redisplay.

Definition at line 354 of file Editor.cc.

◆ scrollTo()

void senf::term::LineEditor::scrollTo ( unsigned n )

Move position
to beginning of display line.

Definition at line 393 of file Editor.cc.

◆ set()

void senf::term::LineEditor::set	(	std::string const &	text,
		unsigned	pos = `0u`
	)

Set edit buffer contents.

The edit buffer contents will be replaced by text. The cursor will be placed at position pos within this text.

Definition at line 304 of file Editor.cc.

◆ show()

void senf::term::LineEditor::show ( )

Enable editor widget.

Definition at line 316 of file Editor.cc.

◆ text()

std::string const & senf::term::LineEditor::text ( )

Get current editor buffer contents.

Definition at line 484 of file Editor.cc.

◆ unsetKey()

void senf::term::LineEditor::unsetKey ( keycode_t key )

Remove all bindings for key.

Definition at line 509 of file Editor.cc.

Member Data Documentation

◆ MAX_HISTORY_SIZE

unsigned const senf::term::LineEditor::MAX_HISTORY_SIZE = 1024u

static

Definition at line 213 of file Editor.hh.

The documentation for this class was generated from the following files:

SENF Extensible Network Framework

Public Types

Public Member Functions

Static Public Attributes

Overall edit control

Cursor and display movement

Text manipulation

History

Aux Display

Get information

Key bindings