Konsole

Konsole::Screen

Konsole::Screen Class Reference

#include <Screen.h>

Detailed Description

An image of characters with associated attributes.

The terminal emulation ( Emulation ) receives a serial stream of characters from the program currently running in the terminal. From this stream it creates an image of characters which is ultimately rendered by the display widget ( TerminalDisplay ). Some types of emulation may have more than one screen image.

getImage() is used to retrieve the currently visible image which is then used by the display widget to draw the output from the terminal.

The number of lines of output history which are kept in addition to the current screen image depends on the history scroll being used to store the output. The scroll is specified using setScroll() The output history can be retrieved using writeToStream()

The screen image has a selection associated with it, specified using setSelectionStart() and setSelectionEnd(). The selected text can be retrieved using selectedText(). When getImage() is used to retrieve the the visible image, characters which are part of the selection have their colours inverted.

Definition at line 78 of file Screen.h.


Public Member Functions
	Screen (int lines, int columns)
	~Screen ()
void	cursorUp (int n)
void	cursorDown (int n)
void	cursorLeft (int n)
void	cursorRight (int n)
void	setCursorY (int y)
void	setCursorX (int x)
void	setCursorYX (int y, int x)
void	setMargins (int topLine, int bottomLine)
int	topMargin () const
int	bottomMargin () const
void	setDefaultMargins ()
void	NewLine ()
void	NextLine ()
void	index ()
void	reverseIndex ()
void	scrollUp (int n)
void	scrollDown (int n)
void	Return ()
void	BackSpace ()
void	Tabulate (int n=1)
void	backTabulate (int n)
void	eraseChars (int n)
void	deleteChars (int n)
void	insertChars (int n)
void	deleteLines (int n)
void	insertLines (int n)
void	clearTabStops ()
void	changeTabStop (bool set)
void	resetMode (int mode)
void	setMode (int mode)
void	saveMode (int mode)
void	restoreMode (int mode)
bool	getMode (int mode) const
void	saveCursor ()
void	restoreCursor ()
void	clearEntireScreen ()
void	clearToEndOfScreen ()
void	clearToBeginOfScreen ()
void	clearEntireLine ()
void	clearToEndOfLine ()
void	clearToBeginOfLine ()
void	helpAlign ()
void	setRendition (int rendition)
void	resetRendition (int rendition)
void	setForeColor (int space, int color)
void	setBackColor (int space, int color)
void	setDefaultRendition ()
int	getCursorX () const
int	getCursorY () const
void	clear ()
void	home ()
void	reset (bool clearScreen=true)
void	ShowCharacter (unsigned short c)
void	compose (const QString &compose)
void	resizeImage (int new_lines, int new_columns)
void	getImage (Character *dest, int size, int startLine, int endLine) const
QVector< LineProperty >	getLineProperties (int startLine, int endLine) const
int	getLines ()
int	getColumns ()
int	getHistLines ()
void	setScroll (const HistoryType &, bool copyPreviousScroll=true)
const HistoryType &	getScroll ()
bool	hasScroll ()
void	setSelectionStart (const int column, const int line, const bool columnmode)
void	setSelectionEnd (const int column, const int line)
void	getSelectionStart (int &column, int &line)
void	getSelectionEnd (int &column, int &line)
void	clearSelection ()
void	setBusySelecting (bool busy)
bool	isSelected (const int column, const int line) const
QString	selectedText (bool preserveLineBreaks)
void	writeToStream (TerminalCharacterDecoder *decoder, int from, int to)
QString	getHistoryLine (int no)
void	writeSelectionToStream (TerminalCharacterDecoder *decoder, bool preserveLineBreaks=true)
void	checkSelection (int from, int to)
void	setLineProperty (LineProperty property, bool enable)
int	scrolledLines () const
QRect	lastScrolledRegion () const
void	resetScrolledLines ()
int	droppedLines () const
void	resetDroppedLines ()
Static Public Member Functions
static void	fillWithDefaultChar (Character *dest, int count)

Constructor & Destructor Documentation

Screen::Screen	(	int	lines,
		int	columns
	)

Construct a new screen image of size lines by columns.

Definition at line 67 of file Screen.cpp.

Screen::~Screen ( )

Destructor

Definition at line 98 of file Screen.cpp.

Member Function Documentation

void Screen::cursorUp ( int n )

Move the cursor up by n lines.

Cursor

The `cursor' is a location within the screen that is implicitely used in many operations. The operations within this section allow to manipulate the cursor explicitly and to obtain it's value.

The position of the cursor is guarantied to be between (including) 0 and `columns-1' and `lines-1'.

