KDb

KDbValidator.h
1 /* This file is part of the KDE project
2  Copyright (C) 2004, 2006 JarosÅ‚aw Staniek <[email protected]>
3 
4  This program is free software; you can redistribute it and/or
5  modify it under the terms of the GNU Library General Public
6  License as published by the Free Software Foundation; either
7  version 2 of the License, or (at your option) any later version.
8 
9  This program is distributed in the hope that it will be useful,
10  but WITHOUT ANY WARRANTY; without even the implied warranty of
11  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12  Library General Public License for more details.
13 
14  You should have received a copy of the GNU Library General Public License
15  along with this program; see the file COPYING. If not, write to
16  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17  * Boston, MA 02110-1301, USA.
18 */
19 
20 #ifndef KDB_TOOLS_VALIDATOR_H
21 #define KDB_TOOLS_VALIDATOR_H
22 
23 #include "kdb_export.h"
24 
25 #include <QValidator>
26 #include <QVariant>
27 #include <QString>
28 
29 //! @short A validator extending QValidator with offline-checking for value's validity
30 /*!
31  The offline-checking for value's validity is provided by @ref KDbValidator::check() method.
32  The validator groups two purposes into one container:
33  - string validator for line editors (online checking, "on typing");
34  - offline-checking for QVariant values, reimplementing validate().
35 
36  It also offers error and warning messages for check() method.
37  You may need to reimplement:
38  - QValidator::State validate(QString& input, int& pos) const
39  - Result check(const QString &valueName, const QVariant &v, QString *message, QString *details)
40  */
41 class KDB_EXPORT KDbValidator : public QValidator
42 {
43  Q_OBJECT
44 public:
45  enum Result { Error = 0, Ok = 1, Warning = 2 };
46 
47  explicit KDbValidator(QObject *parent = nullptr);
48 
49  ~KDbValidator() override;
50 
51  /*! Sets accepting empty values on (true) or off (false).
52  By default the validator does not accepts empty values. */
53  void setAcceptsEmptyValue(bool set);
54 
55  /*! @return true if the validator accepts empty values
56  @see setAcceptsEmptyValue() */
57  bool acceptsEmptyValue() const;
58 
59  /*! Checks if value @a value is ok and returns one of @a Result value:
60  - @a Error is returned on error;
61  - @a Ok on success;
62  - @a Warning if there is something to warn about.
63  In any case except @a Ok, i18n'ed message will be set in @a message
64  and (optionally) datails are set in @a details, e.g. for use in a message box.
65  @a valueName can be used to contruct @a message as well, for example:
66  "[valueName] is not a valid login name".
67  Depending on acceptsEmptyValue(), immediately accepts empty values or not. */
68  Result check(const QString &valueName, const QVariant& v, QString *message,
69  QString *details);
70 
71  /*! This implementation always returns value QValidator::Acceptable. */
72  QValidator::State validate(QString &input, int &pos) const override;
73 
74  //! A generic error/warning message "... value has to be entered."
75  static const QString messageColumnNotEmpty();
76 
77  //! Adds a child validator @a v
78  void addChildValidator(KDbValidator* v);
79 
80 protected:
81  /* Used by check(), for reimplementation, by default returns @a Error.*/
82  virtual Result internalCheck(const QString &valueName, const QVariant& value,
83  QString *message, QString *details);
84 
85  friend class KDbMultiValidator;
86 
87 private:
88  class Private;
89  Private* const d;
91 };
92 
93 //! @short A validator groupping multiple QValidators
94 /*! KDbMultiValidator behaves like normal KDbValidator,
95  but it allows to add define more than one different validator.
96  Given validation is successful if every subvalidator accepted given value.
97 
98  - acceptsEmptyValue() is used globally here
99  (no matter what is defined in subvalidators).
100 
101  - result of calling check() depends on value of check() returned by subvalidators:
102  - Error is returned if at least one subvalidator returned Error;
103  - Warning is returned if at least one subvalidator returned Warning and
104  no validator returned error;
105  - Ok is returned only if exactly all subvalidators returned Ok.
106  - If there is no subvalidators defined, Error is always returned.
107  - If a given subvalidator is not of class KDbValidator but ust QValidator,
108  it's assumed it's check() method returned Ok.
109 
110  - result of calling validate() (a method implemented for QValidator)
111  depends on value of validate() returned by subvalidators:
112  - Invalid is returned if at least one subvalidator returned Invalid
113  - Intermediate is returned if at least one subvalidator returned Intermediate
114  - Acceptable is returned if exactly all subvalidators returned Acceptable.
115  - If there is no subvalidators defined, Invalid is always returned.
116 
117  If there are no subvalidators, the multi validator always accepts the input.
118 */
119 class KDB_EXPORT KDbMultiValidator : public KDbValidator
120 {
121  Q_OBJECT
122 public:
123  /*! Constructs multivalidator with no subvalidators defined.
124  You can add more validators with addSubvalidator(). */
125  explicit KDbMultiValidator(QObject *parent = nullptr);
126 
127  /*! Constructs multivalidator with one validator @a validator.
128  It will be owned if has no parent defined.
129  You can add more validators with addSubvalidator(). */
130  explicit KDbMultiValidator(QValidator *validator, QObject *parent = nullptr);
131 
132  ~KDbMultiValidator() override;
133 
134  /*! Adds validator @a validator as another subvalidator.
135  Subvalidator will be owned by this multivalidator if @a owned is true
136  and its parent is @c nullptr. */
137  void addSubvalidator(QValidator* validator, bool owned = true);
138 
139  /*! Reimplemented to call validate() on subvalidators. */
140  QValidator::State validate(QString &input, int &pos) const override;
141 
142  /*! Calls QValidator::fixup() on every subvalidator.
143  This may be senseless to use this methog in certain cases
144  (can return weir results), so think twice before.. */
145  void fixup(QString &input) const override;
146 
147 protected:
148  KDbValidator::Result internalCheck(const QString &valueName, const QVariant &value,
149  QString *message, QString *details) override;
150 
151 private:
152  class Private;
153  Private* const d;
155 };
156 
157 #endif
QValidator::State validate(QString &input, int &pos) const override
virtual void fixup(QString &input) const const
virtual QValidator::State validate(QString &input, int &pos) const const=0
A validator groupping multiple QValidators.
Definition: KDbValidator.h:119
A validator extending QValidator with offline-checking for value's validity.
Definition: KDbValidator.h:41
Q_DISABLE_COPY(Class)
QString message
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Jun 4 2023 04:06:23 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.