Document Navigation

The navigation commands are for linking the pages of a document in a meaningful sequence. Below is a sequence of QDoc comments that shows a typical use of the navigation commands.

Example

 /*!
     \page basicqt.html
     \nextpage Getting Started

     \indexpage Index
     \startpage Basic Qt

     \title Basic Qt

     The Qt toolkit is a C++ class library and a set of tools for
     building multiplatform GUI programs using a "write once,
     compile anywhere approach".

     Table of contents:

     \list
     \li \l {Getting Started}
     \li \l {Creating Dialogs}
     \li \l {Creating Main Windows}
     \endlist
 */

 /*!
    \page gettingstarted.html
    \previouspage Basic Qt
    \nextpage Creating Dialogs

    \indexpage Index
    \startpage Basic Qt

    \title Getting Started

    This chapter shows how to combine basic C++ with the
    functionality provided by Qt to create a few small graphical
    interface (GUI) applications.
*/

/*!
    \page creatingdialogs.html
    \previouspage Getting Started

    \indexpage Index
    \startpage Basic Qt

    \title Creating Dialogs

    This chapter will teach you how to create dialog boxes using Qt.
*/

/*!
    \page index.html

    \indexpage Index
    \startpage Basic Qt

    \title Index

    \list
        \li \l {Basic Qt}
        \li \l {Creating Dialogs}
        \li \l {Getting Started}
    \endlist
*/

The \startpage command creates a link to the page the author wants as the first page of a multipage document.

The link is included in the generated HTML source code but has no visual effect on the documentation:

<head>
    ...
    <link rel="start" href="basicqt.html" />
    ...
</head>

Commands

\previouspage

The \previouspage command links the current page to the previous page in a sequence. The command has two arguments, each enclosed by curly braces: the first is the link target (the title of the previous page), the second is the link text. If the page's title is equivalent to the link text, the second argument can be omitted.

The command must stand alone on its own line.

\nextpage

The \nextpage command links the current page to the next page in a sequence. The command follows the same syntax and argument convention as the \previouspage command.

\startpage

The \startpage command specifies the first page of a sequence of pages. The command must stand alone on its own line, and its unique argument is the title of the first document.

QDoc will generate a link to the start page and include it in the generated HTML file, but this has no visual effect on the documentation. The generated link type tells browsers and search engines which document is considered by the author to be the starting point of the collection.

\toc

The \toc and \endtoc commands specify a list of sub-topics (pages) for the topic the command appears in. A table of contents (TOC) hierarchy is generated for the entire documentation project based on the TOC entries on each topic.

Within the \toc .. \endtoc block, use \tocentry commands to specify the sub-topics by title. Like the \l (link) command, \tocentry takes an optional second argument for the user-visible title in the generated TOC entry.

/*!
    \page index.html
    \title Qt
    ...
    \toc
        \tocentry {Introduction to Qt} {Introduction}
        \tocentry {What's new in Qt} {What's new}
        \tocentry {Getting started}
    \endtoc
*/

\toc commands cannot be nested. However, each sub-topic can specify their own TOC entries. A topic can use only one \toc command.

QDoc writes the resulting table of contents structure in XML format to a <project>_toc.xml file.

Note: The root topic (index or landing page) must be specified in the project configuration with either navigation.landingpage or navigation.homepage. See navigation for more information.

The \toc command was introduced to QDoc with Qt 6.11.

\tocentry

Specifies a sub-topic (page) as an entry in table of contents. Can only be used inside a pair of \toc and \endtoc commands.

The \tocentry command was introduced to QDoc with Qt 6.11.