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 | |
28 | class QByteArray; |
29 | class 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 | */ |
62 | class KIO_EXPORT KScanDialog : public KPageDialog |
63 | { |
64 | Q_OBJECT |
65 | |
66 | public: |
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 | |
91 | protected: |
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 | |
132 | Q_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 | |
161 | private: |
162 | class KScanDialogPrivate; |
163 | KScanDialogPrivate *const d; |
164 | }; |
165 | |
166 | |
167 | /** |
168 | * Base class for OCR Dialogs. |
169 | */ |
170 | class KIO_EXPORT KOCRDialog : public KPageDialog |
171 | { |
172 | Q_OBJECT |
173 | |
174 | public: |
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 | |
186 | protected: |
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 | |
221 | Q_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 | |
232 | private: |
233 | class KOCRDialogPrivate; |
234 | KOCRDialogPrivate * const d; |
235 | }; |
236 | |
237 | |
238 | #endif // KSCAN_H |
239 | |