Tables and Lists

These commands enable creating lists and tables. A list is rendered left aligned as a separate paragraph. A table is rendered centered as a separate paragraph. The table width depends on the width of its contents.

\table

The \table and \endtable commands delimit the contents of a table.

The command accepts a single argument specifying the table's width as a percentage of the page width:

/*!
   \table 100 %

      ...

   \endtable
*/

The code above ensures that the table will fill all available space. If the table's width is smaller than 100 %, the table will be centered in the generated documentation.

A table can contain headers, rows and columns. A row starts with a \row command and consists of cells, each of which starts with an \li command. There is also a \header command which is a special kind of row that has a special format.

/*!
   \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
*/

You can also make cells span several rows and columns. For example:

/*!
   \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
*/

\row

The \row command begins a new row in a table. The \li items that belong in the new row will immediately follow the \row.

The command can only be used within the \table...\endtable commands. A row can contain several cells. A cell is created with the \li command.

The background cell color of each row alternates between two shades of grey, making it easier to distinguish the rows from each other. The cells' contents is left aligned.

/*!
   \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
*/

\value

The \value command starts the documentation of a C++ enum item.

The command's first argument is the value name. The value name may be preceded by an optional since clause enclosed in square brackets. The value description follows the value name. The description ends at the next blank line or \value. The arguments are rendered in a table.

Note: To include images in the \value description, use the \inlineimage command.

Without a since clause, a \value command could look like this:

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

The same command with a since clause would look like this:

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

The documentation will be located in the associated class, header file or namespace documentation. See the \enum documentation for an example.

Note: Since Qt 5.4, \value command can also be used outside the \enum topic. In this case, QDoc renders a two-column table listing the constant name (taken as-is from the first argument) and its description. This can be used, for example, in \qmlproperty topic for documenting acceptable values for a QML enumeration property.

\omitvalue

The \omitvalue command excludes a C++ enum item from the documentation.

The command's only mandatory argument is the name of the enum item that will be omitted. If the enum item is followed by a single-line description, that is also omitted.

See the \enum documentation for an example.

\list

The \list and \endlist commands delimit a list of items.

Create each list item with the \li command. A list always contains one or more items. Lists can be nested. For example:

/*!
    \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
*/

The \list command takes an optional argument providing alternative appearances for the list items.

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

If you provide 'A' as an argument to the \list command, the bullets are replaced with characters in alphabetical order:

How to Learn Qt
Installation
Tutorial and Examples

If you replace 'A' with '1', the list items are numbered in ascending order:

How to Learn Qt
Installation
Tutorial and Examples

If you provide 'i' as the argument, the bullets are replaced with roman numerals:

How to Learn Qt
Installation
Tutorial and Examples

Finally, you can make the list items appear with roman numbers following in ascending order if you provide 'I' as the optional argument:

How to Learn Qt
Installation
Tutorial and Examples

You can also make the listing start at any character or number by simply provide the number or character you want to start at. For example:

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

\li (table cell, list item)

The \li command marks a table cell or a list item. This command is only used in tables and lists.

It considers everything as its argument until the next \li command, until the next \endtable, or \endlist command. See \table and \list for examples.

If the command is used within a table, you can also specify how many rows or columns the item should span.

/*!
   \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
*/

If not specified, the item will span one column and one row.