GNU Octave  3.8.0
A high-level interpreted language, primarily intended for numerical computations, mostly compatible with Matlab
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Pages
Screen.h
Go to the documentation of this file.
1 /*
2  This file is part of Konsole, KDE's terminal.
3 
4  Copyright (C) 2007, 2013 by Robert Knight <[email protected]>
5  Copyright (C) 1997,1998 by Lars Doelle <[email protected]>
6 
7  Rewritten for QT4 by e_k <e_k at users.sourceforge.net>, Copyright (C)2008
8 
9  This program is free software; you can redistribute it and/or modify
10  it under the terms of the GNU General Public License as published by
11  the Free Software Foundation; either version 2 of the License, or
12  (at your option) any later version.
13 
14  This program is distributed in the hope that it will be useful,
15  but WITHOUT ANY WARRANTY; without even the implied warranty of
16  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17  GNU General Public License for more details.
18 
19  You should have received a copy of the GNU General Public License
20  along with this program; if not, write to the Free Software
21  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
22  02110-1301 USA.
23 */
24 
25 #ifndef SCREEN_H
26 #define SCREEN_H
27 
28 // Qt
29 #include <QtCore/QRect>
30 #include <QtCore/QTextStream>
31 #include <QtCore/QVarLengthArray>
32 
33 // Konsole
34 #include "unix/Character.h"
35 #include "unix/History.h"
36 
37 #define MODE_Origin 0
38 #define MODE_Wrap 1
39 #define MODE_Insert 2
40 #define MODE_Screen 3
41 #define MODE_Cursor 4
42 #define MODE_NewLine 5
43 #define MODES_SCREEN 6
44 
45 struct ScreenParm
46 {
48 };
49 
51 
52 /**
53  \brief An image of characters with associated attributes.
54 
55  The terminal emulation ( Emulation ) receives a serial stream of
56  characters from the program currently running in the terminal.
57  From this stream it creates an image of characters which is ultimately
58  rendered by the display widget ( TerminalDisplay ). Some types of emulation
59  may have more than one screen image.
60 
61  getImage() is used to retrieve the currently visible image
62  which is then used by the display widget to draw the output from the
63  terminal.
64 
65  The number of lines of output history which are kept in addition to the current
66  screen image depends on the history scroll being used to store the output.
67  The scroll is specified using setScroll()
68  The output history can be retrieved using writeToStream()
69 
70  The screen image has a selection associated with it, specified using
71  setSelectionStart() and setSelectionEnd(). The selected text can be retrieved
72  using selectedText(). When getImage() is used to retrieve the the visible image,
73  characters which are part of the selection have their colours inverted.
74 */
75 class Screen
76 {
77 public:
78  /** Construct a new screen image of size @p lines by @p columns. */
79  Screen(int lines, int columns);
80  ~Screen();
81 
82  // VT100/2 Operations
83  // Cursor Movement
84 
85  /** Move the cursor up by @p n lines. */
86  void cursorUp (int n);
87  /** Move the cursor down by @p n lines. */
88  void cursorDown (int n);
89  /** Move the cursor to the left by @p n columns. */
90  void cursorLeft (int n);
91  /** Move the cursor to the right by @p n columns. */
92  void cursorRight (int n);
93  /** Position the cursor on line @p y. */
94  void setCursorY (int y);
95  /** Position the cursor at column @p x. */
96  void setCursorX (int x);
97  /** Position the cursor at line @p y, column @p x. */
98  void setCursorYX (int y, int x);
99  /**
100  * Sets the margins for scrolling the screen.
101  *
102  * @param topLine The top line of the new scrolling margin.
103  * @param bottomLine The bottom line of the new scrolling margin.
104  */
105  void setMargins (int topLine , int bottomLine);
106  /** Returns the top line of the scrolling region. */
107  int topMargin() const;
108  /** Returns the bottom line of the scrolling region. */
109  int bottomMargin() const;
110 
111  /**
112  * Resets the scrolling margins back to the top and bottom lines
113  * of the screen.
114  */
115  void setDefaultMargins();
116 
117  /**
118  * Moves the cursor down one line, if the MODE_NewLine mode
119  * flag is enabled then the cursor is returned to the leftmost
120  * column first.
121  *
122  * Equivalent to NextLine() if the MODE_NewLine flag is set
123  * or index() otherwise.
124  */
125  void NewLine ();
126  /**
127  * Moves the cursor down one line and positions it at the beginning
128  * of the line.
129  */
130  void NextLine ();
131 
132  /**
133  * Move the cursor down one line. If the cursor is on the bottom
134  * line of the scrolling region (as returned by bottomMargin()) the
135  * scrolling region is scrolled up by one line instead.
136  */
137  void index ();
138  /**
139  * Move the cursor up one line. If the cursor is on the top line
140  * of the scrolling region (as returned by topMargin()) the scrolling
141  * region is scrolled down by one line instead.
142  */
143  void reverseIndex();
144 
145  /**
146  * Scroll the scrolling region of the screen up by @p n lines.
147  * The scrolling region is initially the whole screen, but can be changed
148  * using setMargins()
149  */
150  void scrollUp(int n);
151  /**
152  * Scroll the scrolling region of the screen down by @p n lines.
153  * The scrolling region is initially the whole screen, but can be changed
154  * using setMargins()
155  */
156  void scrollDown(int n);
157 
158  /**
159  * Moves the cursor to the beginning of the current line.
160  * Equivalent to setCursorX(0)
161  */
162  void Return ();
163  /**
164  * Moves the cursor one column to the left and erases the character
165  * at the new cursor position.
166  */
167  void BackSpace ();
168  /**
169  * Moves the cursor @p n tab-stops to the right.
170  */
171  void Tabulate (int n = 1);
172  /**
173  * Moves the cursor @p n tab-stops to the left.
174  */
175  void backTabulate(int n);
176 
177  // Editing
178 
179  /**
180  * Erase @p n characters beginning from the current cursor position.
181  * This is equivalent to over-writing @p n characters starting with the current
182  * cursor position with spaces.
183  * If @p n is 0 then one character is erased.
184  */
185  void eraseChars (int n);
186  /**
187  * Delete @p n characters beginning from the current cursor position.
188  * If @p n is 0 then one character is deleted.
189  */
190  void deleteChars (int n);
191  /**
192  * Insert @p n blank characters beginning from the current cursor position.
193  * The position of the cursor is not altered.
194  * If @p n is 0 then one character is inserted.
195  */
196  void insertChars (int n);
197  /**
198  * Removes @p n lines beginning from the current cursor position.
199  * The position of the cursor is not altered.
200  * If @p n is 0 then one line is removed.
201  */
202  void deleteLines (int n);
203  /**
204  * Inserts @p lines beginning from the current cursor position.
205  * The position of the cursor is not altered.
206  * If @p n is 0 then one line is inserted.
207  */
208  void insertLines (int n);
209  /** Clears all the tab stops. */
210  void clearTabStops();
211  /** Sets or removes a tab stop at the cursor's current column. */
212  void changeTabStop(bool set);
213 
214  /** Resets (clears) the specified screen @p mode. */
215  void resetMode (int mode);
216  /** Sets (enables) the specified screen @p mode. */
217  void setMode (int mode);
218  /**
219  * Saves the state of the specified screen @p mode. It can be restored
220  * using restoreMode()
221  */
222  void saveMode (int mode);
223  /** Restores the state of a screen @p mode saved by calling saveMode() */
224  void restoreMode (int mode);
225  /** Returns whether the specified screen @p mode is enabled or not .*/
226  bool getMode (int mode) const;
227 
228  /**
229  * Saves the current position and appearence (text color and style) of the cursor.
230  * It can be restored by calling restoreCursor()
231  */
232  void saveCursor ();
233  /** Restores the position and appearence of the cursor. See saveCursor() */
234  void restoreCursor();
235 
236  /** Clear the whole screen, moving the current screen contents into the history first. */
237  void clearEntireScreen();
238  /**
239  * Clear the area of the screen from the current cursor position to the end of
240  * the screen.
241  */
242  void clearToEndOfScreen();
243  /**
244  * Clear the area of the screen from the current cursor position to the start
245  * of the screen.
246  */
247  void clearToBeginOfScreen();
248  /** Clears the whole of the line on which the cursor is currently positioned. */
249  void clearEntireLine();
250  /** Clears from the current cursor position to the end of the line. */
251  void clearToEndOfLine();
252  /** Clears from the current cursor position to the beginning of the line. */
253  void clearToBeginOfLine();
254 
255  /** Fills the entire screen with the letter 'E' */
256  void helpAlign ();
257 
258  /**
259  * Enables the given @p rendition flag. Rendition flags control the appearence
260  * of characters on the screen.
261  *
262  * @see Character::rendition
263  */
264  void setRendition (int rendition);
265  /**
266  * Disables the given @p rendition flag. Rendition flags control the appearence
267  * of characters on the screen.
268  *
269  * @see Character::rendition
270  */
271  void resetRendition(int rendition);
272 
273  /**
274  * Sets the cursor's foreground color.
275  * @param space The color space used by the @p color argument
276  * @param color The new foreground color. The meaning of this depends on
277  * the color @p space used.
278  *
279  * @see CharacterColor
280  */
281  void setForeColor (int space, int color);
282  /**
283  * Sets the cursor's background color.
284  * @param space The color space used by the @p color argumnet.
285  * @param color The new background color. The meaning of this depends on
286  * the color @p space used.
287  *
288  * @see CharacterColor
289  */
290  void setBackColor (int space, int color);
291  /**
292  * Resets the cursor's color back to the default and sets the
293  * character's rendition flags back to the default settings.
294  */
295  void setDefaultRendition();
296 
297  /** Returns the column which the cursor is positioned at. */
298  int getCursorX() const;
299  /** Returns the line which the cursor is positioned on. */
300  int getCursorY() const;
301 
302  /** TODO Document me */
303  void clear();
304  /**
305  * Sets the position of the cursor to the 'home' position at the top-left
306  * corner of the screen (0,0)
307  */
308  void home();
309  /**
310  * Resets the state of the screen. This resets the various screen modes
311  * back to their default states. The cursor style and colors are reset
312  * (as if setDefaultRendition() had been called)
313  *
314  * <ul>
315  * <li>Line wrapping is enabled.</li>
316  * <li>Origin mode is disabled.</li>
317  * <li>Insert mode is disabled.</li>
318  * <li>Cursor mode is enabled. TODO Document me</li>
319  * <li>Screen mode is disabled. TODO Document me</li>
320  * <li>New line mode is disabled. TODO Document me</li>
321  * </ul>
322  *
323  * If @p clearScreen is true then the screen contents are erased entirely,
324  * otherwise they are unaltered.
325  */
326  void reset(bool clearScreen = true);
327 
328  /**
329  * Displays a new character at the current cursor position.
330  *
331  * If the cursor is currently positioned at the right-edge of the screen and
332  * line wrapping is enabled then the character is added at the start of a new
333  * line below the current one.
334  *
335  * If the MODE_Insert screen mode is currently enabled then the character
336  * is inserted at the current cursor position, otherwise it will replace the
337  * character already at the current cursor position.
338  */
339  void ShowCharacter(unsigned short c);
340 
341  // Do composition with last shown character FIXME: Not implemented yet for KDE 4
342  void compose(const QString& compose);
343 
344  /**
345  * Resizes the image to a new fixed size of @p new_lines by @p new_columns.
346  * In the case that @p new_columns is smaller than the current number of columns,
347  * existing lines are not truncated. This prevents characters from being lost
348  * if the terminal display is resized smaller and then larger again.
349  *
350  * (note that in versions of Konsole prior to KDE 4, existing lines were
351  * truncated when making the screen image smaller)
352  */
353  void resizeImage(int new_lines, int new_columns);
354 
355  /**
356  * Returns the current screen image.
357  * The result is an array of Characters of size [getLines()][getColumns()] which
358  * must be freed by the caller after use.
359  *
360  * @param dest Buffer to copy the characters into
361  * @param size Size of @p dest in Characters
362  * @param startLine Index of first line to copy
363  * @param endLine Index of last line to copy
364  */
365  void getImage( Character* dest , int size , int startLine , int endLine ) const;
366 
367  /**
368  * Returns the additional attributes associated with lines in the image.
369  * The most important attribute is LINE_WRAPPED which specifies that the
370  * line is wrapped,
371  * other attributes control the size of characters in the line.
372  */
373  QVector<LineProperty> getLineProperties( int startLine , int endLine ) const;
374 
375 
376  /** Return the number of lines. */
377  int getLines() { return lines; }
378  /** Return the number of columns. */
379  int getColumns() { return columns; }
380  /** Return the number of lines in the history buffer. */
381  int getHistLines ();
382  /**
383  * Sets the type of storage used to keep lines in the history.
384  * If @p copyPreviousScroll is true then the contents of the previous
385  * history buffer are copied into the new scroll.
386  */
387  void setScroll(const HistoryType& , bool copyPreviousScroll = true);
388  /** Returns the type of storage used to keep lines in the history. */
389  const HistoryType& getScroll();
390  /**
391  * Returns true if this screen keeps lines that are scrolled off the screen
392  * in a history buffer.
393  */
394  bool hasScroll();
395 
396  /**
397  * Sets the start of the selection.
398  *
399  * @param column The column index of the first character in the selection.
400  * @param line The line index of the first character in the selection.
401  * @param columnmode True if the selection is in column mode.
402  */
403  void setSelectionStart(const int column, const int line, const bool columnmode);
404 
405  /**
406  * Sets the end of the current selection.
407  *
408  * @param column The column index of the last character in the selection.
409  * @param line The line index of the last character in the selection.
410  */
411  void setSelectionEnd(const int column, const int line);
412 
413  /**
414  * Retrieves the start of the selection or the cursor position if there
415  * is no selection.
416  */
417  void getSelectionStart(int& column , int& line);
418 
419  /**
420  * Retrieves the end of the selection or the cursor position if there
421  * is no selection.
422  */
423  void getSelectionEnd(int& column , int& line);
424 
425  /** Clears the current selection */
426  void clearSelection();
427 
428  void setBusySelecting(bool busy) { sel_busy = busy; }
429 
430  /**
431  * Returns true if the character at (@p column, @p line) is part of the
432  * current selection.
433  */
434  bool isSelected(const int column,const int line) const;
435 
436  /**
437  * Convenience method. Returns the currently selected text.
438  * @param preserveLineBreaks Specifies whether new line characters should
439  * be inserted into the returned text at the end of each terminal line.
440  */
441  QString selectedText(bool preserveLineBreaks);
442 
443  /**
444  * Copies part of the output to a stream.
445  *
446  * @param decoder A decoder which coverts terminal characters into text
447  * @param from The first line in the history to retrieve
448  * @param to The last line in the history to retrieve
449  */
450  void writeToStream(TerminalCharacterDecoder* decoder, int from, int to);
451 
452  /**
453  * Sets the selection to line @p no in the history and returns
454  * the text of that line from the history buffer.
455  */
456  QString getHistoryLine(int no);
457 
458  /**
459  * Copies the selected characters, set using @see setSelBeginXY and @see setSelExtentXY
460  * into a stream.
461  *
462  * @param decoder A decoder which converts terminal characters into text.
463  * PlainTextDecoder is the most commonly used decoder which coverts characters
464  * into plain text with no formatting.
465  * @param preserveLineBreaks Specifies whether new line characters should
466  * be inserted into the returned text at the end of each terminal line.
467  */
469  preserveLineBreaks = true);
470 
471  /** TODO Document me */
472  void checkSelection(int from, int to);
473 
474  /**
475  * Sets or clears an attribute of the current line.
476  *
477  * @param property The attribute to set or clear
478  * Possible properties are:
479  * LINE_WRAPPED: Specifies that the line is wrapped.
480  * LINE_DOUBLEWIDTH: Specifies that the characters in the current line should be double the normal width.
481  * LINE_DOUBLEHEIGHT:Specifies that the characters in the current line should be double the normal height.
482  * Double-height lines are formed of two lines containing the same characters,
483  * with both having the LINE_DOUBLEHEIGHT attribute. This allows other parts of the
484  * code to work on the assumption that all lines are the same height.
485  *
486  * @param enable true to apply the attribute to the current line or false to remove it
487  */
488  void setLineProperty(LineProperty property , bool enable);
489 
490 
491  /**
492  * Returns the number of lines that the image has been scrolled up or down by,
493  * since the last call to resetScrolledLines().
494  *
495  * a positive return value indicates that the image has been scrolled up,
496  * a negative return value indicates that the image has been scrolled down.
497  */
498  int scrolledLines() const;
499 
500  /**
501  * Returns the region of the image which was last scrolled.
502  *
503  * This is the area of the image from the top margin to the
504  * bottom margin when the last scroll occurred.
505  */
506  QRect lastScrolledRegion() const;
507 
508  /**
509  * Resets the count of the number of lines that the image has been scrolled up or down by,
510  * see scrolledLines()
511  */
512  void resetScrolledLines();
513 
514  /**
515  * Returns the number of lines of output which have been
516  * dropped from the history since the last call
517  * to resetDroppedLines()
518  *
519  * If the history is not unlimited then it will drop
520  * the oldest lines of output if new lines are added when
521  * it is full.
522  */
523  int droppedLines() const;
524 
525  /**
526  * Resets the count of the number of lines dropped from
527  * the history.
528  */
529  void resetDroppedLines();
530 
531  /**
532  * Fills the buffer @p dest with @p count instances of the default (ie. blank)
533  * Character style.
534  */
535  static void fillWithDefaultChar(Character* dest, int count);
536 
537 private:
538 
539  //copies a line of text from the screen or history into a stream using a
540  //specified character decoder
541  //line - the line number to copy, from 0 (the earliest line in the history) up to
542  // hist->getLines() + lines - 1
543  //start - the first column on the line to copy
544  //count - the number of characters on the line to copy
545  //decoder - a decoder which coverts terminal characters (an Character array) into text
546  //appendNewLine - if true a new line character (\n) is appended to the end of the line
547  void copyLineToStream(int line,
548  int start,
549  int count,
550  TerminalCharacterDecoder* decoder,
551  bool appendNewLine,
552  bool preserveLineBreaks);
553 
554  //fills a section of the screen image with the character 'c'
555  //the parameters are specified as offsets from the start of the screen image.
556  //the loc(x,y) macro can be used to generate these values from a column,line pair.
557  void clearImage(int loca, int loce, char c);
558 
559  //move screen image between 'sourceBegin' and 'sourceEnd' to 'dest'.
560  //the parameters are specified as offsets from the start of the screen image.
561  //the loc(x,y) macro can be used to generate these values from a column,line pair.
562  void moveImage(int dest, int sourceBegin, int sourceEnd);
563 
564  void scrollUp(int from, int i);
565  void scrollDown(int from, int i);
566 
567  void addHistLine();
568 
569  void initTabStops();
570 
571  void effectiveRendition();
572  void reverseRendition(Character& p) const;
573 
574  bool isSelectionValid() const;
575 
576  // copies 'count' lines from the screen buffer into 'dest',
577  // starting from 'startLine', where 0 is the first line in the screen buffer
578  void copyFromScreen(Character* dest, int startLine, int count) const;
579  // copies 'count' lines from the history buffer into 'dest',
580  // starting from 'startLine', where 0 is the first line in the history
581  void copyFromHistory(Character* dest, int startLine, int count) const;
582 
583 
584  // screen image ----------------
585  int lines;
586  int columns;
587 
588  typedef QVector<Character> ImageLine; // [0..columns]
589  ImageLine* screenLines; // [lines]
590 
593 
595 
596  QVarLengthArray<LineProperty,64> lineProperties;
597 
598  // history buffer ---------------
600 
601  // cursor location
602  int cuX;
603  int cuY;
604 
605  // cursor color and rendition info
606  CharacterColor cu_fg; // foreground
607  CharacterColor cu_bg; // background
608  quint8 cu_re; // rendition
609 
610  // margins ----------------
611  int tmargin; // top margin
612  int bmargin; // bottom margin
613 
614  // states ----------------
616 
617  // ----------------------------
618 
619  bool* tabstops;
620 
621  // selection -------------------
622  int sel_begin; // The first location selected.
623  int sel_TL; // TopLeft Location.
624  int sel_BR; // Bottom Right Location.
625  bool sel_busy; // Busy making a selection.
626  bool columnmode; // Column selection mode
627 
628  // effective colors and rendition ------------
629  CharacterColor ef_fg; // These are derived from
630  CharacterColor ef_bg; // the cu_* variables above
631  quint8 ef_re; // to speed up operation
632 
633  //
634  // save cursor, rendition & states ------------
635  //
636 
637  // cursor location
638  int sa_cuX;
639  int sa_cuY;
640 
641  // rendition info
642  quint8 sa_cu_re;
645 
646  // last position where we added a character
647  int lastPos;
648 
649  // modes
651 
653 };
654 
655 #endif // SCREEN_H