File indexing completed on 2024-12-01 12:36:41

0001 /*
0002     This file is part of the KDE libraries
0003     SPDX-FileCopyrightText: 2000 David Smith <dsmith@algonet.se>
0004 
0005     This class was inspired by a previous KUrlCompletion by
0006     SPDX-FileContributor: Henner Zeller <zeller@think.de>
0007 
0008     SPDX-License-Identifier: LGPL-2.0-or-later
0009 */
0010 
0011 #ifndef KURLCOMPLETION_H
0012 #define KURLCOMPLETION_H
0013 
0014 #include "kiowidgets_export.h"
0015 #include <kio/udsentry.h>
0016 
0017 #include <KCompletion>
0018 
0019 #include <QString>
0020 #include <QStringList>
0021 
0022 #include <memory>
0023 
0024 namespace KIO
0025 {
0026 class Job;
0027 }
0028 
0029 class KUrlCompletionPrivate;
0030 
0031 /**
0032  * @class KUrlCompletion kurlcompletion.h <KUrlCompletion>
0033  *
0034  * This class does completion of URLs including user directories (~user)
0035  * and environment variables.  Remote URLs are passed to KIO.
0036  *
0037  * @short Completion of a single URL
0038  * @author David Smith <dsmith@algonet.se>
0039  */
0040 class KIOWIDGETS_EXPORT KUrlCompletion : public KCompletion
0041 {
0042     Q_OBJECT
0043 
0044 public:
0045     /**
0046      * Determines how completion is done.
0047      * @li ExeCompletion - executables in $PATH or with full path.
0048      * @li FileCompletion - all files with full path or in dir(), URLs
0049      * are listed using KIO.
0050      * @li DirCompletion - Same as FileCompletion but only returns directories.
0051      */
0052     enum Mode { ExeCompletion = 1, FileCompletion, DirCompletion };
0053 
0054     /**
0055      * Constructs a KUrlCompletion object in FileCompletion mode.
0056      */
0057     KUrlCompletion();
0058     /**
0059      * This overloaded constructor allows you to set the Mode to ExeCompletion
0060      * or FileCompletion without using setMode. Default is FileCompletion.
0061      */
0062     KUrlCompletion(Mode);
0063     /**
0064      * Destructs the KUrlCompletion object.
0065      */
0066     ~KUrlCompletion() override;
0067 
0068     /**
0069      * Finds completions to the given text.
0070      *
0071      * Remote URLs are listed with KIO. For performance reasons, local files
0072      * are listed with KIO only if KURLCOMPLETION_LOCAL_KIO is set.
0073      * The completion is done asynchronously if KIO is used.
0074      *
0075      * Returns the first match for user, environment, and local dir completion
0076      * and QString() for asynchronous completion (KIO or threaded).
0077      *
0078      * @param text the text to complete
0079      * @return the first match, or QString() if not found
0080      */
0081     QString makeCompletion(const QString &text) override;
0082 
0083     /**
0084      * Sets the current directory (used as base for completion).
0085      * Default = $HOME.
0086      * @param dir the current directory, as a URL (use QUrl::fromLocalFile for local paths)
0087      */
0088     virtual void setDir(const QUrl &dir);
0089 
0090     /**
0091      * Returns the current directory, as it was given in setDir
0092      * @return the current directory, as a URL (use QUrl::toLocalFile for local paths)
0093      */
0094     virtual QUrl dir() const;
0095 
0096     /**
0097      * Check whether asynchronous completion is in progress.
0098      * @return true if asynchronous completion is in progress
0099      */
0100     virtual bool isRunning() const;
0101 
0102     /**
0103      * Stops asynchronous completion.
0104      */
0105     virtual void stop();
0106 
0107     /**
0108      * Returns the completion mode: exe or file completion (default FileCompletion).
0109      * @return the completion mode
0110      */
0111     virtual Mode mode() const;
0112 
0113     /**
0114      * Changes the completion mode: exe or file completion
0115      * @param mode the new completion mode
0116      */
0117     virtual void setMode(Mode mode);
0118 
0119     /**
0120      * Checks whether environment variables are completed and
0121      * whether they are replaced internally while finding completions.
0122      * Default is enabled.
0123      * @return true if environment variables will be replaced
0124      */
0125     virtual bool replaceEnv() const;
0126 
0127     /**
0128      * Enables/disables completion and replacement (internally) of
0129      * environment variables in URLs. Default is enabled.
0130      * @param replace true to replace environment variables
0131      */
0132     virtual void setReplaceEnv(bool replace);
0133 
0134     /**
0135      * Returns whether ~username is completed and whether ~username
0136      * is replaced internally with the user's home directory while
0137      * finding completions. Default is enabled.
0138      * @return true to replace tilde with the home directory
0139      */
0140     virtual bool replaceHome() const;
0141 
0142     /**
0143      * Enables/disables completion of ~username and replacement
0144      * (internally) of ~username with the user's home directory.
0145      * Default is enabled.
0146      * @param replace true to replace tilde with the home directory
0147      */
0148     virtual void setReplaceHome(bool replace);
0149 
0150     /**
0151      * Replaces username and/or environment variables, depending on the
0152      * current settings and returns the filtered url. Only works with
0153      * local files, i.e. returns back the original string for non-local
0154      * urls.
0155      * @param text the text to process
0156      * @return the path or URL resulting from this operation. If you
0157      * want to convert it to a QUrl, use QUrl::fromUserInput.
0158      */
0159     QString replacedPath(const QString &text) const;
0160 
0161     /**
0162      * @internal I'll let ossi add a real one to KShell :)
0163      */
0164     static QString replacedPath(const QString &text, bool replaceHome, bool replaceEnv = true);
0165 
0166     /**
0167      * Sets the MIME type filters for the file dialog.
0168      * @see QFileDialog::setMimeTypeFilters()
0169      * @since 5.38
0170      */
0171     void setMimeTypeFilters(const QStringList &mimeTypes);
0172 
0173     /**
0174      * Returns the MIME type filters for the file dialog.
0175      * @see QFileDialog::mimeTypeFilters()
0176      * @since 5.38
0177      */
0178     QStringList mimeTypeFilters() const;
0179 
0180 protected:
0181     // Called by KCompletion, adds '/' to directories
0182     void postProcessMatch(QString *match) const override;
0183     void postProcessMatches(QStringList *matches) const override;
0184     void postProcessMatches(KCompletionMatches *matches) const override;
0185 
0186     void customEvent(QEvent *e) override; // KF6 TODO: remove
0187 
0188 private:
0189     std::unique_ptr<KUrlCompletionPrivate> const d;
0190 };
0191 
0192 #endif // KURLCOMPLETION_H