Including Images

The graphic commands makes it possible to include images in the documentation. The images can be rendered as separate paragraphs, or within running text.

\image

The \image command expands to the image specified by its first argument, and renders it centered as a separate paragraph.

The command takes two arguments. The first argument is the name of the image file. The second argument is optional and is a simple description of the image, equivalent to the HTML alt="" in an image tag. The description is used for tooltips and for browsers that don't support images, like the Lynx text browser.

The remaining text after the file name is the optional, description argument. Be sure to follow the file name or the description with a line break. Curly brackets are required if the description argument spans multiple lines.

/ *!
    Qt is a C++ toolkit for cross-platform GUI application development.

    \image happyguy.jpg "Happy guy"

    Qt provides single-source portability across Microsoft
    Windows, macOS, Linux, and all major commercial Unix
    variants. It is also available for embedded devices.
* /

QDoc renders this as:

Qt is a C++ toolkit for cross-platform GUI application development.

image "Happy guy"

Qt provides single-source portability across Microsoft Windows, macOS, Linux, and all major commercial Unix variants. It is also available for embedded devices.

See also \inlineimage and \caption.

\inlineimage

The \inlineimage command expands to the image specified by its argument. The image is rendered inline with the rest of the text.

The command takes two arguments. The first argument is the name of the image file. The second argument is optional and is a simple description of the image, equivalent to the HTML alt="" in an image tag. The description is used for tooltips, and for when a browser doesn't support images, like the Lynx text browser.

The most common use of the \inlineimage command is in lists and tables. Here is an example of including inline images in a list:

/ *!
    \list 1
      \li \inlineimage happy.gif Oh so happy!
      \li \inlineimage happy.gif Oh so happy!
      \li \inlineimage happy.gif Oh so happy!
    \endlist
* /

QDoc renders this as:

  1. Oh so happy!
  2. Oh so happy!
  3. Oh so happy!

Here is an example of including inline images in a table:

/ *!
    \table
    \header
        \li Qt
        \li Qt Creator
    \row
        \li \inlineimage happy.gif Oh so happy!
        \li \inlineimage happy.gif Oh so happy!
    \row
        \li \inlineimage happy.gif Oh so happy!
        \li \inlineimage happy.gif Oh so happy!
    \endtable
* /

QDoc renders this as:

Qt Qt Creator
Oh so happy! Oh so happy!
Oh so happy! Oh so happy!

The command can also be used to insert an image inline with the text.

/ *!
    \inlineimage training.jpg Qt Training
    The Qt Programming course is offered as a
    five day Open Enrollment Course. The classes
    are open to the public. Although the course is open
    to anyone who wants to learn, attendees should
    have significant experience in C++ development
    to derive maximum benefit from the course.
* /

QDoc renders this as:

Qt Training The Qt Programming course is offered as a five day Open Enrollment Course. The classes are open to the public. Although the course is open to anyone who wants to learn, attendees should have significant experience in C++ development to derive maximum benefit from the course.

See also \image and \caption.

\caption

The \caption command provides a caption for an image.

The command takes all the text up to the end of the paragraph to be the caption. Experiment until you get the effect you want.

/ *!
  \table 100%
    \row
      \li \image windowsvista-pushbutton.png
         \caption The QPushButton widget provides a command button.
      \li \image windowsvista-toolbutton.png
         \caption The QToolButton class provides a quick-access button to commands
         or options, usually used inside a QToolBar.
   \endtable
* /

QDoc renders this as:

The QPushButton widget provides a command button.

The QToolButton class provides a quick-access button to commands or options, usually used inside a QToolBar.

See also \image and \inlineimage

© The Qt Company Ltd
Licensed under the GNU Free Documentation License, Version 1.3.
https://doc.qt.io/qt-6.0/09-qdoc-commands-includingimages.html