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