File indexing completed on 2024-06-09 16:09:46

0001 /* This file is part of the KDE project
0002    Copyright (C) 2004, 2006 Jarosław Staniek <staniek@kde.org>
0003 
0004    This program is free software; you can redistribute it and/or
0005    modify it under the terms of the GNU Library General Public
0006    License as published by the Free Software Foundation; either
0007    version 2 of the License, or (at your option) any later version.
0008 
0009    This program is distributed in the hope that it will be useful,
0010    but WITHOUT ANY WARRANTY; without even the implied warranty of
0011    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0012    Library General Public License for more details.
0013 
0014    You should have received a copy of the GNU Library General Public License
0015    along with this program; see the file COPYING.  If not, write to
0016    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
0017  * Boston, MA 02110-1301, USA.
0018 */
0019 
0020 #ifndef KDB_TOOLS_VALIDATOR_H
0021 #define KDB_TOOLS_VALIDATOR_H
0022 
0023 #include "kdb_export.h"
0024 
0025 #include <QValidator>
0026 #include <QVariant>
0027 #include <QString>
0028 
0029 //! @short A validator extending QValidator with offline-checking for value's validity
0030 /*!
0031  The offline-checking for value's validity is provided by @ref KDbValidator::check() method.
0032  The validator groups two purposes into one container:
0033  - string validator for line editors (online checking, "on typing");
0034  - offline-checking for QVariant values, reimplementing validate().
0035 
0036  It also offers error and warning messages for check() method.
0037  You may need to reimplement:
0038  -  QValidator::State validate(QString& input, int& pos) const
0039  -  Result check(const QString &valueName, const QVariant &v, QString *message, QString *details)
0040  */
0041 class KDB_EXPORT KDbValidator : public QValidator
0042 {
0043     Q_OBJECT
0044 public:
0045     enum Result { Error = 0, Ok = 1, Warning = 2 };
0046 
0047     explicit KDbValidator(QObject *parent = nullptr);
0048 
0049     ~KDbValidator() override;
0050 
0051     /*! Sets accepting empty values on (true) or off (false).
0052      By default the validator does not accepts empty values. */
0053     void setAcceptsEmptyValue(bool set);
0054 
0055     /*! @return true if the validator accepts empty values
0056       @see setAcceptsEmptyValue() */
0057     bool acceptsEmptyValue() const;
0058 
0059     /*! Checks if value @a value is ok and returns one of @a Result value:
0060      - @a Error is returned on error;
0061      - @a Ok on success;
0062      - @a Warning if there is something to warn about.
0063      In any case except @a Ok, i18n'ed message will be set in @a message
0064      and (optionally) datails are set in @a details, e.g. for use in a message box.
0065      @a valueName can be used to contruct @a message as well, for example:
0066      "[valueName] is not a valid login name".
0067      Depending on acceptsEmptyValue(), immediately accepts empty values or not. */
0068     Result check(const QString &valueName, const QVariant& v, QString *message,
0069                  QString *details);
0070 
0071     /*! This implementation always returns value QValidator::Acceptable. */
0072     QValidator::State validate(QString &input, int &pos) const override;
0073 
0074     //! A generic error/warning message "... value has to be entered."
0075     static const QString messageColumnNotEmpty();
0076 
0077     //! Adds a child validator @a v
0078     void addChildValidator(KDbValidator* v);
0079 
0080 protected:
0081     /* Used by check(), for reimplementation, by default returns @a Error.*/
0082     virtual Result internalCheck(const QString &valueName, const QVariant& value,
0083                                  QString *message, QString *details);
0084 
0085     friend class KDbMultiValidator;
0086 
0087 private:
0088     class Private;
0089     Private* const d;
0090     Q_DISABLE_COPY(KDbValidator)
0091 };
0092 
0093 //! @short A validator groupping multiple QValidators
0094 /*! KDbMultiValidator behaves like normal KDbValidator,
0095  but it allows to add define more than one different validator.
0096  Given validation is successful if every subvalidator accepted given value.
0097 
0098  - acceptsEmptyValue() is used globally here
0099    (no matter what is defined in subvalidators).
0100 
0101  - result of calling check() depends on value of check() returned by subvalidators:
0102    - Error is returned if at least one subvalidator returned Error;
0103    - Warning is returned if at least one subvalidator returned Warning and
0104      no validator returned error;
0105    - Ok is returned only if exactly all subvalidators returned Ok.
0106    - If there is no subvalidators defined, Error is always returned.
0107    - If a given subvalidator is not of class KDbValidator but ust QValidator,
0108      it's assumed it's check() method returned Ok.
0109 
0110  - result of calling validate() (a method implemented for QValidator)
0111    depends on value of validate() returned by subvalidators:
0112    - Invalid is returned if at least one subvalidator returned Invalid
0113    - Intermediate is returned if at least one subvalidator returned Intermediate
0114    - Acceptable is returned if exactly all subvalidators returned Acceptable.
0115    - If there is no subvalidators defined, Invalid is always returned.
0116 
0117  If there are no subvalidators, the multi validator always accepts the input.
0118 */
0119 class KDB_EXPORT KDbMultiValidator : public KDbValidator
0120 {
0121     Q_OBJECT
0122 public:
0123     /*! Constructs multivalidator with no subvalidators defined.
0124      You can add more validators with addSubvalidator(). */
0125     explicit KDbMultiValidator(QObject *parent = nullptr);
0126 
0127     /*! Constructs multivalidator with one validator @a validator.
0128      It will be owned if has no parent defined.
0129      You can add more validators with addSubvalidator(). */
0130     explicit KDbMultiValidator(QValidator *validator, QObject *parent = nullptr);
0131 
0132     ~KDbMultiValidator() override;
0133 
0134     /*! Adds validator @a validator as another subvalidator.
0135      Subvalidator will be owned by this multivalidator if @a owned is true
0136      and its parent is @c nullptr. */
0137     void addSubvalidator(QValidator* validator, bool owned = true);
0138 
0139     /*! Reimplemented to call validate() on subvalidators. */
0140     QValidator::State validate(QString &input, int &pos) const override;
0141 
0142     /*! Calls QValidator::fixup() on every subvalidator.
0143      This may be senseless to use this methog in certain cases
0144      (can return weir results), so think twice before.. */
0145     void fixup(QString &input) const override;
0146 
0147 protected:
0148     KDbValidator::Result internalCheck(const QString &valueName, const QVariant &value,
0149                                        QString *message, QString *details) override;
0150 
0151 private:
0152     class Private;
0153     Private* const d;
0154     Q_DISABLE_COPY(KDbMultiValidator)
0155 };
0156 
0157 #endif