File indexing completed on 2024-04-28 08:11:03
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) 1999-2016 Klaas Freitag <freitag@suse.de> * 0007 * Jonathan Marten <jjm@keelhaul.me.uk> * 0008 * * 0009 * Kooka is free software; you can redistribute it and/or modify it * 0010 * under the terms of the GNU Library General Public License as * 0011 * published by the Free Software Foundation and appearing in the * 0012 * file COPYING included in the packaging of this file; either * 0013 * version 2 of the License, or (at your option) any later version. * 0014 * * 0015 * As a special exception, permission is given to link this program * 0016 * with any version of the KADMOS OCR/ICR engine (a product of * 0017 * reRecognition GmbH, Kreuzlingen), and distribute the resulting * 0018 * executable without including the source code for KADMOS in the * 0019 * source distribution. * 0020 * * 0021 * This program is distributed in the hope that it will be useful, * 0022 * but WITHOUT ANY WARRANTY; without even the implied warranty of * 0023 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * 0024 * GNU General Public License for more details. * 0025 * * 0026 * You should have received a copy of the GNU General Public * 0027 * License along with this program; see the file COPYING. If * 0028 * not, see <http://www.gnu.org/licenses/>. * 0029 * * 0030 ************************************************************************/ 0031 0032 #ifndef IMGSAVER_H 0033 #define IMGSAVER_H 0034 0035 #include <qurl.h> 0036 0037 #include "kookacore_export.h" 0038 0039 #include "scanimage.h" 0040 #include "imageformat.h" 0041 0042 class QWidget; 0043 0044 0045 /** 0046 * @short Manages the saving of images. 0047 * 0048 * All saving of images within the application is handled here. Depending 0049 * on the user's preference settings and saved information, it may either 0050 * decide where to save the image automatically, or ask the user for 0051 * a file name and file format. 0052 * 0053 * @author Klaas Freitag 0054 * @author Jonathan Marten 0055 **/ 0056 0057 class KOOKACORE_EXPORT ImgSaver 0058 { 0059 public: 0060 0061 /** 0062 * Status return information. 0063 * 0064 * @see errorString 0065 **/ 0066 enum ImageSaveStatus 0067 { 0068 SaveStatusOk, ///< Success 0069 SaveStatusPermission, ///< Permission denied 0070 SaveStatusBadFilename, ///< Bad file name 0071 SaveStatusNoSpace, ///< No space left on device 0072 SaveStatusFormatNoWrite, ///< Cannot write this image format 0073 SaveStatusFailed, ///< Image save failed 0074 SaveStatusParam, ///< Bad parameter 0075 SaveStatusProtocol, ///< Cannot write to this protocol 0076 SaveStatusMkdir, ///< Cannot create directory 0077 SaveStatusCanceled ///< User cancelled 0078 }; 0079 0080 /** 0081 * Constructor. 0082 * 0083 * @param dir The directory into which the image is to eventually 0084 * be saved. If it does not exist, it will be created at this point. 0085 * The default is the current gallery root. 0086 **/ 0087 explicit ImgSaver(const QUrl &dir = QUrl()); 0088 0089 /** 0090 * Save an image. 0091 * 0092 * @param image The image to save. 0093 * @param url Where to save the image to. This must be a complete URL 0094 * including file name. 0095 * @param format The format to save the image in. 0096 * @param subformat Additional information for the format. 0097 * 0098 * @return Status of the save 0099 * 0100 * @note The @c dir parameter to the constructor is ignored. 0101 **/ 0102 ImgSaver::ImageSaveStatus saveImage(const ScanImage::Ptr image, 0103 const QUrl &url, 0104 const ImageFormat &format, 0105 const QString &subformat = QString()); 0106 0107 /** 0108 * Save an image. 0109 * 0110 * The image is saved to the @c dir location as specified in the 0111 * constructor. Depending on the settings of the application preferences, 0112 * whether @c setImageInfo has previously been called with enough 0113 * information, or the previously remembered settings, this may prompt 0114 * the user for a file name, a file format, or both. 0115 * 0116 * @param image The image to save 0117 * 0118 * @return Status of the save 0119 * 0120 * @see setImageInfo 0121 **/ 0122 ImgSaver::ImageSaveStatus saveImage(const ScanImage::Ptr image); 0123 0124 /** 0125 * Set image information prior to saving. 0126 * 0127 * If there is enough information provided, the file name and save 0128 * format will be resolved and remembered for a subsequent @c saveImage 0129 * operation. The user may be prompted for a file name and/or a file 0130 * format at this point. 0131 * 0132 * @param type the image type 0133 * @return Status of the operation 0134 * @see saveImage 0135 **/ 0136 ImgSaver::ImageSaveStatus setImageInfo(ScanImage::ImageType type); 0137 0138 /** 0139 * Get a readable description for an status return code. 0140 * 0141 * @return The I18N'ed message. 0142 **/ 0143 QString errorString(ImgSaver::ImageSaveStatus status) const; 0144 0145 /** 0146 * Copy a image file. 0147 * 0148 * The file is copied, without any interpretation of the contents, 0149 * using KIO. 0150 * 0151 * @param fromUrl The existing file to be copied. 0152 * @param toUrl The destination file, which must not already exist. 0153 * @param overWidget Top level widget, for KIO access purposes. 0154 * 0155 * @return @c true if the copy operation succeeded. 0156 * 0157 * @note If the @p toUrl does not have a file name extension 0158 * corresponding to any a known MIME type but the @p fromUrl does, 0159 * then the user is asked whether to add the same extension as 0160 * the @p fromUrl. 0161 * 0162 * @note If the @p toUrl and the @p fromurl both do have a file name 0163 * extensions, then they must resolve to the same MIME type. 0164 **/ 0165 static bool copyImage(const QUrl &fromUrl, const QUrl &toUrl, QWidget *overWidget = nullptr); 0166 0167 /** 0168 * Rename a image file. 0169 * 0170 * The file is renamed or moved, without any interpretation of the 0171 * contents, using KIO. 0172 * 0173 * @param fromUrl The existing file to be renamed. 0174 * @param toUrl The destination file, which must not already exist. 0175 * @param overWidget Top level widget, for KIO access purposes. 0176 * 0177 * @return @c true if the rename operation succeeded. 0178 * 0179 * @note If the @p toUrl does not have a file name extension 0180 * corresponding to any a known MIME type but the @p fromUrl does, 0181 * then the user is asked whether to add the same extension as 0182 * the @p fromUrl. 0183 * 0184 * @note If the @p toUrl and the @p fromurl both do have a file name 0185 * extensions, then they must resolve to the same MIME type. 0186 **/ 0187 static bool renameImage(const QUrl &fromUrl, const QUrl &toUrl, bool askExt = false, QWidget *overWidget = nullptr); 0188 0189 /** 0190 * Check the remembered save format for an image type. 0191 * 0192 * @param type Type of image 0193 * @param format Save format 0194 * 0195 * @return @c true if @p format is the remembered format for the image @p type. 0196 **/ 0197 static bool isRememberedFormat(ScanImage::ImageType type, const ImageFormat &format); 0198 0199 /** 0200 * Get a readable description for an image type. 0201 * 0202 * @param type Type of image 0203 * @return The readable description 0204 **/ 0205 static QString picTypeAsString(ScanImage::ImageType type); 0206 0207 /** 0208 * Get the location where the image will be saved to. 0209 * 0210 * @return Save location 0211 **/ 0212 QUrl saveURL() const 0213 { 0214 return (mSaveUrl); 0215 } 0216 0217 /** 0218 * Get the location where the previous image was saved to. 0219 * 0220 * @return Save location 0221 **/ 0222 QUrl lastURL() const 0223 { 0224 return (mLastUrl); 0225 } 0226 0227 private: 0228 QString createFilename(); 0229 ImgSaver::ImageSaveStatus getFilenameAndFormat(ScanImage::ImageType type); 0230 0231 QUrl m_saveDirectory; // dir where the image should be saved 0232 QByteArray mLastFormat; 0233 QUrl mLastUrl; 0234 0235 bool m_saveAskFormat; 0236 bool m_saveAskFilename; 0237 0238 QUrl mSaveUrl; 0239 ImageFormat mSaveFormat; 0240 QString mSaveSubformat; 0241 }; 0242 0243 #endif // IMGSAVER_H