Including External Code▲

<Unknown command>contentspageQDoc Manual

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.

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.

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

QDoc renders this as:

This is a simple "Hello world" example:

 
Sélectionnez
/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the tools applications of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:GPL-EXCEPT$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3 as published by the Free Software
** Foundation with exceptions as appearing in the file LICENSE.GPL3-EXCEPT
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/

#include &lt;QApplication&gt;
#include &lt;QPushButton&gt;

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    QPushButton hello("Hello world!");
    hello.resize(100, 30);

    hello.show();
    return app.exec();
}

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

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.

 
Sélectionnez
/ *!
    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 renders this as:

The whole application is contained within the main() function:

 
Sélectionnez
int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

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

 
Sélectionnez
    QPushButton hello("Hello world!");
    hello.resize(100, 30);

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.

See also \quotefile, \code and \dots.

 

\printline▲

The \printline command expands to the line from the current position to the next non-blank line of the current source file.

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.

 
Sélectionnez
/ *!
    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 renders this as:

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

 
Sélectionnez
#include &lt;QApplication&gt;

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

 
Sélectionnez
#include &lt;QPushButton&gt;

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

 
Sélectionnez
int main(int argc,