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

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

\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 Справочная документация: Начало работы
  • Как изучить 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.