File indexing completed on 2024-11-10 07:17:53
0001 /* This file is part of the KDE project 0002 Copyright (C) 2006-2015 Jarosław Staniek <staniek@kde.org> 0003 0004 This library is free software; you can redistribute it and/or 0005 modify it under the terms of the GNU Library General Public 0006 License as published by the Free Software Foundation; either 0007 version 2 of the License, or (at your option) any later version. 0008 0009 This library is distributed in the hope that it will be useful, 0010 but WITHOUT ANY WARRANTY; without even the implied warranty of 0011 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0012 Library General Public License for more details. 0013 0014 You should have received a copy of the GNU Library General Public License 0015 along with this library; see the file COPYING.LIB. If not, write to 0016 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 0017 * Boston, MA 02110-1301, USA. 0018 */ 0019 0020 #ifndef KDB_LOOKUPFIELDSCHEMA_H 0021 #define KDB_LOOKUPFIELDSCHEMA_H 0022 0023 #include <QMap> 0024 0025 #include "kdb_export.h" 0026 0027 class QStringList; 0028 class QDomElement; 0029 class QDomDocument; 0030 class QVariant; 0031 0032 //! default value for KDbLookupFieldSchema::columnHeadersVisible() 0033 #define KDB_LOOKUP_FIELD_DEFAULT_HEADERS_VISIBLE false 0034 0035 //! default value for KDbLookupFieldSchema::maxVisibleRecords() 0036 #define KDB_LOOKUP_FIELD_DEFAULT_MAX_VISIBLE_RECORDS 8 0037 0038 //! upper limit for KDbLookupFieldSchema::maxVisibleRecords() 0039 #define KDB_LOOKUP_FIELD_LIMIT_MAX_VISIBLE_RECORDS 100 0040 0041 //! default value for KDbLookupFieldSchema::limitToList() 0042 #define KDB_LOOKUP_FIELD_DEFAULT_LIMIT_TO_LIST true 0043 0044 //! default value for KDbLookupFieldSchema::displayWidget() 0045 #define KDB_LOOKUP_FIELD_DEFAULT_DISPLAY_WIDGET KDbLookupFieldSchema::DisplayWidget::ComboBox 0046 0047 //! Record source information that can be specified for the lookup field schema 0048 //! @since 3.1 0049 class KDB_EXPORT KDbLookupFieldSchemaRecordSource 0050 { 0051 public: 0052 //! Record source type 0053 enum class Type { 0054 None, //!< used for invalid schema 0055 Table, //!< table as lookup record source 0056 Query, //!< named query as lookup record source 0057 SQLStatement, //!< anonymous query as lookup record source 0058 ValueList, //!< a fixed list of values as lookup record source 0059 KDbFieldList //!< a list of column names from a table/query will be displayed 0060 }; 0061 0062 KDbLookupFieldSchemaRecordSource(); 0063 0064 KDbLookupFieldSchemaRecordSource(const KDbLookupFieldSchemaRecordSource& other); 0065 0066 ~KDbLookupFieldSchemaRecordSource(); 0067 0068 /*! @return record source type: table, query, anonymous; in the future it will 0069 be also fixed value list and field list. The latter is basically a list 0070 of column names of a table/query, "Field List" in MSA. */ 0071 Type type() const; 0072 0073 /*! Sets record source type to @a type. */ 0074 void setType(Type type); 0075 0076 /*! @return record source type name. @see setTypeByName() */ 0077 QString typeName() const; 0078 0079 /*! Sets record source type by name using @a typeName. Accepted (case sensitive) 0080 names are "table", "query", "sql", "valuelist", "fieldlist". 0081 For other value NoType type is set. */ 0082 void setTypeByName(const QString& typeName); 0083 0084 /*! @return a string for record source: table name, query name or anonymous query 0085 provided as KDbSQL string. If recordSourceType() is a ValueList, 0086 recordSourceValues() should be used instead. If recordSourceType() is a KDbFieldList, 0087 recordSource() should return table or query name. */ 0088 QString name() const; 0089 0090 /*! Sets record source value. @see value() */ 0091 void setName(const QString& name); 0092 0093 /*! @return record source values specified if type() is ValueList. */ 0094 QStringList values() const; 0095 0096 /*! Sets record source values used if type() is ValueList. 0097 Using it clears name (see name()). */ 0098 void setValues(const QStringList& values); 0099 0100 //! Assigns @a other to this record source and returns a reference to this record source. 0101 KDbLookupFieldSchemaRecordSource& operator=(const KDbLookupFieldSchemaRecordSource& other); 0102 0103 //! @return @c true if this record source is equal to @a other; otherwise returns @c false. 0104 //! @since 3.1 0105 bool operator==(const KDbLookupFieldSchemaRecordSource &other) const; 0106 0107 //! @return @c true if this record source is not equal to @a other; otherwise returns @c false. 0108 //! @since 3.1 0109 inline bool operator!=(const KDbLookupFieldSchemaRecordSource &other) const { return !operator==(other); } 0110 0111 private: 0112 class Private; 0113 Private * const d; 0114 }; 0115 0116 //! @short Provides information about lookup field's setup. 0117 /*! 0118 KDbLookupFieldSchema object is owned by KDbTableSchema and created upon creating or retrieving the table schema 0119 from the database metadata. 0120 0121 @see KDbLookupFieldSchema *KDbTableSchema::lookupFieldSchema( KDbField& field ) const 0122 */ 0123 class KDB_EXPORT KDbLookupFieldSchema 0124 { 0125 public: 0126 KDbLookupFieldSchema(); 0127 0128 KDbLookupFieldSchema(const KDbLookupFieldSchema &schema); 0129 0130 ~KDbLookupFieldSchema(); 0131 0132 /*! @return record source information for the lookup field schema */ 0133 KDbLookupFieldSchemaRecordSource recordSource() const; 0134 0135 /*! Sets record source for the lookup field schema */ 0136 void setRecordSource(const KDbLookupFieldSchemaRecordSource& recordSource); 0137 0138 /*! @return bound column: an integer specifying a column that is bound 0139 (counted from 0). -1 means unspecified value. */ 0140 //! @todo in later implementation there can be more columns 0141 int boundColumn() const; 0142 0143 /*! Sets bound column number to @a column. @see boundColumn() */ 0144 void setBoundColumn(int column); 0145 0146 /*! @return a list of visible columns: a list of integers specifying indices (counted from 0) 0147 of columns within the row source that are visible in the combo box. 0148 Empty list means unspecified value. */ 0149 QList<int> visibleColumns() const; 0150 0151 /*! Sets a list of visible columns to \a list. @see visibleColumns() */ 0152 void setVisibleColumns(const QList<int>& list); 0153 0154 /*! A helper method. 0155 If index >= visibleColumns().count(), -1 is returned, 0156 else \a index is returned. */ 0157 int visibleColumn(int index) const; 0158 0159 /*! @return a number of ordered integers specifying column widths; 0160 -1 means 'default width' for a given column. */ 0161 QList<int> columnWidths() const; 0162 0163 /*! Sets column widths. @see columnWidths() */ 0164 void setColumnWidths(const QList<int>& widths); 0165 0166 /*! @return true if column headers are visible in the associated 0167 combo box popup or the list view. The default is false. */ 0168 bool columnHeadersVisible() const; 0169 0170 /*! Sets "column headers visibility" flag. @see columnHeadersVisible() */ 0171 void setColumnHeadersVisible(bool set); 0172 0173 /*! @return integer property specifying a maximum number of records 0174 that can be displayed in a combo box popup or a list box. The default is 0175 equal to KDB_LOOKUP_FIELD_DEFAULT_MAX_VISIBLE_RECORD_COUNT constant. */ 0176 int maxVisibleRecords() const; 0177 0178 /*! Sets maximum number of records that can be displayed in a combo box popup 0179 or a list box. If @a count is 0, KDB_LOOKUP_FIELD_DEFAULT_MAX_VISIBLE_RECORD_COUNT is set. 0180 If @a count is greater than KDB_LOOKUP_FIELD_MAX_LIST_ROWS, 0181 KDB_LOOKUP_FIELD_MAX_LIST_ROWS is set. */ 0182 void setMaxVisibleRecords(int count); 0183 0184 /*! @return true if , only values present on the list can be selected using 0185 the combo box. The default is true. */ 0186 bool limitToList() const; 0187 0188 /*! Sets "limit to list" flag. @see limitToList() */ 0189 void setLimitToList(bool set); 0190 0191 //! used in displayWidget() 0192 enum class DisplayWidget { 0193 ComboBox = 0, //!< (the default) combobox widget should be displayed in forms for this lookup field 0194 ListBox = 1 //!< listbox widget should be displayed in forms for this lookup field 0195 }; 0196 0197 /*! @return the widget type that should be displayed within 0198 the forms for this lookup field. The default is ComboBox. 0199 For the Table View, combo box is always displayed. */ 0200 DisplayWidget displayWidget() const; 0201 0202 /*! Sets type of widget to display within the forms for this lookup field. @see displayWidget() */ 0203 void setDisplayWidget(DisplayWidget widget); 0204 0205 /*! Loads data of lookup column schema from DOM tree. 0206 The data can be outdated or invalid, so the app should handle such cases. 0207 @return a new KDbLookupFieldSchema object even if lookupEl contains no valid contents. */ 0208 static KDbLookupFieldSchema* loadFromDom(const QDomElement& lookupEl); 0209 0210 /*! Saves data of lookup column schema to @a parentEl DOM element of @a doc document. 0211 Does nothing if @a doc or @a parentEl is @c nullptr. */ 0212 void saveToDom(QDomDocument *doc, QDomElement *parentEl); 0213 0214 /*! Gets property values for the lookup schema. 0215 @a values is cleared before filling. 0216 This function is used e.g. for altering table design. */ 0217 void getProperties(QMap<QByteArray, QVariant> *values) const; 0218 0219 /*! Sets property of name @a propertyName and value @a value for the lookup schema @a lookup 0220 @return true on successful set and false on failure because of invalid value or invalid property name. */ 0221 bool setProperty(const QByteArray& propertyName, const QVariant& value); 0222 0223 /*! Sets property values for the lookup schema. 0224 Properties coming from extended schema are also supported. 0225 Properties not listed are kept untouched. 0226 This function is used e.g. for altering table design. 0227 @return true on successful set and false on failure because of invalid value or invalid property name. */ 0228 bool setProperties(const QMap<QByteArray, QVariant>& values); 0229 0230 //! Assigns @a other to this lookup schema and returns a reference to this lookup schema. 0231 KDbLookupFieldSchema& operator=(const KDbLookupFieldSchema& other); 0232 0233 //! @return @c true if this lookup schema is equal to @a other; otherwise returns @c false. 0234 //! @since 3.1 0235 bool operator==(const KDbLookupFieldSchema &other) const; 0236 0237 //! @return @c true if this lookup schema is not equal to @a other; otherwise returns @c false. 0238 //! @since 3.1 0239 inline bool operator!=(const KDbLookupFieldSchema &other) const { return !operator==(other); } 0240 0241 private: 0242 class Private; 0243 Private * const d; 0244 }; 0245 0246 //! Sends lookup field schema's record source information @a source to debug output @a dbg. 0247 KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbLookupFieldSchemaRecordSource& source); 0248 0249 //! Sends lookup field schema information @a lookup to debug output @a dbg. 0250 KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbLookupFieldSchema& lookup); 0251 0252 #endif