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

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

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