PageRouter

View on LXR

#include <pagerouter.h>

Inheritance diagram for PageRouter:

Properties
int	cacheCapacity

QJSValue	initialRoute

ColumnView	pageStack

int	preloadedPoolCapacity

QQmlListProperty< PageRoute >	routes

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< PageRoute >	routes ()

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 QObjectList &	children () 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< QByteArray >	dynamicPropertyNames () const const

virtual bool	event (QEvent *e)

virtual bool	eventFilter (QObject watched, QEvent event)

T	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 QMetaObject *	metaObject () const const

void	moveToThread (QThread *targetThread)

QString	objectName () const const

void	objectNameChanged (const QString &objectName)

QObject *	parent () 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

T	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)

T	qobject_cast (QObject *object)

T	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)

QThread *	thread () const const

Static Public Member Functions
static PageRouterAttached *	qmlAttachedProperties (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

QObject *	sender () 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.

You can push pages onto this stack...

...or pop them off...

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

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

view	The 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 275 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 697 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

route

The 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 235 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 319 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

route The 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 313 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

route The 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 294 of file pagerouter.cpp.

The documentation for this class was generated from the following files:

KDE's Doxygen guidelines are available online.

PageRouter

Properties

Signals

Public Member Functions

Static Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Using a PageRouter

Navigation Model

Example

Property Documentation

Member Function Documentation