senf::term::LineEditor Class Reference

Single line interactive text editor. More...

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

Inheritance diagram for senf::term::LineEditor:

[legend]

List of all 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:

`Return`	bindings::accept
`Right`	bindings::forwardChar
`Left`	bindings::backwardChar
`Up`	bindings::prevHistory
`Down`	bindings::nextHistory
`Backspace`	bindings::backwardDeleteChar
`Delete`	bindings::deleteChar
`Home`	bindings::beginningOfLine
`End`	bindings::endOfLine
`Ctrl-K`	bindings::deleteToEndOfLine
`Ctrl-A`	bindings::beginningOfLine
`Ctrl-E`	bindings::endOfLine
`Ctrl-D`	bindings::deleteChar
`Ctrl-C`	bindings::restartEdit
`Ctrl-L`	bindings::clearScreen

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 myCompleter is a class member, use senf::membind() and pass this instead of &myCompleter to boost::bind() and thus to senf::term::bindings::complete.

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

the completer may restrict the to-be-completed string to any subrange by changing b and e accordingly.
If there is an initial substring which applies to all completions but should not be listed in the list of completions, assign this value to prefix.
Add all possible completions to the completions vector not including the prefix.
The completion result is taken from the size of the completions vector only: If this vector is empty, completion failed (even if prefix is set), a single entry in 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 cleared 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 211 of file Editor.hh.


Public Types
typedef boost::function< void(LineEditor &)>	KeyBinding
	Type of a key binding function.
typedef boost::function< void(std::string const &)>	AcceptCallback
	Callback function type.
Public Member Functions
	LineEditor (AbstractTerminal &terminal, AcceptCallback cb)
	Create a LineEditor.
Static Public Attributes
static unsigned const	MAX_HISTORY_SIZE = 1024u
Overall edit control
void	show ()
	Enable editor widget.
void	hide ()
	Disable editor widget.
void	accept ()
	Accept current user input and call the accept callback.
void	clear ()
	Clear editor buffer.
void	redisplay ()
	Mark the editor buffer for redisplay.
void	forceRedisplay ()
	Redisplay the editor buffer now.
void	prompt (std::string const &text)
	Set prompt string.
Cursor and display movement
void	gotoChar (unsigned n)
	Move cursor to position n.
void	scrollTo (unsigned n)
	Move position to beginning of display line.
Text manipulation
void	deleteChar (unsigned n=1)
	Delete n characters at point.
void	insert (char ch)
	Insert ch at point.
void	insert (std::string const &text)
	Insert text at point.
void	set (std::string const &text, unsigned pos=0u)
	Set edit buffer contents.
History
void	pushHistory (std::string const &text, bool accept=false)
	Add string text to history.
void	prevHistory ()
	Switch to previous history entry.
void	nextHistory ()
	Switch to next history entry.
Aux Display
void	auxDisplay (unsigned line, std::string const &text)
	Display text on aux display line line.
unsigned	maxAuxDisplayHeight ()
	Get maximum height of the aux display area.
void	clearAuxDisplay ()
	Clear the aux display area.
Get information
std::string const &	text ()
	Get current editor buffer contents.
unsigned	point ()
	Get current cursor position.
unsigned	displayPos ()
	Get current display position.
keycode_t	lastKey ()
	Get last key code received.
Key bindings
void	defineKey (keycode_t key, KeyBinding binding)
	Bind key key to binding.
void	unsetKey (keycode_t key)
	Remove all bindings for key.

Member Typedef Documentation

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

Callback function type.

Definition at line 220 of file Editor.hh.

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

Type of a key binding function.

Definition at line 218 of file Editor.hh.

Constructor & Destructor Documentation

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 280 of file Editor.cc.

Member Function Documentation

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

Accept current user input and call the accept callback.

Definition at line 346 of file Editor.cc.

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

Display text on aux display line line.

Definition at line 471 of file Editor.cc.

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

Clear editor buffer.

Definition at line 356 of file Editor.cc.

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

Clear the aux display area.

Definition at line 486 of file Editor.cc.

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

Bind key key to binding.

Definition at line 512 of file Editor.cc.

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

Delete n characters at point.

Definition at line 413 of file Editor.cc.

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

Get current display position.

Definition at line 502 of file Editor.cc.

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

Redisplay the editor buffer now.

Definition at line 367 of file Editor.cc.

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

Move cursor to position n.

Definition at line 389 of file Editor.cc.

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

Disable editor widget.

Definition at line 337 of file Editor.cc.

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

Insert text at point.

Definition at line 428 of file Editor.cc.

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

Insert ch at point.

Definition at line 421 of file Editor.cc.

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

Get last key code received.

Definition at line 507 of file Editor.cc.

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

Get maximum height of the aux display area.

Definition at line 481 of file Editor.cc.

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

Switch to next history entry.

Definition at line 457 of file Editor.cc.

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

Get current cursor position.

Definition at line 497 of file Editor.cc.

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

Switch to previous history entry.

Definition at line 448 of file Editor.cc.

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

Set prompt string.

Definition at line 301 of file Editor.cc.

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

Add string text to history.

Definition at line 435 of file Editor.cc.

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

Mark the editor buffer for redisplay.

Definition at line 362 of file Editor.cc.

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

Move position
to beginning of display line.

Definition at line 401 of file Editor.cc.

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 312 of file Editor.cc.

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

Enable editor widget.

Definition at line 324 of file Editor.cc.

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

Get current editor buffer contents.

Definition at line 492 of file Editor.cc.

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

Remove all bindings for key.

Definition at line 517 of file Editor.cc.

Member Data Documentation

unsigned const senf::term::LineEditor::MAX_HISTORY_SIZE = 1024u
[static]

Definition at line 222 of file Editor.hh.

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

SENF Extensible Network Framework

senf::term::LineEditor Class Reference

Detailed Description

The editor key map

Completion support

The aux display area

Temporarily disabling the editor

Public Types

Public Member Functions

Static Public Attributes

Overall edit control

Cursor and display movement

Text manipulation

History

Aux Display

Get information

Key bindings

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation