KDb

KDbValidator.h
1/* This file is part of the KDE project
2 Copyright (C) 2004, 2006 Jarosław Staniek <staniek@kde.org>
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 */
41class KDB_EXPORT KDbValidator : public QValidator
42{
43 Q_OBJECT
44public:
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
79
80protected:
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
87private:
88 class Private;
89 Private* const d;
90 Q_DISABLE_COPY(KDbValidator)
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*/
119class KDB_EXPORT KDbMultiValidator : public KDbValidator
120{
121 Q_OBJECT
122public:
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
147protected:
148 KDbValidator::Result internalCheck(const QString &valueName, const QVariant &value,
149 QString *message, QString *details) override;
150
151private:
152 class Private;
153 Private* const d;
154 Q_DISABLE_COPY(KDbMultiValidator)
155};
156
157#endif
A validator groupping multiple QValidators.
A validator extending QValidator with offline-checking for value's validity.
void addChildValidator(KDbValidator *v)
Adds a child validator v.
virtual void fixup(QString &input) const const
virtual State validate(QString &input, int &pos) const const=0
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:20:59 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.