Skip to content
GitLab
Commit 340670df authored by Robert Knight's avatar Robert Knight
Browse files

Additional API documentation, for Screen class in particular. 

svn path=/trunk/KDE/kdebase/apps/konsole/; revision=712660
parent 9a7e5667
Hide whitespace changes
Inline Side-by-side
src/EditProfileDialog.h
View file @ 340670df
......@@ -56,8 +56,6 @@ class Profile;
* the SessionManager's changeProfile() method to be called with
* the persistant argument set to false. These changes are then
* un-done when the dialog is closed.
*
* TODO: More documentation
*/
class EditProfileDialog : public KDialog
{
......
src/Profile.h
View file @ 340670df
......@@ -39,7 +39,17 @@ namespace Konsole
/**
* Represents a terminal set-up which can be used to
* set the initial state of new terminal sessions or applied
* to existing sessions.
* to existing sessions. Profiles consist of a number of named
* properties, which can be retrieved using property() and
* set using setProperty(). isPropertySet() can be used to check
* whether a particular property has been set in a profile.
*
* Profiles support a simple form of inheritance. When a new Profile
* is constructed, a pointer to a parent profile can be passed to
* the constructor. When querying a particular property of a profile
* using property(), the profile will return its own value for that
* property if one has been set or otherwise it will return the
* parent's value for that property.
*
* Profiles can be loaded from disk using ProfileReader instances
* and saved to disk using ProfileWriter instances.
......
src/Screen.cpp
View file @ 340670df
......@@ -177,10 +177,6 @@ void Screen::cursorRight(int n)
cuX = qMin(columns-1,cuX+n);
}
/*!
Set top and bottom margin.
*/
void Screen::setMargins(int top, int bot)
//=STBM
{
......@@ -208,13 +204,6 @@ int Screen::bottomMargin() const
return bmargin;
}
/*!
Move the cursor down one line.
If cursor is on bottom margin, the region between the
actual top and bottom margin is scrolled up instead.
*/
void Screen::index()
//=IND
{
......@@ -226,13 +215,6 @@ void Screen::index()
cuY += 1;
}
/*!
Move the cursor up one line.
If cursor is on the top margin, the region between the
actual top and bottom margin is scrolled down instead.
*/
void Screen::reverseIndex()
//=RI
{
......@@ -255,16 +237,6 @@ void Screen::NextLine()
Return(); index();
}
// Line Editing ----------------------------------------------------------------
/*! \section inserting / deleting characters
*/
/*! erase `n' characters starting from (including) the cursor position.
The line is filled in from the right with spaces.
*/
void Screen::eraseChars(int n)
{
if (n == 0) n = 1; // Default
......@@ -272,11 +244,6 @@ void Screen::eraseChars(int n)
clearImage(loc(cuX,cuY),loc(p,cuY),' ');
}
/*! delete `n' characters starting from (including) the cursor position.
The line is filled in from the right with spaces.
*/
void Screen::deleteChars(int n)
{
Q_ASSERT( n >= 0 );
......@@ -298,11 +265,6 @@ void Screen::deleteChars(int n)
screenLines[cuY].remove(cuX,n);
}
/*! insert `n' spaces at the cursor position.
The cursor is not moved by the operation.
*/
void Screen::insertChars(int n)
{
if (n == 0) n = 1; // Default
......@@ -316,11 +278,6 @@ void Screen::insertChars(int n)
screenLines[cuY].resize(columns);
}
/*! delete `n' lines starting from (including) the cursor position.
The cursor is not moved by the operation.
*/
void Screen::deleteLines(int n)
{
if (n == 0) n = 1; // Default
......@@ -376,15 +333,11 @@ void Screen::restoreMode(int m)
currParm.mode[m] = saveParm.mode[m];
}
//NOTE: this is a helper function
/*! Return the setting a specific mode. */
bool Screen::getMode(int m)
{
return currParm.mode[m];
}
/*! Save the cursor position and the rendition attribute settings. */
void Screen::saveCursor()
{
sa_cuX = cuX;
......@@ -394,8 +347,6 @@ void Screen::saveCursor()
sa_cu_bg = cu_bg;
}
/*! Restore the cursor position and the rendition attribute settings. */
void Screen::restoreCursor()
{
cuX = qMin(sa_cuX,columns-1);
......@@ -680,9 +631,6 @@ void Screen::clear()
home();
}
/*! Moves the cursor left one column.
*/
void Screen::BackSpace()
{
cuX = qMin(columns-1,cuX); // nowrap!
......@@ -695,9 +643,6 @@ void Screen::BackSpace()
if (BS_CLEARS) screenLines[cuY][cuX].character = ' ';
}
/*!
*/
void Screen::Tabulate(int n)
{
// note that TAB is a format effector (does not write ' ');
......@@ -934,14 +879,11 @@ void Screen::scrollDown(int from, int n)
clearImage(loc(0,from),loc(columns-1,from+n-1),' ');
}
/*! position the cursor to a specific line and column. */
void Screen::setCursorYX(int y, int x)
{
setCursorY(y); setCursorX(x);
}
/*! Set the cursor to x-th line. */
void Screen::setCursorX(int x)
{
if (x == 0) x = 1; // Default
......@@ -949,8 +891,6 @@ void Screen::setCursorX(int x)
cuX = qMax(0,qMin(columns-1, x));
}
/*! Set the cursor to y-th line. */
void Screen::setCursorY(int y)
{
if (y == 0) y = 1; // Default
......@@ -958,34 +898,22 @@ void Screen::setCursorY(int y)
cuY = qMax(0,qMin(lines -1, y + (getMode(MODE_Origin) ? tmargin : 0) ));
}
/*! set cursor to the `left upper' corner of the screen (1,1).
*/
void Screen::home()
{
cuX = 0;
cuY = 0;
}
/*! set cursor to the begin of the current line.
*/
void Screen::Return()
{
cuX = 0;
}
/*! returns the current cursor columns.
*/
int Screen::getCursorX() const
{
return cuX;
}
/*! returns the current cursor line.
*/
int Screen::getCursorY() const
{
return cuY;
......@@ -1144,25 +1072,16 @@ void Screen::moveImage(int dest, int sourceBegin, int sourceEnd)
}
}
/*! clear from (including) current cursor position to end of screen.
*/
void Screen::clearToEndOfScreen()
{
clearImage(loc(cuX,cuY),loc(columns-1,lines-1),' ');
}
/*! clear from begin of screen to (including) current cursor position.
*/
void Screen::clearToBeginOfScreen()
{
clearImage(loc(0,0),loc(cuX,cuY),' ');
}
/*! clear the entire screen.
*/
void Screen::clearEntireScreen()
{
// Add entire screen to history
......@@ -1183,55 +1102,33 @@ void Screen::helpAlign()
clearImage(loc(0,0),loc(columns-1,lines-1),'E');
}
/*! clear from (including) current cursor position to end of current cursor line.
*/
void Screen::clearToEndOfLine()
{
clearImage(loc(cuX,cuY),loc(columns-1,cuY),' ');
}
/*! clear from begin of current cursor line to (including) current cursor position.
*/
void Screen::clearToBeginOfLine()
{
clearImage(loc(0,cuY),loc(cuX,cuY),' ');
}
/*! clears entire current cursor line
*/
void Screen::clearEntireLine()
{
clearImage(loc(0,cuY),loc(columns-1,cuY),' ');
}
// Rendition ------------------------------------------------------------------
/*!
set rendition mode
*/
void Screen::setRendition(int re)
{
cu_re |= re;
effectiveRendition();
}
/*!
reset rendition mode
*/
void Screen::resetRendition(int re)
{
cu_re &= ~re;
effectiveRendition();
}
/*!
*/
void Screen::setDefaultRendition()
{
setForeColor(COLOR_SPACE_DEFAULT,DEFAULT_FORE_COLOR);
......@@ -1240,8 +1137,6 @@ void Screen::setDefaultRendition()
effectiveRendition();
}
/*!
*/
void Screen::setForeColor(int space, int color)
{
cu_fg = CharacterColor(space, color);
......@@ -1252,8 +1147,6 @@ void Screen::setForeColor(int space, int color)
setForeColor(COLOR_SPACE_DEFAULT,DEFAULT_FORE_COLOR);
}
/*!
*/
void Screen::setBackColor(int space, int color)
{
cu_bg = CharacterColor(space, color);
......
src/Screen.h
View file @ 340670df
......@@ -82,102 +82,264 @@ public:
Screen(int lines, int columns);
~Screen();
public: // these are all `Screen' operations
//
// VT100/2 Operations ------------------
//
// VT100/2 Operations
// Cursor Movement
//
/** Move the cursor up by @p n lines. */
void cursorUp (int n);
/** Move the cursor down by @p n lines. */
void cursorDown (int n);
/** Move the cursor to the left by @p n columns. */
void cursorLeft (int n);
/** Move the cursor to the right by @p n columns. */
void cursorRight (int n);
/** Position the cursor on line @p y. */
void setCursorY (int y);
/** Position the cursor at column @p x. */
void setCursorX (int x);
/** Position the cursor at line @p y, column @p x. */
void setCursorYX (int y, int x);
/**
* Sets the margins for scrolling the screen.
*
* @param topLine The top line of the new scrolling margin.
* @param bottomLine The bottom line of the new scrolling margin.
*/
void setMargins (int topLine , int bottomLine);
/** Returns the top line of the scrolling region. */
int topMargin() const;
/** Returns the bottom line of the scrolling region. */
int bottomMargin() const;
//sets the scrolling margins back to their default positions
/**
* Resets the scrolling margins back to the top and bottom lines
* of the screen.
*/
void setDefaultMargins();
//
// Cursor Movement with Scrolling
//
/**
* 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.
*/
void NewLine ();
/**
* Moves the cursor down one line and positions it at the beginning
* of the line.
*/
void NextLine ();
/**
* 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.
*/
void index ();
/**
* 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.
*/
void reverseIndex();
//
// Scrolling
//
/**
* Scroll the scrolling region of the screen up by @p n lines.
* The scrolling region is initially the whole screen, but can be changed
* using setMargins()
*/
void scrollUp(int n);
/**
* Scroll the scrolling region of the screen down by @p n lines.
* The scrolling region is initially the whole screen, but can be changed
* using setMargins()
*/
void scrollDown(int n);
//
/**
* Moves the cursor to the beginning of the current line.
* Equivalent to setCursorX(0)
*/
void Return ();
/**
* Moves the cursor one column to the left and erases the character
* at the new cursor position.
*/
void BackSpace ();
/**
* Moves the cursor @p n tab-stops to the right.
*/
void Tabulate (int n = 1);
/**
* Moves the cursor @p n tab-stops to the left.
*/
void backTabulate(int n);
//
// Editing
//
/**
* Erase @p n characters beginning from the current cursor position.
* This is equivalent to over-writing @p n characters starting with the current
* cursor position with spaces.
* If @p n is 0 then one character is erased.
*/
void eraseChars (int n);
/**
* Delete @p n characters beginning from the current cursor position.
* If @p n is 0 then one character is deleted.
*/
void deleteChars (int n);
/**
* Insert @p n blank characters beginning from the current cursor position.
* The position of the cursor is not altered.
* If @p n is 0 then one character is inserted.
*/
void insertChars (int n);
void deleteLines (int n);
/**
* Removes @p n lines beginning from the current cursor position.
* The position of the cursor is not altered.
* If @p n is 0 then one line is removed.
*/
void deleteLines (int n);
/**
* Inserts @p lines beginning from the current cursor position.
* The position of the cursor is not altered.
* If @p n is 0 then one line is inserted.
*/
void insertLines (int n);
//
// -------------------------------------
//
/** Clears all the tab stops. */
void clearTabStops();
/** Sets or removes a tab stop at the cursor's current column. */
void changeTabStop(bool set);
//
void resetMode (int n);
void setMode (int n);
void saveMode (int n);
void restoreMode (int n);
//
/** Resets (clears) the specified screen @p mode. */
void resetMode (int mode);
/** Sets (enables) the specified screen @p mode. */
void setMode (int mode);
/**
* Saves the state of the specified screen @p mode. It can be restored
* using restoreMode()
*/
void saveMode (int mode);
/** Restores the state of a screen @p mode saved by calling saveMode() */
void restoreMode (int mode);
/** Returns whether the specified screen @p mode is enabled or not .*/
bool getMode (int mode);
/**
* Saves the current position and appearence (text color and style) of the cursor.
* It can be restored by calling restoreCursor()
*/
void saveCursor ();
/** Restores the position and appearence of the cursor. See saveCursor() */
void restoreCursor();
//
// -------------------------------------
//
/** Clear the whole screen, moving the current screen contents into the history first. */
void clearEntireScreen();
/**
* Clear the area of the screen from the current cursor position to the end of
* the screen.
*/
void clearToEndOfScreen();
/**
* Clear the area of the screen from the current cursor position to the start
* of the screen.
*/
void clearToBeginOfScreen();
//
/** Clears the whole of the line on which the cursor is currently positioned. */
void clearEntireLine();
/** Clears from the current cursor position to the end of the line. */
void clearToEndOfLine();
/** Clears from the current cursor position to the beginning of the line. */
void clearToBeginOfLine();
//
/** Fills the entire screen with the letter 'E' */
void helpAlign ();
//
// -------------------------------------
//
/**
* Enables the given @p rendition flag. Rendition flags control the appearence
* of characters on the screen.
*
* @see Character::rendition
*/
void setRendition (int rendition);
/**
* Disables the given @p rendition flag. Rendition flags control the appearence
* of characters on the screen.
*
* @see Character::rendition
*/
void resetRendition(int rendition);
//
/**
* Sets the cursor's foreground color.
* @param space The color space used by the @p color argument
* @param color The new foreground color. The meaning of this depends on
* the color @p space used.
*
* @see CharacterColor
*/
void setForeColor (int space, int color);
/**
* Sets the cursor's background color.
* @param space The color space used by the @p color argumnet.
* @param color The new background color. The meaning of this depends on
* the color @p space used.
*
* @see CharacterColor
*/
void setBackColor (int space, int color);
//
/**
* Resets the cursor's color back to the default and sets the
* character's rendition flags back to the default settings.
*/
void setDefaultRendition();
//
// -------------------------------------
//
bool getMode (int n);
//
// only for report cursor position
//
/** Returns the column which the cursor is positioned at. */
int getCursorX() const;
/** Returns the line which the cursor is positioned on. */
int getCursorY() const;
//
// -------------------------------------
//
void clear();
/**
* Sets the position of the cursor to the 'home' position at the top-left
* corner of the screen (0,0)
*/
void home();
/**
* 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)
*
* <ul>
* <li>Line wrapping is enabled.</li>
* <li>Origin mode is disabled.</li>
* <li>Insert mode is disabled.</li>
* <li>Cursor mode is enabled. TODO Document me</li>
* <li>Screen mode is disabled. TODO Document me</li>
* <li>New line mode is disabled. TODO Document me</li>
* </ul>
*
* If @p clearScreen is true then the screen contents are erased entirely,
* otherwise they are unaltered.
*/
void reset(bool clearScreen = true);
// Show character
/**
* 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.
*/
void ShowCharacter(unsigned short c);
// Do composition with last shown character FIXME: Not implemented yet for KDE 4
......@@ -194,7 +356,11 @@ public: // these are all `Screen' operations
*/
void resizeImage(int new_lines, int new_columns);
// Return current on screen image. Result array is [getLines()][getColumns()]
/**
* 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.
*/
Character* getCookedImage( int line );
/**
......@@ -205,20 +371,26 @@ public: // these are all `Screen' operations
QVector<LineProperty> getCookedLineProperties( int line );
/*! return the number of lines. */
/** Return the number of lines. */
int getLines() { return lines; }
/*! return the number of columns. */
/** Return the number of columns. */
int getColumns() { return columns; }
/** Return the number of lines in the history buffer. */
int getHistLines ();
/**
* Sets the type of storage used to keep lines in the history.
* If @p copyPreviousScroll is true then the contents of the previous