Navigation dans le document

Les commandes de navigation permettent de relier les pages d'un document selon un ordre logique. Vous trouverez ci-dessous une séquence de commentaires QDoc illustrant une utilisation typique des commandes de navigation.

Exemple

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

La \startpage commande crée un lien vers la page que l'auteur souhaite voir apparaître en première page d'un document comportant plusieurs pages.

Le lien est inclus dans le code source HTML généré, mais n'a aucun effet visuel sur la documentation :

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

Commandes

\previouspage

La commande \previouspage crée un lien entre la page actuelle et la page précédente dans une séquence. Cette commande prend deux arguments, chacun entre accolades : le premier est la cible du lien (le titre de la page précédente), le second est le texte du lien. Si le titre de la page est identique au texte du lien, le deuxième argument peut être omis.

La commande doit figurer seule sur une ligne distincte.

\nextpage

La commande \nextpage crée un lien entre la page actuelle et la page suivante d'une séquence. Cette commande suit la même syntaxe et les mêmes conventions d'arguments que la \previouspage commande.

\startpage

La commande \startpage spécifie la première page d'une séquence de pages. La commande doit figurer seule sur une ligne distincte, et son seul argument est le titre du premier document.

QDoc génère un lien vers la page d'accueil et l'intègre dans le fichier HTML généré, mais cela n'a aucun effet visuel sur la documentation. Le type de lien généré indique aux navigateurs et aux moteurs de recherche quel document est considéré par l'auteur comme le point de départ de la collection.

\toc

Les commandes \toc et \endtoc spécifient une liste de sous-rubriques (pages) pour la rubrique dans laquelle la commande apparaît. Une hiérarchie de table des matières (TDM) est générée pour l’ensemble du projet de documentation à partir des entrées de la table des matières de chaque rubrique.

Au sein du bloc \toc.. \endtoc, utilisez les \tocentry pour spécifier les sous-rubriques par leur titre. À l’instar de la \l commande (link), \tocentry accepte un deuxième argument facultatif correspondant au titre visible par l’utilisateur dans l’entrée de la table des matières générée.

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

\tocLes commandes ne peuvent pas être imbriquées. Cependant, chaque sous-rubrique peut définir ses propres entrées de table des matières. Une rubrique ne peut utiliser qu’une seule commande \toc.

QDoc écrit la structure de table des matières obtenue au format XML dans un fichier <project>_toc.xml.

La commande \toc a été introduite dans QDoc avec Qt 6.11.

Voir également \tocentry.

\tocentry

Spécifie une sous-rubrique (page) comme entrée dans la table des matières. Ne peut être utilisé qu'entre deux commandes « \toc » et « \endtoc ».

La commande \tocentry a été introduite dans QDoc avec Qt 6.11.

Voir aussi \toc.