File indexing completed on 2024-06-23 11:12:20

0001 /* This file is part of the KDE project
0002    Copyright (C) 2002 Lucijan Busch <lucijan@gmx.at>
0003    Copyright (C) 2003 Daniel Molkentin <molkentin@kde.org>
0004    Copyright (C) 2003-2017 Jarosław Staniek <staniek@kde.org>
0005 
0006    This program is free software; you can redistribute it and/or
0007    modify it under the terms of the GNU Library General Public
0008    License as published by the Free Software Foundation; either
0009    version 2 of the License, or (at your option) any later version.
0010 
0011    This program is distributed in the hope that it will be useful,
0012    but WITHOUT ANY WARRANTY; without even the implied warranty of
0013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0014    Library General Public License for more details.
0015 
0016    You should have received a copy of the GNU Library General Public License
0017    along with this program; see the file COPYING.  If not, write to
0018    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
0019  * Boston, MA 02110-1301, USA.
0020 
0021    Original Author:  Till Busch <till@bux.at>
0022    Original Project: buX (www.bux.at)
0023 */
0024 
0025 #ifndef KDB_TABLEVIEWCOLUMN_H
0026 #define KDB_TABLEVIEWCOLUMN_H
0027 
0028 #include "kdb_export.h"
0029 
0030 #include "KDbField.h"
0031 
0032 class KDbQueryColumnInfo;
0033 class KDbQuerySchema;
0034 class KDbTableViewColumn;
0035 class KDbTableViewData;
0036 class KDbValidator;
0037 
0038 //! Definition of a single column for table view.
0039 /*! @todo improve API */
0040 class KDB_EXPORT KDbTableViewColumn
0041 {
0042 public:
0043     /*! Specifies if the associated KDbField object is owned by the column so it will be
0044      automatically destroyed when needed by this column. */
0045     enum class FieldIsOwned {
0046         Yes,
0047         No
0048     };
0049 
0050     /*! Not db-aware ctor. if @a isOwned is Yes, the field @a will be owned by this column so it will be
0051      automatically destroyed when needed by this column. */
0052     explicit KDbTableViewColumn(KDbField *f, FieldIsOwned isOwned = FieldIsOwned::No);
0053 
0054     /*! Not db-aware, convenience ctor, like above. The field is created using specified parameters that are
0055      equal to these accepted by KDbField ctor. The column will be the owner
0056      of this automatically generated field.
0057      */
0058     KDbTableViewColumn(const QString &name, KDbField::Type ctype,
0059                     KDbField::Constraints cconst = KDbField::NoConstraints,
0060                     KDbField::Options options = KDbField::NoOptions,
0061                     int maxLength = 0, int precision = 0,
0062                     QVariant defaultValue = QVariant(),
0063                     const QString &caption = QString(),
0064                     const QString &description = QString());
0065 
0066     /*! Not db-aware, convenience ctor, simplified version of the above. */
0067     KDbTableViewColumn(const QString &name, KDbField::Type ctype, const QString &caption,
0068                     const QString &description = QString());
0069 
0070     //! Db-aware version.
0071     KDbTableViewColumn(const KDbQuerySchema &query, KDbQueryColumnInfo *aColumnInfo,
0072                     KDbQueryColumnInfo *aVisibleLookupColumnInfo = nullptr);
0073 
0074     virtual ~KDbTableViewColumn();
0075 
0076     virtual bool acceptsFirstChar(const QChar &ch) const;
0077 
0078     /*! @return true if the column is read-only
0079      For db-aware column this can depend on whether the column
0080      is in parent table of this query. @see setReadOnly() */
0081     bool isReadOnly() const;
0082 
0083     //! forces readOnly flag to be set to @a ro
0084     //! @todo synchronize this with table view:
0085     void setReadOnly(bool ro);
0086 
0087     //! Column visibility. By default column is visible.
0088     bool isVisible() const;
0089 
0090     //! Changes column visibility.
0091     //! KDbTableViewData is informed about this change.
0092     //! @todo react on changes of KDbQueryColumnInfo::visible too
0093     void setVisible(bool v);
0094 
0095     /*! Sets icon for displaying in the caption area (header). */
0096     void setIcon(const QIcon &icon);
0097 
0098     /*! @return bame of icon displayed in the caption area (header). */
0099     QIcon icon() const;
0100 
0101     /*! If @a visible is true, caption has to be displayed in the column's header,
0102      (or field's name if caption is empty. True by default. */
0103     void setHeaderTextVisible(bool visible);
0104 
0105     /*! @return true if caption has to be displayed in the column's header,
0106      (or field's name if caption is empty. */
0107     bool isHeaderTextVisible() const;
0108 
0109     /*! @return whatever is available:
0110      - field's caption
0111      - or field's alias (from query)
0112      - or finally - field's name */
0113     QString captionAliasOrName() const;
0114 
0115     /*! Assigns validator @a v for this column.
0116      If the validator has no parent object, it will be owned by the column,
0117      so you don't need to care about destroying it. */
0118     void setValidator(KDbValidator *v);
0119 
0120     //! @return validator assigned for this column of 0 if there is no validator assigned.
0121     KDbValidator* validator() const;
0122 
0123     /*! For not-db-aware data only:
0124      Sets related data @a data for this column, what defines simple one-field,
0125      one-to-many relationship between this column and the primary key in @a data.
0126      The relationship will be used to generate a popup editor instead of just regular editor.
0127      This assignment has no result if @a data has no primary key defined.
0128      @a data is owned, so is will be destroyed when needed. It is also destroyed
0129      when another data (or @c nullptr) is set for the same column. */
0130     void setRelatedData(KDbTableViewData *data);
0131 
0132     /*! For not-db-aware data only:
0133      Related data @a data for this column, what defines simple one-field.
0134      @c nullptr by default. @see setRelatedData() */
0135     KDbTableViewData *relatedData();
0136 
0137     //! @overload
0138     const KDbTableViewData *relatedData() const;
0139 
0140     /*! @return field for this column.
0141      For db-aware information is taken from columnInfo(). */
0142     KDbField* field();
0143 
0144     //! @overload
0145     const KDbField* field() const;
0146 
0147     /*! Only usable if related data is set (ie. this is for combo boxes).
0148      Sets 'editable' flag for this column, what means a new value can be entered
0149      by hand. This is similar to QComboBox::setEditable(). */
0150     void setRelatedDataEditable(bool set);
0151 
0152     /*! Only usable if related data is set (ie. this is for combo boxes).
0153      @return 'editable' flag for this column.
0154      False by default. @see setRelatedDataEditable(bool). */
0155     bool isRelatedDataEditable() const;
0156 
0157     /*! A rich field information for db-aware data.
0158      For not-db-aware data it is always 0 (use field() instead). */
0159     KDbQueryColumnInfo* columnInfo();
0160 
0161     //! @overload
0162     const KDbQueryColumnInfo* columnInfo() const;
0163 
0164     /*! A rich field information for db-aware data. Specifies information for a column
0165      that should be visible instead of columnInfo. For example case see
0166      @ref KDbQueryColumnInfo::Vector KDbQuerySchema::fieldsExpanded(KDbQuerySchema::FieldsExpandedMode mode = Default)
0167 
0168      For not-db-aware data it is always @c nullptr. */
0169     KDbQueryColumnInfo* visibleLookupColumnInfo();
0170 
0171     //! @overload
0172     const KDbQueryColumnInfo* visibleLookupColumnInfo() const;
0173 
0174     //! @return true if data is stored in DB, not only in memeory.
0175     bool isDBAware() const;
0176 
0177     /*! Sets visible width for this column to @a w (usually in pixels or points).
0178         0 means there is no hint for the width. */
0179     void setWidth(int w);
0180 
0181     /*! @return width of this field (usually in pixels or points).
0182          0 (the default) means there is no hint for the width. */
0183     int width() const;
0184 
0185 protected:
0186     //! special ctor that does not allocate d member;
0187     explicit KDbTableViewColumn(bool);
0188 
0189     //! used by KDbTableViewData::addColumn()
0190     void setData(KDbTableViewData *data);
0191 
0192 private:
0193     class Private;
0194     Private * const d;
0195 
0196     friend class KDbTableViewData;
0197     friend KDB_EXPORT QDebug operator<<(QDebug, const KDbTableViewColumn&);
0198     Q_DISABLE_COPY(KDbTableViewColumn)
0199 };
0200 
0201 //! Sends information about column @a column to debug output @a dbg.
0202 //! @since 3.1
0203 KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbTableViewColumn &column);
0204 
0205 #endif