Dokumentennavigation

Die Navigationsbefehle dienen dazu, die Seiten eines Dokuments in einer sinnvollen Reihenfolge miteinander zu verknüpfen. Nachfolgend finden Sie eine Abfolge von QDoc-Kommentaren, die eine typische Verwendung der Navigationsbefehle veranschaulicht.

Beispiel

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

Der \startpage Befehl erstellt einen Link zu der Seite, die der Autor als erste Seite eines mehrseitigen Dokuments festlegen möchte.

Der Link wird in den generierten HTML-Quellcode aufgenommen, hat jedoch keine sichtbaren Auswirkungen auf die Dokumentation:

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

Befehle

\previouspage

Der Befehl „ \previouspage “ verlinkt die aktuelle Seite mit der vorherigen Seite in einer Sequenz. Der Befehl hat zwei Argumente, die jeweils in geschweifte Klammern gesetzt sind: Das erste ist das Linkziel (der Titel der vorherigen Seite), das zweite ist der Linktext. Wenn der Titel der Seite mit dem Linktext übereinstimmt, kann das zweite Argument weggelassen werden.

Der Befehl muss allein in einer eigenen Zeile stehen.

\nextpage

Der Befehl „ \nextpage “ verlinkt die aktuelle Seite mit der nächsten Seite in einer Sequenz. Der Befehl folgt derselben Syntax und den gleichen Argumentkonventionen wie der \previouspage Befehl.

\startpage

Der Befehl „ \startpage “ gibt die erste Seite einer Seitenfolge an. Der Befehl muss allein in einer eigenen Zeile stehen, und sein einziges Argument ist der Titel des ersten Dokuments.

QDoc generiert einen Link zur Startseite und fügt ihn in die erzeugte HTML-Datei ein, was jedoch keine sichtbaren Auswirkungen auf die Dokumentation hat. Der generierte Linktyp teilt Browsern und Suchmaschinen mit, welches Dokument vom Autor als Ausgangspunkt der Sammlung angesehen wird.

\toc

Die Befehle „ \toc “ und „ \endtoc “ geben eine Liste von Unterthemen (Seiten) für das Thema an, in dem der Befehl erscheint. Basierend auf den Inhaltsverzeichnis-Einträgen jedes Themas wird eine Inhaltsverzeichnis-Hierarchie für das gesamte Dokumentationsprojekt generiert.

Verwenden Sie innerhalb des Blocks „ \toc … \endtoc “ die \tocentry Befehle, um die Unterthemen anhand ihres Titels anzugeben. Ähnlich wie beim \l (link)-Befehl akzeptiert auch „ \tocentry “ ein optionales zweites Argument für den für den Benutzer sichtbaren Titel im generierten Inhaltsverzeichnis-Eintrag.

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

\tocBefehle können nicht verschachtelt werden. Jedes Unterthema kann jedoch eigene Inhaltsverzeichnis-Einträge festlegen. Ein Thema darf nur einen \toc -Befehl verwenden.

QDoc schreibt die resultierende Inhaltsverzeichnisstruktur im XML-Format in eine Datei namens <project>_toc.xml.

Der Befehl „ \toc “ wurde mit Qt 6.11 in QDoc eingeführt.

Siehe auch \tocentry.

\tocentry

Legt ein Unterthema (eine Seite) als Eintrag im Inhaltsverzeichnis fest. Kann nur innerhalb eines Paares aus den Befehlen „ \toc “ und „ \endtoc “ verwendet werden.

Der Befehl „ \tocentry “ wurde mit Qt 6.11 in QDoc eingeführt.

Siehe auch \toc.