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 | |
27 | struct 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 | |
39 | class KIO_EXPORT KEncodingFileDialog : public KFileDialog |
40 | { |
41 | Q_OBJECT |
42 | |
43 | public: |
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 ':<keyword>' to start in the directory last used |
60 | * by a filedialog in the same application that specified |
61 | * the same keyword. |
62 | * @li '::<keyword>' 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 ':<keyword>' to start in the directory last used |
113 | * by a filedialog in the same application that specified |
114 | * the same keyword. |
115 | * @li '::<keyword>' 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 ':<keyword>' to start in the directory last used |
145 | * by a filedialog in the same application that specified |
146 | * the same keyword. |
147 | * @li '::<keyword>' 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 ':<keyword>' to start in the directory last used |
177 | * by a filedialog in the same application that specified |
178 | * the same keyword. |
179 | * @li '::<keyword>' 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 ':<keyword>' to start in the directory last used |
212 | * by a filedialog in the same application that specified |
213 | * the same keyword. |
214 | * @li '::<keyword>' 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 ':<keyword>' to start in the directory last used |
248 | * by a filedialog in the same application that specified |
249 | * the same keyword. |
250 | * @li '::<keyword>' 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 ':<keyword>' to start in the directory last used |
283 | * by a filedialog in the same application that specified |
284 | * the same keyword. |
285 | * @li '::<keyword>' 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 | |
303 | private: |
304 | KEncodingFileDialogPrivate* const d; |
305 | }; |
306 | |
307 | #endif |
308 | |