File indexing completed on 2024-04-14 04:37:17

0001 /*
0002  * SPDX-FileCopyrightText: 2021 Alexander Stippich <a.stippich@gmx.net>
0003  *
0004  * SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
0005  */
0006 
0007 #ifndef KSANE_COREOPTION_H
0008 #define KSANE_COREOPTION_H
0009 
0010 #include <memory>
0011 
0012 // Qt includes
0013 
0014 #include "ksanecore_export.h"
0015 #include <QObject>
0016 #include <QString>
0017 #include <QVariant>
0018 
0019 namespace KSaneCore
0020 {
0021 
0022 class OptionPrivate;
0023 
0024 /**
0025  * A wrapper class providing access to the internal KSaneBaseOption
0026  * to access all options provided by KSANECore/SANE
0027  */
0028 class KSANECORE_EXPORT Option : public QObject
0029 {
0030     Q_OBJECT
0031 
0032 public:
0033     /** This enumeration describes the type of the option. */
0034     enum OptionType { TypeDetectFail, TypeBool, TypeInteger, TypeDouble, TypeValueList, TypeString, TypeGamma, TypeAction };
0035 
0036     Q_ENUM(OptionType)
0037 
0038     /** This enumeration describes the unit of the value of the option,
0039      * if any. */
0040     enum OptionUnit { UnitNone, UnitPixel, UnitBit, UnitMilliMeter, UnitDPI, UnitPercent, UnitMicroSecond, UnitSecond };
0041 
0042     Q_ENUM(OptionUnit)
0043 
0044     /** This enumeration describes the current statue of the value of
0045      * the option, indicating if this option should be displayed or not. */
0046     enum OptionState { StateHidden, StateDisabled, StateActive };
0047 
0048     Q_ENUM(OptionState)
0049 
0050     explicit Option(QObject *parent = nullptr);
0051     ~Option() override;
0052 
0053     /** This function returns the internal name of the option
0054      * @return the internal name */
0055     QString name() const;
0056 
0057     /** This function returns the translated title of the option
0058      * @return the title */
0059     QString title() const;
0060 
0061     /** This function returns a more verbose, translated description
0062      * of the option.
0063      * @return the description */
0064     QString description() const;
0065 
0066     /** This function the type of the option as determined by KSANECore.
0067      * Each type provides a different implementation for different
0068      * variable types, e.g. integer, float or string.
0069      * @return the type of option the of value OptionType */
0070     OptionType type() const;
0071 
0072     /** This function returns the state of the option indicating
0073      * if the function is disabled or should be hidden.
0074      * @return the state of option the of value OptionState */
0075     OptionState state() const;
0076 
0077     /** This function returns the currently active value for the option.
0078      * @return the current value */
0079     QVariant value() const;
0080 
0081     /** This function returns the minimum value for the option.
0082      * Returns an empty QVariant if this value is not applicable
0083      * for the option type.
0084      * @return the minimum value */
0085     QVariant minimumValue() const;
0086 
0087     /** This function returns the maximum value for the option.
0088      * Returns an empty QVariant if this value is not applicable
0089      * for the option type.
0090      * @return the maximum value */
0091     QVariant maximumValue() const;
0092 
0093     /** This function returns the step value for the option.
0094      * Returns an empty QVariant if this value is not applicable
0095      * for the option type.
0096      * @return the step value */
0097     QVariant stepValue() const;
0098 
0099     /** This function returns the list of possible values if the option
0100      * is of type OptionType::TypeValueList. The list may contain
0101      * formatted or translated values.
0102      * @return a list with all possible values */
0103     QVariantList valueList() const;
0104 
0105     /** This function returns the list of possible values if the option
0106      * is of type OptionType::TypeValueList. The list contains the raw
0107      * internal values without any formatting or translation.
0108      * @return a list with all possible internal values */
0109     QVariantList internalValueList() const;
0110 
0111     /** This function returns an enum specifying whether the values
0112      * of the option have a unit, e.g. mm, px, etc.
0113      * @return unit of value CoreOptionUnit */
0114     OptionUnit valueUnit() const;
0115 
0116     /** This function returns the size of the values of the option
0117      * of type CoreOptionType::TypeValueList.
0118      * If the size is greater than one, value() and setValue()
0119      * return and expect a QVariantList with an accordingly number
0120      * of elements. If the option is a CoreOptionType::TypeString,
0121      * the size represents the number of characters in the string.
0122      * @return the number of elements */
0123     int valueSize() const;
0124 
0125     /** This function temporarily stores the current value
0126      * in a member variable. */
0127     bool storeCurrentData();
0128 
0129     /** This function restores the previously saved value
0130      * and makes it the current value. */
0131     bool restoreSavedData();
0132 
0133 Q_SIGNALS:
0134     /** This signal is emitted when the option is reloaded, which may
0135      * happen if the value of other options has changed. */
0136     void optionReloaded();
0137 
0138     /** This signal is emitted when the current value is updated,
0139      * either when a user sets a new value or by a reload by the backend. */
0140     void valueChanged(const QVariant &value);
0141 
0142 public Q_SLOTS:
0143 
0144     /** This slot allows to change the current value of the option.
0145      * @param value the new value of option inside a QVariant.
0146      * In case the variant cannot be cast to a value suitable for
0147      * the specific option, the value is discarded. */
0148     bool setValue(const QVariant &value);
0149 
0150 protected:
0151     std::unique_ptr<KSaneCore::OptionPrivate> d;
0152 };
0153 
0154 } // namespace KSaneCore
0155 
0156 #endif // KSANE_COREOPTION_H