1 /************************************************************************ 2 * * 3 * This file is part of Kooka, a scanning/OCR application using * 4 * Qt <http://www.qt.io> and KDE Frameworks <http://www.kde.org>. * 5 * * 6 * Copyright (C) 2000-2016 Klaas Freitag <freitag@suse.de> * 7 * Jonathan Marten <jjm@keelhaul.me.uk> * 8 * * 9 * Kooka is free software; you can redistribute it and/or modify it * 10 * under the terms of the GNU Library General Public License as * 11 * published by the Free Software Foundation and appearing in the * 12 * file COPYING included in the packaging of this file; either * 13 * version 2 of the License, or (at your option) any later version. * 14 * * 15 * As a special exception, permission is given to link this program * 16 * with any version of the KADMOS OCR/ICR engine (a product of * 17 * reRecognition GmbH, Kreuzlingen), and distribute the resulting * 18 * executable without including the source code for KADMOS in the * 19 * source distribution. * 20 * * 21 * This program is distributed in the hope that it will be useful, * 22 * but WITHOUT ANY WARRANTY; without even the implied warranty of * 23 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * 24 * GNU General Public License for more details. * 25 * * 26 * You should have received a copy of the GNU General Public * 27 * License along with this program; see the file COPYING. If * 28 * not, see <http://www.gnu.org/licenses/>. * 29 * * 30 ************************************************************************/ 31 32 #ifndef KSCANOPTSET_H 33 #define KSCANOPTSET_H 34 35 #include "kookascan_export.h" 36 37 #include <qhash.h> 38 #include <qmap.h> 39 #include <qbytearray.h> 40 41 class KScanOption; 42 43 /** 44 * @short A set of scanner parameters. 45 * 46 * Named scanner parameters can be added to the set, which stores 47 * their names and values. They can be enumerated and retrieved from 48 * the set. 49 * 50 * A set can be saved to and restored from the global scanner 51 * configuration file. This can be used to save scanner options 52 * between runs of an application, or to manage a repertoire of 53 * saved scanner configurations. 54 * 55 * The saved sets available can be listed, and a saved set can be 56 * deleted from the configuration file. 57 * 58 * @author Klaas Freitag 59 * @author Jonathan Marten 60 **/ 61 62 class KOOKASCAN_EXPORT KScanOptSet : public QHash<QByteArray, QByteArray> 63 { 64 65 public: 66 /** 67 * A map as returned by @c readList(). 68 */ 69 typedef QMap<QString, QString> StringMap; 70 71 /** 72 * Create a new option set container. 73 * 74 * @param setName name for the option set. When saving to or loading 75 * from a configuration file, the set name specified here is used as 76 * the group name. 77 **/ 78 explicit KScanOptSet(const QString &setName); 79 80 /** 81 * Destructor. 82 **/ 83 ~KScanOptSet(); 84 85 /** 86 * Save the current value of an option. 87 * 88 * @param opt The option whose value is to be saved 89 * @return @c true if the option was successfully stored 90 */ 91 bool backupOption(const KScanOption *opt); 92 93 /** 94 * Return the currently stored value of an option. 95 * 96 * @param optName The name of the required option 97 * @return The value of the option, or a null string if no 98 * option of that name is present. 99 * @deprecated Use QHash::value() instead. 100 **/ 101 QByteArray Q_DECL_DEPRECATED getValue(const QByteArray &optName) const; 102 103 /** 104 * Save the option set to the global scanner configuration file. 105 * 106 * @param scannerName The SANE device name of the scanner to which 107 * this configuration applies. 108 * @param desc A description for the option set. If this is a null or 109 * empty string, the description set by setDescription() is used. 110 * 111 * @note This does not automatically read the current options from the 112 * scanner before saving them to the configuration file, the values last 113 * read by backupOption() are used. Therefore, to ensure the saved 114 * option set correctly reflects the current scanner parameters, the 115 * following should be done: 116 * 117 * @code 118 * KScanOptSet optSet(setName); 119 * saneDevice->getCurrentOptions(&optSet); 120 * optSet.saveConfig(saneDevice->scannerBackendName(), setDesc); 121 * @endcode 122 **/ 123 void saveConfig(const QByteArray &scannerName, const QString &desc = QString()) const; 124 125 /** 126 * Load an option set from the global scanner configuration file. 127 * 128 * @param scannerName The SANE device name of the scanner to which 129 * this configuration is intended to apply. If it does not match the 130 * scanner name that this option set was saved for, a warning message 131 * is output (but the load will succeed, as far as is possible, anyway). 132 * If this is a null or empty string, no check is made. 133 * @return @c true if the load was successful. 134 * 135 * @note The option values read are not automatically sent to the scanner. 136 * Therefore, to ensure that the scanner uses the loaded values, the 137 * following should be done: 138 * 139 * @code 140 * KScanOptSet optSet(setName); 141 * optSet.loadConfig(); 142 * saneDevice->loadOptionSet(&optSet); 143 * saneDevice->reloadAll(); 144 * @endcode 145 * 146 * @note The option set is not cleared before it is loaded from the 147 * configuration file, so any preexisting options which are not present 148 * in the file will retain their previous values. If a clean loaded 149 * set is required for a previously-used option set, then simply use 150 * @c clear() on it before calling @c loadConfig(). 151 **/ 152 bool loadConfig(const QByteArray &scannerName = ""); 153 154 /** 155 * Set a description for the option set. 156 * 157 * @param desc The new description 158 **/ 159 void setDescription(const QString &desc); 160 161 /** 162 * Get the description of the option set. 163 * 164 * @return The option set description 165 **/ getDescription()166 QString getDescription() const { return (mSetDescription); } 167 168 /** 169 * Set a new name for the option set. 170 * 171 * @param newName The new option set name 172 **/ 173 void setSetName(const QString &newName); 174 175 /** 176 * Get the name of the option set. 177 * 178 * @return The option set name 179 **/ getSetName()180 const QString &getSetName() const { return (mSetName); } 181 182 /** 183 * Read all of the available saved option set names and descriptions 184 * from the configuration file. 185 * 186 * @return A map from each available set name to its description 187 **/ 188 static StringMap readList(); 189 190 /** 191 * Delete a saved option set from the configuration file. 192 * 193 * @param setName The name of the set to delete 194 **/ 195 static void deleteSet(const QString &setName); 196 197 /** 198 * Get the name of the default startup option set. 199 * 200 * @return The set name 201 **/ startupSetName()202 static QString startupSetName() { return ("saveSet"); } 203 204 private: 205 QString mSetName; 206 QString mSetDescription; 207 }; 208 209 #endif // KSCANOPTSET_H 210