1/* This file is part of the KDE libraries
2 Copyright (C) 2000 David Smith <dsmith@algonet.se>
3
4 This class was inspired by a previous KUrlCompletion by
5 Henner Zeller <zeller@think.de>
6
7 This library is free software; you can redistribute it and/or
8 modify it under the terms of the GNU Library General Public
9 License as published by the Free Software Foundation; either
10 version 2 of the License, or (at your option) any later version.
11
12 This library 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 GNU
15 Library General Public License for more details.
16
17 You should have received a copy of the GNU Library General Public License
18 along with this library; see the file COPYING.LIB. If not, write to
19 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
20 Boston, MA 02110-1301, USA.
21*/
22
23#ifndef KURLCOMPLETION_H
24#define KURLCOMPLETION_H
25
26#include <kcompletion.h>
27#include <kio/jobclasses.h>
28#include <QtCore/QString>
29
30class QStringList;
31class KUrl;
32class KUrlCompletionPrivate;
33
34/**
35 * This class does completion of URLs including user directories (~user)
36 * and environment variables. Remote URLs are passed to KIO.
37 *
38 * @short Completion of a single URL
39 * @author David Smith <dsmith@algonet.se>
40 */
41class KIO_EXPORT KUrlCompletion : public KCompletion
42{
43 Q_OBJECT
44
45public:
46 /**
47 * Determines how completion is done.
48 * @li ExeCompletion - executables in $PATH or with full path.
49 * @li FileCompletion - all files with full path or in dir(), URLs
50 * are listed using KIO.
51 * @li DirCompletion - Same as FileCompletion but only returns directories.
52 */
53 enum Mode { ExeCompletion = 1, FileCompletion, DirCompletion };
54
55 /**
56 * Constructs a KUrlCompletion object in FileCompletion mode.
57 */
58 KUrlCompletion();
59 /**
60 * This overloaded constructor allows you to set the Mode to ExeCompletion
61 * or FileCompletion without using setMode. Default is FileCompletion.
62 */
63 KUrlCompletion(Mode);
64 /**
65 * Destructs the KUrlCompletion object.
66 */
67 virtual ~KUrlCompletion();
68
69 /**
70 * Finds completions to the given text.
71 *
72 * Remote URLs are listed with KIO. For performance reasons, local files
73 * are listed with KIO only if KURLCOMPLETION_LOCAL_KIO is set.
74 * The completion is done asyncronously if KIO is used.
75 *
76 * Returns the first match for user, environment, and local dir completion
77 * and QString() for asynchronous completion (KIO or threaded).
78 *
79 * @param text the text to complete
80 * @return the first match, or QString() if not found
81 */
82 virtual QString makeCompletion(const QString& text);
83
84 /**
85 * Sets the current directory (used as base for completion).
86 * Default = $HOME.
87 * @param dir the current directory, either as a path or URL
88 */
89 virtual void setDir(const QString& dir);
90
91 /**
92 * Returns the current directory, as it was given in setDir
93 * @return the current directory (path or URL)
94 */
95 virtual QString dir() const;
96
97 /**
98 * Check whether asynchronous completion is in progress.
99 * @return true if asynchronous completion is in progress
100 */
101 virtual bool isRunning() const;
102
103 /**
104 * Stops asynchronous completion.
105 */
106 virtual void stop();
107
108 /**
109 * Returns the completion mode: exe or file completion (default FileCompletion).
110 * @return the completion mode
111 */
112 virtual Mode mode() const;
113
114 /**
115 * Changes the completion mode: exe or file completion
116 * @param mode the new completion mode
117 */
118 virtual void setMode(Mode mode);
119
120 /**
121 * Checks whether environment variables are completed and
122 * whether they are replaced internally while finding completions.
123 * Default is enabled.
124 * @return true if environment vvariables will be replaced
125 */
126 virtual bool replaceEnv() const;
127
128 /**
129 * Enables/disables completion and replacement (internally) of
130 * environment variables in URLs. Default is enabled.
131 * @param replace true to replace environment variables
132 */
133 virtual void setReplaceEnv(bool replace);
134
135 /**
136 * Returns whether ~username is completed and whether ~username
137 * is replaced internally with the user's home directory while
138 * finding completions. Default is enabled.
139 * @return true to replace tilde with the home directory
140 */
141 virtual bool replaceHome() const;
142
143 /**
144 * Enables/disables completion of ~username and replacement
145 * (internally) of ~username with the user's home directory.
146 * Default is enabled.
147 * @param replace true to replace tilde with the home directory
148 */
149 virtual void setReplaceHome(bool replace);
150
151 /**
152 * Replaces username and/or environment variables, depending on the
153 * current settings and returns the filtered url. Only works with
154 * local files, i.e. returns back the original string for non-local
155 * urls.
156 * @param text the text to process
157 * @return the path or URL resulting from this operation. If you
158 * want to convert it to a KUrl, use KUrl::fromPathOrUrl.
159 */
160 QString replacedPath(const QString& text) const;
161
162 /**
163 * @internal I'll let ossi add a real one to KShell :)
164 */
165 static QString replacedPath(const QString& text,
166 bool replaceHome, bool replaceEnv = true);
167
168protected:
169 // Called by KCompletion, adds '/' to directories
170 void postProcessMatch(QString* match) const;
171 void postProcessMatches(QStringList* matches) const;
172 void postProcessMatches(KCompletionMatches* matches) const;
173
174 virtual void customEvent(QEvent* e);
175
176private:
177 KUrlCompletionPrivate* const d;
178
179 Q_PRIVATE_SLOT(d, void _k_slotEntries (KIO::Job*, const KIO::UDSEntryList&))
180 Q_PRIVATE_SLOT(d, void _k_slotIOFinished (KJob*))
181};
182
183#endif // KURLCOMPLETION_H
184