1// interface.h
2// Copyright (C) 2002 Dominique Devriese <devriese@kde.org>
3
4// This library is free software; you can redistribute it and/or
5// modify it under the terms of the GNU Lesser General Public
6// License as published by the Free Software Foundation; either
7// version 2.1 of the License, or (at your option) any later version.
8
9// This library is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12// Lesser General Public License for more details.
13
14// You should have received a copy of the GNU Lesser General Public
15// License along with this library; if not, write to the Free Software
16// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
17// 02110-1301 USA
18
19#ifndef KDELIBS_KDE_TERMINAL_INTERFACE_H
20#define KDELIBS_KDE_TERMINAL_INTERFACE_H
21
22#include <QtCore/QObject>
23
24class QStringList;
25
26/**
27 * TerminalInterface is an interface implemented by KonsolePart to
28 * allow developers access to the KonsolePart in ways that are not
29 * possible through the normal KPart interface.
30 *
31 * Note that besides the functions below here, KonsolePart also has
32 * some signals you can connect to. They aren't in this class cause
33 * we can't have signals without having a QObject, which
34 * TerminalInterface is not.
35 *
36 * These are some signals you can connect to:
37 * void currentDirectoryChanged(const QString& dir);
38 *
39 * See the example code below for how to connect to these.
40 *
41 * Use it like this:
42 * \code
43 * //query the .desktop file to get service information about konsolepart
44 * KService::Ptr service = KService::serviceByDesktopName("konsolepart");
45 *
46 * if (!service)
47 * {
48 * QMessageBox::critical(this, tr("Konsole not installed"), tr("Please install the kde konsole and try again!"), QMessageBox::Ok);
49 * return ;
50 * }
51 *
52 * // create one instance of konsolepart
53 * KParts::ReadOnlyPart* p = service->createInstance<KParts::ReadOnlyPart>(parent, parentWidget, QVariantList());
54 *
55 * if (!p)
56 * {
57 * return;
58 * }
59 *
60 * // cast the konsolepart to the TerminalInterface..
61 * TerminalInterface* t = qobject_cast<TerminalInterface*>(p);
62 *
63 * if (!t)
64 * {
65 * return;
66 * }
67 *
68 * // now use the interface in all sorts of ways, e.g.
69 * // t->showShellInDir( QDir::home().path() );
70 * // or:
71 * // QStringList l;
72 * // l.append( "python" );
73 * // t->startProgram( QString::fromUtf8( "/usr/bin/python" ), l);
74 * // or connect to one of the signals. Connect to the Part object,
75 * // not to the TerminalInterface, since the latter is no QObject,
76 * // and as such cannot have signals..:
77 * // connect(p, SIGNAL(currentDirectoryChanged(QString)),
78 * // this, SLOT(currentDirectoryChanged(QString)));
79 * // etc.
80 *
81 * \endcode
82 *
83 * @author Dominique Devriese <devriese@kde.org>
84 */
85class TerminalInterface
86{
87public:
88 virtual ~TerminalInterface(){}
89 /**
90 * This starts @p program, with arguments @p args
91 */
92 virtual void startProgram( const QString& program,
93 const QStringList& args ) = 0;
94 /**
95 * If no shell is running, this starts a shell with the
96 * @dir as the starting directory.
97 * If a shell is already running, nothing is done.
98 */
99 virtual void showShellInDir( const QString& dir ) = 0;
100
101 /**
102 * This sends @param text as input to the currently running
103 * program..
104 */
105 virtual void sendInput( const QString& text ) = 0;
106
107};
108
109Q_DECLARE_INTERFACE(TerminalInterface, "org.kde.TerminalInterface")
110
111#endif
112