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