1 /*
2     This file is part of the KDE libraries
3     SPDX-FileCopyrightText: 2001-2004 Anders Lund <anders@alweb.dk>
4 
5     SPDX-License-Identifier: LGPL-2.0-only
6 */
7 
8 #ifndef KMIMETYPE_CHOOSER_H
9 #define KMIMETYPE_CHOOSER_H
10 
11 #include <QDialog>
12 #include <QWidget>
13 #include <kwidgetsaddons_export.h>
14 #include <memory>
15 
16 /**
17  * @class KMimeTypeChooser kmimetypechooser.h KMimeTypeChooser
18  *
19  * This widget provides a checkable list of all available MIME types, presented
20  * as a treeview, with the MIME type comment and glob patterns as individual columns.
21  * It allows users to edit a MIME type by launching a MIME type editor (if it's
22  * available on the system).
23  *
24  * When the user clicks the OK button, a list of the selected MIME type names
25  * and associated glob patterns can be retrieved respectively; those lists can
26  * be used to populate a text line edit, or set a configuration entry... etc.
27  *
28  * @author Anders Lund (anders at alweb dk), jan 23, 2002
29  */
30 class KWIDGETSADDONS_EXPORT KMimeTypeChooser : public QWidget
31 {
32     Q_OBJECT
33 
34 public:
35     /**
36      * Buttons and data for display.
37      */
38     enum Visuals {
39         Comments = 1, ///< Show the MIME type comment (e.g. "HTML Document") in a column
40         Patterns = 2, ///< Show the MIME types glob patterns (e.g. "*.html;*.htm") in a column
41         EditButton = 4 ///< Show the "Edit" button, allowing to edit the selected type
42     };
43     /**
44      * Create a new KMimeTypeChooser.
45      *
46      * @param text A plain text line to display above the list
47      * @param selectedMimeTypes A list of MIME type names, these will be initially selected
48      *        in the list (provided they exist)
49      * @param visuals OR'd KMimetypeChooser::Visuals enum values to to set whether to
50      *        show the MIME type comment and glob patterns columns and an Edit button,
51      *        respectively, or not
52      * @param defaultGroup The group (e.g. "text") to expand in the treeview when no groups
53      *        are selected. If not provided, no group is expanded by default.
54      *        If @p groupsToShow is provided and it doesn't include @p defaultGroup, this
55      *        parameter is ignored
56      * @param groupsToShow a list of MIME type groups to show. If empty, all groups are shown
57      * @param parent The parent widget to use
58      */
59     explicit KMimeTypeChooser(const QString &text = QString(),
60                               const QStringList &selectedMimeTypes = QStringList(),
61                               const QString &defaultGroup = QString(),
62                               const QStringList &groupsToShow = QStringList(),
63                               int visuals = Comments | Patterns | EditButton,
64                               QWidget *parent = nullptr);
65     ~KMimeTypeChooser() override;
66 
67     /**
68      * @return a list of all selected MIME type names
69      */
70     QStringList mimeTypes() const;
71     /**
72      * @return a list of the filename glob patterns associated with all selected MIME types
73      */
74     QStringList patterns() const;
75 
76 private:
77     std::unique_ptr<class KMimeTypeChooserPrivate> const d;
78 };
79 
80 /**
81  * @class KMimeTypeChooserDialog kmimetypechooser.h KMimeTypeChooserDialog
82  *
83  * @short A dialog to select MIME types from the list of available ones on the system
84  *
85  * This dialog embeds KMimeTypeChooser widget, presenting a checkable tree list of
86  * MIME types, each with its associated icon, and optionally associated glob patterns
87  * (displayed in a separate column); also an optional Edit button to launch a
88  * MIME type editor to edit the selected MIME type.
89  *
90  * Here is an example, using the dialog to set the text of two line edits with the
91  * list of MIME type names and glob patterns, respectively, of the MIME types that
92  * the user has selected:
93  *
94  * @code
95  *    QLineEdit *leMimetypes = new QLineEdit();
96  *    QLineEdit *leGlobPatterns = new QLineEdit();
97  *    [...]
98  *    QString textLine = i18n("Select MIME types");
99  *    QStringList mimeList = QStringList::split(QRegularExpression("\\s*;\\s*"), leMimetypes->text());
100  *    KMimeTypeChooserDialog dlg(i18n("Select MIME Types"), textLine, mimeList, "text", this);
101  *    if (dlg.exec() == QDialog::Accepted) {
102  *        leMimetypes->setText(dlg.chooser()->mimeTypes().join(";"));
103  *        leGlobPatterns->setText(dlg.chooser()->patterns().join(";"));
104  *    }
105  * @endcode
106  *
107  * \image html kmimetypechooserdialog.png "KMimeTypeChooserDialog in action"
108  *
109  * @author Anders Lund (anders at alweb dk) dec 19, 2001
110  */
111 class KWIDGETSADDONS_EXPORT KMimeTypeChooserDialog : public QDialog
112 {
113     Q_OBJECT
114 public:
115     /**
116      * Create a KMimeTypeChooser dialog.
117      *
118      * @param title The title of the dialog
119      * @param text A plain text line to display above the list
120      * @param selectedMimeTypes A list of MIME type names, these will be initially selected
121      *        in the list, provided they exist
122      * @param visuals OR'd KMimetypeChooser::Visuals enum values to to set whether to
123      *        show the MIME type comment and glob patterns columns and an Edit button,
124      *        respectively, or not
125      * @param defaultGroup The group (e.g. "text") to expand in the treeview when no
126      *        groups are selected. If not provided, no group is expanded by default
127      *        If @p groupsToShow is provided and it doesn't include @p defaultGroup,
128      *        this parameter is ignored
129      * @param groupsToShow A list of MIME type groups to show. If empty, all groups are shown
130      * @param parent The parent widget to use
131      */
132     explicit KMimeTypeChooserDialog(const QString &title = QString(),
133                                     const QString &text = QString(),
134                                     const QStringList &selectedMimeTypes = QStringList(),
135                                     const QString &defaultGroup = QString(),
136                                     const QStringList &groupsToShow = QStringList(),
137                                     int visuals = KMimeTypeChooser::Comments | KMimeTypeChooser::Patterns | KMimeTypeChooser::EditButton,
138                                     QWidget *parent = nullptr);
139 
140     /**
141      * @overload
142      */
143     KMimeTypeChooserDialog(const QString &title,
144                            const QString &text,
145                            const QStringList &selectedMimeTypes,
146                            const QString &defaultGroup,
147                            QWidget *parent = nullptr);
148 
149     ~KMimeTypeChooserDialog() override;
150 
151     /**
152      * @return a pointer to the KMimeTypeChooser widget
153      */
154     KMimeTypeChooser *chooser();
155 
156     QSize sizeHint() const override;
157 
158 private:
159     std::unique_ptr<class KMimeTypeChooserDialogPrivate> const d;
160 };
161 #endif // _KMIMETYPE_CHOOSER_H_
162