KDb

KDbLookupFieldSchema.h
1/* This file is part of the KDE project
2 Copyright (C) 2006-2015 Jarosław Staniek <staniek@kde.org>
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
27class QStringList;
28class QDomElement;
29class QDomDocument;
30class 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{
51public:
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
111private:
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*/
123class KDB_EXPORT KDbLookupFieldSchema
124{
125public:
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
241private:
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.
247KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbLookupFieldSchemaRecordSource& source);
248
249//! Sends lookup field schema information @a lookup to debug output @a dbg.
250KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbLookupFieldSchema& lookup);
251
252#endif
Record source information that can be specified for the lookup field schema.
bool operator!=(const KDbLookupFieldSchemaRecordSource &other) const
Provides information about lookup field's setup.
DisplayWidget
used in displayWidget()
bool operator!=(const KDbLookupFieldSchema &other) const
QDebug operator<<(QDebug dbg, const PerceptualColor::LchaDouble &value)
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sun Feb 25 2024 18:47:36 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.