Confusing documentation about PageRow
I found the Kirigami tutorial pretty great until https://develop.kde.org/docs/kirigami/components-pagerow_pagestack/ which is useful for concepts, but contains a whole lot of dead links. In particular, all of the PageRow API docs links lead to 404 pages.
But even if I go directly to the current Kirigami API reference page, I'm having trouble finding useful information about how the page stack is exactly put together or should be used:
- On the above-mentioned API reference page, there is no link to PageRow apidox. If I manually try navigating to where the PageRow docs should be, I get a 404. No such docs are apparently being generated in the first place.
ApplicationWindow, in its class description, tells you that it's "based around the PageRow component". The
pageStackproperty is auto-labeled as an
aliashere, which in its property description mentions that "it's using a PageRow, while having the same API as PageStack". Unfortunately there is no pointer to the API documentation of either component, because those pages don't exist. It does, however, have a "See also" pointer to
AbstractApplicationWidnow[sic], so let's look there.
AbstractApplicationWindow says in the autogenerated header that it's an
Item, then in the description of that property starts with
pageStack: StackViewand telling you to assign something like a QQuickControls
StackViewto that property.
PageRouter calls its
ColumnViewwhich should, according to the code example, be initialized from
applicationWindow.pageStack.columnView. This tells me at least a little bit about the supposed PageRow documentation, namely that I can expect to find a
ColumnViewin it. That's great! ColumnView isn't linked from the Main Page but guessing its URL does in fact lead me to an existing apidox page for ColumnView. On the other hand, PageRouter mentions that one shouldn't directly interact with the ColumnView puppeteered by it, so presumably the same is true for the elusive PageRow? But let's have a look anyway.
ColumnView finally provides some information that I'm looking for, such as the
firstVisibleItemproperty. I'm guessing that I can access this via
applicationWindow().pageStack.firstVisibleItemand indeed, this exists and can be used for writing QML conditions. Note: I was in earlier stages of my discovery adventure and missed the fact that it should have been
applicationWindow.pageStack.columnView.firstVisibleItemif I were to deduce this more correctly. Nevertheless, it also works without the extra
.columnView, so I'm lucky.
- I saw in kirigami2gallery that it's possible to pin a Page. This seems useful! However, the otherwise extensive ColumnView documentation loses no word on this feature, despite @mart's pinned pages commit clearly referencing
root.ColumnView.pinned. So what's going on here? Turns out I'm a QML noob and this is an "attached property" which isn't part of the actual
ColumnViewclass. ColumnView apidox actually mention this, but the only link to the documentation for these attached properties is through the generated line for the
qmlAttachedProperties()function signature, which I had missed until just now because I wasn't specifically looking for ColumnViewAttached and, as mentioned, QML noob here. I learn out how to use attached properties and manage to statically pin my page. (This doesn't have the effect I was looking for exactly, but that's a different issue.)
Page seems related, but other than mentioning the ApplicationWindow's
pageStack, doesn't provide further pointers or links. I reckon this makes sense, because you could put a Page into a variety of different containers so ApplicationWindow really is the right place for that discussion.
- And yes, if I follow the property documentation of ApplicationWindow's
pageStackvariable into the linked source, I can indeed see that PageRow is really a thing and not just some obsolete class that got refactored into something else. PageRow is used directly as a component there. But where does it come from? What is its API of that of the also-mentioned PageStack, apart from the few properties that I can see getting manually assigned inside ApplicationWindow? I still don't know.
I don't want to come across as a downer because by and large, the Kirigami documentation is quite helpful, even if you have to look into a few different places to get the hang of it. But for PageRow in particular, a seemingly central concept which is referenced in a lot of places and documented nowhere, the docs are indeed endlessly confusing for a relative newcomer like myself. Now that I know all of the above, I'll go and read the source file here in this repository, because hey, at least it exists. It would be so nice if the different pieces were coming together more helpfully in the actual documentation though.