KDb

KDbField.h
1 /* This file is part of the KDE project
2  Copyright (C) 2002 Lucijan Busch <[email protected]>
3  Copyright (C) 2002 Joseph Wenninger <[email protected]>
4  Copyright (C) 2003-2017 JarosÅ‚aw Staniek <[email protected]>
5 
6  This library is free software; you can redistribute it and/or
7  modify it under the terms of the GNU Library General Public
8  License as published by the Free Software Foundation; either
9  version 2 of the License, or (at your option) any later version.
10 
11  This library is distributed in the hope that it will be useful,
12  but WITHOUT ANY WARRANTY; without even the implied warranty of
13  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  Library General Public License for more details.
15 
16  You should have received a copy of the GNU Library General Public License
17  along with this library; see the file COPYING.LIB. If not, write to
18  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19  * Boston, MA 02110-1301, USA.
20  */
21 
22 #ifndef KDB_FIELD_H
23 #define KDB_FIELD_H
24 
25 #include <QPair>
26 #include <QVector>
27 #include <QStringList>
28 #include <QHash>
29 #include <QCoreApplication>
30 
31 #include "KDbUtils.h"
32 
33 class KDbTableSchema;
34 class KDbQuerySchema;
35 class KDbFieldList;
36 class KDbExpression;
37 
38 //! Meta-data for a field
39 /*! KDbField provides information about single database field.
40 
41  KDbField class has defined following members:
42  - name
43  - type
44  - database constraints
45  - additional options
46  - maxLength (makes sense mostly for string types)
47  - maxLengthStrategy (makes sense mostly for string types)
48  - precision (for floating-point type)
49  - defaultValue
50  - caption (user readable name that can be e.g. translated)
51  - description (user readable name additional text, can be useful for developers)
52  - defaultWidth (a hint for displaying in tabular mode or as text box)
53 
54  KDbField can also have assigned expression (see KDbExpression class,
55  and expression() method).
56 
57  Note that aliases for fields are defined within query, not in KDbField object,
58  because the same field can be used in different queries with different alias.
59 
60  Notes for advanced use: KDbField obeject is designed to be owned by a parent object.
61  Such a parent object can be KDbTableSchema, if the field defines single table column,
62  or KDbQuerySchema, if the field defines an expression (KDbExpression class).
63 
64  Using expression class for fields allos to define expressions within queries like
65  "SELECT AVG(price) FROM products"
66 
67  You can choose whether your field is owned by query or table,
68  using appropriate constructor, or using parameterless constructor and
69  calling setTable() or setQuery() later.
70 */
71 class KDB_EXPORT KDbField
72 {
73  Q_GADGET
75  Q_DECLARE_TR_FUNCTIONS(KDbField)
76 public:
77  typedef KDbUtils::AutodeletedList<KDbField*> List; //!< list of fields
78  typedef QVector<KDbField*> Vector; //!< vector of fields
79  typedef QList<KDbField*>::ConstIterator ListIterator; //!< iterator for list of fields
80  typedef QPair<KDbField*, KDbField*> Pair; //!< fields pair
81  typedef QList<Pair> PairList; //!< list of fields pair
82 
83  /*! Unified (most common used) types of fields. */
84  enum Type {
85  //-- Normal types:
86  InvalidType = 0, /*!< Unsupported/Unimplemented type */
87  Byte = 1, /*!< 1 byte, signed or unsigned */
88  FirstType = 1, /*! First type */
89  ShortInteger = 2,/*!< 2 bytes, signed or unsigned */
90  Integer = 3, /*!< 4 bytes, signed or unsigned */
91  BigInteger = 4, /*!< 8 bytes, signed or unsigned */
92  Boolean = 5, /*!< 0 or 1 */
93  Date = 6, /*!< */
94  DateTime = 7, /*!< */
95  Time = 8, /*!< */
96  Float = 9, /*!< 4 bytes */
97  Double = 10, /*!< 8 bytes */
98  Text = 11, /*!< Other name: Varchar */
99  LongText = 12, /*!< Other name: Memo */
100  BLOB = 13, /*!< Large binary object */
101 
102  LastType = 13, /*!< This line should be at the end of the list of types! */
103 
104  Null = 128, /*!< Used for fields that are "NULL" expressions. */
105 
106  //-- Special, internal types:
107  Asterisk = 129, /*!< Used in KDbQueryAsterisk subclass objects only,
108  not used in table definitions,
109  but only in query definitions */
110  Enum = 130, /*!< An integer internal with a string list of hints */
111  Map = 131, /*!< Mapping from string to string list (more generic than Enum) */
112  Tuple = 132, /*!< A list of values (e.g. arguments of a function) */
113  LastSpecialType = Tuple /*!< This line should be at the end of the list of special types! */
114  };
115  Q_ENUM(Type)
116 
117  /*! Type groups for fields. */
118  enum TypeGroup {
119  InvalidGroup = 0,
120  TextGroup = 1,
121  IntegerGroup = 2,
122  FloatGroup = 3,
123  BooleanGroup = 4,
124  DateTimeGroup = 5,
125  BLOBGroup = 6, /* large binary object */
126 
127  LastTypeGroup = 6 // This line should be at the end of the enum!
128  };
129  Q_ENUM(TypeGroup)
130 
131  /*! Possible constraints defined for a field. */
132  enum Constraint {
133  NoConstraints = 0,
134  AutoInc = 1,
135  Unique = 2,
136  PrimaryKey = 4,
137  ForeignKey = 8,
138  NotNull = 16,
139  NotEmpty = 32, //!< only legal for string-like and blob fields
140  Indexed = 64
141  };
142  Q_DECLARE_FLAGS(Constraints, Constraint)
143 
144  /*! Possible options defined for a field. */
145  enum Option {
146  NoOptions = 0,
147  Unsigned = 1
148  };
149  Q_DECLARE_FLAGS(Options, Option)
150 
151  /*! Creates a database field as a child of @a tableSchema table.
152  No other properties are set (even the name), so these should be set later. */
153  explicit KDbField(KDbTableSchema *tableSchema);
154 
155  /*! Creates a database field.
156  maxLength property is set to 0 (unlimited length).
157  No other properties are set (even the name), so these should be set later. */
158  KDbField();
159 
160  /*! Creates a database field with specified properties.
161  For meaning of @a maxLength argument please refer to setMaxLength(). */
162  KDbField(const QString &name, Type type, Constraints constr = NoConstraints,
163  Options options = NoOptions, int maxLength = 0, int precision = 0,
164  const QVariant &defaultValue = QVariant(), const QString &caption = QString(),
165  const QString &description = QString());
166 
167  /*! Constructs a deep copy of field @a f. */
168  KDbField(const KDbField &f);
169 
170  virtual ~KDbField();
171 
172  //! @return parent for this field (table, query, etc.)
173  KDbFieldList *parent();
174 
175  //! @overload
176  const KDbFieldList *parent() const;
177 
178  //! @return number of normal types available, i.e. types > InvalidType and <= LastType.
179  static int typesCount();
180 
181  //! @return number of special types available (Asterisk, Enum, etc.), that means
182  static int specialTypesCount();
183 
184  //! @return number of type groups available
185  static int typeGroupsCount();
186 
187  //! Converts type @a type to QVariant equivalent as accurate as possible
188  /*! Only normal types are supported.
189  @see typesCount() specialTypesCount() */
190  static QVariant::Type variantType(Type type);
191 
192  //! Converts value @a value to variant corresponding to type @a type.
193  /*! Only normal types are supported.
194  If converting is not possible a null value is returned. */
195  static QVariant convertToType(const QVariant &value, Type type);
196 
197  //! @return a translated type name for @a type
198  /*! @a type has to be an element from KDbField::Type, not greater than KDbField::LastType.
199  Only normal types and KDbField::Null are supported.
200  For unsupported types empty string is returned. */
201  //! @see typesCount() specialTypesCount()
202  static QString typeName(Type type);
203 
204  //! @return list of all available translated names of normal types
205  /*! The first element of the list is the name of KDbField::InvalidType, the last one
206  is a name of KDbField::LastType.
207  @see typesCount() specialTypesCount() */
208  static QStringList typeNames();
209 
210  //! @return a nontranslated type string for @a type
211  /*! For example returns "Integer" for KDbType::Integer.
212  @a type has to be an element from KDbField::Type, not greater than KDbField::LastType;
213  KDbField::Null is also supported.
214  For unsupported types empty string is returned. */
215  static QString typeString(Type type);
216 
217  //! @return type for a given nontranslated type string @a typeString
218  /*! For example returns KDbType::Integer for "Integer".
219  @a typeString has to be name of type not greater than KDbField::LastType;
220  KDbField::Null is also supported.
221  For unsupported value KDbField::InvalidType is returned. */
222  static Type typeForString(const QString& typeString);
223 
224  //! @return type group for a given nontranslated type group @a typeGroupString
225  /*! For example returns KDbField::TextGroup for "TextGroup" string.
226  For unsupported value KDbField::InvalidGroup is returned. */
227  static TypeGroup typeGroupForString(const QString& typeGroupString);
228 
229  //! @return group for @a type
230  /*! For example returns KDbField::TextGroup for KDbField::Text type.
231  @a type has to be an element from KDbField::Type, not greater than KDbField::LastType.
232  For unsupported type KDbField::InvalidGroup is returned. */
233  static TypeGroup typeGroup(Type type);
234 
235  //! @return a translated group name for @a typeGroup
236  static QString typeGroupName(TypeGroup typeGroup);
237 
238  //! @return list of all available translated type group names
239  /*! The first element of the list is the name of KDbField::InvalidGroup, the last one
240  is a name of KDbField::LastTypeGroup. */
241  static QStringList typeGroupNames();
242 
243  //! @return a nontranslated type group string for @a typeGroup, e.g. "IntegerGroup" for IntegerGroup type
244  static QString typeGroupString(TypeGroup typeGroup);
245 
246  /*! @return the name of this field */
247  QString name() const;
248 
249  /*! @return table schema of table that owns this field
250  or null if it has no table assigned.
251  @see query() */
252  KDbTableSchema* table();
253 
254  //! @overload KDbTableSchema* table()
255  const KDbTableSchema* table() const;
256 
257  /*! Sets @a table schema of table that owns this field.
258  This does not adds the field to @a table object.
259  You do not need to call this method by hand.
260  Call KDbTableSchema::addField(KDbField *field) instead.
261  @see setQuery() */
262  void setTable(KDbTableSchema *table);
263 
264  /*! For special use when the field defines expression.
265  @return query schema of query that owns this field
266  or null if it has no query assigned.
267  @see table() */
268  KDbQuerySchema* query();
269 
270  //! @overload KDbQuerySchema* query()
271  const KDbQuerySchema* query() const;
272 
273  /*! For special use when field defines expression.
274  Sets @a query schema of query that owns this field.
275  This does not adds the field to @a query object.
276  You do not need to call this method by hand.
277  Call KDbQuerySchema::addField() instead.
278  @see setQuery() */
279  void setQuery(KDbQuerySchema *query);
280 
281  /*! @return true if the field is autoincrement (e.g. integer/numeric) */
282  inline bool isAutoIncrement() const {
283  return constraints() & AutoInc;
284  }
285 
286  /*! @return true if the field is member of single-field primary key */
287  inline bool isPrimaryKey() const {
288  return constraints() & PrimaryKey;
289  }
290 
291  /*! @return true if the field is member of single-field unique key */
292  inline bool isUniqueKey() const {
293  return constraints() & Unique;
294  }
295 
296  /*! @return true if the field is member of single-field foreign key */
297  inline bool isForeignKey() const {
298  return constraints() & ForeignKey;
299  }
300 
301  /*! @return true if the field is not allowed to be null */
302  inline bool isNotNull() const {
303  return constraints() & NotNull;
304  }
305 
306  /*! @return true if the field is not allowed to be null */
307  inline bool isNotEmpty() const {
308  return constraints() & NotEmpty;
309  }
310 
311  /*! @return true if the field is indexed using single-field database index. */
312  inline bool isIndexed() const {
313  return constraints() & Indexed;
314  }
315 
316  /*! @return true if the field is of any numeric type (integer or floating point) */
317  inline bool isNumericType() const {
318  return KDbField::isNumericType(type());
319  }
320 
321  /*! Static version of isNumericType() method
322  @return true if the field is of any numeric type (integer or floating point)*/
323  static bool isNumericType(Type type);
324 
325  /*! @return true if the field is of any integer type */
326  inline bool isIntegerType() const {
327  return KDbField::isIntegerType(type());
328  }
329 
330  /*! Static version of isIntegerType() method
331  @return true if the field is of any integer type */
332  static bool isIntegerType(Type type);
333 
334  /*! @return true if the field is of any floating point numeric type */
335  inline bool isFPNumericType() const {
336  return KDbField::isFPNumericType(type());
337  }
338 
339  /*! static version of isFPNumericType() method
340  @return true if the field is of any floating point numeric type */
341  static bool isFPNumericType(Type type);
342 
343  /*! @return true if the field is of any date or time related type */
344  inline bool isDateTimeType() const {
345  return KDbField::isDateTimeType(type());
346  }
347 
348  /*! Static version of isDateTimeType() method
349  @return true if the field is of any date or time related type */
350  static bool isDateTimeType(Type type);
351 
352  /*! @return true if the field is of any text type */
353  inline bool isTextType() const {
354  return KDbField::isTextType(type());
355  }
356 
357  /*! Static version of isTextType() method
358  @return true if the field is of any text type */
359  static bool isTextType(Type type);
360 
361  /*! @return options defined for this field. */
362  Options options() const;
363 
364  /*! Sets options for this field. */
365  void setOptions(Options options);
366 
367  //! Converts field's type to QVariant equivalent as accurate as possible
368  inline QVariant::Type variantType() const {
369  return variantType(type());
370  }
371 
372  /*! @return a type for this field. If there's expression assigned,
373  type of the expression (after evaluation) is returned instead. */
374  Type type() const;
375 
376  //! @return a translated type name for this field
377  inline QString typeName() const {
378  return KDbField::typeName(type());
379  }
380 
381  //! @return type group for this field
382  inline TypeGroup typeGroup() const {
383  return KDbField::typeGroup(type());
384  }
385 
386  //! @return a translated type group name for this field
387  inline QString typeGroupName() const {
388  return KDbField::typeGroupName(typeGroup());
389  }
390 
391  //! @return a type string for this field,
392  //! for example "Integer" string for KDbField::Integer type.
393  inline QString typeString() const {
394  return KDbField::typeString(type());
395  }
396 
397  //! @return a type group string for this field,
398  //! for example "Integer" string for KDbField::IntegerGroup.
399  inline QString typeGroupString() const {
400  return KDbField::typeGroupString(typeGroup());
401  }
402 
403  /*! @return (optional) subtype for this field.
404  Subtype is a string providing additional hint for field's type.
405  E.g. for BLOB type, it can be a MIME type or certain QVariant type name,
406  for example: "QPixmap", "QColor" or "QFont" */
407  QString subType() const;
408 
409  /*! Sets (optional) subtype for this field.
410  @see subType() */
411  void setSubType(const QString& subType);
412 
413  //! @return default value for this field. Null value means there
414  //! is no default value declared. The variant value is compatible with field's type.
415  QVariant defaultValue() const;
416 
417  /*! @return default maximum length of text.
418  Default is 0, i.e unlimited length (if the engine supports it). */
419  static int defaultMaxLength();
420 
421  /*! Sets default maximum length of text. 0 means unlimited length,
422  greater than 0 means specific maximum length. */
423  static void setDefaultMaxLength(int maxLength);
424 
425  /*! Strategy for defining maximum length of text for this field.
426  Only makes sense if the field type is of Text type.
427  Default strategy is DefinedMaxLength.
428  */
430  DefaultMaxLength, //!< Default maximum text length defined globally by the application.
431  //!< @see defaultMaxLength()
432  DefinedMaxLength //!< Used if setMaxLength() was called to set specific maximum value
433  //!< or to unlimited (0).
434  };
435  Q_ENUM(MaxLengthStrategy)
436 
437  /*! @return a hint that indicates if the maximum length of text for this field is based on default setting
438  (defaultMaxLength()) or was explicitly set.
439  Only makes sense if the field type is Text. */
440  MaxLengthStrategy maxLengthStrategy() const;
441 
442  /*! Sets strategy for defining maximum length of text for this field.
443  Only makes sense if the field type is Text.
444  Default strategy is DefinedMaxLength.
445  Changing this value does not affect maxLength property.
446 
447  Fields with DefaultMaxLength strategy does not follow changes made by calling setDefaultMaxLength()
448  so to update the default maximum lengths in fields, the app has to iterate over all fields of type Text,
449  and reset to the new default as explained in setMaxLength() documentation.
450  See documentation for setMaxLength() for information how to reset maxLength to default value.
451 
452  @see maxLengthStrategy(), setMaxLength() */
453  void setMaxLengthStrategy(MaxLengthStrategy strategy);
454 
455  /*! @return maximum length of text allowed for this field. Only meaningful if the type is Text.
456  @see setMaxLength() */
457  int maxLength() const;
458 
459  /*! Sets maximum length for this field. Only works for Text type.
460  It can be specific maximum value or 0 for unlimited length (which will work if engine supports).
461  Resets maxLengthStrategy property to DefinedMaxLength.
462  To reset to default maximum length, call setMaxLength(defaultMaxLength()) and then
463  to indicate this is based on default setting, call setMaxLengthStrategy(DefaultMaxLength).
464  @see maxLength(), maxLengthStrategy() */
465  void setMaxLength(int maxLength);
466 
467  /*! @return precision for numeric and other fields that have both length (scale)
468  and precision (floating point types). */
469  int precision() const;
470 
471  /*! @return scale for numeric and other fields that have both length (scale)
472  and precision (floating point types).
473  The scale of a numeric is the count of decimal digits in the fractional part,
474  to the right of the decimal point. The precision of a numeric is the total count
475  of significant digits in the whole number, that is, the number of digits
476  to both sides of the decimal point. So the number 23.5141 has a precision
477  of 6 and a scale of 4. Integers can be considered to have a scale of zero. */
478  int scale() const;
479 
480 //! @todo should we keep extended properties here or move them to a QVariant dictionary?
481  /*! @return number of decimal places that should be visible to the user,
482  e.g. within table view widget, form or printout.
483  Only meaningful if the field type is floating point or (in the future: decimal or currency).
484 
485  - Any value less than 0 (-1 is the default) means that there should be displayed all digits
486  of the fractional part, except the ending zeros. This is known as "auto" mode.
487  For example, 12.345000 becomes 12.345.
488 
489  - Value of 0 means that all the fractional part should be hidden (as well as the dot or comma).
490  For example, 12.345000 becomes 12.
491 
492  - Value N > 0 means that the fractional part should take exactly N digits.
493  If the fractional part is shorter than N, additional zeros are appended.
494  For example, "12.345" becomes "12.345000" if N=6.
495  */
496  int visibleDecimalPlaces() const;
497 
498  /*! @return the constraints defined for this field. */
499  Constraints constraints() const;
500 
501  /*! @return order of this field in containing table (counting starts from 0)
502  (-1 if unspecified). */
503  int order() const;
504 
505  /*! @return caption of this field. */
506  QString caption() const;
507 
508  /*! @return caption of this field or - if empty - return its name. */
509  QString captionOrName() const;
510 
511  /*! @return description text for this field. */
512  QString description() const;
513 
514  //! if the type has the unsigned attribute
515  inline bool isUnsigned() const {
516  return options() & Unsigned;
517  }
518 
519  /*! @return true if this field has EMPTY property (i.e. it is of type
520  string or is a BLOB). */
521  inline bool hasEmptyProperty() const {
522  return KDbField::hasEmptyProperty(type());
523  }
524 
525  /*! static version of hasEmptyProperty() method
526  @return true if this field type has EMPTY property (i.e. it is string or BLOB type) */
527  static bool hasEmptyProperty(Type type);
528 
529  /*! @return true if this field can be auto-incremented.
530  Actually, returns true for integer field type. @see IntegerType, isAutoIncrement() */
531  inline bool isAutoIncrementAllowed() const {
532  return KDbField::isAutoIncrementAllowed(type());
533  }
534 
535  /*! static version of isAutoIncrementAllowed() method
536  @return true if this field type can be auto-incremented. */
537  static bool isAutoIncrementAllowed(Type type);
538 
539  /*! Sets type @a t for this field.
540  This does nothing if there's expression assigned.
541  @see setExpression() */
542  void setType(Type t);
543 
544  /*! Sets name @a name for this field. */
545  void setName(const QString& name);
546 
547  /*! Sets constraints to @a c. If PrimaryKey is set in @a c, also
548  constraits implied by being primary key are enforced (see setPrimaryKey()).
549  If Indexed is not set in @a c, constraits implied by not being are
550  enforced as well (see setIndexed()). */
551  void setConstraints(Constraints c);
552 
553  /*! Sets scale for this field. Only works for floating-point types.
554  @see scale() */
555  void setScale(int s);
556 
557  /*! Sets number of decimal places that should be visible to the user.
558  @see visibleDecimalPlaces() */
559  void setVisibleDecimalPlaces(int p);
560 
561  /*! Sets scale for this field. Only works for floating-point types. */
562  void setPrecision(int p);
563 
564  /*! Sets unsigned flag for this field. Only works for integer types. */
565  void setUnsigned(bool u);
566 
567  /*! Sets default value for this field. Setting null value removes the default value.
568  @see defaultValue() */
569  void setDefaultValue(const QVariant& def);
570 
571  /*! Sets default value decoded from QByteArray.
572  Decoding errors are detected (value is strictly checked against field type)
573  - if one is encountered, default value is cleared (defaultValue()==QVariant()).
574  @return true if given value was valid for field type. */
575  bool setDefaultValue(const QByteArray& def);
576 
577  /*! Sets auto increment flag. Only available to set true,
578  if isAutoIncrementAllowed() is true. */
579  void setAutoIncrement(bool a);
580 
581  /*! Specifies whether the field is single-field primary key or not
582  (KDb::PrimeryKey item).
583  Use this with caution. Setting this to true implies setting:
584  - setUniqueKey(true)
585  - setNotNull(true)
586  - setNotEmpty(true)
587  - setIndexed(true)
588 
589  Setting this to false implies setting setAutoIncrement(false). */
590  void setPrimaryKey(bool p);
591 
592  /*! Specifies whether the field has single-field unique constraint or not
593  (KDb::Unique item). Setting this to true implies setting Indexed flag
594  to true (setIndexed(true)), because index is required it control unique constraint. */
595  void setUniqueKey(bool u);
596 
597  /*! Sets whether the field has to be declared with single-field foreign key.
598  Used in KDbIndexSchema::setForeigKey(). */
599  void setForeignKey(bool f);
600 
601  /*! Specifies whether the field has single-field unique constraint or not
602  (KDb::NotNull item). Setting this to true implies setting Indexed flag
603  to true (setIndexed(true)), because index is required it control
604  not null constraint. */
605  void setNotNull(bool n);
606 
607  /*! Specifies whether the field has single-field unique constraint or not
608  (KDb::NotEmpty item). Setting this to true implies setting Indexed flag
609  to true (setIndexed(true)), because index is required it control
610  not empty constraint. */
611  void setNotEmpty(bool n);
612 
613  /*! Specifies whether the field is indexed (KDb::Indexed item)
614  (by single-field implicit index) or not.
615  Use this with caution. Since index is used to control unique,
616  not null/empty constratins, setting this to false implies setting:
617  - setPrimaryKey(false)
618  - setUniqueKey(false)
619  - setNotNull(false)
620  - setNotEmpty(false)
621  because above flags need index to be present.
622  Similarly, setting one of the above flags to true, will automatically
623  do setIndexed(true) for the same reason. */
624  void setIndexed(bool s);
625 
626  /*! Sets caption for this field to @a caption. */
627  void setCaption(const QString& caption);
628 
629  /*! Sets description for this field to @a description. */
630  void setDescription(const QString& description);
631 
632  /*! There can be added asterisks (KDbQueryAsterisk objects)
633  to query schemas' field list. KDbQueryAsterisk subclasses KDbField class,
634  and to check if the given object (pointed by KDbField*)
635  is asterisk or just ordinary field definition,
636  you can call this method. This is just effective version of QObject::isA().
637  Every KDbQueryAsterisk object returns true here,
638  and every KDbField object returns false.
639  */
640  inline bool isQueryAsterisk() const {
641  return type() == KDbField::Asterisk;
642  }
643 
644  /*! @return KDbExpression object if the field value is an
645  expression. Unless the expression is set with setExpression(), it is null.
646  */
647  KDbExpression expression();
648 
649  //! @overload KDbExpression expression()
650  const KDbExpression expression() const;
651 
652  /*! Sets expression data @a expr. If there was already expression set, it is removed before new
653  assignment.
654  This KDbField object becames logical owner of @a expr object, so do not use the expression
655  for other objects (you can call KDbExpression::clone()).
656  Current field's expression is deleted, if exists.
657 
658  Because the field defines an expression, it should be assigned to a query, not to a table,
659  otherwise this call will not have any effect.
660  */
661  void setExpression(const KDbExpression& expr);
662 
663  /*! @return true if there is expression defined for this field.
664  This method is provided for better readibility
665  - does the same as expression().isNull(). */
666  bool isExpression() const;
667 
668 //<TMP>
669  /*! @return the hints for enum fields. */
670  QVector<QString> enumHints() const;
671 
672  /*! @return hint name for enum value @a num. */
673  QString enumHint(int num);
674 
675  /*! Sets the hint for enum fields */
676  void setEnumHints(const QVector<QString> &hints);
677 //</TMP>
678 
679  /*! @return custom property @a propertyName.
680  If there is no such a property, @a defaultValue is returned. */
681  QVariant customProperty(const QByteArray& propertyName,
682  const QVariant& defaultValue = QVariant()) const;
683 
684  //! Sets value @a value for custom property @a propertyName
685  void setCustomProperty(const QByteArray& propertyName, const QVariant& value);
686 
687  //! A data type used for handling custom properties of a field
689 
690  //! @return all custom properties
691  CustomPropertiesMap customProperties() const;
692 
693 protected:
694  explicit KDbField(KDbFieldList *aParent, int aOrder = -1);
695 
696  /*! Creates a database field as a child of @a querySchema table
697  Assigns @a expr expression to this field, if present.
698  Used internally by query schemas, e.g. to declare asterisks or
699  to add expression columns.
700  No other properties are set, so these should be set later. */
701  KDbField(KDbQuerySchema *querySchema, const KDbExpression& expr);
702 
703  /*! @overload KDbField(KDbQuerySchema*, const KDbExpression&) */
704  explicit KDbField(KDbQuerySchema *querySchema);
705 
706  //! Sets parent for this field.
707  void setParent(KDbFieldList *parent);
708 
709  /*! Sets order of this field in containing table. Counting starts from 0. -1 if unspecified. */
710  void setOrder(int order);
711 
712  //! @return a deep copy of this object. Used in @ref KDbFieldList(const KDbFieldList& fl).
713  virtual KDbField* copy();
714 
715 private:
716  friend class KDbConnection;
717  friend class KDbFieldList;
718  friend class KDbTableSchema;
719  friend class KDbQuerySchema;
720 
721  class Private;
722  Private * const d;
723 };
724 
725 Q_DECLARE_OPERATORS_FOR_FLAGS(KDbField::Constraints)
726 Q_DECLARE_OPERATORS_FOR_FLAGS(KDbField::Options)
727 
728 //! Sends information about field @a field to debug output @a dbg.
729 KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbField& field);
730 
731 //! Sends information about field type @a type to debug output @a dbg.
732 KDB_EXPORT QDebug operator<<(QDebug dbg, KDbField::Type type);
733 
734 //! Sends information about field type group @a typeGroup to debug output @a dbg.
735 KDB_EXPORT QDebug operator<<(QDebug dbg, KDbField::TypeGroup typeGroup);
736 
737 #endif
QVector< KDbField * > Vector
vector of fields
Definition: KDbField.h:78
bool isNotEmpty() const
Definition: KDbField.h:307
bool isPrimaryKey() const
Definition: KDbField.h:287
KCALENDARCORE_EXPORT QDataStream & operator<<(QDataStream &out, const KCalendarCore::Alarm::Ptr &)
bool isIndexed() const
Definition: KDbField.h:312
bool isQueryAsterisk() const
Definition: KDbField.h:640
@ Asterisk
Definition: KDbField.h:107
QHash< QByteArray, QVariant > CustomPropertiesMap
A data type used for handling custom properties of a field.
Definition: KDbField.h:688
bool isUniqueKey() const
Definition: KDbField.h:292
MaxLengthStrategy
Definition: KDbField.h:429
QString caption()
bool isFPNumericType() const
Definition: KDbField.h:335
bool isUnsigned() const
if the type has the unsigned attribute
Definition: KDbField.h:515
QString typeName() const
Definition: KDbField.h:377
QString typeString() const
Definition: KDbField.h:393
bool isAutoIncrementAllowed() const
Definition: KDbField.h:531
bool isTextType() const
Definition: KDbField.h:353
bool isIntegerType() const
Definition: KDbField.h:326
QVariant::Type variantType() const
Converts field's type to QVariant equivalent as accurate as possible.
Definition: KDbField.h:368
QString typeGroupString() const
Definition: KDbField.h:399
bool isForeignKey() const
Definition: KDbField.h:297
TypeGroup typeGroup() const
Definition: KDbField.h:382
QList< KDbField * >::ConstIterator ListIterator
iterator for list of fields
Definition: KDbField.h:79
bool isNumericType() const
Definition: KDbField.h:317
QList< Pair > PairList
list of fields pair
Definition: KDbField.h:81
bool isDateTimeType() const
Definition: KDbField.h:344
QString typeGroupName() const
Definition: KDbField.h:387
bool isAutoIncrement() const
Definition: KDbField.h:282
KDbQuerySchema provides information about database query.
bool isNotNull() const
Definition: KDbField.h:302
Meta-data for a field.
Definition: KDbField.h:71
bool hasEmptyProperty() const
Definition: KDbField.h:521
Provides database connection, allowing queries and data modification.
Definition: KDbConnection.h:51
The KDbExpression class represents a base class for all expressions.
Definition: KDbExpression.h:51
KDbUtils::AutodeletedList< KDbField * > List
list of fields
Definition: KDbField.h:77
@ Unsigned
Values can be both non-negative.
Definition: KDbGlobal.h:153
QPair< KDbField *, KDbField * > Pair
fields pair
Definition: KDbField.h:80
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Dec 3 2023 04:12:14 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.