File indexing completed on 2024-03-24 15:48:00
0001 /************************************************************************ 0002 * * 0003 * This file is part of Kooka, a scanning/OCR application using * 0004 * Qt <http://www.qt.io> and KDE Frameworks <http://www.kde.org>. * 0005 * * 0006 * Copyright (C) 2016 Jonathan Marten <jjm@keelhaul.me.uk> * 0007 * * 0008 * Kooka is free software; you can redistribute it and/or modify it * 0009 * under the terms of the GNU Library General Public License as * 0010 * published by the Free Software Foundation and appearing in the * 0011 * file COPYING included in the packaging of this file; either * 0012 * version 2 of the License, or (at your option) any later version. * 0013 * * 0014 * As a special exception, permission is given to link this program * 0015 * with any version of the KADMOS OCR/ICR engine (a product of * 0016 * reRecognition GmbH, Kreuzlingen), and distribute the resulting * 0017 * executable without including the source code for KADMOS in the * 0018 * source distribution. * 0019 * * 0020 * This program is distributed in the hope that it will be useful, * 0021 * but WITHOUT ANY WARRANTY; without even the implied warranty of * 0022 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * 0023 * GNU General Public License for more details. * 0024 * * 0025 * You should have received a copy of the GNU General Public * 0026 * License along with this program; see the file COPYING. If * 0027 * not, see <http://www.gnu.org/licenses/>. * 0028 * * 0029 ************************************************************************/ 0030 0031 #ifndef RECENTSAVER_H 0032 #define RECENTSAVER_H 0033 0034 #include <qstring.h> 0035 #include "libdialogutil_export.h" 0036 0037 class QUrl; 0038 0039 0040 /** 0041 * @short A helper to look up and save recent locations for a file dialogue. 0042 * 0043 * Saving the recent locations is handled by @c KRecentDirs, but a bit of code 0044 * is needed before and after each file dialogue to look up the appropriate 0045 * recent location and save it afterwards. This class automates that. 0046 * 0047 * For a simple use of the static QFileDialog functions, simple create and 0048 * use a RecentSaver like this: 0049 * 0050 * @code 0051 * RecentSaver recent("key"); 0052 * QUrl u = QFileDialog::getSaveFileUrl(parent, i18n("caption"), 0053 * recent.recentUrl("untitled.ext")) 0054 * if (u.isValid()) 0055 * { 0056 * recent.save(u); 0057 * // use the URL 0058 * } 0059 * @endcode 0060 * 0061 * @see KRecentDirs 0062 * @see QFileDialog 0063 * @author Jonathan Marten 0064 **/ 0065 0066 class LIBDIALOGUTIL_EXPORT RecentSaver 0067 { 0068 public: 0069 /** 0070 * Constructor. 0071 * 0072 * @param fileClass The name of the file class. If the application-global 0073 * recent locations list is to be used then this may start with a single ":", 0074 * but need not do so; if it does not start with a ":" then one is assumed. 0075 * If the system-global recent locations list is to be used then this 0076 * must start with "::". 0077 **/ 0078 explicit RecentSaver(const QString &fileClass); 0079 0080 /** 0081 * Destructor. 0082 **/ 0083 ~RecentSaver() = default; 0084 0085 /** 0086 * Resolve the saved recent location (if there is one) and a suggested 0087 * file name (if required) into a URL to pass to a @c QFileDialog 0088 * which expects a URL. 0089 * 0090 * @param suggestedName The suggested file name, or a null string 0091 * if none is required. 0092 * @return The resolved URL, or a null URL if there is no saved 0093 * history. 0094 **/ 0095 QUrl recentUrl(const QString &suggestedName = QString()); 0096 0097 /** 0098 * Resolve the saved recent location (if there is one) and a suggested 0099 * file name (if required) into a path, to pass to a @c QFileDialog 0100 * which expects a pathname. 0101 * 0102 * @param suggestedName The suggested file name, or a null string 0103 * if none is required. 0104 * @return The resolved file path, or a null string if there is no 0105 * saved history. 0106 **/ 0107 QString recentPath(const QString &suggestedName = QString()); 0108 0109 /** 0110 * Save the location selected by the file dialogue as a new recent location. 0111 * 0112 * @param url The URL returned from the file dialogue. 0113 **/ 0114 void save(const QUrl &url); 0115 0116 /** 0117 * Save the location selected by the file dialogue as a new recent location. 0118 * 0119 * @param url The file path returned from the file dialogue. 0120 **/ 0121 void save(const QString &path); 0122 0123 private: 0124 QString mRecentClass; 0125 QString mRecentDir; 0126 }; 0127 0128 #endif // RECENTSAVER_H