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