← Back to branch summary

~ubuntu-branches/ubuntu/maverick/kdegraphics/maverick-proposed

« back to all changes in this revision

Viewing changes to libs/libksane/libksane/ksane.h

  • Committer: Bazaar Package Importer
  • Author(s): Jonathan Thomas
  • Date: 2009-12-02 14:03:43 UTC
  • mfrom: (1.1.35 upstream)
  • Revision ID: james.westby@ubuntu.com-20091202140343-2732gbkj69g89arq
Tags: 4:4.3.80-0ubuntu1
* New upstream beta release:
  - Add build-depend on shared-desktop-ontologies for nepomuk integration
  - Bump .so versions for libkexiv, libkdcraw and libkipi
  - Update various .install files

Show diffs side-by-side

added added

removed removed

Lines of Context:
libs/libksane/libksane/ksane.h
63
63
        FormatRGB_16_C,     /**< Every pixel consists of three colors in the order Read,
64
64
                             * Grean and Blue, with two bytes per color(no alpha channel).
65
65
                             * The byte order is the one provided by libsane. */
 
66
        FormatBMP,          /**< The image data  is returned as a BMP. */
66
67
        FormatNone = 0xFFFF /**< This enumeration value should never be returned to the user */
67
68
    } ImageFormat;
68
69
 
89
90
    /** This method opens the specified scanner device and adds the scan options to the
90
91
     * KSane widget.
91
92
     * @param device_name is the libsane device name for the scanner to open.
92
 
     * @return 'true' if all goes well and 'false' if the specified scanner can not be opened.
93
 
     */
 
93
     * @return 'true' if all goes well and 'false' if the specified scanner can not be opened. */
94
94
    bool openDevice(const QString &device_name);
95
95
 
96
96
    /** This method closes the currently open scanner device.
97
 
    * @return 'true' if all goes well and 'false' if no device is open.
98
 
    */
 
97
    * @return 'true' if all goes well and 'false' if no device is open. */
99
98
    bool closeDevice();
100
99
    
101
100
    /**
109
108
     * @param bytes_per_line is the number of bytes used per line. This might include padding
110
109
     * and is probably only relevant for 'FormatBlackWhite'.
111
110
     * @param format is the KSane image format of the data.
112
 
     * @param img is the QImage reference to the image to fill.
113
 
     */
114
 
    bool makeQImage(const QByteArray &data,
115
 
                    int width,
116
 
                    int height,
117
 
                    int bytes_per_line,
118
 
                    ImageFormat format,
119
 
                    QImage &img) KDE_DEPRECATED;
 
111
     * @param img is the QImage reference to the image to fill. */
 
112
     KDE_DEPRECATED bool makeQImage(const QByteArray &data,
 
113
                                    int width,
 
114
                                    int height,
 
115
                                    int bytes_per_line,
 
116
                                    ImageFormat format,
 
117
                                    QImage &img);
120
118
    /**
121
119
     * This is a convenience method that can be used to create a QImage from the image data
122
120
     * returned by the imageReady(...) signal. Note: If the image data has 16 bits/color the
128
126
     * @param bytes_per_line is the number of bytes used per line. This might include padding
129
127
     * and is probably only relevant for 'FormatBlackWhite'.
130
128
     * @param format is the KSane image format of the data.
131
 
     * @return This function returns the provided image data as a QImage.
132
 
     */
 
129
     * @return This function returns the provided image data as a QImage. */
