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 The exact type that gets constructed is deducted by the compiler based on
33 the constructor argument(s), and the differences between value categories
34 can result in different behavior. Therefore, you should not explicitly
35 specify the template parameters. C++ however does not allow class template
36 argument deduction for non-static class data members. To make
37 QRangeModelAdapter a data member of a class, use the following pattern:
38
39 \snippet qrangemodeladapter/main.cpp class-member-rvalue
40
41 This creates a QRangeModelAdapter operating on an unnamed (i.e. rvalue
42 reference) vector of Books. To make the adapter operate on a reference
43 wrapper to a list of Books, use this instead:
44
45 \snippet qrangemodeladapter/main.cpp class-member-refwrapper
46
47 Constructing the adapter from a range implicitly constructs a QRangeModel
48 instance from that same range. Use model() to get it, and pass it to Qt
49 Widgets or Qt Quick item views as usual.
50
51 \snippet qrangemodeladapter/main.cpp use-model
52
53 The adapter owns the model. QRangeModelAdapter is a value type, so it can be
54 copied and moved. All copies share the same QRangeModel, which will be
55 destroyed when the last copy of the adapter is destroyed.
56
57 If the adapter was created from an lvalue or rvalue reference, then the
58 adapter and model will operate on a copy of the original range object.
59 Otherwise, modifications made through the adapter or model will be written
60 to the original range object. To access the updated range, use range():
61
62 \snippet qrangemodeladapter/main.cpp get-range
63
64 To replace the entire range data with data from another (compatible) range,
65 use the assign() function, or the assignment operator.
66
67 \snippet qrangemodeladapter/main.cpp assign
68
69 \section1 Accessing item data
70
71 The QRangeModelAdapter API provides type-safe read and write access to the
72 range that the model operates on. The adapter API is based on the typical
73 API for C++ containers and ranges, including iterators. To access
74 individual rows and items, use at(), the corresponding subscript
75 \l{QRangeModelAdapter::operator[]()}{operator[]}, or data().
76 Which overloads of those functions are available depends on the range for
77 which the adapter was constructed.
78
79 \section2 Reading item data as a QVariant
80
81 The data() function always returns a QVariant with the value stored at the
82 specified position and role. In a list, an item can be accessed by a single
83 integer value specifying the row:
84
85 \snippet qrangemodeladapter/main.cpp list-data
86
87 If the range is a table, then items are specified by row and column:
88
89 \snippet qrangemodeladapter/main.cpp table-data
90
91 If the range is a tree, then items are located using a path of rows, and a
92 single column value:
93
94 \snippet qrangemodeladapter/main.cpp tree-data
95
96 Using a single integer as the row provides access to the toplevel tree
97 items.
98
99 \snippet qrangemodeladapter/main.cpp multirole-data
100
101 If no role is specified, then the QVariant will hold the entire item at the
102 position. Use the \l{QVariant::fromValue()} template function to retrieve a
103 copy of the item.
104
105 \section2 Reading and writing using at()
106
107 That the data() function returns a QVariant makes it flexible, but removes
108 type safety. For ranges where all items are of the same type, the at()
109 function provides a type-safe alternative that is more compatible with
110 regular C++ containers. As with data(), at() overloads exist to access an
111 item at a row for lists, at a row/column pair for table, and a path/column
112 pair for trees. However, at() always returns the whole item at the
113 specified position; it is not possible to read individual role values of
114 an item.
115
116 As expected from a C++ container API, the const overloads of at() (and the
117 corresponding subscript \l{operator[]()}) provide immutable access to the
118 value, while the mutable overloads return a reference object that a new
119 value can be assigned to. Note that a QRangeModelAdapter operating on a
120 const range behaves in that respect like a const QRangeModelAdapter. The
121 mutable overloads are removed from the overload set, so the compiler will
122 always select the const version. Trying to call a function that modifies a
123 range will result in a compiler error, even if the adapter itself is
124 mutable:
125
126 \snippet qrangemodeladapter/main.cpp read-only
127
128 The returned reference objects are wrappers that convert implicitly to the
129 underlying type, have a \l{QRangeModelAdapter::DataReference::}{get()}
130 function to explicitly access the underlying value, and an
131 \l{QRangeModelAdapter::DataReference::}{operator->()} that provides direct
132 access to const member functions. However, to prevent accidental data
133 changes that would bypass the QAbstractItemModel notification protocol,
134 those reference objects prevent direct modifications of the items.
135
136 \note Accessing the reference object always makes a call to the model to get
137 a copy of the value. This can be expensive; for performance critical access
138 to data, store a copy.
139
140 \section3 Item access
141
142 If the range is represented as a list, then only the overloads taking a row
143 are available.
144
145 \snippet qrangemodeladapter/main.cpp list-access
146
147 The const overload returns the item at that row, while the mutable overload
148 returns a wrapper that implicitly converts to and from the value type of the
149 list.
150
151 \snippet qrangemodeladapter/main.cpp list-access-multirole
152
153 Assign a value to the wrapper to modify the data in the list. The model will
154 emit \l{QAbstractItemModel::}{dataChanged()} for all roles.
155
156 When using the mutable overloads, you can also access the item type's const
157 members using the overloaded arrow operator.
158
159 \snippet qrangemodeladapter/main.cpp list-access-multirole-member-access
160
161 It is not possible to access non-const members of the item. Such
162 modifications would bypass the adapter, which couldn't notify the model
163 about the changes. To modify the value stored in the model, make a copy,
164 modify the properties of the copy, and then write that copy back.
165
166 \snippet qrangemodeladapter/main.cpp list-access-multirole-write-back
167
168 This will make the model emit \l{QAbstractItemModel::}{dataChanged()} for
169 this item, and for all roles.
170
171 If the range is represented as a table, then you can access an individual
172 item by row and column, using the \l{at(int, int)}{at(row, column)}
173 overload. For trees, that overload gives access to top-level items, while
174 the \l{at(QSpan<const int>, int)}{at(path, column)} overload provides
175 access to items nested within the tree.
176
177 Accessing an individual item in a table or tree is equivalent to accessing
178 an item in a list.
179
180 \snippet qrangemodeladapter/main.cpp table-item-access
181
182 If the range doesn't store all columns using the same data type, then
183 \c{at(row,column)} returns a (reference wrapper with a) QVariant holding
184 the item.
185
186 \snippet qrangemodeladapter/main.cpp table-mixed-type-access
187
188 \section2 Accessing rows in tables and trees
189
190 For tables and trees, the overloads of at() and subscript \l{operator[]()}
191 without the column parameter provide access to the entire row. The value
192 returned by the const overloads will be a reference type that gives access
193 to the row data. If that row holds pointers, then that reference type will
194 be a view of the row, giving access to pointers to const items.
195
196 \section3 Table row access
197
198 The \l{at(int)} overload is still available, but it returns the entire table
199 row. This makes it possible to work with all the values in the row at once.
200
201 \snippet qrangemodeladapter/main.cpp table-row-const-access
202
203 As with items, the const overload provides direct access to the row type,
204 while the mutable overload returns a wrapper that acts as a reference to the
205 row. The wrapper provides access to const member functions using the
206 overloaded arrow operator. To modify the values, write a modified row type
207 back.
208
209 \snippet qrangemodeladapter/main.cpp table-row-access
210
211 When assigning a new value to the row, then the model emits the
212 \l{QAbstractItemModel::}{dataChanged()} signal for all items in the row,
213 and for all roles.
214
215 \note When using a row type with runtime sizes, such as a \c{std::vector} or
216 a QList, make sure that the new row has the correct size.
217
218 \section3 Tree row access
219
220 Rows in trees are specified by a sequence of integers, one entry for each
221 level in the tree. Note that in the following snippets, the Tree is a range
222 holding raw row pointers, and that the adapter is created with an rvalue
223 reference of that range. This gives the QRangeModel ownership over the row
224 data.
225
226 \snippet qrangemodeladapter/main.cpp tree-row-access
227
228 The overload of \l{at(int)}{at()} taking a single row value provides
229 access to the top-level rows, or items in the top-level rows.
230
231 \snippet qrangemodeladapter/main.cpp tree-item-access
232
233 The basic pattern for accessing rows and items in a tree is identical to
234 accessing rows and items in a table. However, the adapter will make sure
235 that the tree structure is maintained when modifying entire rows.
236
237 \snippet qrangemodeladapter/main.cpp tree-row-write
238
239 In this example, a new row object is created, and assigned to the first
240 child of the first top-level item.
241
242 \section1 Iterator API
243
244 Use begin() and end() to get iterators over the rows of the model, or use
245 ranged-for. If the range is a list of items, dereferencing the iterator
246 will give access to item data.
247
248 \snippet qrangemodeladapter/main.cpp ranged-for-const-list
249
250 As with the const and mutable overloads of at(), a mutable iterator will
251 dereference to a wrapper.
252
253 \snippet qrangemodeladapter/main.cpp ranged-for-mutable-list
254
255 Use the overloaded arrow operator to access const members of the item type,
256 and assign to the wrapper to replace the value.
257
258 It the range is a table or tree, then iterating over the model will give
259 access to the rows.
260
261 \snippet qrangemodeladapter/main.cpp ranged-for-const-table
262
263 Both the const and the mutable iterator will dereference to a wrapper type
264 for the row. This makes sure that we can consistently iterate over each
265 item in the row, even if the underlying row type is not a range (e.g. it
266 might be a tuple or gadget).
267
268 \snippet qrangemodeladapter/main.cpp ranged-for-const-table-items
269
270 When iterating over a mutable table we can overwrite the entire row.
271
272 \snippet qrangemodeladapter/main.cpp ranged-for-mutable-table
273
274 The model emits the \l{QAbstractItemModel::}{dataChanged()} signal for
275 all items in all row, and for all roles.
276
277 \snippet qrangemodeladapter/main.cpp ranged-for-mutable-table-items
278
279 Iterating over the mutable rows allows us to modify individual items.
280
281 When iterating over a tree, the row wrapper has two additional member
282 functions, hasChildren() and children(), that allow us to traverse the
283 entire tree using iterators.
284
285 \snippet qrangemodeladapter/main.cpp ranged-for-tree
286
287 The object returned by children() is a QRangeModelAdapter operating on
288 the same model as the callee, but all operations will use the source row
289 index as the parent index.
290
291 \sa QRangeModel
292*/
293
294/*!
295 \typedef QRangeModelAdapter::range_type
296*/
297
298/*!
299 \fn template <typename Range, typename Protocol, typename Model> QRangeModelAdapter<Range, Protocol, Model>::QRangeModelAdapter(Range &&range, Protocol &&protocol)
300 \fn template <typename Range, typename Protocol, typename Model> QRangeModelAdapter<Range, Protocol, Model>::QRangeModelAdapter(Range &&range)
301
302 Constructs a QRangeModelAdapter that operates on \a range. For tree ranges,
303 the optional \a protocol will be used for tree traversal.
304
305 See the \l{QRangeModel::}{QRangeModel} constructor documentation for details
306 on the requirements to \a Range, and how the value category of \a range
307 changes the interaction between adapter, model, and range.
308
309 \sa QRangeModel
310*/
311
312/*!
313 \fn template <typename Range, typename Protocol, typename Model> bool QRangeModelAdapter<Range, Protocol, Model>::operator==(const QRangeModelAdapter &lhs, const QRangeModelAdapter &rhs)
314
315 \return whether \a lhs is equal to \a rhs. Two adapters are equal if they
316 both hold the same \l{model()}{model} instance.
317*/
318
319/*!
320 \fn template <typename Range, typename Protocol, typename Model> bool QRangeModelAdapter<Range, Protocol, Model>::operator!=(const QRangeModelAdapter &lhs, const QRangeModelAdapter &rhs)
321
322 \return whether \a lhs is not equal to \a rhs. Two adapters are equal if
323 they both hold the same \l{model()}{model} instance.
324*/
325
326/*!
327 \fn template <typename Range, typename Protocol, typename Model> Model *QRangeModelAdapter<Range, Protocol, Model>::model() const
328
329 \return the QRangeModel instance created by this adapter.
330
331 \sa range(), at()
332*/
333
334/*!
335 \fn template <typename Range, typename Protocol, typename Model> const QRangeModelAdapter<Range, Protocol, Model>::range_type &QRangeModelAdapter<Range, Protocol, Model>::range() const
336
337 \return a const reference to the range that the model adapter operates on.
338
339 \sa assign(), at(), model()
340*/
341
342/*!
343 \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)
344 \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)
345
346 Replaces the contents of the model with the rows in \a newRange, possibly
347 using move semantics.
348
349 This function makes the model() emit the \l{QAbstractItemModel::}{modelAboutToBeReset()}
350 and \l{QAbstractItemModel::}{modelReset()} signals.
351
352 \constraints \c Range is mutable, and \a newRange is of a type that can be
353 assigned to \c Range, but not a QRangeModelAdapter.
354
355 \sa range(), at(), model(), assign()
356*/
357
358/*!
359 \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)
360 \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)
361
362 Replaces the contents of the model with the rows in \a newRange.
363
364 \constraints \c Range is mutable, and \a newRange can be assigned to \c Range.
365
366 \sa range(), at, model()
367*/
368
369/*!
370 \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)
371
372 Replaces the contents of the models with the rows in the range [\a first, \a last).
373
374 \sa range(), at, model()
375*/
376
377/*!
378 \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 listRow) const
379 \overload
380
381 Returns the QModelIndex for \a listRow.
382
383 \constraints \c Range is a one-dimensional list.
384*/
385
386/*!
387 \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 tableRow, int column) const
388 \overload
389
390 Returns the QModelIndex for the item at \a tableRow, \a column.
391
392 \constraints \c Range is a table or tree.
393*/
394
395/*!
396 \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
397 \overload
398
399 Returns the QModelIndex for the item at \a column for the row in the tree
400 specified by \a path.
401
402 \constraints \c Range is a tree.
403*/
404
405/*!
406 \fn template <typename Range, typename Protocol, typename Model> int QRangeModelAdapter<Range, Protocol, Model>::columnCount() const
407
408 \return the number of columns. This will be one if the \c Range represents a
409 list, otherwise this returns be the number of elements in each row.
410*/
411
412/*!
413 \fn template <typename Range, typename Protocol, typename Model> int QRangeModelAdapter<Range, Protocol, Model>::rowCount() const
414 \overload
415
416 \return the number of rows. If the \c Range represents a list or table, then
417 this is the number of rows. For trees, this is the number of top-level rows.
418*/
419
420/*!
421 \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
422 \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
423 \overload
424
425 \return the number of rows under \a row.
426 \constraints \c Range is a tree.
427*/
428
429/*!
430 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>> int QRangeModelAdapter<Range, Protocol, Model>::rowCount(const QModelIndex &index) const
431 \overload
432 \since 6.12
433
434 \return the number of rows under \a index.
435 \constraints \c Range is a tree.
436*/
437
438/*!
439 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>> bool QRangeModelAdapter<Range, Protocol, Model>::hasChildren(int row) const
440 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>> bool QRangeModelAdapter<Range, Protocol, Model>::hasChildren(QSpan<const int> row) const
441 \overload
442
443 \return whether there are any rows under \a row.
444 \constraints \c Range is a tree.
445*/
446
447/*!
448 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>> bool QRangeModelAdapter<Range, Protocol, Model>::hasChildren(const QModelIndex &index) const
449 \overload
450 \since 6.12
451
452 \return whether there are any rows under \a index.
453 \constraints \c Range is a tree.
454*/
455
456/*!
457 \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 listRow) const
458 \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 listRow, int role) const
459
460 \return a QVariant holding the data stored under the given \a role for the
461 item at \a listRow, or an invalid QVariant if there is no item. If \a role is
462 not specified, then returns a QVariant holding the complete item.
463
464 \constraints \c Range is a list.
465
466 \sa setData(), at()
467*/
468
469/*!
470 \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 listRow, const QVariant &value, int role)
471
472 Sets the \a role data for the item at \a listRow to \a value.
473
474 Returns \c{true} if successful; otherwise returns \c{false}.
475
476 \constraints \c Range is a mutable list.
477
478 \sa data(), at()
479*/
480
481/*!
482 \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 tableRow, int column) const
483 \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 tableRow, int column, int role) const
484
485 \return a QVariant holding the data stored under the given \a role for the
486 item referred to by a \a tableRow and \a column, or an invalid QVariant if there
487 is no data stored for that position or role. If \a role is not specified,
488 then returns a QVariant holding the complete item.
489
490 \constraints \c Range is a table or tree.
491
492 \sa setData(), at()
493*/
494
495/*!
496 \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 tableRow, int column, const QVariant &value, int role)
497
498 Sets the \a role data for the item referred to by \a tableRow and \a column to
499 \a value.
500
501 Returns \c{true} if successful; otherwise returns \c{false}.
502
503 \constraints \c Range is mutable, and not a list.
504
505 \sa data(), at()
506*/
507
508/*!
509 \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
510 \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
511
512 \return a QVariant holding the data stored under the given \a role for the
513 item referred to by \a path and \a column, or an invalid QVariant if there
514 is no data stored for that position or role. If \a role is not specified,
515 then returns a QVariant holding the complete item.
516
517 \constraints \c Range is a tree.
518
519 \sa setData(), at()
520*/
521
522/*!
523 \fn template <typename Range, typename Protocol, typename Model> QVariant QRangeModelAdapter<Range, Protocol, Model>::data(const QModelIndex &index) const
524 \fn template <typename Range, typename Protocol, typename Model> QVariant QRangeModelAdapter<Range, Protocol, Model>::data(const QModelIndex &index, int role) const
525 \overload
526 \since 6.12
527
528 \return a QVariant holding the data stored under the given \a role for the
529 item at \a index, or an invalid QVariant if there is no data stored for
530 that position or role. If \a role is not specified, then returns a QVariant
531 holding the complete item.
532
533 \sa setData(), at()
534*/
535
536/*!
537 \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)
538
539 Sets the \a role data for the item referred to by \a path and \a column to
540 \a value.
541
542 Returns \c{true} if successful; otherwise returns \c{false}.
543
544 \constraints \c Range is a mutable tree.
545
546 \sa data(), at()
547*/
548
549/*!
550 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_writable<I>> bool QRangeModelAdapter<Range, Protocol, Model>::setData(const QModelIndex &index, const QVariant &value, int role)
551 \overload
552 \since 6.12
553
554 Sets the \a role data for the item at \a index to \a value.
555
556 Returns \c{true} if successful; otherwise returns \c{false}.
557
558 \constraints \c Range is not read-only.
559
560 \sa data(), at()
561*/
562
563/*!
564 \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 listRow) const
565 \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 listRow) const
566
567 \return the value at \a listRow as the type stored in \c Range.
568
569 \constraints \c Range is a list.
570*/
571
572/*!
573 \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 listRow)
574 \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 listRow)
575
576 \return a \l{DataReference}{mutable reference} to the value stored in
577 \c Range.
578
579//! [data-ref]
580 \note Modifications to the range will invalidate that reference. To modify
581 the reference, assign a new value to it. Unless the value stored in the
582 \c Range is a pointer, it is not possible to access individual members of
583 the stored value.
584//! [data-ref]
585
586 \constraints \c Range is a mutable list.
587*/
588
589/*!
590 \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 tableRow) const
591 \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 tableRow) const
592
593 \return a constant reference to the row at \a tableRow, as stored in \c Range.
594
595 \constraints \c Range is a table or tree.
596*/
597
598/*!
599 \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 tableRow)
600 \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 tableRow)
601
602 \return a \l{QRangeModelAdapter::RowReference}{reference wrapper} to the row
603 at \a tableRow, as stored in \c Range.
604
605 \constraints \c Range is a mutable table, but not a tree.
606*/
607
608/*!
609 \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 treeRow)
610 \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 treeRow)
611
612 \return a \l{QRangeModelAdapter::RowReference}{reference wrapper} to the row
613 at \a treeRow, as stored in \c Range.
614
615//! [treerow-ref]
616 To modify the tree row, assign a new value to it. Assigning a new tree row
617 will set the parent the new tree row to be the parent of the old tree row.
618 However, neither the old nor the new tree row must have any child rows. To
619 access the tree row, dereferencing the wrapper using \c{operator*()}, or use
620 \c{operator->()} to access tree row members.
621
622 \note Modifications to the range will invalidate the wrapper.
623//! [treerow-ref]
624
625 \constraints \c Range is a tree.
626*/
627
628/*!
629 \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 tableRow, int column) const
630\omit
631 \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 tableRow, int column) const
632\endomit
633
634 \return a copy of the value stored as the item specified by \a tableRow and
635 \a column. If the item is a multi-role item, then this returns a copy of
636 the entire item. If the rows in the \c Range store different types at
637 different columns, then the return type will be a QVariant.
638
639 \constraints \c Range is a table or tree.
640*/
641
642/*!
643 \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 tableRow, int column)
644\omit
645 \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 tableRow, int column)
646\endomit
647
648 \return a \l{DataReference}{mutable reference} to the value stored as the
649 item specified by \a tableRow and \a column. If the item is a multi-role item,
650 then this will be a reference to the entire item.
651
652 \include qrangemodeladapter.qdoc data-ref
653
654 \constraints \c Range is a mutable table.
655*/
656
657/*!
658 \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
659 \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
660
661 \return a constant reference to the row specified by \a path, as stored in
662 \c Range.
663
664 \constraints \c Range is a tree.
665*/
666
667/*!
668 \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)
669 \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)
670
671 \return a \l{RowReference}{mutable wrapper} holding a reference to the tree
672 row specified by \a path.
673
674 \include qrangemodeladapter.qdoc treerow-ref
675
676 \constraints \c Range is a tree.
677*/
678
679/*!
680 \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
681\omit
682 \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
683\endomit
684
685 \return a copy of the value stored as the item specified by \a path and
686 \a column. If the item is a multi-role item, then this returns a copy of
687 the entire item. If the rows in the \c Range store different types at
688 different columns, then the return type will be a QVariant.
689
690 \constraints \c Range is a tree.
691*/
692
693/*!
694 \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)
695\omit
696 \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)
697\endomit
698
699 \return a \l{DataReference}{mutable reference} to the value stored as the
700 item specified by \a path and \a column. If the item is a multi-role item,
701 then this will be a reference to the entire item. If the rows in the \c
702 Range store different types at different columns, then the return type will
703 be a QVariant.
704
705 \include qrangemodeladapter.qdoc data-ref
706
707 \constraints \c Range is a mutable tree.
708*/
709
710/*!
711 \fn template <typename Range, typename Protocol, typename Model> auto QRangeModelAdapter<Range, Protocol, Model>::at(const QModelIndex &index) const
712 \overload
713 \since 6.12
714
715 \return a copy of the value stored as the item at \a index. If the item is
716 a multi-role item, then this returns a copy of the entire item. If the rows
717 in the \c Range store different types at different columns, then the return
718 type will be a QVariant.
719*/
720
721/*!
722 \fn template <typename Range, typename Protocol, typename Model> template <typename I, QRangeModelAdapter<Range, Protocol, Model>::if_writable<I>> auto QRangeModelAdapter<Range, Protocol, Model>::at(const QModelIndex &index)
723 \overload
724 \since 6.12
725
726 \return a \l{DataReference}{mutable reference} to the value stored as the
727 item at \a index. If the item is a multi-role item, then this will be a
728 reference to the entire item. If the rows in the \c Range store different
729 types at different columns, then the return type will be a QVariant.
730
731 \include qrangemodeladapter.qdoc data-ref
732
733 \constraints \c Range is not read-only.
734*/
735
736/*!
737 \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)
738 \overload
739
740 Inserts a single empty row before the row at \a before, and returns whether
741 the insertion was successful.
742//! [insert-row-appends]
743 If \a before is the same value as rowCount(), then the new row will be appended.
744//! [insert-row-appends]
745
746 \constraints \c Range supports insertion of elements.
747
748 \sa insertRows(), removeRow(), insertColumn()
749*/
750
751/*!
752 \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)
753 \overload
754
755 Inserts a single empty row before the row at the path specified by \a before,
756 and returns whether the insertion was successful.
757 \include qrangemodeladapter.qdoc insert-row-appends
758
759 \constraints \c Range is a tree that supports insertion of elements.
760
761 \sa insertRows(), removeRow(), insertColumn()
762*/
763
764/*!
765 \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(int before, const QModelIndex &parent)
766 \overload
767
768 Inserts a single empty row before the row at \a before in the specified
769 \a parent, and returns whether the insertion was successful.
770 \include qrangemodeladapter.qdoc insert-row-appends
771
772 \constraints \c Range is a tree that supports insertion of elements.
773
774 \sa insertRows(), removeRow(), insertColumn()
775*/
776
777/*!
778 \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)
779 \overload
780
781 Inserts a single row constructed from \a data before the row at \a before,
782 and returns whether the insertion was successful.
783 \include qrangemodeladapter.qdoc insert-row-appends
784
785 \constraints \c Range supports insertion of elements, and if
786 a row can be constructed from \a data.
787
788 \sa insertRows(), removeRow(), insertColumn()
789*/
790
791/*!
792 \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)
793 \overload
794
795 Inserts a single row constructed from \a data before the row at \a before,
796 and returns whether the insertion was successful.
797 \include qrangemodeladapter.qdoc insert-row-appends
798
799 \constraints \c Range is a tree that supports insertion of elements, and if
800 a row can be constructed from \a data.
801
802 \sa insertRows(), removeRow(), insertColumn()
803*/
804
805/*!
806 \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(int before, const QModelIndex &parent, D &&data)
807 \overload
808
809 Inserts a single row constructed from \a data before the row at \a before
810 in the specified \a parent, and returns whether the insertion was successful.
811 \include qrangemodeladapter.qdoc insert-row-appends
812
813 \constraints \c Range is a tree that supports insertion of elements, and if
814 a row can be constructed from \a data.
815
816 \sa insertRows(), removeRow(), insertColumn()
817*/
818
819/*!
820 \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)
821 \overload
822
823 Inserts rows constructed from the elements in \a data before the row at
824 \a before, and returns whether the insertion was successful.
825 \include qrangemodeladapter.qdoc insert-row-appends
826
827 \constraints \c Range supports insertion of elements, and if
828 rows can be constructed from the elements in \a data.
829
830 \sa insertRow(), removeRows(), insertColumns()
831*/
832
833/*!
834 \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)
835 \overload
836
837 Inserts rows constructed from the elements in \a data before the row at
838 \a before, and returns whether the insertion was successful.
839 \include qrangemodeladapter.qdoc insert-row-appends
840
841 \constraints \c Range is a tree that supports insertion of elements, and if
842 rows can be constructed from the elements in \a data.
843
844 \sa insertRow(), removeRows(), insertColumns()
845*/
846
847/*!
848 \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(int before, const QModelIndex &parent, C &&data)
849 \overload
850
851 Inserts rows constructed from the elements in \a data before the row at
852 \a before in the specified \a parent, and returns whether the insertion was
853 successful.
854 \include qrangemodeladapter.qdoc insert-row-appends
855
856 \constraints \c Range is a tree that supports insertion of elements, and if
857 rows can be constructed from the elements in \a data.
858
859 \sa insertRow(), removeRows(), insertColumns()
860*/
861
862/*!
863 \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)
864 \overload
865
866 Removes the given \a row and returns whether the removal was successful.
867
868 \constraints \c Range supports the removal of elements.
869
870 \sa removeRows(), removeColumn(), insertRow()
871*/
872
873/*!
874 \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)
875 \overload
876
877 Removes the row at the given \a path, including all children of that row,
878 and returns whether the removal was successful.
879
880 \constraints \c Range is a tree that supports the removal of elements.
881
882 \sa removeRows(), removeColumn(), insertRow()
883*/
884
885/*!
886 \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(int row, const QModelIndex &parent)
887 \overload
888
889 Removes the specified \a row from the \a parent, including all children of
890 that row, and returns whether the removal was successful.
891
892 \constraints \c Range is a tree that supports the removal of elements.
893
894 \sa removeRows(), removeColumn(), insertRow()
895*/
896
897/*!
898 \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)
899 \overload
900
901 Removes \a count rows starting at \a row, and returns whether the removal
902 was successful.
903
904 \constraints \c Range supports the removal of elements.
905
906 \sa removeRow(), removeColumns(), insertRows()
907*/
908
909/*!
910 \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)
911 \overload
912
913 Removes \a count rows starting at the row specified by \a path, and returns
914 whether the removal was successful.
915
916 \constraints \c Range is a tree that supports the removal of elements.
917
918 \sa removeRow(), removeColumns(), insertRows()
919*/
920
921/*!
922 \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(int row, int count, const QModelIndex &parent)
923 \overload
924
925 Removes \a count rows from the \a parent starting at the specified \a row,
926 and returns whether the removal was successful.
927
928 \constraints \c Range is a tree that supports the removal of elements.
929
930 \sa removeRow(), removeColumns(), insertRows()
931*/
932
933/*!
934 \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)
935 \overload
936
937 Moves the row at \a source to the position at \a destination, and returns
938 whether the row was successfully moved.
939
940 \constraints \c Range supports moving of elements.
941
942 \sa insertRow(), removeRow(), moveColumn()
943*/
944
945/*!
946 \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)
947 \overload
948
949 Moves the tree branch at \a source to the position at \a destination, and
950 returns whether the branch was successfully moved.
951
952 \constraints \c Range is a tree that supports moving of elements.
953
954 \sa insertRow(), removeRow(), moveColumn()
955*/
956
957/*!
958 \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(const QModelIndex &sourceParent, int sourceRow, const QModelIndex &destinationParent, int destinationChild)
959 \overload
960
961 Moves the branch at \a sourceRow from the \a sourceParent to the position
962 at \a destinationChild in the \a destinationParent, and returns whether the
963 branch was successfully moved.
964
965 \constraints \c Range is a tree that supports moving of elements.
966
967 \sa insertRow(), removeRow(), moveColumn()
968*/
969
970/*!
971 \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)
972 \overload
973
974 Moves \a count rows starting at \a source to the position at \a destination,
975 and returns whether the rows were successfully moved.
976
977 \constraints \c Range supports moving of elements.
978
979 \sa insertRows(), removeRows(), moveColumns()
980*/
981
982/*!
983 \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)
984 \overload
985
986 Moves \a count tree branches starting at \a source to the position at
987 \a destination, and returns whether the rows were successfully moved.
988
989 \constraints \c Range is a tree that supports moving of elements.
990
991 \sa insertRows(), removeRows(), moveColumns()
992*/
993
994/*!
995 \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(const QModelIndex &sourceParent, int sourceRow, int count, const QModelIndex &destinationParent, int destinationChild)
996 \overload
997
998 Moves \a count branches starting at \a sourceRow from the \a sourceParent
999 to the position at \a destinationChild in the \a destinationParent, and
1000 returns whether the branch was successfully moved.
1001
1002 \constraints \c Range is a tree that supports moving of elements.
1003
1004 \sa insertRows(), removeRows(), moveColumns()
1005*/
1006
1007/*!
1008 \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)
1009 \overload
1010
1011 Inserts a single empty column before the column specified by \a before into
1012 all rows, and returns whether the insertion was successful.
1013//! [insert-column-appends]
1014 If \a before is the same value as columnCount(), then the column will be
1015 appended to each row.
1016//! [insert-column-appends]
1017
1018 \constraints \c Range has rows that support insertion of elements.
1019
1020 \sa removeColumn(), insertColumns(), insertRow()
1021*/
1022
1023/*!
1024 \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)
1025 \overload
1026
1027 Inserts a single column constructed from \a data before the column specified
1028 by \a before into all rows, and returns whether the insertion was successful.
1029//! [insert-column-appends]
1030 If \a before is the same value as columnCount(), then the column will be
1031 appended to each row.
1032//! [insert-column-appends]
1033
1034 If \a data is a single value, then the new entry in all rows will be constructed
1035 from that single value.
1036
1037 If \a data is a container, then the elements in that container will be used
1038 sequentially to construct the column for each subsequent row. If there are
1039 fewer elements in \a data than there are rows, then function wraps around
1040 and starts again from the first element.
1041
1042 \code
1043 \endcode
1044
1045 \constraints \c Range has rows that support insertion of elements, and the
1046 elements can be constructed from the entries in \a data.
1047
1048 \sa removeColumn(), insertColumns(), insertRow()
1049*/
1050
1051/*!
1052 \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)
1053
1054 Inserts columns constructed from the elements in \a data before the column
1055 specified by \a before into all rows, and returns whether the insertion was
1056 successful.
1057//! [insert-column-appends]
1058 If \a before is the same value as columnCount(), then the column will be
1059 appended to each row.
1060//! [insert-column-appends]
1061
1062 If the elements in \a data are values, then the new entries in all rows will
1063 be constructed from those values.
1064
1065 If the elements in \a data are containers, then the entries in the outer
1066 container will be used sequentially to construct the new entries for each
1067 subsequent row. If there are fewer elements in \a data than there are rows,
1068 then the function wraps around and starts again from the first element.
1069
1070 \code
1071 \endcode
1072
1073 \constraints \c Range has rows that support insertion of elements, and the
1074 elements can be constructed from the entries in \a data.
1075
1076 \sa removeColumns(), insertColumn(), insertRows()
1077*/
1078
1079/*!
1080 \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)
1081
1082 Removes the given \a column from each row, and returns whether the removal
1083 was successful.
1084
1085 \constraints \c Range has rows that support removal of elements.
1086
1087 \sa insertColumn(), removeColumns(), removeRow()
1088*/
1089
1090/*!
1091 \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)
1092
1093 Removes \a count columns starting by the given \a column from each row, and
1094 returns whether the removal was successful.
1095
1096 \constraints \c Range has rows that support removal of elements.
1097
1098 \sa insertColumns(), removeColumn(), removeRow()
1099*/
1100
1101/*!
1102 \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)
1103
1104 Moves the column at \a from to the column at \a to, and returns whether the
1105 column was successfully moved.
1106
1107 \constraints \c Range has rows that support moving of elements.
1108
1109 \sa insertColumn(), removeColumn(), moveColumns(), moveRow()
1110*/
1111
1112/*!
1113 \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)
1114
1115 Moves \a count columns starting at \a from to the position at \a to, and
1116 returns whether the columns were successfully moved.
1117
1118 \constraints \c Range has rows that support moving of elements.
1119
1120 \sa insertColumns(), removeColumns(), moveColumn(), moveRows()
1121*/
1122
1123/*!
1124 \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)
1125 \internal Not possible to create a tree from a row type that can rotate/splice?
1126*/
1127
1128/*!
1129 \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)
1130 \internal Not possible to create a tree from a row type that can rotate/splice?
1131*/
1132
1133/*!
1134 \class QRangeModelAdapter::DataReference
1135 \inmodule QtCore
1136 \since 6.11
1137 \preliminary
1138 \ingroup model-view
1139 \brief DataReference is a reference wrapper around an item in a QRangeModel.
1140
1141 Accessing an item in the model using the non-const overloads of at(),
1142 subscript \l{QRangeModelAdapter::operator[]()}{operator[]}, or
1143 dereferencing a non-const \l{QRangeModelAdapter::RowIterator}{iterator},
1144 returns a DataReference wrapper around the item in the model.
1145
1146 Assigning to that reference wrapper changes the data in the model using
1147 QAbstractItemModel API.
1148
1149 \code
1150 adapter[0] = newValue;
1151 \endcode
1152
1153 A const version of the value itself can be accessed using get() or
1154 operator->().
1155
1156 \code
1157 QRangeModelAdapter adapter(QList<Gadget>{ ~~~ });
1158 auto value = adapter[0]->value();
1159 // adapter[0]->setValue(); // not allowed - would not emit dataChanged()
1160 \endcode
1161
1162 In contrast to \c{std::reference_wrapper}, assigning one DataReference to
1163 another does not rebind the reference, but sets the value using copy-
1164 semantics.
1165
1166 \code
1167 adapter[0] = adapter[1]; // items at row 0 and row 1 now have the same value
1168 \endcode
1169
1170 \sa RowReference, ConstRowReference
1171*/
1172
1173/*!
1174 \typedef QRangeModelAdapter::DataReference::value_type
1175
1176 An alias for the type of the items stored in the underlying range.
1177 If different columns in the model hold different types, then this is an
1178 alias to QVariant.
1179*/
1180
1181/*!
1182 \typedef QRangeModelAdapter::DataReference::const_value_type
1183
1184 An alias for the const type of the items stored in the underlying range.
1185 If different columns in the model hold different types, then this is an
1186 alias to \c{const QVariant}.
1187*/
1188
1189/*!
1190 \typedef QRangeModelAdapter::DataReference::pointer
1191
1192 An alias for the pointer type returned by operator->().
1193*/
1194
1195/*!
1196 \fn template <typename Range, typename Protocol, typename Model> QRangeModelAdapter<Range, Protocol, Model>::DataReference::DataReference(const QModelIndex &index) noexcept
1197
1198 Constructs a DataReference wrapper for the item at \a index.
1199*/
1200
1201/*!
1202 \fn template <typename Range, typename Protocol, typename Model> QRangeModelAdapter<Range, Protocol, Model>::DataReference::DataReference(const DataReference &other)
1203
1204 Constructs a copy of \a other.
1205*/
1206
1207/*!
1208 \fn template <typename Range, typename Protocol, typename Model> QRangeModelAdapter<Range, Protocol, Model>::DataReference::DataReference(DataReference &&other)
1209
1210 Constructs a DataReference by moving from \a other.
1211*/
1212
1213/*!
1214 \fn template <typename Range, typename Protocol, typename Model> QDataReference &QRangeModelAdapter<Range, Protocol, Model>::DataReference::operator=(const DataReference &other)
1215
1216 Assigns the item value referred to by \a other to the value referenced by this wrapper.
1217*/
1218
1219/*!
1220 \fn template <typename Range, typename Protocol, typename Model> DataReference &QRangeModelAdapter<Range, Protocol, Model>::DataReference::operator=(DataReference &&other)
1221
1222 Moves the value reference by \a other into the value referenced by this wrapper.
1223*/
1224
1225/*!
1226 \fn template <typename Range, typename Protocol, typename Model> DataReference &QRangeModelAdapter<Range, Protocol, Model>::DataReference::operator=(const value_type &value)
1227
1228 Assigns \a value to the underlying model item.
1229*/
1230
1231/*!
1232 \fn template <typename Range, typename Protocol, typename Model> DataReference &QRangeModelAdapter<Range, Protocol, Model>::DataReference::operator=(value_type &&value)
1233
1234 Move-assigns \a value to the underlying model item.
1235*/
1236
1237/*!
1238 \fn template <typename Range, typename Protocol, typename Model> const_value_type QRangeModelAdapter<Range, Protocol, Model>::DataReference::get() const
1239 \fn template <typename Range, typename Protocol, typename Model> QRangeModelAdapter<Range, Protocol, Model>::DataReference::operator const_value_type() const
1240 \return the item value referred to by this DataReference as a const value.
1241*/
1242
1243/*!
1244 \fn template <typename Range, typename Protocol, typename Model> pointer QRangeModelAdapter<Range, Protocol, Model>::DataReference::operator->() const
1245 \return a pointer to the value referred to by this DataReference.
1246*/
1247
1248/*!
1249 \fn template <typename Range, typename Protocol, typename Model> bool QRangeModelAdapter<Range, Protocol, Model>::DataReference::isValid() const
1250 \return true if this DataReference refers to a valid model index.
1251*/
1252
1253/*!
1254 \class QRangeModelAdapter::RowReferenceBase
1255 \inmodule QtCore
1256 \since 6.11
1257 \preliminary
1258 \ingroup model-view
1259 \brief RowReferenceBase provides common API for RowReference and ConstRowReference.
1260
1261 For models that are tables or trees, accessing a row of an adapter using
1262 \l{QRangeModelAdapter::}{at()}, subscript \l{QRangeModelAdapter::operator[]()}
1263 {operator[]}, or dereferencing a RowIterator, returns a RowReference or
1264 ConstRowReference to the specified row.
1265
1266 \sa DataReference
1267*/
1268
1269/*!
1270 \fn template <typename Range, typename Protocol, typename Model> template <typename Reference, typename Adapter> template <typename I = Impl, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>> bool QRangeModelAdapter<Range, Protocol, Model>::RowReferenceBase<Reference, Adapter>::hasChildren() const
1271
1272 \return true if the referenced row has one or more child rows, otherwise false.
1273
1274 \constraints \c Range is a tree.
1275*/
1276
1277/*!
1278 \fn template <typename Range, typename Protocol, typename Model> template <typename Reference, typename Adapter> template <typename I = Impl, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>> auto QRangeModelAdapter<Range, Protocol, Model>::RowReferenceBase<Reference, Adapter>::children() const
1279
1280 \return a QRangeModelAdapter operating on the same range and model as this adapter, and with
1281 this row as the root index.
1282
1283 \constraints \c Range is a tree.
1284*/
1285
1286/*!
1287 \fn template <typename Range, typename Protocol, typename Model> template <typename Reference, typename Adapter> ConstColumnIterator QRangeModelAdapter<Range, Protocol, Model>::RowReferenceBase<Reference, Adapter>::cbegin() const
1288
1289 \return a ConstColumnIterator pointing to the first column of this row.
1290*/
1291
1292/*!
1293 \fn template <typename Range, typename Protocol, typename Model> template <typename Reference, typename Adapter> ConstColumnIterator QRangeModelAdapter<Range, Protocol, Model>::RowReferenceBase<Reference, Adapter>::begin() const
1294
1295 \return a ConstColumnIterator pointing to the first column of this row.
1296*/
1297
1298/*!
1299 \fn template <typename Range, typename Protocol, typename Model> template <typename Reference, typename Adapter> ConstColumnIterator QRangeModelAdapter<Range, Protocol, Model>::RowReferenceBase<Reference, Adapter>::cend() const
1300
1301 \return a ConstColumnIterator pointing just after the last column of this row.
1302*/
1303
1304/*!
1305 \fn template <typename Range, typename Protocol, typename Model> template <typename Reference, typename Adapter> ConstColumnIterator QRangeModelAdapter<Range, Protocol, Model>::RowReferenceBase<Reference, Adapter>::end() const
1306
1307 \return a ConstColumnIterator pointing just after the last column of this row.
1308*/
1309
1310/*!
1311 \fn template <typename Range, typename Protocol, typename Model> template <typename Reference, typename Adapter> size_type QRangeModelAdapter<Range, Protocol, Model>::RowReferenceBase<Reference, Adapter>::size() const
1312
1313 \return the number of columns in the model.
1314
1315 This returns the same value for all rows in the model.
1316*/
1317
1318/*!
1319 \fn template <typename Range, typename Protocol, typename Model> template <typename Reference, typename Adapter> auto QRangeModelAdapter<Range, Protocol, Model>::RowReferenceBase<Reference, Adapter>::at(int column) const
1320 \fn template <typename Range, typename Protocol, typename Model> template <typename Reference, typename Adapter> auto QRangeModelAdapter<Range, Protocol, Model>::RowReferenceBase<Reference, Adapter>::operator[](int column) const
1321
1322 \return a reference wrapper to the item at \a column of this row.
1323
1324 Depending on the data structure the adapter operates on, the returned value
1325 is a const reference wrapper, a pointer to a const object, or a QVariant.
1326*/
1327
1328/*!
1329 \class QRangeModelAdapter::RowReference
1330 \inmodule QtCore
1331 \since 6.11
1332 \preliminary
1333 \ingroup model-view
1334 \brief RowReference is a reference wrapper around a row in a QRangeModel.
1335
1336 For ranges that are tables or trees, accessing a row of a QRangeModelAdapter
1337 using the non-const overloads of \l{QRangeModelAdapter::}{at()} or subscript
1338 \l{QRangeModelAdapter::operator[]()}{operator[]}, or by dereferencing a
1339 RowIterator, returns a RowReference for the specified row.
1340
1341 \sa ConstRowReference, DataReference
1342*/
1343
1344/*!
1345 \typedef QRangeModelAdapter::RowReference::row_type
1346
1347 An alias for the type of the rows in the underlying range.
1348*/
1349
1350/*!
1351 \fn template <typename Range, typename Protocol, typename Model> RowReference &QRangeModelAdapter<Range, Protocol, Model>::RowReference::operator=(const RowReference &other)
1352 \fn template <typename Range, typename Protocol, typename Model> RowReference &QRangeModelAdapter<Range, Protocol, Model>::RowReference::operator=(const ConstRowReference &other)
1353
1354 Assigns the row referenced by \a other to the row referenced by this, emitting
1355 dataChanged for all items in the row.
1356
1357//! [rowref-assign]
1358 If the model is a tree, and the referenced row has children, then those children
1359 are removed from the model. If the row referenced by \a other has children,
1360 then those children are inserted into the model.
1361//! [rowref-assign]
1362*/
1363
1364/*!
1365 \fn template <typename Range, typename Protocol, typename Model> RowReference &QRangeModelAdapter<Range, Protocol, Model>::RowReference::operator=(const row_type &other)
1366 \fn template <typename Range, typename Protocol, typename Model> RowReference &QRangeModelAdapter<Range, Protocol, Model>::RowReference::operator=(row_type &&other)
1367
1368 Assigns the row \a other to the row referenced by this, emitting dataChanged
1369 for all items in the row.
1370
1371 \include qrangemodeladapter.qdoc rowref-assign
1372*/
1373
1374/*!
1375 \fn template <typename Range, typename Protocol, typename Model> QRangeModelAdapter<Range, Protocol, Model>::RowReference::operator ConstRowReference() const
1376
1377 \return a ConstRowReference referencing the same row as this.
1378*/
1379
1380/*!
1381 \fn template <typename Range, typename Protocol, typename Model> template <typename I = Impl, QRangeModelAdapter<Range, Protocol, Model>::if_tree<I>> auto QRangeModelAdapter<Range, Protocol, Model>::RowReference::children()
1382
1383 \return a QRangeModelAdapter operating on the same range and model as this adapter, and with
1384 this row as the root index.
1385
1386 \constraints \c Range is a tree.
1387*/
1388
1389/*!
1390 \fn template <typename Range, typename Protocol, typename Model> ColumnIterator QRangeModelAdapter<Range, Protocol, Model>::RowReference::begin()
1391
1392 \return a ColumnIterator pointing to the first column of this row.
1393*/
1394
1395/*!
1396 \fn template <typename Range, typename Protocol, typename Model> ColumnIterator QRangeModelAdapter<Range, Protocol, Model>::RowReference::end()
1397
1398 \return a ColumnIterator pointing just after the last column of this row.
1399*/
1400
1401/*!
1402 \fn template <typename Range, typename Protocol, typename Model> auto QRangeModelAdapter<Range, Protocol, Model>::RowReference::at(int column)
1403 \fn template <typename Range, typename Protocol, typename Model> auto QRangeModelAdapter<Range, Protocol, Model>::RowReference::operator[](int column)
1404
1405 \return a reference wrapper to the item at \a column of this row.
1406*/
1407
1408
1409/*!
1410 \class QRangeModelAdapter::ConstRowReference
1411 \inmodule QtCore
1412 \since 6.11
1413 \preliminary
1414 \ingroup model-view
1415 \brief ConstRowReference is a reference wrapper around a const row in a QRangeModel.
1416
1417 For ranges that are tables or trees, accessing a row of a QRangeModelAdapter
1418 using the const overloads of \l{QRangeModelAdapter::}{at()} or subscript
1419 \l{QRangeModelAdapter::operator[]()}{operator[]}, or by dereferencing a
1420 ConstRowIterator, returns a ConstRowReference for the specified row.
1421
1422 \sa RowReference, DataReference
1423*/
1424
1425/*!
1426 \class QRangeModelAdapter::RowIterator
1427 \inmodule QtCore
1428 \since 6.11
1429 \preliminary
1430 \ingroup model-view
1431 \brief Provides an STL-style non-const iterator over the rows of a model.
1432
1433 The iterator models \c{std::random_access_iterator}. If the model is a list,
1434 then dereferencing the iterator returns a DataReference wrapper for the
1435 pointed-to item in the model.
1436
1437 For tables and trees, dereferencing the iterator returns a RowReference for
1438 the pointed-to row.
1439*/
1440
1441/*!
1442 \class QRangeModelAdapter::ConstRowIterator
1443 \inmodule QtCore
1444 \since 6.11
1445 \preliminary
1446 \ingroup model-view
1447 \brief Provides an STL-style const iterator over the rows of a model.
1448
1449 The iterator models \c{std::random_access_iterator}. If the model is a list,
1450 then dereferencing the iterator returns the pointed-to item in the model.
1451
1452 For tables and trees, dereferencing the iterator returns a ConstRowReference
1453 for the pointed-to row.
1454*/
1455
1456/*!
1457 \class QRangeModelAdapter::ColumnIterator
1458 \inmodule QtCore
1459 \since 6.11
1460 \preliminary
1461 \ingroup model-view
1462 \brief Provides an STL-style non-const iterator over the columns in a model row.
1463
1464 The iterator models \c{std::random_access_iterator}. Dereferencing the iterator
1465 returns a DataReference wrapper for the value at the pointed-to item in
1466 the model.
1467*/
1468
1469/*!
1470 \class QRangeModelAdapter::ConstColumnIterator
1471 \inmodule QtCore
1472 \since 6.11
1473 \preliminary
1474 \ingroup model-view
1475 \brief Provides an STL-style non-const iterator over the columns in a model row.
1476
1477 The iterator models \c{std::random_access_iterator}. Dereferencing the iterator
1478 returns the const value at the pointed-to item in the model.
1479*/