1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2000 David Smith <dsmith@algonet.se>
4
5 This class was inspired by a previous KUrlCompletion by
6 SPDX-FileContributor: Henner Zeller <zeller@think.de>
7
8 SPDX-License-Identifier: LGPL-2.0-or-later
9*/
10
11#ifndef KURLCOMPLETION_H
12#define KURLCOMPLETION_H
13
14#include "kiowidgets_export.h"
15#include <kio/udsentry.h>
16
17#include <KCompletion>
18
19#include <QString>
20#include <QStringList>
21
22#include <memory>
23
24namespace KIO
25{
26class Job;
27}
28
29class KUrlCompletionPrivate;
30
31/**
32 * @class KUrlCompletion kurlcompletion.h <KUrlCompletion>
33 *
34 * This class does completion of URLs including user directories (~user)
35 * and environment variables. Remote URLs are passed to KIO.
36 *
37 * @short Completion of a single URL
38 * @author David Smith <dsmith@algonet.se>
39 */
40class KIOWIDGETS_EXPORT KUrlCompletion : public KCompletion
41{
42 Q_OBJECT
43
44public:
45 /**
46 * Determines how completion is done.
47 * @li ExeCompletion - executables in $PATH or with full path.
48 * @li FileCompletion - all files with full path or in dir(), URLs
49 * are listed using KIO.
50 * @li DirCompletion - Same as FileCompletion but only returns directories.
51 */
52 enum Mode { ExeCompletion = 1, FileCompletion, DirCompletion };
53
54 /**
55 * Constructs a KUrlCompletion object in FileCompletion mode.
56 */
57 KUrlCompletion();
58 /**
59 * This overloaded constructor allows you to set the Mode to ExeCompletion
60 * or FileCompletion without using setMode. Default is FileCompletion.
61 */
62 KUrlCompletion(Mode);
63 /**
64 * Destructs the KUrlCompletion object.
65 */
66 ~KUrlCompletion() override;
67
68 /**
69 * Finds completions to the given text.
70 *
71 * Remote URLs are listed with KIO. For performance reasons, local files
72 * are listed with KIO only if KURLCOMPLETION_LOCAL_KIO is set.
73 * The completion is done asynchronously if KIO is used.
74 *
75 * Returns the first match for user, environment, and local dir completion
76 * and QString() for asynchronous completion (KIO or threaded).
77 *
78 * @param text the text to complete
79 * @return the first match, or QString() if not found
80 */
81 QString makeCompletion(const QString &text) override;
82
83 /**
84 * Sets the current directory (used as base for completion).
85 * Default = $HOME.
86 * @param dir the current directory, as a URL (use QUrl::fromLocalFile for local paths)
87 */
88 virtual void setDir(const QUrl &dir);
89
90 /**
91 * Returns the current directory, as it was given in setDir
92 * @return the current directory, as a URL (use QUrl::toLocalFile for local paths)
93 */
94 virtual QUrl dir() const;
95
96 /**
97 * Check whether asynchronous completion is in progress.
98 * @return true if asynchronous completion is in progress
99 */
100 virtual bool isRunning() const;
101
102 /**
103 * Stops asynchronous completion.
104 */
105 virtual void stop();
106
107 /**
108 * Returns the completion mode: exe or file completion (default FileCompletion).
109 * @return the completion mode
110 */
111 virtual Mode mode() const;
112
113 /**
114 * Changes the completion mode: exe or file completion
115 * @param mode the new completion mode
116 */
117 virtual void setMode(Mode mode);
118
119 /**
120 * Checks whether environment variables are completed and
121 * whether they are replaced internally while finding completions.
122 * Default is enabled.
123 * @return true if environment variables will be replaced
124 */
125 virtual bool replaceEnv() const;
126
127 /**
128 * Enables/disables completion and replacement (internally) of
129 * environment variables in URLs. Default is enabled.
130 * @param replace true to replace environment variables
131 */
132 virtual void setReplaceEnv(bool replace);
133
134 /**
135 * Returns whether ~username is completed and whether ~username
136 * is replaced internally with the user's home directory while
137 * finding completions. Default is enabled.
138 * @return true to replace tilde with the home directory
139 */
140 virtual bool replaceHome() const;
141
142 /**
143 * Enables/disables completion of ~username and replacement
144 * (internally) of ~username with the user's home directory.
145 * Default is enabled.
146 * @param replace true to replace tilde with the home directory
147 */
148 virtual void setReplaceHome(bool replace);
149
150 /**
151 * Replaces username and/or environment variables, depending on the
152 * current settings and returns the filtered url. Only works with
153 * local files, i.e. returns back the original string for non-local
154 * urls.
155 * @param text the text to process
156 * @return the path or URL resulting from this operation. If you
157 * want to convert it to a QUrl, use QUrl::fromUserInput.
158 */
159 QString replacedPath(const QString &text) const;
160
161 /**
162 * @internal I'll let ossi add a real one to KShell :)
163 */
164 static QString replacedPath(const QString &text, bool replaceHome, bool replaceEnv = true);
165
166 /**
167 * Sets the MIME type filters for the file dialog.
168 * @see QFileDialog::setMimeTypeFilters()
169 * @since 5.38
170 */
171 void setMimeTypeFilters(const QStringList &mimeTypes);
172
173 /**
174 * Returns the MIME type filters for the file dialog.
175 * @see QFileDialog::mimeTypeFilters()
176 * @since 5.38
177 */
178 QStringList mimeTypeFilters() const;
179
180protected:
181 // Called by KCompletion, adds '/' to directories
182 void postProcessMatch(QString *match) const override;
183 void postProcessMatches(QStringList *matches) const override;
184 void postProcessMatches(KCompletionMatches *matches) const override;
185
186private:
187 std::unique_ptr<KUrlCompletionPrivate> const d;
188};
189
190#endif // KURLCOMPLETION_H
191

source code of kio/src/widgets/kurlcompletion.h