File indexing completed on 2022-11-29 19:02:24

0001 /* This file is part of the KDE project
0002    Copyright (C) 2002 Lucijan Busch <lucijan@gmx.at>
0003    Copyright (C) 2002 Joseph Wenninger <jowenn@kde.org>
0004    Copyright (C) 2003-2017 Jarosław Staniek <staniek@kde.org>
0005 
0006    This library is free software; you can redistribute it and/or
0007    modify it under the terms of the GNU Library General Public
0008    License as published by the Free Software Foundation; either
0009    version 2 of the License, or (at your option) any later version.
0010 
0011    This library is distributed in the hope that it will be useful,
0012    but WITHOUT ANY WARRANTY; without even the implied warranty of
0013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0014    Library General Public License for more details.
0015 
0016    You should have received a copy of the GNU Library General Public License
0017    along with this library; see the file COPYING.LIB.  If not, write to
0018    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
0019  * Boston, MA 02110-1301, USA.
0020  */
0021 
0022 #ifndef KDB_FIELD_H
0023 #define KDB_FIELD_H
0024 
0025 #include <QPair>
0026 #include <QVector>
0027 #include <QStringList>
0028 #include <QHash>
0029 #include <QCoreApplication>
0030 
0031 #include "KDbUtils.h"
0032 
0033 class KDbTableSchema;
0034 class KDbQuerySchema;
0035 class KDbFieldList;
0036 class KDbExpression;
0037 
0038 //! Meta-data for a field
0039 /*! KDbField provides information about single database field.
0040 
0041  KDbField class has defined following members:
0042  - name
0043  - type
0044  - database constraints
0045  - additional options
0046  - maxLength (makes sense mostly for string types)
0047  - maxLengthStrategy (makes sense mostly for string types)
0048  - precision (for floating-point type)
0049  - defaultValue
0050  - caption (user readable name that can be e.g. translated)
0051  - description (user readable name additional text, can be useful for developers)
0052  - defaultWidth (a hint for displaying in tabular mode or as text box)
0053 
0054  KDbField can also have assigned expression (see KDbExpression class,
0055  and expression() method).
0056 
0057  Note that aliases for fields are defined within query, not in KDbField object,
0058  because the same field can be used in different queries with different alias.
0059 
0060  Notes for advanced use: KDbField obeject is designed to be owned by a parent object.
0061  Such a parent object can be KDbTableSchema, if the field defines single table column,
0062  or KDbQuerySchema, if the field defines an expression (KDbExpression class).
0063 
0064  Using expression class for fields allos to define expressions within queries like
0065  "SELECT AVG(price) FROM products"
0066 
0067  You can choose whether your field is owned by query or table,
0068  using appropriate constructor, or using parameterless constructor and
0069  calling setTable() or setQuery() later.
0070 */
0071 class KDB_EXPORT KDbField
0072 {
0073     Q_GADGET
0074     Q_FLAGS(Constraints Constraint Options Option)
0075     Q_DECLARE_TR_FUNCTIONS(KDbField)
0076 public:
0077     typedef KDbUtils::AutodeletedList<KDbField*> List; //!< list of fields
0078     typedef QVector<KDbField*> Vector; //!< vector of fields
0079     typedef QList<KDbField*>::ConstIterator ListIterator; //!< iterator for list of fields
0080     typedef QPair<KDbField*, KDbField*> Pair; //!< fields pair
0081     typedef QList<Pair> PairList; //!< list of fields pair
0082 
0083     /*! Unified (most common used) types of fields. */
0084     enum Type {
0085         //-- Normal types:
0086         InvalidType = 0, /*!< Unsupported/Unimplemented type */
0087         Byte = 1,        /*!< 1 byte, signed or unsigned */
0088         FirstType = 1, /*! First type */
0089         ShortInteger = 2,/*!< 2 bytes, signed or unsigned */
0090         Integer = 3,     /*!< 4 bytes, signed or unsigned */
0091         BigInteger = 4,  /*!< 8 bytes, signed or unsigned */
0092         Boolean = 5,     /*!< 0 or 1 */
0093         Date = 6,        /*!< */
0094         DateTime = 7,    /*!< */
0095         Time = 8,        /*!< */
0096         Float = 9,       /*!< 4 bytes */
0097         Double = 10,     /*!< 8 bytes */
0098         Text = 11,       /*!< Other name: Varchar */
0099         LongText = 12,   /*!< Other name: Memo */
0100         BLOB = 13,       /*!< Large binary object */
0101 
0102         LastType = 13,   /*!< This line should be at the end of the list of types! */
0103 
0104         Null = 128,       /*!< Used for fields that are "NULL" expressions. */
0105 
0106         //-- Special, internal types:
0107         Asterisk = 129,  /*!< Used in KDbQueryAsterisk subclass objects only,
0108                              not used in table definitions,
0109                              but only in query definitions */
0110         Enum = 130,      /*!< An integer internal with a string list of hints */
0111         Map = 131,       /*!< Mapping from string to string list (more generic than Enum) */
0112         Tuple = 132,     /*!< A list of values (e.g. arguments of a function) */
0113         LastSpecialType = Tuple /*!< This line should be at the end of the list of special types! */
0114     };
0115     Q_ENUM(Type)
0116 
0117     /*! Type groups for fields. */
0118     enum TypeGroup {
0119         InvalidGroup = 0,
0120         TextGroup = 1,
0121         IntegerGroup = 2,
0122         FloatGroup = 3,
0123         BooleanGroup = 4,
0124         DateTimeGroup = 5,
0125         BLOBGroup = 6, /* large binary object */
0126 
0127         LastTypeGroup = 6 // This line should be at the end of the enum!
0128     };
0129     Q_ENUM(TypeGroup)
0130 
0131     /*! Possible constraints defined for a field. */
0132     enum Constraint {
0133         NoConstraints = 0,
0134         AutoInc = 1,
0135         Unique = 2,
0136         PrimaryKey = 4,
0137         ForeignKey = 8,
0138         NotNull = 16,
0139         NotEmpty = 32, //!< only legal for string-like and blob fields
0140         Indexed = 64
0141     };
0142     Q_DECLARE_FLAGS(Constraints, Constraint)
0143 
0144     /*! Possible options defined for a field. */
0145     enum Option {
0146         NoOptions = 0,
0147         Unsigned = 1
0148     };
0149     Q_DECLARE_FLAGS(Options, Option)
0150 
0151     /*! Creates a database field as a child of @a tableSchema table.
0152      No other properties are set (even the name), so these should be set later. */
0153     explicit KDbField(KDbTableSchema *tableSchema);
0154 
0155     /*! Creates a database field.
0156      maxLength property is set to 0 (unlimited length).
0157      No other properties are set (even the name), so these should be set later. */
0158     KDbField();
0159 
0160     /*! Creates a database field with specified properties.
0161      For meaning of @a maxLength argument please refer to setMaxLength(). */
0162     KDbField(const QString &name, Type type, Constraints constr = NoConstraints,
0163              Options options = NoOptions, int maxLength = 0, int precision = 0,
0164              const QVariant &defaultValue = QVariant(), const QString &caption = QString(),
0165              const QString &description = QString());
0166 
0167     /*! Constructs a deep copy of field @a f. */
0168     KDbField(const KDbField &f);
0169 
0170     virtual ~KDbField();
0171 
0172     //! @return parent for this field (table, query, etc.)
0173     KDbFieldList *parent();
0174 
0175     //! @overload
0176     const KDbFieldList *parent() const;
0177 
0178     //! @return number of normal types available, i.e. types > InvalidType and <= LastType.
0179     static int typesCount();
0180 
0181     //! @return number of special types available (Asterisk, Enum, etc.), that means
0182     static int specialTypesCount();
0183 
0184     //! @return number of type groups available
0185     static int typeGroupsCount();
0186 
0187     //! Converts type @a type to QVariant equivalent as accurate as possible
0188     /*! Only normal types are supported.
0189      @see typesCount() specialTypesCount() */
0190     static QVariant::Type variantType(Type type);
0191 
0192     //! Converts value @a value to variant corresponding to type @a type.
0193     /*! Only normal types are supported.
0194      If converting is not possible a null value is returned. */
0195     static QVariant convertToType(const QVariant &value, Type type);
0196 
0197     //! @return a translated type name for @a type
0198     /*! @a type has to be an element from KDbField::Type, not greater than KDbField::LastType.
0199      Only normal types and KDbField::Null are supported.
0200      For unsupported types empty string is returned. */
0201     //! @see typesCount() specialTypesCount()
0202     static QString typeName(Type type);
0203 
0204     //! @return list of all available translated names of normal types
0205     /*! The first element of the list is the name of KDbField::InvalidType, the last one
0206      is a name of KDbField::LastType.
0207      @see typesCount() specialTypesCount() */
0208     static QStringList typeNames();
0209 
0210     //! @return a nontranslated type string for @a type
0211     /*! For example returns "Integer" for KDbType::Integer.
0212         @a type has to be an element from KDbField::Type, not greater than KDbField::LastType;
0213         KDbField::Null is also supported.
0214         For unsupported types empty string is returned. */
0215     static QString typeString(Type type);
0216 
0217     //! @return type for a given nontranslated type string @a typeString
0218     /*! For example returns KDbType::Integer for "Integer".
0219         @a typeString has to be name of type not greater than KDbField::LastType;
0220         KDbField::Null is also supported.
0221         For unsupported value KDbField::InvalidType is returned. */
0222     static Type typeForString(const QString& typeString);
0223 
0224     //! @return type group for a given nontranslated type group @a typeGroupString
0225     /*! For example returns KDbField::TextGroup for "TextGroup" string.
0226         For unsupported value KDbField::InvalidGroup is returned. */
0227     static TypeGroup typeGroupForString(const QString& typeGroupString);
0228 
0229     //! @return group for @a type
0230     /*! For example returns KDbField::TextGroup for KDbField::Text type.
0231         @a type has to be an element from KDbField::Type, not greater than KDbField::LastType.
0232         For unsupported type KDbField::InvalidGroup is returned. */
0233     static TypeGroup typeGroup(Type type);
0234 
0235     //! @return a translated group name for @a typeGroup
0236     static QString typeGroupName(TypeGroup typeGroup);
0237 
0238     //! @return list of all available translated type group names
0239     /*! The first element of the list is the name of KDbField::InvalidGroup, the last one
0240         is a name of KDbField::LastTypeGroup. */
0241     static QStringList typeGroupNames();
0242 
0243     //! @return a nontranslated type group string for @a typeGroup, e.g. "IntegerGroup" for IntegerGroup type
0244     static QString typeGroupString(TypeGroup typeGroup);
0245 
0246     /*! @return the name of this field */
0247     QString name() const;
0248 
0249     /*! @return table schema of table that owns this field
0250      or null if it has no table assigned.
0251      @see query() */
0252     KDbTableSchema* table();
0253 
0254     //! @overload KDbTableSchema* table()
0255     const KDbTableSchema* table() const;
0256 
0257     /*! Sets @a table schema of table that owns this field.
0258      This does not adds the field to @a table object.
0259      You do not need to call this method by hand.
0260      Call KDbTableSchema::addField(KDbField *field) instead.
0261      @see setQuery() */
0262     void setTable(KDbTableSchema *table);
0263 
0264     /*! For special use when the field defines expression.
0265      @return query schema of query that owns this field
0266      or null if it has no query assigned.
0267      @see table() */
0268     KDbQuerySchema* query();
0269 
0270     //! @overload KDbQuerySchema* query()
0271     const KDbQuerySchema* query() const;
0272 
0273     /*! For special use when field defines expression.
0274      Sets @a query schema of query that owns this field.
0275      This does not adds the field to @a query object.
0276      You do not need to call this method by hand.
0277      Call KDbQuerySchema::addField() instead.
0278      @see setQuery() */
0279     void setQuery(KDbQuerySchema *query);
0280 
0281     /*! @return true if the field is autoincrement (e.g. integer/numeric) */
0282     inline bool isAutoIncrement() const {
0283         return constraints() & AutoInc;
0284     }
0285 
0286     /*! @return true if the field is member of single-field primary key */
0287     inline bool isPrimaryKey() const {
0288         return constraints() & PrimaryKey;
0289     }
0290 
0291     /*! @return true if the field is member of single-field unique key */
0292     inline bool isUniqueKey() const {
0293         return constraints() & Unique;
0294     }
0295 
0296     /*! @return true if the field is member of single-field foreign key */
0297     inline bool isForeignKey() const {
0298         return constraints() & ForeignKey;
0299     }
0300 
0301     /*! @return true if the field is not allowed to be null */
0302     inline bool isNotNull() const {
0303         return constraints() & NotNull;
0304     }
0305 
0306     /*! @return true if the field is not allowed to be null */
0307     inline bool isNotEmpty() const {
0308         return constraints() & NotEmpty;
0309     }
0310 
0311     /*! @return true if the field is indexed using single-field database index. */
0312     inline bool isIndexed() const {
0313         return constraints() & Indexed;
0314     }
0315 
0316     /*! @return true if the field is of any numeric type (integer or floating point) */
0317     inline bool isNumericType() const {
0318         return KDbField::isNumericType(type());
0319     }
0320 
0321     /*! Static version of isNumericType() method
0322      @return true if the field is of any numeric type (integer or floating point)*/
0323     static bool isNumericType(Type type);
0324 
0325     /*! @return true if the field is of any integer type */
0326     inline bool isIntegerType() const {
0327         return KDbField::isIntegerType(type());
0328     }
0329 
0330     /*! Static version of isIntegerType() method
0331      @return true if the field is of any integer type */
0332     static bool isIntegerType(Type type);
0333 
0334     /*! @return true if the field is of any floating point numeric type */
0335     inline bool isFPNumericType() const {
0336         return KDbField::isFPNumericType(type());
0337     }
0338 
0339     /*! static version of isFPNumericType() method
0340      @return true if the field is of any floating point numeric type */
0341     static bool isFPNumericType(Type type);
0342 
0343     /*! @return true if the field is of any date or time related type */
0344     inline bool isDateTimeType() const {
0345         return KDbField::isDateTimeType(type());
0346     }
0347 
0348     /*! Static version of isDateTimeType() method
0349      @return true if the field is of any date or time related type */
0350     static bool isDateTimeType(Type type);
0351 
0352     /*! @return true if the field is of any text type */
0353     inline bool isTextType() const {
0354         return KDbField::isTextType(type());
0355     }
0356 
0357     /*! Static version of isTextType() method
0358      @return true if the field is of any text type */
0359     static bool isTextType(Type type);
0360 
0361     /*! @return options defined for this field. */
0362     Options options() const;
0363 
0364     /*! Sets options for this field. */
0365     void setOptions(Options options);
0366 
0367     //! Converts field's type to QVariant equivalent as accurate as possible
0368     inline QVariant::Type variantType() const {
0369         return variantType(type());
0370     }
0371 
0372     /*! @return a type for this field. If there's expression assigned,
0373      type of the expression (after evaluation) is returned instead. */
0374     Type type() const;
0375 
0376     //! @return a translated type name for this field
0377     inline QString typeName() const {
0378         return KDbField::typeName(type());
0379     }
0380 
0381     //! @return type group for this field
0382     inline TypeGroup typeGroup() const {
0383         return KDbField::typeGroup(type());
0384     }
0385 
0386     //! @return a translated type group name for this field
0387     inline QString typeGroupName() const {
0388         return KDbField::typeGroupName(typeGroup());
0389     }
0390 
0391     //! @return a type string for this field,
0392     //! for example "Integer" string for KDbField::Integer type.
0393     inline QString typeString() const {
0394         return KDbField::typeString(type());
0395     }
0396 
0397     //! @return a type group string for this field,
0398     //! for example "Integer" string for KDbField::IntegerGroup.
0399     inline QString typeGroupString() const {
0400         return KDbField::typeGroupString(typeGroup());
0401     }
0402 
0403     /*! @return (optional) subtype for this field.
0404      Subtype is a string providing additional hint for field's type.
0405      E.g. for BLOB type, it can be a MIME type or certain QVariant type name,
0406      for example: "QPixmap", "QColor" or "QFont" */
0407     QString subType() const;
0408 
0409     /*! Sets (optional) subtype for this field.
0410      @see subType() */
0411     void setSubType(const QString& subType);
0412 
0413     //! @return default value for this field. Null value means there
0414     //! is no default value declared. The variant value is compatible with field's type.
0415     QVariant defaultValue() const;
0416 
0417     /*! @return default maximum length of text.
0418         Default is 0, i.e unlimited length (if the engine supports it). */
0419     static int defaultMaxLength();
0420 
0421     /*! Sets default maximum length of text. 0 means unlimited length,
0422         greater than 0 means specific maximum length. */
0423     static void setDefaultMaxLength(int maxLength);
0424 
0425     /*! Strategy for defining maximum length of text for this field.
0426       Only makes sense if the field type is of Text type.
0427       Default strategy is DefinedMaxLength.
0428      */
0429     enum MaxLengthStrategy {
0430         DefaultMaxLength,  //!< Default maximum text length defined globally by the application.
0431                            //!< @see defaultMaxLength()
0432         DefinedMaxLength   //!< Used if setMaxLength() was called to set specific maximum value
0433                            //!< or to unlimited (0).
0434     };
0435     Q_ENUM(MaxLengthStrategy)
0436 
0437     /*! @return a hint that indicates if the maximum length of text for this field is based on default setting
0438       (defaultMaxLength()) or was explicitly set.
0439       Only makes sense if the field type is Text. */
0440     MaxLengthStrategy maxLengthStrategy() const;
0441 
0442     /*! Sets strategy for defining maximum length of text for this field.
0443       Only makes sense if the field type is Text.
0444       Default strategy is DefinedMaxLength.
0445       Changing this value does not affect maxLength property.
0446 
0447       Fields with DefaultMaxLength strategy does not follow changes made by calling setDefaultMaxLength()
0448       so to update the default maximum lengths in fields, the app has to iterate over all fields of type Text,
0449       and reset to the new default as explained in setMaxLength() documentation.
0450       See documentation for setMaxLength() for information how to reset maxLength to default value.
0451 
0452       @see maxLengthStrategy(), setMaxLength() */
0453     void setMaxLengthStrategy(MaxLengthStrategy strategy);
0454 
0455     /*! @return maximum length of text allowed for this field. Only meaningful if the type is Text.
0456       @see setMaxLength() */
0457     int maxLength() const;
0458 
0459     /*! Sets maximum length for this field. Only works for Text type.
0460      It can be specific maximum value or 0 for unlimited length (which will work if engine supports).
0461      Resets maxLengthStrategy property to DefinedMaxLength.
0462      To reset to default maximum length, call setMaxLength(defaultMaxLength()) and then
0463      to indicate this is based on default setting, call setMaxLengthStrategy(DefaultMaxLength).
0464      @see maxLength(), maxLengthStrategy() */
0465     void setMaxLength(int maxLength);
0466 
0467     /*! @return precision for numeric and other fields that have both length (scale)
0468      and precision (floating point types). */
0469     int precision() const;
0470 
0471     /*! @return scale for numeric and other fields that have both length (scale)
0472      and precision (floating point types).
0473      The scale of a numeric is the count of decimal digits in the fractional part,
0474      to the right of the decimal point. The precision of a numeric is the total count
0475      of significant digits in the whole number, that is, the number of digits
0476      to both sides of the decimal point. So the number 23.5141 has a precision
0477      of 6 and a scale of 4. Integers can be considered to have a scale of zero. */
0478     int scale() const;
0479 
0480 //! @todo should we keep extended properties here or move them to a QVariant dictionary?
0481     /*! @return number of decimal places that should be visible to the user,
0482      e.g. within table view widget, form or printout.
0483      Only meaningful if the field type is floating point or (in the future: decimal or currency).
0484 
0485      - Any value less than 0 (-1 is the default) means that there should be displayed all digits
0486        of the fractional part, except the ending zeros. This is known as "auto" mode.
0487        For example, 12.345000 becomes 12.345.
0488 
0489      - Value of 0 means that all the fractional part should be hidden (as well as the dot or comma).
0490        For example, 12.345000 becomes 12.
0491 
0492      - Value N > 0 means that the fractional part should take exactly N digits.
0493        If the fractional part is shorter than N, additional zeros are appended.
0494        For example, "12.345" becomes "12.345000" if N=6.
0495     */
0496     int visibleDecimalPlaces() const;
0497 
0498     /*! @return the constraints defined for this field. */
0499     Constraints constraints() const;
0500 
0501     /*! @return order of this field in containing table (counting starts from 0)
0502     (-1 if unspecified). */
0503     int order() const;
0504 
0505     /*! @return caption of this field. */
0506     QString caption() const;
0507 
0508     /*! @return caption of this field or - if empty - return its name. */
0509     QString captionOrName() const;
0510 
0511     /*! @return description text for this field. */
0512     QString description() const;
0513 
0514     //! if the type has the unsigned attribute
0515     inline bool isUnsigned() const {
0516         return options() & Unsigned;
0517     }
0518 
0519     /*! @return true if this field has EMPTY property (i.e. it is of type
0520     string or is a BLOB). */
0521     inline bool hasEmptyProperty() const {
0522         return KDbField::hasEmptyProperty(type());
0523     }
0524 
0525     /*! static version of hasEmptyProperty() method
0526      @return true if this field type has EMPTY property (i.e. it is string or BLOB type) */
0527     static bool hasEmptyProperty(Type type);
0528 
0529     /*! @return true if this field can be auto-incremented.
0530      Actually, returns true for integer field type. @see IntegerType, isAutoIncrement() */
0531     inline bool isAutoIncrementAllowed() const {
0532         return KDbField::isAutoIncrementAllowed(type());
0533     }
0534 
0535     /*! static version of isAutoIncrementAllowed() method
0536      @return true if this field type can be auto-incremented. */
0537     static bool isAutoIncrementAllowed(Type type);
0538 
0539     /*! Sets type @a t for this field.
0540      This does nothing if there's expression assigned.
0541      @see setExpression() */
0542     void setType(Type t);
0543 
0544     /*! Sets name @a name for this field. */
0545     void setName(const QString& name);
0546 
0547     /*! Sets constraints to @a c. If PrimaryKey is set in @a c, also
0548      constraits implied by being primary key are enforced (see setPrimaryKey()).
0549      If Indexed is not set in @a c, constraits implied by not being are
0550      enforced as well (see setIndexed()). */
0551     void setConstraints(Constraints c);
0552 
0553     /*! Sets scale for this field. Only works for floating-point types.
0554      @see scale() */
0555     void setScale(int s);
0556 
0557     /*! Sets number of decimal places that should be visible to the user.
0558      @see visibleDecimalPlaces() */
0559     void setVisibleDecimalPlaces(int p);
0560 
0561     /*! Sets scale for this field. Only works for floating-point types. */
0562     void setPrecision(int p);
0563 
0564     /*! Sets unsigned flag for this field. Only works for integer types. */
0565     void setUnsigned(bool u);
0566 
0567     /*! Sets default value for this field. Setting null value removes the default value.
0568      @see defaultValue() */
0569     void setDefaultValue(const QVariant& def);
0570 
0571     /*! Sets default value decoded from QByteArray.
0572       Decoding errors are detected (value is strictly checked against field type)
0573       - if one is encountered, default value is cleared (defaultValue()==QVariant()).
0574       @return true if given value was valid for field type. */
0575     bool setDefaultValue(const QByteArray& def);
0576 
0577     /*! Sets auto increment flag. Only available to set true,
0578      if isAutoIncrementAllowed() is true. */
0579     void setAutoIncrement(bool a);
0580 
0581     /*! Specifies whether the field is single-field primary key or not
0582      (KDb::PrimeryKey item).
0583      Use this with caution. Setting this to true implies setting:
0584      - setUniqueKey(true)
0585      - setNotNull(true)
0586      - setNotEmpty(true)
0587      - setIndexed(true)
0588 
0589      Setting this to false implies setting setAutoIncrement(false). */
0590     void setPrimaryKey(bool p);
0591 
0592     /*! Specifies whether the field has single-field unique constraint or not
0593      (KDb::Unique item). Setting this to true implies setting Indexed flag
0594      to true (setIndexed(true)), because index is required it control unique constraint. */
0595     void setUniqueKey(bool u);
0596 
0597     /*! Sets whether the field has to be declared with single-field foreign key.
0598      Used in KDbIndexSchema::setForeigKey(). */
0599     void setForeignKey(bool f);
0600 
0601     /*! Specifies whether the field has single-field unique constraint or not
0602      (KDb::NotNull item). Setting this to true implies setting Indexed flag
0603      to true (setIndexed(true)), because index is required it control
0604      not null constraint. */
0605     void setNotNull(bool n);
0606 
0607     /*! Specifies whether the field has single-field unique constraint or not
0608      (KDb::NotEmpty item). Setting this to true implies setting Indexed flag
0609      to true (setIndexed(true)), because index is required it control
0610      not empty constraint. */
0611     void setNotEmpty(bool n);
0612 
0613     /*! Specifies whether the field is indexed (KDb::Indexed item)
0614      (by single-field implicit index) or not.
0615      Use this with caution. Since index is used to control unique,
0616      not null/empty constratins, setting this to false implies setting:
0617      - setPrimaryKey(false)
0618      - setUniqueKey(false)
0619      - setNotNull(false)
0620      - setNotEmpty(false)
0621      because above flags need index to be present.
0622      Similarly, setting one of the above flags to true, will automatically
0623      do setIndexed(true) for the same reason. */
0624     void setIndexed(bool s);
0625 
0626     /*! Sets caption for this field to @a caption. */
0627     void setCaption(const QString& caption);
0628 
0629     /*! Sets description for this field to @a description. */
0630     void setDescription(const QString& description);
0631 
0632     /*! There can be added asterisks (KDbQueryAsterisk objects)
0633      to query schemas' field list. KDbQueryAsterisk subclasses KDbField class,
0634      and to check if the given object (pointed by KDbField*)
0635      is asterisk or just ordinary field definition,
0636      you can call this method. This is just effective version of QObject::isA().
0637      Every KDbQueryAsterisk object returns true here,
0638      and every KDbField object returns false.
0639     */
0640     inline bool isQueryAsterisk() const {
0641         return type() == KDbField::Asterisk;
0642     }
0643 
0644     /*! @return KDbExpression object if the field value is an
0645      expression.  Unless the expression is set with setExpression(), it is null.
0646     */
0647     KDbExpression expression();
0648 
0649     //! @overload KDbExpression expression()
0650     const KDbExpression expression() const;
0651 
0652     /*! Sets expression data @a expr. If there was already expression set, it is removed before new
0653      assignment.
0654      This KDbField object becames logical owner of @a expr object, so do not use the expression
0655      for other objects (you can call KDbExpression::clone()).
0656      Current field's expression is deleted, if exists.
0657 
0658      Because the field defines an expression, it should be assigned to a query, not to a table,
0659      otherwise this call will not have any effect.
0660     */
0661     void setExpression(const KDbExpression& expr);
0662 
0663     /*! @return true if there is expression defined for this field.
0664      This method is provided for better readibility
0665      - does the same as expression().isNull(). */
0666     bool isExpression() const;
0667 
0668 //<TMP>
0669     /*! @return the hints for enum fields. */
0670     QVector<QString> enumHints() const;
0671 
0672     /*! @return hint name for enum value @a num. */
0673     QString enumHint(int num);
0674 
0675     /*! Sets the hint for enum fields */
0676     void setEnumHints(const QVector<QString> &hints);
0677 //</TMP>
0678 
0679     /*! @return custom property @a propertyName.
0680      If there is no such a property, @a defaultValue is returned. */
0681     QVariant customProperty(const QByteArray& propertyName,
0682                             const QVariant& defaultValue = QVariant()) const;
0683 
0684     //! Sets value @a value for custom property @a propertyName
0685     void setCustomProperty(const QByteArray& propertyName, const QVariant& value);
0686 
0687     //! A data type used for handling custom properties of a field
0688     typedef QHash<QByteArray, QVariant> CustomPropertiesMap;
0689 
0690     //! @return all custom properties
0691     CustomPropertiesMap customProperties() const;
0692 
0693 protected:
0694     explicit KDbField(KDbFieldList *aParent, int aOrder = -1);
0695 
0696     /*! Creates a database field as a child of @a querySchema table
0697      Assigns @a expr expression to this field, if present.
0698      Used internally by query schemas, e.g. to declare asterisks or
0699      to add expression columns.
0700      No other properties are set, so these should be set later. */
0701     KDbField(KDbQuerySchema *querySchema, const KDbExpression& expr);
0702 
0703     /*! @overload KDbField(KDbQuerySchema*, const KDbExpression&) */
0704     explicit KDbField(KDbQuerySchema *querySchema);
0705 
0706     //! Sets parent for this field.
0707     void setParent(KDbFieldList *parent);
0708 
0709     /*! Sets order of this field in containing table. Counting starts from 0. -1 if unspecified. */
0710     void setOrder(int order);
0711 
0712     //! @return a deep copy of this object. Used in @ref KDbFieldList(const KDbFieldList& fl).
0713     virtual KDbField* copy();
0714 
0715 private:
0716     friend class KDbConnection;
0717     friend class KDbFieldList;
0718     friend class KDbTableSchema;
0719     friend class KDbQuerySchema;
0720 
0721     class Private;
0722     Private * const d;
0723 };
0724 
0725 Q_DECLARE_OPERATORS_FOR_FLAGS(KDbField::Constraints)
0726 Q_DECLARE_OPERATORS_FOR_FLAGS(KDbField::Options)
0727 
0728 //! Sends information about field @a field to debug output @a dbg.
0729 KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbField& field);
0730 
0731 //! Sends information about field type @a type to debug output @a dbg.
0732 KDB_EXPORT QDebug operator<<(QDebug dbg, KDbField::Type type);
0733 
0734 //! Sends information about field type group @a typeGroup to debug output @a dbg.
0735 KDB_EXPORT QDebug operator<<(QDebug dbg, KDbField::TypeGroup typeGroup);
0736 
0737 #endif