KDb

KDbTableViewData.h
1/* This file is part of the KDE project
2 Copyright (C) 2002 Lucijan Busch <lucijan@gmx.at>
3 Copyright (C) 2003 Daniel Molkentin <molkentin@kde.org>
4 Copyright (C) 2003-2016 Jarosław Staniek <staniek@kde.org>
5 Copyright (C) 2014 Michał Poteralski <michalpoteralskikde@gmail.com>
6
7 This program is free software; you can redistribute it and/or
8 modify it under the terms of the GNU Library General Public
9 License as published by the Free Software Foundation; either
10 version 2 of the License, or (at your option) any later version.
11
12 This program is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 Library General Public License for more details.
16
17 You should have received a copy of the GNU Library General Public License
18 along with this program; see the file COPYING. If not, write to
19 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
20 * Boston, MA 02110-1301, USA.
21
22 Original Author: Till Busch <till@bux.at>
23 Original Project: buX (www.bux.at)
24*/
25
26#ifndef KDB_TABLEVIEWDATA_H
27#define KDB_TABLEVIEWDATA_H
28
29#include "KDbField.h"
30#include "KDbUtils.h"
31#include "KDbRecordData.h"
32#include "KDbOrderByColumn.h"
33
34class KDbCursor;
36class KDbResultInfo;
38
40typedef KDbTableViewDataBase::ConstIterator KDbTableViewDataConstIterator;
41typedef KDbTableViewDataBase::Iterator KDbTableViewDataIterator;
42
43//! A list of records to allow configurable sorting and more.
44/*! @todo improve API */
45class KDB_EXPORT KDbTableViewData : public QObject, protected KDbTableViewDataBase
46{
47 Q_OBJECT
48public:
49 //! Non-db-aware version
51
52 //! Db-aware version. The cursor is not owned by the data.
53 explicit KDbTableViewData(KDbCursor *c);
54
55 /*! Defines two-column table usually used with comboboxes.
56 First column is invisible and contains key values.
57 Second column and contains user-visible value.
58 @param keys a list of keys
59 @param values a list of text values (must be of the same length as keys list)
60 @param keyType a type for keys
61 @param valueType a type for values
62
63 @todo make this more generic: allow to add more columns! */
65 const QList<QVariant> &keys, const QList<QVariant> &values,
67
68 /*! Like above constructor, but keys and values are not provided.
69 You can do this later by calling append(KDbRecordData*) method.
70 (KDbRecordData object must have exactly two columns) */
72
73 ~KDbTableViewData() override;
74
75 /*! Preloads all records provided by cursor (only for db-aware version). */
76 bool preloadAllRecords();
77
78 /*! Sets sorting for @a column. If @a column is -1, sorting is disabled. */
79 void setSorting(int column, KDbOrderByColumn::SortOrder order = KDbOrderByColumn::SortOrder::Ascending);
80
81 /*! @return the column number by which the data is sorted,
82 or -1 if sorting is disabled.
83 Initial sorted column number for data after instantiating object is -1. */
84 int sortColumn() const;
85
86 /*! @return sorting order. This is independent of whether the data is actually sorted.
87 sortColumn() should be checked first to see if sorting for any column is enabled
88 (by default it is not). */
89 KDbOrderByColumn::SortOrder sortOrder() const;
90
91 //! Sorts this data using previously set order.
92 void sort();
93
94 /*! Adds column @a col.
95 Warning: @a col will be owned by this object, and deleted on its destruction. */
96 void addColumn(KDbTableViewColumn* col);
97
98 //! @return Index of visible column @a visibleIndex on global list.
99 int globalIndexOfVisibleColumn(int visibleIndex) const;
100
101 //! @return Index on list of visible columns for column @a globalIndex
102 //! or -1 if column at @a globalIndex is not visible.
103 int visibleColumnIndex(int globalIndex) const;
104
105 /*! @return true if this db-aware data set. */
106 /*! @todo virtual? */
107 bool isDBAware() const;
108
109 /*! For db-aware data set only: table name is returned;
110 equivalent to cursor()->query()->parentTable()->name(). */
111 QString dbTableName() const;
112
113 KDbCursor* cursor() const;
114
115 int columnCount() const;
116
117 //! @return number of visible columns
118 int visibleColumnCount() const;
119
120 //! @return column at index @a index (visible or not)
121 KDbTableViewColumn* column(int c);
122
123 //! @return visible column at index @a index
124 KDbTableViewColumn* visibleColumn(int index);
125
126 //! @return list of all columns
128
129 //! @return list of visible columns
130 QList<KDbTableViewColumn*>* visibleColumns();
131
132 /*! @return true if data is not editable. Can be set using setReadOnly()
133 but it's still true if database cursor returned by cursor()
134 is not 0 and has read-only connection. */
135 virtual bool isReadOnly() const;
136
137 /*! Sets readOnly flag for this data.
138 If @a set is true, insertingEnabled flag will be cleared automatically.
139 @see isInsertingEnabled() */
140 virtual void setReadOnly(bool set);
141
142 /*! @return true if data inserting is enabled (the default). */
143 virtual bool isInsertingEnabled() const;
144
145 /*! Sets insertingEnabled flag. If true, empty record is available
146 If @a set is true, read-only flag will be cleared automatically.
147 @see setReadOnly() */
148 virtual void setInsertingEnabled(bool set);
149
150 /*! Clears and initializes internal record edit buffer for incoming editing.
151 Creates buffer using recordEditBuffer(false) (false means not db-aware type)
152 if our data is not db-aware,
153 or db-aware buffer if data is db-aware (isDBAware()==true).
154 @see KDbRecordEditBuffer */
155 void clearRecordEditBuffer();
156
157 /*! Updates internal record edit buffer: currently edited column @a col (number @a colnum)
158 has now assigned new value of @a newval.
159 Uses column's caption to address the column in buffer
160 if the buffer is of simple type, or db-aware buffer if (isDBAware()==true).
161 (then fields are addressed with KDbField, instead of caption strings).
162 If @a allowSignals is true (the default), aboutToChangeCell() signal is emitted.
163 @a visibleValueForLookupField allows to pass visible value (usually a text)
164 for a lookup field (only reasonable if col->visibleLookupColumnInfo != 0).
165 Note that @a newval may be changed in aboutToChangeCell() signal handler.
166 If either @a record or @a col or @a newval is @c nullptr, @c false is returned.
167 @see KDbRecordEditBuffer */
168 bool updateRecordEditBufferRef(KDbRecordData *record,
169 int colnum, KDbTableViewColumn* col, QVariant* newval,
170 bool allowSignals = true,
171 QVariant *visibleValueForLookupField = nullptr);
172
173 /*! Added for convenience. Like above but @a newval is passed by value. */
174 bool updateRecordEditBuffer(KDbRecordData *record, int colnum, KDbTableViewColumn* col,
175 const QVariant &newval, bool allowSignals = true);
176
177 /*! Added for convenience. Like above but it's assumed that @a record record's columns
178 are ordered like in table view, not like in form view. Don't use this with form views. */
179 bool updateRecordEditBuffer(KDbRecordData *record, int colnum,
180 const QVariant &newval, bool allowSignals = true);
181
182 //! @return record edit buffer for currently edited record. Can be 0 or empty.
183 KDbRecordEditBuffer* recordEditBuffer() const;
184
185 /*! @return last operation's result information (always not null). */
186 const KDbResultInfo& result() const;
187
188 bool saveRecordChanges(KDbRecordData *record, bool repaint = false);
189
190 bool saveNewRecord(KDbRecordData *record, bool repaint = false);
191
192 bool deleteRecord(KDbRecordData *record, bool repaint = false);
193
194 /*! Deletes records (by number) passed with @a recordsToDelete.
195 Currently, this method is only for non data-aware tables. */
196 void deleteRecords(const QList<int> &recordsToDelete, bool repaint = false);
197
198 /*! Deletes all records. Works either for db-aware and non db-aware tables.
199 Column's definition is not changed.
200 For db-aware version, all records are removed from a database.
201 Record-edit buffer is cleared.
202
203 If @a repaint is true, reloadRequested() signal
204 is emitted after deleting (if at least one record was deleted),
205 so presenters can repaint their contents.
206
207 @return true on success. */
208 virtual bool deleteAllRecords(bool repaint = false);
209
210 /*! @internal method, used mostly by specialized classes like KexiTableView.
211 Clears internal record structures. Record-edit buffer is cleared.
212 Does not touch data @ database backend.
213 Use deleteAllRecords() to safely delete all records. */
214 virtual void clearInternal(bool processEvents = true);
215
216 /*! Inserts new @a record at index @a index.
217 @a record will be owned by this data object.
218 Note: Reasonable only for not not-db-aware version. */
219 void insertRecord(KDbRecordData *record, int index, bool repaint = false);
220
221 //! @todo add this as well? void insertRecord(KDbRecordData *record, KDbRecordData *aboveRecord)
222
223 //! @return index of autoincremented column. The result is cached.
224 //! @todo what about multiple autoinc columns?
225 //! @todo what about changing column order?
226 int autoIncrementedColumn() const;
227
228 //! Emits reloadRequested() signal to reload presenters.
229 void reload() {
230 emit reloadRequested();
231 }
232
233 inline KDbRecordData* at(int index) {
234 return KDbTableViewDataBase::at(index);
235 }
236 inline virtual int count() const {
238 }
239 inline bool isEmpty() const {
241 }
242 inline KDbRecordData* first() {
244 }
245 inline KDbRecordData* last() {
247 }
248 inline int indexOf(const KDbRecordData* record, int from = 0) const {
249 return KDbTableViewDataBase::indexOf(const_cast<KDbRecordData*>(record), from);
250 }
251 inline void removeFirst() {
252 KDbTableViewDataBase::removeFirst();
253 }
254 inline void removeLast() {
255 KDbTableViewDataBase::removeLast();
256 }
257 inline void append(KDbRecordData* record) {
259 }
260 inline void prepend(KDbRecordData* record) {
262 }
263 inline KDbTableViewDataConstIterator constBegin() const {
265 }
266 inline KDbTableViewDataConstIterator constEnd() const {
268 }
269 inline KDbTableViewDataIterator begin() {
271 }
272 inline KDbTableViewDataIterator end() {
274 }
275
276 /*! @return true if ROWID information is stored within every record.
277 Only reasonable for db-aware version. ROWID information is available
278 if KDbDriverBehavior::ROW_ID_FIELD_RETURNS_LAST_AUTOINCREMENTED_VALUE == false
279 for a KDb database driver and a table has no primary key defined.
280 Phisically, ROWID information is stored after last KDbRecordData's element,
281 so every KDbRecordData's length is expanded by one. */
282 bool containsRecordIdInfo() const;
283
284 //! Creates a single record data with proper number of columns.
285 KDbRecordData* createItem() const;
286
287 //! @return reusable i18n'd message
288 //! "Please correct data in this record or use the \"Cancel record changes\" function."
289 static QString messageYouCanImproveData();
290
291public Q_SLOTS:
292 //! @internal Clean up.
293 void deleteLater();
294
296 void destroying();
297
298 /*! Emitted before change of the single, currently edited cell.
299 Connect this signal to your slot and set @a result->success to false
300 to disallow this change. You can also change @a newValue to other value,
301 or change other columns in @a record. */
302 void aboutToChangeCell(KDbRecordData *record, int colnum, QVariant* newValue,
303 KDbResultInfo* result);
304
305 /*! Emitted before inserting of a new, current record.
306 Connect this signal to your slot and set @a result->success to false
307 to disallow this inserting. You can also change columns in @a record. */
308 void aboutToInsertRecord(KDbRecordData *record, KDbResultInfo* result, bool repaint);
309
310 /*! Emitted before changing of an edited, current record.
311 Connect this signal to your slot and set @a result->success to false
312 to disallow this change. You can also change columns in @a record. */
314 KDbResultInfo* result);
315
316 void recordUpdated(KDbRecordData*); //!< Current record has been updated
317
318 void recordInserted(KDbRecordData*, bool repaint); //!< A record has been inserted
319
320 //! A record has been inserted at @a index position (not db-aware data only)
321 void recordInserted(KDbRecordData*, int index, bool repaint);
322
323 /*! Emitted before deleting of a current record.
324 Connect this signal to your slot and set @a result->success to false
325 to disallow this deleting. */
326 void aboutToDeleteRecord(KDbRecordData *record, KDbResultInfo* result, bool repaint);
327
328 //! Current record has been deleted
330
331 //! Records have been deleted
332 void recordsDeleted(const QList<int> &recordsToDelete);
333
334 //! Displayed data needs to be reloaded in all presenters.
336
337 void recordRepaintRequested(KDbRecordData*);
338
339protected:
340 //! Used by KDbTableViewColumn::setVisible()
341 void columnVisibilityChanged(const KDbTableViewColumn &column);
342
343private:
344 //! @internal for saveRecordChanges() and saveNewRecord()
345 bool saveRecord(KDbRecordData *record, bool insert, bool repaint);
346
347 friend class KDbTableViewColumn;
348
349 Q_DISABLE_COPY(KDbTableViewData)
350 class Private;
351 Private * const d;
352};
353
354//! Sends information about data @a data to debug output @a dbg.
355//! @since 3.1
356KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbTableViewData &data);
357
358#endif
Provides database cursor functionality.
Definition KDbCursor.h:69
SortOrder
Column sort order.
Structure for storing single record with type information.
provides data for single edited database record
Definition of a single column for table view.
A list of records to allow configurable sorting and more.
void recordUpdated(KDbRecordData *)
Current record has been updated.
void aboutToInsertRecord(KDbRecordData *record, KDbResultInfo *result, bool repaint)
void aboutToChangeCell(KDbRecordData *record, int colnum, QVariant *newValue, KDbResultInfo *result)
void recordInserted(KDbRecordData *, bool repaint)
A record has been inserted.
void aboutToUpdateRecord(KDbRecordData *record, KDbRecordEditBuffer *buffer, KDbResultInfo *result)
void recordInserted(KDbRecordData *, int index, bool repaint)
A record has been inserted at index position (not db-aware data only)
void aboutToDeleteRecord(KDbRecordData *record, KDbResultInfo *result, bool repaint)
void reload()
Emits reloadRequested() signal to reload presenters.
void recordsDeleted(const QList< int > &recordsToDelete)
Records have been deleted.
void reloadRequested()
Displayed data needs to be reloaded in all presenters.
void recordDeleted()
Current record has been deleted.
Autodeleting list.
Definition KDbUtils.h:245
typedef ConstIterator
typedef Iterator
void append(QList< T > &&value)
const_reference at(qsizetype i) const const
iterator begin()
const_iterator constBegin() const const
const_iterator constEnd() const const
qsizetype count() const const
iterator end()
qsizetype indexOf(const AT &value, qsizetype from) const const
bool isEmpty() const const
void prepend(parameter_type value)
Q_SIGNALSQ_SIGNALS
Q_SLOTSQ_SLOTS
void deleteLater()
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jul 12 2024 12:05:29 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.