1// -*- c++ -*-
2/*
3 This file is part of the KDE libraries
4 SPDX-FileCopyrightText: 2003 Joseph Wenninger <jowenn@kde.org>
5 SPDX-FileCopyrightText: 2003 Andras Mantia <amantia@freemail.hu>
6 SPDX-FileCopyrightText: 2013 Teo Mrnjavac <teo@kde.org>
7
8 SPDX-License-Identifier: LGPL-2.0-or-later
9*/
10
11#ifndef __KENCODINGFILEDIALOG_H__
12#define __KENCODINGFILEDIALOG_H__
13
14#include "kiofilewidgets_export.h"
15
16#include <QFileDialog>
17
18#include <memory>
19
20struct KEncodingFileDialogPrivate;
21
22/**
23 * @class KEncodingFileDialog kencodingfiledialog.h <KEncodingFileDialog>
24 *
25 * Provides a user (and developer) friendly way to select files with support for
26 * choosing encoding.
27 * This class comes with a private constructor, the only way to show a file dialog
28 * is through its static methods.
29 */
30class KEncodingFileDialog : public QDialog
31{
32 Q_OBJECT
33
34public:
35 class KIOFILEWIDGETS_EXPORT Result
36 {
37 public:
38 QStringList fileNames;
39 QList<QUrl> URLs;
40 QString encoding;
41 };
42
43 /**
44 * Creates a modal file dialog and return the selected
45 * filename or an empty string if none was chosen additionally a chosen
46 * encoding value is returned.
47 *
48 * Note that with
49 * this method the user must select an existing filename.
50 *
51 * @param encoding The encoding shown in the encoding combo.
52 * @param startDir This can either be
53 * @li The URL of the directory to start in.
54 * @li QString() to start in the current working
55 * directory, or the last directory where a file has been
56 * selected.
57 * @li ':&lt;keyword&gt;' to start in the directory last used
58 * by a filedialog in the same application that specified
59 * the same keyword.
60 * @li '::&lt;keyword&gt;' to start in the directory last used
61 * by a filedialog in any application that specified the
62 * same keyword.
63 * @param filter A shell glob or a MIME type filter that specifies which files to display.
64 * see KFileFilter::KFileFilter(const QString &label, const QStringList &filePatterns, const QStringList &mimePatterns)
65 * for examples of patterns.
66 * @param parent The widget the dialog will be centered on initially.
67 * @param title The name of the dialog widget.
68 */
69 static KIOFILEWIDGETS_EXPORT Result getOpenFileNameAndEncoding(const QString &encoding = QString(),
70 const QUrl &startDir = QUrl(),
71 const QString &filter = QString(),
72 QWidget *parent = nullptr,
73 const QString &title = QString());
74
75 /**
76 * Creates a modal file dialog and returns the selected encoding and the selected
77 * filenames or an empty list if none was chosen.
78 *
79 * Note that with
80 * this method the user must select an existing filename.
81 *
82 * @param encoding The encoding shown in the encoding combo.
83 * @param startDir This can either be
84 * @li The URL of the directory to start in.
85 * @li QString() to start in the current working
86 * directory, or the last directory where a file has been
87 * selected.
88 * @li ':&lt;keyword&gt;' to start in the directory last used
89 * by a filedialog in the same application that specified
90 * the same keyword.
91 * @li '::&lt;keyword&gt;' to start in the directory last used
92 * by a filedialog in any application that specified the
93 * same keyword.
94 * @param filter A shell glob or a MIME type filter that specifies which files to display.
95 * see KFileFilter::KFileFilter(const QString &label, const QStringList &filePatterns, const QStringList &mimePatterns)
96 * for examples of patterns.
97 * @param parent The widget the dialog will be centered on initially.
98 * @param title The name of the dialog widget.
99 */
100 static KIOFILEWIDGETS_EXPORT Result getOpenFileNamesAndEncoding(const QString &encoding = QString(),
101 const QUrl &startDir = QUrl(),
102 const QString &filter = QString(),
103 QWidget *parent = nullptr,
104 const QString &title = QString());
105
106 /**
107 * Creates a modal file dialog and returns the selected encoding and
108 * URL or an empty string if none was chosen.
109 *
110 * Note that with
111 * this method the user must select an existing URL.
112 *
113 * @param encoding The encoding shown in the encoding combo.
114 * @param startDir This can either be
115 * @li The URL of the directory to start in.
116 * @li QString() to start in the current working
117 * directory, or the last directory where a file has been
118 * selected.
119 * @li ':&lt;keyword&gt;' to start in the directory last used
120 * by a filedialog in the same application that specified
121 * the same keyword.
122 * @li '::&lt;keyword&gt;' to start in the directory last used
123 * by a filedialog in any application that specified the
124 * same keyword.
125 * @param filter A shell glob or a MIME type filter that specifies which files to display.
126 * see KFileFilter::KFileFilter(const QString &label, const QStringList &filePatterns, const QStringList &mimePatterns)
127 * for examples of patterns.
128 * @param parent The widget the dialog will be centered on initially.
129 * @param title The name of the dialog widget.
130 */
131 static KIOFILEWIDGETS_EXPORT Result getOpenUrlAndEncoding(const QString &encoding = QString(),
132 const QUrl &startDir = QUrl(),
133 const QString &filter = QString(),
134 QWidget *parent = nullptr,
135 const QString &title = QString());
136
137 /**
138 * Creates a modal file dialog and returns the selected encoding
139 * URLs or an empty list if none was chosen.
140 *
141 * Note that with
142 * this method the user must select an existing filename.
143 *
144 * @param encoding The encoding shown in the encoding combo.
145 * @param startDir This can either be
146 * @li The URL of the directory to start in.
147 * @li QString() to start in the current working
148 * directory, or the last directory where a file has been
149 * selected.
150 * @li ':&lt;keyword&gt;' to start in the directory last used
151 * by a filedialog in the same application that specified
152 * the same keyword.
153 * @li '::&lt;keyword&gt;' to start in the directory last used
154 * by a filedialog in any application that specified the
155 * same keyword.
156 * @param filter A shell glob or a MIME type filter that specifies which files to display.
157 * see KFileFilter::KFileFilter(const QString &label, const QStringList &filePatterns, const QStringList &mimePatterns)
158 * for examples of patterns.
159 * @param parent The widget the dialog will be centered on initially.
160 * @param title The name of the dialog widget.
161 */
162 static KIOFILEWIDGETS_EXPORT Result getOpenUrlsAndEncoding(const QString &encoding = QString(),
163 const QUrl &startDir = QUrl(),
164 const QString &filter = QString(),
165 QWidget *parent = nullptr,
166 const QString &title = QString());
167
168 /**
169 * Creates a modal file dialog and returns the selected encoding and
170 * filename or an empty string if none was chosen.
171 *
172 * Note that with this
173 * method the user need not select an existing filename.
174 *
175 * @param encoding The encoding shown in the encoding combo.
176 * @param startDir This can either be
177 * @li The URL of the directory to start in.
178 * @li a relative path or a filename determining the
179 * directory to start in and the file to be selected.
180 * @li QString() to start in the current working
181 * directory, or the last directory where a file has been
182 * selected.
183 * @li ':&lt;keyword&gt;' to start in the directory last used
184 * by a filedialog in the same application that specified
185 * the same keyword.
186 * @li '::&lt;keyword&gt;' to start in the directory last used
187 * by a filedialog in any application that specified the
188 * same keyword.
189 * @param filter A shell glob or a MIME type filter that specifies which files to display.
190 * see KFileFilter::KFileFilter(const QString &label, const QStringList &filePatterns, const QStringList &mimePatterns)
191 * for examples of patterns.
192 * @param parent The widget the dialog will be centered on initially.
193 * @param title The name of the dialog widget.
194 */
195 static KIOFILEWIDGETS_EXPORT Result getSaveFileNameAndEncoding(const QString &encoding = QString(),
196 const QUrl &startDir = QUrl(),
197 const QString &filter = QString(),
198 QWidget *parent = nullptr,
199 const QString &title = QString());
200
201 /**
202 * Creates a modal file dialog and returns the selected encoding and
203 * filename or an empty string if none was chosen.
204 *
205 * Note that with this
206 * method the user need not select an existing filename.
207 *
208 * @param encoding The encoding shown in the encoding combo.
209 * @param startDir This can either be
210 * @li The URL of the directory to start in.
211 * @li a relative path or a filename determining the
212 * directory to start in and the file to be selected.
213 * @li QString() to start in the current working
214 * directory, or the last directory where a file has been
215 * selected.
216 * @li ':&lt;keyword&gt;' to start in the directory last used
217 * by a filedialog in the same application that specified
218 * the same keyword.
219 * @li '::&lt;keyword&gt;' to start in the directory last used
220 * by a filedialog in any application that specified the
221 * same keyword.
222 * @param filter A shell glob or a MIME type filter that specifies which files to display.
223 * see KFileFilter::KFileFilter(const QString &label, const QStringList &filePatterns, const QStringList &mimePatterns)
224 * for examples of patterns.
225 * @param parent The widget the dialog will be centered on initially.
226 * @param title The name of the dialog widget.
227 */
228 static KIOFILEWIDGETS_EXPORT Result getSaveUrlAndEncoding(const QString &encoding = QString(),
229 const QUrl &startDir = QUrl(),
230 const QString &filter = QString(),
231 QWidget *parent = nullptr,
232 const QString &title = QString());
233
234 QSize sizeHint() const override;
235
236protected:
237 void hideEvent(QHideEvent *e) override;
238
239private Q_SLOTS:
240 void accept() override;
241
242 void slotOk();
243 void slotCancel();
244
245private:
246 /**
247 * Constructs a file dialog for text files with encoding selection possibility.
248 *
249 * @param startDir This can either be
250 * @li The URL of the directory to start in.
251 * @li QString() to start in the current working
252 * directory, or the last directory where a file has been
253 * selected.
254 * @li ':&lt;keyword&gt;' to start in the directory last used
255 * by a filedialog in the same application that specified
256 * the same keyword.
257 * @li '::&lt;keyword&gt;' to start in the directory last used
258 * by a filedialog in any application that specified the
259 * same keyword.
260 *
261 * @param encoding The encoding shown in the encoding combo. If it's
262 * QString(), the global default encoding will be shown.
263 *
264 * @param filter A shell glob or a MIME type filter that specifies which files to display.
265 * The preferred option is to set a list of MIME type names, see setMimeFilter() for details.
266 * Otherwise you can set the text to be displayed for the each glob, and
267 * provide multiple globs, see setFilters() for details.
268 *
269 * @param title The title of the dialog
270 *
271 * @param type This can either be
272 * @li QFileDialog::AcceptOpen (open dialog, the default setting)
273 * @li QFileDialog::AcceptSave
274 * @param parent The parent widget of this dialog
275 */
276 KEncodingFileDialog(const QUrl &startDir = QUrl(),
277 const QString &encoding = QString(),
278 const QString &filter = QString(),
279 const QString &title = QString(),
280 QFileDialog::AcceptMode type = QFileDialog::AcceptOpen,
281 QWidget *parent = nullptr);
282 /**
283 * Destructs the file dialog.
284 */
285 ~KEncodingFileDialog() override;
286
287 /**
288 * @returns The selected encoding if the constructor with the encoding parameter was used, otherwise QString().
289 */
290 QString selectedEncoding() const;
291
292 std::unique_ptr<KEncodingFileDialogPrivate> const d;
293};
294
295#endif
296

source code of kio/src/filewidgets/kencodingfiledialog.h