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

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

Примечание: Хотя все эти команды могут использоваться для отображения кода C++, команды \snippet и \codeline предпочтительнее других. Эти команды позволяют подставить эквивалентные фрагменты кода для других языковых библиотек Qt, заменяя фрагменты C++ в документации.

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

В каждом приложении GUI, использующем 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, .dita и .xq.

\codeline

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