1// -*- c++ -*-
2/* This file is part of the KDE libraries
3 Copyright (C) 2003 Joseph Wenninger <jowenn@kde.org>
4 2003 Andras Mantia <amantia@freemail.hu>
5
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Library General Public
8 License as published by the Free Software Foundation; either
9 version 2 of the License, or (at your option) any later version.
10
11 This library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Library General Public License for more details.
15
16 You should have received a copy of the GNU Library General Public License
17 along with this library; see the file COPYING.LIB. If not, write to
18 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 Boston, MA 02110-1301, USA.
20*/
21
22#ifndef __KENCODINGFILEDIALOG_H__
23#define __KENCODINGFILEDIALOG_H__
24
25#include <kfiledialog.h>
26
27struct KEncodingFileDialogPrivate;
28
29/**
30 * Provides a user (and developer) friendly way to
31 * select files with support for choosing encoding
32 *
33 *
34 * The dialog has been designed to allow applications to customize it
35 * by subclassing. It uses geometry management to ensure that subclasses
36 * can easily add children that will be incorporated into the layout.
37 */
38
39class KIO_EXPORT KEncodingFileDialog : public KFileDialog
40{
41 Q_OBJECT
42
43public:
44 class Result {
45 public:
46 QStringList fileNames;
47 KUrl::List URLs;
48 QString encoding;
49 };
50
51 /**
52 * Constructs a file dialog for text files with encoding selection possibility.
53 *
54 * @param startDir This can either be
55 * @li The URL of the directory to start in.
56 * @li QString() to start in the current working
57 * directory, or the last directory where a file has been
58 * selected.
59 * @li ':&lt;keyword&gt;' to start in the directory last used
60 * by a filedialog in the same application that specified
61 * the same keyword.
62 * @li '::&lt;keyword&gt;' to start in the directory last used
63 * by a filedialog in any application that specified the
64 * same keyword.
65 *
66 * @param encoding The encoding shown in the encoding combo. If it's
67 * QString(), the global default encoding will be shown.
68 *
69 * @param filter A shell glob or a mime-type-filter that specifies which files to display.
70 * The preferred option is to set a list of mimetype names, see setMimeFilter() for details.
71 * Otherwise you can set the text to be displayed for the each glob, and
72 * provide multiple globs, see setFilter() for details.
73 *
74 * @param caption The caption of the dialog
75 *
76 * @param type This can either be
77 * @li Opening (open dialog, the default setting)
78 * @li Saving
79 * @param parent The parent widget of this dialog
80 */
81 KEncodingFileDialog (const QString& startDir = QString(),
82 const QString& encoding = QString(),
83 const QString& filter = QString(),
84 const QString& caption = QString(), KFileDialog::OperationMode type = KFileDialog::Opening,
85 QWidget *parent= 0);
86 /**
87 * Destructs the file dialog.
88 */
89 ~KEncodingFileDialog();
90
91
92 /**
93 * @returns The selected encoding if the constructor with the encoding parameter was used, otherwise QString().
94 */
95 QString selectedEncoding() const;
96
97
98 /**
99 * Creates a modal file dialog and return the selected
100 * filename or an empty string if none was chosen additionally a chosen
101 * encoding value is returned.
102 *
103 * Note that with
104 * this method the user must select an existing filename.
105 *
106 * @param encoding The encoding shown in the encoding combo.
107 * @param startDir This can either be
108 * @li The URL of the directory to start in.
109 * @li QString() to start in the current working
110 * directory, or the last directory where a file has been
111 * selected.
112 * @li ':&lt;keyword&gt;' to start in the directory last used
113 * by a filedialog in the same application that specified
114 * the same keyword.
115 * @li '::&lt;keyword&gt;' to start in the directory last used
116 * by a filedialog in any application that specified the
117 * same keyword.
118 * @param filter A shell glob or a mime-type-filter that specifies which files to display.
119 * The preferred option is to set a list of mimetype names, see setMimeFilter() for details.
120 * Otherwise you can set the text to be displayed for the each glob, and
121 * provide multiple globs, see setFilter() for details.
122 * @param parent The widget the dialog will be centered on initially.
123 * @param caption The name of the dialog widget.
124 */
125 static Result getOpenFileNameAndEncoding(const QString& encoding=QString(),
126 const QString& startDir= QString(),
127 const QString& filter= QString(),
128 QWidget *parent= 0,
129 const QString& caption = QString());
130
131 /**
132 * Creates a modal file dialog and returns the selected encoding and the selected
133 * filenames or an empty list if none was chosen.
134 *
135 * Note that with
136 * this method the user must select an existing filename.
137 *
138 * @param encoding The encoding shown in the encoding combo.
139 * @param startDir This can either be
140 * @li The URL of the directory to start in.
141 * @li QString() to start in the current working
142 * directory, or the last directory where a file has been
143 * selected.
144 * @li ':&lt;keyword&gt;' to start in the directory last used
145 * by a filedialog in the same application that specified
146 * the same keyword.
147 * @li '::&lt;keyword&gt;' to start in the directory last used
148 * by a filedialog in any application that specified the
149 * same keyword.
150 * @param filter A shell glob or a mime-type-filter that specifies which files to display.
151 * The preferred option is to set a list of mimetype names, see setMimeFilter() for details.
152 * Otherwise you can set the text to be displayed for the each glob, and
153 * provide multiple globs, see setFilter() for details.
154 * @param parent The widget the dialog will be centered on initially.
155 * @param caption The name of the dialog widget.
156 */
157 static Result getOpenFileNamesAndEncoding(const QString& encoding=QString(),
158 const QString& startDir= QString(),
159 const QString& filter= QString(),
160 QWidget *parent = 0,
161 const QString& caption= QString());
162
163 /**
164 * Creates a modal file dialog and returns the selected encoding and
165 * URL or an empty string if none was chosen.
166 *
167 * Note that with
168 * this method the user must select an existing URL.
169 *
170 * @param encoding The encoding shown in the encoding combo.
171 * @param startDir This can either be
172 * @li The URL of the directory to start in.
173 * @li QString() to start in the current working
174 * directory, or the last directory where a file has been
175 * selected.
176 * @li ':&lt;keyword&gt;' to start in the directory last used
177 * by a filedialog in the same application that specified
178 * the same keyword.
179 * @li '::&lt;keyword&gt;' to start in the directory last used
180 * by a filedialog in any application that specified the
181 * same keyword.
182 * @param filter A shell glob or a mime-type-filter that specifies which files to display.
183 * The preferred option is to set a list of mimetype names, see setMimeFilter() for details.
184 * Otherwise you can set the text to be displayed for the each glob, and
185 * provide multiple globs, see setFilter() for details.
186 * @param parent The widget the dialog will be centered on initially.
187 * @param caption The name of the dialog widget.
188 */
189 static Result getOpenUrlAndEncoding(const QString& encoding=QString(),
190 const QString& startDir = QString(),
191 const QString& filter= QString(),
192 QWidget *parent= 0,
193 const QString& caption = QString());
194
195
196
197
198 /**
199 * Creates a modal file dialog and returns the selected encoding
200 * URLs or an empty list if none was chosen.
201 *
202 * Note that with
203 * this method the user must select an existing filename.
204 *
205 * @param encoding The encoding shown in the encoding combo.
206 * @param startDir This can either be
207 * @li The URL of the directory to start in.
208 * @li QString() to start in the current working
209 * directory, or the last directory where a file has been
210 * selected.
211 * @li ':&lt;keyword&gt;' to start in the directory last used
212 * by a filedialog in the same application that specified
213 * the same keyword.
214 * @li '::&lt;keyword&gt;' to start in the directory last used
215 * by a filedialog in any application that specified the
216 * same keyword.
217 * @param filter A shell glob or a mime-type-filter that specifies which files to display.
218 * The preferred option is to set a list of mimetype names, see setMimeFilter() for details.
219 * Otherwise you can set the text to be displayed for the each glob, and
220 * provide multiple globs, see setFilter() for details.
221 * @param parent The widget the dialog will be centered on initially.
222 * @param caption The name of the dialog widget.
223 */
224 static Result getOpenUrlsAndEncoding(const QString& encoding=QString(),
225 const QString& startDir= QString(),
226 const QString& filter= QString(),
227 QWidget *parent = 0,
228 const QString& caption= QString());
229
230
231
232 /**
233 * Creates a modal file dialog and returns the selected encoding and
234 * filename or an empty string if none was chosen.
235 *
236 * Note that with this
237 * method the user need not select an existing filename.
238 *
239 * @param encoding The encoding shown in the encoding combo.
240 * @param startDir This can either be
241 * @li The URL of the directory to start in.
242 * @li a relative path or a filename determining the
243 * directory to start in and the file to be selected.
244 * @li QString() to start in the current working
245 * directory, or the last directory where a file has been
246 * selected.
247 * @li ':&lt;keyword&gt;' to start in the directory last used
248 * by a filedialog in the same application that specified
249 * the same keyword.
250 * @li '::&lt;keyword&gt;' to start in the directory last used
251 * by a filedialog in any application that specified the
252 * same keyword.
253 * @param filter A shell glob or a mime-type-filter that specifies which files to display.
254 * The preferred option is to set a list of mimetype names, see setMimeFilter() for details.
255 * Otherwise you can set the text to be displayed for the each glob, and
256 * provide multiple globs, see setFilter() for details.
257 * @param parent The widget the dialog will be centered on initially.
258 * @param caption The name of the dialog widget.
259 */
260 static Result getSaveFileNameAndEncoding(const QString& encoding=QString(),
261 const QString& startDir=QString(),
262 const QString& filter= QString(),
263 QWidget *parent= 0,
264 const QString& caption = QString());
265
266
267 /**
268 * Creates a modal file dialog and returns the selected encoding and
269 * filename or an empty string if none was chosen.
270 *
271 * Note that with this
272 * method the user need not select an existing filename.
273 *
274 * @param encoding The encoding shown in the encoding combo.
275 * @param startDir This can either be
276 * @li The URL of the directory to start in.
277 * @li a relative path or a filename determining the
278 * directory to start in and the file to be selected.
279 * @li QString() to start in the current working
280 * directory, or the last directory where a file has been
281 * selected.
282 * @li ':&lt;keyword&gt;' to start in the directory last used
283 * by a filedialog in the same application that specified
284 * the same keyword.
285 * @li '::&lt;keyword&gt;' to start in the directory last used
286 * by a filedialog in any application that specified the
287 * same keyword.
288 * @param filter A shell glob or a mime-type-filter that specifies which files to display.
289 * The preferred option is to set a list of mimetype names, see setMimeFilter() for details.
290 * Otherwise you can set the text to be displayed for the each glob, and
291 * provide multiple globs, see setFilter() for details.
292 * @param parent The widget the dialog will be centered on initially.
293 * @param caption The name of the dialog widget.
294 */
295 static Result getSaveUrlAndEncoding(const QString& encoding=QString(),
296 const QString& startDir= QString(),
297 const QString& filter= QString(),
298 QWidget *parent= 0,
299 const QString& caption = QString());
300
301
302
303private:
304 KEncodingFileDialogPrivate* const d;
305};
306
307#endif
308