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