Включение внешнего кода

Следующие команды позволяют включать фрагменты кода из внешних файлов. Вы можете заставить QDoc включить всё содержимое файла или выделить конкретные части и пропустить остальные. Типичное применение последнего — цитирование файла по частям.

\quotefile

Команда \quotefile расширяется до полного содержимого файла, указанного в качестве аргумента.

Команда рассматривает остаток строки как часть своего аргумента, убедитесь, что имя файла следует заносить с новой строки.

Содержимое файла отображается в отдельном абзаце с моноширинным шрифтом и стандартными отступами. Код отображается дословно.

/ *!
    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 отображает это как:

Это простой пример «Hello world»:

/****************************************************************************
**
** 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 <QApplication>
#include <QPushButton>

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

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

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

Он содержит только минимум необходимый для запуска приложения Qt.

См. также \quotefromfile и \code.

\quotefromfile

Команда \quotefromfile открывает файл, указанный в качестве аргумента, для цитирования.

Команда рассматривает остаток строки как часть своего аргумента, убедитесь, что имя файла следует заносить с новой строки.

Эта команда предназначена для использования при цитировании частей файла с командами пошагового руководства: \printline, \printto, \printuntil, \skipline, \skipto, \skipuntil. Это позволяет цитировать определённые части файла.

/ *!
    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 отображает это как:

Всё приложение содержится в функции main():

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

Сначала мы создаём объект QApplication с параметрами argc и argv.

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

Затем мы создаём QPushButton и задаём ему разумный размер с помощью функции QWidget::resize().

...

QDoc запоминает, из какого файла происходит цитирование и текущую позицию в этом файле (см. \printline для получения дополнительной информации). Нет необходимости «закрывать» файл.

См. также \quotefile, \code и \dots.

\printline

Команда \printline расширяется до строки от текущей позиции до следующей непустой строки в текущем исходном файле.

Чтобы убедиться, что документация остаётся синхронизированной с исходным файлом, подстрока должна быть указана в качестве аргумента команды. Обратите внимание, что команда рассматривает остаток строки как часть своего аргумента, убедитесь, что подстрока следует заносить с новой строки.

Строка из исходного файла отображается в отдельном абзаце с моноширинным шрифтом и стандартными отступами. Код отображается дословно.

/ *!
    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 отображает это как:

В каждом приложении с графическим интерфейсом пользователя, использующем Qt, должен быть ровно один объект QApplication.

#include <QApplication>

Эта строка включает определение класса QApplication. QApplication управляет различными ресурсами, относящимися ко всему приложению, такими как шрифт и курсор по умолчанию.

#include <QPushButton>

Эта строка включает определение класса QPushButton. Виджет QPushButton предоставляет кнопку команды.

int main(int argc, char *argv[])

Функция main...

QDoc считывает файл последовательно. Чтобы переместить текущую позицию вперёд, можно использовать команды \skip.... Чтобы переместить текущую позицию назад, можно снова использовать команду \quotefromfile.

Если аргумент подстроки заключён в слэши, он интерпретируется как регулярное выражение.

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

QDoc отображает это как:

void MainWindow::closeEvent(QCloseEvent *event)
//! [1] //! [2]
{
    if (maybeSave()) {
        event->accept();
    } else {
        event->ignore();
    }
}

События закрытия отправляются виджетам, которые пользователи хотят закрыть, обычно нажав File|Exit или нажав кнопку на X панели заголовка. Переопределяя обработчик событий, мы можем перехватить попытки закрыть приложение.

(Полный пример файла...)

Регулярное выражение /^\}/ заставляет QDoc печатать до первой скобки '}' в начале строки без отступов. /.../ заключает регулярное выражение, а '^' означает начало строки. Символ '}' должен быть экранирован, так как он является специальным символом в регулярных выражениях.

QDoc выдаст предупреждение, если указанную подстроку или регулярное выражение не удаётся найти, то есть если исходный код был изменён.

См. также \printto и \printuntil.

\printto

Команда \printto расширяется до всех строк от текущей позиции до и исключая следующую строку, содержащую указанную подстроку.

Команда рассматривает остаток строки как часть своего аргумента, убедитесь, что подстрока следует заносить с новой строки. Команда также следует тем же правилам для позиционирования и аргумента, что и команда \printline.

Строки из исходного файла отображаются в отдельном абзаце с моноширинным шрифтом и стандартными отступами. Код отображается дословно.

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

QDoc отображает это как:

Всё приложение содержится в функции main():

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

Сначала мы создаём объект QApplication с параметрами argc и argv...

См. также \printline и \printuntil.

\printuntil

Команда \printuntil расширяется до всех строк от текущей позиции до и включая следующую строку, содержащую указанную подстроку.

Команда рассматривает остаток строки как часть своего аргумента, убедитесь, что подстрока следует заносить с новой строки. Команда также следует тем же правилам для позиционирования и аргумента, что и команда \printline.

Если \printuntil используется без аргумента, она расширяется до всех строк от текущей позиции до конца цитируемого файла.

Строки из исходного файла отображаются в отдельном абзаце с моноширинным шрифтом и стандартными отступами. Код отображается дословно.

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

QDoc отображает это как:

Всё приложение содержится в функции main():

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

    QPushButton hello("Hello world!");

Сначала мы создаём объект QApplication с параметрами argc и argv, затем создаём QPushButton.

См. также \printline и \printto.

\skipline

Команда \skipline пропускает следующую непустую строку в текущем исходном файле.

QDoc читает файл последовательно, а команда \skipline используется для перемещения текущей позиции (пропуская строку исходного файла). См. примечание о позиционировании файла выше.

Команда рассматривает остаток строки как часть своего аргумента, убедитесь, что подстрока следует заносить с новой строки. Команда также следует тем же правилам для аргумента, что и команда \printline, и используется совместно с командой \quotefromfile.

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

QDoc отображает это как:

QPushButton — кнопка GUI, которую пользователь может нажать и отпустить.

#include <QPushButton>

Эта строка включает определение класса QPushButton. Для каждого класса, являющегося частью публичного API Qt, существует файл заголовков с таким же именем, который содержит его определение.

См. также \skipto, \skipuntil и \dots.

\skipto

Команда \skipto пропускает все строки от текущей позиции до и исключая следующую строку, содержащую указанную подстроку.

QDoc читает файл последовательно, а команда \skipto используется для перемещения текущей позиции (пропуская одну или несколько строк исходного файла). См. примечание о позиционировании файла выше.

Команда рассматривает остаток строки как часть своего аргумента, убедитесь, что подстрока следует заносить с новой строки.

Команда также следует тем же правилам для аргумента, что и команда \printline, и используется совместно с командой \quotefromfile.

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

QDoc отображает это как:

Весь прикладной код содержится в функции main():

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

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

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

Сначала мы создаём объект QApplication. В каждом графическом приложении Qt должен быть ровно один такой объект. Затем мы создаём QPushButton, изменяем его размер на приемлемый ...

См. также \skipline, \skipuntil и \dots.

\skipuntil

Команда \skipuntil пропускает все строки от текущей позиции до включительно следующей строки, содержащей заданную подстроку.

QDoc считывает файл последовательно, и команда \skipuntil используется для перемещения текущей позиции (пропуская одну или несколько строк исходного файла). См. примечание о позиционировании файла выше.

Команда учитывает остальную часть строки как часть своего аргумента, убедитесь, что подстрока завершается переводом строки.

Команда также следует тем же правилам для аргумента, что и команда \printline, и она используется совместно с командой \quotefromfile.

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

QDoc отображает это как:

Первым делом в функции main() мы создали объект QApplication app.

    ...
    return app.exec();
}

В конце мы должны убедиться, что main() передаёт управление Qt. QCoreApplication::exec() вернёт значение при выходе приложения...

См. также \skipline, \skipto и \dots.

\dots

Команда \dots указывает, что части исходного файла были пропущены при цитировании файла.

Команда используется совместно с командой \quotefromfile и должна быть указана на отдельной строке. Точки отображаются на новой строке с использованием шрифта с фиксированной шириной.

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

QDoc отображает это как:

int main(int argc, char *argv[])
{
    ...
}

По умолчанию отступ составляет 4 пробела, но его можно изменить, используя необязательный аргумент команды.

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

QDoc отображает это как:

...
    ...
        ...
            ...
                ...

См. также \skipline, \skipto и \skipuntil.

\snippet

Команда \snippet вставляет фрагмент кода буквально в виде форматированного текста, который может быть выделен по синтаксису.

Каждый фрагмент кода ссылается на файл, в котором он находится, и на уникальный идентификатор этого файла. Файлы фрагментов обычно хранятся в каталоге snippets внутри каталога документации (например, $QTDIR/doc/src/snippets).

Например, следующая документация ссылается на фрагмент в файле, находящемся в подкаталоге каталога документации:

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

Текст после имени файла является уникальным идентификатором фрагмента. Он используется для определения цитируемого кода в соответствующем файле фрагмента, как показано в следующем примере, который соответствует вышеуказанной \snippet команде:

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

По умолчанию QDoc ищет //! как маркер фрагмента кода. Для файлов .pro, .py, .cmake и CMakeLists.txt обнаруживается #!. Наконец, <!-- принимается в файлах .html, .qrc, .ui, .xml и .xq.

\codeline

Команда \codeline вставляет пустую строку форматированного текста. Она используется для вставки пробелов между фрагментами кода без закрытия текущей области форматированного текста и открытия новой.