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