KDb

KDbTableViewData.h
1 /* This file is part of the KDE project
2  Copyright (C) 2002 Lucijan Busch <[email protected]>
3  Copyright (C) 2003 Daniel Molkentin <[email protected]>
4  Copyright (C) 2003-2016 Jarosław Staniek <[email protected]>
5  Copyright (C) 2014 Michał Poteralski <[email protected]>
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 <[email protected]>
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 
34 class KDbCursor;
36 class KDbResultInfo;
37 class KDbTableViewColumn;
38 
40 typedef KDbTableViewDataBase::ConstIterator KDbTableViewDataConstIterator;
41 typedef KDbTableViewDataBase::Iterator KDbTableViewDataIterator;
42 
43 //! A list of records to allow configurable sorting and more.
44 /*! @todo improve API */
45 class KDB_EXPORT KDbTableViewData : public QObject, protected KDbTableViewDataBase
46 {
47  Q_OBJECT
48 public:
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
127  QList<KDbTableViewColumn*>* 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() {
273  return KDbTableViewDataBase::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 
291 public Q_SLOTS:
292  //! @internal Clean up.
293  void deleteLater();
294 
295 Q_SIGNALS:
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. */
313  void aboutToUpdateRecord(KDbRecordData *record, KDbRecordEditBuffer* buffer,
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
329  void recordDeleted();
330 
331  //! Records have been deleted
332  void recordsDeleted(const QList<int> &recordsToDelete);
333 
334  //! Displayed data needs to be reloaded in all presenters.
335  void reloadRequested();
336 
337  void recordRepaintRequested(KDbRecordData*);
338 
339 protected:
340  //! Used by KDbTableViewColumn::setVisible()
341  void columnVisibilityChanged(const KDbTableViewColumn &column);
342 
343 private:
344  //! @internal for saveRecordChanges() and saveNewRecord()
345  bool saveRecord(KDbRecordData *record, bool insert, bool repaint);
346 
347  friend class KDbTableViewColumn;
348 
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
356 KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbTableViewData &data);
357 
358 #endif
void append(const T &value)
Provides database cursor functionality.
Definition: KDbCursor.h:68
Autodeleting list.
Definition: KDbUtils.h:244
KCALENDARCORE_EXPORT QDataStream & operator<<(QDataStream &out, const KCalendarCore::Alarm::Ptr &)
Q_SLOTSQ_SLOTS
@ Text
Definition: KDbField.h:98
Definition of a single column for table view.
QList::const_iterator constBegin() const const
A list of records to allow configurable sorting and more.
void deleteLater()
void prepend(const T &value)
int count() const const
int indexOf(const T &value, int from) const const
const T & at(int i) const const
bool isEmpty() const const
provides data for single edited database record
Q_SIGNALSQ_SIGNALS
typedef ConstIterator
void reload()
Emits reloadRequested() signal to reload presenters.
typedef Iterator
Structure for storing single record with type information.
Definition: KDbRecordData.h:36
QList::const_iterator constEnd() const const
QList::iterator begin()
SortOrder
Column sort order.
QList::iterator end()
Q_DISABLE_COPY(Class)
QVector< V > values(const QMultiHash< K, V > &c)
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Wed Sep 27 2023 04:08:32 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.