Externen Code einbinden

Mit den folgenden Befehlen können Sie Codeschnipsel aus externen Dateien einbinden. Sie können QDoc veranlassen, den gesamten Inhalt einer Datei einzubinden, oder Sie können bestimmte Teile der Datei zitieren und andere auslassen. Die typische Anwendung des letzteren ist, eine Datei Stück für Stück zu zitieren.

\quotefile

Der Befehl \quotefile expandiert den gesamten Inhalt der als Argument angegebenen Datei.

Der Befehl betrachtet den Rest der Zeile als Teil seines Arguments. Stellen Sie sicher, dass dem Dateinamen ein Zeilenumbruch folgt.

Der Inhalt der Datei wird in einem separaten Absatz dargestellt, wobei eine Monospace-Schriftart und die Standardeinrückung verwendet werden. Der Code wird wortwörtlich wiedergegeben.

/*!
   This is a simple "Hello world" example:

   \quotefile examples/main.cpp

   It contains only the bare minimum you need
   to get a Qt application up and running.
*/

Siehe auch \quotefromfile und \code.

\quotefromfile

Der Befehl \quotefromfile öffnet die als Argument angegebene Datei für Zitate.

Der Befehl betrachtet den Rest der Zeile als Teil seines Arguments. Stellen Sie sicher, dass dem Dateinamen ein Zeilenumbruch folgt.

Der Befehl ist für die Verwendung beim Zitieren von Teilen aus einer Datei mit den walkthrough-Befehlen gedacht: \printline, \printto, \printuntil, \skipline, \skipto, \skipuntil. Damit können Sie bestimmte Teile einer Datei zitieren.

/*!
   The whole application is contained within
   the \c main() function:

   \quotefromfile examples/main.cpp

   \skipto main
   \printuntil app(argc, argv)

   First we create a QApplication object using
   the \c argc and \c argv parameters.

   \skipto QPushButton
   \printuntil resize

   Then we create a QPushButton, and give it a reasonable
   size using the QWidget::resize() function.

   ...
*/

QDoc merkt sich, aus welcher Datei es zitiert und an welcher Stelle in dieser Datei es sich gerade befindet (siehe \printline für weitere Informationen). Die Datei muss nicht "geschlossen" werden.

Siehe auch \quotefile, \code und \dots.

\printline

Der Befehl \printline expandiert auf die Zeile von der aktuellen Position bis zur nächsten nicht leeren Zeile der aktuellen Quelldatei.

Um sicherzustellen, dass die Dokumentation mit der Quelldatei synchronisiert bleibt, muss ein Teilstring der Zeile als Argument für den Befehl angegeben werden. Beachten Sie, dass der Befehl den Rest der Zeile als Teil seines Arguments betrachtet, stellen Sie also sicher, dass nach der Teilzeichenkette ein Zeilenumbruch folgt.

Die Zeile aus der Quelldatei wird als separater Absatz dargestellt, wobei eine Monospace-Schriftart und die Standardeinrückung verwendet werden. Der Code wird wortwörtlich wiedergegeben.

/*!
   There has to be exactly one QApplication object
   in every GUI application that uses Qt.

   \quotefromfile examples/main.cpp

   \printline QApplication

   This line includes the QApplication class
   definition. QApplication manages various
   application-wide resources, such as the
   default font and cursor.

   \printline QPushButton

   This line includes the QPushButton class
   definition. The QPushButton widget provides a command
   button.

   \printline main

   The main function...
*/

QDoc liest die Datei sequentiell ein. Um die aktuelle Position vorwärts zu bewegen, können Sie einen der beiden \skip ... Befehle verwenden. Um die aktuelle Position nach hinten zu verschieben, können Sie erneut den Befehl \quotefromfile verwenden.

Wenn das Teilstring-Argument von Schrägstrichen umgeben ist, wird es als regular expression interpretiert.

/*!
   \quotefromfile examples/mainwindow.cpp

   \skipto closeEvent
   \printuntil /^\}/

   Close events are sent to widgets that the users want to
   close, usually by clicking \c File|Exit or by clicking
   the \c X title bar button. By reimplementing the event
   handler, we can intercept attempts to close the
   application.
*/

(Die vollständige Beispieldatei...)

