KSane

ksanewidget.h
1/*
2 * SPDX-FileCopyrightText: 2007-2010 Kare Sars <kare dot sars at iki dot fi>
3 * SPDX-FileCopyrightText: 2007 Gilles Caulier <caulier dot gilles at gmail dot com>
4 * SPDX-FileCopyrightText: 2014 Gregor Mitsch : port to KDE5 frameworks
5 * SPDX-FileCopyrightText: 2021 Alexander Stippich <a.stippich@gmx.net>
6 *
7 * SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
8 */
9
10#ifndef KSANE_H
11#define KSANE_H
12
13#include "ksane_export.h"
14
15#include <QWidget>
16
17namespace KSaneIface
18{
19
20class KSaneWidgetPrivate;
21
22/**
23 * This class provides the widget containing the scan options and the preview.
24 * @author Kare Sars <kare.sars@iki.fi>
25 */
26class KSANE_EXPORT KSaneWidget : public QWidget
27{
28 Q_OBJECT
29 friend class KSaneWidgetPrivate;
30
31public:
32
33 /** @note There might come more enumerations in the future. */
34 typedef enum {
35 NoError, /**< The scanning was finished successfully.*/
36 ErrorCannotSegment, /**< If this error status is returned libksane can not segment the
37 * returned data. Scanning without segmentation should work.
38 * @note segmentation is not implemented yet.*/
39 ErrorGeneral, /**< The error string should contain an error message. */
40 Information /**< There is some information to the user. */
41 } ScanStatus;
42
43 struct DeviceInfo {
44 QString name; /* unique device name */
45 QString vendor; /* device vendor string */
46 QString model; /* device model name */
47 QString type; /* device type (e.g., "flatbed scanner") */
48 };
49
50 /** This constructor initializes the private class variables, but the widget is left empty.
51 * The options and the preview are added with the call to openDevice(). */
52 KSaneWidget(QWidget *parent = nullptr);
53
54 /** Standard destructor */
55 ~KSaneWidget() override;
56
57 /** This helper method displays a dialog for selecting a scanner. The libsane
58 * device name of the selected scanner device is returned. */
59 QString selectDevice(QWidget *parent = nullptr);
60
61 /** This method opens the specified scanner device and adds the scan options to the
62 * KSane widget.
63 * @param device_name is the libsane device name for the scanner to open.
64 * @return 'true' if all goes well and 'false' if the specified scanner can not be opened. */
65 bool openDevice(const QString &device_name);
66
67 /** This method closes the currently open scanner device.
68 * @return 'true' if all goes well and 'false' if no device is open. */
69 bool closeDevice();
70
71 /** This method returns the internal device name of the currently opened scanner. */
72 QString deviceName() const;
73
74 /** This method returns the vendor name of the currently opened scanner. */
75 QString deviceVendor() const;
76
77 /** This method returns the model of the currently opened scanner. */
78 QString deviceModel() const;
79
80 /** This method returns the scan area's width in mm
81 * @return Width of the scannable area in mm */
82 float scanAreaWidth();
83
84 /** This method returns the scan area's height in mm
85 * @return Height of the scannable area in mm */
86 float scanAreaHeight();
87
88 /** This method sets the selection according to the given points
89 * @note The points are defined with respect to the scan areas top-left corner in mm
90 * @param topLeft Upper left corner of the selection (in mm)
91 * @param bottomRight Lower right corner of the selection (in mm) */
92 void setSelection(QPointF topLeft, QPointF bottomRight);
93
94 /** This function is used to set the preferred resolution for scanning the preview.
95 * @param dpi is the wanted scan resolution for the preview
96 * @note if the set value is not supported, the cloasest one is used
97 * @note setting the value 0 means that the default calculated value should be used */
98 void setPreviewResolution(float dpi);
99
100 /** This method reads the available parameters and their values and
101 * returns them in a QMap (Name, value)
102 * @param opts is a QMap with the parameter names and values. */
103 void getOptionValues(QMap <QString, QString> &options);
104
105 /** This method can be used to write many parameter values at once.
106 * @param opts is a QMap with the parameter names and values.
107 * @return This function returns the number of successful writes
108 * or -1 if scanning is in progress. */
109 int setOptionValues(const QMap <QString, QString> &options);
110
111 /** This function reads one parameter value into a string.
112 * @param optname is the name of the parameter to read.
113 * @param value is the string representation of the value.
114 * @return this function returns true if the read was successful. */
115 bool getOptionValue(const QString &option, QString &value);
116
117 /** This function writes one parameter value into a string.
118 * @param optname is the name of the parameter to write.
119 * @param value is the string representation of the value.
120 * @return this function returns true if the write was successful and
121 * false if it was unsuccessful or scanning is in progress. */
122 bool setOptionValue(const QString &option, const QString &value);
123
124 /** This function can be used to enable/disable automatic selections on previews.
125 * The default state is enabled.
126 * @param enable specifies if the auto selection should be turned on or off. */
127 void enableAutoSelect(bool enable);
128
129public Q_SLOTS:
130 /** This method can be used to cancel a scan or prevent an automatic new scan. */
131 void cancelScan();
132
133 /** This method can be used to start a scan (if no GUI is needed).
134 * @note libksane may return one or more images as a result of one invocation of this slot.
135 * If no more images are wanted cancelScan should be called in the slot handling the
136 * imageReady signal. */
137 void startScan();
138
139 /** This method can be used to start a preview scan. */
140 void startPreviewScan();
141
142Q_SIGNALS:
143 /**
144 * This signal is emitted when a final scan is ready.
145 * @param scannedImage is the QImage containing the scanned image data. */
146 void scannedImageReady(const QImage &scannedImage);
147
148 /**
149 * This signal is emitted when the scanning has ended.
150 * @param status contains a ScanStatus status code.
151 * @param strStatus If an error has occurred this string will contain an error message.
152 * otherwise the string is empty. */
153 void scanDone(int status, const QString &strStatus);
154
155 /**
156 * This signal is emitted when the user is to be notified about something.
157 * @note If no slot is connected to this signal the message will be displayed in a KMessageBox.
158 * @param type contains a ScanStatus code to identify the type of message (error/info/...).
159 * @param strStatus If an error has occurred this string will contain an error message.
160 * otherwise the string is empty. */
161 void userMessage(int type, const QString &strStatus);
162
163 /**
164 * This Signal is emitted for progress information during a scan.
165 * The GUI already has a progress bar, but if the GUI is hidden,
166 * this can be used to display a progress bar.
167 * @param percent is the percentage of the scan progress (0-100). */
168 void scanProgress(int percent);
169
170 /**
171 * This signal is emitted every time the device list is updated or
172 * after initGetDeviceList() is called.
173 * @param deviceList is a QList of KSaneWidget::DeviceInfo that contain the
174 * device name, model, vendor and type of the attached scanners.
175 * @note The list is only a snapshot of the current available devices. Devices
176 * might be added or removed/opened after the signal is emitted.
177 */
179
180 /**
181 * This Signal is emitted when a hardware button is pressed.
182 * @param optionName is the untranslated technical name of the sane-option.
183 * @param optionLabel is the translated user visible label of the sane-option.
184 * @param pressed indicates if the value is true or false.
185 * @note The SANE standard does not specify hardware buttons and their behaviors,
186 * so this signal is emitted for sane-options that behave like hardware buttons.
187 * That is the sane-options are read-only and type boolean. The naming of hardware
188 * buttons also differ from backend to backend.
189 */
190 void buttonPressed(const QString &optionName, const QString &optionLabel, bool pressed);
191
192 /**
193 * This signal is not emitted anymore.
194 */
195 void openedDeviceInfoUpdated(const QString &deviceName, const QString &deivceVendor, const QString &deviceModel);
196
197private:
198 KSaneWidgetPrivate *const d;
199};
200
201} // NameSpace KSaneIface
202
203#endif // SANE_WIDGET_H
This class provides the widget containing the scan options and the preview.
Definition ksanewidget.h:27
@ NoError
The scanning was finished successfully.
Definition ksanewidget.h:35
@ ErrorGeneral
The error string should contain an error message.
Definition ksanewidget.h:39
void availableDevices(const QList< KSaneWidget::DeviceInfo > &deviceList)
This signal is emitted every time the device list is updated or after initGetDeviceList() is called.
void scanDone(int status, const QString &strStatus)
This signal is emitted when the scanning has ended.
void userMessage(int type, const QString &strStatus)
This signal is emitted when the user is to be notified about something.
void openedDeviceInfoUpdated(const QString &deviceName, const QString &deivceVendor, const QString &deviceModel)
This signal is not emitted anymore.
void scannedImageReady(const QImage &scannedImage)
This signal is emitted when a final scan is ready.
void scanProgress(int percent)
This Signal is emitted for progress information during a scan.
void buttonPressed(const QString &optionName, const QString &optionLabel, bool pressed)
This Signal is emitted when a hardware button is pressed.
Q_SCRIPTABLE CaptureState status()
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 24 2024 12:00:24 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.