1/* This file is part of the KDE libraries
2 Copyright (C) 2001 Carsten Pfeiffer <pfeiffer@kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License as published by the Free Software Foundation; either
7 version 2 of the License, or (at your option) any later version.
8
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Library General Public License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to
16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 Boston, MA 02110-1301, USA.
18*/
19
20#ifndef KSCAN_H
21#define KSCAN_H
22
23#include <kio/kio_export.h>
24#include <kpagedialog.h>
25#include <kcomponentdata.h> // KDE5: remove include
26#include <kpluginfactory.h> // KDE5: remove include
27
28class QByteArray;
29class QImage;
30
31/**
32 * This is a base class for scanning dialogs. You can derive from this class
33 * and implement your own dialog. An implementation is available in
34 * kdegraphics/libkscan.
35 *
36 * Application developers that wish to add scanning support to their program
37 * can use the static method @p KScanDialog::getScanDialog() to get an instance
38 * of the user's preferred scanning dialog.
39 *
40 * Typical usage looks like this (e.g. in a slotShowScanDialog() method):
41 *
42 * \code
43 * if ( !m_scanDialog ) {
44 * m_scanDialog = KScanDialog::getScanDialog( this );
45 * if ( !m_scanDialog ) // no scanning support installed?
46 * return;
47 *
48 * connect( m_scanDialog, SIGNAL( finalImage( const QImage&, int )),
49 * SLOT( slotScanned( const QImage&, int ) ));
50 * }
51 *
52 * if ( m_scanDialog->setup() ) // only if scanner configured/available
53 * m_scanDialog->show();
54 * \endcode
55 *
56 * This will create and show a non-modal scanning dialog. Connect to more
57 * signals if you like.
58 *
59 * @short A baseclass and accessor for Scanning Dialogs
60 * @author Carsten Pfeiffer <pfeiffer@kde.org>
61 */
62class KIO_EXPORT KScanDialog : public KPageDialog
63{
64 Q_OBJECT
65
66public:
67 /**
68 * Creates the user's preferred scanning dialog and returns it,
69 * or 0L if no scan-support
70 * is available. Pass a suitable @p parent widget, if you like. If you
71 * don't you have to 'delete' the returned pointer yourself.
72 * @param parent the QWidget's parent, or 0
73 * @return the KScanDialog, or 0 if the function failed
74 */
75 static KScanDialog * getScanDialog( QWidget *parent = 0 );
76 /**
77 * Destructs the scan dialog.
78 */
79 ~KScanDialog();
80
81 /**
82 * Reimplement this if you need to set up some things, before showing the
83 * dialog, e.g. to ask the user for the scanner device to use. If you
84 * return false (e.g. there is no device available or the user aborted
85 * device selection), the dialog will not be shown.
86 *
87 * @return true by default.
88 */
89 virtual bool setup();
90
91protected:
92 /**
93 * Constructs the scan dialog. If you implement an own dialog, you can
94 * customize it with the usual KPageDialog flags.
95 *
96 * @param dialogFace The KPageDialog::FaceType
97 * @param buttonMask An ORed mask of all buttons (see
98 * KDialog::ButtonCode)
99 * @param parent The QWidget's parent, or 0
100 * @see KPageDialog
101 */
102 explicit KScanDialog( int dialogFace = Tabbed,
103 int buttonMask = Close|Help,
104 QWidget *parent = 0 );
105
106 /**
107 * Returns the current id for an image. You can use that in your subclass
108 * for the signals. The id is used in the signals to let people know
109 * which preview and which text-recognition belongs to which scan.
110 *
111 * @return the current id for the image
112 * @see nextId
113 * @see finalImage
114 * @see preview
115 * @see textRecognized
116 */
117 int id() const;
118
119 /**
120 * Returns the id for the next image. You can use that in your subclass
121 * for the signals.
122 *
123 * @return the id for the next image
124 * @see id
125 * @see finalImage
126 * @see preview
127 * @see textRecognized
128 *
129 */
130 int nextId();
131
132Q_SIGNALS:
133 /**
134 * Informs you that an image has been previewed.
135 * @param img the image
136 * @param id the image's id
137 */
138 void preview( const QImage &img, int id );
139
140 /**
141 * Informs you that an image has scanned. @p id is the same as in the
142 * @p preview() signal, if this image had been previewed before.
143 *
144 * Note, that those id's may not be properly implemented in the current
145 * libkscan.
146 * @param img the image
147 * @param id the image's id
148 */
149 void finalImage( const QImage &img, int id );
150
151 /**
152 * Informs you that the image with the id @p id has been run through
153 * text-recognition. The text is in the QString parameter. In the future,
154 * a compound document, using rich text will be used instead.
155 *
156 * @param text the text that has been recognized
157 * @param id the id of the image
158 */
159 void textRecognized( const QString &text, int id );
160
161private:
162 class KScanDialogPrivate;
163 KScanDialogPrivate *const d;
164};
165
166
167/**
168 * Base class for OCR Dialogs.
169 */
170class KIO_EXPORT KOCRDialog : public KPageDialog
171{
172 Q_OBJECT
173
174public:
175 /**
176 * Creates the user's preferred OCR dialog and returns it,
177 * or 0L if no OCR-support
178 * is available. Pass a suitable @p parent widget, if you like. If you
179 * don't you have to 'delete' the returned pointer yourself.
180 * @param parent the QWidget's parent, or 0
181 * @return the KOCRDialog, or 0 if the function failed
182 */
183 static KOCRDialog * getOCRDialog( QWidget *parent = 0 );
184 ~KOCRDialog();
185
186protected:
187 /**
188 * Constructs the OCR dialog. If you implement an own dialog, you can
189 * customize it with the usual KPageDialog flags.
190 *
191 * @param dialogFace the KPageDialog::FaceType
192 * @param buttonMask a ORed mask of all buttons (see
193 * KDialog::ButtonCode)
194 * @param parent the QWidget's parent, or 0
195 * @param modal if true the dialog is model
196 */
197 explicit KOCRDialog( int dialogFace=Tabbed, int buttonMask = Close|Help,
198 QWidget *parent=0L, bool modal=false );
199
200 /**
201 * Returns the current id for an image. You can use that in your subclass
202 * for the signals. The id is used in the signals to let people know
203 * which text-recognition belongs to which scan.
204 *
205 * @return the current id for the image
206 * @see nextId
207 * @see textRecognized
208 */
209 int id() const;
210
211 /**
212 * Returns the id for the next image. You can use that in your subclass
213 * for the signals.
214 *
215 * @return the id for the next image
216 * @see id
217 * @see textRecognized
218 */
219 int nextId();
220
221Q_SIGNALS:
222 /**
223 * Informs you that the image with the id @p id has been run through
224 * text-recognition. The text is in the QString parameter. In the future,
225 * a compound document, using rich text will be used instead.
226 *
227 * @param text the text that has been recognized
228 * @param id the id of the image
229 */
230 void textRecognized( const QString &text, int id );
231
232private:
233 class KOCRDialogPrivate;
234 KOCRDialogPrivate * const d;
235};
236
237
238#endif // KSCAN_H
239