File indexing completed on 2024-02-25 04:00:31

0001 // -*- c++ -*-
0002 /*
0003     This file is part of the KDE libraries
0004     SPDX-FileCopyrightText: 2003 Joseph Wenninger <jowenn@kde.org>
0005     SPDX-FileCopyrightText: 2003 Andras Mantia <amantia@freemail.hu>
0006     SPDX-FileCopyrightText: 2013 Teo Mrnjavac <teo@kde.org>
0007 
0008     SPDX-License-Identifier: LGPL-2.0-or-later
0009 */
0010 
0011 #ifndef __KENCODINGFILEDIALOG_H__
0012 #define __KENCODINGFILEDIALOG_H__
0013 
0014 #include "kiofilewidgets_export.h"
0015 
0016 #include <QFileDialog>
0017 
0018 #include <memory>
0019 
0020 struct KEncodingFileDialogPrivate;
0021 
0022 /**
0023  * @class KEncodingFileDialog kencodingfiledialog.h <KEncodingFileDialog>
0024  *
0025  * Provides a user (and developer) friendly way to select files with support for
0026  * choosing encoding.
0027  * This class comes with a private constructor, the only way to show a file dialog
0028  * is through its static methods.
0029  */
0030 class KEncodingFileDialog : public QDialog
0031 {
0032     Q_OBJECT
0033 
0034 public:
0035     class KIOFILEWIDGETS_EXPORT Result
0036     {
0037     public:
0038         QStringList fileNames;
0039         QList<QUrl> URLs;
0040         QString encoding;
0041     };
0042 
0043     /**
0044      * Creates a modal file dialog and return the selected
0045      * filename or an empty string if none was chosen additionally a chosen
0046      * encoding value is returned.
0047      *
0048      * Note that with
0049      * this method the user must select an existing filename.
0050      *
0051      * @param encoding The encoding shown in the encoding combo.
0052      * @param startDir This can either be
0053      *         @li The URL of the directory to start in.
0054      *         @li QString() to start in the current working
0055      *          directory, or the last directory where a file has been
0056      *          selected.
0057      *         @li ':&lt;keyword&gt;' to start in the directory last used
0058      *             by a filedialog in the same application that specified
0059      *             the same keyword.
0060      *         @li '::&lt;keyword&gt;' to start in the directory last used
0061      *             by a filedialog in any application that specified the
0062      *             same keyword.
0063      * @param filter A shell glob or a MIME type filter that specifies which files to display.
0064      *    The preferred option is to set a list of MIME type names, see setMimeFilter() for details.
0065      *    Otherwise you can set the text to be displayed for the each glob, and
0066      *    provide multiple globs, see setFilter() for details.
0067      * @param parent The widget the dialog will be centered on initially.
0068      * @param title The name of the dialog widget.
0069      */
0070     static KIOFILEWIDGETS_EXPORT Result getOpenFileNameAndEncoding(const QString &encoding = QString(),
0071                                                                    const QUrl &startDir = QUrl(),
0072                                                                    const QString &filter = QString(),
0073                                                                    QWidget *parent = nullptr,
0074                                                                    const QString &title = QString());
0075 
0076     /**
0077      * Creates a modal file dialog and returns the selected encoding and the selected
0078      * filenames or an empty list if none was chosen.
0079      *
0080      * Note that with
0081      * this method the user must select an existing filename.
0082      *
0083      * @param encoding The encoding shown in the encoding combo.
0084      * @param startDir This can either be
0085      *         @li The URL of the directory to start in.
0086      *         @li QString() to start in the current working
0087      *          directory, or the last directory where a file has been
0088      *          selected.
0089      *         @li ':&lt;keyword&gt;' to start in the directory last used
0090      *             by a filedialog in the same application that specified
0091      *             the same keyword.
0092      *         @li '::&lt;keyword&gt;' to start in the directory last used
0093      *             by a filedialog in any application that specified the
0094      *             same keyword.
0095      * @param filter A shell glob or a MIME type filter that specifies which files to display.
0096      *    The preferred option is to set a list of MIME type names, see setMimeFilter() for details.
0097      *    Otherwise you can set the text to be displayed for the each glob, and
0098      *    provide multiple globs, see setFilter() for details.
0099      * @param parent The widget the dialog will be centered on initially.
0100      * @param title The name of the dialog widget.
0101      */
0102     static KIOFILEWIDGETS_EXPORT Result getOpenFileNamesAndEncoding(const QString &encoding = QString(),
0103                                                                     const QUrl &startDir = QUrl(),
0104                                                                     const QString &filter = QString(),
0105                                                                     QWidget *parent = nullptr,
0106                                                                     const QString &title = QString());
0107 
0108     /**
0109      * Creates a modal file dialog and returns the selected encoding and
0110      * URL or an empty string if none was chosen.
0111      *
0112      * Note that with
0113      * this method the user must select an existing URL.
0114      *
0115      * @param encoding The encoding shown in the encoding combo.
0116      * @param startDir This can either be
0117      *         @li The URL of the directory to start in.
0118      *         @li QString() to start in the current working
0119      *          directory, or the last directory where a file has been
0120      *          selected.
0121      *         @li ':&lt;keyword&gt;' to start in the directory last used
0122      *             by a filedialog in the same application that specified
0123      *             the same keyword.
0124      *         @li '::&lt;keyword&gt;' to start in the directory last used
0125      *             by a filedialog in any application that specified the
0126      *             same keyword.
0127      * @param filter A shell glob or a MIME type filter that specifies which files to display.
0128      *    The preferred option is to set a list of MIME type names, see setMimeFilter() for details.
0129      *    Otherwise you can set the text to be displayed for the each glob, and
0130      *    provide multiple globs, see setFilter() for details.
0131      * @param parent The widget the dialog will be centered on initially.
0132      * @param title The name of the dialog widget.
0133      */
0134     static KIOFILEWIDGETS_EXPORT Result getOpenUrlAndEncoding(const QString &encoding = QString(),
0135                                                               const QUrl &startDir = QUrl(),
0136                                                               const QString &filter = QString(),
0137                                                               QWidget *parent = nullptr,
0138                                                               const QString &title = QString());
0139 
0140     /**
0141      * Creates a modal file dialog and returns the selected encoding
0142      * URLs or an empty list if none was chosen.
0143      *
0144      * Note that with
0145      * this method the user must select an existing filename.
0146      *
0147      * @param encoding The encoding shown in the encoding combo.
0148      * @param startDir This can either be
0149      *         @li The URL of the directory to start in.
0150      *         @li QString() to start in the current working
0151      *          directory, or the last directory where a file has been
0152      *          selected.
0153      *         @li ':&lt;keyword&gt;' to start in the directory last used
0154      *             by a filedialog in the same application that specified
0155      *             the same keyword.
0156      *         @li '::&lt;keyword&gt;' to start in the directory last used
0157      *             by a filedialog in any application that specified the
0158      *             same keyword.
0159      * @param filter A shell glob or a MIME type filter that specifies which files to display.
0160      *    The preferred option is to set a list of MIME type names, see setMimeFilter() for details.
0161      *    Otherwise you can set the text to be displayed for the each glob, and
0162      *    provide multiple globs, see setFilter() for details.
0163      * @param parent The widget the dialog will be centered on initially.
0164      * @param title The name of the dialog widget.
0165      */
0166     static KIOFILEWIDGETS_EXPORT Result getOpenUrlsAndEncoding(const QString &encoding = QString(),
0167                                                                const QUrl &startDir = QUrl(),
0168                                                                const QString &filter = QString(),
0169                                                                QWidget *parent = nullptr,
0170                                                                const QString &title = QString());
0171 
0172     /**
0173      * Creates a modal file dialog and returns the selected encoding and
0174      * filename or an empty string if none was chosen.
0175      *
0176      * Note that with this
0177      * method the user need not select an existing filename.
0178      *
0179      * @param encoding The encoding shown in the encoding combo.
0180      * @param startDir This can either be
0181      *         @li The URL of the directory to start in.
0182      *         @li a relative path or a filename determining the
0183      *             directory to start in and the file to be selected.
0184      *         @li QString() to start in the current working
0185      *          directory, or the last directory where a file has been
0186      *          selected.
0187      *         @li ':&lt;keyword&gt;' to start in the directory last used
0188      *             by a filedialog in the same application that specified
0189      *             the same keyword.
0190      *         @li '::&lt;keyword&gt;' to start in the directory last used
0191      *             by a filedialog in any application that specified the
0192      *             same keyword.
0193      * @param filter A shell glob or a MIME type filter that specifies which files to display.
0194      *    The preferred option is to set a list of MIME type names, see setMimeFilter() for details.
0195      *    Otherwise you can set the text to be displayed for the each glob, and
0196      *    provide multiple globs, see setFilter() for details.
0197      * @param parent The widget the dialog will be centered on initially.
0198      * @param title The name of the dialog widget.
0199      */
0200     static KIOFILEWIDGETS_EXPORT Result getSaveFileNameAndEncoding(const QString &encoding = QString(),
0201                                                                    const QUrl &startDir = QUrl(),
0202                                                                    const QString &filter = QString(),
0203                                                                    QWidget *parent = nullptr,
0204                                                                    const QString &title = QString());
0205 
0206     /**
0207      * Creates a modal file dialog and returns the selected encoding and
0208      * filename or an empty string if none was chosen.
0209      *
0210      * Note that with this
0211      * method the user need not select an existing filename.
0212      *
0213      * @param encoding The encoding shown in the encoding combo.
0214      * @param startDir This can either be
0215      *         @li The URL of the directory to start in.
0216      *         @li a relative path or a filename determining the
0217      *             directory to start in and the file to be selected.
0218      *         @li QString() to start in the current working
0219      *          directory, or the last directory where a file has been
0220      *          selected.
0221      *         @li ':&lt;keyword&gt;' to start in the directory last used
0222      *             by a filedialog in the same application that specified
0223      *             the same keyword.
0224      *         @li '::&lt;keyword&gt;' to start in the directory last used
0225      *             by a filedialog in any application that specified the
0226      *             same keyword.
0227      * @param filter A shell glob or a MIME type filter that specifies which files to display.
0228      *    The preferred option is to set a list of MIME type names, see setMimeFilter() for details.
0229      *    Otherwise you can set the text to be displayed for the each glob, and
0230      *    provide multiple globs, see setFilter() for details.
0231      * @param parent The widget the dialog will be centered on initially.
0232      * @param title The name of the dialog widget.
0233      */
0234     static KIOFILEWIDGETS_EXPORT Result getSaveUrlAndEncoding(const QString &encoding = QString(),
0235                                                               const QUrl &startDir = QUrl(),
0236                                                               const QString &filter = QString(),
0237                                                               QWidget *parent = nullptr,
0238                                                               const QString &title = QString());
0239 
0240     QSize sizeHint() const override;
0241 
0242 protected:
0243     void hideEvent(QHideEvent *e) override;
0244 
0245 private Q_SLOTS:
0246     void accept() override;
0247 
0248     void slotOk();
0249     void slotCancel();
0250 
0251 private:
0252     /**
0253      * Constructs a file dialog for text files with encoding selection possibility.
0254      *
0255      * @param startDir This can either be
0256      *         @li The URL of the directory to start in.
0257      *         @li QString() to start in the current working
0258      *          directory, or the last directory where a file has been
0259      *          selected.
0260      *         @li ':&lt;keyword&gt;' to start in the directory last used
0261      *             by a filedialog in the same application that specified
0262      *             the same keyword.
0263      *         @li '::&lt;keyword&gt;' to start in the directory last used
0264      *             by a filedialog in any application that specified the
0265      *             same keyword.
0266      *
0267      * @param encoding The encoding shown in the encoding combo. If it's
0268      *          QString(), the global default encoding will be shown.
0269      *
0270      * @param filter A shell glob or a MIME type filter that specifies which files to display.
0271      *    The preferred option is to set a list of MIME type names, see setMimeFilter() for details.
0272      *    Otherwise you can set the text to be displayed for the each glob, and
0273      *    provide multiple globs, see setFilter() for details.
0274      *
0275      * @param title The title of the dialog
0276      *
0277      * @param type This can either be
0278      *      @li QFileDialog::AcceptOpen (open dialog, the default setting)
0279      *      @li QFileDialog::AcceptSave
0280      * @param parent The parent widget of this dialog
0281      */
0282     KEncodingFileDialog(const QUrl &startDir = QUrl(),
0283                         const QString &encoding = QString(),
0284                         const QString &filter = QString(),
0285                         const QString &title = QString(),
0286                         QFileDialog::AcceptMode type = QFileDialog::AcceptOpen,
0287                         QWidget *parent = nullptr);
0288     /**
0289      * Destructs the file dialog.
0290      */
0291     ~KEncodingFileDialog() override;
0292 
0293     /**
0294      * @returns The selected encoding if the constructor with the encoding parameter was used, otherwise QString().
0295      */
0296     QString selectedEncoding() const;
0297 
0298     std::unique_ptr<KEncodingFileDialogPrivate> const d;
0299 };
0300 
0301 #endif