Der reguläre Ausdruck /^\}/ veranlasst QDoc, bis zum ersten '}'-Zeichen am Anfang der Zeile ohne Einrückung zu drucken. /.../ umschließt den regulären Ausdruck, und '^' steht für den Anfang der Zeile. Das '}'-Zeichen muss escaped werden, da es ein Sonderzeichen in regulären Ausdrücken ist.

QDoc gibt eine Warnung aus, wenn die angegebene Teilzeichenkette oder der reguläre Ausdruck nicht gefunden werden kann, d.h. wenn der Quellcode geändert wurde.

Siehe auch \printto und \printuntil.

\printto

Der Befehl \printto dehnt sich auf alle Zeilen ab der aktuellen Position bis zur nächsten Zeile aus, die eine bestimmte Teilzeichenkette enthält.

Der Befehl betrachtet den Rest der Zeile als Teil seines Arguments, wobei darauf zu achten ist, dass nach der Teilzeichenkette ein Zeilenumbruch erfolgt. Der Befehl folgt auch den gleichen Konventionen für Positionierung und Argumente wie der Befehl \printline.

Die Zeilen aus der Quelldatei werden in einem separaten Absatz wiedergegeben, wobei eine Monospace-Schriftart und die Standardeinrückung verwendet werden. Der Code wird wortwörtlich wiedergegeben.

/*!
   The whole application is contained within the
   \c main() function:

   \quotefromfile examples/main.cpp
   \printto hello

   First we create a QApplication object using the \c argc and
   \c argv parameters...
*/

Siehe auch \printline und \printuntil.

\printuntil

Der Befehl \printuntil dehnt sich auf alle Zeilen ab der aktuellen Position bis einschließlich der nächsten Zeile aus, die eine bestimmte Teilzeichenkette enthält.

Der Befehl betrachtet den Rest der Zeile als Teil seines Arguments. Stellen Sie sicher, dass der Teilzeichenkette ein Zeilenumbruch folgt. Der Befehl folgt auch den gleichen Konventionen für Positionierung und Argumente wie der Befehl \printline.

Wenn \printuntil ohne Argument verwendet wird, werden alle Zeilen ab der aktuellen Position bis zum Ende der zitierten Datei ausgegeben.

Die Zeilen der Quelldatei werden in einem separaten Absatz dargestellt, wobei eine Monospace-Schriftart und die Standardeinrückung verwendet werden. Der Code wird wortwörtlich wiedergegeben.

/*!
   The whole application is contained within the
   \c main() function:

   \quotefromfile examples/main.cpp
   \skipto main
   \printuntil hello

   First we create a QApplication object using the
   \c argc and \c argv parameters, then we create
   a QPushButton.
*/

Siehe auch \printline und \printto.

\skipline

Der Befehl \skipline ignoriert die nächste nicht-leere Zeile in der aktuellen Quelldatei.

Doc liest die Datei sequentiell, und der Befehl \skipline wird verwendet, um die aktuelle Position zu verschieben (Auslassen einer Zeile der Quelldatei). Siehe die Bemerkung zur Dateipositionierung oben.

Der Befehl betrachtet den Rest der Zeile als Teil seines Arguments; stellen Sie sicher, dass Sie der Teilzeichenkette einen Zeilenumbruch folgen lassen. Der Befehl folgt auch den gleichen Konventionen für Argumente wie der Befehl \printline und wird in Verbindung mit dem Befehl \quotefromfile verwendet.

/*!
   QPushButton is a GUI push button that the user
   can press and release.

   \quotefromfile examples/main.cpp
   \skipline QApplication
   \printline QPushButton

   This line includes the QPushButton class
   definition. For each class that is part of the
   public Qt API, there exists a header file of
   the same name that contains its definition.
*/

Siehe auch \skipto, \skipuntil und \dots.

\skipto

Der Befehl \skipto ignoriert alle Zeilen ab der aktuellen Position bis einschließlich der nächsten Zeile, die eine bestimmte Teilzeichenkette enthält.

QDoc liest die Datei sequentiell, und der \skipto-Befehl wird verwendet, um die aktuelle Position zu verschieben (Auslassen einer oder mehrerer Zeilen der Quelldatei). Siehe die Bemerkung zur Dateipositionierung oben.

Der Befehl betrachtet den Rest der Zeile als Teil seines Arguments, stellen Sie also sicher, dass Sie der Teilzeichenkette einen Zeilenumbruch folgen lassen.

Der Befehl folgt auch den gleichen Konventionen für Argumente wie der Befehl \printline und wird in Verbindung mit dem Befehl \quotefromfile verwendet.

