From 340670df5b6b8a9ed355f6db185eb12dbead9d1a Mon Sep 17 00:00:00 2001 From: Robert Knight Date: Sat, 15 Sep 2007 00:58:40 +0000 Subject: [PATCH] Additional API documentation, for Screen class in particular. svn path=/trunk/KDE/kdebase/apps/konsole/; revision=712660 --- src/EditProfileDialog.h | 2 - src/Profile.h | 12 +- src/Screen.cpp | 107 --------------- src/Screen.h | 283 ++++++++++++++++++++++++++++++++-------- 4 files changed, 241 insertions(+), 163 deletions(-) diff --git a/src/EditProfileDialog.h b/src/EditProfileDialog.h index cac344d59..0f2072528 100644 --- a/src/EditProfileDialog.h +++ b/src/EditProfileDialog.h @@ -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 { diff --git a/src/Profile.h b/src/Profile.h index 1065228b7..df72aeca0 100644 --- a/src/Profile.h +++ b/src/Profile.h @@ -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. diff --git a/src/Screen.cpp b/src/Screen.cpp index 8bd91aeeb..a095f6e3c 100644 --- a/src/Screen.cpp +++ b/src/Screen.cpp @@ -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); diff --git a/src/Screen.h b/src/Screen.h index 9fe0336f0..c9252bed5 100644 --- a/src/Screen.h +++ b/src/Screen.h @@ -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) + * + * + * + * 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 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 + * history buffer are copied into the new scroll. + */ void setScroll(const HistoryType& , bool copyPreviousScroll = true); + /** Returns the type of storage used to keep lines in the history. */ const HistoryType& getScroll(); + /** + * Returns true if this screen keeps lines that are scrolled off the screen + * in a history buffer. + */ bool hasScroll(); - // - // Selection - // - /** * Sets the start of the selection. * @@ -271,7 +443,11 @@ public: // these are all `Screen' operations * @param to The last line in the history to retrieve */ void writeToStream(TerminalCharacterDecoder* decoder, int from, int to); - + + /** + * Sets the selection to line @p no in the history and returns + * the text of that line from the history buffer. + */ QString getHistoryLine(int no); /** @@ -288,6 +464,7 @@ public: // these are all `Screen' operations void writeSelectionToStream(TerminalCharacterDecoder* decoder , bool preserveLineBreaks = true); + /** TODO Document me */ void checkSelection(int from, int to); /** @@ -347,7 +524,7 @@ public: // these are all `Screen' operations */ void resetDroppedLines(); -private: // helper +private: //copies a line of text from the screen or history into a stream using a specified character decoder //line - the line number to copy, from 0 (the earliest line in the history) up to