apps/konsole/src/Emulation.h

   1 /*
   2     This file is part of Konsole, an X terminal.
   3
   4     Copyright 2007-2008 by Robert Knight <robertknight@gmail.com>
   5     Copyright 1997,1998 by Lars Doelle <lars.doelle@on-line.de>
   6
   7     This program is free software; you can redistribute it and/or modify
   8     it under the terms of the GNU General Public License as published by
   9     the Free Software Foundation; either version 2 of the License, or
  10     (at your option) any later version.
  11
  12     This program is distributed in the hope that it will be useful,
  13     but WITHOUT ANY WARRANTY; without even the implied warranty of
  14     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15     GNU General Public License for more details.
  16
  17     You should have received a copy of the GNU General Public License
  18     along with this program; if not, write to the Free Software
  19     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  20     02110-1301  USA.
  21 */
  22
  23 #ifndef EMULATION_H
  24 #define EMULATION_H
  25
  26 // System
  27 #include <stdio.h>
  28
  29 // Qt
  30 #include <QtGui/QKeyEvent>
  31 //#include <QPointer>
  32 #include <QtCore/QTextCodec>
  33 #include <QtCore/QTextStream>
  34 #include <QtCore/QTimer>
  35
  36
  37 namespace Konsole
  38 {
  39
  40 class KeyboardTranslator;
  41 class HistoryType;
  42 class Screen;
  43 class ScreenWindow;
  44 class TerminalCharacterDecoder;
  45
  46 /**
  47  * This enum describes the available states which
  48  * the terminal emulation may be set to.
  49  *
  50  * These are the values used by Emulation::stateChanged()
  51  */
  52 enum
  53 {
  54     /** The emulation is currently receiving user input. */
  55     NOTIFYNORMAL=0,
  56     /**
  57      * The terminal program has triggered a bell event
  58      * to get the user's attention.
  59      */
  60     NOTIFYBELL=1,
  61     /**
  62      * The emulation is currently receiving data from its
  63      * terminal input.
  64      */
  65     NOTIFYACTIVITY=2,
  66
  67     // unused here?
  68     NOTIFYSILENCE=3
  69 };
  70
  71 /**
  72  * Base class for terminal emulation back-ends.
  73  *
  74  * The back-end is responsible for decoding an incoming character stream and
  75  * producing an output image of characters.
  76  *
  77  * When input from the terminal is received, the receiveData() slot should be called with
  78  * the data which has arrived.  The emulation will process the data and update the
  79  * screen image accordingly.  The codec used to decode the incoming character stream
  80  * into the unicode characters used internally can be specified using setCodec()
  81  *
  82  * The size of the screen image can be specified by calling setImageSize() with the
  83  * desired number of lines and columns.  When new lines are added, old content
  84  * is moved into a history store, which can be set by calling setHistory().
  85  *
  86  * The screen image can be accessed by creating a ScreenWindow onto this emulation
  87  * by calling createWindow().  Screen windows provide access to a section of the
  88  * output.  Each screen window covers the same number of lines and columns as the
  89  * image size returned by imageSize().  The screen window can be moved up and down
  90  * and provides transparent access to both the current on-screen image and the
  91  * previous output.  The screen windows emit an outputChanged signal
  92  * when the section of the image they are looking at changes.
  93  * Graphical views can then render the contents of a screen window, listening for notifications
  94  * of output changes from the screen window which they are associated with and updating
  95  * accordingly.
  96  *
  97  * The emulation also is also responsible for converting input from the connected views such
  98  * as keypresses and mouse activity into a character string which can be sent
  99  * to the terminal program.  Key presses can be processed by calling the sendKeyEvent() slot,
 100  * while mouse events can be processed using the sendMouseEvent() slot.  When the character
 101  * stream has been produced, the emulation will emit a sendData() signal with a pointer
 102  * to the character buffer.  This data should be fed to the standard input of the terminal
 103  * process.  The translation of key presses into an output character stream is performed
 104  * using a lookup in a set of key bindings which map key sequences to output
 105  * character sequences.  The name of the key bindings set used can be specified using
 106  * setKeyBindings()
 107  *
 108  * The emulation maintains certain state information which changes depending on the
 109  * input received.  The emulation can be reset back to its starting state by calling
 110  * reset().
 111  *
 112  * The emulation also maintains an activity state, which specifies whether
 113  * terminal is currently active ( when data is received ), normal
 114  * ( when the terminal is idle or receiving user input ) or trying
 115  * to alert the user ( also known as a "Bell" event ).  The stateSet() signal
 116  * is emitted whenever the activity state is set.  This can be used to determine
 117  * how long the emulation has been active/idle for and also respond to
 118  * a 'bell' event in different ways.
 119  */
 120 class Emulation : public QObject
 121 {
 122 Q_OBJECT
 123
 124 public:
 125
 126    /** Constructs a new terminal emulation */
 127    Emulation();
 128   ~Emulation();
 129
 130   /**
 131    * Creates a new window onto the output from this emulation.  The contents
 132    * of the window are then rendered by views which are set to use this window using the
 133    * TerminalDisplay::setScreenWindow() method.
 134    */
 135   ScreenWindow* createWindow();
 136
 137   /** Returns the size of the screen image which the emulation produces */
 138   QSize imageSize() const;
 139
 140   /**
 141    * Returns the total number of lines, including those stored in the history.
 142    */
 143   int lineCount() const;
 144
 145   /**
 146    * Sets the history store used by this emulation.  When new lines
 147    * are added to the output, older lines at the top of the screen are transferred to a history
 148    * store.
 149    *
 150    * The number of lines which are kept and the storage location depend on the
 151    * type of store.
 152    */
 153   void setHistory(const HistoryType&);
 154   /** Returns the history store used by this emulation.  See setHistory() */
 155   const HistoryType& history() const;
 156   /** Clears the history scroll. */
 157   void clearHistory();
 158
 159   /**
 160    * Copies the output history from @p startLine to @p endLine
 161    * into @p stream, using @p decoder to convert the terminal
 162    * characters into text.
 163    *
 164    * @param decoder A decoder which converts lines of terminal characters with
 165    * appearance attributes into output text.  PlainTextDecoder is the most commonly
 166    * used decoder.
 167    * @param startLine The first
 168    */
 169   virtual void writeToStream(TerminalCharacterDecoder* decoder,int startLine,int endLine);
 170
 171   /** Returns the codec used to decode incoming characters.  See setCodec() */
 172   const QTextCodec* codec() const { return _codec; }
 173   /** Sets the codec used to decode incoming characters.  */
 174   void setCodec(const QTextCodec*);
 175
 176   /**
 177    * Convenience method.
 178    * Returns true if the current codec used to decode incoming
 179    * characters is UTF-8
 180    */
 181   bool utf8() const
 182   { Q_ASSERT(_codec); return _codec->mibEnum() == 106; }
 183
 184
 185   /** TODO Document me */
 186   virtual char eraseChar() const;
 187
 188   /**
 189    * Sets the key bindings used to key events
 190    * ( received through sendKeyEvent() ) into character
 191    * streams to send to the terminal.
 192    */
 193   void setKeyBindings(const QString& name);
 194   /**
 195    * Returns the name of the emulation's current key bindings.
 196    * See setKeyBindings()
 197    */
 198   QString keyBindings() const;
 199
 200   /**
 201    * Copies the current image into the history and clears the screen.
 202    */
 203   virtual void clearEntireScreen() =0;
 204
 205   /** Resets the state of the terminal. */
 206   virtual void reset() =0;
 207
 208   /**
 209    * Returns true if the active terminal program wants
 210    * mouse input events.
 211    *
 212    * The programUsesMouseChanged() signal is emitted when this
 213    * changes.
 214    */
 215   bool programUsesMouse() const;
 216
 217 public slots:
 218
 219   /** Change the size of the emulation's image */
 220   virtual void setImageSize(int lines, int columns);
 221
 222   /**
 223    * Interprets a sequence of characters and sends the result to the terminal.
 224    * This is equivalent to calling sendKeyEvent() for each character in @p text in succession.
 225    */
 226   virtual void sendText(const QString& text) = 0;
 227
 228   /**
 229    * Interprets a key press event and emits the sendData() signal with
 230    * the resulting character stream.
 231    */
 232   virtual void sendKeyEvent(QKeyEvent*);
 233
 234   /**
 235    * Converts information about a mouse event into an xterm-compatible escape
 236    * sequence and emits the character sequence via sendData()
 237    */
 238   virtual void sendMouseEvent(int buttons, int column, int line, int eventType);
 239
 240   /**
 241    * Sends a string of characters to the foreground terminal process.
 242    *
 243    * @param string The characters to send.
 244    * @param length Length of @p string or if set to a negative value, @p string will
 245    * be treated as a null-terminated string and its length will be determined automatically.
 246    */
 247   virtual void sendString(const char* string, int length = -1) = 0;
 248
 249   /**
 250    * Processes an incoming stream of characters.  receiveData() decodes the incoming
 251    * character buffer using the current codec(), and then calls receiveChar() for
 252    * each unicode character in the resulting buffer.
 253    *
 254    * receiveData() also starts a timer which causes the outputChanged() signal
 255    * to be emitted when it expires.  The timer allows multiple updates in quick
 256    * succession to be buffered into a single outputChanged() signal emission.
 257    *
 258    * @param buffer A string of characters received from the terminal program.
 259    * @param len The length of @p buffer
 260    */
 261   void receiveData(const char* buffer,int len);
 262
 263 signals:
 264
 265   /**
 266    * Emitted when a buffer of data is ready to send to the
 267    * standard input of the terminal.
 268    *
 269    * @param data The buffer of data ready to be sent
 270    * @paran len The length of @p data in bytes
 271    */
 272   void sendData(const char* data,int len);
 273
 274   /**
 275    * Requests that sending of input to the emulation
 276    * from the terminal process be suspended or resumed.
 277    *
 278    * @param suspend If true, requests that sending of
 279    * input from the terminal process' stdout be
 280    * suspended.  Otherwise requests that sending of
 281    * input be resumed.
 282    */
 283   void lockPtyRequest(bool suspend);
 284
 285   /**
 286    * Requests that the pty used by the terminal process
 287    * be set to UTF 8 mode.
 288    *
 289    * TODO: More documentation
 290    */
 291   void useUtf8Request(bool);
 292
 293   /**
 294    * Emitted when the activity state of the emulation is set.
 295    *
 296    * @param state The new activity state, one of NOTIFYNORMAL, NOTIFYACTIVITY
 297    * or NOTIFYBELL
 298    */
 299   void stateSet(int state);
 300
 301   /** TODO Document me */
 302   void zmodemDetected();
 303
 304
 305   /**
 306    * Requests that the color of the text used
 307    * to represent the tabs associated with this
 308    * emulation be changed.  This is a Konsole-specific
 309    * extension from pre-KDE 4 times.
 310    *
 311    * TODO: Document how the parameter works.
 312    */
 313   void changeTabTextColorRequest(int color);
 314
 315   /**
 316    * This is emitted when the program running in the shell indicates whether or
 317    * not it is interested in mouse events.
 318    *
 319    * @param usesMouse This will be true if the program wants to be informed about
 320    * mouse events or false otherwise.
 321    */
 322   void programUsesMouseChanged(bool usesMouse);
 323
 324   /**
 325    * Emitted when the contents of the screen image change.
 326    * The emulation buffers the updates from successive image changes,
 327    * and only emits outputChanged() at sensible intervals when
 328    * there is a lot of terminal activity.
 329    *
 330    * Normally there is no need for objects other than the screen windows
 331    * created with createWindow() to listen for this signal.
 332    *
 333    * ScreenWindow objects created using createWindow() will emit their
 334    * own outputChanged() signal in response to this signal.
 335    */
 336   void outputChanged();
 337
 338   /**
 339    * Emitted when the program running in the terminal wishes to update the
 340    * session's title.  This also allows terminal programs to customize other
 341    * aspects of the terminal emulation display.
 342    *
 343    * This signal is emitted when the escape sequence "\033]ARG;VALUE\007"
 344    * is received in the input string, where ARG is a number specifying what
 345    * should change and VALUE is a string specifying the new value.
 346    *
 347    * TODO:  The name of this method is not very accurate since this method
 348    * is used to perform a whole range of tasks besides just setting
 349    * the user-title of the session.
 350    *
 351    * @param title Specifies what to change.
 352    * <ul>
 353    * <li>0 - Set window icon text and session title to @p newTitle</li>
 354    * <li>1 - Set window icon text to @p newTitle</li>
 355    * <li>2 - Set session title to @p newTitle</li>
 356    * <li>11 - Set the session's default background color to @p newTitle,
 357    *         where @p newTitle can be an HTML-style string (#RRGGBB) or a named
 358    *         color (eg 'red', 'blue').
 359    *         See http://doc.trolltech.com/4.2/qcolor.html#setNamedColor for more
 360    *         details.
 361    * </li>
 362    * <li>31 - Supposedly treats @p newTitle as a URL and opens it (NOT IMPLEMENTED)</li>
 363    * <li>32 - Sets the icon associated with the session.  @p newTitle is the name
 364    *    of the icon to use, which can be the name of any icon in the current KDE icon
 365    *    theme (eg: 'konsole', 'kate', 'folder_home')</li>
 366    * </ul>
 367    * @param newTitle Specifies the new title
 368    */
 369
 370   void titleChanged(int title,const QString& newTitle);
 371
 372   /**
 373    * Emitted when the program running in the terminal changes the
 374    * screen size.
 375    */
 376   void imageSizeChanged(int lineCount , int columnCount);
 377
 378   /**
 379    * Emitted when the terminal program requests to change various properties
 380    * of the terminal display.
 381    *
 382    * A profile change command occurs when a special escape sequence, followed
 383    * by a string containing a series of name and value pairs is received.
 384    * This string can be parsed using a ProfileCommandParser instance.
 385    *
 386    * @param text A string expected to contain a series of key and value pairs in
 387    * the form:  name=value;name2=value2 ...
 388    */
 389   void profileChangeCommandReceived(const QString& text);
 390
 391   /**
 392    * Emitted when a flow control key combination ( Ctrl+S or Ctrl+Q ) is pressed.
 393    * @param suspendKeyPressed True if Ctrl+S was pressed to suspend output or Ctrl+Q to
 394    * resume output.
 395    */
 396   void flowControlKeyPressed(bool suspendKeyPressed);
 397
 398 protected:
 399   virtual void setMode(int mode) = 0;
 400   virtual void resetMode(int mode) = 0;
 401
 402   /**
 403    * Processes an incoming character.  See receiveData()
 404    * @p ch A unicode character code.
 405    */
 406   virtual void receiveChar(int ch);
 407
 408   /**
 409    * Sets the active screen.  The terminal has two screens, primary and alternate.
 410    * The primary screen is used by default.  When certain interactive programs such
 411    * as Vim are run, they trigger a switch to the alternate screen.
 412    *
 413    * @param index 0 to switch to the primary screen, or 1 to switch to the alternate screen
 414    */
 415   void setScreen(int index);
 416
 417   enum EmulationCodec
 418   {
 419       LocaleCodec = 0,
 420       Utf8Codec   = 1
 421   };
 422   void setCodec(EmulationCodec codec); // codec number, 0 = locale, 1=utf8
 423
 424
 425   QList<ScreenWindow*> _windows;
 426
 427   Screen* _currentScreen;  // pointer to the screen which is currently active,
 428                             // this is one of the elements in the screen[] array
 429
 430   Screen* _screen[2];      // 0 = primary screen ( used by most programs, including the shell
 431                             //                      scrollbars are enabled in this mode )
 432                             // 1 = alternate      ( used by vi , emacs etc.
 433                             //                      scrollbars are not enabled in this mode )
 434
 435
 436   //decodes an incoming C-style character stream into a unicode QString using
 437   //the current text codec.  (this allows for rendering of non-ASCII characters in text files etc.)
 438   const QTextCodec* _codec;
 439   QTextDecoder* _decoder;
 440   const KeyboardTranslator* _keyTranslator; // the keyboard layout
 441
 442 protected slots:
 443   /**
 444    * Schedules an update of attached views.
 445    * Repeated calls to bufferedUpdate() in close succession will result in only a single update,
 446    * much like the Qt buffered update of widgets.
 447    */
 448   void bufferedUpdate();
 449
 450 private slots:
 451
 452   // triggered by timer, causes the emulation to send an updated screen image to each
 453   // view
 454   void showBulk();
 455
 456   void usesMouseChanged(bool usesMouse);
 457
 458 private:
 459   bool _usesMouse;
 460   QTimer _bulkTimer1;
 461   QTimer _bulkTimer2;
 462
 463 };
 464
 465 }
 466
 467 #endif // ifndef EMULATION_H