Google Git
Sign in
third-party-mirror / orbit / 301094089f7066c20f6885ee60d316d3f550a3c2 / . / qt-everywhere-src-5.15.1 / qttools / src / qdoc / doc / qdoc-manual-markupcmds.qdoc
blob: f03be6899e832e49cdb2118f70fa73c80b18314a [file] [log] [blame]
/****************************************************************************
**
** Copyright (C) 2020 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page 03-qdoc-commands-markup.html
\previouspage Naming Things
\nextpage Text Markup
\title Markup Commands
The markup commands indicate the generated documentation's visual
appearance and logical structure.
\list
\li \l {a-command} {\\a}
\li \l {annotatedlist-command} {\\annotatedlist}
\li \l {b-command} {\\b}
\li \l {badcode-command} {\\badcode}
\li \l {b-command} {\\bold} (deprecated, use \\b)
\li \l {brief-command} {\\brief}
\li \l {c-command} {\\c}
\li \l {caption-command} {\\caption}
\li \l {code-command} {\\code}
\li \l {codeline-command} {\\codeline}
\li \l {div-command} {\\div}
\li \l {dots-command} {\\dots}
\li \l {e-command} {\\e}
\li \l {else-command} {\\else}
\li \l {endif-command} {\\endif}
\li \l {footnote-command} {\\footnote}
\li \l {generatelist-command} {\\generatelist}
\li \l {header-command} {\\header}
\li \l {e-command} {\\i} (deprecated, use \\e)
\li \l {if-command} {\\if}
\li \l {image-command} {\\image}
\li \l {include-command} {\\include}
\li \l {include-command} {\\input}
\li \l {inlineimage-command} {\\inlineimage}
\li \l {keyword-command} {\\keyword}
\li \l {l-command} {\\l}
\li \l {legalese-command} {\\legalese}
\li \l {li-command} {\\li}
\li \l {list-command} {\\list}
\li \l {meta-command} {\\meta}
\li \l {noautolist-command} {\\noautolist}
\li \l {newcode-command} {\\newcode}
\li \l {li-command} {\\o} (deprecated, use \\li)
\li \l {note-command} {\\note}
\li \l {oldcode-command} {\\oldcode}
\li \l {omit-command} {\\omit}
\li \l {printline-command} {\\printline}
\li \l {printto-command} {\\printto}
\li \l {printuntil-command} {\\printuntil}
\li \l {qml-command}{\\qml}
\li \l {quotation-command} {\\quotation}
\li \l {quotefile-command} {\\quotefile}
\li \l {quotefromfile-command} {\\quotefromfile}
\li \l {raw-command} {\\raw}
\li \l {row-command} {\\row}
\li \l {sa-command} {\\sa}
\li \l {sectionOne-command} {\\section1}
\li \l {sectionTwo-command} {\\section2}
\li \l {sectionThree-command} {\\section3}
\li \l {sectionFour-command} {\\section4}
\li \l {skipline-command} {\\skipline}
\li \l {skipto-command} {\\skipto}
\li \l {skipuntil-command} {\\skipuntil}
\li \l {snippet-command} {\\snippet}
\li \l {span-command} {\\span}
\li \l {sub-command} {\\sub}
\li \l {sup-command} {\\sup}
\li \l {table-command} {\\table}
\li \l {tableofcontents-command} {\\tableofcontents}
\li \l {target-command} {\\target}
\li \l {tt-command} {\\tt}
\li \l {uicontrol-command} {\\uicontrol}
\li \l {underline-command} {\\underline}
\li \l {raw-command} {\\unicode}
\li \l {warning-command} {\\warning}
\li \l {backslash-command} {\\\\}
\endlist
*/
/*!
\page 04-qdoc-commands-textmarkup.html
\previouspage Markup Commands
\nextpage Document Structure
\title Text Markup
The text formatting commands indicate how text is to be rendered.
\target a-command
\section1 \\a (parameter marker)
The \\a command tells QDoc the next word is a formal parameter name.
A warning is emitted when a formal parameter is not documented or
is misspelled, so when you document a function you should mention
each formal parameter by name in the function description,
preceded by the \\a command. The parameter name is then rendered
in italics.
\code
/ *!
Constructs a line edit containing the text
\a contents. The \a parent parameter is sent
to the QWidget constructor.
* /
QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)
{
...
}
\endcode
QDoc renders this as:
\quotation
\b {QLineEdit::QLineEdit ( const QString &
contents, QWidget *parent )}
Constructs a line edit containing the text \a contents.
The \a parent parameter is sent to the QWidget constructor.
\endquotation
The formal parameter name may be enclosed between curly brackets,
but that isn't required.
\target c-command
\section1 \\c (code font)
The \\c command is used for rendering variable names, user-defined
class names, and C++ keywords (for example, \c int and \c for) in the code
font.
The command renders its argument using a monospace font. For
example:
\code
/ *!
The \c AnalogClock class provides a clock widget with hour
and minute hands that is automatically updated every
few seconds.
* /
\endcode
QDoc renders this as:
\quotation
The \c AnalogClock class provides a clock widget with hour
and minute hands, which are automatically updated every
few seconds.
\endquotation
If the text to be rendered in the code font contains spaces, enclose the
entire text in curly brackets.
\code
\c {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)}
\endcode
QDoc renders this as:
\quotation
\c {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)}
\endquotation
The \\c command accepts the special character \c \ within its
argument, which renders it as a normal character. So if you want
to use nested commands, you must use the \l {tt-command} {teletype
(\\tt)} command instead.
See also \l {tt-command} {\\tt} and \l {code-command} {\\code}.
\target div-command
\section1 \\div
The \\div and \\enddiv commands delimit a large or small block of
text (which may include other QDoc commands) to which special
formatting attributes should be applied.
An argument must be provided in curly braces, as in the QDoc
comment shown below. The argument is not interpreted but is used
as attribute(s) of the tag that is output by QDoc.
For example, we might want to render an inline image so that it
floats to the right of the current block of text:
\code
/ *!
\div {class="float-right"}
\inlineimage qml-column.png
\enddiv
* /
\endcode
If QDoc is generating HTML, it will translate these commands to:
\code
<div class="float-right"><p><img src="images/qml-column.png" /></p></div>
\endcode
For HTML, the attribute value \e {float-right} then will refer to
a clause in the style.css file, which in this case could be:
\code
div.float-right
{
float: right; margin-left: 2em
}
\endcode
\note Note that the \b {\\div} command can be nested.
Below you can find an example taken from the index.qdoc file used to
generate index.html for Qt 4.7:
\code
\div {class="indexbox guide"}
\div {class="heading"}
Qt Developer Guide
\enddiv
\div {class="indexboxcont indexboxbar"}
\div {class="section indexIcon"} \emptyspan
\enddiv
\div {class="section"}
Qt is a cross-platform application and UI
framework. Using Qt, you can write web-enabled
applications once and deploy them across desktop,
mobile and embedded operating systems without
rewriting the source code.
\enddiv
\div {class="section sectionlist"}
\list
\li \l{Getting Started}
\li \l{Installation} {Installation}
\li \l{how-to-learn-qt.html} {How to learn Qt}
\li \l{tutorials.html} {Tutorials}
\li \l{Qt Examples} {Examples}
\li \l{qt4-7-intro.html} {What's new in Qt 4.7}
\endlist
\enddiv
\enddiv
\enddiv
\endcode
When all the class attribute values are defined as they are in the
style.css file that is used for rendering the Qt documentation,
the above example is rendered as:
\div {class="indexbox guide"}
\div {class="heading"}
Qt Developer Guide
\enddiv
\div {class="indexboxcont indexboxbar"}
\div {class="section indexIcon"} \emptyspan
\enddiv
\div {class="section"}
Qt is a cross-platform application and UI
framework. Using Qt, you can write web-enabled
applications once and deploy them across desktop,
mobile and embedded operating systems without
rewriting the source code.
\enddiv
\div {class="section sectionlist"}
\list
\li Getting Started
\li Installation
\li How to learn Qt
\li Tutorials
\li Examples
\li What's new in Qt 4.7
\endlist
\enddiv
\enddiv
\enddiv
See also \l {span-command} {\\span}.
\target span-command
\section1 \\span
The \\span command applies special formatting to a small block of text.
Two arguments must be provided, each argument in curly braces, as
shown in the QDoc comment below. The first argument is not
interpreted, but specifies the formatting attribute(s) of the tag
output by QDoc. The second argument is the text to be rendered with
the special formatting attributes.
For example, we might want to render the first word of each
element in a numeric list in blue.
\code
/ *!
Global variables with complex types:
\list 1
\li \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14
\li \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15
\li \span {class="variableName"} {constComplex1} in globals.cpp at line 16
\li \span {class="variableName"} {constComplex2} in globals.cpp at line 17
\endlist
* /
\endcode
Class \e {variableName} refers to a clause in your style.css.
\code
.variableName
{
font-family: courier;
color: blue
}
\endcode
Using the \e {variableName} clause shown above, the example is rendered as:
Global variables with complex types:
\list 1
\li \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14
\li \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15
\li \span {class="variableName"} {constComplex1} in globals.cpp at line 16
\li \span {class="variableName"} {constComplex2} in globals.cpp at line 17
\endlist
\note The \b span command does not cause a new paragraph to be
started.
See also \l {div-command} {\\div}.
\target tt-command
\section1 \\tt (teletype font)
The \\tt command renders its argument in a monospace font. This
command behaves just like the \l {c-command} {\\c} command, except
that \\tt allows you to nest QDoc commands within the argument
(e.g. \l {e-command} {\\e}, \l {b-command} {\\b} and \l
{underline-command} {\\underline}).
\code
/ *!
After having populated the main container with
child widgets, \c setupUi() scans the main container's list of
slots for names with the form
\tt{on_\e{objectName}_\e{signalName}().}
* /
\endcode
QDoc renders this as:
\quotation
After having populated the main container with
child widgets, \c setupUi() scans the main container's list of
slots for names with the form
\tt{on_\e{objectName}_\e{signalName}().}
\endquotation
If the text to be rendered in the code font contains spaces, enclose the
entire text in curly brackets.
\code
\tt {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)}
\endcode
QDoc renders this as:
\quotation
\tt {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)}
\endquotation
See also \l {c-command} {\\c}.
\target b-command
\section1 \\b
The \\b command renders its argument in bold font. This command used
to be called \\bold.
\code
/ *!
This is regular text; \b {this text is
rendered using the \\b command}.
* /
\endcode
QDoc renders this as:
\quotation
This is regular text; \b {this text is rendered using
the \\b command}.
\endquotation
\target e-command
\section1 \\e (emphasis, italics)
The \\e command renders its argument in a special font, normally italics. This
command used to be called \\i, which is now deprecated.
If the argument contains spaces or other punctuation, enclose the
argument in curly brackets.
\code
/ *!
Here, we render \e {a few words} in italics.
* /
\endcode
QDoc renders this as:
\quotation
Here, we render \e {a few words} in italics.
\endquotation
If you want to use other QDoc commands within an argument that
contains spaces, you always need to enclose the argument in
braces. But QDoc is smart enough to count parentheses [3], so you
don't need braces in cases like this:
\code
/ *!
An argument can sometimes contain whitespaces,
for example: \e QPushButton(tr("A Brand New Button"))
* /
\endcode
QDoc renders this as:
\quotation
An argument can sometimes contain whitespaces,
for example: \e QPushButton(tr("A Brand New Button"))
\endquotation
Finally, trailing punctuation is not included in an argument [4],
nor is "'s" [5]
\raw HTML
<table align="center" cellpadding="2"
cellspacing="1" border="0">
<tr valign="top" bgcolor="#a2c511">
<th></th>
<th>QDoc Syntax</th>
<th>Generated Documentation</th>
</tr>
<tr valign="top" bgcolor="#d0d0d0">
<td>1</td>
<td>A variation of a command button is a \e menu
button.</td>
<td>A variation of a command button is a <i>menu</i>
button.</td>
</tr>
<tr valign="top" bgcolor="#c0c0c0">
<td>2</td>
<td>The QPushButton widget provides a
\e {command button}.</td>
<td>The QPushButton widget provides a
<i>command button</i>.</td>
</tr>
<tr valign="top" bgcolor="#d0d0d0">
<td>3</td>
<td>Another class of buttons are option buttons
\e (see QRadioButton).</td>
<td>Another class of buttons are option buttons
<i> (see QRadioButton)</i>.</td>
</tr>
<tr valign="top" bgcolor="#c0c0c0">
<td>4</td>
<td>A push button emits the signal \e clicked().</td>
<td>A push button emits the signal <i>clicked</i>().</td>
</tr>
<tr valign="top" bgcolor="#d0d0d0">
<td>5</td>
<td>The \e QPushButton's checked property is
false by default.</td>
<td>The <i>QPushButton</i>'s checked property is
false by default.</td>
</tr>
</table>
\endraw
\target sub-command
\section1 \\sub
The \\sub command renders its argument lower than the baseline of
the regular text, using a smaller font.
\code
/ *!
Definition (Range): Consider the sequence
{x\sub n}\sub {n > 1} . The set
{x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...}
is called the range of the sequence.
* /
\endcode
QDoc renders this as:
\quotation
Definition (Range): Consider the sequence
{x\sub n}\sub {n > 1} . The set
{x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...}
is called the range of the sequence.
\endquotation
If the argument contains spaces or other punctuation, enclose the
argument in curly brackets.
\target sup-command
\section1 \\sup
The \\sup command renders its argument higher than
the baseline of the regular text, using a smaller font.
\code
/ *!
The series
1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ...
is called the \i {geometric series}.
* /
\endcode
QDoc renders this as:
\quotation
The series
1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ...
is called the \e {geometric series}.
\endquotation
If the argument contains spaces or other punctuation, enclose the
argument in curly brackets.
\target uicontrol-command
\section1 \\uicontrol
The \\uicontrol command is used to mark content as being used for UI
control elements. When using HTML, the output is rendered in bold.
\sa \\b
\target underline-command
\section1 \\underline
The \\underline command renders its argument underlined.
\code
/ *!
The \underline {F}ile menu gives the users the possibility
to edit an existing file, or save a new or modified
file, and exit the application.
* /
\endcode
QDoc renders this as:
\quotation
The \underline {F}ile menu gives the users the possibility
to edit an existing file, or save a new or modified
file, and exit the application.
\endquotation
If the argument contains spaces or other punctuation, enclose the
argument in curly brackets.
\target backslash-command
\section1 \\\\ (double backslash)
The \\\\ command expands to a double backslash.
QDoc commands always start with a single backslash. To display a
single backslash in the text you need to type two backslashes. If
you want to display two backslashes, you need to type four.
\code
/ *!
The \\\\ command is useful if you want a
backslash to appear verbatim, for example,
writing C:\\windows\\home\\.
* /
\endcode
QDoc renders this as:
\quotation
The \\\\ command is useful if you want a
backslash to appear verbatim, for example,
writing C:\\windows\\home\\.
\endquotation
However, if you want your text to appear in a monospace font as
well, you can use the \l {c-command} {\\c} command instead, which
accepts and renders the backslash as any other character. For
example:
\code
/ *!
The \\c command is useful if you want a
backslash to appear verbatim, and the word
that contains it written in a monospace font,
like this: \c {C:\windows\home\}.
* /
\endcode
QDoc renders this as:
\quotation
The \\c command is useful if you want a
backslash to appear verbatim, and the word
that contains it written in a monospace font,
like this: \c {C:\windows\home\}.
\endquotation
*/
/*!
\page 05-qdoc-commands-documentstructure.html
\previouspage Text Markup
\nextpage Including Code Inline
\title Document Structure
The document structuring commands are for dividing your document
into sections. QDoc supports four levels of section: \c \section1,
\c \section2, \c \section3, and \c \section4. The section commands
correspond to the traditional section, subsection, etc used in
outlining.
\target section-commands
\section1 Section commands
In general a document structuring command considers everything
that follows it until the first line break as its argument. The
argument is rendered as the unit's title. If the title needs to be
spanned over several lines, make sure that each line (except the
last one) is ended with a backslash.
In total, there are four levels for sections in QDoc: \c \section1,
\c \section2, \c \section3 and \c \section4. These correspond to the
traditional section, subsection, subsubsection and subsubsubsection.
There is a strict ordering of the section units:
\code
section1
|
section2
|
section3
|
section4
\endcode
When sections are used, the first section command should be \c section1.
\code
/ *!
\section1 Basic Qt
This is the first section.
\section2 Getting Started
This is the first subsection.
\section3 Hello Qt
This is the first subsubsection.
\section3 Making Connections
This is the second subsubsection.
\section3 Using the Reference Documentation
This is the third subsubsection.
\section2 Creating Dialogs
This is the second subsection.
\section3 Subclassing QDialog
This is the first subsubsection.
...
\section1 Intermediate Qt
This is the second section.
\section2 Layout Management
This is the second section's first subsection.
\section3 Basic Layouts
This is the first subsubsection.
...
* /
\endcode
QDoc renders this as:
\quotation
\raw HTML
<a name="Basic Qt">
<h1>Basic Qt</h1>
</a>
<p>This is the first section.</p>
<a name="Getting started">
<h2>Getting Started</h2>
</a>
This is the first subsection.</p>
<a name="Hello Qt">
<h3>Hello Qt</h3>
</a>
<p>This is the first subsubsection.</p>
<a name="Making Connections">
<h3>Making Connections</h3>
</a>
<p>This is the second subsubsection.</p>
<a name="Using the Reference Documentation">
<h3>Using the Reference Documentation</h3>
</a>
<p>This is the third subsubsection.</p>
<a name="Creating Dialogs">
<h2>Creating Dialogs</h2>
</a>
<p>This is the second subsection.</p>
<a name="Subclassing QDialog">
<h3>Subclassing QDialog</h3>
</a>
<p>This is the first subsubsection.</p>
...
<a name="Intermediate Qt">
<h1>Intermediate Qt</h1>
</a>
<p>This is the second section.</p>
<a name="Layout Management">
<h2>Layout Management</h2>
</a>
<p>This is the second section's first subsection.</p>
<a name="Basic Layouts">
<h3>Basic Layouts</h3>
</a>
<p>This is the first subsubsection.</p>
...
\endraw
\endquotation
Each section is a logical unit in the document. The section
heading appears in the automatically generated table of contents
that normally appears in the upper right-hand corner of the page.
\target sectionOne-command
\section1 \\section1
The \\section1 command starts a new section.
See \l{section-commands} {Section commands} for an explanation of the various
section units, command argument, and rendering.
\target sectionTwo-command
\section1 \\section2
The \\section2 command starts a new section.
See \l{section-commands} {Section commands} for an explanation of the various
section units, command argument, and rendering.
\target sectionThree-command
\section1 \\section3
The \\section3 command starts a new section.
See \l{section-commands} {Section commands} for an explanation of the various
section units, command argument, and rendering.
\target sectionFour-command
\section1 \\section4
The \\section4 command starts a new section.
See \l{section-commands} {Section commands} for an explanation of the various
section units, command argument, and rendering.
*/
/*!
\page 06-qdoc-commands-includecodeinline.html
\previouspage Document Structure
\nextpage Including External Code
\title Including Code Inline
The following commands are used to render source code without
formatting. The source code begins on a new line, rendered in the
code.
\note Although most of these commands are for rendering C++
code, the
\l{07-0-qdoc-commands-includingexternalcode.html#snippet-command}
{\\snippet} and
\l{07-0-qdoc-commands-includingexternalcode.html#codeline-command}
{\\codeline} commands are preferred over the others. These
commands allow equivalent code snippets for other Qt language
bindings to be substituted for the C++ snippets in the
documentation.
\target code-command
\section1 \\code
The \\code and \\endcode commands enclose a snippet of source code.
\note The \l {c-command} {\\c} command can be used for short code
fragments within a sentence. The \\code command is for longer code
snippets. It renders the code verbatim in a separate paragraph in
a html <pre> element, and parses the enclosed snippet, creating links
to any known types in the code.
For documenting command-line instructions, shell scripts, or any
content that is not in a Qt language recognized by QDoc, use
\l {badcode-command}{\\badcode} instead.
When processing any of the \\code, \l {newcode-command} {\\newcode} or \l
{oldcode-command} {\\oldcode} commands, QDoc removes all
indentation that is common for the verbatim code blocks within a
\c{/}\c{*!} ... \c{*}\c{/} comment before it adds the standard
indentation.
\note This doesn't apply to externally quoted code using the \l
{quotefromfile-command} {\\quotefromfile} or \l
{quotefile-command} {\\quotefile} command.
\code
/ *!
\code
#include <QApplication>
#include <QPushButton>
int main(int argc, char *argv[])
{
...
}
\ endcode
* /
\endcode
QDoc renders this as:
\code
#include <QApplication>
#include <QPushButton>
int main(int argc, char *argv[])
{
...
}
\endcode
Other QDoc commands are disabled within \\code... \\endcode, and
the special character '\\' is accepted and rendered like the rest
of the code, unless it is followed by a digit and parameters were
passed to \\code.
\section2 Code snippet parameters
Since QDoc version 5.12, \\code command accepts also optional
parameters. Parameters are useful for injecting simple
strings into the code snippet. To inject a string to a specific
location in the snippet, add a backslash followed by a digit (1..8).
The digits correspond with the order of the argument list, where
arguments are separated by spaces.
For example:
\code
/ *!
\code * hello
/\1 \2 \1/
\ endcode
* /
\endcode
For the above snippet, QDoc renders the word \e hello enclosed in
a C-style comment.
\section2 Including code from external files
To include code snippets from an external file, use the
\l{07-0-qdoc-commands-includingexternalcode.html#snippet-command}
{\\snippet} and
\l{07-0-qdoc-commands-includingexternalcode.html#codeline-command}
{\\codeline} commands.
See also \l {c-command} {\\c}, \l {badcode-command} {\\badcode}, \l
{07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command}
{\\quotefromfile}, \l{newcode-command} {\\newcode}, and \l {oldcode-command}
{\\oldcode}.
\target badcode-command
\section1 \\badcode
Similar to \l {code-command}{\\code}, \\badcode and \\endcode commands
enclose content that is rendered verbatim in a separate paragraph, but no
parsing or automatic link creation is performed. Instead, the content is
treated as plain text.
Substitute \\code with this command when documenting command-line
instructions, shell scripts or any other content that is not in a Qt
language, but should still be styled similarly to a \\code paragraph.
Like \\code, \\badcode accepts also optional parameters.
\target newcode-command
\section1 \\newcode
The \\newcode, \\oldcode, and \\endcode commands enable you to
show how to port a snippet of code to a new version of an API.
The \\newcode command and its companion the \\oldcode command are
a convenience combination of the \l {code-command} {\\code} commands:
this combination provides a text relating the two code snippets to each
other.
The \\newcode command requires a preceding \\oldcode statement.
Like the \l{code-command}{\\code} command, the \\newcode command renders its
code on a new line in the documentation using a monospace font and the
standard indentation.
\code
/ *!
\oldcode
if (printer->setup(parent))
...
\newcode
QPrintDialog dialog(printer, parent);
if (dialog.exec())
...
\ endcode
* /
\endcode
QDoc renders this as:
\quotation
\oldcode
if (printer->setup(parent))
...
\newcode
QPrintDialog dialog(printer, parent);
if (dialog.exec())
...
\endcode
\endquotation
Other QDoc commands are disabled within \\oldcode ... \\endcode,
and the '\\' character doesn't need to be escaped.
\target oldcode-command
\section1 \\oldcode
The \\oldcode command requires a corresponding
\\newcode statement; otherwise QDoc fails to parse the command
and emits a warning.
See also \l {newcode-command} {\\newcode}.
\target qml-command
\section1 \\qml
The \\qml and \\endqml commands enclose a snippet of QML source
code.
\code
/ *!
\qml
import QtQuick 2.0
Row {
Rectangle {
width: 100; height: 100
color: "blue"
transform: Translate { y: 20 }
}
Rectangle {
width: 100; height: 100
color: "red"
transform: Translate { y: -20 }
}
}
\endqml
* /
\endcode
QDoc renders this as:
\qml
import QtQuick 2.0
Row {
Rectangle {
width: 100; height: 100
color: "blue"
transform: Translate { y: 20 }
}
Rectangle {
width: 100; height: 100
color: "red"
transform: Translate { y: -20 }
}
}
\endqml
Like the \l{code-command}{\\code} command, \\qml accepts optional
parameters.
*/
/*!
\page 07-0-qdoc-commands-includingexternalcode.html
\previouspage Including Code Inline
\nextpage Creating Links
\title Including External Code
The following commands enable you to include code snippets from
external files. You can make QDoc include the complete contents of
a file, or you can quote specific parts of the file and skip
others. The typical use of the latter is to quote a file chunk by
chunk.
\note Although all these commands can be used for rendering C++
code, the
\l{07-0-qdoc-commands-includingexternalcode.html#snippet-command}
{\\snippet} and
\l{07-0-qdoc-commands-includingexternalcode.html#codeline-command}
{\\codeline} commands are preferred over the others. These
commands allow equivalent code snippets for other Qt language
bindings to be substituted for the C++ snippets in the
documentation.
\target quotefile-command
\section1 \\quotefile
The \\quotefile command expands to the complete contents of the
file given as argument.
The command considers the rest of the line as part of its
argument, make sure to follow the file name with a line break.
The file's contents is rendered in a separate paragraph, using a
monospace font and the standard indentation. The code is shown
verbatim.
\code
/ *!
This is a simple "Hello world" example:
\quotefile examples/main.cpp
It contains only the bare minimum you need
to get a Qt application up and running.
* /
\endcode
QDoc renders this as:
\quotation
This is a simple "Hello world" example:
\quotefile examples/main.cpp
It contains only the bare minimum you need to get a Qt
application up and running.
\endquotation
See also \l {quotefromfile-command} {\\quotefromfile} and
\l {code-command} {\\code}.
\target quotefromfile-command
\section1 \\quotefromfile
The \\quotefromfile command opens the file given as argument for
quoting.
The command considers the rest of the line as part of its
argument, make sure to follow the file name with a line break.
The command is intended for use when quoting parts from file with
the walkthrough commands: \l {printline-command} {\\printline}, \l
{printto-command} {\\printto}, \l {printuntil-command}
{\\printuntil}, \l {skipline-command} {\\skipline}, \l
{skipto-command} {\\skipto}, \l {skipuntil-command}
{\\skipuntil}. This enables you to quote specific portions of a
file.
\code
/ *!
The whole application is contained within
the \c main() function:
\quotefromfile examples/main.cpp
\skipto main
\printuntil app(argc, argv)
First we create a QApplication object using
the \c argc and \c argv parameters.
\skipto QPushButton
\printuntil resize
Then we create a QPushButton, and give it a reasonable
size using the QWidget::resize() function.
...
* /
\endcode
QDoc renders this as:
\quotation
The whole application is contained within
the \c main() function:
\quotefromfile examples/main.cpp
\skipto main
\printuntil app(argc, argv)
First we create a QApplication object using the \c argc
and \c argv parameters.
\skipto QPushButton
\printuntil resize
Then we create a QPushButton, and give it a reasonable
size using the QWidget::resize() function.
...
\endquotation
QDoc remembers which file it is quoting from, and the current
position in that file (see \l {file} {\\printline} for more
information). There is no need to "close" the file.
See also \l {quotefile-command} {\\quotefile}, \l {code-command}
{\\code} and \l {dots} {\\dots}.
\target printline-command
\section1 \\printline
The \\printline command expands to the line from the current
position to the next non-blank line of the current source file.
To ensure that the documentation remains synchronized with the
source file, a substring of the line must be specified as an
argument to the command. Note that the command considers the rest
of the line as part of its argument, make sure to follow the
substring with a line break.
The line from the source file is rendered as a separate paragraph,
using a monospace font and the standard indentation. The code is
shown verbatim.
\code
/ *!
There has to be exactly one QApplication object
in every GUI application that uses Qt.
\quotefromfile examples/main.cpp
\printline QApplication
This line includes the QApplication class
definition. QApplication manages various
application-wide resources, such as the
default font and cursor.
\printline QPushButton
This line includes the QPushButton class
definition. The QPushButton widget provides a command
button.
\printline main
The main function...
* /
\endcode
QDoc renders this as:
\quotation
There has to be exactly one QApplication object
in every GUI application that uses Qt.
\quotefromfile examples/main.cpp
\skipto QApplication
\printline QApplication
This line includes the QApplication class
definition. QApplication manages various
application-wide resources, such as the
default font and cursor.
\printline QPushButton
This line includes the QPushButton class
definition. The QPushButton widget provides a command
button.
\printline main
The main function...
\endquotation
\target file
QDoc reads the file sequentially. To move the current position
forward you can use either of the \l {skipline-command}
{\\skip...} commands. To move the current position backward, you
can use the \l {quotefromfile-command} {\\quotefromfile} command
again.
\target substring
If the substring argument is surrounded by slashes it is
interpreted as a \l {QRegExp}{regular expression}.
\code
/ *!
\quotefromfile examples/mainwindow.cpp
\skipto closeEvent
\printuntil /^\}/
Close events are sent to widgets that the users want to
close, usually by clicking \c File|Exit or by clicking
the \c X title bar button. By reimplementing the event
handler, we can intercept attempts to close the
application.
* /
\endcode
QDoc renders this as:
\quotation
\quotefromfile examples/mainwindow.cpp
\skipto closeEvent
\printuntil /^\}/
Close events are sent to widgets that the users want to
close, usually by clicking \c File|Exit or by clicking
the \c X title bar button. By reimplementing the event
handler, we can intercept attempts to close the
application.
\endquotation
(\l {widgets/scribble} {The complete example file...})
The regular expression \c /^\}/ makes QDoc print until the first
'}' character occurring at the beginning of the line without
indentation. /.../ encloses the regular expression, and '^' means
the beginning of the line. The '}' character must be escaped since
it is a special character in regular expressions.
QDoc will emit a warning if the specified substring or regular
expression cannot be located, i.e. if the source code has changed.
See also \l {printto-command} {\\printto} and \l
{printuntil-command} {\\printuntil}.
\target printto-command
\section1 \\printto
The \\printto command expands to all the lines from the current
position up to and \e excluding the next line containing a given
substring.
The command considers the rest of the line as part of its
argument, make sure to follow the substring with a line break. The
command also follows the same conventions for \l {file}
{positioning} and \l {substring} {argument} as the \l
{printline-command} {\\printline} command.
The lines from the source file are rendered in a separate
paragraph, using a monospace font and the standard
indentation. The code is shown verbatim.
\code
/ *!
The whole application is contained within the
\c main() function:
\quotefromfile examples/main.cpp
\printto hello
First we create a QApplication object using the \c argc and
\c argv parameters...
* /
\endcode
QDoc renders this as:
\quotation
The whole application is contained within the
\c main() function:
\quotefromfile examples/main.cpp
\skipto main
\printto hello
First we create a QApplication object using the \c argc
and \c argv parameters...
\endquotation
See also \l {printline-command} {\\printline} and \l
{printuntil-command} {\\printuntil}.
\target printuntil-command
\section1 \\printuntil
The \\printuntil command expands to all the lines from the current
position up to and \e including the next line containing a given
substring.
The command considers the rest of the line as part of its
argument, make sure to follow the substring with a line break. The
command also follows the same conventions for \l {file}
{positioning} and \l {substring} {argument} as the \l
{printline-command} {\\printline} command.
If \\printuntil is used without an argument, it expands to all the
lines from the current position to the end of the quoted file.
The lines from the source file are rendered in a separate
paragraph, using a monospace font and the standard
indentation. The code is shown verbatim.
\code
/ *!
The whole application is contained within the
\c main() function:
\quotefromfile examples/main.cpp
\skipto main
\printuntil hello
First we create a QApplication object using the
\c argc and \c argv parameters, then we create
a QPushButton.
* /
\endcode
QDoc renders this as:
\quotation
The whole application is contained within the
\c main() function:
\quotefromfile examples/main.cpp
\skipto main
\printuntil hello
First we create a \l
{http://doc.qt.io/qt-5/qapplication.html} {QApplication}
object using the \c argc and \c argv parameters, then we
create a \l
{http://doc.qt.io/qt-5/qpushbutton.html} {QPushButton}.
\endquotation
See also \l {printline-command} {\\printline} and \l
{printto-command} {\\printto}.
\target skipline-command
\section1 \\skipline
The \\skipline command ignores the next non-blank line in the
current source file.
Doc reads the file sequentially, and the \\skipline command is
used to move the current position (omitting a line of the source
file). See the remark about \l {file} {file positioning} above.
The command considers the rest of the line as part of its
argument, make sure to follow the substring with a line break. The
command also follows the same conventions for \l {substring}
{argument} as the \l {printline-command} {\\printline} command,
and it is used in conjunction with the \l {quotefromfile-command}
{\\quotefromfile} command.
\code
/ *!
QPushButton is a GUI push button that the user
can press and release.
\quotefromfile examples/main.cpp
\skipline QApplication
\printline QPushButton
This line includes the QPushButton class
definition. For each class that is part of the
public Qt API, there exists a header file of
the same name that contains its definition.
* /
\endcode
QDoc renders this as:
\quotation
\l
QPushButton is a GUI push button that the user
can press and release.
\quotefromfile examples/main.cpp
\skipto QApplication
\skipline QApplication
\printline QPushButton
This line includes the QPushButton class
definition. For each class that is part of the public
Qt API, there exists a header file of the same name
that contains its definition.
\endquotation
See also \l {skipto-command} {\\skipto}, \l {skipuntil-command}
{\\skipuntil} and \l {dots} {\\dots}.
\target skipto-command
\section1 \\skipto
The \\skipto command ignores all the lines from the current
position up to and \e excluding the next line containing a given
substring.
QDoc reads the file sequentially, and the \\skipto command is used
to move the current position (omitting one or several lines of the
source file). See the remark about \l {file} {file positioning}
above.
The command considers the rest of the line as part of its
argument, make sure to follow the substring with a line break.
The command also follows the same conventions for \l {substring}
{argument} as the \l {printline-command} {\\printline} command,
and it is used in conjunction with the \l {quotefromfile-command}
{\\quotefromfile} command.
\code
/ *!
The whole application is contained within
the \c main() function:
\quotefromfile examples/main.cpp
\skipto main
\printuntil }
First we create a QApplication object. There
has to be exactly one such object in
every GUI application that uses Qt. Then
we create a QPushButton, resize it to a reasonable
size...
* /
\endcode
QDoc renders this as:
\quotation
The whole application is contained within
the \c main() function:
\quotefromfile examples/main.cpp
\skipto main
\printuntil }
First we create a QApplication object. There has to be
exactly one such object in every GUI application that
uses Qt. Then we create a QPushButton, resize it to a
reasonable size ...
\endquotation
See also \l {skipline-command} {\\skipline}, \l
{skipuntil-command} {\\skipuntil} and \l {dots} {\\dots}.
\target skipuntil-command
\section1 \\skipuntil
The \\skipuntil command ignores all the lines from the current
position up to and \e including the next line containing a given
substring.
QDoc reads the file sequentially, and the \\skipuntil command is
used to move the current position (omitting one or several lines
of the source file). See the remark about \l {file} {file
positioning} above.
The command considers the rest of the line as part of its
argument, make sure to follow the substring with a line break.
The command also follows the same conventions for \l {substring}
{argument} as the \l {printline-command} {\\printline} command,
and it is used in conjunction with the \l {quotefromfile-command}
{\\quotefromfile} command.
\code
/ *!
The first thing we did in the \c main() function
was to create a QApplication object \c app.
\quotefromfile examples/main.cpp
\skipuntil show
\dots
\printuntil }
In the end we must remember to make \c main() pass the
control to Qt. QCoreApplication::exec() will return when
the application exits...
* /
\endcode
QDoc renders this as:
\quotation
The first thing we did in the \c main() function was to
create a QApplication object \c app.
\quotefromfile examples/main.cpp
\skipuntil show
\dots
\printuntil }
In the end we must remember to make \c main() pass the
control to Qt. QCoreApplication::exec()
will return when the application exits...
\endquotation
See also \l {skipline-command} {\\skipline}, \l {skipto-command}
{\\skipto} and \l {dots} {\\dots}.
\target dots-command
\section1 \\dots
The \\dots command indicates that parts of the source file have
been omitted when quoting a file.
The command is used in conjunction with the \l
{quotefromfile-command} {\\quotefromfile} command, and should be
stated on its own line. The dots are rendered on a new line, using
a monospace font.
\code
/ *!
\quotefromfile examples/main.cpp
\skipto main
\printuntil {
\dots
\skipuntil exec
\printline }
* /
\endcode
QDoc renders this as:
\quotefromfile examples/main.cpp
\skipto main
\printuntil {
\dots
\skipuntil exec
\printline }
The default indentation is 4 spaces, but this can be adjusted
using the command's optional argument.
\code
/ *!
\dots 0
\dots
\dots 8
\dots 12
\dots 16
* /
\endcode
QDoc renders this as:
\dots 0
\dots
\dots 8
\dots 12
\dots 16
See also \l {skipline-command} {\\skipline}, \l {skipto-command}
{\\skipto} and \l {skipuntil-command} {\\skipuntil}.
\target snippet-command
\section1 \\snippet
The \\snippet command causes a code snippet to be included
verbatim as preformatted text, which may be syntax highlighted.
Each code snippet is referenced by the file that holds it and by
a unique identifier for that file. Snippet files are typically
stored in a \c{snippets} directory inside the documentation
directory (for example, \c{$QTDIR/doc/src/snippets}).
For example, the following documentation references a snippet in a
file residing in a subdirectory of the documentation directory:
\code
\snippet snippets/textdocument-resources/main.cpp Adding a resource
\endcode
The text following the file name is the unique identifier for the
snippet. This is used to delimit the quoted code in the relevant
snippet file, as shown in the following example that corresponds to
the above \c{\snippet} command:
\code
...
QImage image(64, 64, QImage::Format_RGB32);
image.fill(qRgb(255, 160, 128));
//! [Adding a resource]
document->addResource(QTextDocument::ImageResource,
QUrl("mydata://image.png"), QVariant(image));
//! [Adding a resource]
...
\endcode
By default, QDoc looks for \c{//!} as a code snippet marker.
For \c{.pro}, \c{.py}, \c{.cmake}, and \c{CMakeLists.txt}
files, \c {#!} is detected. Finally, \c{<!--} is accepted in
\c{.html}, \c{.qrc}, \c{.ui}, \c{.xml}, \c{.dita}, and \c{.xq} files.
\target codeline-command
\section1 \\codeline
The \\codeline command inserts a blank line of preformatted
text. It is used to insert gaps between snippets without closing
the current preformatted text area and opening a new one.
*/
/*!
\page 08-qdoc-commands-creatinglinks.html
\previouspage Including External Code
\nextpage Including Images
\title Creating Links
These commands are for creating hyperlinks to classes, functions,
examples, and other targets.
\target l-command
\section1 \\l (link)
The \\l link command is used to create a hyperlink to many
different kinds of targets. The command's general syntax is:
\code
\l [ link criteria ] { link target } { link text }
\endcode
...where the \c {link criteria} in square brackets are optional
but may be required when the \c {link target} is ambiguous. See
\l {Fixing Ambiguous Links} below.
Here is an example using the \\l command to link to an external page:
\code
/ *!
Read the \l {http://doc.qt.io/qt-5/}
{Qt 5.0 Documentation} carefully.
* /
\endcode
QDoc renders this as:
\quotation
Read the \l {http://doc.qt.io/qt-5/}
{Qt 5.0 Documentation} carefully.
\endquotation
If the link target is equivalent to the link text, the second
argument can be omitted.
For example, if you have documentation like:
\code
/ *!
\target assertions
Assertions make some statement about the text at the
point where they occur in the regexp, but they do not
match any characters.
...
Regexps are built up from expressions, quantifiers, and
\l {assertions} {assertions}.
* /
\endcode
You can simplify this as follows:
\code
/ *!
\target assertions
Assertions make some statement about the text at the
point where they occur in the regexp, but they do not
match any characters.
...
Regexps are built up from expressions, quantifiers, and
\l assertions.
* /
\endcode
For the one-parameter version, the braces can often be omitted.
The \\l command supports several ways of linking:
\list
\li \c {\l QWidget} - The name of a class documented with the \l
{class-command} {\\class} command.
\li \c {\l QWidget::sizeHint()} - The signature of a function without
parameters. If a matching function without parameters can't be found,
the link is satisfied with the first matching function found.
\li \c {\l QWidget::removeAction(QAction* action)} - The signature
of a function with parameters. If an exact match is not found, the
link is not satisfied and QDoc reports a \e {Can't link to...} error.
\li \c {\l <QtGlobal>} - The subject of a \l {headerfile-command}
{\\headerfile} command.
\li \c {\l widgets/wiggly} - The relative path used in an \l
{example-command} {\\example} command.
\li \c {\l {QWidget Class Reference}} - The title used in a
\l {title-command} {\\title} command.
\li \c {\l {Introduction to QDoc}}- The text from one of the
\l{section-commands} {Section commands}.
\li \c {\l fontmatching} - The argument of a \l {target-command}
{\\target} command.
\li \c {\l {Shared Classes}} - A keyword named in a \l
{keyword-command} {\\keyword} command.
\li \c {\l http://qt-project.org/} - A URL.
\endlist
QDoc also tries to make a link out of any word that doesn't
resemble a normal English word, for example, Qt class names or
functions, like QWidget or QWidget::sizeHint(). In these cases,
the \\l command can actually be omitted, but by using the command,
you ensure that QDoc will emit a warning if it cannot find the
link target. In addition, if you only want the function name to
appear in the link, you can use the following syntax:
\list
\li \c {\l {QWidget::} {sizeHint()}}
\endlist
QDoc renders this as:
\quotation
\l {QWidget::} {sizeHint()}
\endquotation
\section2 Fixing Ambiguous Links
Because of the modularization of Qt beginning with Qt 5.0, The
possibility that QDoc will have to deal with ambiguous links has
increased. An ambiguous link is one that has a matching target in
more than one Qt module, e.g. the same section title can appear in
more than one Qt module, or the name of a C++ class in one module
can also be the name of a QML type in another module. A real
example in Qt5 is the name Qt itself. Qt is the name of both a C++
namespace in QtCore and a QML type in QtQml.
Suppose we want to link to the \l {Qt} {Qt C++ namespace}. At the
time QDoc generated this HTML page, that link was correct. Does
it still go to the C++ namespace? Qdoc generated that link from
this link command:
\list
\li \c {\l {Qt} {Qt C++ namespace}}
\endlist
Now suppose we want to link to the \l [QML] {Qt} {Qt QML type}.
At the time QDoc generated this HTML page, that link was also
correct, but we had to use this link command:
\list
\li \c {\l [QML] {Qt} {Qt QML type}}
\endlist
The \e {QML} in \e {square brackets} tells QDoc to accept a
matching target only if the traget is on a QML page. Qdoc actually
finds the C++ namespace target first, but since that target is on
a C++ page, QDoc ignores it and keeps looking until it finds the
same target on a QML page.
Without the guidance in the \e{\\l command} in the optional \e
{square bracket} argument, QDoc links to the first matching target
it finds. QDoc can't warn that the link was ambiguous in such
cases because it doesn't know that another matching target exists.
\section2 What arguments can appear in square brackets?
A link command with square bracket argument has the following syntax:
\list
\c {\l [QML|CPP|DOC|QtModuleName] {link target} {link text}}
\endlist
The \e {square bracket} argument is only allowed in the \c {\l
(link)} command. The example above shows how \c QML is used as the
\e {square brackets} argument to force QDoc to match a QML target.
Most often, this will be a QML type, but it can also be a QML
member function of property.
In the example, QDoc didn't need a \e {square bracket} argument to
find the Qt C++ namespace page, because that one was the first
matching target QDoc found anyway. However, to force QDoc to find
a C++ target when a matching QML target gets in the way, \c CPP
can be used as the \e {square bracket} argument. For example:
\list
\li \c {\l [CPP] {Qt} {Qt C++ namespace}}
\endlist
...will force QDoc to ignore the Qt QML type and continue
searching until it matches the Qt C++ namespace.
If the link target is neither a C++ nor a QML entity, \c {DOC} can
be used as the \e {square bracket} argument to prevent QDoc from
matching either of those. At this writing, there were no cases of
ambiguous links where using \c {DOC} was required.
Often, the documentor knows which Qt module the link target is
in. When the module name is known, use the module name as the \e
{square bracket} argument. In the example above, if we know that
the QML type named Qt is located in the QtQml module, we can write
the link command like this:
\list
\li \c {\l [QtQml] {Qt} {Qt QML type}}
\endlist
When a module name is used as the \e {square bracket} argument,
QDoc will search for link the target in that module only. This
makes searching for link targets more efficient.
Finally, the module name and entity type arguments can be
combined, separated by a blank, so something like this is also
allowed:
\list
\li \c {\l [CPP QtQml] {Window} {C++ class Window}}
\endlist
As of this writing, there were no cases where combining the two
was required.
See also \l {sa-command} {\\sa}, \l {target-command} {\\target},
and \l {keyword-command} {\\keyword}.
\target sa-command
\section1 \\sa (see also)
The \\sa command defines a list of links that will be rendered in
a separate "See also" section at the bottom of the documentation
unit.
The command takes a comma-separated list of links as its
argument. If the line ends with a comma, you can continue
the list on the next line. The general syntax is:
\code
\sa {the first link}, {the second link},
{the third link}, ...
\endcode
QDoc will automatically try to generate "See also" links
interconnecting a property's various functions. For example, a
setVisible() function will automatically get a link to visible()
and vice versa.
In general, QDoc will generate "See also" links that interconnect
the functions that access the same property. It recognizes four
different syntax versions:
\list
\li \c property()
\li \c setProperty()
\li \c isProperty()
\li \c hasProperty()
\endlist
The \\sa command supports the same kind of links as the \l
{l-command} {\\l} command.
\code
/ *!
Appends the actions \a actions to this widget's
list of actions.
\sa removeAction(), QMenu, addAction()
* /
void QWidget::addActions(QList<QAction *> actions)
{
...
}
\endcode
QDoc renders this as:
\quotation
\b {void QWidget::addActions ( QList<QAction*>
\e actions )}
Appends the actions \e actions to this widget's list of
actions.
See also \l {QWidget::removeAction()} {removeAction()},
\l QMenu, and \l {QWidget::addAction()} {addAction()}.
\endquotation
See also \l {l-command} {\\l}, \l {target-command} {\\target} and
\l {keyword-command} {\\keyword}.
\target target-command
\section1 \\target
The \\target command names a place in the documentation that you
can link to using the \l {l-command} {\\l (link)} and \l
{sa-command} {\\sa (see also)} commands.
The text up to the line break becomes the target name. Be sure to
follow the target name with a line break. Curly brackets are not
required around the target name, but they may be required when the
target name is used in a link command. See below.
\code
/ *!
\target capturing parentheses
\section1 Capturing Text
Parentheses allow us to group elements together so that
we can quantify and capture them.
...
* /
\endcode
The target name \e{capturing parentheses} can be linked from
within the same document containing the target in the following way:
\list
\li \c {\l {capturing parentheses}} (from within the same QDoc comment)
\endlist
\note The brackets in the link example are required because the
target name contains spaces.
See also \l {l-command} {\\l}, \l {sa-command} {\\sa} and \l
{keyword-command} {\\keyword}.
\target keyword-command
\section1 \\keyword
The \\keyword command names a place in the documentation that you
can link to using the \l {l-command} {\\l (link)} and \l
{sa-command} {\\sa (see also)} commands.
The \\keyword command is like the \l {target-command} {\\target}
command, except when linking to keyword the link goes to the top of
the QDoc comment where the \\keyword appears in. If you want to
create a link target to a \c section unit within a \\page, use
\\target instead. A keyword can be linked from anywhere using a
simple syntax.
Keywords must be unique over all the documents processed during
the QDoc run. The command uses the rest of the line as its
argument. Be sure to follow the keyword with a line break.
\code
/ *!
\class QRegExp
\reentrant
\brief The QRegExp class provides pattern
matching using regular expressions.
\ingroup tools
\ingroup misc
\ingroup shared
\keyword regular expression
Regular expressions, or "regexps", provide a way to
find patterns within text.
...
* /
\endcode
The location marked with the keyword can be linked to with:
\code
/ *!
When a string is surrounded by slashes, it is
interpreted as a \l {QRegExp}{regular expression}.
* /
\endcode
QDoc renders this as:
\quotation
When a string is surrounded by slashes, it is
interpreted as a \l {regular expression}.
\endquotation
If the keyword text contains spaces, the brackets are required.
See also \l {l-command} {\\l (link)}, \l {sa-command} {\\sa (see
also)} and \l {target-command} {\\target}.
*/
/*!
\page 09-qdoc-commands-includingimages.html
\previouspage Creating Links
\nextpage Tables and Lists
\title 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.
\target image-command
\section1 \\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 \e{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.
\code
/ *!
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.
* /
\endcode
QDoc renders this as:
\quotation
Qt is a C++ toolkit for cross-platform GUI application development.
\image happyguy.jpg 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.
\endquotation
See also \l {inlineimage-command} {\\inlineimage} and \l
{caption-command} {\\caption}.
\target inlineimage-command
\section1 \\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:
\code
/ *!
\list 1
\li \inlineimage happy.gif Oh so happy!
\li \inlineimage happy.gif Oh so happy!
\li \inlineimage happy.gif Oh so happy!
\endlist
* /
\endcode
QDoc renders this as:
\list 1
\li \inlineimage happy.gif Oh so happy!
\li \inlineimage happy.gif Oh so happy!
\li \inlineimage happy.gif Oh so happy!
\endlist
Here is an example of including inline images in a table:
\code
/ *!
\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
* /
\endcode
QDoc renders this as:
\raw HTML
<table align="center" cellpadding="2"
cellspacing="1" border="0">
<tr valign="top" bgcolor="#a2c511">
<th>Qt</th>
<th>Qt Creator</th>
</tr>
<tr valign="top" bgcolor="#f0f0f0">
<td><img src="images/happy.gif" alt="Oh so happy!" />
</td>
<td><img src="images/happy.gif" alt="Oh so happy!" />
</td>
</tr>
<tr valign="top" bgcolor="#f0f0f0">
<td><img src="images/happy.gif" alt="Oh so happy!"/>
</td>
<td><img src="images/happy.gif" alt="Oh so happy!" />
</td>
</tr>
</table>
\endraw
The command can also be used to insert an image inline with the
text.
\code
/ *!
\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.
* /
\endcode
QDoc renders this as:
\quotation
\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.
\endquotation
See also \l {image-command} {\\image} and \l {caption-command} {\\caption}.
\target caption-command
\section1 \\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.
\code
/ *!
\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
* /
\endcode
QDoc renders this as:
\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
See also \l {image-command} {\\image} and \l {inlineimage-command}
{\\inlineimage}
*/
/*!
\page 10-qdoc-commands-tablesandlists.html
\previouspage Including Images
\nextpage Special Content
\title 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.
\target table-command
\section1 \\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:
\code
/ *!
\table 100 %
...
\endtable
* /
\endcode
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
\l {row-command} {\\row} command and consists of cells, each of which
starts with an \l {li-command} {\\li} command. There is also a \l
{header-command} {\\header} command which is a special kind of row
that has a special format.
\code
/ *!
\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
* /
\endcode
QDoc renders this as:
\raw HTML
<table align="center" cellpadding="2"
cellspacing="1" border="0">
<tr valign="top" bgcolor="#a2c511">
<th>Qt Core Feature</th>
<th>Brief Description</th>
</tr>
<tr valign="top" bgcolor="#d0d0d0">
<td>
<a href="http://doc.qt.io/qt-5/signalsandslots.html">
Signals and Slots</a>
</td>
<td>Signals and slots are used for communication
between objects.</td>
</tr>
<tr valign="top" bgcolor="#c0c0c0">
<td>
<a href="http://doc.qt.io/qt-5/layout.html">
Layout Management</a></td>
<td>The Qt layout system provides a simple
and powerful way of specifying the layout
of child widgets.</td>
</tr>
<tr valign="top" bgcolor="#d0d0d0">
<td>
<a href="http://doc.qt.io/qt-5/dnd.html">
Drag and Drop</a></td>
<td>Drag and drop provides a simple visual
mechanism which users can use to transfer
information between and within applications.</td>
</tr>
</table>
\endraw
You can also make cells span several rows and columns. For
example:
\code
/ *!
\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
* /
\endcode
QDoc renders this as:
\raw HTML
<table align="center" cellpadding="2" cellspacing="1"
border="0">
<tr valign="top" bgcolor="#a2c511">
<th colspan="3" rowspan=" 1">
This header cell spans three columns, but only one row.
</th>
</tr>
<tr valign="top" bgcolor="#d0d0d0">
<td colspan="2" rowspan=" 1">
This table cell spans two columns, but only one row.
</td>
<td rowspan=" 2">
This table cell spans only one column, but two rows.
</td>
</tr>
<tr valign="top" bgcolor="#c0c0c0">
<td>A regular table cell</td>
<td>A regular table cell</td>
</tr>
</table>
\endraw
See also \l {header-command} {\\header}, \l {row-command} {\\row} and \l {li-command} {\\li}.
\target header-command
\section1 \\header
The \\header command indicates that the following table cells are
the current table's column headers.
The command can only be used within the \l{table-command}
{\\table...\\endtable} commands. A header can contain several
cells. A cell is created with the \l {li-command} {\\li} command.
A header cell's text is centered within the table cell and
rendered using a bold font.
\code
/ *!
\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
* /
\endcode
QDoc renders this as:
\raw HTML
<table align="center" cellpadding="2"
cellspacing="1" border="0">
<tr valign="top" bgcolor="#a2c511">
<th>Qt Core Feature</th>
<th>Brief Description</th>
</tr>
<tr valign="top" bgcolor="#d0d0d0">
<td>
<a href="http://doc.qt.io/qt-5/signalsandslots.html">
Signals and Slots</a>
</td>
<td>Signals and slots are used for communication
between objects.</td>
</tr>
</table>
\endraw
See also \l {table-command} {\\table}, \l {row-command} {\\row} and \l {li-command} {\\li}.
\target row-command
\section1 \\row
The \\row command begins a new row in a table. The \l {li-command}
{\\li items} that belong in the new row will immediately follow the
\\row.
The command can only be used within the \l{table-command}
{\\table...\\endtable} commands. A row can contain several
cells. A cell is created with the \l {li-command} {\\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.
\code
/ *!
\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
* /
\endcode
QDoc renders this as:
\raw HTML
<table align="center" cellpadding="2"
cellspacing="1" border="0">
<tr valign="top" bgcolor="#a2c511">
<th>Qt Core Feature</th>
<th>Brief Description</th>
</tr>
<tr valign="top" bgcolor="#d0d0d0">
<td>
<a href="http://doc.qt.io/qt-5/signalsandslots.html">
Signals and Slots</a>
</td>
<td>Signals and slots are used for communication
between objects.</td>
</tr>
<tr valign="top" bgcolor="#c0c0c0">
<td>
<a href="http://doc.qt.io/qt-5/layout.html">
Layout Management</a></td>
<td>The Qt layout system provides a simple
and powerful way of specifying the layout
of child widgets.</td>
</tr>
<tr valign="top" bgcolor="#d0d0d0">
<td>
<a href="http://doc.qt.io/qt-5/dnd.html">
Drag and Drop</a></td>
<td>Drag and drop provides a simple visual
mechanism which users can use to transfer
information between and within applications.</td>
</tr>
</table>
\endraw
See also \l {table-command} {\\table}, \l {header-command}
{\\header}, and \l {li-command} {\\li}.
\target value-command
\section1 \\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 \e 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.
Without a \e since clause, a \\value command could look like this:
\code
\value QtInfoMsg A message generated by the qInfo() function.
\endcode
The same command with a \e since clause would look like this:
\code
\value [since 5.5] QtInfoMsg A message generated by the qInfo() function.
\endcode
The documentation will be located in the associated class, header
file or namespace documentation. See the \l {enum-command}
{\\enum} documentation for an example.
\note Since Qt 5.4, \\value command can also be used outside the
\l {enum-command} {\\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 \l {qmlproperty-command}{\\qmlproperty} topic for
documenting acceptable values for a QML enumeration property.
See also \l {enum-command} {\\enum} and \l {omitvalue-command} {\\omitvalue}.
\target omitvalue-command
\section1 \\omitvalue
The \\omitvalue command excludes a C++ enum item from the
documentation.
The command's only argument is the name of the enum item that will
be omitted. See the \l {enum-command} {\\enum} documentation for
an example.
See also \l {enum-command} {\\enum} and \l {value-command}
{\\value} \l {since-command}{\\since}
\target list-command
\section1 \\list
The \\list and \\endlist commands delimit a list of items.
Create each list item with the \l {li-command} {\\li} command. A
list always contains one or more items. Lists can be nested. For
example:
\code
/ *!
\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
* /
\endcode
QDoc renders this as:
\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.
\code
/ *!
\list
\li How to Learn Qt
\li Installation
\li Tutorial and Examples
\endlist
* /
\endcode
QDoc renders the list items with bullets (the default):
\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:
\list A
\li How to Learn Qt
\li Installation
\li Tutorial and Examples
\endlist
If you replace 'A' with '1', the list items are numbered in
ascending order:
\list 1
\li How to Learn Qt
\li Installation
\li Tutorial and Examples
\endlist
If you provide 'i' as the argument, the bullets are replaced with
roman numerals:
\list i
\li How to Learn Qt
\li Installation
\li Tutorial and Examples
\endlist
Finally, you can make the list items appear with roman numbers
following in ascending order if you provide 'I' as the optional
argument:
\list I
\li How to Learn Qt
\li Installation
\li Tutorial and Examples
\endlist
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:
\code
/ *!
\list G
\li How to Learn Qt
\li Installation
\li Tutorial and Examples
\endlist
* /
\endcode
QDoc renders this as:
\list G
\li How to Learn Qt
\li Installation
\li Tutorial and Examples
\endlist
See also \l {li-command} {\\li}.
\target li-command
\section1 \\li (table cell, list item)
The \\li command marks a table cell or a list item. This command
is only used in \l{table-command} {tables} and \l{list-command}
{lists}.
It considers everything as its argument until the next \\li command, until the
next \l {table-command} {\\endtable}, or \l {list-command} {\\endlist}
command. See \l {table-command} {\\table} and \l {list-command} {\\list}
for examples.
If the command is used within a table, you can also specify
how many rows or columns the item should span.
\code
/ *!
\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
* /
\endcode
QDoc renders this as:
\raw HTML
<table align="center" cellpadding="2" cellspacing="1"
border="0">
<tr valign="top" bgcolor="#a2c511">
<th colspan="3" rowspan=" 1">
This header cell spans three columns, but only one row.
</th>
</tr>
<tr valign="top" bgcolor="#d0d0d0">
<td colspan="2" rowspan=" 1">
This table item spans two columns, but only one row.
</td>
<td rowspan=" 2">
This table item spans only one column, but two rows.
</td>
</tr>
<tr valign="top" bgcolor="#c0c0c0">
<td>A regular table item</td>
<td>A regular table item</td>
</tr>
</table>
\endraw
If not specified, the item will span one column and one row.
See also \l {table-command} {\\table}, \l {header-command}
{\\header}, and \l {list-command} {\\list}.
*/
/*!
\page 11-qdoc-commands-specialcontent.html
\previouspage Tables and Lists
\nextpage Miscellaneous
\title Special Content
The document contents commands identify parts of the documentation,
parts with a special rendering, conceptual meaning or
function.
\target quotation-command
\section1 \\quotation
The \\quotation and \\endquotation commands delimit a long quotation.
The text in the delimited block is surrounded by
\b{<blockquote>} and \b{</blockquote>} in the html output,
e.g.:
\code
/ *!
Although the prospect of a significantly broader market is
good news for Firstlogic, the notion also posed some
challenges. Dave Dobson, director of technology for the La
Crosse, Wisconsin-based company, said:
\quotation
As our solutions were being adopted into new
environments, we saw an escalating need for easier
integration with a wider range of enterprise
applications.
\endquotation
* /
\endcode
The text in the \b{\\quotation} block will appear in the generated HTML as:
\code
<blockquote>
<p>As our solutions were being adopted into new environments,
we saw an escalating need for easier integration with a wider
range of enterprise applications.</p>
</blockquote>
\endcode
The built-in style sheet for most browsers will render the
contents of the <blockquote> tag with left and right
indentations. The example above would be rendered as:
\quotation
As our solutions were being adopted into new
environments, we saw an escalating need for easier
integration with a wider range of enterprise
applications.
\endquotation
But you can redefine the \b{<blockquote>} tag in your style.css file.
\target footnote-command
\section1 \\footnote
The \\footnote and \\endfootnote commands delimit a footnote.
The footnote is rendered at the bottom of the page.
\warning The \b{\\footnote} and \b{\\endfootnote} commands
have not been implemented. The footnote is rendered as a regular
HTML paragraph.
\target note-command
\section1 \\note
The \\note command defines a new paragraph preceded by "Note:"
in bold.
\target tableofcontents-command
\section1 \\tableofcontents
The \\tableofcontents command has been disabled because QDoc
now generates a table of contents automatically.
The automatically generated table of contents appears in the upper
righthand corner of the page.
\target brief-command
\section1 \\brief
The \\brief command introduces a one-sentence description of a
class, namespace, header file, property, or variable.
The brief text is used to introduce the documentation of the
associated object, and in lists generated using the \l
{generatelist-command} {\\generatelist} command and the \l
{annotatedlist-command} {\\annotatedlist} command.
The \\brief command can be used in two significant different ways:
\l {brief class} {One for classes, namespaces and header files},
and \l {brief-property} {one for properties and variables}.
\target brief-property
When the \\brief command is used to describe a property or a
variable, the brief text must be a sentence fragment starting with
"whether" (for a boolean property or variable) or starting with
"the" (for any other property or variable).
For example the boolean QWidget::isWindow property:
\code
/ *!
\property QWidget::isActiveWindow
\brief Whether this widget's window is the active window.
The active window is the window that contains the widget that
has keyboard focus.
When popup windows are visible, this property is \c true
for both the active window \e and the popup.
\sa activateWindow(), QApplication::activeWindow()
* /
\endcode
and the QWidget::geometry property
\code
/ *!
\property QWidget::geometry
\brief The geometry of the widget relative to its parent and
excluding the window frame.
When changing the geometry, the widget, if visible,
receives a move event (moveEvent()) and/or a resize
event (resizeEvent()) immediately.
...
\sa frameGeometry(), rect(), ...
* /
\endcode
QDoc renders this as:
\quotation
\raw HTML
<h3>geometry :
<a href="http://doc.qt.io/qt-5/qrect.html">QRect</a>
</h3>
\endraw
This property holds the geometry of the widget relative
to its parent and excluding the window frame.
...
Access functions:
\list
\li \b {const QRect & geometry () const}
\li \b {void setGeometry ( int x, int y, int w, int h )}
\li \b {void setGeometry ( const QRect & )}
\endlist
See also \l
{QWidget::frameGeometry()} {frameGeometry()}, \l
{QWidget::rect()} {rect()}, ...
\endquotation
\target brief class
When the \\brief command is used to describe a class, we recommend
using a complete sentence like this:
\code
The <classname> class is|provides|contains|specifies...
\endcode
\warning Do not repeat your detailed description with the same sentence as
the brief statement will be the first paragraph of the detailed
description.
\code
/ *!
\class PreviewWindow
\brief The PreviewWindow class is a custom widget
displaying the names of its currently set
window flags in a read-only text editor.
The PreviewWindow class inherits QWidget. The widget
displays the names of its window flags set with the
setWindowFlags() function. It is also provided with a
QPushButton that closes the window.
...
\sa QWidget
* /
\endcode
QDoc renders this as:
\quotation
\raw HTML
<h1>PreviewWindow Class Reference</h1>
\endraw
The PreviewWindow class is a custom widget displaying
the names of its currently set window flags in a
read-only text editor. \l {preview window} {More...}
\raw HTML
<h3>Properties</h3>
\endraw
\list
\li 52 properties inherited from QWidget
\li 1 property inherited from QObject
\endlist
\raw HTML
<h3>Public Functions</h3>
\endraw
\list
\li \l {constructor} {PreviewWindow}(QWidget *parent = 0)
\li void \l {function} {setWindowFlags}(Qt::WindowFlags flags)
\endlist
\list
\li 183 public functions inherited from QWidget
\li 28 public functions inherited from QObject
\endlist
\raw HTML
<h3>Public Slots</h3>
\endraw
\list
\li 17 public slots inherited from QWidget
\li 1 public slot inherited from QObject
\endlist
\raw HTML
<h3>Additional Inherited Members</h3>
\endraw
\list
\li 1 signal inherited from QWidget
\li 1 signal inherited from QObject
\li 4 static public members inherited from QWidget
\li 4 static public members inherited from QObject
\li 39 protected functions inherited from QWidget
\li 7 protected functions inherited from QObject
\endlist
\target preview window
\raw HTML
<hr />
<h2>Detailed Description</h2>
\endraw
The PreviewWindow class is a custom widget displaying
the names of its currently set window flags in a
read-only text editor.
The PreviewWindow class inherits QWidget. The widget
displays the names of its window flags set with the \l
{function} {setWindowFlags()} function. It is also
provided with a QPushButton that closes the window.
...
See also QWidget.
\raw HTML
<hr />
<h2>Member Function Documentation</h2>
\endraw
\target constructor
\raw HTML
<h3>PreviewWindow(QWidget *parent = 0)</h3>
\endraw
Constructs a preview window widget with \e parent.
\target function
\raw HTML
<h3>setWindowFlags(Qt::WindowFlags flags)</h3>
\endraw
Sets the widgets flags using the
QWidget::setWindowFlags() function.
Then runs through the available window flags,
creating a text that contains the names of the flags
that matches the flags parameter, displaying
the text in the widgets text editor.
\endquotation
Using \\brief in a \l{namespace-command}{\\namespace}:
\code
/ *!
\namespace Qt
\brief The Qt namespace contains miscellaneous identifiers
used throughout the Qt library.
* /
\endcode
Using \\brief in a \l{headerfile-command}{\\headerfile}:
\code
/ *!
\headerfile <QtGlobal>
\title Global Qt Declarations
\brief The <QtGlobal> header file provides basic
declarations and is included by all other Qt headers.
\sa <QtAlgorithms>
* /
\endcode
See also \l{property-command} {\\property}, \l{class-command}
{\\class}, \l{namespace-command} {\\namespace} and
\l{headerfile-command} {\\headerfile}.
\target legalese-command
\section1 \\legalese
The \\legalese and \\endlegalese commands delimit a license agreement.
In the generated HTML, the delimited text is surrounded by a \b
{<div class="LegaleseLeft">} and \b {</div>} tags.
An example of a license agreement enclosed in \\legalese
and \\endlegalese:
\code
/ *!
\legalese
Copyright 1996 Daniel Dardailler.
Permission to use, copy, modify, distribute, and sell this
software for any purpose is hereby granted without fee,
provided that the above copyright notice appear in all
copies and that both that copyright notice and this
permission notice appear in supporting documentation, and
that the name of Daniel Dardailler not be used in
advertising or publicity pertaining to distribution of the
software without specific, written prior permission. Daniel
Dardailler makes no representations about the suitability of
this software for any purpose. It is provided "as is"
without express or implied warranty.
Modifications Copyright 1999 Matt Koss, under the same
license as above.
\endlegalese
* /
\endcode
It will appear in the generated HTML as:
\code
<div class="LegaleseLeft">
<p>Copyright 1996 Daniel Dardailler.</p>
<p>Permission to use, copy, modify, distribute, and sell
this software for any purpose is hereby granted without fee,
provided that the above copyright notice appear in all
copies and that both that copyright notice and this
permission notice appear in supporting documentation, and
that the name of Daniel Dardailler not be used in
advertising or publicity pertaining to distribution of the
software without specific, written prior permission. Daniel
Dardailler makes no representations about the suitability of
this software for any purpose. It is provided "as is"
without express or implied warranty.</p>
<p>Modifications Copyright 1999 Matt Koss, under the same
license as above.</p>
</div>
\endcode
If the \\endlegalese command is omitted, QDoc will process the
\\legalese command but considers the rest of the documentation
page as the license agreement.
Ideally, the license text is located with the licensed code.
Elsewhere, the documentation identified as \e{\\legalese} command
can be accumulated using \l {generatelist-command} {\\generatelist}
with \c {legalese} as the argument. This is useful for generating
an overview of the license agreements associated with the source
code.
\note The output of the \c {\generatelist legalese} command includes
the \\legalese texts in the current documentation project only. If
the current documentation project depends on other modules, their
license texts will not be listed.
\target warning-command
\section1 \\warning
The \\warning command prepends "Warning:" to the command's
argument, in bold font.
\code
/ *!
Qt::HANDLE is a platform-specific handle type
for system objects. This is equivalent to
\c{void *} on Windows and macOS, and to
\c{unsigned long} on X11.
\warning Using this type is not portable.
* /
\endcode
QDoc renders this as:
\quotation
Qt::HANDLE is a platform-specific handle type
for system objects. This is equivalent to
\c{void *} on Windows and macOS, and to
\c{unsigned long} on X11.
\warning Using this type is not portable.
\endquotation
*/
/*!
\page 12-0-qdoc-commands-miscellaneous.html
\previouspage Special Content
\nextpage The QDoc Configuration File
\title Miscellaneous
These commands provide miscellaneous functions connected to the
visual appearance of the documentation, and to the process of
generating the documentation.
\target annotatedlist-command
\section1 \\annotatedlist
The \\annotatedlist command expands to a list of the members of a
group, each member listed with its \e {brief} text. Below is an
example from the Qt Reference Documentation:
\code
/ *!
...
\section1 Drag and Drop Classes
These classes deal with drag and drop and the necessary mime type
encoding and decoding.
\annotatedlist draganddrop
* /
\endcode
This generates a list of all the C++ classes and/or QML types in
the \e{draganddrop} group. A C++ class or QML type in the
\e{draganddrop} group will have \e{\\ingroup draganddrop} in its
\e{\\class} or \e{\\qmltype} comment.
\target generatelist-command
\section1 \\generatelist
The \\generatelist command expands to a list of links to the
documentation entities in a group. Below is an example from the Qt
Reference Documentation:
\code
/ *!
\page classes.html
\title All Classes
For a shorter list that only includes the most
frequently used classes, see \l{Qt's Main Classes}.
\generatelist classes Q
* /
\endcode
This generates the \e {All Classes} page. The command accepts the
following arguments:
\target table example
\section2 \c annotatedclasses
The \c annotatedclasses argument provides a table containing the
names of all the classes, and a description of each class. Each
class name is a link to the class's reference documentation. For
example:
\table
\row
\li QDial
\li Rounded range control (like a speedometer or potentiometer)
\row
\li QDialog
\li The base class of dialog windows
\row
\li QDir
\li Access to directory structures and their contents
\endtable
A C++ class is documented with the \l {class-command} {\\class}
command. The annotation for the class is taken from the argument
of the class comment's \l {brief-command} {\\brief} command.
\section2 \c annotatedexamples
The \c annotatedexamples argument provides a complete list of all
examples as a set of tables containing the titles of all the
examples, and a description of each example. Each title is a
link to the example's documentation.
A separate table for each module (that has documented examples)
is generated, provided that the module has defined a
navigation.landingpage configuration variable. The \e landingpage
variable is used as a title for a header that precedes each table.
\section2 \c annotatedattributions
The \c annotatedattributions argument provides a complete list of all
attributions as a set of tables containing the titles of all the
attributions, and a description of each attribution. Each title is a
link to the attribution's page.
A separate table for each module (that has attributions)
is generated, provided that the module has defined a
navigation.landingpage configuration variable. The \e landingpage
variable is used as a title for a header that precedes each table.
\target list example
\section2 \c {classes <prefix>}
The \c classes argument provides a complete alphabetical list of
the classes. The second argument, \c{<prefix>}, is the common
prefix for the class names. The class names will be sorted on the
character that follows the common prefix. e.g. The common prefix
for the Qt classes is \c Q. The common prefix argument is
optional. If no common prefix is provided, the class names will
be sorted on their first character.
Each class name becomes a link to the class's reference
documentation. This command is used to generate the
\e {All Classes} page this way:
\code
/ *!
\page classes.html
\title All Classes
\ingroup classlists
\brief Alphabetical list of classes.
This is a list of all Qt classes. For classes that
have been deprecated, see the \l{Obsolete Classes}
list.
\generatelist classes Q
* /
\endcode
A C++ class is documented with the \l {class-command} {\\class}
command.
\section2 \c classesbymodule
When this argument is used, a second argument is required, which
specifies the module whose classes are to be listed. QDoc
generates a table containing those classes. Each class is listed
with the text of its \l{brief-command} {\\brief} command.
For example, this command can be used on a module page as follows:
\code
/ *!
\page phonon-module.html
\module Phonon
\title Phonon Module
\ingroup modules
\brief Contains namespaces and classes for multimedia functionality.
\generatelist{classesbymodule Phonon}
...
* /
\endcode
Each class that is a member of the specified module must be marked
with the \l {inmodule-command} {\\inmodule} command in its \\class
comment.
\section2 \c qmltypesbymodule
Similar to \c classesbymodule argument, but used for listing the
QML types from the QML module specified with the second argument.
\note Support for this argument was introduced in QDoc 5.6.
\section2 \c jstypesbymodule
Similar to \c classesbymodule argument, but used for listing the
JavaScript types from the module specified with the second argument.
\note Support for this argument was introduced in QDoc 5.6.
\section2 \c {examplefiles [regular_expression]}
The \c examplefiles argument lists the files that are part of
an example project. The optional second argument is a regular
expression; if provided, only the files whose path matches with
the regular expression are listed.
The \c examplefiles argument can be only used within example
documentation (see \l {example-command}{\\example}), and is
typically used together with the \l {noautolist-command}{\\noautolist}
command.
\section2 \c {exampleimages [regular_expression]}
The \c exampleimages argument lists the images that are part of
an example project. The optional second argument is a regular
expression; if provided, only the image files whose path matches
with the regular expression are listed.
The \c exampleimages argument can be only used within example
documentation (see \l {example-command}{\\example}), and is
typically used together with the \l {noautolist-command}{\\noautolist}
command.
\section2 \c functionindex
The \c functionindex argument provides a complete alphabetical
list of all the documented member functions. It is normally used
only to generate the \e {Qt function index} page
this way:
\code
/ *!
\page functions.html
\title All Functions
\ingroup funclists
\brief All documented Qt functions listed alphabetically with a
link to where each one is declared.
This is the list of all documented member functions and global
functions in the Qt API. Each function has a link to the
class or header file where it is declared and documented.
\generatelist functionindex
* /
\endcode
\section2 \c legalese
The \c legalese argument tells QDoc to generate a list of licenses in
the current documentation project. Each license is identified using
the \l {legalese-command} {\\legalese} command.
\section2 \c overviews
The \c overviews argument is used to tell QDoc to generate a list
by concatenating the contents of all the \l {group-command}
{\\group} pages. Qt uses it to generate the \e {overviews} page
this way:
\code
/ *!
\page overviews.html
\title All Overviews and HOWTOs
\generatelist overviews
* /
\endcode
\section2 \c attributions
The \c attributions argument is used to tell QDoc to generate a list
of attributions in the documentation.
\section2 \c related
The \c related argument is used in combination with the \l
{group-command} {\\group} and \l {ingroup-command} {\\ingroup}
commands to list all the overviews related to a specified
group. For example, the page for the \e {Programming with Qt}
page is generated this way:
\code
/ *!
\group qt-basic-concepts
\title Programming with Qt
\brief The basic architecture of the Qt cross-platform application and UI framework.
Qt is a cross-platform application and UI framework for
writing web-enabled applications for desktop, mobile, and
embedded operating systems. This page contains links to
articles and overviews explaining key components and
techniuqes used in Qt development.
\generatelist {related}
* /
\endcode
Each page listed on this group page contains the command:
\code
\ingroup qt-basic-concepts
\endcode
\target if-command
\section1 \\if
The \\if command and the corresponding \\endif command
enclose parts of a QDoc comment that only will be included if
the condition specified by the command's argument is true.
The command reads the rest of the line and parses it as an C++ #if
statement.
\code
/ *!
\if defined(opensourceedition)
\note This edition is for the development of
\l{Qt Open Source Edition} {Free and Open Source}
software only; see \l{Qt Commercial Editions}.
\endif
* /
\endcode
This QDoc comment will only be rendered if the \c
opensourceedition preprocessor symbol is defined, and specified in
the \l {defines-variable} {defines} variable in the configuration
file to make QDoc process the code within #ifdef and #endif:
\code
defines = opensourceedition
\endcode
You can also define the preprocessor symbol manually on the
command line. For more information see the documentation of the \l
{defines-variable} {defines} variable.
See also \l{endif-command} {\\endif}, \l{else-command} {\\else},
\l {defines-variable} {defines} and \l {falsehoods-variable}
{falsehoods}.
\target endif-command
\section1 \\endif
The \\endif command and the corresponding \\if command
enclose parts of a QDoc comment that will be included if
the condition specified by the \l {if-command} {\\if} command's
argument is true.
For more information, see the documentation of the \l {if-command}
{\\if} command.
See also \l{if-command} {\\if}, \l{else-command} {\\else}, \l
{defines-variable} {defines} and \l {falsehoods-variable}
{falsehoods}.
\target else-command
\section1 \\else
The \\else command specifies an alternative if the
condition in the \l {if-command} {\\if} command is false.
The \\else command can only be used within \l {if-command}
{\\if...\\endif} commands, but is useful when there is only two
alternatives.
\target include-command
\section1 \\include
The \\include command sends all or part of the file specified by
its first argument to the QDoc input stream to be processed as a
QDoc comment snippet.
The command is useful when some snippet of commands or text is to
be used in multiple places in the documentation. Use the \\include
command wherever you want to insert a snippet into the documentation.
The file containing the snippet to include, must be located under the
path(s) listed in the \l{sourcedirs-variable}{sourcedirs} or
\l{exampledirs-variable}{exampledirs} QDoc configuration variable.
It can be either any source file parsed by QDoc (or even the same one
where \\include command is used), or any other text file. To store
snippets in a separate file that is not meant to be parsed by QDoc,
use a file extension that is not listed in
\l{sources.fileextensions-variable}{sources.fileextensions};
for example, \c .qdocinc.
The command can have either one or two arguments. The first
argument is always a file name. The contents of the file must be
QDoc input, in other words, a sequence of QDoc commands and text, but
without the enclosing QDoc comment \c{/}\c{*!} ... \c{*}\c{/} delimiters.
If you want to include the entire named file, don't use the second
argument. If you want to include only part of the file, see the
\l{2-argument-form}{two argument form} below. Here is an example
of the one argument form:
\code
/ *!
\page corefeatures.html
\title Core Features
\include examples/signalandslots.qdocinc
\include examples/objectmodel.qdocinc
\include examples/layoutmanagement.qdocinc
* /
\endcode
QDoc renders this page \l{corefeatures.html} {as shown here}.
\target 2-argument-form
\section2 \\include filename snippet-identifier
It is a waste of time to make a separate \c .qdocinc file for every
QDoc include snippet you want to use in multiple places in the
documentation, especially given that you probably have to put the
copyright/license notice in every one of these files. So if you
have a large number of snippets to be included, you can put them all in a
single file if you want, and surround each one with:
\code
//! [snippet-id1]
QDoc commands and text...
//! [snippet-id1]
//! [snippet-id2]
More QDoc commands and text...
//! [snippet-id2]
\endcode
Then you can use the two-argument form of the command:
\code
\input examples/signalandslots.qdocinc snippet-id2
\input examples/objectmodel.qdocinc another-snippet-id
\endcode
It works as expected. The sequence of QDoc commands and text found
between the two tags with the same name as the second argument is
sent to the QDoc input stream. You can even have nested snippets.
\note Snippet identifiers work also within documentation comment
(\beginqdoc .. \endqdoc) blocks, so it's not necessary to use a
separate \c .qdocinc file. When processing a comment block, QDoc
removes any \c {//!} comment lines from the generated output.
\target meta-command
\section1 \\meta
The \\meta command is used for adding metadata to example documentation,
and when generating HTML output for specifying the \e maintainer(s) of a
C++ class.
The command has two arguments: the first argument is the name of the
metadata attribute, and the second argument is the
value for the attribute. Each argument should be enclosed in curly
brackets, as shown in this example:
\code
/ *!
\class QWidget
\brief The QWidget class is the base class of all user interface objects.
\ingroup basicwidgets
\meta {technology} {User Interface}
\meta {platform} {macOS 10.6}
\meta {platform} {MeeGo}
\meta {audience} {user}
\meta {audience} {programmer}
\meta {audience} {designer}
* /
\endcode
When running QDoc to generate HTML, the example above will have no
effect on the generated output.
\b {Example Metadata}
Another use for \\meta command is to include metadata (tags) in
\l {example-command}{\\example} documentation. By default, QDoc
generates example tags based on the example's \l {title-command}{\\title}
and module name. These tags are displayed in Qt Creator's Welcome mode,
helping users navigate the list of examples.
Additional tags can be created with \c {\\meta {tag} {tag1,[tag2,...]}}.
For example:
\badcode
/ *!
\example helloworld
\title Hello World Example
\meta {tag} {tutorial,basic}
* /
\endcode
This would result in the following tags: \e {tutorial,basic,hello,world}.
Common words such as \e example are ignored.
\b {Example Install Paths}
The \\meta command combined with an argument \c installpath specifies the
location of an installed example. This value overrides the one that is set
using the \c examplesinstallpath configuration variable.
\badcode
/ *!
\example helloworld
\title Hello World Example
\meta {installpath} {tutorials}
* /
\endcode
See also \l {examplesinstallpath}.
\target noautolist-command
\section1 \\noautolist
The \\noautolist command indicates that the annotated list of C++
classes or QML types, which is automatically generated at the
bottom of the C++ or QML module page should be omitted, because
the classes or types have been listed manually. This command can
also be used with the \l {group-command}{\\group} command to omit
the list of group members, when they are listed manually.
The command must stand on its own line. See \l {Qt Sensors QML Types} for
an example. The page is generated from \c {qtsensors5.qdoc}. There you will
find a QDoc comment containing the \c{\qmlmodule} command for the QtSensors
module. The same QDoc comment contains two \c {\annotated-list} commands to
list the QML types in two separate groups. The QML types have been divided
into these two groups because it makes more sense to list them this way than
it does to list them in a single alphabetical list. At the bottom of the
comment, \c {\noautolist} has been used to tell QDoc not to generate the
automatic annotated list.
This command was introduced in QDoc 5.6.
Since Qt 5.10, this command can be applied also to \l{example-command}
{\\example} documentation, where it causes the automatically generated
list of files and images belonging to an example project to be omitted.
\target omit-command
\section1 \\omit
The \\omit command and the corresponding \\endomit command
delimit parts of the documentation that you want QDoc to skip. For
example:
\code
/ *!
\table
\row
\li Basic Widgets
\li Basic GUI widgets such as buttons, comboboxes
and scrollbars.
\omit
\row
\li Component Model
\li Interfaces and helper classes for the Qt
Component Model.
\endomit
\row
\li Database Classes
\li Database related classes, e.g. for SQL databases.
\endtable
* /
\endcode
QDoc renders this as:
\raw HTML
<table align="center" cellpadding="2"
cellspacing="1" border="0">
<tr valign="top" bgcolor="#d0d0d0">
<td>Basic Widgets</td>
<td>Basic GUI widgets such as buttons, comboboxes
and scrollbars.</td>
</tr>
<tr valign="top" bgcolor="#c0c0c0">
<td>Database Classes</td>
<td>Database related classes, e.g. for SQL databases.</td>
</tr>
</table>
\endraw
\target raw-command
\section1 \\raw (avoid)
The \\raw command and the corresponding
\\endraw command delimit a block of raw mark-up language code.
\note Avoid using this command if possible. If you are trying to generate
special table or list behavior, try to get the behavior you want
using the \l {span-command} {\\span} and \l {div-command} {\\div}
commands in your \l {table-command} {\\table} or \l {list-command}
{\\list}.
The command takes an argument specifying the code's format.
Currently, the only supported format is HTML.
The \\raw command is useful if you want some special HTML effects
in your documentation.
\code
/ *!
Qt has some predefined QColor objects.
\raw HTML
<style type="text/css" id="colorstyles">
#color-blue { background-color: #0000ff; color: #ffffff }
#color-darkBlue { background-color: #000080; color: #ffffff }
#color-cyan { background-color: #00ffff; color: #000000 }
</style>
<p>
<tt id="color-blue">Blue(#0000ff)</tt>,
<tt id="color-darkBlue">dark blue(#000080)</tt> and
<tt id="color-cyan">cyan(#00ffff)</tt>.
</p>
\endraw
* /
\endcode
QDoc renders this as:
\quotation
Qt has some predefined QColor objects.
\raw HTML
<style type="text/css" id="colorstyles">
#color-blue { background-color: #0000ff; color: #ffffff }
#color-darkBlue { background-color: #000080; color: #ffffff }
#color-cyan { background-color: #00ffff; color: #000000 }
</style>
<p>
<tt id="color-blue">Blue(#0000ff)</tt>,
<tt id="color-darkBlue">dark blue(#000080)</tt> and
<tt id="color-cyan">cyan(#00ffff)</tt>.
</p>
\endraw
\endquotation
\note But you can achieve the exact same thing using QDoc
commands. In this case, all you have to do is include the color
styles in your style.css file. Then you can write:
\code
\tt {\span {id="color-blue"} {Blue(#0000ff)}},
\tt {\span {id="color-darkBlue"} {dark blue(#000080)}} and
\tt {\span {id="color-cyan"} {cyan(#00ffff)}}.
\endcode
...which is rendered as:
\tt {\span {id="color-blue"} {Blue(#0000ff)}},
\tt {\span {id="color-darkBlue"} {dark blue(#000080)}} and
\tt {\span {id="color-cyan"} {cyan(#00ffff)}}.
\target unicode-command
\section1 \\unicode
The \\unicode command allows you to insert an arbitrary Unicode
character in the document.
The command takes an argument specifying the character as an
integer. By default, base 10 is assumed, unless a '0x' or '0'
prefix is specified (for base 16 and 8, respectively). For
example:
\code
O G\unicode{0xEA}nio e as Rosas
\unicode 0xC0 table en famille avec 15 \unicode 0x20AC par jour
\unicode 0x3A3 \e{a}\sub{\e{i}}
\endcode
QDoc renders this as:
\quotation
O G\unicode{0xEA}nio e as Rosas
\unicode 0xC0 table en famille avec 15 \unicode 0x20AC par jour
\unicode 0x3A3 \e{a}\sub{\e{i}}
\endquotation
*/