File indexing completed on 2024-05-19 07:45:01

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     /// @since 5.108
0059     Q_PROPERTY(QStringList nameFilters READ nameFilters WRITE setNameFilters)
0060     Q_PROPERTY(KFile::Modes mode READ mode WRITE setMode)
0061     Q_PROPERTY(QFileDialog::AcceptMode acceptMode READ acceptMode WRITE setAcceptMode)
0062     Q_PROPERTY(QString placeholderText READ placeholderText WRITE setPlaceholderText)
0063     Q_PROPERTY(QString text READ text WRITE setText NOTIFY textChanged)
0064     Q_PROPERTY(Qt::WindowModality fileDialogModality READ fileDialogModality WRITE setFileDialogModality)
0065 
0066 public:
0067     /**
0068      * Constructs a KUrlRequester widget.
0069      */
0070     explicit KUrlRequester(QWidget *parent = nullptr);
0071 
0072     /**
0073      * Constructs a KUrlRequester widget with the initial URL @p url.
0074      */
0075     explicit KUrlRequester(const QUrl &url, QWidget *parent = nullptr);
0076 
0077     /**
0078      * Special constructor, which creates a KUrlRequester widget with a custom
0079      * edit-widget. The edit-widget can be either a KComboBox or a KLineEdit
0080      * (or inherited thereof). Note: for geometry management reasons, the
0081      * edit-widget is reparented to have the KUrlRequester as parent.
0082      */
0083     KUrlRequester(QWidget *editWidget, QWidget *parent);
0084     /**
0085      * Destructs the KUrlRequester.
0086      */
0087     ~KUrlRequester() override;
0088 
0089     /**
0090      * @returns the current url in the lineedit. May be malformed, if the user
0091      * entered something weird. For local files, ~user or environment variables
0092      * are substituted, relative paths will be resolved against startDir()
0093      */
0094     QUrl url() const;
0095 
0096     /**
0097      * @returns the current start dir
0098      */
0099     QUrl startDir() const;
0100 
0101     /**
0102      * @returns the current text in the lineedit or combobox.
0103      * This does not do the URL expansion that url() does, it's only provided
0104      * for cases where KUrlRequester is used to enter URL-or-something-else,
0105      * like KOpenWithDialog where you can type a full command with arguments.
0106      *
0107      */
0108     QString text() const;
0109 
0110     /**
0111      * Sets the mode of the file dialog.
0112      *
0113      * The default mode of the file dialog is 'KFile::File | KFile::ExistingOnly | KFile::LocalOnly',
0114      * which you can change using this method.
0115      *
0116      * @note You can only select one file from the file dialog invoked
0117      * by KUrlRequester, hence setting KFile::Files doesn't make
0118      * much sense here.
0119      *
0120      * @param mode an OR'ed combination of KFile::Modes flags
0121      *
0122      * @see QFileDialog::setFileMode()
0123      */
0124     void setMode(KFile::Modes mode);
0125 
0126     /**
0127      * Returns the current mode
0128      * @see QFileDialog::fileMode()
0129      */
0130     KFile::Modes mode() const;
0131 
0132     /**
0133      * Sets the open / save mode of the file dialog.
0134      *
0135      * The default is QFileDialog::AcceptOpen.
0136      *
0137      * @see QFileDialog::setAcceptMode()
0138      * @since 5.33
0139      */
0140     void setAcceptMode(QFileDialog::AcceptMode m);
0141 
0142     /**
0143      * Returns the current open / save mode
0144      * @see QFileDialog::acceptMode()
0145      * @since 5.33
0146      */
0147     QFileDialog::AcceptMode acceptMode() const;
0148 
0149     /**
0150      * Sets the filters for the file dialog.
0151      * @see QFileDialog::setNameFilters()
0152      * @since 5.108
0153      */
0154     void setNameFilters(const QStringList &filters);
0155 
0156     /**
0157      * Sets the filters for the file dialog.
0158      * @see QFileDialog::setNameFilter()
0159      * @since 5.108
0160      */
0161     void setNameFilter(const QString &filter);
0162 
0163     /**
0164      * Returns the filters for the file dialog.
0165      * @see QFileDialog::nameFilters()
0166      * @since 5.108
0167      */
0168     QStringList nameFilters() const;
0169 
0170     /**
0171      * Sets the MIME type filters for the file dialog.
0172      * @see QFileDialog::setMimeTypeFilters()
0173      * @since 5.31
0174      */
0175     void setMimeTypeFilters(const QStringList &mimeTypes);
0176     /**
0177      * Returns the MIME type filters for the file dialog.
0178      * @see QFileDialog::mimeTypeFilters()
0179      * @since 5.31
0180      */
0181     QStringList mimeTypeFilters() const;
0182 
0183     /**
0184      * @returns a pointer to the filedialog.
0185      * You can use this to customize the dialog, e.g. to call setLocationLabel
0186      * or other things which are not accessible in the KUrlRequester API.
0187      *
0188      * Never returns 0. This method creates the file dialog on demand.
0189      *
0190      * @deprecated since 5.0. The dialog will be created anyway when the user
0191      * requests it, and will behave according to the properties of KUrlRequester.
0192      */
0193     KIOWIDGETS_DEPRECATED_VERSION(5, 0, "See API docs")
0194     virtual QFileDialog *fileDialog() const;
0195 
0196     /**
0197      * @returns a pointer to the lineedit, either the default one, or the
0198      * special one, if you used the special constructor.
0199      *
0200      * It is provided so that you can e.g. set an own completion object
0201      * (e.g. KShellCompletion) into it.
0202      */
0203     KLineEdit *lineEdit() const;
0204 
0205     /**
0206      * @returns a pointer to the combobox, in case you have set one using the
0207      * special constructor. Returns 0L otherwise.
0208      */
0209     KComboBox *comboBox() const;
0210 
0211     /**
0212      * @returns a pointer to the pushbutton. It is provided so that you can
0213      * specify an own pixmap or a text, if you really need to.
0214      */
0215     QPushButton *button() const;
0216 
0217     /**
0218      * @returns the KUrlCompletion object used in the lineedit/combobox.
0219      */
0220     KUrlCompletion *completionObject() const;
0221 
0222     /**
0223      * @returns an object, suitable for use with KEditListWidget. It allows you
0224      * to put this KUrlRequester into a KEditListWidget.
0225      * Basically, do it like this:
0226      * \code
0227      * KUrlRequester *req = new KUrlRequester( someWidget );
0228      * [...]
0229      * KEditListWidget *editListWidget = new KEditListWidget( req->customEditor(), someWidget );
0230      * \endcode
0231      */
0232     const KEditListWidget::CustomEditor &customEditor();
0233 
0234     /**
0235      * @return the message set with setPlaceholderText
0236      * @since 5.0
0237      */
0238     QString placeholderText() const;
0239 
0240     /**
0241      * This makes the KUrlRequester line edit display a grayed-out hinting text as long as
0242      * the user didn't enter any text. It is often used as indication about
0243      * the purpose of the line edit.
0244      * @since 5.0
0245      */
0246     void setPlaceholderText(const QString &msg);
0247 
0248     /**
0249      * @returns the window modality of the file dialog set with setFileDialogModality
0250      */
0251     Qt::WindowModality fileDialogModality() const;
0252 
0253     /**
0254      * Set the window modality for the file dialog to @p modality
0255      * Directory selection dialogs are always modal
0256      *
0257      * The default is Qt::ApplicationModal.
0258      *
0259      */
0260     void setFileDialogModality(Qt::WindowModality modality);
0261 
0262 public Q_SLOTS:
0263     /**
0264      * Sets the url in the lineedit to @p url.
0265      */
0266     void setUrl(const QUrl &url);
0267 
0268     /**
0269      * Sets the start dir @p startDir.
0270      * The start dir is only used when the URL isn't set.
0271      */
0272     void setStartDir(const QUrl &startDir);
0273 
0274     /**
0275      * Sets the current text in the lineedit or combobox.
0276      * This is used for cases where KUrlRequester is used to
0277      * enter URL-or-something-else, like KOpenWithDialog where you
0278      * can type a full command with arguments.
0279      *
0280      * @see text
0281      */
0282     void setText(const QString &text);
0283 
0284     /**
0285      * Clears the lineedit/combobox.
0286      */
0287     void clear();
0288 
0289 Q_SIGNALS:
0290     // forwards from LineEdit
0291     /**
0292      * Emitted when the text in the lineedit changes.
0293      * The parameter contains the contents of the lineedit.
0294      */
0295     void textChanged(const QString &);
0296 
0297     /**
0298      * Emitted when the text in the lineedit was modified by the user.
0299      * Unlike textChanged(), this signal is not emitted when the text is changed programmatically, for example, by calling setText().
0300      * @since 5.21
0301      */
0302     void textEdited(const QString &);
0303 
0304     /**
0305      * Emitted when return or enter was pressed in the lineedit.
0306      * The parameter contains the contents of the lineedit.
0307      */
0308     void returnPressed(const QString &text);
0309 
0310     /**
0311      * Emitted before the filedialog is going to open. Connect
0312      * to this signal to "configure" the filedialog, e.g. set the
0313      * filefilter, the mode, a preview-widget, etc. It's usually
0314      * not necessary to set a URL for the filedialog, as it will
0315      * get set properly from the editfield contents.
0316      *
0317      * If you use multiple KUrlRequesters, you can connect all of them
0318      * to the same slot and use the given KUrlRequester pointer to know
0319      * which one is going to open.
0320      */
0321     void openFileDialog(KUrlRequester *);
0322 
0323     /**
0324      * Emitted when the user changed the URL via the file dialog.
0325      * The parameter contains the contents of the lineedit.
0326      */
0327     void urlSelected(const QUrl &);
0328 
0329 protected:
0330     void changeEvent(QEvent *e) override;
0331     bool eventFilter(QObject *obj, QEvent *ev) override;
0332 
0333 private:
0334     class KUrlRequesterPrivate;
0335     std::unique_ptr<KUrlRequesterPrivate> const d;
0336 
0337     Q_DISABLE_COPY(KUrlRequester)
0338 };
0339 
0340 class KIOWIDGETS_EXPORT KUrlComboRequester : public KUrlRequester // krazy:exclude=dpointer (For use in Qt Designer)
0341 {
0342     Q_OBJECT
0343 public:
0344     /**
0345      * Constructs a KUrlRequester widget with a combobox.
0346      */
0347     explicit KUrlComboRequester(QWidget *parent = nullptr);
0348 
0349 private:
0350     class Private;
0351     Private *const d;
0352 };
0353 
0354 #endif // KURLREQUESTER_H