Qt 5.8 | QDoc Manual | Document Navigation

Qt 5.8.0 Reference Documentation

Context Commands ◦ Status

# 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
           \contentspage {Basic Qt} {Contents}
           \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
          \contentspage {Basic Qt} {Contents}
          \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
          \contentspage {Basic Qt} {Contents}

          \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
      */

QDoc renders the "Getting Started" page in `creatingdialogs.html`:

> [Previous: Basic Qt] [Contents] [Next: Creating Dialogs]

> # 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.

> [Previous: Basic Qt] [Contents] [Next: Creating Dialogs]

The \indexpage and \startpage commands create links to the page's index page and start page. These links can be used by browsers and search engines.

The index page is typically an alphabetical list of the document's titles and topics, while the start page is the page considered by the author to be the starting point of a multipage document.

The links are included in the generated HTML source code, but have no visual effect on the documentation:

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

## Commands

### \previouspage

The \previouspage command links the current page to the previous page in a sequence.a 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.

### \contentspage

The \contentspage command links the current page to a table of contents page. The command follows the same syntax and argument convention as the \previouspage command.

### \indexpage

The \indexpage command specifies an index page for the current document. The command must stand alone on its own line, and its unique argument is the title of the index document.

QDoc will generate a link to the index 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 index page of the collection.