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