PageRouter

#include <pagerouter.h>

Inheritance diagram for PageRouter:

Properties

int cacheCapacity
 
QJSValue initialRoute
 
ColumnView pageStack
 
int preloadedPoolCapacity
 
QQmlListProperty< PageRouteroutes
 
- Properties inherited from QObject
 objectName
 

Signals

void currentIndexChanged ()
 
void initialRouteChanged ()
 
void navigationChanged ()
 
void pageStackChanged ()
 
void routesChanged ()
 

Public Member Functions

 PageRouter (QQuickItem *parent=nullptr)
 
Q_INVOKABLE void bringToView (QJSValue route)
 
int cacheCapacity () const
 
Q_INVOKABLE QJSValue currentRoutes () const
 
QJSValue initialRoute () const
 
Q_INVOKABLE void navigateToRoute (QJSValue route)
 
Q_INVOKABLE void popRoute ()
 
int preloadedPoolCapacity () const
 
Q_INVOKABLE void pushRoute (QJSValue route)
 
Q_INVOKABLE bool routeActive (QJSValue route)
 
QQmlListProperty< PageRouteroutes ()
 
void setCacheCapacity (int size)
 
void setInitialRoute (QJSValue initialRoute)
 
void setPreloadedPoolCapacity (int size)
 
- Public Member Functions inherited from QObject
 QObject (QObject *parent)
 
bool blockSignals (bool block)
 
const QObjectListchildren () const const
 
QMetaObject::Connection connect (const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type) const const
 
void deleteLater ()
 
void destroyed (QObject *obj)
 
bool disconnect (const char *signal, const QObject *receiver, const char *method) const const
 
bool disconnect (const QObject *receiver, const char *method) const const
 
void dumpObjectInfo ()
 
void dumpObjectInfo () const const
 
void dumpObjectTree ()
 
void dumpObjectTree () const const
 
QList< QByteArraydynamicPropertyNames () const const
 
virtual bool event (QEvent *e)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
findChild (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const
 
bool inherits (const char *className) const const
 
void installEventFilter (QObject *filterObj)
 
bool isWidgetType () const const
 
bool isWindowType () const const
 
void killTimer (int id)
 
virtual const QMetaObjectmetaObject () const const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const const
 
void objectNameChanged (const QString &objectName)
 
QObjectparent () const const
 
QVariant property (const char *name) const const
 
 Q_CLASSINFO (Name, Value)
 
 Q_DISABLE_COPY (Class)
 
 Q_DISABLE_COPY_MOVE (Class)
 
 Q_DISABLE_MOVE (Class)
 
 Q_EMIT Q_EMIT
 
 Q_ENUM (...)
 
 Q_ENUM_NS (...)
 
 Q_ENUMS (...)
 
 Q_FLAG (...)
 
 Q_FLAG_NS (...)
 
 Q_FLAGS (...)
 
 Q_GADGET Q_GADGET
 
 Q_INTERFACES (...)
 
 Q_INVOKABLE Q_INVOKABLE
 
 Q_NAMESPACE Q_NAMESPACE
 
 Q_NAMESPACE_EXPORT (EXPORT_MACRO)
 
 Q_OBJECT Q_OBJECT
 
 Q_PROPERTY (...)
 
 Q_REVISION Q_REVISION
 
 Q_SET_OBJECT_NAME (Object)
 
 Q_SIGNAL Q_SIGNAL
 
 Q_SIGNALS Q_SIGNALS
 
 Q_SLOT Q_SLOT
 
 Q_SLOTS Q_SLOTS
 
qFindChild (const QObject *obj, const QString &name)
 
QList< T > qFindChildren (const QObject *obj, const QRegExp &regExp)
 
QList< T > qFindChildren (const QObject *obj, const QString &name)
 
qobject_cast (QObject *object)
 
qobject_cast (const QObject *object)
 
 QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const char *name, const QVariant &value)
 
bool signalsBlocked () const const
 
int startTimer (int interval, Qt::TimerType timerType)
 
int startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)
 
QThreadthread () const const
 

Static Public Member Functions

static PageRouterAttachedqmlAttachedProperties (QObject *object)
 
- Static Public Member Functions inherited from QObject
QMetaObject::Connection connect (const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *context, Functor functor, Qt::ConnectionType type)
 
bool disconnect (const QMetaObject::Connection &connection)
 
bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *method)
 
bool disconnect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)
 
bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)
 
QString tr (const char *sourceText, const char *disambiguation, int n)
 
QString trUtf8 (const char *sourceText, const char *disambiguation, int n)
 

Protected Member Functions

void classBegin () override
 
void componentComplete () override
 
