KDb

KDbLookupFieldSchema.h
1 /* This file is part of the KDE project
2  Copyright (C) 2006-2015 JarosÅ‚aw Staniek <[email protected]>
3 
4  This library 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 library 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 library; see the file COPYING.LIB. 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_LOOKUPFIELDSCHEMA_H
21 #define KDB_LOOKUPFIELDSCHEMA_H
22 
23 #include <QMap>
24 
25 #include "kdb_export.h"
26 
27 class QStringList;
28 class QDomElement;
29 class QDomDocument;
30 class QVariant;
31 
32 //! default value for KDbLookupFieldSchema::columnHeadersVisible()
33 #define KDB_LOOKUP_FIELD_DEFAULT_HEADERS_VISIBLE false
34 
35 //! default value for KDbLookupFieldSchema::maxVisibleRecords()
36 #define KDB_LOOKUP_FIELD_DEFAULT_MAX_VISIBLE_RECORDS 8
37 
38 //! upper limit for KDbLookupFieldSchema::maxVisibleRecords()
39 #define KDB_LOOKUP_FIELD_LIMIT_MAX_VISIBLE_RECORDS 100
40 
41 //! default value for KDbLookupFieldSchema::limitToList()
42 #define KDB_LOOKUP_FIELD_DEFAULT_LIMIT_TO_LIST true
43 
44 //! default value for KDbLookupFieldSchema::displayWidget()
45 #define KDB_LOOKUP_FIELD_DEFAULT_DISPLAY_WIDGET KDbLookupFieldSchema::DisplayWidget::ComboBox
46 
47 //! Record source information that can be specified for the lookup field schema
48 //! @since 3.1
50 {
51 public:
52  //! Record source type
53  enum class Type {
54  None, //!< used for invalid schema
55  Table, //!< table as lookup record source
56  Query, //!< named query as lookup record source
57  SQLStatement, //!< anonymous query as lookup record source
58  ValueList, //!< a fixed list of values as lookup record source
59  KDbFieldList //!< a list of column names from a table/query will be displayed
60  };
61 
63 
65 
67 
68  /*! @return record source type: table, query, anonymous; in the future it will
69  be also fixed value list and field list. The latter is basically a list
70  of column names of a table/query, "Field List" in MSA. */
71  Type type() const;
72 
73  /*! Sets record source type to @a type. */
74  void setType(Type type);
75 
76  /*! @return record source type name. @see setTypeByName() */
77  QString typeName() const;
78 
79  /*! Sets record source type by name using @a typeName. Accepted (case sensitive)
80  names are "table", "query", "sql", "valuelist", "fieldlist".
81  For other value NoType type is set. */
82  void setTypeByName(const QString& typeName);
83 
84  /*! @return a string for record source: table name, query name or anonymous query
85  provided as KDbSQL string. If recordSourceType() is a ValueList,
86  recordSourceValues() should be used instead. If recordSourceType() is a KDbFieldList,
87  recordSource() should return table or query name. */
88  QString name() const;
89 
90  /*! Sets record source value. @see value() */
91  void setName(const QString& name);
92 
93  /*! @return record source values specified if type() is ValueList. */
94  QStringList values() const;
95 
96  /*! Sets record source values used if type() is ValueList.
97  Using it clears name (see name()). */
98  void setValues(const QStringList& values);
99 
100  //! Assigns @a other to this record source and returns a reference to this record source.
102 
103  //! @return @c true if this record source is equal to @a other; otherwise returns @c false.
104  //! @since 3.1
105  bool operator==(const KDbLookupFieldSchemaRecordSource &other) const;
106 
107  //! @return @c true if this record source is not equal to @a other; otherwise returns @c false.
108  //! @since 3.1
109  inline bool operator!=(const KDbLookupFieldSchemaRecordSource &other) const { return !operator==(other); }
110 
111 private:
112  class Private;
113  Private * const d;
114 };
115 
116 //! @short Provides information about lookup field's setup.
117 /*!
118  KDbLookupFieldSchema object is owned by KDbTableSchema and created upon creating or retrieving the table schema
119  from the database metadata.
120 
121  @see KDbLookupFieldSchema *KDbTableSchema::lookupFieldSchema( KDbField& field ) const
122 */
123 class KDB_EXPORT KDbLookupFieldSchema
124 {
125 public:
127 
129 
131 
132  /*! @return record source information for the lookup field schema */
133  KDbLookupFieldSchemaRecordSource recordSource() const;
134 
135  /*! Sets record source for the lookup field schema */
136  void setRecordSource(const KDbLookupFieldSchemaRecordSource& recordSource);
137 
138  /*! @return bound column: an integer specifying a column that is bound
139  (counted from 0). -1 means unspecified value. */
140 //! @todo in later implementation there can be more columns
141  int boundColumn() const;
142 
143  /*! Sets bound column number to @a column. @see boundColumn() */
144  void setBoundColumn(int column);
145 
146  /*! @return a list of visible columns: a list of integers specifying indices (counted from 0)
147  of columns within the row source that are visible in the combo box.
148  Empty list means unspecified value. */
149  QList<int> visibleColumns() const;
150 
151  /*! Sets a list of visible columns to \a list. @see visibleColumns() */
152  void setVisibleColumns(const QList<int>& list);
153 
154  /*! A helper method.
155  If index >= visibleColumns().count(), -1 is returned,
156  else \a index is returned. */
157  int visibleColumn(int index) const;
158 
159  /*! @return a number of ordered integers specifying column widths;
160  -1 means 'default width' for a given column. */
161  QList<int> columnWidths() const;
162 
163  /*! Sets column widths. @see columnWidths() */
164  void setColumnWidths(const QList<int>& widths);
165 
166  /*! @return true if column headers are visible in the associated
167  combo box popup or the list view. The default is false. */
168  bool columnHeadersVisible() const;
169 
170  /*! Sets "column headers visibility" flag. @see columnHeadersVisible() */
171  void setColumnHeadersVisible(bool set);
172 
173  /*! @return integer property specifying a maximum number of records
174  that can be displayed in a combo box popup or a list box. The default is
175  equal to KDB_LOOKUP_FIELD_DEFAULT_MAX_VISIBLE_RECORD_COUNT constant. */
176  int maxVisibleRecords() const;
177 
178  /*! Sets maximum number of records that can be displayed in a combo box popup
179  or a list box. If @a count is 0, KDB_LOOKUP_FIELD_DEFAULT_MAX_VISIBLE_RECORD_COUNT is set.
180  If @a count is greater than KDB_LOOKUP_FIELD_MAX_LIST_ROWS,
181  KDB_LOOKUP_FIELD_MAX_LIST_ROWS is set. */
182  void setMaxVisibleRecords(int count);
183 
184  /*! @return true if , only values present on the list can be selected using
185  the combo box. The default is true. */
186  bool limitToList() const;
187 
188  /*! Sets "limit to list" flag. @see limitToList() */
189  void setLimitToList(bool set);
190 
191  //! used in displayWidget()
192  enum class DisplayWidget {
193  ComboBox = 0, //!< (the default) combobox widget should be displayed in forms for this lookup field
194  ListBox = 1 //!< listbox widget should be displayed in forms for this lookup field
195  };
196 
197  /*! @return the widget type that should be displayed within
198  the forms for this lookup field. The default is ComboBox.
199  For the Table View, combo box is always displayed. */
200  DisplayWidget displayWidget() const;
201 
202  /*! Sets type of widget to display within the forms for this lookup field. @see displayWidget() */
203  void setDisplayWidget(DisplayWidget widget);
204 
205  /*! Loads data of lookup column schema from DOM tree.
206  The data can be outdated or invalid, so the app should handle such cases.
207  @return a new KDbLookupFieldSchema object even if lookupEl contains no valid contents. */
208  static KDbLookupFieldSchema* loadFromDom(const QDomElement& lookupEl);
209 
210  /*! Saves data of lookup column schema to @a parentEl DOM element of @a doc document.
211  Does nothing if @a doc or @a parentEl is @c nullptr. */
212  void saveToDom(QDomDocument *doc, QDomElement *parentEl);
213 
214  /*! Gets property values for the lookup schema.
215  @a values is cleared before filling.
216  This function is used e.g. for altering table design. */
217  void getProperties(QMap<QByteArray, QVariant> *values) const;
218 
219  /*! Sets property of name @a propertyName and value @a value for the lookup schema @a lookup
220  @return true on successful set and false on failure because of invalid value or invalid property name. */
221  bool setProperty(const QByteArray& propertyName, const QVariant& value);
222 
223  /*! Sets property values for the lookup schema.
224  Properties coming from extended schema are also supported.
225  Properties not listed are kept untouched.
226  This function is used e.g. for altering table design.
227  @return true on successful set and false on failure because of invalid value or invalid property name. */
228  bool setProperties(const QMap<QByteArray, QVariant>& values);
229 
230  //! Assigns @a other to this lookup schema and returns a reference to this lookup schema.
231  KDbLookupFieldSchema& operator=(const KDbLookupFieldSchema& other);
232 
233  //! @return @c true if this lookup schema is equal to @a other; otherwise returns @c false.
234  //! @since 3.1
235  bool operator==(const KDbLookupFieldSchema &other) const;
236 
237  //! @return @c true if this lookup schema is not equal to @a other; otherwise returns @c false.
238  //! @since 3.1
239  inline bool operator!=(const KDbLookupFieldSchema &other) const { return !operator==(other); }
240 
241 private:
242  class Private;
243  Private * const d;
244 };
245 
246 //! Sends lookup field schema's record source information @a source to debug output @a dbg.
247 KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbLookupFieldSchemaRecordSource& source);
248 
249 //! Sends lookup field schema information @a lookup to debug output @a dbg.
250 KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbLookupFieldSchema& lookup);
251 
252 #endif
Provides information about lookup field's setup.
QCA_EXPORT void setProperty(const QString &name, const QVariant &value)
QDataStream & operator<<(QDataStream &out, const KDateTime &dateTime)
DisplayWidget
used in displayWidget()
Record source information that can be specified for the lookup field schema.
bool operator!=(const KDbLookupFieldSchema &other) const
QVector< V > values(const QMultiHash< K, V > &c)
bool operator!=(const KDbLookupFieldSchemaRecordSource &other) const
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Sep 29 2023 04:07:19 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.