/*!
   The whole application is contained within
   the \c main() function:

   \quotefromfile examples/main.cpp
   \skipto main
   \printuntil }

   First we create a QApplication object. There
   has to be exactly one such object in
   every GUI application that uses Qt. Then
   we create a QPushButton, resize it to a reasonable
   size ...
*/

Siehe auch \skipline, \skipuntil und \dots.

\skipuntil

Der Befehl \skipuntil ignoriert alle Zeilen ab der aktuellen Position bis einschließlich der nächsten Zeile, die eine bestimmte Teilzeichenkette enthält.

QDoc liest die Datei sequentiell, und der \skipuntil-Befehl wird verwendet, um die aktuelle Position zu verschieben (Auslassen einer oder mehrerer Zeilen der Quelldatei). Siehe die Bemerkung zur Dateipositionierung oben.

Der Befehl betrachtet den Rest der Zeile als Teil seines Arguments, stellen Sie also sicher, dass Sie der Teilzeichenkette einen Zeilenumbruch folgen lassen.

Der Befehl folgt auch den gleichen Konventionen für Argumente wie der Befehl \printline und wird in Verbindung mit dem Befehl \quotefromfile verwendet.

/*!
   The first thing we did in the \c main() function
   was to create a QApplication object \c app.

   \quotefromfile examples/main.cpp
   \skipuntil show
   \dots
   \printuntil }

   In the end we must remember to make \c main() pass the
   control to Qt. QCoreApplication::exec() will return when
   the application exits...
*/

Siehe auch \skipline, \skipto und \dots.

\dots

Der Befehl \dots zeigt an, dass Teile der Quelldatei beim Zitieren einer Datei ausgelassen wurden.

Der Befehl wird in Verbindung mit dem Befehl \quotefromfile verwendet und sollte in einer eigenen Zeile angegeben werden. Die Punkte werden in einer neuen Zeile unter Verwendung einer Monospace-Schriftart dargestellt.

/*!
   \quotefromfile examples/main.cpp
   \skipto main
   \printuntil {
   \dots
   \skipuntil exec
   \printline }
*/

Die Standardeinrückung beträgt 4 Leerzeichen, kann aber mit dem optionalen Argument des Befehls angepasst werden.

/*!
    \dots 0
    \dots
    \dots 8
    \dots 12
    \dots 16
*/

Siehe auch \skipline, \skipto und \skipuntil.

\snippet

Der Befehl \snippet bewirkt, dass ein Codeschnipsel wortwörtlich als vorformatierter Text eingefügt wird, der syntaktisch hervorgehoben sein kann.

Jeder Codeausschnitt wird durch die Datei, in der er enthalten ist, und durch einen eindeutigen Bezeichner für diese Datei referenziert. Snippet-Dateien werden normalerweise in einem Verzeichnis snippets innerhalb des Dokumentationsverzeichnisses gespeichert (z. B. $QTDIR/doc/src/snippets).

Die folgende Dokumentation verweist beispielsweise auf ein Snippet in einer Datei, die sich in einem Unterverzeichnis des Dokumentationsverzeichnisses befindet:

\snippet snippets/textdocument-resources/main.cpp Adding a resource

Der Text nach dem Dateinamen ist der eindeutige Bezeichner für das Snippet. Dieser wird verwendet, um den zitierten Code in der entsprechenden Snippet-Datei abzugrenzen, wie im folgenden Beispiel gezeigt, das dem obigen Befehl \snippet entspricht:

    ...
    QImage image(64, 64, QImage::Format_RGB32);
    image.fill(qRgb(255, 160, 128));

//! [Adding a resource]
    document->addResource(QTextDocument::ImageResource,
        QUrl("mydata://image.png"), QVariant(image));
//! [Adding a resource]
    ...

Standardmäßig sucht QDoc nach //! als Code-Snippet-Marker. Für die Dateien .pro, .py, .cmake und CMakeLists.txt wird #! erkannt. Schließlich wird <!-- in den Dateien .html, .qrc, .ui, .xml und .xq akzeptiert.

\codeline

Der Befehl \codeline fügt eine Leerzeile mit vorformatiertem Text ein. Er wird verwendet, um Lücken zwischen Snippets einzufügen, ohne den aktuellen vorformatierten Textbereich zu schließen und einen neuen zu öffnen.