Including Images | Qt 6.11

- Qt 6.11
- QDoc Manual
- Markup Commands
- Including Images
- Qt 6.11.2 Reference Documentation

Creating Links ◦ Tables and Lists

# 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 a description of what the image contains, and is used for the HTML `alt` attribute. Its contents is read aloud by screen readers, and its use is therefore strongly recommended for accessibility purposes. It may also be used by browsers that don't support images, like the Lynx text browser. You can also set the usealttextastitle variable to make QDoc generate a title attribute for the image, which commonly is rendered by graphical text browsers as a tooltip when the user hovers the mouse over the image.

While QDoc is quite forgiving, you should wrap both the file name and the description in curly braces, like so:

     \image {Bandit.png} {A Golden Retriever holding a bag of coffee in its mouth}

This syntax is the most explicit and should always give the expected result. If not, 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. If the description is wrapped in double quotes, QDoc will remove them before generating output. Special characters may be replaced with the corresponding HTML entity code in QDoc's HTML output.

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

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 within braces {}, 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, I am a caption!}
           \li \inlineimage happy.gif Oh so happy, but I'm not a caption.
         \endlist
     */

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

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.
     */

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 windows-pushbutton.png
              \caption The QPushButton widget provides a command button.
           \li \image windows-toolbutton.png
              \caption The QToolButton class provides a quick-access button to commands
              or options, usually used inside a QToolBar.
        \endtable
     */

See also \image and \inlineimage

Creating Links ◦ Tables and Lists