133
130
    QImage toQImage(const QByteArray &data,
134
131
                    int width,
135
132
                    int height,
146
143
    /** This method returns the current resolution of the aquired image,
147
144
    * in dots per inch.
148
145
    * @note This function should be called from the slot connected
149
 
    * to the imageReady signal.
 
146
    * to the imageReady signal. The connection should not be queued.
150
147
    * @return the resolution used for scanning or 0.0 on failure. */
151
148
    float currentDPI();
152
149
 
 
150
    /** This method returns the scan area's width in mm
 
151
    * @return Width of the scannable area in mm */
 
152
    float scanAreaWidth();
 
153
 
 
154
    /** This method returns the scan area's height in mm
 
155
    * @return Height of the scannable area in mm */
 
156
    float scanAreaHeight();
 
157
 
 
158
    /** This method sets the selection according to the given points
 
159
    * @note The points are defined with respect to the scan areas top-left corner in mm
 
160
    * @param topLeft Upper left corner of the selection (in mm)
 
161
    * @param bottomRight Lower right corner of the selection (in mm) */
 
162
    void setSelection(QPointF topLeft, QPointF bottomRight);
 
163
    
 
164
    /** This function is used to set the preferred resolution for scanning the preview.
 
165
    * @param dpi is the wanted scan resolution for the preview
 
166
    * @note if the set value is not supported, the cloasest one is used
 
167
    * @note setting the value 0 means that the default calculated value should be used */
 
168
    void setPreviewResolution(float dpi);
 
169
 
153
170
    /** This method reads the available parameters and their values and
154
171
     * returns them in a QMap (Name, value)
155
 
     * @param opts is a QMap with the parameter names and values.
156
 
     */
 
172
     * @param opts is a QMap with the parameter names and values. */
157
173
    void getOptVals(QMap <QString, QString> &opts);
158
174
 
159
175
    /** This method can be used to write many parameter values at once.
160
176
     * @param opts is a QMap with the parameter names and values.
161
 
     * @return This function returns the number of successful writes.
162
 
     */
 
177
     * @return This function returns the number of successful writes. */
163
178
    int setOptVals(const QMap <QString, QString> &opts);
164
179
 
165
180
    /** This function reads one parameter value into a string.
166
181
     * @param optname is the name of the parameter to read.
167
182
     * @param value is the string representation of the value.
168
 
     * @return this function returns true if the read was successful.
169
 
     */
 
183
     * @return this function returns true if the read was successful. */
170
184
    bool getOptVal(const QString &optname, QString &value);
171
185
 
172
186
    /** This function writes one parameter value into a string.
173
187
     * @param optname is the name of the parameter to write.
174
188
     * @param value is the string representation of the value.
175
 
     * @return this function returns true if the write was successful.
176
 
     */
 
189
     * @return this function returns true if the write was successful. */
177
190
    bool setOptVal(const QString &optname, const QString &value);
178
191
 
179
192
    /** This function sets the label on the final scan button
180
 
    * @param scanLabel is the new label for the button.
181
 
    */
 
193
    * @param scanLabel is the new label for the button. */
182
194
    void setScanButtonText(const QString &scanLabel);
183
195
 
184
196
    /** This function sets the label on the preview button
185
 
    * @param scanLabel is the new label for the button.
186
 
    */
 
197
    * @param previewLabel is the new label for the button. */
187
198
    void setPreviewButtonText(const QString &previewLabel);
188
 
    
 
199
 
189
200
    /** This function can be used to enable/disable automatic selections on previews.
190
201
    * The default state is enabled.
191
 
    * @param enable specifies if the auto selection should be turned on or off.
192
 
    */
 
202
    * @param enable specifies if the auto selection should be turned on or off. */
193
203
    void enableAutoSelect(bool enable);
194
 
    
 
204
 
 
205
    /** This function is used to programatically collapse/restore the options.
 
206
    * @param collapse defines the state to set. */
 
207
    void setOptionsCollapsed(bool collapse);
 
208
 
 
209
    /** This function is used hide/show the final scan button.
 
210
    * @param hidden defines the state to set. */
 
211
    void setScanButtonHidden(bool hidden);
 
212
 
195
213
public Q_SLOTS:
196
214
    /** This method can be used to cancel a scan or prevent an automatic new scan. */
197
215
    void scanCancel();
199
217
    /** This method can be used to start a scan (if no GUI is needed).
200
218
    * @note libksane may return one or more images as a result of one invocation of this slot.
201
219
    * If no more images are wanted scanCancel should be called in the slot handling the
202
 
    * imageReady signal.
203
 
    */
 
220
    * imageReady signal. */
204
221
    void scanFinal();
205
222
 
206
223
    Q_SIGNALS:
211
228
     * @param height is the height of the image in pixels.
212
229
     * @param bytes_per_line is the number of bytes used per line. This might include padding
213
230
     * and is probably only relevant for 'FormatBlackWhite'.
214
 
     * @param format is the KSane image format of the data.
215
 
     */
 
231
     * @param format is the KSane image format of the data. */
216
232
    void imageReady(QByteArray &data, int width, int height,
217
233
                    int bytes_per_line, int format);
218
234
 
220
236
     * This signal is emitted when the scanning has ended.
221
237
     * @param status contains a ScanStatus status code.
222
238
     * @param strStatus If an error has occurred this string will contain an error message.
223
 
     * otherwise the string is empty.
224
 
     */
 
239
     * otherwise the string is empty. */
225
240
    void scanDone(int status, const QString &strStatus);
226
241
 
227
242
    /**
228
243
     * This Signal is emitted for progress information during a scan.
229
244
     * The GUI already has a progress bar, but if the GUI is hidden,
230
245
     * this can be used to display a progress bar.
231
 
     * @param percent is the percentage of the scan progress (0-100).
232
 
     */
 
246
     * @param percent is the percentage of the scan progress (0-100). */
233
247
    void scanProgress(int percent);
234
248
 
235
249
private: