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

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

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