Таблицы и списки

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

\table

Команды \table и \endtable определяют содержимое таблицы.

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

/ *!
    \table 100 %

       ...

    \endtable
* /

Приведённый выше код гарантирует, что таблица заполнит всё доступное пространство. Если ширина таблицы меньше 100 %, таблица будет центрирована в сгенерированной документации.

Таблица может содержать заголовки, строки и столбцы. Строка начинается с команды \row и состоит из ячеек, каждая из которых начинается с команды \li. Также есть команда \header, которая является специальным видом строки со специальным форматом.

/ *!
    \table
    \header
        \li Qt Core Feature
        \li Brief Description
    \row
        \li \l {Signal and Slots}
        \li Signals and slots are used for communication
           between objects.
    \row
        \li \l {Layout Management}
        \li The Qt layout system provides a simple
           and powerful way of specifying the layout
           of child widgets.
    \row
        \li \l {Drag and Drop}
        \li Drag and drop provides a simple visual
           mechanism which users can use to transfer
           information between and within applications.
    \endtable
* /

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

Вы также можете сделать так, чтобы ячейки занимали несколько строк и столбцов. Например:

/ *!
    \table
    \header
        \li {3,1} This header cell spans three columns,
           but only one row.
    \row
        \li {2, 1} This table cell spans two columns,
           but only one row
        \li {1, 2} This table cell spans only one column,
        but two rows.
    \row
        \li A regular table cell
        \li A regular table cell
    \endtable
* /

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

См. также \header, \row и \li.

\header

Команда \header указывает, что следующие ячейки таблицы являются заголовками столбцов текущей таблицы.

Эта команда может использоваться только в пределах команд \table...\endtable. Заголовок может содержать несколько ячеек. Ячейка создаётся с помощью команды \li.

Текст ячейки заголовка центрируется внутри ячейки таблицы и отображается жирным шрифтом.

/ *!
    \table
    \header
        \li Qt Core Feature
        \li Brief Description
    \row
        \li \l {Signal and Slots}
        \li Signals and slots are used for communication
           between objects.
    \endtable
* /

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

См. также \table, \row и \li.

\row

Команда \row начинает новую строку в таблице. Элементы \li, которые относятся к новой строке, будут следовать сразу после \row.

Команда может использоваться только в пределах команд \table...\endtable. Строка может содержать несколько ячеек. Ячейка создаётся с помощью команды \li.

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

/ *!
    \table
    \header
        \li Qt Core Feature
        \li Brief Description
    \row
        \li \l {Signal and Slots}
        \li Signals and slots are used for communication
           between objects.
    \row
        \li \l {Layout Management}
        \li The Qt layout system provides a simple
           and powerful way of specifying the layout
           of child widgets.
    \row
        \li \l {Drag and Drop}
        \li Drag and drop provides a simple visual
           mechanism which users can use to transfer
           information between and within applications.
    \endtable
* /

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

См. также \table, \header и \li.

\value

Команда \value начинает документацию элемента перечисления C++.

Первый аргумент команды — имя значения. Имя значения может быть предварено необязательной фразой since в квадратных скобках. Описание значения следует за именем значения. Описание заканчивается на следующей пустой строке или команде \value. Аргументы отображаются в таблице.

Без фразы since команда \value может выглядеть так:

\value QtInfoMsg A message generated by the qInfo() function.

Та же команда с фразой since выглядит так:

\value [since 5.5] QtInfoMsg A message generated by the qInfo() function.

Документация будет расположена в соответствующем классу, заголовочному файлу или пространству имён документации. См. документацию \enum для примера.

Примечание: С Qt 5.4 команда \value также может использоваться вне темы \enum. В этом случае QDoc отображает двухколоночную таблицу, перечисляющую имя константы (взятое как есть из первого аргумента) и её описание. Это можно использовать, например, в теме \qmlproperty для документирования допустимых значений свойства перечисления QML.

См. также \enum и \omitvalue.

\omitvalue

Команда \omitvalue исключает элемент перечисления C++ из документации.

Единственный аргумент команды — имя элемента перечисления, который будет исключён. См. документацию \enum для примера.

См. также \enum и \value \since

\list

Команды \list и \endlist определяют список элементов.

Создайте каждый элемент списка с помощью команды \li. Список всегда содержит один или более элементов. Списка могут быть вложенными. Например:

/ *!
    \list
    \li Qt Reference Documentation: Getting Started
        \list
        \li How to Learn Qt
        \li Installation
            \list
            \li Qt/X11
            \li Qt/Windows
            \li Qt/Mac
            \li Qt/Embedded
            \endlist
        \li Tutorial and Examples
        \endlist
    \endlist
* /

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

• Qt Справочная документация: Начало работы
  • Как изучать Qt
  • Установка
    • Qt/X11
    • Qt/Windows
    • Qt/Mac
    • Qt/Embedded
  • Руководство и примеры

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

/ *!
    \list
        \li How to Learn Qt
        \li Installation
        \li Tutorial and Examples
    \endlist
* /

QDoc отображает элементы списка с маркерами (по умолчанию):

• Как изучать Qt
• Установка
• Руководство и примеры

Предупреждение: Похоже, здесь есть ошибка в qdoc. Если вы включаете какие-либо типы аргументов, вы получаете числовой список. Мы разбираемся с этим.

Если вы передадите 'A' в качестве аргумента команды \list, маркеры заменятся символами в алфавитном порядке:

1. Как изучать Qt
2. Установка
3. Руководство и примеры

Если вы замените 'A' на '1', элементы списка будут пронумерованы в порядке возрастания:

1. Как изучать Qt
2. Установка
3. Руководство и примеры

Если вы передадите 'i' в качестве аргумента, маркеры заменятся римскими цифрами:

1. Как изучать Qt
2. Установка
3. Руководство и примеры

Наконец, вы можете отобразить элементы списка с римскими цифрами в порядке возрастания, если передадите 'I' в качестве необязательного аргумента:

1. Как изучать Qt
2. Установка
3. Руководство и примеры

Вы также можете сделать так, чтобы нумерация начиналась с любого символа или числа, просто передав желаемое число или символ. Например:

/ *!
    \list G
        \li How to Learn Qt
        \li Installation
        \li Tutorial and Examples
    \endlist
* /

Примечание: Это не работает в DITA XML, поэтому не используйте это, потому что это создаёт файл DITA XML, который не проходит валидацию. Возможно, есть способ сделать это в DITA, поэтому, если мы его найдём, мы его добавим. Но эта возможность не используется нигде, кроме как прямо здесь, поэтому, вероятно, она не важна. Пока что, если вы используете этот параметр, qdoc проигнорирует его и создаст список без него.

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

7. Как изучать Qt
8. Установка
9. Руководство и примеры

См. также \li.

\li (ячейка таблицы, элемент списка)

Команда \li отмечает ячейку таблицы или элемент списка. Эта команда используется только в таблицах и списках.

Она рассматривает всё как свой аргумент до следующей команды \li, до следующей команды \endtable или \endlist. См. \table и \list для примеров.

Если команда используется в таблице, вы также можете указать, сколько строк или столбцов должно занимать элемент.

/ *!
    \table
    \header
        \li {3,1} This header cell spans three columns
           but only one row.
    \row
        \li {2, 1} This table item spans two columns
           but only one row
        \li {1, 2} This table item spans only one column,
        but two rows.
    \row
        \li A regular table item
        \li A regular table item
    \endtable
* /

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

Если не указано, элемент займёт один столбец и одну строку.

См. также \table, \header и \list.