- Protected Member Functions inherited from QObject
virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const QMetaMethod &signal)
 
virtual void customEvent (QEvent *event)
 
virtual void disconnectNotify (const QMetaMethod &signal)
 
bool isSignalConnected (const QMetaMethod &signal) const const
 
int receivers (const char *signal) const const
 
QObjectsender () const const
 
int senderSignalIndex () const const
 
virtual void timerEvent (QTimerEvent *event)
 

Additional Inherited Members

- Public Attributes inherited from QObject
typedef QObjectList
 

Detailed Description

An item managing pages and data of a ColumnView using named routes.



Using a PageRouter

Applications typically manage their contents via elements called "pages" or "screens." In Kirigami, these are called Pages and are arranged in routes using a PageRouter to manage them. The PageRouter manages a stack of Pages created from a pool of potential PageRoutes .

Unlike most traditional stacks, a PageRouter provides functions for random access to its pages with navigateToRoute and routeActive.

When your user interface fits the stack paradigm and is likely to use random access navigation, using the PageRouter is appropriate. For simpler navigation, it is more appropriate to avoid the overhead of a PageRouter by using a PageRow instead.



Navigation Model

A PageRouter draws from a pool of PageRoutes in order to construct its stack.

PageRouterModel.svg



You can push pages onto this stack...

PageRouterPush.svg

...or pop them off...

PageRouterPop.svg

...or navigate to an arbitrary collection of pages.

PageRouterNavigate.svg



Components are able to query the PageRouter about the currently active routes on the stack. This is useful for e.g. a card indicating that the page it takes the user to is currently active.



Example

import QtQuick 2.12
import QtQuick.Controls 2.12 as QQC2
import org.kde.kirigami 2.12 as Kirigami
Kirigami.ApplicationWindow {
id: applicationWindow
Kirigami.PageRouter {
initialRoute: "home"
pageStack: applicationWindow.pageStack.columnView
Kirigami.PageRoute {
name: "home"
cache: false
Component {
Kirigami.Page {
Column {
Kirigami.Heading {
text: "Welcome"
}
QQC2.Button {
text: "Red Login"
onClicked: Kirigami.PageRouter.navigateToRoute(["home", {"route": "login", "data": "red"}])
}
QQC2.Button {
text: "Blue Login"
onClicked: Kirigami.PageRouter.navigateToRoute(["home", {"route": "login", "data": "blue"}])
}
}
}
}
}
Kirigami.PageRoute {
name: "login"
cache: true
Component {
Kirigami.Page {
Column {
Kirigami.Heading {
text: "Login"
}
Rectangle {
height: 50
width: 50
color: Kirigami.PageRouter.data
}
QQC2.Button {
text: "Back to Home"
onClicked: Kirigami.PageRouter.navigateToRoute("home")
}
}
}
}
}
}
}
See also
PageRouterAttached
PageRoute

Definition at line 297 of file pagerouter.h.

Property Documentation

int PageRouter::cacheCapacity
readwrite

How large the cache can be.

The combined costs of cached routes will never exceed the cache capacity.

Definition at line 342 of file pagerouter.h.

QJSValue PageRouter::initialRoute
readwrite

The initial route.

initialRoute is the page that the PageRouter will push upon creation. Changing it after creation will cause the PageRouter to reset its state. Not providing an initialRoute will result in undefined behavior.

import QtQuick 2.12
import org.kde.kirigami 2.12 as Kirigami
Kirigami.ApplicationWindow {
id: applicationWindow
Kirigami.PageRouter {
initialRoute: "home"
pageStack: applicationWindow.pageStack.columnView
Kirigami.PageRoute {
name: "home"
Component {
Kirigami.Page {
// This page will show up when starting the application
}
}
}
Kirigami.PageRoute {
name: "login"
Component {
Kirigami.Page {
// Page contents...
}
}
}
}
}

Definition at line 321 of file pagerouter.h.

ColumnView PageRouter::pageStack

The ColumnView being puppeted by the PageRouter.

All PageRouters should be created with a ColumnView, and creating one without a ColumnView is undefined behaviour.

Warning
You should not directly interact with a ColumnView being puppeted by a PageRouter. Instead, use a PageRouter's functions to manipulate the ColumnView.
import QtQuick 2.12
import org.kde.kirigami 2.12 as Kirigami
Kirigami.ApplicationWindow {
id: applicationWindow
Kirigami.PageRouter {
pageStack: applicationWindow.pageStack.columnView
Kirigami.PageRoute {
name: "home"
Component {
Kirigami.Page {
// Page contents...
}
}
}
initialRoute: "home"
Component.onCompleted: navigateToRoute("home", "home")
}
}

