File indexing completed on 2024-11-10 12:24:06

0001 /*
0002     This file is part of the KDE libraries
0003     SPDX-FileCopyrightText: 1999, 2000, 2001 Carsten Pfeiffer <pfeiffer@kde.org>
0004     SPDX-FileCopyrightText: 2013 Teo Mrnjavac <teo@kde.org>
0005 
0006     SPDX-License-Identifier: LGPL-2.0-only
0007 */
0008 
0009 #ifndef KURLREQUESTER_H
0010 #define KURLREQUESTER_H
0011 
0012 #include "kiowidgets_export.h"
0013 
0014 #include <KEditListWidget>
0015 #include <kfile.h>
0016 
0017 #include <QFileDialog>
0018 #include <QPushButton>
0019 #include <QUrl>
0020 
0021 #include <memory>
0022 
0023 class KComboBox;
0024 class KLineEdit;
0025 class KUrlCompletion;
0026 
0027 class QEvent;
0028 class QString;
0029 
0030 /**
0031  * @class KUrlRequester kurlrequester.h <KUrlRequester>
0032  *
0033  * This class is a widget showing a lineedit and a button, which invokes a
0034  * filedialog. File name completion is available in the lineedit.
0035  *
0036  * The default for the filedialog is to ask for one existing local file, i.e.
0037  * the default mode is 'KFile::File | KFile::ExistingOnly | KFile::LocalOnly',
0038  * which you can change by using setMode().
0039  *
0040  * The default filter is "*", i.e. show all files, which you can change by
0041  * using setNameFilters() or setMimeTypeFilters().
0042  *
0043  * By default the start directory is the current working directory, or the
0044  * last directory where a file has been selected previously, you can change
0045  * this behavior by calling setStartDir().
0046  *
0047  * The default window modality for the file dialog is Qt::ApplicationModal
0048  *
0049  * \image html kurlrequester.png "KUrlRequester"
0050  *
0051  * @short A widget to request a filename/url from the user
0052  * @author Carsten Pfeiffer <pfeiffer@kde.org>
0053  */
0054 class KIOWIDGETS_EXPORT KUrlRequester : public QWidget
0055 {
0056     Q_OBJECT
0057     Q_PROPERTY(QUrl url READ url WRITE setUrl NOTIFY textChanged USER true)
0058 #if KIOWIDGETS_BUILD_DEPRECATED_SINCE(5, 108)
0059     /// @deprecated Since 5.108, use nameFilters
0060     Q_PROPERTY(QString filter READ filter WRITE setFilter)
0061 #endif
0062     /// @since 5.108
0063     Q_PROPERTY(QStringList nameFilters READ nameFilters WRITE setNameFilters)
0064     Q_PROPERTY(KFile::Modes mode READ mode WRITE setMode)
0065     Q_PROPERTY(QFileDialog::AcceptMode acceptMode READ acceptMode WRITE setAcceptMode)
0066 #if KIOWIDGETS_BUILD_DEPRECATED_SINCE(5, 0)
0067     /// @deprecated Since 5.0, use placeholderText
0068     Q_PROPERTY(QString clickMessage READ clickMessage WRITE setClickMessage)
0069 #endif
0070     Q_PROPERTY(QString placeholderText READ placeholderText WRITE setPlaceholderText)
0071     Q_PROPERTY(QString text READ text WRITE setText NOTIFY textChanged)
0072     Q_PROPERTY(Qt::WindowModality fileDialogModality READ fileDialogModality WRITE setFileDialogModality)
0073 
0074 public:
0075     /**
0076      * Constructs a KUrlRequester widget.
0077      */
0078     explicit KUrlRequester(QWidget *parent = nullptr);
0079 
0080     /**
0081      * Constructs a KUrlRequester widget with the initial URL @p url.
0082      */
0083     explicit KUrlRequester(const QUrl &url, QWidget *parent = nullptr);
0084 
0085     /**
0086      * Special constructor, which creates a KUrlRequester widget with a custom
0087      * edit-widget. The edit-widget can be either a KComboBox or a KLineEdit
0088      * (or inherited thereof). Note: for geometry management reasons, the
0089      * edit-widget is reparented to have the KUrlRequester as parent.
0090      */
0091     KUrlRequester(QWidget *editWidget, QWidget *parent);
0092     /**
0093      * Destructs the KUrlRequester.
0094      */
0095     ~KUrlRequester() override;
0096 
0097     /**
0098      * @returns the current url in the lineedit. May be malformed, if the user
0099      * entered something weird. For local files, ~user or environment variables
0100      * are substituted, relative paths will be resolved against startDir()
0101      */
0102     QUrl url() const;
0103 
0104     /**
0105      * @returns the current start dir
0106      * @since 4.3
0107      */
0108     QUrl startDir() const;
0109 
0110     /**
0111      * @returns the current text in the lineedit or combobox.
0112      * This does not do the URL expansion that url() does, it's only provided
0113      * for cases where KUrlRequester is used to enter URL-or-something-else,
0114      * like KOpenWithDialog where you can type a full command with arguments.
0115      *
0116      * @since 4.2
0117      */
0118     QString text() const;
0119 
0120     /**
0121      * Sets the mode of the file dialog.
0122      *
0123      * The default mode of the file dialog is 'KFile::File | KFile::ExistingOnly | KFile::LocalOnly',
0124      * which you can change using this method.
0125      *
0126      * @note You can only select one file from the file dialog invoked
0127      * by KUrlRequester, hence setting KFile::Files doesn't make
0128      * much sense here.
0129      *
0130      * @param mode an OR'ed combination of KFile::Modes flags
0131      *
0132      * @see QFileDialog::setFileMode()
0133      */
0134     void setMode(KFile::Modes mode);
0135 
0136     /**
0137      * Returns the current mode
0138      * @see QFileDialog::fileMode()
0139      */
0140     KFile::Modes mode() const;
0141 
0142     /**
0143      * Sets the open / save mode of the file dialog.
0144      *
0145      * The default is QFileDialog::AcceptOpen.
0146      *
0147      * @see QFileDialog::setAcceptMode()
0148      * @since 5.33
0149      */
0150     void setAcceptMode(QFileDialog::AcceptMode m);
0151 
0152     /**
0153      * Returns the current open / save mode
0154      * @see QFileDialog::acceptMode()
0155      * @since 5.33
0156      */
0157     QFileDialog::AcceptMode acceptMode() const;
0158 
0159 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 108)
0160     /**
0161      * Sets the filters for the file dialog, separated by \\n.
0162      * Use "*.foo *.bar|Comment" syntax for each named filter.
0163      * "*.foo *.bar" for name-less filters also is supported.
0164      * @note This filter syntax is different from the one used in
0165      * QFileDialog::nameFilters() and converted internally.
0166      * @see filter()
0167      * @deprecated Since 5.108, use setNameFilters(const QStringList &) or setNameFilter(const QString &).
0168      *              Note: the filter argument might need adaption, due to the different filter syntax.
0169      */
0170     KIOWIDGETS_DEPRECATED_VERSION(
0171         5,
0172         108,
0173         "Use KUrlRequester::setNameFilters(const QStringList &) or KUrlRequester::setNameFilter(const QString &). NOTE: different filter syntax.")
0174     void setFilter(const QString &filter);
0175 #endif
0176 
0177 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 108)
0178     /**
0179      * Returns the filters for the file dialog, separated by \\n.
0180      * @note This filter syntax is different from the one used in
0181      * QFileDialog::nameFilters() and converted internally.
0182      * @see setFilter()
0183      * @deprecated Since 5.108, use nameFilters() const.
0184      */
0185     KIOWIDGETS_DEPRECATED_VERSION(5, 108, "Use KUrlRequester::nameFilters() const")
0186     QString filter() const;
0187 #endif
0188 
0189     /**
0190      * Sets the filters for the file dialog.
0191      * @see QFileDialog::setNameFilters()
0192      * @since 5.108
0193      */
0194     void setNameFilters(const QStringList &filters);
0195 
0196     /**
0197      * Sets the filters for the file dialog.
0198      * @see QFileDialog::setNameFilter()
0199      * @since 5.108
0200      */
0201     void setNameFilter(const QString &filter);
0202 
0203     /**
0204      * Returns the filters for the file dialog.
0205      * @see QFileDialog::nameFilters()
0206      * @since 5.108
0207      */
0208     QStringList nameFilters() const;
0209 
0210     /**
0211      * Sets the MIME type filters for the file dialog.
0212      * @see QFileDialog::setMimeTypeFilters()
0213      * @since 5.31
0214      */
0215     void setMimeTypeFilters(const QStringList &mimeTypes);
0216     /**
0217      * Returns the MIME type filters for the file dialog.
0218      * @see QFileDialog::mimeTypeFilters()
0219      * @since 5.31
0220      */
0221     QStringList mimeTypeFilters() const;
0222 
0223     /**
0224      * @returns a pointer to the filedialog.
0225      * You can use this to customize the dialog, e.g. to call setLocationLabel
0226      * or other things which are not accessible in the KUrlRequester API.
0227      *
0228      * Never returns 0. This method creates the file dialog on demand.
0229      *
0230      * @deprecated since 5.0. The dialog will be created anyway when the user
0231      * requests it, and will behave according to the properties of KUrlRequester.
0232      */
0233     KIOWIDGETS_DEPRECATED_VERSION(5, 0, "See API docs")
0234     virtual QFileDialog *fileDialog() const;
0235 
0236     /**
0237      * @returns a pointer to the lineedit, either the default one, or the
0238      * special one, if you used the special constructor.
0239      *
0240      * It is provided so that you can e.g. set an own completion object
0241      * (e.g. KShellCompletion) into it.
0242      */
0243     KLineEdit *lineEdit() const;
0244 
0245     /**
0246      * @returns a pointer to the combobox, in case you have set one using the
0247      * special constructor. Returns 0L otherwise.
0248      */
0249     KComboBox *comboBox() const;
0250 
0251     /**
0252      * @returns a pointer to the pushbutton. It is provided so that you can
0253      * specify an own pixmap or a text, if you really need to.
0254      */
0255     QPushButton *button() const;
0256 
0257     /**
0258      * @returns the KUrlCompletion object used in the lineedit/combobox.
0259      */
0260     KUrlCompletion *completionObject() const;
0261 
0262     /**
0263      * @returns an object, suitable for use with KEditListWidget. It allows you
0264      * to put this KUrlRequester into a KEditListWidget.
0265      * Basically, do it like this:
0266      * \code
0267      * KUrlRequester *req = new KUrlRequester( someWidget );
0268      * [...]
0269      * KEditListWidget *editListWidget = new KEditListWidget( req->customEditor(), someWidget );
0270      * \endcode
0271      */
0272     const KEditListWidget::CustomEditor &customEditor();
0273 
0274 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 0)
0275     /**
0276      * @returns the message set with setClickMessage
0277      * @since 4.2
0278      * @deprecated Since 5.0, use KUrlRequester::placeholderText instead.
0279      */
0280     KIOWIDGETS_DEPRECATED_VERSION(5, 0, "Use KUrlRequester::placeholderText()")
0281     QString clickMessage() const;
0282 #endif
0283 
0284 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 0)
0285     /**
0286      * Set a click message @p msg
0287      * @since 4.2
0288      * @deprecated Since 5.0, use KUrlRequester::setPlaceholderText instead.
0289      */
0290     KIOWIDGETS_DEPRECATED_VERSION(5, 0, "Use KUrlRequester::setPlaceholderText(const QString&)")
0291     void setClickMessage(const QString &msg);
0292 #endif
0293 
0294     /**
0295      * @return the message set with setPlaceholderText
0296      * @since 5.0
0297      */
0298     QString placeholderText() const;
0299 
0300     /**
0301      * This makes the KUrlRequester line edit display a grayed-out hinting text as long as
0302      * the user didn't enter any text. It is often used as indication about
0303      * the purpose of the line edit.
0304      * @since 5.0
0305      */
0306     void setPlaceholderText(const QString &msg);
0307 
0308     /**
0309      * @returns the window modality of the file dialog set with setFileDialogModality
0310      * @since 4.4
0311      */
0312     Qt::WindowModality fileDialogModality() const;
0313 
0314     /**
0315      * Set the window modality for the file dialog to @p modality
0316      * Directory selection dialogs are always modal
0317      *
0318      * The default is Qt::ApplicationModal.
0319      *
0320      * @since 4.4
0321      */
0322     void setFileDialogModality(Qt::WindowModality modality);
0323 
0324 public Q_SLOTS:
0325     /**
0326      * Sets the url in the lineedit to @p url.
0327      */
0328     void setUrl(const QUrl &url);
0329 
0330     /**
0331      * Sets the start dir @p startDir.
0332      * The start dir is only used when the URL isn't set.
0333      * @since 4.3
0334      */
0335     void setStartDir(const QUrl &startDir);
0336 
0337 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(4, 3)
0338     /**
0339      * Sets the url in the lineedit to @p QUrl::fromLocalFile(path).
0340      * This is only for local paths; do not pass a url here.
0341      * This method is mostly for "local paths only" url requesters,
0342      * for instance those set up with setMode(KFile::File|KFile::ExistingOnly|KFile::LocalOnly)
0343      *
0344      * @deprecated Since 4.3. Use setUrl(QUrl::fromLocalFile(path)) instead.
0345      */
0346     KIOWIDGETS_DEPRECATED_VERSION(4, 3, "Use KUrlRequester::setUrl(QUrl::fromLocalFile(path))")
0347     void setPath(const QString &path);
0348 #endif
0349 
0350     /**
0351      * Sets the current text in the lineedit or combobox.
0352      * This is used for cases where KUrlRequester is used to
0353      * enter URL-or-something-else, like KOpenWithDialog where you
0354      * can type a full command with arguments.
0355      *
0356      * @see text
0357      * @since 4.3
0358      */
0359     void setText(const QString &text);
0360 
0361     /**
0362      * Clears the lineedit/combobox.
0363      */
0364     void clear();
0365 
0366 Q_SIGNALS:
0367     // forwards from LineEdit
0368     /**
0369      * Emitted when the text in the lineedit changes.
0370      * The parameter contains the contents of the lineedit.
0371      */
0372     void textChanged(const QString &);
0373 
0374     /**
0375      * Emitted when the text in the lineedit was modified by the user.
0376      * Unlike textChanged(), this signal is not emitted when the text is changed programmatically, for example, by calling setText().
0377      * @since 5.21
0378      */
0379     void textEdited(const QString &);
0380 
0381 #if KIOWIDGETS_ENABLE_DEPRECATED_SINCE(5, 80)
0382     /**
0383      * Emitted when return or enter was pressed in the lineedit.
0384      *
0385      * @deprecated since 5.80, use KUrlRequester::returnPressed(const QString &) signal
0386      */
0387     KIOWIDGETS_DEPRECATED_VERSION(5, 80, "Use KUrlRequester::returnPressed(const QString &) signal")
0388     void returnPressed(); // clazy:exclude=overloaded-signal
0389 #endif
0390 
0391     /**
0392      * Emitted when return or enter was pressed in the lineedit.
0393      * The parameter contains the contents of the lineedit.
0394      */
0395     void returnPressed(const QString &text); // clazy:exclude=overloaded-signal
0396 
0397     /**
0398      * Emitted before the filedialog is going to open. Connect
0399      * to this signal to "configure" the filedialog, e.g. set the
0400      * filefilter, the mode, a preview-widget, etc. It's usually
0401      * not necessary to set a URL for the filedialog, as it will
0402      * get set properly from the editfield contents.
0403      *
0404      * If you use multiple KUrlRequesters, you can connect all of them
0405      * to the same slot and use the given KUrlRequester pointer to know
0406      * which one is going to open.
0407      */
0408     void openFileDialog(KUrlRequester *);
0409 
0410     /**
0411      * Emitted when the user changed the URL via the file dialog.
0412      * The parameter contains the contents of the lineedit.
0413      */
0414     void urlSelected(const QUrl &);
0415 
0416 protected:
0417     void changeEvent(QEvent *e) override;
0418     bool eventFilter(QObject *obj, QEvent *ev) override;
0419 
0420 private:
0421     class KUrlRequesterPrivate;
0422     std::unique_ptr<KUrlRequesterPrivate> const d;
0423 
0424     Q_DISABLE_COPY(KUrlRequester)
0425 };
0426 
0427 class KIOWIDGETS_EXPORT KUrlComboRequester : public KUrlRequester // krazy:exclude=dpointer (For use in Qt Designer)
0428 {
0429     Q_OBJECT
0430 public:
0431     /**
0432      * Constructs a KUrlRequester widget with a combobox.
0433      */
0434     explicit KUrlComboRequester(QWidget *parent = nullptr);
0435 
0436 private:
0437     class Private;
0438     Private *const d;
0439 };
0440 
0441 #endif // KURLREQUESTER_H