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

source code of kwidgetsaddons/src/kmimetypechooser.h