apps/konsole/src/Pty.h

   1 /*
   2     This file is part of Konsole, KDE's terminal emulator.
   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 PTY_H
  24 #define PTY_H
  25
  26 // Qt
  27 #include <QtCore/QStringList>
  28 #include <QtCore/QVector>
  29 #include <QtCore/QList>
  30 #include <QtCore/QSize>
  31
  32 // KDE
  33 #include <KPtyProcess>
  34 #include <kdemacros.h>
  35
  36 namespace Konsole
  37 {
  38
  39 /**
  40  * The Pty class is used to start the terminal process,
  41  * send data to it, receive data from it and manipulate
  42  * various properties of the pseudo-teletype interface
  43  * used to communicate with the process.
  44  *
  45  * To use this class, construct an instance and connect
  46  * to the sendData slot and receivedData signal to
  47  * send data to or receive data from the process.
  48  *
  49  * To start the terminal process, call the start() method
  50  * with the program name and appropriate arguments.
  51  */
  52 class KDE_EXPORT Pty: public KPtyProcess
  53 {
  54 Q_OBJECT
  55
  56   public:
  57
  58     /**
  59      * Constructs a new Pty.
  60      *
  61      * Connect to the sendData() slot and receivedData() signal to prepare
  62      * for sending and receiving data from the terminal process.
  63      *
  64      * To start the terminal process, call the run() method with the
  65      * name of the program to start and appropriate arguments.
  66      */
  67     explicit Pty(QObject* parent = 0);
  68
  69     /**
  70      * Construct a process using an open pty master.
  71      * See KPtyProcess::KPtyProcess()
  72      */
  73     explicit Pty(int ptyMasterFd, QObject* parent = 0);
  74
  75     ~Pty();
  76
  77     /**
  78      * Starts the terminal process.
  79      *
  80      * Returns 0 if the process was started successfully or non-zero
  81      * otherwise.
  82      *
  83      * @param program Path to the program to start
  84      * @param arguments Arguments to pass to the program being started
  85      * @param environment A list of key=value pairs which will be added
  86      * to the environment for the new process.  At the very least this
  87      * should include an assignment for the TERM environment variable.
  88      * @param winid Specifies the value of the WINDOWID environment variable
  89      * in the process's environment.
  90      * @param addToUtmp Specifies whether a utmp entry should be created for
  91      * the pty used.  See K3Process::setUsePty()
  92      * @param dbusService Specifies the value of the KONSOLE_DBUS_SERVICE
  93      * environment variable in the process's environment.
  94      * @param dbusSession Specifies the value of the KONSOLE_DBUS_SESSION
  95      * environment variable in the process's environment.
  96      */
  97     int start( const QString& program,
  98                const QStringList& arguments,
  99                const QStringList& environment,
 100                ulong winid,
 101                bool addToUtmp,
 102                const QString& dbusService,
 103                const QString& dbusSession
 104              );
 105
 106     /** TODO: Document me */
 107     void setWriteable(bool writeable);
 108
 109     /**
 110      * Enables or disables Xon/Xoff flow control.  The flow control setting
 111      * may be changed later by a terminal application, so flowControlEnabled()
 112      * may not equal the value of @p on in the previous call to setFlowControlEnabled()
 113      */
 114     void setFlowControlEnabled(bool on);
 115
 116     /** Queries the terminal state and returns true if Xon/Xoff flow control is enabled. */
 117     bool flowControlEnabled() const;
 118
 119     /**
 120      * Sets the size of the window (in lines and columns of characters)
 121      * used by this teletype.
 122      */
 123     void setWindowSize(int lines, int cols);
 124
 125     /** Returns the size of the window used by this teletype.  See setWindowSize() */
 126     QSize windowSize() const;
 127
 128     /** TODO Document me */
 129     void setErase(char erase);
 130
 131     /** */
 132     char erase() const;
 133
 134     /**
 135      * Returns the process id of the teletype's current foreground
 136      * process.  This is the process which is currently reading
 137      * input sent to the terminal via. sendData()
 138      *
 139      * If there is a problem reading the foreground process group,
 140      * 0 will be returned.
 141      */
 142     int foregroundProcessGroup() const;
 143
 144   public slots:
 145
 146     /**
 147      * Put the pty into UTF-8 mode on systems which support it.
 148      */
 149     void setUtf8Mode(bool on);
 150
 151     /**
 152      * Suspend or resume processing of data from the standard
 153      * output of the terminal process.
 154      *
 155      * See K3Process::suspend() and K3Process::resume()
 156      *
 157      * @param lock If true, processing of output is suspended,
 158      * otherwise processing is resumed.
 159      */
 160     void lockPty(bool lock);
 161
 162     /**
 163      * Sends data to the process currently controlling the
 164      * teletype ( whose id is returned by foregroundProcessGroup() )
 165      *
 166      * @param buffer Pointer to the data to send.
 167      * @param length Length of @p buffer.
 168      */
 169     void sendData(const char* buffer, int length);
 170
 171   signals:
 172
 173     /**
 174      * Emitted when a new block of data is received from
 175      * the teletype.
 176      *
 177      * @param buffer Pointer to the data received.
 178      * @param length Length of @p buffer
 179      */
 180     void receivedData(const char* buffer, int length);
 181
 182   protected:
 183       void setupChildProcess();
 184
 185   private slots:
 186     // called when data is received from the terminal process
 187     void dataReceived();
 188
 189   private:
 190       void init();
 191
 192     // takes a list of key=value pairs and adds them
 193     // to the environment for the process
 194     void addEnvironmentVariables(const QStringList& environment);
 195
 196     int  _windowColumns;
 197     int  _windowLines;
 198     char _eraseChar;
 199     bool _xonXoff;
 200     bool _utf8;
 201 };
 202
 203 }
 204
 205 #endif // PTY_H