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
24 * \inmodule KIOFileWidgets
25 *
26 * \brief Provides a user (and developer) friendly way to select files with support for
27 * choosing encoding.
28 *
29 * This class comes with a private constructor, the only way to show a file dialog
30 * is through its static methods.
31 */
32class KEncodingFileDialog : public QDialog
33{
34 Q_OBJECT
35
36public:
37 class KIOFILEWIDGETS_EXPORT Result
38 {
39 public:
40 /*!
41 *
42 */
43 QStringList fileNames;
44
45 /*!
46 *
47 */
48 QList<QUrl> URLs;
49
50 /*!
51 *
52 */
53 QString encoding;
54 };
55
56 /*!
57 * Creates a modal file dialog and return the selected
58 * filename or an empty string if none was chosen additionally a chosen
59 * encoding value is returned.
60 *
61 * Note that with
62 * this method the user must select an existing filename.
63 *
64 * \a encoding The encoding shown in the encoding combo.
65 *
66 * \a startDir This can either be
67 * \list
68 * \li The URL of the directory to start in.
69 * \li QString() to start in the current working
70 * directory, or the last directory where a file has been
71 * selected.
72 * \li ':<keyword>' to start in the directory last used
73 * by a filedialog in the same application that specified
74 * the same keyword.
75 * \li '::<keyword>' to start in the directory last used
76 * by a filedialog in any application that specified the
77 * same keyword.
78 * \endlist
79 *
80 * \a filter A shell glob or a MIME type filter that specifies which files to display.
81 * see KFileFilter::KFileFilter(const QString &label, const QStringList &filePatterns, const QStringList &mimePatterns)
82 * for examples of patterns.
83 *
84 * \a parent The widget the dialog will be centered on initially.
85 *
86 * \a title The name of the dialog widget.
87 */
88 static KIOFILEWIDGETS_EXPORT Result getOpenFileNameAndEncoding(const QString &encoding = QString(),
89 const QUrl &startDir = QUrl(),
90 const QString &filter = QString(),
91 QWidget *parent = nullptr,
92 const QString &title = QString());
93
94 /*!
95 * Creates a modal file dialog and returns the selected encoding and the selected
96 * filenames or an empty list if none was chosen.
97 *
98 * Note that with
99 * this method the user must select an existing filename.
100 *
101 * \a encoding The encoding shown in the encoding combo.
102 *
103 * \a startDir This can either be
104 * \list
105 * \li The URL of the directory to start in.
106 * \li QString() to start in the current working
107 * directory, or the last directory where a file has been
108 * selected.
109 * \li ':<keyword>' to start in the directory last used
110 * by a filedialog in the same application that specified
111 * the same keyword.
112 * \li '::<keyword>' to start in the directory last used
113 * by a filedialog in any application that specified the
114 * same keyword.
115 * \endlist
116 *
117 * \a filter A shell glob or a MIME type filter that specifies which files to display.
118 * see KFileFilter::KFileFilter(const QString &label, const QStringList &filePatterns, const QStringList &mimePatterns)
119 * for examples of patterns.
120 *
121 * \a parent The widget the dialog will be centered on initially.
122 *
123 * \a title The name of the dialog widget.
124 */
125 static KIOFILEWIDGETS_EXPORT Result getOpenFileNamesAndEncoding(const QString &encoding = QString(),
126 const QUrl &startDir = QUrl(),
127 const QString &filter = QString(),
128 QWidget *parent = nullptr,
129 const QString &title = QString());
130
131 /*!
132 * Creates a modal file dialog and returns the selected encoding and
133 * URL or an empty string if none was chosen.
134 *
135 * Note that with
136 * this method the user must select an existing URL.
137 *
138 * \a encoding The encoding shown in the encoding combo.
139 *
140 * \a startDir This can either be
141 * \list
142 * \li The URL of the directory to start in.
143 * \li QString() to start in the current working
144 * directory, or the last directory where a file has been
145 * selected.
146 * \li ':<keyword>' to start in the directory last used
147 * by a filedialog in the same application that specified
148 * the same keyword.
149 * \li '::<keyword>' to start in the directory last used
150 * by a filedialog in any application that specified the
151 * same keyword.
152 * \endlist
153 *
154 * \a filter A shell glob or a MIME type filter that specifies which files to display.
155 * see KFileFilter::KFileFilter(const QString &label, const QStringList &filePatterns, const QStringList &mimePatterns)
156 * for examples of patterns.
157 *
158 * \a parent The widget the dialog will be centered on initially.
159 *
160 * \a title The name of the dialog widget.
161 */
162 static KIOFILEWIDGETS_EXPORT Result getOpenUrlAndEncoding(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
170 * URLs or an empty list if none was chosen.
171 *
172 * Note that with
173 * this method the user must select an existing filename.
174 *
175 * \a encoding The encoding shown in the encoding combo.
176 *
177 * \a startDir This can either be
178 * \list
179 * \li The URL of the directory to start in.
180 * \li QString() to start in the current working
181 * directory, or the last directory where a file has been
182 * selected.
183 * \li ':<keyword>' to start in the directory last used
184 * by a filedialog in the same application that specified
185 * the same keyword.
186 * \li '::<keyword>' to start in the directory last used
187 * by a filedialog in any application that specified the
188 * same keyword.
189 * \endlist
190 *
191 * \a filter A shell glob or a MIME type filter that specifies which files to display.
192 * see KFileFilter::KFileFilter(const QString &label, const QStringList &filePatterns, const QStringList &mimePatterns)
193 * for examples of patterns.
194 *
195 * \a parent The widget the dialog will be centered on initially.
196 *
197 * \a title The name of the dialog widget.
198 */
199 static KIOFILEWIDGETS_EXPORT Result getOpenUrlsAndEncoding(const QString &encoding = QString(),
200 const QUrl &startDir = QUrl(),
201 const QString &filter = QString(),
202 QWidget *parent = nullptr,
203 const QString &title = QString());
204
205 /*!
206 * Creates a modal file dialog and returns the selected encoding and
207 * filename or an empty string if none was chosen.
208 *
209 * Note that with this
210 * method the user need not select an existing filename.
211 *
212 * \a encoding The encoding shown in the encoding combo.
213 * \a startDir This can either be
214 * \list
215 * \li The URL of the directory to start in.
216 * \li a relative path or a filename determining the
217 * directory to start in and the file to be selected.
218 * \li QString() to start in the current working
219 * directory, or the last directory where a file has been
220 * selected.
221 * \li ':<keyword>' to start in the directory last used
222 * by a filedialog in the same application that specified
223 * the same keyword.
224 * \li '::<keyword>;' to start in the directory last used
225 * by a filedialog in any application that specified the
226 * same keyword.
227 * \endlist
228 *
229 * \a filter A shell glob or a MIME type filter that specifies which files to display.
230 * see KFileFilter::KFileFilter(const QString &label, const QStringList &filePatterns, const QStringList &mimePatterns)
231 * for examples of patterns.
232 *
233 * \a parent The widget the dialog will be centered on initially.
234 *
235 * \a title The name of the dialog widget.
236 */
237 static KIOFILEWIDGETS_EXPORT Result getSaveFileNameAndEncoding(const QString &encoding = QString(),
238 const QUrl &startDir = QUrl(),
239 const QString &filter = QString(),
240 QWidget *parent = nullptr,
241 const QString &title = QString());
242
243 /*!
244 * Creates a modal file dialog and returns the selected encoding and
245 * filename or an empty string if none was chosen.
246 *
247 * Note that with this
248 * method the user need not select an existing filename.
249 *
250 * \a encoding The encoding shown in the encoding combo.
251 *
252 * \a startDir This can either be
253 * \list
254 * \li The URL of the directory to start in.
255 * \li a relative path or a filename determining the
256 * directory to start in and the file to be selected.
257 * \li QString() to start in the current working
258 * directory, or the last directory where a file has been
259 * selected.
260 * \li ':<keyword>' to start in the directory last used
261 * by a filedialog in the same application that specified
262 * the same keyword.
263 * \li '::<keyword>' to start in the directory last used
264 * by a filedialog in any application that specified the
265 * same keyword.
266 * \endlist
267 *
268 * \a filter A shell glob or a MIME type filter that specifies which files to display.
269 * see KFileFilter::KFileFilter(const QString &label, const QStringList &filePatterns, const QStringList &mimePatterns)
270 * for examples of patterns.
271 *
272 * \a parent The widget the dialog will be centered on initially.
273 *
274 * \a title The name of the dialog widget.
275 */
276 static KIOFILEWIDGETS_EXPORT Result getSaveUrlAndEncoding(const QString &encoding = QString(),
277 const QUrl &startDir = QUrl(),
278 const QString &filter = QString(),
279 QWidget *parent = nullptr,
280 const QString &title = QString());
281
282 QSize sizeHint() const override;
283
284protected:
285 void hideEvent(QHideEvent *e) override;
286
287private Q_SLOTS:
288 void accept() override;
289
290 void slotOk();
291 void slotCancel();
292
293private:
294 /*!
295 * Constructs a file dialog for text files with encoding selection possibility.
296 *
297 * \a startDir This can either be
298 * \list
299 * \li The URL of the directory to start in.
300 * \li QString() to start in the current working
301 * directory, or the last directory where a file has been
302 * selected.
303 * \li ':<keyword>' to start in the directory last used
304 * by a filedialog in the same application that specified
305 * the same keyword.
306 * \li '::<keyword>' to start in the directory last used
307 * by a filedialog in any application that specified the
308 * same keyword.
309 * \endlist
310 *
311 * \a encoding The encoding shown in the encoding combo. If it's
312 * QString(), the global default encoding will be shown.
313 *
314 * \a filter A shell glob or a MIME type filter that specifies which files to display.
315 * The preferred option is to set a list of MIME type names, see setMimeFilter() for details.
316 * Otherwise you can set the text to be displayed for the each glob, and
317 * provide multiple globs, see setFilters() for details.
318 *
319 * \a title The title of the dialog
320 *
321 * \a type This can either be
322 * \list
323 * \li QFileDialog::AcceptOpen (open dialog, the default setting)
324 * \li QFileDialog::AcceptSave
325 * \endlist
326 * \a parent The parent widget of this dialog
327 */
328 KEncodingFileDialog(const QUrl &startDir = QUrl(),
329 const QString &encoding = QString(),
330 const QString &filter = QString(),
331 const QString &title = QString(),
332 QFileDialog::AcceptMode type = QFileDialog::AcceptOpen,
333 QWidget *parent = nullptr);
334 ~KEncodingFileDialog() override;
335
336 /*!
337 * Returns The selected encoding if the constructor with the encoding parameter was used, otherwise QString().
338 */
339 QString selectedEncoding() const;
340
341 std::unique_ptr<KEncodingFileDialogPrivate> const d;
342};
343
344#endif
345

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