apps/konsole/src/Session.h

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