File indexing completed on 2024-03-24 15:48:03

0001 /* This file is part of the KDE Project
0002    Copyright (C) 2000 Klaas Freitag <freitag@suse.de>
0003    Copyright (C) 2010 Jonathan Marten <jjm@keelhaul.me.uk>
0004 
0005    This library is free software; you can redistribute it and/or
0006    modify it under the terms of the GNU Library General Public
0007    License as published by the Free Software Foundation; either
0008    version 2 of the License, or (at your option) any later version.
0009 
0010    This library is distributed in the hope that it will be useful,
0011    but WITHOUT ANY WARRANTY; without even the implied warranty of
0012    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0013    Library General Public License for more details.
0014 
0015    You should have received a copy of the GNU Library General Public License
0016    along with this library; see the file COPYING.LIB.  If not, write to
0017    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
0018    Boston, MA 02110-1301, USA.
0019 */
0020 
0021 #ifndef KSCANCONTROLS_H
0022 #define KSCANCONTROLS_H
0023 
0024 #include "kookascan_export.h"
0025 
0026 #include <qwidget.h>
0027 
0028 class QHBoxLayout;
0029 class QToolButton;
0030 class QSpinBox;
0031 class QComboBox;
0032 class QCheckBox;
0033 class QSlider;
0034 class QLineEdit;
0035 class QGroupBox;
0036 class QPushButton;
0037 
0038 class KUrlRequester;
0039 
0040 /**
0041  * An abstract base class representing a GUI for a single scan
0042  * parameter control.  All scanner controls are one of the subclasses
0043  * of this, their precise appearance and operation depending on the
0044  * SANE type of the parameter.
0045  */
0046 
0047 class KScanControl : public QWidget
0048 {
0049     Q_OBJECT
0050 
0051 public:
0052     /**
0053      * The internal type of the control (regardless of GUI appearance).
0054      *
0055      * A @c Text control maintains a string value, a @c Number control a
0056      * numeric value.  @c Group and @c Button controls do not have values.
0057      */
0058     enum ControlType {
0059         Text,
0060         Number,
0061         Group,
0062         Button
0063     };
0064 
0065     /**
0066      * Creates a control.
0067      *
0068      * @param parent The parent widget
0069      * @param text Text label for control
0070      */
0071     explicit KScanControl(QWidget *parent, const QString &text);
0072 
0073     /**
0074      * Destroys the control and any child widgets that it uses.
0075      */
0076     virtual ~KScanControl();
0077 
0078     /**
0079      * Control type.
0080      *
0081      * @return the control type
0082      * @see ControlType
0083      */
0084     virtual KScanControl::ControlType type() const = 0;
0085 
0086     /**
0087      * Set the control's text value, for controls of type @c Text.
0088      * Ignored for controls of type @c Number or @c Group.
0089      *
0090      * @param text The new text value
0091      */
0092     virtual void setText(const QString &text);
0093 
0094     /**
0095      * Get the control's current text value.
0096      *
0097      * @return the text value, or @c QString() for a @c Number
0098      * or @c Group control.
0099      */
0100     virtual QString text() const;
0101 
0102     /**
0103      * Set the control's numeric value, for controls of type @c Number.
0104      * Ignored for controls of type @c Text or @c Group.
0105      *
0106      * @param val The new numeric value
0107      */
0108     virtual void setValue(int val);
0109 
0110     /**
0111      * Get the control's current numeric value.
0112      *
0113      * @return the numeric value, or @c 0 for a @c Text
0114      * or @c Group control.
0115      */
0116     virtual int value() const;
0117 
0118     /**
0119      * Get a descriptive label text for the control.
0120      *
0121      * For all controls except check boxes, this is the original @p text
0122      * parameter to the constructor with a ":" appended.  For a check box,
0123      * this is null (a check box has its own label in the usual place,
0124      * on the right).
0125      *
0126      * @return the label string
0127      */
0128     virtual QString label() const;
0129 
0130 protected:
0131     QHBoxLayout *mLayout;
0132     QString mText;
0133 
0134 signals:
0135     /**
0136      * The setting of a @c Text control has changed.
0137      *
0138      * @param text The new text setting
0139      */
0140     void settingChanged(const QString &text);
0141 
0142     /**
0143      * The setting of a @c Number control has changed.
0144      *
0145      * @param val The new numeric setting
0146      */
0147     void settingChanged(int val);
0148 
0149     /**
0150      * The Return/Enter key has been pressed in a @c Text or
0151      * @c Number entry field, or a @c Button control has been pressed.
0152      * @c Group control types do not provide this signal (nor either of
0153      * the above).
0154      */
0155     void returnPressed();
0156 };
0157 
0158 /**
0159  * A slider combined with a spin box, providing the possibility of either
0160  * selecting a value with the slider or entering a precise value in the
0161  * spin box.  There can also optionally be a 'reset' button which returns
0162  * the setting to a default value.
0163  *
0164  * @see QSlider, QSpinBox
0165  */
0166 
0167 class KOOKASCAN_EXPORT KScanSlider : public KScanControl
0168 {
0169     Q_OBJECT
0170 
0171 public:
0172     /**
0173      * Creates the control.
0174      *
0175      * @param parent parent widget
0176      * @param text descriptive label for the control
0177      * @param min minimum slider value
0178      * @param max maximum slider value
0179      * @param haveStdButt if @c true, the 'reset' button will be present
0180      * @param stdValue the value to which the 'reset' button resets the control
0181      */
0182     Q_DECL_DEPRECATED_X("Use KScanSlider(QWidget *,const QString &, bool) then setRange()")
0183     KScanSlider(QWidget *parent, const QString &text,
0184                 double min, double max,
0185                 bool haveStdButt = false, int stdValue = 0);
0186 
0187     /**
0188      * Creates the control.
0189      *
0190      * @param parent parent widget
0191      * @param text descriptive label for the control
0192      * @param haveStdButt if @c true, the 'reset' button will be present
0193      */
0194     KScanSlider(QWidget *parent, const QString &text, bool haveStdButt = false);
0195 
0196     KScanControl::ControlType type() const override     { return (KScanControl::Number); }
0197 
0198     int value() const override;
0199     void setValue(int val) override;
0200     QSpinBox *spinBox() const                   { return (mSpinbox); }
0201 
0202     /**
0203      * Sets the allowed range and step for the slider.
0204      *
0205      * @param min minimum slider value
0206      * @param max maximum slider value
0207      * @param step value step, or -1 for a default setting
0208      * @param stdValue the value to which the 'reset' button resets the control
0209      *
0210      * @note The current control value is set to @p stdValue.
0211      */
0212     void setRange(int min, int max, int step = -1, int stdValue = 0);
0213 
0214 protected slots:
0215     void slotSliderSpinboxChange(int val);
0216     void slotRevertValue();
0217 
0218 private:
0219     void init(bool haveStdButt);
0220 
0221 private:
0222     QSlider *mSlider;
0223     QSpinBox *mSpinbox;
0224     QToolButton *mStdButt;
0225 
0226     int mValue;
0227     int mStdValue;
0228 };
0229 
0230 /**
0231  * A free text entry field.
0232  *
0233  * @see QLineEdit
0234  */
0235 
0236 class KOOKASCAN_EXPORT KScanStringEntry : public KScanControl
0237 {
0238     Q_OBJECT
0239 
0240 public:
0241     /**
0242      * Creates the control.
0243      *
0244      * @param parent parent widget
0245      * @param text descriptive label for the control
0246      */
0247     KScanStringEntry(QWidget *parent, const QString &text);
0248 
0249     KScanControl::ControlType type() const override
0250     {
0251         return (KScanControl::Text);
0252     }
0253 
0254     QString text() const override;
0255     void setText(const QString &text) override;
0256 
0257 private:
0258     QLineEdit *mEntry;
0259 };
0260 
0261 /**
0262  * A numeric entry field.
0263  *
0264  * @see QLineEdit
0265  */
0266 
0267 class KOOKASCAN_EXPORT KScanNumberEntry : public KScanControl
0268 {
0269     Q_OBJECT
0270 
0271 public:
0272     /**
0273      * Creates the control.
0274      *
0275      * @param parent parent widget
0276      * @param text descriptive label for the control
0277      */
0278     KScanNumberEntry(QWidget *parent, const QString &text);
0279 
0280     KScanControl::ControlType type() const override
0281     {
0282         return (KScanControl::Number);
0283     }
0284 
0285     int value() const override;
0286     void setValue(int i) override;
0287 
0288 protected slots:
0289     void slotTextChanged(const QString &s);
0290 
0291 private:
0292     QLineEdit *mEntry;
0293 };
0294 
0295 /**
0296  * A check box for an on/off option.
0297  *
0298  * @see QCheckBox
0299  */
0300 
0301 class KOOKASCAN_EXPORT KScanCheckbox : public KScanControl
0302 {
0303     Q_OBJECT
0304 
0305 public:
0306     /**
0307      * Creates the control.
0308      *
0309      * @param parent parent widget
0310      * @param text descriptive label for the control
0311      */
0312     KScanCheckbox(QWidget *parent, const QString &text);
0313 
0314     KScanControl::ControlType type() const override
0315     {
0316         return (KScanControl::Number);
0317     }
0318 
0319     int value() const override;
0320     void setValue(int i) override;
0321 
0322     QString label() const override;
0323 
0324 private:
0325     QCheckBox *mCheckbox;
0326 };
0327 
0328 /**
0329  * A combo box for a list of options.
0330  *
0331  * @see QComboBox
0332  */
0333 
0334 class KOOKASCAN_EXPORT KScanCombo : public KScanControl
0335 {
0336     Q_OBJECT
0337 
0338 public:
0339     /**
0340      * Creates the control.
0341      *
0342      * @param parent parent widget
0343      * @param text descriptive label for the control
0344      */
0345     KScanCombo(QWidget *parent, const QString &text);
0346 
0347     KScanControl::ControlType type() const override
0348     {
0349         return (KScanControl::Text);
0350     }
0351 
0352     QString text() const override;
0353     void setText(const QString &text) override;
0354     void setValue(int i) override;
0355 
0356     /**
0357      * Populate the combo box with a list of values.
0358      *
0359      * @param list list of options to fill the combo box
0360      */
0361     void setList(const QList<QByteArray> &list);
0362 
0363     /**
0364      * Get the text at a specified index in the combo box.
0365      *
0366      * @param i the requested index
0367      * @return the text at that index
0368      */
0369     QString textAt(int i) const;
0370 
0371     /**
0372      * Count how many combo box entries there are.
0373      *
0374      * @return the number of entries
0375      */
0376     int count() const;
0377 
0378     /**
0379      * Set an icon for an item in the combo box.
0380      *
0381      * @param pix the pixmap to set
0382      * @param ent the entry for which the pixmap should be set
0383      */
0384     void setIcon(const QIcon &pix, const char *ent);
0385 
0386 protected slots:
0387     void slotActivated(int i);
0388 
0389 private:
0390     QComboBox *mCombo;
0391 };
0392 
0393 /**
0394  * A standard URL requester for a file name.
0395  *
0396  * @see KUrlRequester
0397  */
0398 
0399 class KOOKASCAN_EXPORT KScanFileRequester : public KScanControl
0400 {
0401     Q_OBJECT
0402 
0403 public:
0404     /**
0405      * Creates the control.
0406      *
0407      * @param parent parent widget
0408      * @param text descriptive label for the control
0409      */
0410     KScanFileRequester(QWidget *parent, const QString &text);
0411 
0412     KScanControl::ControlType type() const override
0413     {
0414         return (KScanControl::Text);
0415     }
0416 
0417     QString text() const override;
0418     void setText(const QString &text) override;
0419 
0420 private:
0421     KUrlRequester *mEntry;
0422 };
0423 
0424 /**
0425  * A line separator between option groups.
0426  *
0427  * @see QGroupBox
0428  */
0429 
0430 class KOOKASCAN_EXPORT KScanGroup : public KScanControl
0431 {
0432     Q_OBJECT
0433 
0434 public:
0435     /**
0436      * Creates the control.
0437      *
0438      * @param parent parent widget
0439      * @param text descriptive label for the control
0440      */
0441     KScanGroup(QWidget *parent, const QString &text);
0442 
0443     KScanControl::ControlType type() const override
0444     {
0445         return (KScanControl::Group);
0446     }
0447 
0448     QString label() const override;
0449 
0450 private:
0451     QGroupBox *mGroup;
0452 };
0453 
0454 /**
0455  * A button to perform an action.
0456  *
0457  * @see QPushButton
0458  */
0459 
0460 class KOOKASCAN_EXPORT KScanPushButton : public KScanControl
0461 {
0462     Q_OBJECT
0463 
0464 public:
0465     /**
0466      * Creates the control.
0467      *
0468      * @param parent parent widget
0469      * @param text descriptive label for the control
0470      */
0471     KScanPushButton(QWidget *parent, const QString &text);
0472 
0473     KScanControl::ControlType type() const override
0474     {
0475         return (KScanControl::Button);
0476     }
0477 
0478     QString label() const override;
0479 
0480 private:
0481     QPushButton *mButton;
0482 };
0483 
0484 #endif                          // KSCANCONTROLS_H