Move the cursor up.

The cursor will not be moved beyond the top margin.

Definition at line 129 of file Screen.cpp.

void Screen::cursorDown ( int n )

Move the cursor down by n lines.

Move the cursor down.

The cursor will not be moved beyond the bottom margin.

Definition at line 144 of file Screen.cpp.

void Screen::cursorLeft ( int n )

Move the cursor to the left by n columns.

Move the cursor left.

The cursor will not move beyond the first column.

Definition at line 159 of file Screen.cpp.

void Screen::cursorRight ( int n )

Move the cursor to the right by n columns.

Move the cursor left.

The cursor will not move beyond the rightmost column.

Definition at line 173 of file Screen.cpp.

void Screen::setCursorY ( int y )

Position the cursor on line y.

Definition at line 919 of file Screen.cpp.

void Screen::setCursorX ( int x )

Position the cursor at column x.

Definition at line 912 of file Screen.cpp.

void Screen::setCursorYX	(	int	y,
		int	x
	)

Position the cursor at line y, column x.

Definition at line 907 of file Screen.cpp.

void Screen::setMargins	(	int	topLine,
		int	bottomLine
	)

Sets the margins for scrolling the screen.

Parameters:

	topLine	The top line of the new scrolling margin.
	bottomLine	The bottom line of the new scrolling margin.

Definition at line 180 of file Screen.cpp.

int Screen::topMargin ( ) const

Returns the top line of the scrolling region.

Definition at line 198 of file Screen.cpp.

int Screen::bottomMargin ( ) const

Returns the bottom line of the scrolling region.

Definition at line 202 of file Screen.cpp.

void Screen::setDefaultMargins ( )

Resets the scrolling margins back to the top and bottom lines of the screen.

Definition at line 422 of file Screen.cpp.

void Screen::NewLine ( )

Moves the cursor down one line, if the MODE_NewLine mode flag is enabled then the cursor is returned to the leftmost column first.

Equivalent to NextLine() if the MODE_NewLine flag is set or index() otherwise.

This behaves either as IND (Screen::Index) or as NEL (Screen::NextLine) depending on the NewLine Mode (LNM). This mode also affects the key sequence returned for newline ([CR]LF).

Definition at line 726 of file Screen.cpp.

void Screen::NextLine ( )

Moves the cursor down one line and positions it at the beginning of the line.

Move the cursor to the begin of the next line.

If cursor is on bottom margin, the region between the actual top and bottom margin is scrolled up.

Definition at line 234 of file Screen.cpp.

void Screen::index ( )

Move the cursor down one line.

If the cursor is on the bottom line of the scrolling region (as returned by bottomMargin()) the scrolling region is scrolled up by one line instead.

Definition at line 207 of file Screen.cpp.

void Screen::reverseIndex ( )

Move the cursor up one line.

If the cursor is on the top line of the scrolling region (as returned by topMargin()) the scrolling region is scrolled down by one line instead.

Definition at line 218 of file Screen.cpp.

void Screen::scrollUp ( int n )

Scroll the scrolling region of the screen up by n lines.

The scrolling region is initially the whole screen, but can be changed using setMargins()

Definition at line 852 of file Screen.cpp.

void Screen::scrollDown ( int n )

Scroll the scrolling region of the screen down by n lines.

The scrolling region is initially the whole screen, but can be changed using setMargins()

Definition at line 881 of file Screen.cpp.

void Screen::Return ( )

Moves the cursor to the beginning of the current line.

Equivalent to setCursorX(0)

Definition at line 932 of file Screen.cpp.

void Screen::BackSpace ( )

Moves the cursor one column to the left and erases the character at the new cursor position.

Definition at line 664 of file Screen.cpp.

void Screen::Tabulate ( int n = 1 )

Moves the cursor n tab-stops to the right.

Definition at line 676 of file Screen.cpp.

void Screen::backTabulate ( int n )

Moves the cursor n tab-stops to the left.

Definition at line 687 of file Screen.cpp.

void Screen::eraseChars ( int n )

Erase n characters beginning from the current cursor position.

This is equivalent to over-writing n characters starting with the current cursor position with spaces. If n is 0 then one character is erased.

Definition at line 240 of file Screen.cpp.

void Screen::deleteChars ( int n )

Delete n characters beginning from the current cursor position.

If n is 0 then one character is deleted.

Definition at line 247 of file Screen.cpp.

void Screen::insertChars ( int n )

Insert n blank characters beginning from the current cursor position.

The position of the cursor is not altered. If n is 0 then one character is inserted.

Definition at line 268 of file Screen.cpp.

void Screen::deleteLines ( int n )

Removes n lines beginning from the current cursor position.

The position of the cursor is not altered. If n is 0 then one line is removed.

Definition at line 281 of file Screen.cpp.

void Screen::insertLines ( int n )

Inserts lines beginning from the current cursor position.

The position of the cursor is not altered. If n is 0 then one line is inserted.

insert `n' lines at the cursor position.

The cursor is not moved by the operation.

Definition at line 292 of file Screen.cpp.

void Screen::clearTabStops ( )

Clears all the tab stops.

Definition at line 698 of file Screen.cpp.

void Screen::changeTabStop ( bool set )

Sets or removes a tab stop at the cursor's current column.

Definition at line 703 of file Screen.cpp.

void Screen::resetMode ( int m )

Resets (clears) the specified screen mode.

Reset a specific mode.

Definition at line 313 of file Screen.cpp.

void Screen::setMode ( int m )

Sets (enables) the specified screen mode.

Set a specific mode.

Definition at line 302 of file Screen.cpp.

void Screen::saveMode ( int m )

Saves the state of the specified screen mode.

It can be restored using restoreMode()

Save a specific mode.

Definition at line 324 of file Screen.cpp.

void Screen::restoreMode ( int m )

Restores the state of a screen mode saved by calling saveMode().

Restore a specific mode.

Definition at line 331 of file Screen.cpp.

bool Screen::getMode ( int mode ) const

Returns whether the specified screen mode is enabled or not .

Definition at line 336 of file Screen.cpp.

void Screen::saveCursor ( )

Saves the current position and appearence (text color and style) of the cursor.

It can be restored by calling restoreCursor()

Definition at line 341 of file Screen.cpp.

void Screen::restoreCursor ( )

Restores the position and appearence of the cursor.

See saveCursor()

Definition at line 350 of file Screen.cpp.

void Screen::clearEntireScreen ( )

Clear the whole screen, moving the current screen contents into the history first.

Definition at line 1110 of file Screen.cpp.

void Screen::clearToEndOfScreen ( )

Clear the area of the screen from the current cursor position to the end of the screen.

Definition at line 1100 of file Screen.cpp.

void Screen::clearToBeginOfScreen ( )

Clear the area of the screen from the current cursor position to the start of the screen.

Definition at line 1105 of file Screen.cpp.

void Screen::clearEntireLine ( )

Clears the whole of the line on which the cursor is currently positioned.

Definition at line 1140 of file Screen.cpp.

void Screen::clearToEndOfLine ( )

Clears from the current cursor position to the end of the line.

Definition at line 1130 of file Screen.cpp.

void Screen::clearToBeginOfLine ( )

Clears from the current cursor position to the beginning of the line.

Definition at line 1135 of file Screen.cpp.

void Screen::helpAlign ( )

Fills the entire screen with the letter 'E'.

fill screen with 'E' This is to aid screen alignment

Definition at line 1125 of file Screen.cpp.

void Screen::setRendition ( int rendition )

Enables the given rendition flag.

Rendition flags control the appearence of characters on the screen.

See also:: Character::rendition

Definition at line 1145 of file Screen.cpp.

void Screen::resetRendition ( int rendition )

Disables the given rendition flag.

Rendition flags control the appearence of characters on the screen.

See also:: Character::rendition

Definition at line 1151 of file Screen.cpp.

void Screen::setForeColor	(	int	space,
		int	color
	)

Sets the cursor's foreground color.

Parameters:

	space	The color space used by the `color` argument
	color	The new foreground color. The meaning of this depends on the color `space` used.

See also:: CharacterColor

Definition at line 1165 of file Screen.cpp.

void Screen::setBackColor	(	int	space,
		int	color
	)

Sets the cursor's background color.

Parameters:

	space	The color space used by the `color` argumnet.
	color	The new background color. The meaning of this depends on the color `space` used.

See also:: CharacterColor

Definition at line 1175 of file Screen.cpp.

void Screen::setDefaultRendition ( )

Resets the cursor's color back to the default and sets the character's rendition flags back to the default settings.

Definition at line 1157 of file Screen.cpp.

int Screen::getCursorX ( ) const

Returns the column which the cursor is positioned at.

Definition at line 937 of file Screen.cpp.

int Screen::getCursorY ( ) const

Returns the line which the cursor is positioned on.

Definition at line 942 of file Screen.cpp.

void Screen::clear ( )

TODO Document me.

Clear the entire screen and home the cursor.

Definition at line 658 of file Screen.cpp.

void Screen::home ( )

Sets the position of the cursor to the 'home' position at the top-left corner of the screen (0,0).

Definition at line 926 of file Screen.cpp.

void Screen::reset ( bool clearScreen = true )

Resets the state of the screen.

This resets the various screen modes back to their default states. The cursor style and colors are reset (as if setDefaultRendition() had been called)

Line wrapping is enabled.
Origin mode is disabled.
Insert mode is disabled.
Cursor mode is enabled. TODO Document me
Screen mode is disabled. TODO Document me
New line mode is disabled. TODO Document me

If clearScreen is true then the screen contents are erased entirely, otherwise they are unaltered.

Definition at line 636 of file Screen.cpp.

void Screen::ShowCharacter ( unsigned short c )

Displays a new character at the current cursor position.

If the cursor is currently positioned at the right-edge of the screen and line wrapping is enabled then the character is added at the start of a new line below the current one.

If the MODE_Insert screen mode is currently enabled then the character is inserted at the current cursor position, otherwise it will replace the character already at the current cursor position.

Definition at line 749 of file Screen.cpp.

void Screen::compose ( const QString & compose )

Definition at line 818 of file Screen.cpp.

void Screen::resizeImage	(	int	new_lines,
		int	new_columns
	)

Resizes the image to a new fixed size of new_lines by new_columns.

In the case that new_columns is smaller than the current number of columns, existing lines are not truncated. This prevents characters from being lost if the terminal display is resized smaller and then larger again.

(note that in versions of Konsole prior to KDE 4, existing lines were truncated when making the screen image smaller)

Resize the screen image

The topmost left position is maintained, while lower lines or right hand side columns might be removed or filled with spaces to fit the new size.

The region setting is reset to the whole screen and the tab positions reinitialized.

If the new image is narrower than the old image then text on lines which extends past the end of the new image is preserved so that it becomes visible again if the screen is later resized to make it larger.

Definition at line 380 of file Screen.cpp.

void Screen::getImage	(	Character *	dest,
		int	size,
		int	startLine,
		int	endLine
	)			const

Returns the current screen image.

The result is an array of Characters of size [getLines()][getColumns()] which must be freed by the caller after use.

Parameters:

	dest	Buffer to copy the characters into
	size	Size of `dest` in Characters
	startLine	Index of first line to copy
	endLine	Index of last line to copy

Definition at line 564 of file Screen.cpp.

QVector< LineProperty > Screen::getLineProperties	(	int	startLine,
		int	endLine
	)			const

Returns the additional attributes associated with lines in the image.

The most important attribute is LINE_WRAPPED which specifies that the line is wrapped, other attributes control the size of characters in the line.

Definition at line 599 of file Screen.cpp.

int Konsole::Screen::getLines ( ) [inline]

Return the number of lines.

Definition at line 380 of file Screen.h.

int Konsole::Screen::getColumns ( ) [inline]

Return the number of columns.

Definition at line 382 of file Screen.h.

int Screen::getHistLines ( )

Return the number of lines in the history buffer.

Definition at line 1519 of file Screen.cpp.

void Screen::setScroll	(	const HistoryType &	t,
		bool	copyPreviousScroll = `true`
	)

Sets the type of storage used to keep lines in the history.

If copyPreviousScroll is true then the contents of the previous history buffer are copied into the new scroll.

Definition at line 1524 of file Screen.cpp.

const HistoryType & Screen::getScroll ( )

Returns the type of storage used to keep lines in the history.

Definition at line 1543 of file Screen.cpp.

bool Screen::hasScroll ( )

Returns true if this screen keeps lines that are scrolled off the screen in a history buffer.

Definition at line 1538 of file Screen.cpp.

void Screen::setSelectionStart	(	const int	column,
		const int	line,
		const bool	columnmode
	)

Sets the start of the selection.

Parameters:

	column	The column index of the first character in the selection.
	line	The line index of the first character in the selection.
	columnmode	True if the selection is in column mode.

Definition at line 1224 of file Screen.cpp.

void Screen::setSelectionEnd	(	const int	column,
		const int	line
	)

Sets the end of the current selection.

Parameters:

	column	The column index of the last character in the selection.
	line	The line index of the last character in the selection.

Definition at line 1237 of file Screen.cpp.

void Screen::getSelectionStart	(	int &	column,
		int &	line
	)

Retrieves the start of the selection or the cursor position if there is no selection.

Definition at line 1198 of file Screen.cpp.

void Screen::getSelectionEnd	(	int &	column,
		int &	line
	)

Retrieves the end of the selection or the cursor position if there is no selection.

Definition at line 1211 of file Screen.cpp.

void Screen::clearSelection ( )

Clears the current selection.

Definition at line 1191 of file Screen.cpp.

void Konsole::Screen::setBusySelecting ( bool busy ) [inline]

Definition at line 431 of file Screen.h.

bool Screen::isSelected	(	const int	column,
		const int	line
	)			const

Returns true if the character at (column, line) is part of the current selection.

Definition at line 1258 of file Screen.cpp.

QString Screen::selectedText ( bool preserveLineBreaks )

Convenience method.

Returns the currently selected text.

Parameters:

preserveLineBreaks

Specifies whether new line characters should be inserted into the returned text at the end of each terminal line.

Definition at line 1278 of file Screen.cpp.

void Screen::writeToStream	(	TerminalCharacterDecoder *	decoder,
		int	from,
		int	to
	)

Copies part of the output to a stream.

Parameters:

	decoder	A decoder which coverts terminal characters into text
	from	The first line in the history to retrieve
	to	The last line in the history to retrieve

Definition at line 1441 of file Screen.cpp.

QString Screen::getHistoryLine ( int no )

Sets the selection to line no in the history and returns the text of that line from the history buffer.

Definition at line 1450 of file Screen.cpp.

void Screen::writeSelectionToStream	(	TerminalCharacterDecoder *	decoder,
		bool	preserveLineBreaks = `true`
	)

Copies the selected characters, set using.

See also:: setSelBeginXY and
setSelExtentXY into a stream.

Parameters:

	decoder	A decoder which converts terminal characters into text. PlainTextDecoder is the most commonly used decoder which coverts characters into plain text with no formatting.
	preserveLineBreaks	Specifies whether new line characters should be inserted into the returned text at the end of each terminal line.

Definition at line 1296 of file Screen.cpp.

void Screen::checkSelection	(	int	from,
		int	to
	)

TODO Document me.

put `c' literally onto the screen at the current cursor position.

VT100 uses the convention to produce an automatic newline (am) with the *first* character that would fall onto the next line (xenl).

Definition at line 738 of file Screen.cpp.

void Screen::setLineProperty	(	LineProperty	property,
		bool	enable
	)

Sets or clears an attribute of the current line.

Parameters:

	property	The attribute to set or clear Possible properties are: LINE_WRAPPED: Specifies that the line is wrapped. LINE_DOUBLEWIDTH: Specifies that the characters in the current line should be double the normal width. LINE_DOUBLEHEIGHT:Specifies that the characters in the current line should be double the normal height. Double-height lines are formed of two lines containing the same characters, with both having the LINE_DOUBLEHEIGHT attribute. This allows other parts of the code to work on the assumption that all lines are the same height.
	enable	true to apply the attribute to the current line or false to remove it

Definition at line 1548 of file Screen.cpp.

int Screen::scrolledLines ( ) const

Returns the number of lines that the image has been scrolled up or down by, since the last call to resetScrolledLines().

a positive return value indicates that the image has been scrolled up, a negative return value indicates that the image has been scrolled down.

Definition at line 831 of file Screen.cpp.

QRect Screen::lastScrolledRegion ( ) const

Returns the region of the image which was last scrolled.

This is the area of the image from the top margin to the bottom margin when the last scroll occurred.

scroll up `n' lines within current region. The `n' new lines are cleared.

See also:: setRegion
scrollDown

Definition at line 864 of file Screen.cpp.

void Screen::resetScrolledLines ( )

Resets the count of the number of lines that the image has been scrolled up or down by, see scrolledLines().

Definition at line 843 of file Screen.cpp.

int Screen::droppedLines ( ) const

Returns the number of lines of output which have been dropped from the history since the last call to resetDroppedLines().

If the history is not unlimited then it will drop the oldest lines of output if new lines are added when it is full.

Definition at line 835 of file Screen.cpp.

void Screen::resetDroppedLines ( )

Resets the count of the number of lines dropped from the history.

Definition at line 839 of file Screen.cpp.

void Screen::fillWithDefaultChar	(	Character *	dest,
		int	count
	)			`[static]`

Fills the buffer dest with count instances of the default (ie.

blank) Character style.

Definition at line 1559 of file Screen.cpp.

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

Konsole

Konsole::Screen Class Reference

Detailed Description

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation

Cursor

Konsole

API Reference