Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
qrangemodeladapter.qdoc
Go to the documentation of this file.
1// Copyright (C) 2025 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3// Qt-Security score:insignificant reason:default
4
5#include <QtCore/qrangemodeladapter.h>
6
7/*!
8 \class QRangeModelAdapter
9 \inmodule QtCore
10 \since 6.11
11 \preliminary
12 \ingroup model-view
13 \brief QRangeModelAdapter provides QAbstractItemModel-compliant access to any C++ range.
14 \compares equality
15 \compareswith equality Range
16 \endcompareswith
17
18 QRangeModelAdapter provides a type-safe and structure-aware C++ API around
19 a C++ range and a QRangeModel. Modifications made to the C++ range using
20 the adapter will inform clients of the QRangeModel about the changes. This
21 makes sure that item views are updated, caches are cleaned, and persistent
22 item indexes are invalidated and adapted correctly.
23
24 \section1 Construction and model ownership
25
26 QRangeModelAdapter has to be constructed from a C++ range. As with
27 QRangeModel, the range can be provided by lvalue or rvalue reference, as a
28 reference wrapper, and as a raw or smart pointer.
29
30 \snippet qrangemodeladapter/main.cpp construct
31
32 Constructing the adapter from a range implicitly constructs a QRangeModel
33 instance from that same range. Use model() to get it, and pass it to Qt
34 Widgets or Qt Quick item views as usual.
35
36 \snippet qrangemodeladapter/main.cpp use-model
37
38 The adapter owns the model. QRangeModelAdapter is a value type, so it can be
39 copied and moved. All copies share the same QRangeModel, which will be
40 destroyed when the last copy of the adapter is destroyed.
41
42 If the adapter was created from an lvalue or rvalue reference, then the
43 adapter and model will operate on a copy of the original range object.
44 Otherwise, modifications made through the adapter or model will be written
45 to the original range object. To get the updated range, use the range()
46 function explicitly, or use the implicit conversion of the adapter to a
47 the range.
48
49 \snippet qrangemodeladapter/main.cpp get-range
50
51 To replace the entire range data with data from another (compatible) range,
52 use the setRange() function or the assignment operator.
53
54 \snippet qrangemodeladapter/main.cpp set-range
55
56 \section1 Accessing item data
57
58 The QRangeModelAdapter API provides type-safe read and write access to the
59 range that the model operates on. The adapter API is based on the typical
60 API for C++ containers and ranges, including iterators. To access
61 individual rows and items, use at(), the corresponding subscript
62 \c{operator[]}, or data(). Which overloads of those functions are available
63 depends on the range for which the adapter was constructed.
64
65 \section2 Reading item data as a QVariant
66
67 The data() function always returns a QVariant with the value stored at the
68 specified position and role. In a list, an item can be accessed by a single
69 integer value specifying the row:
70
71 \snippet qrangemodeladapter/main.cpp list-data
72
73 If the range is a table, then items are specified by row and column:
74
75 \snippet qrangemodeladapter/main.cpp table-data
76
77 If the range is a tree, then items are located using a path of rows, and a
78 single column value:
79
80 \snippet qrangemodeladapter/main.cpp tree-data
81
82 Using a single integer as the row provides access to the toplevel tree
83 items.
84
85 \snippet qrangemodeladapter/main.cpp multirole-data
86
87 If no role is specified, then the QVariant will hold the entire item at the
88 position. Use the \l{QVariant::fromValue()} template function to retrieve a
89 copy of the item.
90
91 \section2 Reading and writing using at()
92
93 That the data() function returns a QVariant makes it flexible, but removes
94 type safety. For ranges where all items are of the same type, the at()
95 function provides a type-safe alternative that is more compatible with
96 regular C++ containers. As with data(), at() overloads exist to access an
97 item at a row for lists, at a row/column pair for table, and a path/column
98 pair for trees. However, at() always returns the whole item at the
99 specified position; it's not possible to read an individual role values for
100 an item.
101
102 As expected from a C++ container API, the const overloads of at() (and the
103 corresponding subscript \c{operator[]}) provide immutable access to the
104 value, while the mutable overloads return a reference object that a new
105 value can be assigned to. Note that a QRangeModelAdapter operating on a
106 const range behaves in that respect like a const QRangeModelAdapter. The
107 mutable overloads are removed from the overload set, so the compiler will
108 always select the const version. Trying to call a function that modifies a
109 range will result in a compiler error, even if the adapter itself is
110 mutable:
111
112 \snippet qrangemodeladapter/main.cpp read-only
113
114 The returned reference objects are wrappers that convert implicitly to the
115 underlying type, have a \c{get()} function to explicitly access the
116 underlying value, and an \c{operator->()} that provides direct access to
117 const member functions. However, to prevent accidental data changes that
118 would bypass the QAbstractItemModel notification protocol, those reference
119 objects prevent direct modifications of the items.
120
121 \note Accessing the reference object always makes a call to the model to get
122 a copy of the value. This can be expensive; for performance critical access
123 to data, store a copy.
124
125 \section3 Item access
126
127 If the range is represented as a list, then only the overloads taking a row
128 are available.
129
130 \snippet qrangemodeladapter/main.cpp list-access
131
132 The const overload returns the item at that row, while the mutable overload
133 returns a wrapper that implicitly converts to and from the value type of the
134 list.
135
136 \snippet qrangemodeladapter/main.cpp list-access-multirole
137
138 Assign a value to the wrapper to modify the data in the list. The model will
139 emit \l{QAbstractItemModel::}{dataChanged()} for all roles.
140
141 When using the mutable overloads, you can also access the item type's const
142 members using the overloaded arrow operator.
143
144 \snippet qrangemodeladapter/main.cpp list-access-multirole-member-access
145
146 It is not possible to access non-const members of the item. Such
147 modifications would bypass the adapter, which couldn't notify the model
148 about the changes. To modify the value stored in the model, make a copy,
149 modify the properties of the copy, and then write that copy back.
150
151 \snippet qrangemodeladapter/main.cpp list-access-multirole-write-back
152
153 This will make the model emit \l{QAbstractItemModel::}{dataChanged()} for
154 this item, and for all roles.
155
156 If the range is represented as a table, then you can access an individual
157 item by row and columns, using the \l{at(int, int)}{at(row, column)}
158 overload. For trees, that overload gives access to top-level items, while
159 the \l{at(QSpan<const int>, int)}{at(path, column)} overload provides
160 access to items nested within the tree.
161
162 Accessing an individual item in a table or tree is equivalent to accessing
163 an item in a list.
164
165 \snippet qrangemodeladapter/main.cpp table-item-access
166
167 If the range doesn't store all columns using the same data type, then
168 \c{at(row,column)} returns a (a reference wrapper with a) QVariant holding
169 the item.
170
171 \snippet qrangemodeladapter/main.cpp table-mixed-type-access
172
173 \section2 Accessing rows in tables and trees
174
175 For tables and trees, the overloads of at() and subscript \c{operator[]}
176 without the column parameter provide access to the entire row. The value
177 returned by the const overloads will be a reference type that gives access
178 to the row data. If that row holds pointers, then that reference type will
179 be a view of the row, giving access to pointers to const items.
180
181 \section3 Table row access
182
183 The \l{at(int)} overload is still available, but it returns the entire table
184 wor. This makes it possible to work with all the values in the row at once.
185
186 \snippet qrangemodeladapter/main.cpp table-row-const-access
187
188 As with items, the const overload provides direct access to the row type,
189 while the mutable overload returns a wrapper that acts as a reference to the
190 row. The wrapper provides access to const member functions using the
191 overloaded arrow operator. To modify the values, write a modified row type
192 back.
193
194 \snippet qrangemodeladapter/main.cpp table-row-access
195
196 When assigning a new value to the row, then the model emits the
197 \l{QAbstractItemModel::}{dataChanged()} signal for all items in the row,
198 and for all roles.
199
200 \note When using a row type with runtime sizes, such as a \c{std::vector} or
201 a QList, make sure that the new row has the correct size.
202
203 \section3 Tree row access
204
205 Rows in trees are specified by a sequence of integers, one entry for each
206 level in the tree. Note that in the following snippets, the Tree is a range
207 holding raw row pointers, and that the adapter is created with an rvalue
208 reference of that range. This gives the QRangeModel ownership over the row
209 data.
210
211 \snippet qrangemodeladapter/main.cpp tree-row-access
212
213 The overload of \l{at(int)}{at()} taking a single row value provides
214 access to the top-level rows, or items in the top-level rows.
215
216 \snippet qrangemodeladapter/main.cpp tree-item-access
217
218 The basic pattern for accessing rows and items in a tree is identical to
219 accessing rows and items in a table. However, the adapter will make sure
220 that the tree structure is maintained when modifying entire rows.
221
222 \snippet qrangemodeladapter/main.cpp tree-row-write
223
224 In this example, a new row object is created, and assigned to the first
225 child of the first top-level item.
226
227 \section1 Iterator API
228
229 Use begin() and end() to get iterators over the rows of the model, or use
230 ranged-for. If the range is a list of items, dereferencing the iterator
231 will give access to item data.
232
233 \snippet qrangemodeladapter/main.cpp ranged-for-const-list
234
235 As with the const and mutable overloads of at(), a mutable iterator will
236 dereference to a wrapper.
237
238 \snippet qrangemodeladapter/main.cpp ranged-for-mutable-list
239
240 Use the overloaded arrow operator to access const members of the item type,
241 and assign to the wrapper to replace the value.
242
243 It the range is a table or tree, then iterating over the model will give
244 access to the rows.
245
246 \snippet qrangemodeladapter/main.cpp ranged-for-const-table
247
248 Both the const and the mutable iterator will dereference to a wrapper type
249 for the row. This make sure that we can consistently iterate over each
250 column, even if the underlying row type is not a range (e.g. it might be a
251 tuple or gadget).
252
253 \snippet qrangemodeladapter/main.cpp ranged-for-const-table-items
254
255 When iterating over a mutable table we can overwrite the entire row.
256
257 \snippet qrangemodeladapter/main.cpp ranged-for-mutable-table
258
259 The model emits the \l{QAbstractItemModel::}{dataChanged()} signal for
260 all items in all row, and for all roles.
261
262 \snippet qrangemodeladapter/main.cpp ranged-for-mutable-table-items
263
264 Iterating over the mutable rows allows us to modify individual items.
265
266 When iterating over a tree, the row wrapper has two additional member
267 functions, hasChildren() and children(), that allow us to traverse the
268 entire tree using iterators.
269
270 \snippet qrangemodeladapter/main.cpp ranged-for-tree
271
272 The object returned by children() is a QRangeModelAdapter operating on
273 the same model as the callee, but all operations will use the source row
274 index as the parent index.
275
276 \sa QRangeModel
277*/
278
279/*!
280 \typedef QRangeModelAdapter::range_type
281*/
282
283/*!
284 \fn template <typename Range, typename Protocol, typename Model> QRangeModelAdapter<Range, Protocol, Model>::QRangeModelAdapter(Range &&range, Protocol &&protocol)
285 \fn template <typename Range, typename Protocol, typename Model> QRangeModelAdapter<Range, Protocol, Model>::QRangeModelAdapter(Range &&range)
286
287 Constructs a QRangeModelAdapter that operates on \a range. For tree ranges,
288 the optional \a protocol will be used for tree traversal.
289*/
290
291/*!
292 \fn template <typename Range, typename Protocol, typename Model> bool QRangeModelAdapter<Range, Protocol, Model>::operator==(const QRangeModelAdapter &lhs, const QRangeModelAdapter &rhs)
293
294 \return whether \a lhs is equal to \a rhs. Two adapters are equal if they
295 both hold the same \l{model()}{model} instance.
296*/
297
298/*!
299 \fn template <typename Range, typename Protocol, typename Model> bool QRangeModelAdapter<Range, Protocol, Model>::operator!=(const QRangeModelAdapter &lhs, const QRangeModelAdapter &rhs)
300
301 \return whether \a lhs is not equal to \a rhs. Two adapters are equal if
302 they both hold the same \l{model()}{model} instance.
303*/
304
305/*!
306 \fn template <typename Range, typename Protocol, typename Model> Model *QRangeModelAdapter<Range, Protocol, Model>::model() const
307
308 \return the QRangeModel instance created by this adapter.
309
310 \sa range(), at()
311*/
312
313/*!
314 \fn template <typename Range, typename Protocol, typename Model> const QRangeModelAdapter<Range, Protocol, Model>::range_type &QRangeModelAdapter<Range, Protocol, Model>::range() const
315 \fn template <typename Range, typename Protocol, typename Model> QRangeModelAdapter<Range, Protocol, Model>::operator const QRangeModelAdapter<Range, Protocol, Model>::range_type &() const
316
317 \return a const reference to the range that the model adapter operates on.
318
319 \sa setRange(), at(), model()
320*/
321
322/*!
323 \fn template <typename Range, typename Protocol, typename Model> template <typename NewRange, QRangeModelAdapter<Range, Protocol, Model>::if_assignable_range<NewRange>> void QRangeModelAdapter<Range, Protocol, Model>::setRange(NewRange &&newRange)
324 \fn template <typename Range, typename Protocol, typename Model> template <typename NewRange, QRangeModelAdapter<Range, Protocol, Model>::if_assignable_range<NewRange>, QRangeModelAdapter<Range, Protocol, Model>::unless_adapter<NewRange>> QRangeModelAdapter &QRangeModelAdapter<Range, Protocol, Model>::operator=(NewRange &&newRange)
325
326 Replaces the contents of the model with the rows in \a newRange, possibly
327 using move semantics.
328
329 This function makes the model() emit the \l{QAbstractItemModel::}{modelAboutToBeReset()}
330 and \l{QAbstractItemModel::}{modelReset()} signals.
331
332 \constraints \c Range is mutable, and \a newRange is of a type that can be
333 assigned to \c Range, but not a QRangeModelAdapter.
334
335 \sa range(), at(), model(), assign()
336*/
337
338/*!
339 \fn template <typename Range, typename Protocol, typename Model> template <typename Row, QRangeModelAdapter<Range, Protocol, Model>::if_assignable_range<std::initializer_list<Row>>> void QRangeModelAdapter<Range, Protocol, Model>::setRange(std::initializer_list<Row> newRange)
340 \fn template <typename Range, typename Protocol, typename Model> template <typename Row, QRangeModelAdapter<Range, Protocol, Model>::if_assignable_range<std::initializer_list<Row>>> QRangeModelAdapter &QRangeModelAdapter<Range, Protocol, Model>::assign(std::initializer_list<Row> newRange)
341 \fn template <typename Range, typename Protocol, typename Model> template <typename Row, QRangeModelAdapter<Range, Protocol, Model>::if_assignable_range<std::initializer_list<Row>>> QRangeModelAdapter &QRangeModelAdapter<Range, Protocol, Model>::operator=(std::initializer_list<Row> newRange)
342
343 Replaces the contents of the model with the rows in \a newRange.
344
345 \constraints \c Range is mutable, and \a newRange can be assigned to \c Range.
346
347 \sa range(), at, model()
348*/
349
350/*!
351 \fn template <typename Range, typename Protocol, typename Model> template <typename InputIterator, typename Sentinel, typename I = Impl, QRangeModelAdapter<Range, Protocol, Model>::if_writable<I>> void QRangeModelAdapter<Range, Protocol, Model>::setRange(InputIterator first, Sentinel last)
352 \fn template <typename Range, typename Protocol, typename Model> template <typename InputIterator, typename Sentinel, typename I = Impl, QRangeModelAdapter<Range, Protocol, Model>::if_writable<I>> void QRangeModelAdapter<Range, Protocol, Model>::assign(InputIterator first, Sentinel last)
353
354 Replaces the contents of the models with the rows in the range [\a first, \a last).
355
356 \sa range(), at, model()
357*/
358
359/*!
360 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_list<I>> QModelIndex QRangeModelAdapter<Range, Protocol, Model>::index(int row) const
361 \overload
362
363 Returns the QModelIndex for \a row.
364
365 \constraints \c Range is a one-dimensional list.
366*/
367
368/*!
369 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::unless_list<I>> QModelIndex QRangeModelAdapter<Range, Protocol, Model>::index(int row, int column) const
370 \overload
371
372 Returns the QModelIndex for the item at \a row, \a column.
373
374 \constraints \c Range is a table or tree.
375*/
376
377/*!
378 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>> QModelIndex QRangeModelAdapter<Range, Protocol, Model>::index(QSpan<const int> path, int column) const
379 \overload
380
381 Returns the QModelIndex for the item at \a column for the row in the tree
382 specified by \a path.
383
384 \constraints \c Range is a tree.
385*/
386
387/*!
388 \fn template <typename Range, typename Protocol, typename Model> int QRangeModelAdapter<Range, Protocol, Model>::columnCount() const
389
390 \return the number of columns. This will be one if the \c Range represents a
391 list, otherwise this returns be the number of elements in each row.
392*/
393
394/*!
395 \fn template <typename Range, typename Protocol, typename Model> int QRangeModelAdapter<Range, Protocol, Model>::rowCount() const
396 \overload
397
398 \return the number of rows. If the \c Range represents a list or table, then
399 this is the number of rows. For trees, this is the number of top-level rows.
400*/
401
402/*!
403 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>> int QRangeModelAdapter<Range, Protocol, Model>::rowCount(int row) const
404 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>> int QRangeModelAdapter<Range, Protocol, Model>::rowCount(QSpan<const int> row) const
405 \overload
406
407 \return the number of rows under \a row.
408 \constraints \c Range is a tree.
409*/
410
411/*!
412 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>> int QRangeModelAdapter<Range, Protocol, Model>::hasChildren(int row) const
413 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>> int QRangeModelAdapter<Range, Protocol, Model>::hasChildren(QSpan<const int> row) const
414 \overload
415
416 \return whether there are any rows under \a row.
417 \constraints \c Range is a tree.
418*/
419
420/*!
421 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_list<I>> QVariant QRangeModelAdapter<Range, Protocol, Model>::data(int row) const
422 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_list<I>> QVariant QRangeModelAdapter<Range, Protocol, Model>::data(int row, int role) const
423
424 \return a QVariant holding the data stored under the given \a role for the
425 item at \a row, or an invalid QVariant if there is no item. If \a role is
426 not specified, then returns a QVariant holding the complete item.
427
428 \constraints \c Range is a list.
429
430 \sa setData(), at()
431*/
432
433/*!
434 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_list<I>, QRangeModelAdapter<Range, Protocol, Model>::if_writable<I>> bool QRangeModelAdapter<Range, Protocol, Model>::setData(int row, const QVariant &value, int role)
435
436 Sets the \a role data for the item at \a row to \a value.
437
438 Returns \c{true} if successful; otherwise returns \c{false}.
439
440 \constraints \c Range is a mutable list.
441
442 \sa data(), at()
443*/
444
445/*!
446 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::unless_list<I>> QVariant QRangeModelAdapter<Range, Protocol, Model>::data(int row, int column) const
447 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::unless_list<I>> QVariant QRangeModelAdapter<Range, Protocol, Model>::data(int row, int column, int role) const
448
449 \return a QVariant holding the data stored under the given \a role for the
450 item referred to by a \a row and \a column, or an invalid QVariant if there
451 is no data stored for that position or role. If \a role is not specified,
452 then returns a QVariant holding the complete item.
453
454 \constraints \c Range is a table or tree.
455
456 \sa setData(), at()
457*/
458
459/*!
460 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::unless_list<I>, QRangeModelAdapter<Range, Protocol, Model>::if_writable<I>> bool QRangeModelAdapter<Range, Protocol, Model>::setData(int row, int column, const QVariant &value, int role)
461
462 Sets the \a role data for the item referred to by \a row and \a column to
463 \a value.
464
465 Returns \c{true} if successful; otherwise returns \c{false}.
466
467 \constraints \c Range is mutable, and not a list.
468
469 \sa data(), at()
470*/
471
472/*!
473 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>> QVariant QRangeModelAdapter<Range, Protocol, Model>::data(QSpan<const int> path, int column) const
474 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>> QVariant QRangeModelAdapter<Range, Protocol, Model>::data(QSpan<const int> path, int column, int role) const
475
476 \return a QVariant holding the data stored under the given \a role for the
477 item referred to by \a path and \a column, or an invalid QVariant if there
478 is no data stored for that position or role. If \a role is not specified,
479 then returns a QVariant holding the complete item.
480
481 \constraints \c Range is a tree.
482
483 \sa setData(), at()
484*/
485
486/*!
487 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>, QRangeModelAdapter<Range, Protocol, Model>::if_writable<I>> bool QRangeModelAdapter<Range, Protocol, Model>::setData(QSpan<const int> path, int column, const QVariant &value, int role)
488
489 Sets the \a role data for the item referred to by \a path and \a column to
490 \a value.
491
492 Returns \c{true} if successful; otherwise returns \c{false}.
493
494 \constraints \c Range is a mutable tree.
495
496 \sa data(), at()
497*/
498
499/*!
500 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_list<I>> auto QRangeModelAdapter<Range, Protocol, Model>::at(int row) const
501 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_list<I>> auto QRangeModelAdapter<Range, Protocol, Model>::operator[](int row) const
502
503 \return the value at \a row as the type stored in \c Range.
504
505 \constraints \c Range is a list.
506*/
507
508/*!
509 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_list<I>, QRangeModelAdapter<Range, Protocol, Model>::if_writable<I>> auto QRangeModelAdapter<Range, Protocol, Model>::at(int row)
510 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_list<I>, QRangeModelAdapter<Range, Protocol, Model>::if_writable<I>> auto QRangeModelAdapter<Range, Protocol, Model>::operator[](int row)
511
512 \return the value at \a row wrapped into a mutable reference to the type
513 stored in \c Range.
514
515//! [data-ref]
516 \note Modifications to the range will invalidate that reference. To modify
517 the reference, assign a new value to it. Unless the value stored in the
518 \c Range is a pointer, it is not possible to access individual members of
519 the stored value.
520//! [data-ref]
521
522 \constraints \c Range is a mutable list.
523*/
524
525/*!
526 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::unless_list<I>> decltype(auto) QRangeModelAdapter<Range, Protocol, Model>::at(int row) const
527 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::unless_list<I>> decltype(auto) QRangeModelAdapter<Range, Protocol, Model>::operator[](int row) const
528
529 \return a constant reference to the row at \a row, as stored in \c Range.
530
531 \constraints \c Range is a table or tree.
532*/
533
534/*!
535 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_table<I>, QRangeModelAdapter<Range, Protocol, Model>::if_writable<I>> auto QRangeModelAdapter<Range, Protocol, Model>::at(int row)
536 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_table<I>, QRangeModelAdapter<Range, Protocol, Model>::if_writable<I>> auto QRangeModelAdapter<Range, Protocol, Model>::operator[](int row)
537
538 \return a mutable reference to the row at \a row, as stored in \c Range.
539
540 \constraints \c Range is a mutable table, but not a tree.
541*/
542
543/*!
544 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>, QRangeModelAdapter<Range, Protocol, Model>::if_writable<I>> auto QRangeModelAdapter<Range, Protocol, Model>::at(int row)
545 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>, QRangeModelAdapter<Range, Protocol, Model>::if_writable<I>> auto QRangeModelAdapter<Range, Protocol, Model>::operator[](int row)
546
547 \return a mutable wrapper holding a reference to the tree row specified by \a row.
548
549//! [treerow-ref]
550 To modify the tree row, assign a new value to it. Assigning a new tree row
551 will set the parent the new tree row to be the parent of the old tree row.
552 However, neither the old nor the new tree row must have any child rows. To
553 access the tree row, dereferencing the wrapper using \c{operator*()}, or use
554 \c{operator->()} to access tree row members.
555
556 \note Modifications to the range will invalidate the wrapper.
557//! [treerow-ref]
558
559 \constraints \c Range is a tree.
560*/
561
562/*!
563 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::unless_list<I>> auto QRangeModelAdapter<Range, Protocol, Model>::at(int row, int column) const
564\omit
565 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::unless_list<I>> auto QRangeModelAdapter<Range, Protocol, Model>::operator[](int row, int column) const
566\endomit
567
568 \return a copy of the value stored as the item specified by \a row and
569 \a column. If the item is a multi-role item, then this returns a copy of
570 the entire item. If the rows in the \c Range store different types at
571 different columns, then the return type will be a QVariant.
572
573 \constraints \c Range is a table or tree.
574*/
575
576/*!
577 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::unless_list<I>, QRangeModelAdapter<Range, Protocol, Model>::if_writable<I>> auto QRangeModelAdapter<Range, Protocol, Model>::at(int row, int column)
578\omit
579 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::unless_list<I>, QRangeModelAdapter<Range, Protocol, Model>::if_writable<I>> auto QRangeModelAdapter<Range, Protocol, Model>::operator[](int row, int column)
580\endomit
581
582 \return a mutable reference to the value stored as the item specified by
583 \a row and \a column. If the item is a multi-role item, then this will be
584 a reference to the entire item.
585
586 \include qrangemodeladapter.qdoc data-ref
587
588 \constraints \c Range is a mutable table.
589*/
590
591/*!
592 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>> decltype(auto) QRangeModelAdapter<Range, Protocol, Model>::at(QSpan<const int> path) const
593 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>> decltype(auto) QRangeModelAdapter<Range, Protocol, Model>::operator[](QSpan<const int> path) const
594
595 \return a constant reference to the row specified by \a path, as stored in
596 \c Range.
597
598 \constraints \c Range is a tree.
599*/
600
601/*!
602 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>, QRangeModelAdapter<Range, Protocol, Model>::if_writable<I>> auto QRangeModelAdapter<Range, Protocol, Model>::at(QSpan<const int> path)
603 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>, QRangeModelAdapter<Range, Protocol, Model>::if_writable<I>> auto QRangeModelAdapter<Range, Protocol, Model>::operator[](QSpan<const int> path)
604
605 \return a mutable wrapper holding a reference to the tree row specified by \a path.
606
607 \include qrangemodeladapter.qdoc treerow-ref
608
609 \constraints \c Range is a tree.
610*/
611
612/*!
613 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>> auto QRangeModelAdapter<Range, Protocol, Model>::at(QSpan<const int> path, int column) const
614\omit
615 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>> auto QRangeModelAdapter<Range, Protocol, Model>::operator[](QSpan<const int> path, int column) const
616\endomit
617
618 \return a copy of the value stored as the item specified by \a path and
619 \a column. If the item is a multi-role item, then this returns a copy of
620 the entire item. If the rows in the \c Range store different types at
621 different columns, then the return type will be a QVariant.
622
623 \constraints \c Range is a tree.
624*/
625
626/*!
627 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>, QRangeModelAdapter<Range, Protocol, Model>::if_writable<I>> auto QRangeModelAdapter<Range, Protocol, Model>::at(QSpan<const int> path, int column)
628\omit
629 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>, QRangeModelAdapter<Range, Protocol, Model>::if_writable<I>> auto QRangeModelAdapter<Range, Protocol, Model>::operator[](QSpan<const int> path, int column)
630\endomit
631
632 \return a mutable reference to the value stored as the item specified by
633 \a path and \a column. If the item is a multi-role item, then this will be
634 a reference to the entire item. If the rows in the \c Range store different
635 types at different columns, then the return type will be a QVariant.
636
637 \include qrangemodeladapter.qdoc data-ref
638
639 \constraints \c Range is a mutable tree.
640*/
641
642/*!
643 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_canInsertRows<I>> bool QRangeModelAdapter<Range, Protocol, Model>::insertRow(int before)
644 \overload
645
646 Inserts a single empty row before the row at \a before, and returns whether
647 the insertion was successful.
648//! [insert-row-appends]
649 If \a before is the same value as rowCount(), then the new row will be appended.
650//! [insert-row-appends]
651
652 \constraints \c Range supports insertion of elements.
653
654 \sa insertRows(), removeRow(), insertColumn()
655*/
656
657/*!
658 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_canInsertRows<I>, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>> bool QRangeModelAdapter<Range, Protocol, Model>::insertRow(QSpan<const int> before)
659 \overload
660
661 Inserts a single empty row before the row at the path specified by \a before,
662 and returns whether the insertion was successful.
663 \include qrangemodeladapter.qdoc insert-row-appends
664
665 \constraints \c Range is a tree that supports insertion of elements.
666
667 \sa insertRows(), removeRow(), insertColumn()
668*/
669
670/*!
671 \fn template <typename Range, typename Protocol, typename Model> template <typename D, typename I, QRangeModelAdapter<Range, Protocol, Model>::if_canInsertRows<I>, QRangeModelAdapter<Range, Protocol, Model>::if_compatible_row<D>> bool QRangeModelAdapter<Range, Protocol, Model>::insertRow(int before, D &&data)
672 \overload
673
674 Inserts a single row constructed from \a data before the row at \a before,
675 and returns whether the insertion was successful.
676 \include qrangemodeladapter.qdoc insert-row-appends
677
678 \constraints \c Range supports insertion of elements, and if
679 a row can be constructed from \a data.
680
681 \sa insertRows(), removeRow(), insertColumn()
682*/
683
684/*!
685 \fn template <typename Range, typename Protocol, typename Model> template <typename D, typename I, QRangeModelAdapter<Range, Protocol, Model>::if_canInsertRows<I>, QRangeModelAdapter<Range, Protocol, Model>::if_compatible_row<D>, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>> bool QRangeModelAdapter<Range, Protocol, Model>::insertRow(QSpan<const int> before, D &&data)
686 \overload
687
688 Inserts a single row constructed from \a data before the row at \a before,
689 and returns whether the insertion was successful.
690 \include qrangemodeladapter.qdoc insert-row-appends
691
692 \constraints \c Range is a tree that supports insertion of elements, and if
693 a row can be constructed from \a data.
694
695 \sa insertRows(), removeRow(), insertColumn()
696*/
697
698/*!
699 \fn template <typename Range, typename Protocol, typename Model> template <typename C, typename I, QRangeModelAdapter<Range, Protocol, Model>::if_canInsertRows<I>, QRangeModelAdapter<Range, Protocol, Model>::if_compatible_row_range<C>> bool QRangeModelAdapter<Range, Protocol, Model>::insertRows(int before, C &&data)
700 \overload
701
702 Inserts rows constructed from the elements in \a data before the row at
703 \a before, and returns whether the insertion was successful.
704 \include qrangemodeladapter.qdoc insert-row-appends
705
706 \constraints \c Range supports insertion of elemnets, and if
707 rows can be constructed from the elements in \a data.
708
709 \sa insertRow(), removeRows(), insertColumns()
710*/
711
712/*!
713 \fn template <typename Range, typename Protocol, typename Model> template <typename C, typename I, QRangeModelAdapter<Range, Protocol, Model>::if_canInsertRows<I>, QRangeModelAdapter<Range, Protocol, Model>::if_compatible_row_range<C>, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>> bool QRangeModelAdapter<Range, Protocol, Model>::insertRows(QSpan<const int> before, C &&data)
714 \overload
715
716 Inserts rows constructed from the elements in \a data before the row at
717 \a before, and returns whether the insertion was successful.
718 \include qrangemodeladapter.qdoc insert-row-appends
719
720 \constraints \c Range is a tree that supports insertion of elements, and if
721 rows can be constructed from the elements in \a data.
722
723 \sa insertRow(), removeRows(), insertColumns()
724*/
725
726/*!
727 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_canRemoveRows<I>> bool QRangeModelAdapter<Range, Protocol, Model>::removeRow(int row)
728 \overload
729
730 Removes the given \a row and returns whether the removal was successful.
731
732 \constraints \c Range supports the removal of elements.
733
734 \sa removeRows(), removeColumn(), insertRow()
735*/
736
737/*!
738 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_canRemoveRows<I>, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>> bool QRangeModelAdapter<Range, Protocol, Model>::removeRow(QSpan<const int> path)
739 \overload
740
741 Removes the row at the given \a path, including all children of that row,
742 and returns whether the removal was successful.
743
744 \constraints \c Range is a tree that supports the removal of elements.
745
746 \sa removeRows(), removeColumn(), insertRow()
747*/
748
749/*!
750 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_canRemoveRows<I>> bool QRangeModelAdapter<Range, Protocol, Model>::removeRows(int row, int count)
751 \overload
752
753 Removes \a count rows starting at \a row, and returns whether the removal
754 was successful.
755
756 \constraints \c Range supports the removal of elements.
757
758 \sa removeRow(), removeColumns(), insertRows()
759*/
760
761/*!
762 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_canRemoveRows<I>, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>> bool QRangeModelAdapter<Range, Protocol, Model>::removeRows(QSpan<const int> path, int count)
763 \overload
764
765 Removes \a count rows starting at the row specified by \a path, and returns
766 whether the removal was successful.
767
768 \constraints \c Range is a tree that supports the removal of elements.
769
770 \sa removeRow(), removeColumns(), insertRows()
771*/
772
773/*!
774 \fn template <typename Range, typename Protocol, typename Model> template <typename F, QRangeModelAdapter<Range, Protocol, Model>::if_canMoveItems<F>> bool QRangeModelAdapter<Range, Protocol, Model>::moveRow(int source, int destination)
775 \overload
776
777 Moves the row at \a source to the position at \a destination, and returns
778 whether the row was successfully moved.
779
780 \constraints \c Range supports moving of elements.
781
782 \sa insertRow(), removeRow(), moveColumn()
783*/
784
785/*!
786 \fn template <typename Range, typename Protocol, typename Model> template <typename I, typename F, QRangeModelAdapter<Range, Protocol, Model>::if_canMoveItems<F>, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>> bool QRangeModelAdapter<Range, Protocol, Model>::moveRow(QSpan<const int> source, QSpan<const int> destination)
787 \overload
788
789 Moves the tree branch at \a source to the position at \a destination, and
790 returns whether the branch was successfully moved.
791
792 \constraints \c Range is a tree that supports moving of elements.
793
794 \sa insertRow(), removeRow(), moveColumn()
795*/
796
797/*!
798 \fn template <typename Range, typename Protocol, typename Model> template <typename F, QRangeModelAdapter<Range, Protocol, Model>::if_canMoveItems<F>> bool QRangeModelAdapter<Range, Protocol, Model>::moveRows(int source, int count, int destination)
799 \overload
800
801 Moves \a count rows starting at \a source to the position at \a destination,
802 and returns whether the rows were successfully moved.
803
804 \constraints \c Range supports moving of elements.
805
806 \sa insertRows(), removeRows(), moveColumns()
807*/
808
809/*!
810 \fn template <typename Range, typename Protocol, typename Model> template <typename I, typename F, QRangeModelAdapter<Range, Protocol, Model>::if_canMoveItems<F>, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>> bool QRangeModelAdapter<Range, Protocol, Model>::moveRows(QSpan<const int> source, int count, QSpan<const int> destination)
811 \overload
812
813 Moves \a count tree branches starting at \a source to the position at
814 \a destination, and returns whether the rows were successfully moved.
815
816 \constraints \c Range is a tree that supports moving of elements.
817
818 \sa insertRows(), removeRows(), moveColumns()
819*/
820
821/*!
822 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_canInsertColumns<I>> bool QRangeModelAdapter<Range, Protocol, Model>::insertColumn(int before)
823 \overload
824
825 Inserts a single empty column before the column specified by \a before into
826 all rows, and returns whether the insertion was successful.
827//! [insert-column-appends]
828 If \a before is the same value as columnCount(), then the column will be
829 appended to each row.
830//! [insert-column-appends]
831
832 \constraints \c Range has rows that support insertion of elements.
833
834 \sa removeColumn(), insertColumns(), insertRow()
835*/
836
837/*!
838 \fn template <typename Range, typename Protocol, typename Model> template <typename D, typename I, QRangeModelAdapter<Range, Protocol, Model>::if_canInsertColumns<I>, QRangeModelAdapter<Range, Protocol, Model>::if_compatible_column_data<D>> bool QRangeModelAdapter<Range, Protocol, Model>::insertColumn(int before, D &&data)
839 \overload
840
841 Inserts a single column constructed from \a data before the column specified
842 by \a before into all rows, and returns whether the insertion was successful.
843//! [insert-column-appends]
844 If \a before is the same value as columnCount(), then the column will be
845 appended to each row.
846//! [insert-column-appends]
847
848 If \a data is a single value, then the new entry in all rows will be constructed
849 from that single value.
850
851 If \a data is a container, then the elements in that container will be used
852 sequentially to construct the column for each subsequent row. If there are
853 fewer elements in \a data than there are rows, then function wraps around
854 and starts again from the first element.
855
856 \code
857 \endcode
858
859 \constraints \c Range has rows that support insertion of elements, and the
860 elements can be constructed from the entries in \a data.
861
862 \sa removeColumn(), insertColumns(), insertRow()
863*/
864
865/*!
866 \fn template <typename Range, typename Protocol, typename Model> template <typename C, typename I, QRangeModelAdapter<Range, Protocol, Model>::if_canInsertColumns<I>, QRangeModelAdapter<Range, Protocol, Model>::if_compatible_column_range<C>> bool QRangeModelAdapter<Range, Protocol, Model>::insertColumns(int before, C &&data)
867
868 Inserts columns constructed from the elements in \a data before the column
869 specified by \a before into all rows, and returns whether the insertion was
870 successful.
871//! [insert-column-appends]
872 If \a before is the same value as columnCount(), then the column will be
873 appended to each row.
874//! [insert-column-appends]
875
876 If the elements in \a data are values, then the new entries in all rows will
877 be constructed from those values.
878
879 If the elements in \a data are containers, then the entries in the outer
880 container will be used sequentially to construct the new entries for each
881 subsequent row. If there are fewer elements in \a data than there are rows,
882 then the function wraps around and starts again from the first element.
883
884 \code
885 \endcode
886
887 \constraints \c Range has rows that support insertion of elements, and the
888 elements can be constructed from the entries in \a data.
889
890 \sa removeColumns(), insertColumn(), insertRows()
891*/
892
893/*!
894 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_canRemoveColumns<I>> bool QRangeModelAdapter<Range, Protocol, Model>::removeColumn(int column)
895
896 Removes the given \a column from each row, and returns whether the removal
897 was successful.
898
899 \constraints \c Range has rows that support removal of elements.
900
901 \sa insertColumn(), removeColumns(), removeRow()
902*/
903
904/*!
905 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_canRemoveColumns<I>> bool QRangeModelAdapter<Range, Protocol, Model>::removeColumns(int column, int count)
906
907 Removes \a count columns starting by the given \a column from each row, and
908 returns whether the removal was successful.
909
910 \constraints \c Range has rows that support removal of elements.
911
912 \sa insertColumns(), removeColumn(), removeRow()
913*/
914
915/*!
916 \fn template <typename Range, typename Protocol, typename Model> template <typename F, QRangeModelAdapter<Range, Protocol, Model>::if_canMoveItems<F>> bool QRangeModelAdapter<Range, Protocol, Model>::moveColumn(int from, int to)
917
918 Moves the column at \a from to the column at \a to, and returns whether the
919 column was successfully moved.
920
921 \constraints \c Range has rows that support moving of elements.
922
923 \sa insertColumn(), removeColumn(), moveColumns(), moveRow()
924*/
925
926/*!
927 \fn template <typename Range, typename Protocol, typename Model> template <typename F, QRangeModelAdapter<Range, Protocol, Model>::if_canMoveItems<F>> bool QRangeModelAdapter<Range, Protocol, Model>::moveColumns(int from, int count, int to)
928
929 Moves \a count columns starting at \a from to the position at \a to, and
930 returns whether the columns were successfully moved.
931
932 \constraints \c Range has rows that support moving of elements.
933
934 \sa insertColumns(), removeColumns(), moveColumn(), moveRows()
935*/
936
937/*!
938 \fn template <typename Range, typename Protocol, typename Model> template <typename I, typename F, QRangeModelAdapter<Range, Protocol, Model>::if_canMoveItems<F>, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>> bool QRangeModelAdapter<Range, Protocol, Model>::moveColumn(QSpan<const int> source, int to)
939 \internal Not possible to create a tree from a row type that can rotate/splice?
940*/
941
942/*!
943 \fn template <typename Range, typename Protocol, typename Model> template <typename I, typename F, QRangeModelAdapter<Range, Protocol, Model>::if_canMoveItems<F>, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>> bool QRangeModelAdapter<Range, Protocol, Model>::moveColumns(QSpan<const int> source, int count, int to)
944 \internal Not possible to create a tree from a row type that can rotate/splice?
945*/