src/Widgets/BaulkTerm/qtermwidget/Session.h

   1 //  This file is part of Konsole, an X terminal.
   2 //
   3 //  Copyright (C) 2007 by Robert Knight <robertknight@gmail.com>
   4 //  Copyright (C) 1997,1998 by Lars Doelle <lars.doelle@on-line.de>
   5 //
   6 //  Rewritten for QT4 by e_k <e_k at users.sourceforge.net>, Copyright (C)2008
   7 //  Forked for Baulk - Copyright (C) 2008-2009 - Jacob Alexander <haata at users.sf.net>
   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 //  any later version, including version 3 of the License.
  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, see <http://www.gnu.org/licenses/>.
  21
  22 #ifndef SESSION_H
  23 #define SESSION_H
  24
  25 // Qt
  26 #include <QtCore/QStringList>
  27 #include <QtCore>
  28 #include <QWidget>
  29
  30 // Konsole
  31 #include "History.h"
  32
  33 class KProcess;
  34
  35 namespace Konsole
  36 {
  37
  38 class Emulation;
  39 class Pty;
  40 class TerminalDisplay;
  41 //class ZModemDialog;
  42
  43 /*!
  44  * Represents a terminal session consisting of a pseudo-teletype and a terminal emulation.
  45  * The pseudo-teletype (or PTY) handles I/O between the terminal process and Konsole.
  46  * The terminal emulation ( Emulation and subclasses ) processes the output stream from the
  47  * PTY and produces a character image which is then shown on views connected to the session.
  48  *
  49  * Each Session can be connected to one or more views by using the addView() method.
  50  * The attached views can then display output from the program running in the terminal
  51  * or send input to the program in the terminal in the form of keypresses and mouse
  52  * activity.
  53  */
  54 class Session : public QObject
  55 {
  56 Q_OBJECT
  57
  58 public:
  59   Q_PROPERTY(QString name READ nameTitle)
  60   Q_PROPERTY(int processId READ processId)
  61   Q_PROPERTY(QString keyBindings READ keyBindings WRITE setKeyBindings)
  62   Q_PROPERTY(QSize size READ size WRITE setSize)
  63
  64   /*!
  65    * Constructs a new session.
  66    *
  67    * To start the terminal process, call the run() method,
  68    * after specifying the program and arguments
  69    * using setProgram() and setArguments()
  70    *
  71    * If no program or arguments are specified explicitly, the Session
  72    * falls back to using the program specified in the SHELL environment
  73    * variable.
  74    */
  75   Session();
  76   ~Session();
  77
  78   /*!
  79    * Returns true if the session is currently running.  This will be true
  80    * after run() has been called successfully.
  81    */
  82   bool isRunning() const;
  83
  84   /*!
  85    * Sets the profile associated with this session.
  86    *
  87    * @param profileKey A key which can be used to obtain the current
  88    * profile settings from the SessionManager
  89    */
  90   void setProfileKey(const QString& profileKey);
  91   /*!
  92    * Returns the profile key associated with this session.
  93    * This can be passed to the SessionManager to obtain the current
  94    * profile settings.
  95    */
  96   QString profileKey() const;
  97
  98   /*!
  99    * Adds a new view for this session.
 100    *
 101    * The viewing widget will display the output from the terminal and
 102    * input from the viewing widget (key presses, mouse activity etc.)
 103    * will be sent to the terminal.
 104    *
 105    * Views can be removed using removeView().  The session is automatically
 106    * closed when the last view is removed.
 107    */
 108   void addView(TerminalDisplay* widget);
 109   /*!
 110    * Removes a view from this session.  When the last view is removed,
 111    * the session will be closed automatically.
 112    *
 113    * @p widget will no longer display output from or send input
 114    * to the terminal
 115    */
 116   void removeView(TerminalDisplay* widget);
 117
 118   /*!
 119    * Returns the views connected to this session
 120    */
 121   QList<TerminalDisplay*> views() const;
 122
 123   /*!
 124    * Returns the terminal emulation instance being used to encode / decode
 125    * characters to / from the process.
 126    */
 127   Emulation*  emulation() const;
 128
 129   /*!
 130    * Returns the environment of this session as a list of strings like
 131    * VARIABLE=VALUE
 132    */
 133   QStringList environment() const;
 134   /*!
 135    * Sets the environment for this session.
 136    * @p environment should be a list of strings like
 137    * VARIABLE=VALUE
 138    */
 139   void setEnvironment(const QStringList& environment);
 140
 141   /*! Returns the unique ID for this session. */
 142   int sessionId() const;
 143
 144   /*!
 145    * Return the session title set by the user (ie. the program running
 146    * in the terminal), or an empty string if the user has not set a custom title
 147    */
 148   QString userTitle() const;
 149
 150   /*!
 151    * This enum describes the contexts for which separate
 152    * tab title formats may be specified.
 153    */
 154   enum TabTitleContext
 155   {
 156     /*! Default tab title format */
 157     LocalTabTitle,
 158     /*!
 159      * Tab title format used session currently contains
 160      * a connection to a remote computer (via SSH)
 161      */
 162     RemoteTabTitle
 163   };
 164   /*!
 165    * Sets the format used by this session for tab titles.
 166    *
 167    * @param context The context whoose format should be set.
 168    * @param format The tab title format.  This may be a mixture
 169    * of plain text and dynamic elements denoted by a '%' character
 170    * followed by a letter.  (eg. %d for directory).  The dynamic
 171    * elements available depend on the @p context
 172    */
 173   void setTabTitleFormat(TabTitleContext context , const QString& format);
 174   /*! Returns the format used by this session for tab titles. */
 175   QString tabTitleFormat(TabTitleContext context) const;
 176
 177
 178   /*! Returns the arguments passed to the shell process when run() is called. */
 179   QStringList arguments() const;
 180   /*! Returns the program name of the shell process started when run() is called. */
 181   QString program() const;
 182
 183   /*!
 184    * Sets the command line arguments which the session's program will be passed when
 185    * run() is called.
 186    */
 187   void setArguments(const QStringList& arguments);
 188   /*! Sets the program to be executed when run() is called. */
 189   void setProgram(const QString& program);
 190
 191   /*! Returns the session's current working directory. */
 192   QString initialWorkingDirectory() { return _initialWorkingDir; }
 193
 194   /*!
 195    * Sets the initial working directory for the session when it is run
 196    * This has no effect once the session has been started.
 197    */
 198   void setInitialWorkingDirectory( const QString& dir );
 199
 200   /*!
 201    * Sets the type of history store used by this session.
 202    * Lines of output produced by the terminal are added
 203    * to the history store.  The type of history store
 204    * used affects the number of lines which can be
 205    * remembered before they are lost and the storage
 206    * (in memory, on-disk etc.) used.
 207    */
 208   void setHistoryType(const HistoryType& type);
 209   /*!
 210    * Returns the type of history store used by this session.
 211    */
 212   const HistoryType& historyType() const;
 213   /*!
 214    * Clears the history store used by this session.
 215    */
 216   void clearHistory();
 217
 218   /*!
 219    * Enables monitoring for activity in the session.
 220    * This will cause notifySessionState() to be emitted
 221    * with the NOTIFYACTIVITY state flag when output is
 222    * received from the terminal.
 223    */
 224   void setMonitorActivity(bool);
 225   /*! Returns true if monitoring for activity is enabled. */
 226   bool isMonitorActivity() const;
 227
 228   /*!
 229    * Enables monitoring for silence in the session.
 230    * This will cause notifySessionState() to be emitted
 231    * with the NOTIFYSILENCE state flag when output is not
 232    * received from the terminal for a certain period of
 233    * time, specified with setMonitorSilenceSeconds()
 234    */
 235   void setMonitorSilence(bool);
 236   /*!
 237    * Returns true if monitoring for inactivity (silence)
 238    * in the session is enabled.
 239    */
 240   bool isMonitorSilence()  const;
 241   /*! See setMonitorSilence() */
 242   void setMonitorSilenceSeconds(int seconds);
 243
 244   /*!
 245    * Sets the key bindings used by this session.  The bindings
 246    * specify how input key sequences are translated into
 247    * the character stream which is sent to the terminal.
 248    *
 249    * @param id The name of the key bindings to use.  The
 250    * names of available key bindings can be determined using the
 251    * KeyboardTranslatorManager class.
 252    */
 253   void setKeyBindings(const QString& id);
 254   /*! Returns the name of the key bindings used by this session. */
 255   QString keyBindings() const;
 256
 257   /*!
 258    * This enum describes the available title roles.
 259    */
 260   enum TitleRole
 261   {
 262       /*! The name of the session. */
 263       NameRole,
 264       /*! The title of the session which is displayed in tabs etc. */
 265       DisplayedTitleRole
 266   };
 267
 268   /*! Sets the session's title for the specified @p role to @p title. */
 269   void setTitle(TitleRole role , const QString& title);
 270   /*! Returns the session's title for the specified @p role. */
 271   QString title(TitleRole role) const;
 272   /*! Convenience method used to read the name property.  Returns title(Session::NameRole). */
 273   QString nameTitle() const { return title(Session::NameRole); }
 274
 275   /*! Sets the name of the icon associated with this session. */
 276   void setIconName(const QString& iconName);
 277   /*! Returns the name of the icon associated with this session. */
 278   QString iconName() const;
 279
 280   /*! Sets the text of the icon associated with this session. */
 281   void setIconText(const QString& iconText);
 282   /*! Returns the text of the icon associated with this session. */
 283   QString iconText() const;
 284
 285   /*! Specifies whether a utmp entry should be created for the pty used by this session. */
 286   void setAddToUtmp(bool);
 287
 288   /*! Sends the specified @p signal to the terminal process. */
 289   bool sendSignal(int signal);
 290
 291   /*!
 292    * Specifies whether to close the session automatically when the terminal
 293    * process terminates.
 294    */
 295   void setAutoClose(bool b) { _autoClose = b; }
 296
 297   /*!
 298    * Sets whether flow control is enabled for this terminal
 299    * session.
 300    */
 301   void setFlowControlEnabled(bool enabled);
 302
 303   /*! Returns whether flow control is enabled for this terminal session. */
 304   bool flowControlEnabled() const;
 305
 306   /*!
 307    * Sends @p text to the current foreground terminal program.
 308    */
 309   void sendText(const QString& text) const;
 310
 311   /*!
 312    * Returns the process id of the terminal process.
 313    * This is the id used by the system API to refer to the process.
 314    */
 315   int processId() const;
 316
 317   /*!
 318    * Returns the process id of the terminal's foreground process.
 319    * This is initially the same as processId() but can change
 320    * as the user starts other programs inside the terminal.
 321    */
 322   int foregroundProcessId() const;
 323
 324   /*! Returns the terminal session's window size in lines and columns. */
 325   QSize size();
 326   /*!
 327    * Emits a request to resize the session to accommodate
 328    * the specified window size.
 329    *
 330    * @param size The size in lines and columns to request.
 331    */
 332   void setSize(const QSize& size);
 333
 334   /*! Sets the text codec used by this session's terminal emulation. */
 335   void setCodec(QTextCodec* codec);
 336
 337   /*!
 338    * Sets whether the session has a dark background or not.  The session
 339    * uses this information to set the COLORFGBG variable in the process's
 340    * environment, which allows the programs running in the terminal to determine
 341    * whether the background is light or dark and use appropriate colors by default.
 342    *
 343    * This has no effect once the session is running.
 344    */
 345   void setDarkBackground(bool darkBackground);
 346   /*!
 347    * Returns true if the session has a dark background.
 348    * See setDarkBackground()
 349    */
 350   bool hasDarkBackground() const;
 351
 352   /*!
 353    * Attempts to get the shell program to redraw the current display area.
 354    * This can be used after clearing the screen, for example, to get the
 355    * shell to redraw the prompt line.
 356    */
 357   void refresh();
 358
 359 //  void startZModem(const QString &rz, const QString &dir, const QStringList &list);
 360 //  void cancelZModem();
 361 //  bool isZModemBusy() { return _zmodemBusy; }
 362
 363 public slots:
 364
 365   /*!
 366    * Starts the terminal session.
 367    *
 368    * This creates the terminal process and connects the teletype to it.
 369    */
 370   void run();
 371
 372   /*!
 373    * Closes the terminal session.  This sends a hangup signal
 374    * (SIGHUP) to the terminal process and causes the done(Session*)
 375    * signal to be emitted.
 376    */
 377   void close();
 378
 379   /*!
 380    * Changes the session title or other customizable aspects of the terminal
 381    * emulation display. For a list of what may be changed see the
 382    * Emulation::titleChanged() signal.
 383    */
 384   void setUserTitle( int, const QString &caption );
 385
 386 signals:
 387
 388   /*! Emitted when the terminal process starts. */
 389   void started();
 390
 391   /*!
 392    * Emitted when the terminal process exits.
 393    */
 394   void finished();
 395
 396   /*!
 397    * Emitted when output is received from the terminal process.
 398    */
 399   void receivedData( const QString& text );
 400
 401   /*! Emitted when the session's title has changed. */
 402   void titleChanged();
 403
 404   /*! Emitted when the session's profile has changed. */
 405   void profileChanged(const QString& profile);
 406
 407   /*!
 408    * Emitted when the activity state of this session changes.
 409    *
 410    * @param state The new state of the session.  This may be one
 411    * of NOTIFYNORMAL, NOTIFYSILENCE or NOTIFYACTIVITY
 412    */
 413   void stateChanged(int state);
 414
 415   /*! Emitted when a bell event occurs in the session. */
 416   void bellRequest( const QString& message );
 417
 418   /*!
 419    * Requests that the color the text for any tabs associated with
 420    * this session should be changed;
 421    *
 422    * TODO: Document what the parameter does
 423    */
 424   void changeTabTextColorRequest(int);
 425
 426   /*!
 427    * Requests that the background color of views on this session
 428    * should be changed.
 429    */
 430   void changeBackgroundColorRequest(const QColor&);
 431
 432   /*! TODO: Document me. */
 433   void openUrlRequest(const QString& url);
 434
 435   /*! TODO: Document me. */
 436 //  void zmodemDetected();
 437
 438   /*!
 439    * Emitted when the terminal process requests a change
 440    * in the size of the terminal window.
 441    *
 442    * @param size The requested window size in terms of lines and columns.
 443    */
 444   void resizeRequest(const QSize& size);
 445
 446   /*!
 447    * Emitted when a profile change command is received from the terminal.
 448    *
 449    * @param text The text of the command.  This is a string of the form
 450    * "PropertyName=Value;PropertyName=Value ..."
 451    */
 452   void profileChangeCommandReceived(const QString& text);
 453
 454  /*!
 455   * Emitted when the flow control state changes.
 456   *
 457   * @param enabled True if flow control is enabled or false otherwise.
 458   */
 459   void flowControlEnabledChanged(bool enabled);
 460
 461 private slots:
 462   void done(int);
 463
 464 //  void fireZModemDetected();
 465
 466   void onReceiveBlock( const char* buffer, int len );
 467   void monitorTimerDone();
 468
 469   void onViewSizeChange(int height, int width);
 470   void onEmulationSizeChange(int lines , int columns);
 471
 472   void activityStateSet(int);
 473
 474   //automatically detach views from sessions when view is destroyed
 475   void viewDestroyed(QObject* view);
 476
 477 //  void zmodemReadStatus();
 478 //  void zmodemReadAndSendBlock();
 479 //  void zmodemRcvBlock(const char *data, int len);
 480 //  void zmodemFinished();
 481
 482 private:
 483
 484   void updateTerminalSize();
 485   WId windowId() const;
 486
 487   int            _uniqueIdentifier;
 488
 489   Pty*          _shellProcess;
 490   Emulation*    _emulation;
 491
 492   QList<TerminalDisplay*> _views;
 493
 494   bool           _monitorActivity;
 495   bool           _monitorSilence;
 496   bool           _notifiedActivity;
 497   bool           _masterMode;
 498   bool           _autoClose;
 499   bool           _wantedClose;
 500   QTimer*        _monitorTimer;
 501
 502   int            _silenceSeconds;
 503
 504   QString        _nameTitle;
 505   QString        _displayTitle;
 506   QString        _userTitle;
 507
 508   QString        _localTabTitleFormat;
 509   QString        _remoteTabTitleFormat;
 510
 511   QString        _iconName;
 512   QString        _iconText; // as set by: echo -en '\033]1;IconText\007
 513   bool           _addToUtmp;
 514   bool           _flowControl;
 515   bool           _fullScripting;
 516
 517   QString        _program;
 518   QStringList    _arguments;
 519
 520   QStringList    _environment;
 521   int            _sessionId;
 522
 523   QString        _initialWorkingDir;
 524
 525   // ZModem
 526 //  bool           _zmodemBusy;
 527 //  KProcess*      _zmodemProc;
 528 //  ZModemDialog*  _zmodemProgress;
 529
 530   // Color/Font Changes by ESC Sequences
 531
 532   QColor         _modifiedBackground; // as set by: echo -en '\033]11;Color\007
 533
 534   QString        _profileKey;
 535
 536   bool _hasDarkBackground;
 537
 538   static int lastSessionId;
 539
 540 };
 541
 542 /*!
 543  * Provides a group of sessions which is divided into master and slave sessions.
 544  * Activity in master sessions can be propagated to all sessions within the group.
 545  * The type of activity which is propagated and method of propagation is controlled
 546  * by the masterMode() flags.
 547  */
 548 class SessionGroup : public QObject
 549 {
 550 Q_OBJECT
 551
 552 public:
 553     /*! Constructs an empty session group. */
 554     SessionGroup();
 555     /*! Destroys the session group and removes all connections between master and slave sessions. */
 556     ~SessionGroup();
 557
 558     /*! Adds a session to the group. */
 559     void addSession( Session* session );
 560     /*! Removes a session from the group. */
 561     void removeSession( Session* session );
 562
 563     /*! Returns the list of sessions currently in the group. */
 564     QList<Session*> sessions() const;
 565
 566     /*!
 567      * Sets whether a particular session is a master within the group.
 568      * Changes or activity in the group's master sessions may be propagated
 569      * to all the sessions in the group, depending on the current masterMode()
 570      *
 571      * @param session The session whoose master status should be changed.
 572      * @param master True to make this session a master or false otherwise
 573      */
 574     void setMasterStatus( Session* session , bool master );
 575     /*! Returns the master status of a session.  See setMasterStatus() */
 576     bool masterStatus( Session* session ) const;
 577
 578     /*!
 579      * This enum describes the options for propagating certain activity or
 580      * changes in the group's master sessions to all sessions in the group.
 581      */
 582     enum MasterMode
 583     {
 584         /*!
 585          * Any input key presses in the master sessions are sent to all
 586          * sessions in the group.
 587          */
 588         CopyInputToAll = 1
 589     };
 590
 591     /*!
 592      * Specifies which activity in the group's master sessions is propagated
 593      * to all sessions in the group.
 594      *
 595      * @param mode A bitwise OR of MasterMode flags.
 596      */
 597     void setMasterMode( int mode );
 598     /*!
 599      * Returns a bitwise OR of the active MasterMode flags for this group.
 600      * See setMasterMode()
 601      */
 602     int masterMode() const;
 603
 604 private:
 605     void connectPair(Session* master , Session* other);
 606     void disconnectPair(Session* master , Session* other);
 607     void connectAll(bool connect);
 608     QList<Session*> masters() const;
 609
 610     // maps sessions to their master status
 611     QHash<Session*,bool> _sessions;
 612
 613     int _masterMode;
 614 };
 615
 616 }
 617
 618 #endif
 619