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/QSize>
28
29// KDE
30#include <KPtyProcess>
31
32// Konsole
33#include "konsole_export.h"
34
35class QStringList;
36
37namespace Konsole
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 */
52class KONSOLEPRIVATE_EXPORT Pty: public KPtyProcess
53{
54 Q_OBJECT
55
56public:
57 /**
58 * Constructs a new Pty.
59 *
60 * Connect to the sendData() slot and receivedData() signal to prepare
61 * for sending and receiving data from the terminal process.
62 *
63 * To start the terminal process, call the run() method with the
64 * name of the program to start and appropriate arguments.
65 */
66 explicit Pty(QObject* parent = 0);
67
68 /**
69 * Construct a process using an open pty master.
70 * See KPtyProcess::KPtyProcess()
71 */
72 explicit Pty(int ptyMasterFd, QObject* parent = 0);
73
74 ~Pty();
75
76 /**
77 * Starts the terminal process.
78 *
79 * Returns 0 if the process was started successfully or non-zero
80 * otherwise.
81 *
82 * @param program Path to the program to start
83 * @param arguments Arguments to pass to the program being started
84 * @param environment A list of key=value pairs which will be added
85 * to the environment for the new process. At the very least this
86 * should include an assignment for the TERM environment variable.
87 */
88 int start(const QString& program,
89 const QStringList& arguments,
90 const QStringList& environment
91 );
92
93 /** Control whether the pty device is writeable by group members. */
94 void setWriteable(bool writeable);
95
96 /**
97 * Enables or disables Xon/Xoff flow control. The flow control setting
98 * may be changed later by a terminal application, so flowControlEnabled()
99 * may not equal the value of @p on in the previous call to setFlowControlEnabled()
100 */
101 void setFlowControlEnabled(bool on);
102
103 /** Queries the terminal state and returns true if Xon/Xoff flow control is enabled. */
104 bool flowControlEnabled() const;
105
106 /**
107 * Sets the size of the window (in columns and lines of characters)
108 * used by this teletype.
109 */
110 void setWindowSize(int columns, int lines);
111
112 /** Returns the size of the window used by this teletype. See setWindowSize() */
113 QSize windowSize() const;
114
115 /**
116 * Sets the special character for erasing previous not-yet-erased character.
117 * See termios(3) for detailed description.
118 */
119 void setEraseChar(char eraseChar);
120
121 /** */
122 char eraseChar() const;
123
124 /**
125 * Sets the initial working directory.
126 */
127 void setInitialWorkingDirectory(const QString& dir);
128
129 /**
130 * Returns the process id of the teletype's current foreground
131 * process. This is the process which is currently reading
132 * input sent to the terminal via. sendData()
133 *
134 * If there is a problem reading the foreground process group,
135 * 0 will be returned.
136 */
137 int foregroundProcessGroup() const;
138
139 /**
140 * Close the underlying pty master/slave pair.
141 */
142 void closePty();
143
144public slots:
145 /**
146 * Put the pty into UTF-8 mode on systems which support it.
147 */
148 void setUtf8Mode(bool on);
149
150 /**
151 * Sends data to the process currently controlling the
152 * teletype ( whose id is returned by foregroundProcessGroup() )
153 *
154 * @param buffer Pointer to the data to send.
155 * @param length Length of @p buffer.
156 */
157 void sendData(const char* buffer, int length);
158
159signals:
160 /**
161 * Emitted when a new block of data is received from
162 * the teletype.
163 *
164 * @param buffer Pointer to the data received.
165 * @param length Length of @p buffer
166 */
167 void receivedData(const char* buffer, int length);
168
169protected:
170 void setupChildProcess();
171
172private slots:
173 // called when data is received from the terminal process
174 void dataReceived();
175
176private:
177 void init();
178
179 // takes a list of key=value pairs and adds them
180 // to the environment for the process
181 void addEnvironmentVariables(const QStringList& environment);
182
183 int _windowColumns;
184 int _windowLines;
185 char _eraseChar;
186 bool _xonXoff;
187 bool _utf8;
188};
189}
190
191#endif // PTY_H
192