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