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