1/*
2 * This file is a part of QTerminal - http://gitorious.org/qterminal
3 *
4 * This file was un-linked from KDE and modified
5 * by Maxim Bourmistrov <maxim@unixconn.com>
6 *
7 */
8
9/*
10 This file is part of Konsole, KDE's terminal emulator.
11
12 Copyright 2007-2008 by Robert Knight <robertknight@gmail.com>
13 Copyright 1997,1998 by Lars Doelle <lars.doelle@on-line.de>
14
15 This program is free software; you can redistribute it and/or modify
16 it under the terms of the GNU General Public License as published by
17 the Free Software Foundation; either version 2 of the License, or
18 (at your option) any later version.
19
20 This program is distributed in the hope that it will be useful,
21 but WITHOUT ANY WARRANTY; without even the implied warranty of
22 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
23 GNU General Public License for more details.
24
25 You should have received a copy of the GNU General Public License
26 along with this program; if not, write to the Free Software
27 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
28 02110-1301 USA.
29*/
30
31#ifndef PTY_H
32#define PTY_H
33
34// Qt
35#include <QStringList>
36#include <QVector>
37#include <QList>
38#include <QSize>
39
40// KDE
41#include "kptyprocess.h"
42
43namespace Konsole {
44
45/**
46 * The Pty class is used to start the terminal process,
47 * send data to it, receive data from it and manipulate
48 * various properties of the pseudo-teletype interface
49 * used to communicate with the process.
50 *
51 * To use this class, construct an instance and connect
52 * to the sendData slot and receivedData signal to
53 * send data to or receive data from the process.
54 *
55 * To start the terminal process, call the start() method
56 * with the program name and appropriate arguments.
57 */
58class Pty: public KPtyProcess
59{
60Q_OBJECT
61
62 public:
63
64 /**
65 * Constructs a new Pty.
66 *
67 * Connect to the sendData() slot and receivedData() signal to prepare
68 * for sending and receiving data from the terminal process.
69 *
70 * To start the terminal process, call the run() method with the
71 * name of the program to start and appropriate arguments.
72 */
73 explicit Pty(QObject* parent = 0);
74
75 /**
76 * Construct a process using an open pty master.
77 * See KPtyProcess::KPtyProcess()
78 */
79 explicit Pty(int ptyMasterFd, QObject* parent = 0);
80
81 ~Pty();
82
83 /**
84 * Starts the terminal process.
85 *
86 * Returns 0 if the process was started successfully or non-zero
87 * otherwise.
88 *
89 * @param program Path to the program to start
90 * @param arguments Arguments to pass to the program being started
91 * @param environment A list of key=value pairs which will be added
92 * to the environment for the new process. At the very least this
93 * should include an assignment for the TERM environment variable.
94 * @param winid Specifies the value of the WINDOWID environment variable
95 * in the process's environment.
96 * @param addToUtmp Specifies whether a utmp entry should be created for
97 * the pty used. See K3Process::setUsePty()
98 * @param dbusService Specifies the value of the KONSOLE_DBUS_SERVICE
99 * environment variable in the process's environment.
100 * @param dbusSession Specifies the value of the KONSOLE_DBUS_SESSION
101 * environment variable in the process's environment.
102 */
103 int start( const QString& program,
104 const QStringList& arguments,
105 const QStringList& environment,
106 ulong winid,
107 bool addToUtmp
108 );
109
110 /**
111 * set properties for "EmptyPTY"
112 */
113 void setEmptyPTYProperties();
114
115 /** TODO: Document me */
116 void setWriteable(bool writeable);
117
118 /**
119 * Enables or disables Xon/Xoff flow control. The flow control setting
120 * may be changed later by a terminal application, so flowControlEnabled()
121 * may not equal the value of @p on in the previous call to setFlowControlEnabled()
122 */
123 void setFlowControlEnabled(bool on);
124
125 /** Queries the terminal state and returns true if Xon/Xoff flow control is enabled. */
126 bool flowControlEnabled() const;
127
128 /**
129 * Sets the size of the window (in lines and columns of characters)
130 * used by this teletype.
131 */
132 void setWindowSize(int lines, int cols);
133
134 /** Returns the size of the window used by this teletype. See setWindowSize() */
135 QSize windowSize() const;
136
137 /** TODO Document me */
138 void setErase(char erase);
139
140 /** */
141 char erase() const;
142
143 /**
144 * Returns the process id of the teletype's current foreground
145 * process. This is the process which is currently reading
146 * input sent to the terminal via. sendData()
147 *
148 * If there is a problem reading the foreground process group,
149 * 0 will be returned.
150 */
151 int foregroundProcessGroup() const;
152
153 public slots:
154
155 /**
156 * Put the pty into UTF-8 mode on systems which support it.
157 */
158 void setUtf8Mode(bool on);
159
160 /**
161 * Suspend or resume processing of data from the standard
162 * output of the terminal process.
163 *
164 * See K3Process::suspend() and K3Process::resume()
165 *
166 * @param lock If true, processing of output is suspended,
167 * otherwise processing is resumed.
168 */
169 void lockPty(bool lock);
170
171 /**
172 * Sends data to the process currently controlling the
173 * teletype ( whose id is returned by foregroundProcessGroup() )
174 *
175 * @param buffer Pointer to the data to send.
176 * @param length Length of @p buffer.
177 */
178 void sendData(const char* buffer, int length);
179
180 signals:
181
182 /**
183 * Emitted when a new block of data is received from
184 * the teletype.
185 *
186 * @param buffer Pointer to the data received.
187 * @param length Length of @p buffer
188 */
189 void receivedData(const char* buffer, int length);
190
191 protected:
192 void setupChildProcess();
193
194 private slots:
195 // called when data is received from the terminal process
196 void dataReceived();
197
198 private:
199 void init();
200
201 // takes a list of key=value pairs and adds them
202 // to the environment for the process
203 void addEnvironmentVariables(const QStringList& environment);
204
205 int _windowColumns;
206 int _windowLines;
207 char _eraseChar;
208 bool _xonXoff;
209 bool _utf8;
210};
211
212}
213
214#endif // PTY_H
215