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

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

\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++.

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

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

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

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

\omitvalue

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

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

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

\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 Reference: Начало работы
  • Как изучать 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.