Including External Code | Qt 6.11

- Qt 6.11
- QDoc Manual
- Markup Commands
- Including External Code
- Qt 6.11.1 Reference Documentation

Including Code Inline ◦ Creating Links

# Including External Code

The following commands enable you to include code snippets from external files. You can make QDoc include the complete contents of a file, or you can quote specific parts of the file and skip others. The typical use of the latter is to quote a file chunk by chunk.

Note: Although all these commands can be used for rendering C++ code, the \snippet and \codeline commands are preferred over the others. These commands allow equivalent code snippets for other Qt language bindings to be substituted for the C++ snippets in the documentation.

## \quotefile

The \quotefile command expands to the complete contents of the file given as argument.

The command considers the rest of the line as part of its argument, make sure to follow the file name with a line break.

The file's contents is rendered in a separate paragraph, using a monospace font and the standard indentation. The code is shown verbatim.

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

From version 6.11, a language can be specified as an optional case-insensitive argument on the same line as the \quotefile command. This influences the quoted text in the same way as for the \code command.

For example:

     \quotefile [text] examples/main.cpp

This can be useful when quoting from a file containing source code that QDoc does not have the ability to mark up.

See also \quotefromfile and \code.

## \quotefromfile

The \quotefromfile command opens the file given as argument for quoting.

The command considers the rest of the line as part of its argument, make sure to follow the file name with a line break.

The command is intended for use when quoting parts from file with the walkthrough commands: \printline, \printto, \printuntil, \skipline, \skipto, \skipuntil. This enables you to quote specific portions of a file.

     /*!
        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 remembers which file it is quoting from, and the current position in that file (see \printline for more information). There is no need to "close" the file.

From version 6.11, a language can be specified as an optional case-insensitive argument on the same line as the \quotefromfile command. This influences the quoted text in the same way as for the \code command.

For example:

     \quotefromfile [text] examples/main.cpp
     \skipto main
     \printuntil app(argc, argv)

QDoc also remembers which code language it is quoting from, so commands like \printline, \printto and \printuntil quote from the current file, applying a consistent style of markup until a new file is read.

See also \quotefile, \code and \dots.

## \printline

The \printline command expands to the line from the current position.

To ensure that the documentation remains synchronized with the source file, a substring of the line must be specified as an argument to the command. Note that the command considers the rest of the line as part of its argument, make sure to follow the substring with a line break.

The line from the source file is rendered as a separate paragraph, using a monospace font and the standard indentation. The code is shown verbatim.

     /*!
        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 reads the file sequentially. To move the current position forward you can use either of the \skip... commands. To move the current position backward, you can use the \quotefromfile command again.

If the substring argument is surrounded by slashes it is interpreted as a regular expression.

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

(The complete example file...)

The regular expression `/^\`}/ makes QDoc print until the first '}' character occurring at the beginning of the line without indentation. /.../ encloses the regular expression, and '^' means the beginning of the line. The '}' character must be escaped since it is a special character in regular expressions.

QDoc will emit a warning if the specified substring or regular expression cannot be located, i.e. if the source code has changed.

See also \printto and \printuntil.

## \printto

The \printto command expands to all the lines from the current position up to and excluding the next line containing a given substring.

The command considers the rest of the line as part of its argument, make sure to follow the substring with a line break. The command also follows the same conventions for positioning and argument as the \printline command.

The lines from the source file are rendered in a separate paragraph, using a monospace font and the standard indentation. The code is shown verbatim.

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

See also \printline and \printuntil.

## \printuntil

The \printuntil command expands to all the lines from the current position up to and including the next line containing a given substring.

The command considers the rest of the line as part of its argument, make sure to follow the substring with a line break. The command also follows the same conventions for positioning and argument as the \printline command.

If \printuntil is used without an argument, it expands to all the lines from the current position to the end of the quoted file.

The lines from the source file are rendered in a separate paragraph, using a monospace font and the standard indentation. The code is shown verbatim.

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

See also \printline and \printto.

## \skipline

The \skipline command ignores the next non-blank line in the current source file.

Doc reads the file sequentially, and the \skipline command is used to move the current position (omitting a line of the source file). See the remark about file positioning above.

The command considers the rest of the line as part of its argument, make sure to follow the substring with a line break. The command also follows the same conventions for argument as the \printline command, and it is used in conjunction with the \quotefromfile command.

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

See also \skipto, \skipuntil and \dots.

## \skipto

The \skipto command ignores all the lines from the current position up to and excluding the next line containing a given substring.

QDoc reads the file sequentially, and the \skipto command is used to move the current position (omitting one or several lines of the source file). See the remark about file positioning above.

The command considers the rest of the line as part of its argument, make sure to follow the substring with a line break.

The command also follows the same conventions for argument as the \printline command, and it is used in conjunction with the \quotefromfile command.

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

See also \skipline, \skipuntil and \dots.

## \skipuntil

The \skipuntil command ignores all the lines from the current position up to and including the next line containing a given substring.

QDoc reads the file sequentially, and the \skipuntil command is used to move the current position (omitting one or several lines of the source file). See the remark about file positioning above.

The command considers the rest of the line as part of its argument, make sure to follow the substring with a line break.

The command also follows the same conventions for argument as the \printline command, and it is used in conjunction with the \quotefromfile command.

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

See also \skipline, \skipto and \dots.

## \dots

The \dots command indicates that parts of the source file have been omitted when quoting a file.

The command is used in conjunction with the \quotefromfile command, and should be stated on its own line. The dots are rendered on a new line, using a monospace font.

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

The default indentation is 4 spaces, but this can be adjusted using the command's optional argument.

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

See also \skipline, \skipto and \skipuntil.

## \snippet

The \snippet command causes a code snippet to be included verbatim as preformatted text, which may be syntax highlighted.

Each code snippet is referenced by the file that holds it and by a unique identifier for that file. Snippet files are typically stored in a `snippets` directory inside the documentation directory (for example, `$QTDIR/doc/src/snippets`).

For example, the following documentation references a snippet in a file residing in a subdirectory of the documentation directory:

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

The text following the file name is the unique identifier for the snippet. This is used to delimit the quoted code in the relevant snippet file, as shown in the following example that corresponds to the above `\snippet` command:

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

By default, QDoc looks for `//!` as a code snippet marker. For `.pro`, `.py`, `.cmake`, and `CMakeLists.txt` files, `#!` is detected. Finally, `<!--` is accepted in `.html`, `.qrc`, `.ui`, `.xml`, and `.xq` files.

QDoc normalizes snippet indentation by comparing the snippet-marker's space-based indentation against the snippet's minimum content indentation (ignoring Qt-macros, blank lines, and full-line comments). It then automatically un-indents the snippet body to whichever is smaller, ensuring the generated code always preserves its natural structure regardless of where the markers sit. Under-indented markers are left untouched.

Note: QDoc only handles space characters for indentation normalization, not tabs or other whitespace. For best results, use consistent space-based indentation in source files containing snippets.

From version 6.11, a language can be specified as an optional case-insensitive argument on the same line as the \snippet command. This influences the quoted text in the same way as for the \code command.

This example use of the command overrides the default C++ markup style and outputs plain text instead:

     \snippet [text] code.cpp

This can be useful when quoting a language that QDoc does not have the ability to mark up, or when needing to quote from a file with an unconventional file name.

## \codeline

The \codeline command inserts a blank line of preformatted text. It is used to insert gaps between snippets without closing the current preformatted text area and opening a new one.

Including Code Inline ◦ Creating Links