Definition at line 335 of file pagerouter.h.

int PageRouter::preloadedPoolCapacity
readwrite

How large the preloaded pool can be.

The combined costs of preloaded routes will never exceed the pool capacity.

Definition at line 349 of file pagerouter.h.

QQmlListProperty< PageRoute > PageRouter::routes
read

The named routes a PageRouter can navigate to.

import QtQuick 2.12
import org.kde.kirigami 2.12 as Kirigami
Kirigami.ApplicationWindow {
id: applicationWindow
Kirigami.PageRouter {
pageStack: applicationWindow.pageStack.columnView
Kirigami.PageRoute {
name: "routeOne"
Component {
Kirigami.Page {
// Page contents...
}
}
}
Kirigami.PageRoute {
name: "routeTwo"
Component {
Kirigami.Page {
// Page contents...
}
}
}
Kirigami.PageRoute {
name: "routeThree"
Component {
Kirigami.Page {
// Page contents...
}
}
}
}
}

Definition at line 307 of file pagerouter.h.

Member Function Documentation

void PageRouter::bringToView ( QJSValue  route)

Shifts keyboard focus and view to a given index on the PageRouter's stack.

Parameters
viewThe view to bring to focus. If this is an integer index, the PageRouter will navigate to the given index. If it's a route specifier, the PageRouter will navigate to the first route matching it.

Navigating to route by index:

Kirigami.PageRouter.navigateToRoute(["/home", "/browse", "/apps", "/login"])
Kirigami.PageRouter.bringToView(1)

Navigating to route by name:

Kirigami.PageRouter.navigateToRoute(["/home", "/browse", "/apps", "/login"])
Kirigami.PageRouter.bringToView("/browse")

Navigating to route by data:

Kirigami.PageRouter.navigateToRoute([{"route": "/page", "data": "red"},
{"route": "/page", "data": "blue"},
{"route": "/page", "data": "green"},
{"route": "/page", "data": "yellow"}])
Kirigami.PageRouter.bringToView({"route": "/page", "data": "blue"})

Definition at line 276 of file pagerouter.cpp.

QJSValue PageRouter::currentRoutes ( ) const

Returns a QJSValue corresponding to the current pages on the stack.

The returned value is in the same form as the input to navigateToRoute.

Definition at line 700 of file pagerouter.cpp.

void PageRouter::navigateToRoute ( QJSValue  route)

Navigate to the given route.

Calling navigateToRoute causes the PageRouter to replace currently active pages with the new route.

Parameters
routeThe given route for the PageRouter to navigate to. A route is an array of variants or a single item. A string item will be interpreted as a page without associated data. An object item will be interpreted as follows:
{
"route": "/home" // The named page of the route.
"data": QtObject {} // The data to pass to the page.
}
Navigating to a route not defined in a PageRouter's routes is undefined behavior.
Button {
text: "Login"
onClicked: {
Kirigami.PageRouter.navigateToRoute(["/home", "/login"])
}
}

Definition at line 236 of file pagerouter.cpp.

void PageRouter::popRoute ( )

Pops the last page on the router.

Calling popRoute will result in the last page on the router getting popped. You should not call this function when there is only one page on the router.

Kirigami.PageRouter.navigateToRoute(["/home", "/login"])
// The PageRouter is navigated to /home/login
Kirigami.PageRouter.popRoute()
// The PageRouter is navigated to /home

Definition at line 320 of file pagerouter.cpp.

void PageRouter::pushRoute ( QJSValue  route)

Appends a route to the currently navigated route.

Calling pushRoute will append the given route to the currently navigated routes. See navigateToRoute() if you want to replace the items currently on the PageRouter.

Parameters
routeThe given route to push.
Kirigami.PageRouter.navigateToRoute(["/home", "/login"])
// The PageRouter is navigated to /home/login
Kirigami.PageRouter.pushRoute("/google")
// The PageRouter is navigated to /home/login/google

Definition at line 314 of file pagerouter.cpp.

bool PageRouter::routeActive ( QJSValue  route)

Check whether the current route is on the stack.

routeActive will return true if the given route is on the stack.

Parameters
routeThe given route to check for.

routeActive returns true for partial routes like the following:

Kirigami.PageRouter.navigateToRoute(["/home", "/login", "/google"])
Kirigami.PageRouter.routeActive(["/home", "/login"]) // returns true

This only works from the root page, e.g. the following will return false:

Kirigami.PageRouter.navigateToRoute(["/home", "/login", "/google"])
Kirigami.PageRouter.routeActive(["/login", "/google"]) // returns false

Definition at line 295 of file pagerouter.cpp.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Thu Dec 3 2020 22:38:40 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.