8616 lines
282 KiB
Plaintext
8616 lines
282 KiB
Plaintext
/****************************************************************************
|
|
**
|
|
** Copyright (C) 2015 The Qt Company Ltd.
|
|
** Contact: http://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 http://www.qt.io/terms-conditions. For further
|
|
** information use the contact form at http://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: http://www.gnu.org/copyleft/fdl.html.
|
|
** $QT_END_LICENSE$
|
|
**
|
|
****************************************************************************/
|
|
|
|
/*!
|
|
\page index.html
|
|
\nextpage Introduction to QDoc
|
|
|
|
\title Table of Contents
|
|
|
|
\list
|
|
\o \l {Introduction to QDoc}
|
|
\o \l {Command Index}
|
|
\o \l {Topic Commands}
|
|
\o \l {Context Commands}
|
|
\list
|
|
\o \l {Document Navigation}
|
|
\o \l {Reporting Status}
|
|
\o \l {Thread Support}
|
|
\o \l {Relating Things}
|
|
\o \l {Grouping Things}
|
|
\o \l {Naming Things}
|
|
\endlist
|
|
\o \l{Markup Commands}
|
|
\list
|
|
\o \l {Text Markup}
|
|
\o \l {Document Structure}
|
|
\o \l {Including Code Inline}
|
|
\o \l {Including External Code}
|
|
\o \l {Creating Links}
|
|
\o \l {Including Images}
|
|
\o \l {Tables and Lists}
|
|
\o \l {Special Content}
|
|
\o \l {Miscellaneous}
|
|
\endlist
|
|
\o \l {The QDoc Configuration File}
|
|
\list
|
|
\o \l {Generic Configuration Variables}
|
|
\o \l {Creating Help Project Files}
|
|
\o \l {C++ Specific Configuration Variables}
|
|
\o \l {HTML Specific Configuration Variables}
|
|
\o \l {Supporting Derived Projects}
|
|
\o \l {Compatibility Issues}
|
|
\o \l {qt.qdocconf}
|
|
\o \l {minimum.qdocconf}
|
|
\o \l {Generating DITA XML Output}
|
|
\endlist
|
|
\endlist
|
|
|
|
*/
|
|
|
|
/*!
|
|
\page 01-qdoc-manual.html
|
|
\contentspage Table of Contents
|
|
\previouspage Table of Contents
|
|
\nextpage Command Index
|
|
|
|
\title Introduction to QDoc
|
|
|
|
QDoc is a tool used by Qt Developers to generate documentation for
|
|
software projects. It works by extracting \e {qdoc comments} from
|
|
project source files and then formatting these comments as HTML
|
|
pages or DITA XML documents, etc. QDoc finds qdoc comments in \c
|
|
{.cpp} files and in \c {.qdoc} files. QDoc does not look for qdoc
|
|
comments in \c {.h} files. A qdoc comment always begins with an
|
|
exclamation mark \bold{!} e.g.:
|
|
|
|
\code
|
|
/ *!
|
|
\class QObject
|
|
\brief The QObject class is the base class of all Qt objects.
|
|
|
|
\ingroup objectmodel
|
|
|
|
\reentrant
|
|
|
|
QObject is the heart of the Qt \l{Object Model}. The
|
|
central feature in this model is a very powerful mechanism
|
|
for seamless object communication called \l{signals and
|
|
slots}. You can connect a signal to a slot with connect()
|
|
and destroy the connection with disconnect(). To avoid
|
|
never ending notification loops you can temporarily block
|
|
signals with blockSignals(). The protected functions
|
|
connectNotify() and disconnectNotify() make it possible to
|
|
track connections.
|
|
|
|
QObjects organize themselves in \l {Object Trees &
|
|
Ownership} {object trees}. When you create a QObject with
|
|
another object as parent, the object will automatically
|
|
add itself to the parent's children() list. The parent
|
|
takes ownership of the object; i.e., it will automatically
|
|
delete its children in its destructor. You can look for an
|
|
object by name and optionally type using findChild() or
|
|
findChildren().
|
|
|
|
Every object has an objectName() and its class name can be
|
|
found via the corresponding metaObject() (see
|
|
QMetaObject::className()). You can determine whether the
|
|
object's class inherits another class in the QObject
|
|
inheritance hierarchy by using the inherits() function.
|
|
|
|
....
|
|
* /
|
|
\endcode
|
|
|
|
From the qdoc comment above, QDoc generates the now famous HTML
|
|
page \l {http://doc.trolltech.com/4.7/qobject.html#details}
|
|
{QObject Class Reference}.
|
|
|
|
This manual explains how to use the QDoc commands in qdoc comments
|
|
to embed good documentation in your source files. It also explains
|
|
how to make a \l {The QDoc Configuration File} {QDoc configuration
|
|
file}, which you will pass to QDoc on the command line.
|
|
|
|
\section1 Running QDoc
|
|
|
|
The current name of the QDoc program is \c {qdoc3}. To run qdoc3
|
|
from the command line, give it the name of a configuration file:
|
|
|
|
\quotation
|
|
\c {$ ../../bin/qdoc3 ./config.qdocconf}
|
|
\endquotation
|
|
|
|
QDoc recognizes the \c {.qdocconf} suffix as a \l{The QDoc
|
|
Configuration File} {QDoc configuration file}. The configuration
|
|
file is where you tell QDoc where to find the project source
|
|
files, header files, and \c {.qdoc} files. It is also where you
|
|
tell QDoc what kind of output to generate (HTML, DITA XML,...),
|
|
and where to put the generated documentation. The configuration
|
|
file also contains other information for QDoc.
|
|
|
|
See \l{The QDoc Configuration File} for a instructions on how to
|
|
build a Qdoc configuration file.
|
|
|
|
\section1 How QDoc Works
|
|
|
|
QDoc begins by reading the configuarion file you specified on the
|
|
command line. It stores all the variables from the configuration
|
|
file for later use. One of the first variables it uses is \c
|
|
{outputformats}. This variable tells QDoc which output generators
|
|
it will run. The default value is \e {HTML}, so if you don't set
|
|
\c {outputformats} in your configuration file, QDoc will generate
|
|
HTML output. That's usually what you will want anyway, but you can
|
|
also specify \e {DITAXML} to get DITA XML output instead.
|
|
|
|
Next, QDoc uses the values of the \l
|
|
{22-qdoc-configuration-generalvariables.html#headerdirs-variable}
|
|
{headerdirs} variable and/or the \l
|
|
{22-qdoc-configuration-generalvariables.html#headers-variable}
|
|
{headers} variable to find and parse all the header files for your
|
|
project. QDoc does \e not scan header files for qdoc comments. It
|
|
parses the header files to build a master tree of all the items
|
|
that should be documented (i.e. the items that QDoc should find
|
|
qdoc comments for).
|
|
|
|
After parsing all the header files and building the master tree of
|
|
items to be documented, QDoc uses the value of the \l
|
|
{22-qdoc-configuration-generalvariables.html#sourcedirs-variable}
|
|
{sourcedirs} variable and/or the value of the \l
|
|
{22-qdoc-configuration-generalvariables.html#sources-variable}
|
|
{sources} variable to find and parse all the \c {.cpp} and \c
|
|
{.qdoc} files for your project. These are the files QDoc scans for
|
|
\e {qdoc comments}. Remember that a qdoc comment begins with
|
|
an exclamation mark, i.e. \bold {/*!} .
|
|
|
|
For each qdoc comment it finds, it searches the master tree for
|
|
the item where the documentation belongs. The it interprets the
|
|
qdoc commands in the comment and stores the interpreted commands
|
|
and the comment text in the tree node for the item.
|
|
|
|
Finally, QDoc traverses the master tree. For each node, if the
|
|
node has stored documentation, QDoc calls the output generator
|
|
specified by the \c {outputformats} variable to format and write
|
|
the documentation in the directory specified in the configuration
|
|
file in the \l
|
|
{22-qdoc-configuration-generalvariables.html#outputdir-variable}
|
|
{outputdir} variable.
|
|
|
|
\section1 Command Types
|
|
|
|
QDoc interprets three types of commands:
|
|
|
|
\list
|
|
\o \l {Topic Commands}
|
|
\o \l {Context Commands}
|
|
\o \l {Markup Commands}
|
|
\endlist
|
|
|
|
Topic commands identify the elememt you are documenting, e.g. a C++
|
|
class, function, or type, an example, or an extra page of text
|
|
that doesn't map to an underlying C++ elememnt.
|
|
|
|
Context commands tell QDoc how the element being documented
|
|
relates to other documented elememnts, e.g. next and previous page
|
|
links or inclusion in page groups or library modules. Context
|
|
commands can also provide information about the documented element
|
|
that QDoc can't get from the source files, e.g. whether the
|
|
element is thread-safe, an overloaded or reimplemented function,
|
|
or that it has been deprecated.
|
|
|
|
Markup commands tell QDoc how text and image elements in the
|
|
document should be rendered, or about the document's outline
|
|
structure.
|
|
*/
|
|
|
|
/*!
|
|
\page 03-qdoc-commands-markup.html
|
|
\contentspage Table of Contents
|
|
\previouspage Naming Things
|
|
\nextpage Text Markup
|
|
|
|
\title Markup Commands
|
|
|
|
The markup commands indicate the generated documentation's visual
|
|
appearance and logical structure.
|
|
|
|
\list
|
|
\o \l {04-qdoc-commands-textmarkup.html#a-command} {\\a}
|
|
\o \l {11-qdoc-commands-specialcontent.html#abstract-command} {\\abstract}
|
|
\o \l {06-qdoc-commands-includecodeinline.html#badcode-command} {\\badcode}
|
|
\o \l {04-qdoc-commands-textmarkup.html#bold-command} {\\bold}
|
|
\o \l {11-qdoc-commands-specialcontent.html#brief-command} {\\brief}
|
|
\o \l {04-qdoc-commands-textmarkup.html#c-command} {\\c}
|
|
\o \l {09-qdoc-commands-includingimages.html#caption-command} {\\caption}
|
|
\o \l {05-qdoc-commands-documentstructure.html#chapter-command} {\\chapter}
|
|
\o \l {06-qdoc-commands-includecodeinline.html#code-command} {\\code}
|
|
\o \l {07-0-qdoc-commands-includingexternalcode.html#codeline-command} {\\codeline}
|
|
\o \l {04-qdoc-commands-textmarkup.html#div-command} {\\div} \span {class="newStuff"} {(new)}
|
|
\o \l {07-0-qdoc-commands-includingexternalcode.html#dots-command} {\\dots}
|
|
\o \l {12-0-qdoc-commands-miscellaneous.html#else-command} {\\else}
|
|
\o \l {12-0-qdoc-commands-miscellaneous.html#endif-command} {\\endif}
|
|
\o \l {12-0-qdoc-commands-miscellaneous.html#expire-command} {\\expire}
|
|
\o \l {11-qdoc-commands-specialcontent.html#footnote-command} {\\footnote}
|
|
\o \l {12-0-qdoc-commands-miscellaneous.html#generatelist-command} {\\generatelist}
|
|
\o \l {10-qdoc-commands-tablesandlists.html#header-command} {\\header}
|
|
\o \l {04-qdoc-commands-textmarkup.html#i-command} {\\i}
|
|
\o \l {12-0-qdoc-commands-miscellaneous.html#if-command} {\\if}
|
|
\o \l {09-qdoc-commands-includingimages.html#image-command} {\\image}
|
|
\o \l {12-0-qdoc-commands-miscellaneous.html#include-command} {\\include}
|
|
\o \l {12-0-qdoc-commands-miscellaneous.html#include-command} {\\input}
|
|
\o \l {09-qdoc-commands-includingimages.html#inlineimage-command} {\\inlineimage}
|
|
\o \l {08-qdoc-commands-creatinglinks.html#keyword-command} {\\keyword}
|
|
\o \l {08-qdoc-commands-creatinglinks.html#l-command} {\\l}
|
|
\o \l {11-qdoc-commands-specialcontent.html#legalese-command} {\\legalese}
|
|
\o \l {10-qdoc-commands-tablesandlists.html#list-command} {\\list}
|
|
\o \l {12-0-qdoc-commands-miscellaneous.html#meta-command} {\\meta}
|
|
\o \l {06-qdoc-commands-includecodeinline.html#newcode-command} {\\newcode}
|
|
\o \l {10-qdoc-commands-tablesandlists.html#o-command} {\\o}
|
|
\o \l {06-qdoc-commands-includecodeinline.html#oldcode-command} {\\oldcode}
|
|
\o \l {12-0-qdoc-commands-miscellaneous.html#omit-command} {\\omit}
|
|
\o \l {05-qdoc-commands-documentstructure.html#part-command} {\\part}
|
|
\o \l {07-0-qdoc-commands-includingexternalcode.html#printline-command} {\\printline}
|
|
\o \l {07-0-qdoc-commands-includingexternalcode.html#printto-command} {\\printto}
|
|
\o \l {07-0-qdoc-commands-includingexternalcode.html#printuntil-command} {\\printuntil}
|
|
\o \l {11-qdoc-commands-specialcontent.html#quotation-command} {\\quotation}
|
|
\o \l {07-0-qdoc-commands-includingexternalcode.html#quotefile-command} {\\quotefile}
|
|
\o \l {07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command} {\\quotefromfile}
|
|
\o \l {12-0-qdoc-commands-miscellaneous.html#raw-command} {\\raw} \span {class="newStuff"} {(deprecated)}
|
|
\o \l {10-qdoc-commands-tablesandlists.html#row-command} {\\row}
|
|
\o \l {08-qdoc-commands-creatinglinks.html#sa-command} {\\sa}
|
|
\o \l {05-qdoc-commands-documentstructure.html#sectionOne-command} {\\section1}
|
|
\o \l {05-qdoc-commands-documentstructure.html#sectionTwo-command} {\\section2}
|
|
\o \l {05-qdoc-commands-documentstructure.html#sectionThree-command} {\\section3}
|
|
\o \l {05-qdoc-commands-documentstructure.html#sectionFour-command} {\\section4}
|
|
\o \l {07-0-qdoc-commands-includingexternalcode.html#skipline-command} {\\skipline}
|
|
\o \l {07-0-qdoc-commands-includingexternalcode.html#skipto-command} {\\skipto}
|
|
\o \l {07-0-qdoc-commands-includingexternalcode.html#skipuntil-command} {\\skipuntil}
|
|
\o \l {07-0-qdoc-commands-includingexternalcode.html#snippet-command} {\\snippet}
|
|
\o \l {04-qdoc-commands-textmarkup.html#span-command} {\\span} \span {class="newStuff"} {(new)}
|
|
\o \l {04-qdoc-commands-textmarkup.html#sub-command} {\\sub}
|
|
\o \l {04-qdoc-commands-textmarkup.html#sup-command} {\\sup}
|
|
\o \l {10-qdoc-commands-tablesandlists.html#table-command} {\\table}
|
|
\o \l {11-qdoc-commands-specialcontent.html#tableofcontents-command} {\\tableofcontents}
|
|
\o \l {08-qdoc-commands-creatinglinks.html#target-command} {\\target}
|
|
\o \l {04-qdoc-commands-textmarkup.html#tt-command} {\\tt}
|
|
\o \l {04-qdoc-commands-textmarkup.html#underline-command} {\\underline}
|
|
\o \l {12-0-qdoc-commands-miscellaneous.html#raw-command} {\\unicode}
|
|
\o \l {11-qdoc-commands-specialcontent.html#warning-command} {\\warning}
|
|
\o \l {04-qdoc-commands-textmarkup.html#backslash-command} {\\\\}
|
|
\endlist
|
|
*/
|
|
|
|
/*!
|
|
\page 04-qdoc-commands-textmarkup.html
|
|
\contentspage Table of Contents
|
|
\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
|
|
\bold {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
|
|
|
|
You can enclose the formal parameter name in curly brackets, if
|
|
you want to, but it isn't necessary.
|
|
|
|
\target c-command
|
|
\section1 \\c (code font)
|
|
|
|
The \\c command is used for rendering variable names, user-defined
|
|
class names, and C++ keywords (e.g. \c int and \c for) in the code
|
|
font.
|
|
|
|
The command renders its argument using a typewriter 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 that is 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, i.e. it 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 \span {class="newStuff"} {(new)}
|
|
|
|
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 ultimately 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
|
|
|
|
If qdoc is generating DITA XML, it will translate the commands to:
|
|
|
|
\code
|
|
<sectiondiv outputclass="float-right">
|
|
<p>
|
|
<fig>
|
|
<image href="images/qml-column.png" placement="inline"/>
|
|
</fig>
|
|
</p>
|
|
</sectiondiv>
|
|
\endcode
|
|
|
|
Your DITA XML publishing program must then recognize the \e
|
|
{outputclass} attribute value.
|
|
|
|
\note The \bold {\\div} command can be nested.
|
|
|
|
Below is 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
|
|
\o \l{Getting Started Guides} {Getting started}
|
|
\o \l{Installation} {Installation}
|
|
\o \l{how-to-learn-qt.html} {How to learn Qt}
|
|
\o \l{tutorials.html} {Tutorials}
|
|
\o \l{Qt Examples} {Examples}
|
|
\o \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 4.7 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
|
|
\o \l{Getting Started Guides} {Getting started}
|
|
\o \l{Installation} {Installation}
|
|
\o \l{how-to-learn-qt.html} {How to learn Qt}
|
|
\o \l{tutorials.html} {Tutorials}
|
|
\o \l{Qt Examples} {Examples}
|
|
\o \l{qt4-7-intro.html} {What's new in Qt 4.7}
|
|
\endlist
|
|
\enddiv
|
|
\enddiv
|
|
\enddiv
|
|
|
|
When generating DITA XML, qdoc outputs the nested \e {div} commands as:
|
|
|
|
\code
|
|
<sectiondiv outputclass="indexbox guide">
|
|
<sectiondiv outputclass="heading">
|
|
<p>Qt Developer Guide</p>
|
|
</sectiondiv>
|
|
<sectiondiv outputclass="indexboxcont indexboxbar">
|
|
<sectiondiv outputclass="section indexIcon"/>
|
|
<sectiondiv outputclass="section">
|
|
<p>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.
|
|
</p>
|
|
</sectiondiv>
|
|
<sectiondiv outputclass="section sectionlist">
|
|
<ul>
|
|
<li>
|
|
<xref href="gettingstarted.xml#id-606ee7a8-219b-47b7-8f94-91bc8c76e54c">Getting started</xref>
|
|
</li>
|
|
<li>
|
|
<xref href="installation.xml#id-075c20e2-aa1e-4f88-a316-a46517e50443">Installation</xref>
|
|
</li>
|
|
<li>
|
|
<xref href="how-to-learn-qt.xml#id-49f509b5-52f9-4cd9-9921-74217b9a5182">How to learn Qt</xref>
|
|
</li>
|
|
<li>
|
|
<xref href="tutorials.xml#id-a737f955-a904-455f-b4aa-0dc69ed5a64f">Tutorials</xref>
|
|
</li>
|
|
<li>
|
|
<xref href="all-examples.xml#id-98d95159-d65b-4706-b08f-13d80080448d">Examples</xref>
|
|
</li>
|
|
<li>
|
|
<xref href="qt4-7-intro.xml#id-519ae0e3-4242-4c2a-b2be-e05d1e95f177">What's new in Qt 4.7</xref>
|
|
</li>
|
|
</ul>
|
|
</sectiondiv>
|
|
</sectiondiv>
|
|
</sectiondiv>
|
|
\endcode
|
|
|
|
Your DITA XML publishing program must recognize the values of the
|
|
\e {outputclass} attribute.
|
|
|
|
See also \l {span-command} {\\span}.
|
|
|
|
\target span -command
|
|
\section1 \\span \span {class="newStuff"} {(new)}
|
|
|
|
The \\span command is for applying special formatting
|
|
attributes 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 is used as the formatting attribute(s) of the tag
|
|
that is ultimately 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
|
|
\o \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14
|
|
\o \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15
|
|
\o \span {class="variableName"} {constComplex1} in globals.cpp at line 16
|
|
\o \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
|
|
\o \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14
|
|
\o \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15
|
|
\o \span {class="variableName"} {constComplex1} in globals.cpp at line 16
|
|
\o \span {class="variableName"} {constComplex2} in globals.cpp at line 17
|
|
\endlist
|
|
|
|
\note The \bold 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 {i-command} {\\i}, \l {bold-command} {\\bold} and \l
|
|
{underline-command} {\\underline}).
|
|
|
|
\code
|
|
/ *!
|
|
After \c setupUi() populates the main container with
|
|
child widgets it 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 \c setupUi() populates the main container with
|
|
child widgets it 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 bold-command
|
|
\section1 \\bold
|
|
|
|
The \\bold command renders its argument in bold font.
|
|
|
|
\code
|
|
/ *!
|
|
This is regular text; \bold {this text is
|
|
rendered using the \\bold command}.
|
|
* /
|
|
\endcode
|
|
|
|
QDoc renders this as:
|
|
|
|
\quotation
|
|
This is regular text; \bold {this text is rendered using
|
|
the \\bold command}.
|
|
\endquotation
|
|
|
|
\target i-command
|
|
\section1 \\i (italics)
|
|
|
|
The \\i command renders its argument in italics.
|
|
|
|
\warning If \\i doesn't work and you get some strange error
|
|
meesages from qdoc3 about using \\o outside of tables and lists,
|
|
use \bold{\\e} for italics instead of \\i. For more information,
|
|
see the relevant explanation in the section on \l
|
|
{26-qdoc-commands-compatibility.html#i-versus-e} {compatibility
|
|
issues}.
|
|
|
|
If the argument contains spaces or other punctuation, enclose the
|
|
argument in curly brackets.
|
|
|
|
\code
|
|
/ *!
|
|
Here, we render \i {a few words} in italic.
|
|
* /
|
|
\endcode
|
|
|
|
QDoc renders this as:
|
|
|
|
\quotation
|
|
Here, we render \e {a few words} in italic.
|
|
\endquotation
|
|
|
|
If you want to use other QDoc commands within an argument that
|
|
contains spaces, you always need to enclose the argument with
|
|
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: \i 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 underline-command
|
|
\section1 \\underline
|
|
|
|
The \\underline command renders its argument underlined.
|
|
|
|
\code
|
|
/ *!
|
|
The \underline {F}ile menu gives the users the possibility
|
|
to open, and edit, an existing file, 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 open, and edit, an existing file, 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 single backslash.
|
|
|
|
QDoc commands always start with a backslash alone. To display an
|
|
actual backslash in the text you need to type two of the kind. If
|
|
you want to display two backslashes, you need to type four, and so
|
|
forth.
|
|
|
|
\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 typewriter 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 typewriter 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 typewriter font,
|
|
like this: \c {C:\windows\home\}.
|
|
\endquotation
|
|
|
|
*/
|
|
|
|
/*!
|
|
\page 05-qdoc-commands-documentstructure.html
|
|
\previouspage Text Markup
|
|
\contentspage Table of Contents
|
|
\nextpage Including Code Inline
|
|
|
|
\title Document Structure
|
|
|
|
The document structuring commands are for dividing your document
|
|
into sections. QDoc supports six kinds of sections: \c \part, \c
|
|
\chapter, \c \section1, \c \section2, \c \section3 and \c
|
|
\section4. The \c \section1..4 commands are the most useful. The
|
|
correspond to the traditional section, subsection, etc used in
|
|
outlining.
|
|
|
|
\target part-command
|
|
\section1 \\part
|
|
|
|
The \\part command is intended for use in a large document, like a
|
|
book.
|
|
|
|
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 six levels of sections in QDoc: \c \part, \c
|
|
\chapter, \c \section1, \c \section2, \c \section3 and \c
|
|
\section4. \c \section1 to \c \section4 correspond to the
|
|
traditional section, subsection, subsubsection and
|
|
subsubsubsection.
|
|
|
|
There is a strict ordering of the section units:
|
|
|
|
\code
|
|
part
|
|
|
|
|
chapter
|
|
|
|
|
section1
|
|
|
|
|
section2
|
|
|
|
|
section3
|
|
|
|
|
section4
|
|
\endcode
|
|
|
|
For example, a \c section1 unit can only appear as the top level
|
|
section or inside a \c chapter unit. Skipping a section unit, for
|
|
example from \c part to \c section1, is not allowed.
|
|
|
|
You can \e begin with either of the three: \c part, \c chapter or
|
|
\c section1.
|
|
|
|
|
|
\code
|
|
/ *!
|
|
\part Basic Qt
|
|
|
|
This is the first part.
|
|
|
|
|
|
\chapter Getting Started
|
|
|
|
This is the first part's first chapter.
|
|
|
|
|
|
\section1 Hello Qt
|
|
|
|
This is the first chapter's first section.
|
|
|
|
|
|
\section1 Making Connections
|
|
|
|
This is the first chapter's second section.
|
|
|
|
|
|
\section1 Using the Reference Documentation
|
|
|
|
This is the first chapter's third section.
|
|
|
|
|
|
\chapter Creating Dialogs
|
|
|
|
This is the first part's second chapter.
|
|
|
|
|
|
\section1 Subclassing QDialog
|
|
|
|
This is the second chapter's first section.
|
|
|
|
...
|
|
|
|
|
|
\part Intermediate Qt
|
|
|
|
This is the second part.
|
|
|
|
|
|
\chapter Layout Management
|
|
|
|
This is the second part's first chapter.
|
|
|
|
|
|
\section1 Basic Layouts
|
|
|
|
This is the first chapter's first section.
|
|
|
|
...
|
|
* /
|
|
\endcode
|
|
|
|
QDoc renders this as:
|
|
|
|
\quotation
|
|
\raw HTML
|
|
<a name="Basic Qt">
|
|
<h1>Basic Qt</h1>
|
|
</a>
|
|
<p>This is the first part.</p>
|
|
|
|
<a name="Getting started">
|
|
<h2>Getting Started</h2>
|
|
</a>
|
|
This is the first part's first chapter.</p>
|
|
|
|
<a name="Hello Qt">
|
|
<h3>Hello Qt</h3>
|
|
</a>
|
|
<p>This is the first chapter's first section.</p>
|
|
|
|
<a name="Making Connections">
|
|
<h3>Making Connections</h3>
|
|
</a>
|
|
<p>This is the first chapter's second section.</p>
|
|
|
|
<a name="Using the Reference Documentation">
|
|
<h3>Using the Reference Documentation</h3>
|
|
</a>
|
|
<p>This is the first chapter's third section.</p>
|
|
|
|
<a name="Creating Dialogs">
|
|
<h2>Creating Dialogs</h2>
|
|
</a>
|
|
<p>This is the first part's second chapter.</p>
|
|
|
|
<a name="Subclassing QDialog">
|
|
<h3>Subclassing QDialog</h3>
|
|
</a>
|
|
<p>This is the second chapter's first section.</p>
|
|
|
|
...
|
|
|
|
<a name="Intermediate Qt">
|
|
<h1>Intermediate Qt</h1>
|
|
</a>
|
|
<p>This is the second part.</p>
|
|
|
|
<a name="Layout Management">
|
|
<h2>Layout Management</h2>
|
|
</a>
|
|
<p>This is the second part's first chapter.</p>
|
|
|
|
<a name="Basic Layouts">
|
|
<h3>Basic Layouts</h3>
|
|
</a>
|
|
<p>This is the first chapter's first section.</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 righthand corner of the page.
|
|
|
|
\target chapter-command
|
|
\section1 \\chapter
|
|
|
|
The \\chapter command is intended for use in
|
|
larger documents, and divides the document into chapters.
|
|
|
|
See \l{part} {\\part} for an explanation of the various
|
|
section units, command argument and rendering.
|
|
|
|
\target sectionOne-command
|
|
\section1 \\section1
|
|
|
|
The \\section1 command starts a new section.
|
|
|
|
See \l{part} {\\part} 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{part} {\\part} 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{part} {\\part} 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{part} {\\part} for an explanation of the various
|
|
section units, command argument and rendering.
|
|
|
|
*/
|
|
|
|
/*!
|
|
\page 06-qdoc-commands-includecodeinline.html
|
|
\previouspage Document Structure
|
|
\contentspage Table of Contents
|
|
\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.
|
|
|
|
\bold{Note:} Although all 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
|
|
the code font.
|
|
|
|
When processing any of the \\code, \l {badcode-command}
|
|
{\\badcode}, \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. For that reason the recommended style is to use 8
|
|
spaces for the verbatim code contained within these commands
|
|
|
|
\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.
|
|
|
|
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
|
|
{07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command}
|
|
{\\quotefromfile}, \l {badcode-command} {\\badcode}, \l
|
|
{newcode-command} {\\newcode} and \l {oldcode-command}
|
|
{\\oldcode}.
|
|
|
|
\target badcode-command
|
|
\section1 \\badcode
|
|
|
|
The \\badcode and \\endcode commands delimit a snippet of code
|
|
that doesn't compile or is wrong for some other reason.
|
|
|
|
The \\badcode command is similar to the \l {code-command} {\\code}
|
|
command, but it renders the code snippet using a grey font instead
|
|
of black.
|
|
|
|
Like the \l {code-command} {\\code} command, this command begins
|
|
its code snippet on a new line rendered in the code font and with
|
|
the standard indentation.
|
|
|
|
\code
|
|
/ *!
|
|
The statement below is rendered using the
|
|
regular \\code command:
|
|
|
|
\code
|
|
statusbar()->message(tr("Host %1 found").arg(hostName));
|
|
\ endcode
|
|
|
|
While the following statement is rendered using
|
|
the \\badcode command:
|
|
|
|
\badcode
|
|
statusbar()->message(tr("Host" + hostName + " found"));
|
|
\ endcode
|
|
* /
|
|
\endcode
|
|
|
|
QDoc renders this as:
|
|
|
|
\quotation
|
|
The statement below is rendered using the
|
|
regular \\code command:
|
|
|
|
\code
|
|
statusbar()->message(tr("Host %1 found").arg(hostName));
|
|
\endcode
|
|
|
|
While the following statement is rendered using
|
|
the \\badcode command:
|
|
|
|
\badcode
|
|
statusbar()->message(tr("Host" + hostName + " found"));
|
|
\endcode
|
|
\endquotation
|
|
|
|
Other QDoc commands are disabled within \\badcode... \\endcode,
|
|
and the special character '\\' is accepted and rendered like the
|
|
rest of the code.
|
|
|
|
See also \l {code-command} {\\code}, \l {newcode-command}
|
|
{\\newcode} and \l {oldcode-command} {\\oldcode}.
|
|
|
|
\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, is
|
|
a convenience combination of the \l {code-command} {\\code} and \l
|
|
{badcode-command} {\\badcode} commands: The combination provides a
|
|
text relating the two code snippets to each other. The command
|
|
requires a preceding \\oldcode statement.
|
|
|
|
Like the \l {code-command} {\\code} and \l {badcode-command}
|
|
{\\badcode} commands, the \\newcode command renders its code on a
|
|
new line in the documentation using a typewriter 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} and \l {badcode-command} {\\badcode}.
|
|
|
|
\target qml-command
|
|
\section1 \\qml \span {class="newStuff"} {(new)}
|
|
|
|
The \\qml and \\endqml commands enclose a snippet of QML source
|
|
code. Currently, QDoc handles \\qml and \\endqml exactly the same
|
|
as \\code and \\endcode.
|
|
|
|
\code
|
|
/ *!
|
|
\qml
|
|
import QtQuick 1.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 1.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
|
|
*/
|
|
|
|
/*!
|
|
\page 07-0-qdoc-commands-includingexternalcode.html
|
|
\previouspage Including Code Inline
|
|
\contentspage Table of Contents
|
|
\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.
|
|
|
|
\bold{Note:} Although all 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 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
|
|
typewriter 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
|
|
|
|
(\l {Example File} {The complete example file...})
|
|
|
|
QDoc remembers which file it's quoting, and the current position
|
|
within that file (see \l {file} {\\printline} for more
|
|
information). There is no need to "close" the file.
|
|
|
|
Earlier we called this command \\quotefile. For more information,
|
|
see the \l
|
|
{26-qdoc-commands-compatibility.html#quotefromfile-versus-quotefile}
|
|
{compatibility} section.
|
|
|
|
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 souce 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 typewriter 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
|
|
|
|
(\l {Example File} {The complete example file...})
|
|
|
|
\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 {regular expression}.
|
|
|
|
\code
|
|
/ *!
|
|
\quotefromfile widgets/scribble/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 widgets/scribble/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 typewriter 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
|
|
|
|
(\l {Example File} {The complete example file...})
|
|
|
|
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.
|
|
|
|
The lines from the source file are rendered in a separate
|
|
paragraph, using a typewriter 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://qt.nokia.com/doc/4.0/qapplication} {QApplication}
|
|
object using the \c argc and \c argv parameters, then we
|
|
create a \l
|
|
{http://qt.nokia.com/doc/4.0/qpushbutton} {QPushButton}.
|
|
\endquotation
|
|
|
|
(\l {Example File} {The complete example file...})
|
|
|
|
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
|
|
|
|
(\l {Example File} {The complete example file...})
|
|
|
|
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
|
|
|
|
(\l {Example File} {The complete example file...})
|
|
|
|
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
|
|
|
|
(\l {Example File} {The complete example file...})
|
|
|
|
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 typewriter 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 }
|
|
|
|
(\l {Example File} {The complete example file...})
|
|
|
|
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 are 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 (e.g., \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:
|
|
|
|
\dots
|
|
\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
|
|
\dots
|
|
|
|
\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 07-1-example.html
|
|
\previouspage Including External Code
|
|
\contentspage Table of Contents
|
|
|
|
\title Example File
|
|
|
|
\quotefile examples/main.cpp
|
|
*/
|
|
|
|
/*!
|
|
\page 08-qdoc-commands-creatinglinks.html
|
|
\previouspage Including External Code
|
|
\contentspage Table of Contents
|
|
\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 target} {link text}
|
|
\endcode
|
|
|
|
\code
|
|
/ *!
|
|
Read the \l {http://qt.nokia.com/doc/4.0/}
|
|
{Qt's Reference Documentation} carefully.
|
|
* /
|
|
\endcode
|
|
|
|
QDoc renders this as:
|
|
|
|
\quotation
|
|
Read the \l {http://qt.nokia.com/doc/4.0/}
|
|
{Qt's Reference 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 kinds of links:
|
|
|
|
\list
|
|
|
|
\o \c {\l QWidget} - The name of a class documented with the \l
|
|
{class-command} {\\class} command.
|
|
|
|
\o \c {\l QWidget::sizeHint()} - The name of a member function,
|
|
documented with or without an \l {fn-command} {\\fn} command.
|
|
|
|
\o \c {\l <QtGlobal>} - The subject of a \l {headerfile-command}
|
|
{\\headerfile} command.
|
|
|
|
\o \c {\l widgets/wiggly} - The relative path used in an \l
|
|
{example-command} {\\example} command.
|
|
|
|
\o \c {\l {QWidget Class Reference}} - The title used in a
|
|
\l {title-command} {\\title} command.
|
|
|
|
\o \c {\l {Introduction to QDoc}}- The text from one of the
|
|
\l{part-command} {\\part}, \l{chapter} {\\chapter} or \l
|
|
{sectionOne-command} {\\section} commands.
|
|
|
|
\o \c {\l fontmatching} - The argument of a \l {target-command}
|
|
{\\target} command.
|
|
|
|
\o \c {\l {Shared Classes}} - A keyword named in a \l
|
|
{keyword-command} {\\keyword} command.
|
|
|
|
\o \c {\l network.html} - The file name used in a \l
|
|
{page-command} {\\page} command.
|
|
|
|
\o \c {\l http://www.trolltech.com/} - A URL.
|
|
|
|
\endlist
|
|
|
|
QDoc also tries to make a link out of any words that don't
|
|
resemble any normal English words, 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
|
|
\o \c {\l {QWidget::} {sizeHint()}}
|
|
\endlist
|
|
|
|
QDoc renders this as:
|
|
|
|
\quotation
|
|
\l {QWidget::} {sizeHint()}
|
|
\endquotation
|
|
|
|
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
|
|
\o \c property()
|
|
\o \c setProperty()
|
|
\o \c isProperty()
|
|
\o \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
|
|
\bold {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 cammand. 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 two ways:
|
|
|
|
\list
|
|
\o \c {\l {capturing parentheses}} (from within the same qdoc comment)
|
|
\o \c {\l qregexp.html#capturing-parentheses} (from elsewhere in the same document)
|
|
\endlist
|
|
|
|
\note The brackets in the link example are required because the
|
|
target name contains spaces.
|
|
|
|
From other documents, the target name can be linked this way:
|
|
|
|
\list
|
|
\o \c {\l http://www.trolltech.com/4.0/doc/html/qregexp.html#capturing-parentheses}
|
|
\endlist
|
|
|
|
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, but stronger. 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
|
|
\mainclass
|
|
|
|
\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 with:
|
|
|
|
\code
|
|
/ *!
|
|
When a string is surrounded by slashes, it is
|
|
interpreted as a \l {regular expression}.
|
|
* /
|
|
\endcode
|
|
|
|
QDoc renders this as:
|
|
|
|
\quotation
|
|
When a string is surrounded by slashes, it's
|
|
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
|
|
\contentspage Table of Contents
|
|
\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 \\image command replaces the old \\img command. For more
|
|
information, see the \l
|
|
{26-qdoc-commands-compatibility.html#image-versus-img}
|
|
{compatibility} section.
|
|
|
|
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 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 by Trolltech is a C++ toolkit for cross-platform GUI
|
|
application development.
|
|
|
|
\image happyguy.jpg "Happy guy"
|
|
|
|
Qt provides single-source portability across Microsoft
|
|
Windows, Mac OS X, Linux, and all major commercial Unix
|
|
variants. It is also available for embedded devices.
|
|
* /
|
|
\endcode
|
|
|
|
QDoc renders this as:
|
|
|
|
\quotation
|
|
Qt by Trolltech is a C++ toolkit for cross-platform GUI
|
|
application development.
|
|
|
|
\image happyguy.jpg image "Happy guy"
|
|
|
|
Qt provides single-source portability across Microsoft
|
|
Windows, Mac OS X, 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
|
|
\o \inlineimage happy.gif Oh so happy!
|
|
\o \inlineimage happy.gif Oh so happy!
|
|
\o \inlineimage happy.gif Oh so happy!
|
|
\endlist
|
|
* /
|
|
\endcode
|
|
|
|
QDoc renders this as:
|
|
|
|
\list 1
|
|
\o \inlineimage happy.gif Oh so happy!
|
|
\o \inlineimage happy.gif Oh so happy!
|
|
\o \inlineimage happy.gif Oh so happy!
|
|
\endlist
|
|
|
|
Her eis an example of including inline images in a table:
|
|
|
|
\code
|
|
/ *!
|
|
\table
|
|
\header
|
|
\o Trolltech
|
|
\o Trolltech
|
|
\row
|
|
\o \inlineimage happy.gif Oh so happy!
|
|
\o \inlineimage happy.gif Oh so happy!
|
|
\row
|
|
\o \inlineimage happy.gif Oh so happy!
|
|
\o \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>Trolltech</th>
|
|
<th>Trolltech</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 Training by Trolltech
|
|
The Qt Programming course is offered as a
|
|
five day Open Enrollment Course. The classes
|
|
are open to the public.While 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 Training by Trolltech
|
|
The Qt Programming course is offered as a
|
|
five day Open Enrollment Course. The classes
|
|
are open to the public.While 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
|
|
\o \image windowsvista-pushbutton.png
|
|
\caption The QPushButton widget provides a command button.
|
|
\o \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
|
|
\o \image windowsvista-pushbutton.png
|
|
\caption The QPushButton widget provides a command button.
|
|
\o \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
|
|
\contentspage Table of Contents
|
|
\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, which
|
|
starts with a \l {o-command} {\\o} command. There is also a \l
|
|
{header-command} {\\header} command which is a special kind of row
|
|
with a special formatting.
|
|
|
|
\code
|
|
/ *!
|
|
\table
|
|
\header
|
|
\o Qt Core Feature
|
|
\o Brief Description
|
|
\row
|
|
\o \l {Signal and Slots}
|
|
\o Signals and slots are used for communication
|
|
between objects.
|
|
\row
|
|
\o \l {Layout Management}
|
|
\o The Qt layout system provides a simple
|
|
and powerful way of specifying the layout
|
|
of child widgets.
|
|
\row
|
|
\o \l {Drag and Drop}
|
|
\o 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://qt.nokia.com/doc/4.0/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://qt.nokia.com/doc/4.0/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://qt.nokia.com/doc/4.0/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
|
|
\o {3,1} This header cell spans three columns
|
|
but only one row.
|
|
\row
|
|
\o {2, 1} This table cell spans two columns
|
|
but only one row
|
|
\o {1, 2} This table cell spans only one column,
|
|
but two rows.
|
|
\row
|
|
\o A regular table cell
|
|
\o 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 {o-command} {\\o}.
|
|
|
|
\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 {o-command} {\\o} command.
|
|
|
|
A header cell's text is centered within the table cell and
|
|
rendered using a bold font.
|
|
|
|
\code
|
|
/ *!
|
|
\table
|
|
\header
|
|
\o Qt Core Feature
|
|
\o Brief Description
|
|
\row
|
|
\o \l {Signal and Slots}
|
|
\o 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://qt.nokia.com/doc/4.0/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 {o-command} {\\o}.
|
|
|
|
\target row-command
|
|
\section1 \\row
|
|
|
|
The \\row command begins a new row in a table. The \l {o-command}
|
|
{\\o 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 {o-command} {\\o} 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
|
|
\o Qt Core Feature
|
|
\o Brief Description
|
|
\row
|
|
\o \l {Signal and Slots}
|
|
\o Signals and slots are used for communication
|
|
between objects.
|
|
\row
|
|
\o \l {Layout Management}
|
|
\o The Qt layout system provides a simple
|
|
and powerful way of specifying the layout
|
|
of child widgets.
|
|
\row
|
|
\o \l {Drag and Drop}
|
|
\o 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://qt.nokia.com/doc/4.0/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://qt.nokia.com/doc/4.0/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://qt.nokia.com/doc/4.0/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 {o-command} {\\o}.
|
|
|
|
\target value-command
|
|
\section1 \\value
|
|
|
|
The \\value command starts the documentation of a C++ enum item.
|
|
|
|
The command's first argument is the enum item. Then follows its
|
|
associated description. The description argument ends at the next
|
|
blank line or \\value. The arguments are rendered within a table.
|
|
|
|
The documentation will be located in the associated class, header
|
|
file or namespace documentation. See the \l {enum-command}
|
|
{\\enum} documentation for an example.
|
|
|
|
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}.
|
|
|
|
\target list-command
|
|
\section1 \\list
|
|
|
|
The \\list and \\endlist commands delimit a list of items.
|
|
|
|
Create each list item with the \l {o-command} {\\o} command. A
|
|
list always contains one or more items. Lists can be nested. For
|
|
example:
|
|
|
|
\code
|
|
/ *!
|
|
\list
|
|
\o Qt Reference Documentation: Getting Started
|
|
\list
|
|
\o How to Learn Qt
|
|
\o Installation
|
|
\list
|
|
\o Qt/X11
|
|
\o Qt/Windows
|
|
\o Qt/Mac
|
|
\o Qt/Embedded
|
|
\endlist
|
|
\o Tutorial and Examples
|
|
\endlist
|
|
\endlist
|
|
* /
|
|
\endcode
|
|
|
|
QDoc renders this as:
|
|
|
|
\list
|
|
\o Qt Reference Documentation: Getting Started
|
|
\list
|
|
\o How to Learn Qt
|
|
\o Installation
|
|
\list
|
|
\o Qt/X11
|
|
\o Qt/Windows
|
|
\o Qt/Mac
|
|
\o Qt/Embedded
|
|
\endlist
|
|
\o Tutorial and Examples
|
|
\endlist
|
|
\endlist
|
|
|
|
The \\list command takes an optional argument providing
|
|
alternative appearances for the list items.
|
|
|
|
\code
|
|
/ *!
|
|
\list
|
|
\o How to Learn Qt
|
|
\o Installation
|
|
\o Tutorial and Examples
|
|
\endlist
|
|
* /
|
|
\endcode
|
|
|
|
QDoc renders the list items with bullets (the default):
|
|
|
|
\list
|
|
\o How to Learn Qt
|
|
\o Installation
|
|
\o Tutorial and Examples
|
|
\endlist
|
|
|
|
\warning There appears to be a bug in qdoc3 here. If you include
|
|
any of the argument types, you get a numeric list. We're looking
|
|
into it.
|
|
|
|
If you provide 'A' as an argument to the \\list command, the
|
|
bullets are replaced with characters in alphabetical order:
|
|
|
|
\list A
|
|
\o How to Learn Qt
|
|
\o Installation
|
|
\o Tutorial and Examples
|
|
\endlist
|
|
|
|
If you replace 'A' with '1', the list items are numbered in
|
|
ascending order:
|
|
|
|
\list 1
|
|
\o How to Learn Qt
|
|
\o Installation
|
|
\o Tutorial and Examples
|
|
|
|
\endlist
|
|
|
|
If you provide 'i' as the argument, the bullets are replaced with
|
|
roman numerals:
|
|
|
|
\list i
|
|
\o How to Learn Qt
|
|
\o Installation
|
|
\o 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
|
|
\o How to Learn Qt
|
|
\o Installation
|
|
\o 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
|
|
\o How to Learn Qt
|
|
\o Installation
|
|
\o Tutorial and Examples
|
|
\endlist
|
|
* /
|
|
\endcode
|
|
|
|
QDoc renders this as:
|
|
|
|
\list G
|
|
\o How to Learn Qt
|
|
\o Installation
|
|
\o Tutorial and Examples
|
|
\endlist
|
|
|
|
See also \l {o-command} {\\o}.
|
|
|
|
\target o-command
|
|
\section1 \\o (cell, item)
|
|
|
|
The \\o command announce a table or list item.
|
|
|
|
Earlier we used the \l {i-command} {\\i} command for this
|
|
purpose. For more information see the \l
|
|
{26-qdoc-commands-compatibility.html#o-versus-i} {compatibility}
|
|
section.
|
|
|
|
The command can only be used within the \l{table-command}
|
|
{\\table...\\endtable} or \l{list-command} {\\list... \\endlist}
|
|
commands.
|
|
|
|
It considers everything until the next occurrence of the \\o
|
|
command, or the currently applicable \l {table-command}
|
|
{\\endtable} or \l {list-command} {\\endlist} command, as its
|
|
argument. For examples, see \l {table-command} {\\table} and \l
|
|
{list-command} {\\list}.
|
|
|
|
If the command is used within a table, you can in addition specify
|
|
how many rows or columns the item should span.
|
|
|
|
\code
|
|
/ *!
|
|
\table
|
|
\header
|
|
\o {3,1} This header cell spans three columns
|
|
but only one row.
|
|
\row
|
|
\o {2, 1} This table item spans two columns
|
|
but only one row
|
|
\o {1, 2} This table item spans only one column,
|
|
but two rows.
|
|
\row
|
|
\o A regular table item
|
|
\o 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}, \l {list-command} {\\list} and \l {o-command} {\\o}.
|
|
|
|
*/
|
|
|
|
/*!
|
|
\page 11-qdoc-commands-specialcontent.html
|
|
\previouspage Tables and Lists
|
|
\contentspage Table of Contents
|
|
\nextpage Miscellaneous
|
|
|
|
\title Special Content
|
|
|
|
The document contents commands identify parts of the documentation,
|
|
i.e. parts with a special rendering, conceptual meaning or
|
|
function.
|
|
|
|
\target abstract-command
|
|
\section1 \\abstract
|
|
|
|
The \\abstract and \\endabstract commands delimit a
|
|
document's abstract section.
|
|
|
|
The abstract section is rendered as an indented italicized
|
|
paragraph.
|
|
|
|
\warning The \bold{\\abstract} and \bold{\\endabstract} commands
|
|
have not been implemented. The abstract section is rendered as a
|
|
regular HTML paragraph.
|
|
|
|
\target quotation-command
|
|
\section1 \\quotation
|
|
|
|
The \\quotation and \\endquotation commands delimit a long quotation.
|
|
|
|
The text in the delimited block is surrounded by
|
|
\bold{<blockquote>} and \bold{</blockquote>} in the html output,
|
|
e.g.:
|
|
|
|
\code
|
|
/ *!
|
|
While 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 \bold{\\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 \bold{<blockquote>} tag in your style.css file.
|
|
|
|
This command replaces the old \\quote command. For more
|
|
information see the \l
|
|
{26-qdoc-commands-compatibility.html#quotation-versus-quote}
|
|
{compatibility} section.
|
|
|
|
\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 \bold{\\footnote} and \bold{\\endfootnote} commands
|
|
have not been implemented. The footnote is rendered as a regular
|
|
HTML paragraph.
|
|
|
|
\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.
|
|
|
|
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 true
|
|
for both the active window \e and for 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://qt.nokia.com/doc/4.0/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
|
|
\o \bold {const QRect & geometry () const}
|
|
\o \bold {void setGeometry ( int x, int y, int w, int h )}
|
|
\o \bold {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, the brief
|
|
text should be a complete sentence and must start like this:
|
|
|
|
\code
|
|
The <classname> class is|provides|contains|specifies...
|
|
\endcode
|
|
|
|
\warning The brief statement is used as the first paragraph of the
|
|
detailed description. Do not repeat the sentence.
|
|
|
|
\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
|
|
\o 52 properties inherited from QWidget
|
|
\o 1 property inherited from QObject
|
|
\endlist
|
|
|
|
\raw HTML
|
|
<h3>Public Functions</h3>
|
|
\endraw
|
|
|
|
\list
|
|
\o \l {constructor} {PreviewWindow}(QWidget *parent = 0)
|
|
\o void \l {function} {setWindowFlags}(Qt::WindowFlags flags)
|
|
\endlist
|
|
|
|
\list
|
|
\o 183 public functions inherited from QWidget
|
|
\o 28 public functions inherited from QObject
|
|
\endlist
|
|
|
|
\raw HTML
|
|
<h3>Public Slots</h3>
|
|
\endraw
|
|
|
|
\list
|
|
\o 17 public slots inherited from QWidget
|
|
\o 1 public slot inherited from QObject
|
|
\endlist
|
|
|
|
\raw HTML
|
|
<h3>Additional Inherited Members</h3>
|
|
\endraw
|
|
|
|
\list
|
|
\o 1 signal inherited from QWidget
|
|
\o 1 signal inherited from QObject
|
|
\o 4 static public members inherited from QWidget
|
|
\o 4 static public members inherited from QObject
|
|
\o 39 protected functions inherited from QWidget
|
|
\o 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 licence agreement.
|
|
|
|
In the generated HTML, the delimited text is surrounded by a \bold
|
|
{<div class="LegaleseLeft">} and \bold {</div>} tags.
|
|
|
|
For example, here is 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-command} as the argument. This is useful for
|
|
generating an overview of the license agreements associated with
|
|
the source code.
|
|
|
|
\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 Mac OS X, 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 Mac OS X, 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
|
|
\contentspage Table of Contents
|
|
\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 expire-command
|
|
\section1 \\expire
|
|
|
|
The \\expire command allows you to define an expiration
|
|
date for your documentation.
|
|
|
|
When using the \\expire command, QDoc will emit a warning when the
|
|
current date is larger than the specified date. The command
|
|
accepts one argument; the argument's format is yyyy-mm-dd. For
|
|
example:
|
|
|
|
\code
|
|
/ *!
|
|
\page porting.html
|
|
|
|
\title Porting to Qt 3.x
|
|
|
|
\expire 2004-12-31
|
|
|
|
This document describes porting applications from Qt
|
|
2.x to Qt 3.x.
|
|
|
|
The Qt 3.x series is not binary compatible with the
|
|
2.x series.
|
|
...
|
|
* /
|
|
\endcode
|
|
|
|
If you run QDoc on 4 July 2005, it will emit the warning
|
|
|
|
\quotation
|
|
porting.qdoc:6: Documentation expired 185 days ago
|
|
\endquotation
|
|
|
|
|
|
\target generatelist-command
|
|
\section1 \\generatelist
|
|
|
|
The \\generatelist command expands to a list of various
|
|
documentation or links to documentation. 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}. For
|
|
a list of Qt 3 support classes, see \l{Qt3Support
|
|
Classes}.
|
|
|
|
\generatelist classes
|
|
* /
|
|
\endcode
|
|
|
|
This generates the \l {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
|
|
\o QDial
|
|
\o Rounded range control (like a speedometer or potentiometer)
|
|
\row
|
|
\o QDialog
|
|
\o The base class of dialog windows
|
|
\row
|
|
\o QDir
|
|
\o 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.
|
|
|
|
\target list example
|
|
\section2 \c classes
|
|
|
|
The \c classes argument provides a complete alphabetical list of
|
|
the classes. Each class name is a link to the class's reference
|
|
documentation. This command is uded to generate the \l
|
|
{classes.html} {All Classes} page this way:
|
|
|
|
\code
|
|
/ *!
|
|
\page classes.html
|
|
\title All Classes
|
|
\ingroup classlists
|
|
|
|
\brief If you know the name of the class you want, find it here.
|
|
|
|
This is a list of all Qt classes. For a list of the classes
|
|
provided for compatibility with Qt3, see \l{Qt3 Support
|
|
Classes}. For classes that have been deprecated, see the
|
|
\l{Obsolete Classes} list.
|
|
|
|
\generatelist classes
|
|
* /
|
|
\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.
|
|
|
|
This command is used to generate the \l {phonon-module.html}
|
|
{Phonon Module} page this way.
|
|
|
|
\code
|
|
/ *!
|
|
\page phonon-module.html
|
|
\module Phonon
|
|
\title Phonon Module
|
|
\ingroup modules
|
|
|
|
\brief The Phonon module 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 compatclasses
|
|
|
|
The \c compatclasses argument generates a list in alphabetical
|
|
order of the support classes. It is normally used only to
|
|
generate the \l {compatclasses.html} {Qt3 Support Classes} page
|
|
this way:
|
|
|
|
\code
|
|
/ *!
|
|
\page compatclasses.html
|
|
\title Qt3 Support Classes
|
|
\ingroup classlists
|
|
|
|
\brief These classes ease the porting of code from Qt 3 to Qt 4.
|
|
|
|
These are the classes that Qt provides for compatibility with Qt
|
|
3. Most of these are provided by the Qt3Support module.
|
|
|
|
\generatelist compatclasses
|
|
* /
|
|
\endcode
|
|
|
|
A support class is identified in the \\class comment with the \l
|
|
{compat-command} {\\compat} 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 \l {functions.html} {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 complete list of
|
|
licenses in the documentation. Each license is identified using
|
|
the \l {legalese-command} {\\legalese} command. This command is
|
|
used to generate the \l {licenses.html} {Qt license information}
|
|
page this way:
|
|
|
|
\code
|
|
/ *!
|
|
\page licenses.html
|
|
\title Other Licenses Used in Qt
|
|
\ingroup licensing
|
|
\brief Information about other licenses used for Qt components and third-party code.
|
|
|
|
Qt contains some code that is not provided under the
|
|
\l{GNU General Public License (GPL)},
|
|
\l{GNU Lesser General Public License (LGPL)} or the
|
|
\l{Qt Commercial Edition}{Qt Commercial License Agreement}, but rather under
|
|
specific licenses from the original authors. Some pieces of code were developed
|
|
by The Qt Company and others originated from third parties.
|
|
This page lists the licenses used, names the authors, and links
|
|
to the places where it is used.
|
|
|
|
The Qt Company gratefully acknowledges these and other contributions
|
|
to Qt. We recommend that programs that use Qt also acknowledge
|
|
these contributions, and quote these license statements in an
|
|
appendix to the documentation.
|
|
|
|
See also: \l{Licenses for Fonts Used in Qt for Embedded Linux}
|
|
|
|
\generatelist legalese
|
|
* /
|
|
\endcode
|
|
|
|
\section2 \c mainclasses
|
|
|
|
The \c mainclasses argument tells QDoc to generate an alphabetical
|
|
list of the main classes. A class is marked as a main class by
|
|
including a \l {mainclass-command} {\\mainclass} command in the
|
|
\\class comment.
|
|
|
|
\note The Qt documentation no longer includes a main classes page,
|
|
but you can generate one for your main classes if you want it.
|
|
|
|
\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 \l {overviews.html}
|
|
{overviews} page this way:
|
|
|
|
\code
|
|
/ *!
|
|
\page overviews.html
|
|
|
|
\title All Overviews and HOWTOs
|
|
|
|
\generatelist overviews
|
|
* /
|
|
\endcode
|
|
|
|
\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 \l {Programming with Qt}
|
|
{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
|
|
|
|
\section2 \c service
|
|
|
|
The \c service argument tells QDoc to generate an alphabetical
|
|
list of the services. Each service name is a link to the service's
|
|
reference documentation.
|
|
|
|
A service is identified with the \l {service-command} {\\service}
|
|
command.
|
|
|
|
\note This command and the \l {service-command} {\\service}
|
|
command are not used in the Qt documentation.
|
|
|
|
\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)
|
|
|
|
\bold{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.
|
|
|
|
\code
|
|
/ *!
|
|
The Qt 3 support library is provided to keep old
|
|
source code working.
|
|
|
|
In addition to the \c Qt3Support classes, Qt 4 provides
|
|
compatibility functions when it's possible for an old
|
|
API to cohabit with the new one.
|
|
|
|
\if !defined(QT3_SUPPORT)
|
|
\if defined(QT3_SUPPORTWARNINGS)
|
|
The compiler emits a warning when a
|
|
compatibility function is called. (This works
|
|
only with GCC 3.2+ and MSVC 7.)
|
|
\else
|
|
To use the Qt 3 support library, you need to
|
|
have the line QT += qt3support in your .pro
|
|
file (qmake automatically define the
|
|
QT3_SUPPORT symbol, turning on compatibility
|
|
function support).
|
|
|
|
You can also define the symbol manually (e.g.,
|
|
if you don't want to link against the \c
|
|
Qt3Support library), or you can define \c
|
|
QT3_SUPPORT_WARNINGS instead, telling the
|
|
compiler to emit a warning when a compatibility
|
|
function is called. (This works only with GCC
|
|
3.2+ and MSVC 7.)
|
|
\endif
|
|
\endif
|
|
* /
|
|
\endcode
|
|
|
|
If the \c QT3_SUPPORT is defined, the comment will be rendered
|
|
like this:
|
|
|
|
\quotation
|
|
The Qt 3 support library is provided to keep old source
|
|
code working.
|
|
|
|
In addition to the Qt3Support classes, Qt 4 provides
|
|
compatibility functions when it's possible for an old
|
|
API to cohabit with the new one.
|
|
\endquotation
|
|
|
|
If \c QT3_SUPPORT is not defined but \c QT3_SUPPORT_WARNINGS is
|
|
defined, the comment will be rendered like this:
|
|
|
|
\quotation
|
|
The Qt 3 support library is provided to keep old source
|
|
code working.
|
|
|
|
In addition to the Qt3Support classes, Qt 4 provides
|
|
compatibility functions when it's possible for an old
|
|
API to cohabit with the new one.
|
|
|
|
The compiler emits a warning when a compatibility
|
|
function is called. (This works only with GCC 3.2+ and
|
|
MSVC 7.)
|
|
\endquotation
|
|
|
|
If none of the symbols are defined, the comment will be
|
|
rendered as
|
|
|
|
\quotation
|
|
The Qt 3 support library is provided to keep old
|
|
source code working.
|
|
|
|
In addition to the \c Qt3Support classes, Qt 4 provides
|
|
compatibility functions when it's possible for an old
|
|
API to cohabit with the new one.
|
|
|
|
To use the Qt 3 support library, you need to have the
|
|
line QT += qt3support in your .pro file (qmake
|
|
automatically define the QT3_SUPPORT symbol, turning on
|
|
compatibility function support).
|
|
|
|
You can also define the symbol manually (e.g., if you
|
|
don't want to link against the \c Qt3Support library),
|
|
or you can define \c QT3_SUPPORT_WARNINGS instead,
|
|
telling the compiler to emit a warning when a
|
|
compatibility function is called. (This works only with
|
|
GCC 3.2+ and MSVC 7.)
|
|
\endquotation
|
|
|
|
See also \l{if-command} {\\if}, \l{endif-command} {\\endif}, \l
|
|
{defines-variable} {defines} and \l {falsehoods-variable}
|
|
{falsehoods}.
|
|
|
|
\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. This command is often assigned the alias,
|
|
\e {input}, in the QDoc configuration file, e.g. \e {alias.include
|
|
= input}.
|
|
|
|
The command is useful when some snippet of commands and text is to
|
|
be used in multiple places in the documentation. In that case,
|
|
move the snippet into a separate file and use the \\include
|
|
command wherever you want to insert the snippet into the
|
|
documentation. To prevent QDoc from reading the file as a
|
|
stand-alone page of documentation, we recommend that you use the
|
|
\c .qdocinc extension for these \e {include} files.
|
|
|
|
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, i.e. a sequence of QDoc commands and text, but without
|
|
the enclosing qdoc comment \c{/}\c{*!} ... \c{*}\c{/} delimeters.
|
|
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
|
|
|
|
Here are links to the \c .qdocinc files used above:
|
|
\l{signalandslots.qdocinc}, \l{objectmodel.qdocinc},
|
|
\l{layoutmanagement.qdocinc}. QDoc renders this page
|
|
\l{corefeatures.html} {as shown here}.
|
|
|
|
\target 2-argument-form}
|
|
\section2 \\include filename snippet-identifier \span {class="newStuff"} {(new)}
|
|
|
|
It is kind of a pain 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 lots of these include snippets, 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 nest these snippets,
|
|
although it's not clear why you would want to do that.
|
|
|
|
\target meta-command
|
|
\section1 \\meta
|
|
|
|
The \\meta command is mainly used for including metadata in DITA
|
|
XML files. It is also used 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 you wish to set, 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} {OS X 10.6}
|
|
\meta {platform} {Symbian}
|
|
\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, but if you run QDoc to generate
|
|
DITA XML, the example will generate the following:
|
|
|
|
\code
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE cxxClass PUBLIC "-//NOKIA//DTD DITA C++ API Class Reference Type v0.6.0//EN" "dtd/cxxClass.dtd">
|
|
<!--qwidget.cpp-->
|
|
<cxxClass id="id-9a14268e-6b09-4eee-b940-21a00a0961df">
|
|
<apiName>QWidget</apiName>
|
|
<shortdesc>the QWidget class is the base class of all user interface objects.</shortdesc>
|
|
<prolog>
|
|
<author>Qt Development Frameworks</author>
|
|
<publisher>The Qt Company</publisher>
|
|
<copyright>
|
|
<copyryear year="2015"/>
|
|
<copyrholder>The Qt Company Ltd</copyrholder>
|
|
</copyright>
|
|
<permissions view="all"/>
|
|
<metadata>
|
|
<audience type="designer"/>
|
|
<audience type="programmer"/>
|
|
<audience type="user"/>
|
|
<category>Class reference</category>
|
|
<prodinfo>
|
|
<prodname>Qt Reference Documentation</prodname>
|
|
<vrmlist>
|
|
<vrm version="4" release="7" modification="3"/>
|
|
</vrmlist>
|
|
<component>QtGui</component>
|
|
</prodinfo>
|
|
<othermeta name="platform" content="MeeGo"/>
|
|
<othermeta name="platform" content="Symbian"/>
|
|
<othermeta name="platform" content="OS X 10.6"/>
|
|
<othermeta name="technology" content="User Interface"/>
|
|
</metadata>
|
|
</prolog>
|
|
\endcode
|
|
|
|
In the example output, several values have been set using defualt
|
|
values obtained from the QDoc configuration file. See \l
|
|
{Generating DITA XML Output} for details.
|
|
|
|
\target omit-command
|
|
\section1 \\omit
|
|
|
|
The \\omit command and the correspondning \\endomit command
|
|
delimit parts of the documentation that you want QDoc to skip. For
|
|
example:
|
|
|
|
\code
|
|
/ *!
|
|
\table
|
|
\row
|
|
\o Basic Widgets
|
|
\o Basic GUI widgets such as buttons, comboboxes
|
|
and scrollbars.
|
|
|
|
\omit
|
|
\row
|
|
\o Component Model
|
|
\o Interfaces and helper classes for the Qt
|
|
Component Model.
|
|
\endomit
|
|
|
|
\row
|
|
\o Database Classes
|
|
\o 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 \span {class="newStuff"} {(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, because it generates
|
|
DITA XML code that causes problems. 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 again 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
|
|
*/
|
|
|
|
/*!
|
|
\page 12-1-signalandslots.html
|
|
\previouspage Miscellaneous
|
|
\contentspage Table of Contents
|
|
|
|
\title signalandslots.qdocinc
|
|
|
|
\quotefile examples/signalandslots.qdocinc
|
|
*/
|
|
|
|
/*!
|
|
\page 12-2-objectmodel.html
|
|
\previouspage Miscellaneous
|
|
\contentspage Table of Contents
|
|
|
|
\title objectmodel.qdocinc
|
|
|
|
\quotefile examples/objectmodel.qdocinc
|
|
*/
|
|
|
|
/*!
|
|
\page 12-3-layoutmanagement.html
|
|
\previouspage Miscellaneous
|
|
\contentspage Table of Contents
|
|
|
|
\title layoutmanagement.qdocinc
|
|
|
|
\quotefile examples/layoutmanagement.qdocinc
|
|
*/
|
|
|
|
/*!
|
|
\page 13-qdoc-commands-topics.html
|
|
\previouspage Command Index
|
|
\contentspage Table of Contents
|
|
\nextpage Context Commands
|
|
|
|
\title Topic Commands
|
|
|
|
A topic command tells QDoc which source code element is being
|
|
documented. Some topic commands allow you to create documentation
|
|
pages that aren't tied to any underlying source code element.
|
|
|
|
When QDoc processes a QDoc comment, it tries to connect the
|
|
comment to an element in the source code by first looking for a
|
|
topic command that names the source code element. If there is no
|
|
topic command, QDoc tries to connect the comment to the source
|
|
code element that immediately follows the comment. If it can't do
|
|
either of these and if there is no topic command that indicates
|
|
the comment does not have an underlying source code element (e.g.
|
|
\l{page-command} {\\page}), then the comment is discarded.
|
|
|
|
\target topic argument
|
|
|
|
The name of the thing being documented is the unique argument for
|
|
each topic command. The naming convention is to use the complete
|
|
name.
|
|
|
|
\code
|
|
\enum QComboBox::InsertPolicy
|
|
\endcode
|
|
|
|
The \l {fn-command} {\\fn} command is a special case. For the \l
|
|
{fn-command} {\\fn} command, use the function's signature
|
|
including the class qualifier.
|
|
|
|
\code
|
|
\fn void QGraphicsWidget::setWindowFlags(Qt::WindowFlags wFlags)
|
|
\endcode
|
|
|
|
A topic command can appear anywhere in a comment but must stand
|
|
alone on its own line. Best practice is to put the topic commend
|
|
at the top of the comment. If the argument spans several lines,
|
|
make sure that each line (except the last one) is ended with a
|
|
backslash. In addition QDoc counts parentheses, which means that
|
|
if it encounters a '(' it considers everything until the closing
|
|
')' as its argument.
|
|
|
|
If a topic command is repeated with different arguments, the
|
|
same documentation will appear for both the units.
|
|
|
|
\code
|
|
/ *!
|
|
\fn void PreviewWindow::setWindowFlags()
|
|
\fn void ControllerWindow::setWindowFlags()
|
|
|
|
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.
|
|
* /
|
|
\endcode
|
|
|
|
The \c PreviewWindow::setWindowFlags() and \c
|
|
ControllerWindow::setWindowFlags() functions will get the same
|
|
documentation.
|
|
|
|
\target class-command
|
|
\section1 \\class
|
|
|
|
The \\class command is for documenting a C++ class. The argument
|
|
is the complete name of the class. The command tells QDoc that a
|
|
class is part of the public API, and lets you enter a detailed
|
|
description.
|
|
|
|
\code
|
|
/ *!
|
|
\class QMap::iterator
|
|
|
|
\brief The QMap::iterator class provides an STL-style
|
|
non-const iterator for QMap and QMultiMap.
|
|
|
|
QMap features both \l{STL-style iterators} and
|
|
\l{Java-style iterators}. The STL-style iterators ...
|
|
* /
|
|
\endcode
|
|
|
|
The HTML documentation for the named class is written to a
|
|
\c{.html} file named from the class name, in lower case, and with
|
|
the double colon qulifier(s) replaced with '-'. For example, the
|
|
documentation for the \c QMap::Iterator class is written to \c
|
|
qmap-iterator.html.
|
|
|
|
\target framework
|
|
|
|
The file contains the class description from the \\class comment,
|
|
plus the documentation generated from QDoc comments for all the
|
|
class members, i.e. a list of the class's types, properties,
|
|
functions, signals, and slots.
|
|
|
|
In addition to the detailed description of the class, the \\class
|
|
comment typically contains a \l {brief-command} {\\brief} command
|
|
and one or more \l{Markup Commands}. See the \\class command for
|
|
any of the Qt class for examples. Here is a very simple example:
|
|
|
|
\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.
|
|
|
|
\ingroup miscellaneous
|
|
|
|
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.
|
|
|
|
...
|
|
|
|
\sa QWidget
|
|
* /
|
|
\endcode
|
|
|
|
The way QDoc renders this \\class will depend a lot on your \c
|
|
{style.css} file, but the general outline of the class reference
|
|
page will look like this:
|
|
|
|
\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
|
|
\o 52 properties inherited from QWidget
|
|
\o 1 property inherited from QObject
|
|
\endlist
|
|
|
|
\raw HTML
|
|
<h3>Public Functions</h3>
|
|
\endraw
|
|
|
|
\list
|
|
\o \l {constructor} {PreviewWindow}(QWidget *parent = 0)
|
|
\o void \l {function} {setWindowFlags}(Qt::WindowFlags flags)
|
|
\endlist
|
|
|
|
\list
|
|
\o 183 public functions inherited from QWidget
|
|
\o 28 public functions inherited from QObject
|
|
\endlist
|
|
|
|
\raw HTML
|
|
<h3>Public Slots</h3>
|
|
\endraw
|
|
|
|
\list
|
|
\o 17 public slots inherited from QWidget
|
|
\o 1 public slot inherited from QObject
|
|
\endlist
|
|
|
|
\raw HTML
|
|
<h3>Additional Inherited Members</h3>
|
|
\endraw
|
|
|
|
\list
|
|
\o 1 signal inherited from QWidget
|
|
\o 1 signal inherited from QObject
|
|
\o 4 static public members inherited from QWidget
|
|
\o 4 static public members inherited from QObject
|
|
\o 39 protected functions inherited from QWidget
|
|
\o 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
|
|
|
|
\target enum-command
|
|
\section1 \\enum
|
|
|
|
The \\enum command is for documenting a C++ enum type. The
|
|
argument is the full name of the enum type.
|
|
|
|
The enum values are documented in the \\enum comment using the \l
|
|
{value-command} {\\value} command. If an enum value is not
|
|
documented with \\value, QDoc emits a warning. These warnings can
|
|
be avoided using the \l {omitvalue-command} {\\omitvalue} command
|
|
to tell QDoc that an enum value should not be documented. The enum
|
|
documentation will be included on the class reference page, header
|
|
file page, or namespace page where the enum type is defined. For
|
|
example, consider the enum type \c {Corner} in the Qt namespace:
|
|
|
|
\code
|
|
enum Corner {
|
|
TopLeftCorner = 0x00000,
|
|
TopRightCorner = 0x00001,
|
|
BottomLeftCorner = 0x00002,
|
|
BottomRightCorner = 0x00003
|
|
#if defined(QT3_SUPPORT) && !defined(Q_MOC_RUN)
|
|
,TopLeft = TopLeftCorner,
|
|
TopRight = TopRightCorner,
|
|
BottomLeft = BottomLeftCorner,
|
|
BottomRight = BottomRightCorner
|
|
#endif
|
|
};
|
|
\endcode
|
|
|
|
This enum can be cocumented this way:
|
|
|
|
\code
|
|
/ *!
|
|
\enum Qt::Corner
|
|
|
|
This enum type specifies a corner in a rectangle:
|
|
|
|
\value TopLeftCorner
|
|
The top-left corner of the rectangle.
|
|
\value TopRightCorner
|
|
The top-right corner of the rectangle.
|
|
\value BottomLeftCorner
|
|
The bottom-left corner of the rectangle.
|
|
\value BottomRightCorner
|
|
The bottom-right corner of the rectangle.
|
|
|
|
\omitvalue TopLeft
|
|
\omitvalue TopRight
|
|
\omitvalue BottomLeft
|
|
\omitvalue BottomRight
|
|
* /
|
|
\endcode
|
|
|
|
Note the inclusion of the namespace qualifier. QDoc will render
|
|
this enum type in \c {qt.html} like this:
|
|
|
|
\quotation
|
|
\raw HTML
|
|
<h3 class="fn"><a name="Corner-enum"></a>enum Qt::Corner</h3>
|
|
|
|
<p>This enum type specifies a corner in a rectangle:</p>
|
|
|
|
<table border="1" cellpadding="2" cellspacing="1" width="100%">
|
|
<tr>
|
|
<th width="25%">Constant</th>
|
|
<th width="15%">Value</th>
|
|
<th width="60%">Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><tt>Qt::TopLeftCorner</tt></td>
|
|
<td align="center" valign="top"><tt>0x00000</tt></td>
|
|
<td valign="top">The top-left corner of the rectangle.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><tt>Qt::TopRightCorner</tt></td>
|
|
<td align="center" valign="top"><tt>0x00001</tt></td>
|
|
<td valign="top">The top-right corner of the rectangle.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><tt>Qt::BottomLeftCorner</tt></td>
|
|
<td align="center" valign="top"><tt>0x00002</tt></td>
|
|
<td valign="top">The bottom-left corner of the rectangle.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><tt>Qt::BottomRightCorner</tt></td>
|
|
<td align="center" valign="top"><tt>0x00003</tt></td>
|
|
<td valign="top">The bottom-right corner of the rectangle.</td>
|
|
</tr>
|
|
|
|
</table>
|
|
\endraw
|
|
\endquotation
|
|
|
|
See also \l {value-command} {\\value} and \l {omitvalue-command} {\\omitvalue}.
|
|
|
|
\target example-command
|
|
\section1 \\example
|
|
|
|
The \\example command is for documenting an example. The argument
|
|
is the example's path relative to omne of the paths listed in the
|
|
\l {exampledirs-variable} {exampledirs} variable in the QDoc
|
|
configuration file.
|
|
|
|
The documentation page will be output to \c {path-to-example}.html.
|
|
QDoc will add a list of all the example's source files at the top
|
|
of the page.
|
|
|
|
For example, if \l {exampledirs-variable} {exampledirs} contains
|
|
\c $QTDIR/examples/widgets/imageviewer, then
|
|
|
|
\code
|
|
/ *!
|
|
\example widgets/imageviewer
|
|
\title ImageViewer Example
|
|
\subtitle
|
|
|
|
The example shows how to combine QLabel and QScrollArea
|
|
to display an image.
|
|
|
|
...
|
|
* /
|
|
\endcode
|
|
|
|
QDoc renders this example in widgets-imageviewer.html:
|
|
|
|
\quotation
|
|
\raw HTML
|
|
<center><h1>Image Viewer Example</h1></center>
|
|
\endraw
|
|
|
|
Files:
|
|
\list
|
|
\o \l{http://qt.nokia.com/doc/4.0/widgets-imageviewer-imageviewer-cpp.html}
|
|
{widgets/imageviewer/imageviewer.cpp}
|
|
\o \l{http://qt.nokia.com/doc/4.0/widgets-imageviewer-imageviewer-h.html}
|
|
{widgets/imageviewer/imageviewer.h}
|
|
\o \l{http://qt.nokia.com/doc/4.0/widgets-imageviewer-main-cpp.html}
|
|
{widgets/imageviewer/main.cpp}
|
|
\endlist
|
|
|
|
The example shows how to combine QLabel and QScrollArea
|
|
to display an image.
|
|
|
|
...
|
|
\endquotation
|
|
|
|
\target externalpage-command
|
|
\section1 \\externalpage
|
|
|
|
The \\externalpage command assigns a title to an external URL.
|
|
|
|
\code
|
|
/ *!
|
|
\externalpage http://doc.trolltech.com/4.3/qtopiacore.html
|
|
\title Qtopia Core
|
|
* /
|
|
\endcode
|
|
|
|
This allows you to include a link to the external page in your
|
|
documentation this way:
|
|
|
|
\code
|
|
/ *!
|
|
The broad scope of the \l {Qtopia Core} API enables it to
|
|
be used across a wide variety of development projects.
|
|
* /
|
|
\endcode
|
|
|
|
QDoc renders this as:
|
|
|
|
\quotation
|
|
The broad scope of the \l
|
|
{http://doc.trolltech.com/4.3/qtopiacore.html} {Qtopia
|
|
Core} API enables it to be used across a wide variety
|
|
of development projects.
|
|
\endquotation
|
|
|
|
To achieve the same result without using the \\externalpage
|
|
command, you would have to hard code the adress into your
|
|
documentation:
|
|
|
|
\code
|
|
/ *!
|
|
The broad scope of the \l
|
|
{http://doc.trolltech.com/4.3/qtopiacore.html} {Qtopia
|
|
Core} API enables it to be used across a wide variety
|
|
of development projects.
|
|
* /
|
|
\endcode
|
|
|
|
The \\externalpage command makes it easier to maintain the
|
|
documentation. If the adress changes, you only need to change the
|
|
argument of the \\externalpage command.
|
|
|
|
\target fn-command
|
|
\section1 \\fn (function)
|
|
|
|
The \\fn command is for documenting a function. The argument is
|
|
the function's signature, including its return type, const-ness,
|
|
and list of formal arguments with types. If the named function
|
|
doesn't exist, QDoc emits a warning.
|
|
|
|
\note The \\fn command is QDoc's default command, i.e. when no
|
|
topic command can be found in a QDoc comment, QDoc tries to tie
|
|
the documentation to the following code as if it is the
|
|
documentation for a function. Hence, it is normally not necessary
|
|
to include this command when documenting a function, if the
|
|
function's QDoc comment is written immediately above the function
|
|
implementation in the \c .cpp file. But it must be present when
|
|
documenting an inline function in the \c .cpp file that is
|
|
implemented in the \c .h file.
|
|
|
|
\code
|
|
/ *!
|
|
\fn bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const
|
|
|
|
Returns true if this toolbar is dockable in the given
|
|
\a area; otherwise returns false.
|
|
* /
|
|
\endcode
|
|
|
|
QDoc renders this as:
|
|
|
|
\quotation
|
|
\raw HTML
|
|
<h3>bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const
|
|
</h3>
|
|
\endraw
|
|
|
|
Returns true if this toolbar is dockable in the given
|
|
\a area; otherwise returns false.
|
|
\endquotation
|
|
|
|
See also \l {overload-command} {\\overload}.
|
|
|
|
\target group-command
|
|
\section1 \\group
|
|
|
|
The \\group command creates a separate page that lists the classes
|
|
belonging to the group. The argument is the group name.
|
|
|
|
A class is included in a group by using the \l {ingroup-command}
|
|
{\\ingroup} command. Overview pages can also be related to a group
|
|
using the same command, but the list of overview pages must be
|
|
requested explicitly using the \l {generatelist-command}
|
|
{\\generatelist} command (see example below).
|
|
|
|
The \\group command is typically followed by a \l {title-command}
|
|
{\\title} command and a short introduction to the group. The
|
|
HTML page for the group is written to a \c {.html} file put in
|
|
<lower-case>\e{group}.html.
|
|
|
|
Each class name is listed as a link to the class reference page
|
|
followed by the text from the class's \l {brief-command} {\\brief}
|
|
texts.
|
|
|
|
\code
|
|
/ *!
|
|
\group io
|
|
|
|
\title Input/Output and Networking
|
|
|
|
These classes are used to handle input and output to
|
|
and from external devices, processes, files etc. as
|
|
well as manipulating files and directories.
|
|
* /
|
|
\endcode
|
|
|
|
QDoc generates a group page in \c{io.html} that will look
|
|
like this:
|
|
|
|
\quotation
|
|
\raw HTML
|
|
|
|
<h1>Input/Output and Networking</h1>
|
|
|
|
<p>These classes are used to handle input and output
|
|
to and from external devices, processes, files etc. as
|
|
well as manipulating files and directories.</p>
|
|
|
|
<p>
|
|
<table width="100%">
|
|
<tr valign="top" bgcolor="#e0e0e0">
|
|
<td><b>
|
|
<a href="http://qt.nokia.com/doc/4.0/qabstractsocket.html">QAbstractSocket</a>
|
|
</b></td>
|
|
<td>
|
|
The base functionality common to all socket types
|
|
</td></tr>
|
|
|
|
<tr valign="top" bgcolor="#e0e0e0">
|
|
<td><b>
|
|
<a href="http://qt.nokia.com/doc/4.0/qbuffer.html">QBuffer</a>
|
|
</b></td>
|
|
<td>
|
|
QIODevice interface for a QByteArray
|
|
</td></tr>
|
|
|
|
<tr valign="top" bgcolor="#e0e0e0">
|
|
<td><b>
|
|
<a href="http://qt.nokia.com/doc/4.0/qclipboard.html">QClipboard</a>
|
|
</b></td>
|
|
<td>
|
|
Access to the window system clipboard
|
|
</td></tr>
|
|
</table>
|
|
\endraw
|
|
\endquotation
|
|
|
|
Note that overview pages related to the group, must be listed
|
|
explicitly using the \l {generatelist-command} {\\generatelist}
|
|
command with the \c related argument.
|
|
|
|
\code
|
|
/ *!
|
|
\group architecture
|
|
|
|
\title Architecture
|
|
|
|
These documents describe aspects of Qt's architecture
|
|
and design, including overviews of core Qt features and
|
|
technologies.
|
|
|
|
\generatelist{related}
|
|
* /
|
|
\endcode
|
|
|
|
See also \l {ingroup-command} {\\ingroup} and \l
|
|
{generatelist-command} {\\generatelist}.
|
|
|
|
\target headerfile-command
|
|
\section1 \\headerfile
|
|
|
|
The \\headerfile command is for documenting the global functions,
|
|
types and macros that are declared in a header file but not in a
|
|
namespace. The argument is the name of the header file. The HTML
|
|
page is written to a \c {.html} file constructed from the header
|
|
file aregument.
|
|
|
|
The documentation for a function, type, or macro that is declared
|
|
in the header file being documented is included in the header file
|
|
page using the \l {relates-command} {\\relates} command.
|
|
|
|
If the argument doesn't exist as a header file, the \\headerfile
|
|
command creates a documentation page for the header file anyway.
|
|
|
|
\code
|
|
/ *!
|
|
\headerfile <QtAlgorithms>
|
|
|
|
\title Generic Algorithms
|
|
|
|
\brief The <QtAlgorithms> header file provides
|
|
generic template-based algorithms.
|
|
|
|
Qt provides a number of global template functions in \c
|
|
<QtAlgorithms> that work on containers and perform
|
|
well-know algorithms.
|
|
* /
|
|
\endcode
|
|
|
|
QDoc generates a header file page \c{qtalgorithms.html} that looks
|
|
like this:
|
|
|
|
\quotation
|
|
\raw HTML
|
|
<center><h1><QtAlgorithms> -
|
|
Generic Algorithms</h1></center>
|
|
<p>The <QtAlgorithms> header file provides generic
|
|
template-based algorithms.
|
|
<a href="13-qdoc-commands-topics.html#header-command">More...</a>
|
|
</p>
|
|
|
|
<h3>Functions</h3>
|
|
<ul>
|
|
<li>RandomAccessIterator
|
|
<a href="http://qt.nokia.com/doc/4.0/qlineedit.html#EchoMode-enum">qBinaryFind</a></b>
|
|
(RandomAccessIterator begin, RandomAccessIterator end,
|
|
const T & value)</li>
|
|
<li>...</li></ul>
|
|
<hr />
|
|
\endraw
|
|
|
|
\target header
|
|
|
|
\raw HTML
|
|
<h2>Detailed Description</h2>
|
|
<p>The <QtAlgorithms> header file provides generic
|
|
template-based algorithms. </p>
|
|
\endraw
|
|
|
|
Qt provides a number of global template functions in \c
|
|
<QtAlgorithms> that work on containers and perform
|
|
well-know algorithms.
|
|
|
|
...
|
|
\endquotation
|
|
|
|
\target macro-command
|
|
\section1 \\macro
|
|
|
|
The \\macro command is for documententin a C++ macro. The argument
|
|
is the macro in one of three styles: function-like macros like
|
|
Q_ASSERT(), declaration-style macros like Q_PROPERTY(), and macros
|
|
without parentheses like Q_OBJECT.
|
|
|
|
The \\macro comment must contain a \l {relates-command}
|
|
{\\relates} command that attaches the macro comment to a class,
|
|
header file, or namespace. Otherwise, the documentation will be
|
|
lost. Here are three example macro comments followed by what they
|
|
might look like in \c {qtglobal.html} or \c {qobject.html}:
|
|
|
|
\code
|
|
/ *!
|
|
\macro void Q_ASSERT(bool test)
|
|
\relates <QtGlobal>
|
|
|
|
Prints a warning message containing the source code
|
|
file name and line number if \a test is false.
|
|
|
|
...
|
|
|
|
\sa Q_ASSERT_X(), qFatal(), {Debugging Techniques}
|
|
* /
|
|
\endcode
|
|
|
|
\quotation
|
|
\raw HTML
|
|
<h3>void Q_ASSERT ( bool <i>test</i> )</h3>
|
|
\endraw
|
|
|
|
Prints a warning message containing the source code
|
|
file name and line number if \a test is false.
|
|
|
|
...
|
|
|
|
See also Q_ASSERT_X(), qFatal() and \l {Debugging Techniques}.
|
|
|
|
\endquotation
|
|
|
|
\code
|
|
/ *!
|
|
\macro Q_PROPERTY(...)
|
|
\relates QObject
|
|
|
|
This macro declares a QObject property. The syntax is:
|
|
|
|
...
|
|
|
|
\sa {Qt's Property System}
|
|
* /
|
|
\endcode
|
|
|
|
\quotation
|
|
\raw HTML
|
|
<h3>Q_PROPERTY ( ... )</h3>
|
|
\endraw
|
|
|
|
This macro declares a QObject property. The syntax is:
|
|
|
|
...
|
|
|
|
See also \l {Qt's Property System}.
|
|
\endquotation
|
|
|
|
\code
|
|
/ *!
|
|
\macro Q_OBJECT
|
|
\relates QObject
|
|
|
|
The Q_OBJECT macro must appear in the private section
|
|
of a class definition that declares its own signals and
|
|
slots or that uses other services provided by Qt's
|
|
meta-object system.
|
|
|
|
...
|
|
|
|
\sa {Meta-Object System}, {Signals and Slots}, {Qt's
|
|
Property System}
|
|
* /
|
|
\endcode
|
|
|
|
\quotation
|
|
\raw HTML
|
|
<h3>Q_OBJECT</h3>
|
|
\endraw
|
|
|
|
The Q_OBJECT macro must appear in the private section
|
|
of a class definition that declares its own signals and
|
|
slots or that uses other services provided by Qt's
|
|
meta-object system.
|
|
|
|
...
|
|
|
|
See also \l {Meta-Object System}, \l {Signals &
|
|
Slots} and \l {Qt's Property System}.
|
|
\endquotation
|
|
|
|
\target module-command
|
|
\section1 \\module
|
|
|
|
The \\module creates a page that lists the classes belonging to
|
|
the module specified by the command's argument. A class included
|
|
in the module by including the \l {inmodule-command} {\\inmodule}
|
|
command in the \\class comment.
|
|
|
|
The \\module command is typically followed by a \l {title-command}
|
|
{\\title} and a \l {brief-command} {\\brief} command. Each class
|
|
is listed as a link to the class reference page followed by the
|
|
text from the class's \l {brief-command} {\\brief} command. For
|
|
example:
|
|
|
|
\code
|
|
/ *!
|
|
\module QtNetwork
|
|
|
|
\title QtNetwork Module
|
|
|
|
\brief The QtNetwork module offers classes that allow
|
|
you to write TCP/IP clients and servers.
|
|
|
|
The network module provides classes to make network
|
|
programming easier and portable. It offers both
|
|
high-level classes such as QHttp and QFtp that
|
|
implement specific application-level protocols, and
|
|
lower-level classes such as QTcpSocket, QTcpServer, and
|
|
QUdpSocket.
|
|
* /
|
|
\endcode
|
|
|
|
QDoc renders this in \c {qtnetwork.html} like this:
|
|
|
|
\quotation
|
|
\raw HTML
|
|
<h1><center>QtNetwork Module</center></h1>
|
|
\endraw
|
|
|
|
The QtNetwork module offers classes that allow you to
|
|
write TCP/IP clients and servers.\l {module
|
|
details} {More...}
|
|
|
|
\raw HTML
|
|
<p>
|
|
<table width="100%">
|
|
<tr valign="top" bgcolor="#d0d0d0">
|
|
<td><b>
|
|
<a href="http://qt.nokia.com/doc/4.0/qabstractsocket.html">QAbstractSocket</a>
|
|
</b></td>
|
|
<td>
|
|
The base functionality common to all socket types
|
|
</td></tr>
|
|
|
|
<tr valign="top" bgcolor="#d0d0d0">
|
|
<td><b>
|
|
<a href="http://qt.nokia.com/doc/4.0/qftp.html">QFtp</a>
|
|
</b></td>
|
|
<td>
|
|
Implementation of the FTP protocol
|
|
</td></tr>
|
|
|
|
<tr valign="top" bgcolor="#d0d0d0">
|
|
<td>...</td>
|
|
<td>...</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><hr /></p>
|
|
\endraw
|
|
|
|
\target module details
|
|
|
|
\raw HTML
|
|
<h2>Detailed Description</h2>
|
|
|
|
<p>
|
|
The QtNetwork module offers classes that allow you to
|
|
write TCP/IP clients and servers.
|
|
</p>
|
|
|
|
<p>
|
|
The network module provides classes to make network
|
|
programming easier and portable. It offers both
|
|
high-level classes such as QHttp and QFtp that
|
|
implement specific application-level protocols, and
|
|
lower-level classes such as QTcpSocket, QTcpServer, and
|
|
QUdpSocket.
|
|
</p>
|
|
\endraw
|
|
|
|
...
|
|
|
|
\endquotation
|
|
|
|
See also \l {inmodule-command} {\\inmodule}
|
|
|
|
\target namespace-command
|
|
\section1 \\namespace
|
|
|
|
The \\namespace command is for documenting the contents of the C++
|
|
namespace named as its argument. The documentation outline QDoc
|
|
generates for a namespace is similar to the outline it generates
|
|
for a C++ class.
|
|
|
|
\code
|
|
/ *!
|
|
\namespace Qt
|
|
|
|
\brief The Qt namespace contains miscellaneous
|
|
identifiers used throughout the Qt library.
|
|
* /
|
|
\endcode
|
|
|
|
QDoc renders this in \c{qt.html} like this:
|
|
|
|
\quotation
|
|
\raw HTML
|
|
<center><h1>Qt Namespace Reference</h1></center>
|
|
<p>The Qt namespace contains miscellaneous
|
|
identifiers used throughout the Qt library.
|
|
<a href="13-qdoc-commands-topics.html#name">More...</a>
|
|
</p>
|
|
|
|
<pre>#include <Qt></pre>
|
|
<ul>
|
|
<li>
|
|
<a href="http://qt.nokia.com/doc/4.0/qt-qt3.html">
|
|
Qt 3 support members</a></li>
|
|
</ul>
|
|
|
|
|
|
<h3>Types</h3>
|
|
<ul>
|
|
<li>flags
|
|
<a href="http://qt.nokia.com/doc/4.0/qt.html#AlignmentFlag-enum">Alignment</a></b></li>
|
|
<li>...</li></ul>
|
|
<hr />
|
|
\endraw
|
|
|
|
\target name
|
|
|
|
\raw HTML
|
|
<h2>Detailed Description</h2>
|
|
<p>The Qt namespace contains miscellaneous identifiers
|
|
used throughout the Qt library.</p>
|
|
\endraw
|
|
|
|
...
|
|
\endquotation
|
|
|
|
\target page-command
|
|
\section1 \\page
|
|
|
|
The \\page command is for creating a stand-alone documentation
|
|
page. The argument is the name of the file where QDoc should
|
|
store the page. The page title is set using the \l {title-command}
|
|
{\\title} command.
|
|
|
|
\code
|
|
/ *!
|
|
\page aboutqt.html
|
|
|
|
\title About Qt
|
|
|
|
Qt by Trolltech is a C++ toolkit for cross-platform GUI
|
|
application development. Qt provides single-source
|
|
portability across Microsoft Windows, Mac OS X, Linux,
|
|
and all major commercial Unix variants. (A version of
|
|
Qt 4 for embedded Linux will be available in
|
|
August/September 2005.)
|
|
|
|
Qt provides application developers with all the
|
|
functionality needed to build applications with
|
|
state-of-the-art graphical user interfaces. Qt is fully
|
|
object-oriented, easily extensible, and allows true
|
|
component programming.
|
|
|
|
...
|
|
* /
|
|
\endcode
|
|
|
|
QDoc renders this page in \c {aboutqt.html}.
|
|
|
|
\target property-command
|
|
\section1 \\property
|
|
|
|
The \\property command is for documenting a Qt property. The
|
|
argument is the full property name.
|
|
|
|
A property is defined using the Q_PROPERTY() macro. The macro
|
|
takes as arguments the property's name and its set, reset and get
|
|
functions.
|
|
|
|
\code
|
|
Q_PROPERTY(QString state READ state WRITE setState)
|
|
\endcode
|
|
|
|
The set, reset and get functions don't need to be documented,
|
|
documenting the property is sufficient. QDoc will generate a list
|
|
of the access function that will appear in the property
|
|
documentation which in turn will be located in the documentation
|
|
of the class that defines the property.
|
|
|
|
The \\property command comment typically includes a \l
|
|
{brief-command} {\\brief} command. Forproperties the \l
|
|
{brief-command} {\\brief} command's argument is a sentence
|
|
fragment that will be included in a one line description of the
|
|
property. The command follows the same rules for the \l
|
|
{brief-property} {description} as the \l {variable-command}
|
|
{\\variable} command.
|
|
|
|
\code
|
|
/ *!
|
|
\property QPushButton::flat
|
|
\brief whether the border is disabled
|
|
|
|
This property's default is false.
|
|
* /
|
|
\endcode
|
|
|
|
QDoc includes this in \c {qpushbutton.html} like this:
|
|
|
|
\quotation
|
|
\raw HTML
|
|
<h3>flat : bool</h3>
|
|
\endraw
|
|
|
|
This property holds whether the border is disabled.
|
|
|
|
This property's default is false.
|
|
|
|
Access functions:
|
|
|
|
\list
|
|
\o \bold { bool isFlat () const}
|
|
\o \bold { void setFlat ( bool )}
|
|
\endlist
|
|
|
|
\endquotation
|
|
|
|
\code
|
|
/ *!
|
|
\property QWidget::width
|
|
\brief the width of the widget excluding any window frame
|
|
|
|
See the \l {Window Geometry} documentation for an
|
|
overview of window geometry.
|
|
|
|
\sa geometry, height, size
|
|
* /
|
|
\endcode
|
|
|
|
QDoc includes this in \c {qwidget.html} like this:
|
|
|
|
\quotation
|
|
\raw HTML
|
|
<h3>width : const int</h3>
|
|
\endraw
|
|
|
|
This property holds the width of the widget excluding
|
|
any window frame.
|
|
|
|
See the \l {Window Geometry} documentation for an
|
|
overview of window geometry.
|
|
|
|
Access functions:
|
|
|
|
\list
|
|
\o \bold { int width () const}
|
|
\endlist
|
|
|
|
See also \l{QWidget::geometry} {geometry},
|
|
\l{QWidget::height} {height}, and \l{QWidget::size} {size}.
|
|
\endquotation
|
|
|
|
\target service-command
|
|
\section1 \\service
|
|
|
|
The \\service command tells QDoc that a class is a service class
|
|
and names the service. The command takes two arguments, the name
|
|
of the class and the name of the service. Currently, this command
|
|
is not used in the Qt documentation.
|
|
|
|
\code
|
|
/ *!
|
|
\service TimeService Time
|
|
...
|
|
* /
|
|
class TimeService : public QCopObjectService
|
|
{
|
|
...
|
|
}
|
|
\endcode
|
|
|
|
See also \l {class-command} {\\class} and \l
|
|
{generatelist-command} {\\generatelist}.
|
|
|
|
\target qmlattachedproperty-command
|
|
\section1 \\qmlattachedproperty \span {class="newStuff"} {(new)}
|
|
|
|
The \\qmlattachedproperty command is for documenting a QML
|
|
property that will be attached to some QML element type. See
|
|
\l{http://doc.trolltech.com/4.7/qdeclarativeintroduction.html#attached-properties}
|
|
{Attached Properties}. The argument is the rest of the line. The
|
|
argument text should be the property type, followed by the QML
|
|
element name where the property is being declared, the \c{::}
|
|
qualifier, and finally the property name. If we have a QML
|
|
attached property named \c isCurrentItem in QML element \c ListView,
|
|
and the property has type \c {bool}, the \\qmlattachedproperty for
|
|
it would look like this:
|
|
|
|
\code
|
|
/ *!
|
|
\qmlattachedproperty bool ListView::isCurrentItem
|
|
This attached property is true if this delegate is the current
|
|
item; otherwise false.
|
|
|
|
It is attached to each instance of the delegate.
|
|
|
|
This property may be used to adjust the appearance of the current
|
|
item, for example:
|
|
|
|
\snippet doc/src/snippets/declarative/listview/listview.qml isCurrentItem
|
|
* /
|
|
\endcode
|
|
|
|
QDoc includes this attached property on the QML reference page for the
|
|
\l{http://doc.trolltech.com/4.7/qml-listview.html#isCurrentItem-prop}
|
|
{ListView} element.
|
|
|
|
\target qmlattachedsignal-command
|
|
\section1 \\qmlattachedsignal \span {class="newStuff"} {(new)}
|
|
|
|
The \\qmlattachedsignal command is for documenting an attachable
|
|
\l{http://doc.trolltech.com/4.7/qdeclarativeintroduction.html#signal-handlers}
|
|
{signal handler}. The \\qmlattachedsignal command is used just like
|
|
the \l{qmlsignal-command} {\\qmlsignal} command.
|
|
|
|
The argument is the rest of the line. It should be the name of the
|
|
QML element where the signal handler is declared, the \c{::}
|
|
qualifier, and finally the signal handler name. If we have a QML
|
|
attached signal handler named \c onAdd() in the \c GridView
|
|
element, the \\qmlattachedsignal for it would look like this:
|
|
|
|
\code
|
|
/ *!
|
|
\qmlattachedsignal GridView::onAdd()
|
|
This attached handler is called immediately after an item is
|
|
added to the view.
|
|
* /
|
|
\endcode
|
|
|
|
QDoc includes this documentation on the QML reference page for the
|
|
\l{http://doc.trolltech.com/4.7/qml-gridview.html#onAdd-signal}
|
|
{GridView} element.
|
|
|
|
\target qmlbasictype-command
|
|
\section1 \\qmlbasictype \span {class="newStuff"} {(new)}
|
|
|
|
The \\qmlbasictype command is for documenting a basic type for QML.
|
|
The argument is the type name. The type must be included in the
|
|
QML basic types group using the \l{ingroup-command}{\\ingroup}
|
|
command as shown below. This will cause QDoc to include the
|
|
documentation for the type on the
|
|
\l{http://doc.trolltech.com/4.7/qdeclarativebasictypes.html}
|
|
{QML Basic Types} page. The \l{brief-command} {\\brief} command
|
|
is also required, because it appears on the
|
|
\l{http://doc.trolltech.com/4.7/qdeclarativebasictypes.html}
|
|
{QML Basic Types} page as well.
|
|
|
|
\code
|
|
/ *!
|
|
\qmlbasictype int
|
|
\ingroup qmlbasictypes
|
|
|
|
\brief An integer is a whole number, e.g. 0, 10, or -20.
|
|
|
|
An integer is a whole number, e.g. 0, 10, or -20. The possible
|
|
\c int values range from around -2000000000 to around
|
|
2000000000, although most elements will only accept a reduced
|
|
range (which they mention in their documentation).
|
|
|
|
Example:
|
|
\qml
|
|
Item { width: 100; height: 200 }
|
|
\endqml
|
|
|
|
\sa {QML Basic Types}
|
|
* /
|
|
\endcode
|
|
|
|
QDoc outputs this as \l{http://doc.trolltech.com/4.7/qml-int.html}
|
|
{qml-int.html}.
|
|
|
|
\target qmlclass-command
|
|
\section1 \\qmlclass \span {class="newStuff"} {(new)}
|
|
|
|
The \\qmlclass command is for documenting a QML element that is
|
|
instantiated by a C++ class. The command has two arguments. The
|
|
first argument is the name of the QML element. The second argument
|
|
is the name of the C++ class that instantiates the QML element.
|
|
|
|
\code
|
|
/ *!
|
|
\qmlclass Transform QGraphicsTransform
|
|
\ingroup qml-transform-elements
|
|
\since 4.7
|
|
\brief The Transform elements provide a way of building
|
|
advanced transformations on Items.
|
|
|
|
The Transform element is a base type which cannot be
|
|
instantiated directly. The following concrete Transform types
|
|
are available:
|
|
|
|
\list
|
|
\o \l Rotation
|
|
\o \l Scale
|
|
\o \l Translate
|
|
\endlist
|
|
|
|
The Transform elements let you create and control advanced
|
|
transformations that can be configured independently using
|
|
specialized properties.
|
|
|
|
You can assign any number of Transform elements to an \l
|
|
Item. Each Transform is applied in order, one at a time.
|
|
|
|
* /
|
|
\endcode
|
|
|
|
This example generates the
|
|
\l {http://doc.trolltech.com/4.7/qml-transform.html} {QML Trasform
|
|
Element} page. The \\qmlclass comment should include the \l
|
|
{since-command} {\\since} command, because all QML elements are
|
|
new. It should also include the \l{brief-command} {\\brief}
|
|
command. And since every QML element is a member of a group of QML
|
|
elements, it should also include one or more \l{ingroup-command}
|
|
{\\ingroup} commands.
|
|
|
|
\target qmlmethod-command
|
|
\section1 \\qmlmethod \span {class="newStuff"} {(new)}
|
|
|
|
The \\qmlmethod command is for documenting a QML method. The
|
|
argument is the complete method signature, including return
|
|
type and parameter names and types.
|
|
|
|
\code
|
|
/ *!
|
|
\qmlmethod void TextInput::select(int start, int end)
|
|
|
|
Causes the text from \a start to \a end to be selected.
|
|
|
|
If either start or end is out of range, the selection is not changed.
|
|
|
|
After calling this, selectionStart will become the lesser and
|
|
selectionEnd will become the greater (regardless of the order
|
|
passed to this method).
|
|
|
|
\sa selectionStart, selectionEnd
|
|
* /
|
|
\endcode
|
|
|
|
QDoc includes this documentation on the element refence page for the
|
|
\l{http://doc.trolltech.com/4.7/qml-textinput.html#select-method}
|
|
{TextInput} element.
|
|
|
|
\target qmlproperty-command
|
|
\section1 \\qmlproperty \span {class="newStuff"} {(new)}
|
|
|
|
The \\qmlproperty command is for documenting a QML property. The
|
|
argument is the rest of the line. The argument text should be the
|
|
property type, followed by the QML element name, the \c{::}
|
|
qualifier, and finally the property name. If we have a QML
|
|
property named \c x in QML element \c Translate, and the property
|
|
has type \c {real}, the \\qmlproperty for it would look like this:
|
|
|
|
\code
|
|
/ *!
|
|
\qmlproperty real Translate::x
|
|
|
|
The translation along the X axis.
|
|
* /
|
|
\endcode
|
|
|
|
QDoc includes this QML property on the QML reference page for the
|
|
\l {http://doc.trolltech.com/4.7/qml-translate.html} {Translate}
|
|
element.
|
|
|
|
\target qmlsignal-command
|
|
\section1 \\qmlsignal \span {class="newStuff"} {(new)}
|
|
|
|
The \\qmlsignal command is for documenting a
|
|
\l{http://doc.trolltech.com/4.7/qdeclarativeintroduction.html#signal-handlers}
|
|
{signal handler}.
|
|
The argument is the rest of the line. It should be the QML element where the
|
|
signal handler is declared, the \c{::} qualifier, and finally the signal
|
|
handler name. If we have a QML signal handler named \c onAdd() in QML
|
|
element \c MouseArea, the \\qmlsignal for it would look like this:
|
|
|
|
\code
|
|
/ *!
|
|
\qmlsignal MouseArea::onEntered()
|
|
|
|
This handler is called when the mouse enters the mouse area.
|
|
|
|
By default the onEntered handler is only called while a button is
|
|
pressed. Setting hoverEnabled to true enables handling of
|
|
onEntered when no mouse button is pressed.
|
|
|
|
\sa hoverEnabled
|
|
* /
|
|
\endcode
|
|
|
|
QDoc includes this documentation on the QML reference page for the
|
|
\l{http://doc.trolltech.com/4.7/qml-mousearea.html#onEntered-signal}
|
|
{MouseArea} element.
|
|
|
|
\target typedef-command
|
|
\section1 \\typedef
|
|
|
|
The \\typedef command is for documenting a C++ typedef. The
|
|
argument is the name of the typedef. The documentation for
|
|
the typedef will be included in the refernece documentation
|
|
for the class, namespace, or header file in which the typedef
|
|
is declared. To relat the \\typedef to a class, namespace, or
|
|
header file, the \\typedef comment must contain a
|
|
\l {relates-command} {\\relates} command.
|
|
|
|
\code
|
|
/ *!
|
|
\typedef QObjectList
|
|
\relates QObject
|
|
|
|
Synonym for QList<QObject>.
|
|
* /
|
|
\endcode
|
|
|
|
QDoc includes this in \c {qobject.html} as:
|
|
|
|
\quotation
|
|
\raw HTML
|
|
<h3>typedef QObjectList</h3>
|
|
\endraw
|
|
|
|
Synonym for QList<QObject>.
|
|
\endquotation
|
|
|
|
Another, although more rare, example:
|
|
|
|
\code
|
|
/ *!
|
|
\typedef QMsgHandler
|
|
\relates QtGlobal
|
|
|
|
This is a typedef for a pointer to a function with the
|
|
following signature:
|
|
|
|
\code
|
|
void myMsgHandler(QtMsgType, const char *);
|
|
\ endcode
|
|
|
|
\sa QtMsgType, qInstallMsgHandler()
|
|
* /
|
|
\endcode
|
|
|
|
QDoc includes this in \c {qtglobal.html} as:
|
|
|
|
\quotation
|
|
\raw HTML
|
|
<h3>typedef QtMsgHandler</h3>
|
|
\endraw
|
|
|
|
This is a typedef for a pointer to a function with the
|
|
following signature:
|
|
|
|
\raw HTML
|
|
<tt>
|
|
<pre> void myMsgHandler(QtMsgType, const char *);</pre>
|
|
</tt>
|
|
\endraw
|
|
|
|
See also QtMsgType and qInstallMsgHandler().
|
|
\endquotation
|
|
|
|
Other typedefs are located on the reference page for the class
|
|
that defines them.
|
|
|
|
\code
|
|
/ *!
|
|
\typedef QLinkedList::Iterator
|
|
|
|
Qt-style synonym for QList::iterator.
|
|
* /
|
|
\endcode
|
|
|
|
QDoc includes this one on the reference page for class QLinkedList as:
|
|
|
|
\quotation
|
|
\raw HTML
|
|
<h3>typedef QLinkedList::Iterator</h3>
|
|
\endraw
|
|
|
|
Qt-style synonym for QList::iterator.
|
|
\endquotation
|
|
|
|
\target variable-command
|
|
\section1 \\variable
|
|
|
|
The \\variable command is for documenting a class member variable
|
|
or a constant. The argument is the variable or constant name. The
|
|
\\variable command comment includes a \l {brief-command} {\\brief}
|
|
command. QDoc generates the documentation based on the text from
|
|
\\brief command.
|
|
|
|
The documentation will be located in the in the associated class,
|
|
header file or namespace documentation.
|
|
|
|
In case of a member variable:
|
|
|
|
\code
|
|
/ *!
|
|
\variable QStyleOption::palette
|
|
\brief the palette that should be used when painting
|
|
the control
|
|
* /
|
|
\endcode
|
|
|
|
QDoc includes this in qstyleoption.html as:
|
|
|
|
\quotation
|
|
\raw HTML
|
|
<h3>
|
|
<a href="http://qt.nokia.com/doc/4.0/qpalette.html">
|
|
QPalette
|
|
</a>
|
|
QStyleOption::palette
|
|
</h3>
|
|
\endraw
|
|
|
|
This variable holds the palette that should be used
|
|
when painting the control.
|
|
\endquotation
|
|
|
|
You can also document constants with the \\variable command. For
|
|
example, suppose you have the \c Type and \c UserType constants in
|
|
the QTreeWidgetItem class:
|
|
|
|
\code
|
|
enum { Type = 0, UserType = 1000 };
|
|
\endcode
|
|
|
|
For these, the \\vaqriable command can be used this way:
|
|
|
|
\code
|
|
/ *!
|
|
\variable QTreeWidgetItem::Type
|
|
|
|
The default type for tree widget items.
|
|
|
|
\sa UserType, type()
|
|
* /
|
|
\endcode
|
|
\code
|
|
/ *!
|
|
\variable QTreeWidgetItem::UserType
|
|
|
|
The minimum value for custom types. Values below
|
|
UserType are reserved by Qt.
|
|
|
|
\sa Type, type()
|
|
* /
|
|
\endcode
|
|
|
|
QDoc includes these in qtreewidget.html as:
|
|
|
|
\quotation
|
|
\raw HTML
|
|
<h3>
|
|
const int QTreeWidgetItem::Type
|
|
</h3>
|
|
\endraw
|
|
|
|
The default type for tree widget items.
|
|
|
|
See also \l {QTreeWidgetItem::UserType} {UserType} and \l
|
|
{QTreeWidgetItem::type()} {type()}.
|
|
|
|
\raw HTML
|
|
<h3>
|
|
const int QTreeWidgetItem::UserType
|
|
</h3>
|
|
\endraw
|
|
|
|
The minimum value for custom types. Values below
|
|
UserType are reserved by Qt.
|
|
|
|
See also \l {QTreeWidgetItem::Type} {Type} and
|
|
\l{QTreeWidgetItem::type()} {type()}.
|
|
|
|
\endquotation
|
|
*/
|
|
|
|
/*!
|
|
\page 14-qdoc-commands-contextcommands.html
|
|
\previouspage Topic Commands
|
|
\contentspage Table of Contents
|
|
\nextpage Document Navigation
|
|
|
|
\title Context Commands
|
|
|
|
The context commands provide information about the element being
|
|
documented that QDoc can't deduce on its own. e.g. Is a class
|
|
thread-safe? Is a function reentrant? Which module is the class a
|
|
member of? Context commands can appear anywhere in a QDoc comment,
|
|
but they are normally placed near the top of the comment, just
|
|
below the \l {Topic Commands} {topic} command.
|
|
|
|
\list
|
|
\o \l {16-qdoc-commands-status.html#compat-command}{\\compat},
|
|
\o \l {15-qdoc-commands-navigation.html#contentspage-command}{\\contentspage},
|
|
\o \l {15-qdoc-commands-navigation.html#indexpage-command}{\\indexpage},
|
|
\o \l {19-qdoc-commands-grouping.html#ingroup-command}{\\ingroup},
|
|
\o \l {18-qdoc-commands-relating.html#inherits-command}{\\inherits},
|
|
\o \l {19-qdoc-commands-grouping.html#inmodule-command}{\\inmodule},
|
|
\o \l {16-qdoc-commands-status.html#internal-command}{\\internal},
|
|
\o \l {19-qdoc-commands-grouping.html#mainclass-command}{\\mainclass},
|
|
\o \l {15-qdoc-commands-navigation.html#nextpage-command}{\\nextpage},
|
|
\o \l {17-qdoc-commands-thread.html#nonreentrant-command}{\\nonreentrant},
|
|
\o \l {16-qdoc-commands-status.html#obsolete-command}{\\obsolete},
|
|
\o \l {18-qdoc-commands-relating.html#overload-command}{\\overload},
|
|
\o \l {16-qdoc-commands-status.html#preliminary-command}{\\preliminary},
|
|
\o \l {15-qdoc-commands-navigation.html#previouspage-command}{\\previouspage},
|
|
\o \l {17-qdoc-commands-thread.html#reentrant-command}{\\reentrant},
|
|
\o \l {18-qdoc-commands-relating.html#reimp-command}{\\reimp},
|
|
\o \l {18-qdoc-commands-relating.html#relates-command}{\\relates},
|
|
\o \l {16-qdoc-commands-status.html#since-command}{\\since},
|
|
\o \l {15-qdoc-commands-navigation.html#startpage-command}{\\startpage},
|
|
\o \l {20-qdoc-commands-namingthings.html#subtitle-command}{\\subtitle}
|
|
\o \l {17-qdoc-commands-thread.html#threadsafe-command}{\\threadsafe},
|
|
\o \l {20-qdoc-commands-namingthings.html#title-command}{\\title}
|
|
\endlist
|
|
|
|
*/
|
|
|
|
/*!
|
|
\page 15-qdoc-commands-navigation.html
|
|
\previouspage Context Commands
|
|
\contentspage Table of Contents
|
|
\nextpage Reporting Status
|
|
|
|
\title Document Navigation
|
|
|
|
The navigation commands are for linking the pages of a document in
|
|
a meaningful sequence. Below is a sequence of QDoc comments that
|
|
shows a typical use of the navigation commands.
|
|
|
|
\section1 Example
|
|
|
|
\code
|
|
/ *!
|
|
\page basicqt.html
|
|
\contentspage {Basic Qt} {Contents}
|
|
\nextpage Getting Started
|
|
|
|
\indexpage Index
|
|
\startpage Basic Qt
|
|
|
|
\title Basic Qt
|
|
|
|
The Qt toolkit is a C++ class library and a set of tools for
|
|
building multiplatform GUI programs using a "write once,
|
|
compile anywhere approach".
|
|
|
|
Table of contents:
|
|
|
|
\list
|
|
\o \l {Getting Started}
|
|
\o \l {Creating Dialogs}
|
|
\o \l {Creating Main Windows}
|
|
\endlist
|
|
* /
|
|
|
|
/ *!
|
|
\page gettingstarted.html
|
|
\previouspage Basic Qt
|
|
\contentspage {Basic Qt} {Contents}
|
|
\nextpage Creating Dialogs
|
|
|
|
\indexpage Index
|
|
\startpage Basic Qt
|
|
|
|
\title Getting Started
|
|
|
|
This chapter shows how to combine basic C++ with the
|
|
functionality provided by Qt to create a few small graphical
|
|
interface (GUI) applications.
|
|
* /
|
|
|
|
/ *!
|
|
\page creatingdialogs.html
|
|
\previouspage Getting Started
|
|
\contentspage {Basic Qt} {Contents}
|
|
|
|
\indexpage Index
|
|
\startpage Basic Qt
|
|
|
|
\title Creating Dialogs
|
|
|
|
This chapter will teach you how to create dialog boxes using Qt.
|
|
* /
|
|
|
|
/ *!
|
|
\page index.html
|
|
|
|
\indexpage Index
|
|
\startpage Basic Qt
|
|
|
|
\title Index
|
|
|
|
\list
|
|
\o \l {Basic Qt}
|
|
\o \l {Creating Dialogs}
|
|
\o \l {Getting Started}
|
|
\endlist
|
|
* /
|
|
\endcode
|
|
|
|
QDoc renders the "Getting Started" page in \c{creatingdialogs.html}:
|
|
|
|
\quotation
|
|
\raw HTML
|
|
<table border="0" cellpadding="0" cellspacing="5" width="100%">
|
|
|
|
<tr>
|
|
<p>
|
|
[Previous: <a href="15-qdoc-commands-navigation.html#deadlink">
|
|
Basic Qt</a>]
|
|
[<a href="15-qdoc-commands-navigation.html#deadlink">Contents</a>]
|
|
[Next: <a href="15-qdoc-commands-navigation.html#deadlink">
|
|
Creating Dialogs</a>]
|
|
</p>
|
|
|
|
<h1 align="center">Getting Started<br /></h1>
|
|
|
|
<p>
|
|
This chapter shows how to combine basic C++ with the
|
|
functionality provided by Qt to create a few small graphical
|
|
interface (GUI) applications.
|
|
</p>
|
|
|
|
<p>
|
|
[Previous: <a href="15-qdoc-commands-navigation.html#deadlink">
|
|
Basic Qt</a>]
|
|
[<a href="15-qdoc-commands-navigation.html#deadlink">Contents</a>]
|
|
[Next: <a href="15-qdoc-commands-navigation.html#deadlink">
|
|
Creating Dialogs</a>]
|
|
</p>
|
|
|
|
</table>
|
|
\endraw
|
|
\endquotation
|
|
|
|
The \l {indexpage-command} {\\indexpage} and \l
|
|
{startpage-command} {\\startpage} commands create links to the
|
|
page's index page and start page. These links can be used by
|
|
browsers and search engines.
|
|
|
|
The index page is typically an alphabetical list of the document's
|
|
titles and topics, while the start page is the page considered by
|
|
the author to be the starting point of a multipage document.
|
|
|
|
The links are included in the generated HTML source code but have
|
|
no visual effect on the documentation:
|
|
|
|
\code
|
|
<head>
|
|
...
|
|
<link rel="index" href="index.html" />
|
|
<link rel="start" href="basicqt.html" />
|
|
...
|
|
</head>
|
|
\endcode
|
|
|
|
\section1 Commands
|
|
|
|
\target previouspage-command
|
|
\section2 \\previouspage
|
|
|
|
The \\previouspage command links the current page to the previous
|
|
page in a sequence.a The command has two arguments, each enclosed
|
|
by curly braces: The first is the link target, i.e. the title of
|
|
the previous page, the second is the link text. If the page's
|
|
title is equivalent to the link text, the second argument can be
|
|
omitted.
|
|
|
|
The command must stand alone on its own line.
|
|
|
|
\target nextpage-command
|
|
\section2 \\nextpage
|
|
|
|
The \\nextpage command links the current page to the next page in
|
|
a sequence. The command follows the same syntax and argument
|
|
convention as the \l {previouspage-command} {\\previouspage}
|
|
command.
|
|
|
|
\target startpage-command
|
|
\section2 \\startpage
|
|
|
|
The \\startpage command specifies the first page of a sequence of
|
|
pages. The command must stand alone on its own line, and its
|
|
unique argument is the title of the first document.
|
|
|
|
QDoc will generate a link to the start page and include it in the
|
|
generated HTML file, but this has no visual effect on the
|
|
documentation. The generated link type tells browsers and search
|
|
engines which document is considered by the author to be the
|
|
starting point of the collection.
|
|
|
|
\target contentspage-command
|
|
\section2 \\contentspage
|
|
|
|
The \\contentspage command links the current page to a table of
|
|
contents page. The command follows the same syntax and argument
|
|
convention as the \l {previouspage-command} {\\previouspage}
|
|
command.
|
|
|
|
\target indexpage-command
|
|
\section2 \\indexpage
|
|
|
|
The \\indexpage command specifies an index page for the current
|
|
document. The command must stand alone on its own line, and its
|
|
unique argument is the title of the index document.
|
|
|
|
QDoc will generate a link to the index page and include it in the
|
|
generated HTML file, but this has no visual effect on the
|
|
documentation. The generated link type tells browsers and search
|
|
engines which document is considered by the author to be the
|
|
index page of the collection.
|
|
*/
|
|
|
|
/*!
|
|
\page 16-qdoc-commands-status.html
|
|
\previouspage Document Navigation
|
|
\contentspage Table of Contents
|
|
\nextpage Thread Support
|
|
|
|
\title Reporting Status
|
|
|
|
These commands are for indicating that a documented element is
|
|
still under development, is becoming obsolete, is provided for
|
|
compatibility reasons, or is simply not to be included in the
|
|
public interface. The \l {since-command}{\\since} command is for
|
|
including information about the version when a function or class
|
|
first appeared.
|
|
|
|
\target compat-command
|
|
\section1 \\compat
|
|
|
|
The \\compat command is for indicating that a class or function is
|
|
part of the support library provided to keep old source code
|
|
working.
|
|
|
|
The command must stand on its own line.
|
|
|
|
Usually an equivalent function or class is provided as an
|
|
alternative.
|
|
|
|
If the command is used in the documentation of a class, the
|
|
command expands to a warning that the referenced class is part of
|
|
the support library. The warning is located at the top of the
|
|
documentation page.
|
|
|
|
\code
|
|
/ *!
|
|
\class MyQt3SupportClass
|
|
\compat
|
|
* /
|
|
\endcode
|
|
|
|
QDoc renders this at the top of the MyQt3SupportClass class
|
|
reference page.
|
|
|
|
\quotation
|
|
\bold {This class is part of the Qt 3 support
|
|
library.} It is provided to keep old source code
|
|
working. We strongly advise against using it in new
|
|
code. See the \l
|
|
{http://qt.nokia.com/doc/4.0/porting4.html} {Porting
|
|
Guide} for more information.
|
|
\endquotation
|
|
|
|
If the command is used when documenting a function, QDoc will
|
|
create and link to a separate page documenting Qt 3 support
|
|
members when generating the reference documentation for the
|
|
associated class.
|
|
|
|
\code
|
|
/ *!
|
|
\fn MyClass::MyQt3SupportMemberFunction
|
|
\compat
|
|
|
|
Use MyNewFunction() instead.
|
|
* /
|
|
\endcode
|
|
|
|
QDoc renders this in \c{myclass-qt3.html} as:
|
|
|
|
\quotation
|
|
\raw HTML
|
|
<h1>Qt 3 Support Members for MyClass</h1>
|
|
\endraw
|
|
|
|
\bold {The following class members are part of the Qt 3
|
|
support layer.} They are provided to help you port old code to
|
|
Qt 4. We advise against using them in new code.
|
|
|
|
...
|
|
|
|
\list
|
|
\o void MyQt3SupportMemberFunction()
|
|
\o ...
|
|
\endlist
|
|
|
|
\raw HTML
|
|
<hr />
|
|
<h2>Member Function Documentation</h2>
|
|
<h3>void MyQt3SupportMemberFunction ()</h3>
|
|
<p>Use MyNewFunction() instead.</p>
|
|
\endraw
|
|
...
|
|
\endquotation
|
|
|
|
\target default-command
|
|
\section1 \\default \span {class="newStuff"} {(new)}
|
|
|
|
The \\default command is for marking a QML property as the
|
|
\l {http://doc.trolltech.com/4.7/qdeclarativeintroduction.html#default-properties}
|
|
{default property}. The word \span {class="newStuff"} {default} is shown in red in
|
|
the documentation of the property.
|
|
|
|
\code
|
|
/ *!
|
|
\qmlproperty list<Change> State::changes
|
|
This property holds the changes to apply for this state
|
|
\default
|
|
|
|
By default these changes are applied against the default state. If the state
|
|
extends another state, then the changes are applied against the state being
|
|
extended.
|
|
* /
|
|
\endcode
|
|
|
|
See how QDoc renders this property on the reference page for the
|
|
\l {http://doc.trolltech.com/4.7/qml-state.html#changes-prop} {State}
|
|
element.
|
|
|
|
\target obsolete-command
|
|
\section1 \\obsolete
|
|
|
|
The \\obsolete command is for indicating that a function is being
|
|
deprecated, and it should no longer be used in new code. There is
|
|
no guarantee for how long it will remain in the library.
|
|
|
|
The command must stand on its own line.
|
|
|
|
When generating the reference documentation for a class, QDoc will
|
|
create and link to a separate page documenting its obsolete
|
|
functions. Usually an equivalent function is provided as an
|
|
alternative.
|
|
|
|
\code
|
|
/ *!
|
|
\fn MyClass::MyObsoleteFunction
|
|
\obsolete
|
|
|
|
Use MyNewFunction() instead.
|
|
* /
|
|
\endcode
|
|
|
|
QDoc renders this in \c{myclass-obsolete.html} as:
|
|
|
|
\quotation
|
|
\raw HTML
|
|
<h1>Obsolete Members for MyClass</h1>
|
|
\endraw
|
|
|
|
\bold {The following class members are obsolete.} They are
|
|
provided to keep old source code working. We strongly advise
|
|
against using them in new code.
|
|
|
|
...
|
|
|
|
\list
|
|
\o void MyObsoleteFunction() \c (obsolete)
|
|
\o ...
|
|
\endlist
|
|
|
|
\raw HTML
|
|
<hr />
|
|
<h2>Member Function Documentation</h2>
|
|
<h3>void MyObsoleteFunction ()</h3>
|
|
<p>Use MyNewFunction() instead.</p>
|
|
\endraw
|
|
...
|
|
\endquotation
|
|
|
|
\target internal-command
|
|
\section1 \\internal
|
|
|
|
The \\internal command indicates that the referenced
|
|
function is not part of the public interface.
|
|
|
|
The command must stand on its own line.
|
|
|
|
QDoc ignores the documentation as well as the documented item,
|
|
when generating the associated class reference documenation.
|
|
|
|
\code
|
|
/ *!
|
|
\internal
|
|
|
|
Tries to find the decimal separator. If it can't find
|
|
it and the thousand delimiter is != '.' it will try to
|
|
find a '.';
|
|
* /
|
|
int QDoubleSpinBoxPrivate::findDelimiter
|
|
(const QString &str, int index) const
|
|
{
|
|
int dotindex = str.indexOf(delimiter, index);
|
|
if (dotindex == -1 && thousand != dot && delimiter != dot)
|
|
dotindex = str.indexOf(dot, index);
|
|
return dotindex;
|
|
}
|
|
\endcode
|
|
|
|
This function will not be included in the documentation.
|
|
|
|
\target preliminary-command
|
|
\section1 \\preliminary
|
|
|
|
The \\preliminary command is for indicating that a referenced
|
|
function is still under development.
|
|
|
|
The command must stand on its own line.
|
|
|
|
The \\preliminary command expands to a notification in the
|
|
function documentation, and marks the function as preliminary when
|
|
it appears in lists.
|
|
|
|
\code
|
|
/ *!
|
|
\preliminary
|
|
|
|
Returns information about the joining properties of the
|
|
character (needed for certain languages such as
|
|
Arabic).
|
|
* /
|
|
QChar::Joining QChar::joining() const
|
|
{
|
|
return ::joining(*this);
|
|
}
|
|
\endcode
|
|
|
|
QDoc renders this as:
|
|
|
|
\quotation
|
|
\raw HTML
|
|
<h3>
|
|
<a href="http://qt.nokia.com/doc/4.0/qchar.html#Joining-enum">Joining</a>
|
|
QChar::joining () const</h3>
|
|
\endraw
|
|
|
|
\bold {This function is under development and
|
|
subject to change.}
|
|
|
|
Returns information about the joining properties of the
|
|
character (needed for certain languages such as
|
|
Arabic).
|
|
\endquotation
|
|
|
|
And the function's entry in QChar's list of functions will be
|
|
rendered as:
|
|
|
|
\quotation
|
|
\list
|
|
\o ...
|
|
\o Joining
|
|
\l {http://qt.nokia.com/doc/4.0/qchar.html#Joining-enum}
|
|
{joining}()
|
|
const \c (preliminary)
|
|
\o ...
|
|
\endlist
|
|
\endquotation
|
|
|
|
\target since-command
|
|
\section1 \\since
|
|
|
|
The \\since command tells in which minor release
|
|
the associated functionality was added.
|
|
|
|
\code
|
|
/ *!
|
|
\since 4.1
|
|
|
|
Returns an icon for \a standardIcon.
|
|
|
|
...
|
|
|
|
\sa standardIconImplementation(), standardPixmap()
|
|
* /
|
|
QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const
|
|
{
|
|
}
|
|
\endcode
|
|
|
|
QDoc renders this as:
|
|
|
|
\quotation
|
|
\raw HTML
|
|
<h3>QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const</h3>
|
|
\endraw
|
|
|
|
This function was introduced in Qt version 4.1
|
|
|
|
Returns an icon for \a standardIcon.
|
|
|
|
...
|
|
|
|
See also \l {QStyle::standardIconImplementation()}
|
|
{standardIconImplementation()} and \l
|
|
{QStyle::standardPixmap()} {standardPixmap()}.
|
|
\endquotation
|
|
|
|
QDoc generates the "Qt" reference from the \l
|
|
{25-qdoc-configuration-derivedprojects.html#project} {\c project}
|
|
configuration variable. For that reason this reference will change
|
|
according to the current documentation project.
|
|
|
|
See also \l {25-qdoc-configuration-derivedprojects.html#project}
|
|
{\c project}.
|
|
*/
|
|
|
|
/*!
|
|
\page 17-qdoc-commands-thread.html
|
|
\previouspage Reporting Status
|
|
\contentspage Table of Contents
|
|
\nextpage Relating Things
|
|
|
|
\title Thread Support
|
|
|
|
The thread support commands are for specifying the level of
|
|
support for multithreaded programming in a class or function.
|
|
There are three levels of support: \c threadsafe, \c reentrant and
|
|
\c nonreentrant.
|
|
|
|
The default is \c nonreentrant which means that the associated
|
|
class or function cannot be called by multiple threads. \c
|
|
Reentrant and \c threadsafe are levels primarily used for classes.
|
|
|
|
\c Reentrant means that all the functions in the referenced class
|
|
can be called simultaneously by multiple threads, provided that
|
|
each invocation of the functions reference unique data. While \c
|
|
threadsafe means that all the functions in the referenced class
|
|
can be called simultaneously by multiple threads even when each
|
|
invocation references shared data.
|
|
|
|
When a class is marked \l {reentrant-command} {\\reentrant} or \l
|
|
{threadsafe-command} {\\threadsafe}, functions in that class can
|
|
be marked \c nonreentrant using the \l {nonreentrant-command}
|
|
{\\nonreentrant} command.
|
|
|
|
\section1 Example
|
|
|
|
\target reentrant-example
|
|
\code
|
|
/ *!
|
|
\class QLocale
|
|
\brief The QLocale class converts between numbers and their
|
|
string representations in various languages.
|
|
|
|
\reentrant
|
|
\ingroup i18n
|
|
\ingroup text
|
|
\mainclass
|
|
|
|
QLocale is initialized with a language/country pair in its
|
|
constructor and offers number-to-string and string-to-number
|
|
conversion functions similar to those in QString.
|
|
|
|
...
|
|
* /
|
|
|
|
/ *!
|
|
\nonreentrant
|
|
|
|
Sets the global default locale to \a locale. These values are
|
|
used when a QLocale object is constructed with no
|
|
arguments. If this function is not called, the system's locale
|
|
is used.
|
|
|
|
\warning In a multithreaded application, the default locale
|
|
should be set at application startup, before any non-GUI
|
|
threads are created.
|
|
|
|
\sa system() c()
|
|
* /
|
|
void QLocale::setDefault(const QLocale &locale)
|
|
{
|
|
default_d = locale.d;
|
|
}
|
|
\endcode
|
|
|
|
QDoc renders this as:
|
|
|
|
\quotation
|
|
\raw HTML
|
|
<h1><center>QLocale Class Reference</center></h1>
|
|
\endraw
|
|
|
|
The QLocale class converts between numbers and their string
|
|
representations in various languages. More...
|
|
|
|
\code
|
|
#include <QLocale>
|
|
\endcode
|
|
|
|
\bold {Note:} All the functions in this class are \l
|
|
{threads.html#reentrant} {reentrant}, except \l
|
|
{QLocale::setDefault()} {setDefault()}.
|
|
|
|
...
|
|
|
|
\raw HTML
|
|
<hr />
|
|
<h2>Member Type Documentation</h2>
|
|
\endraw
|
|
|
|
...
|
|
|
|
\raw HTML
|
|
<h3>void QLocale::setDefault ( const QLocale & locale ) </h3>
|
|
\endraw
|
|
|
|
Sets the global default locale to locale. These values are
|
|
used when a QLocale object is constructed with no
|
|
arguments. If this function is not called, the system's locale
|
|
is used.
|
|
|
|
\warning In a multithreaded application, the default locale
|
|
should be set at application startup, before any non-GUI
|
|
threads are created.
|
|
|
|
\warning This function is not reentrant.
|
|
|
|
See also \l {QLocale::system()} {system()} and \l
|
|
{QLocale::c()} {c()}.
|
|
|
|
...
|
|
\endquotation
|
|
|
|
As shown above, QDoc generates a notification when a class is
|
|
declared reentrant, and lists the exceptions (the declared
|
|
nonreentrant functions). A link to the general documentation on \l
|
|
{threads.html#reentrant} {reentrancy and thread-safety} is
|
|
included. In addition a warning, "\bold Warning: This function is
|
|
not reentrant.", is generated in the nonreentrant functions'
|
|
documentation.
|
|
|
|
QDoc will generate the same notification and warnings when a class
|
|
is declared threadsafe.
|
|
|
|
For more information see the general documentation on \l
|
|
{threads.html#reentrant} {reentrancy and thread-safety}.
|
|
|
|
\section1 Commands
|
|
|
|
\target threadsafe-command
|
|
\section2 \\threadsafe
|
|
|
|
The \\threadsafe command includes a line in the documentation to
|
|
indicate that the associated class or function is \e threadsafe
|
|
and can be called simultaneously by multiple threads, even when
|
|
separate invocations reference shared data.
|
|
|
|
The command must stand on its own line.
|
|
|
|
The documentation generated from this command will be similar to
|
|
the what is generated for the \l {reentrant-command} {\\reentrant}
|
|
command. See the example above in the \l {reentrant-example}
|
|
{introduction}.
|
|
|
|
See also \l{reentrant-command} {\\reentrant} and
|
|
\l{nonreentrant-command} {\\nonreentrant}.
|
|
|
|
\target reentrant-command
|
|
\section2 \\reentrant
|
|
|
|
The \\reentrant command indicates that the associated class or
|
|
function can be called simultaneously by multiple threads,
|
|
provided that each invocation references its own data. See the \l
|
|
{reentrant-example} {example} above.
|
|
|
|
The command must stand on its own line.
|
|
|
|
See also \l{nonreentrant-command} {\\nonreentrant} and
|
|
\l{threadsafe-command} {\\threadsafe}.
|
|
|
|
\target nonreentrant-command
|
|
\section2 \\nonreentrant
|
|
|
|
The \\nonreentrant command indicates that the associated class or
|
|
function cannot be called by multiple threads. Nonreentrant is the
|
|
default case.
|
|
|
|
The command must stand on its own line.
|
|
|
|
When a class is marked \l {reentrant-command} {\\reentrant} or \l
|
|
{threadsafe-command} {\\threadsafe}, functions in that class can
|
|
be marked \c nonreentrant using this command in the \l{fn-command}
|
|
{\\fn} comment of the functions to be excluded.
|
|
|
|
See also \l{reentrant-command} {\\reentrant} and
|
|
\l{threadsafe-command} {\\threadsafe}.
|
|
*/
|
|
|
|
/*!
|
|
\page 18-qdoc-commands-relating.html
|
|
\previouspage Thread Support
|
|
\contentspage Table of Contents
|
|
\nextpage Grouping Things
|
|
|
|
\title Relating Things
|
|
|
|
The relating commands are for specifying how one documented
|
|
element relates to another documented element. e.g., This function
|
|
is an overload of another function, or this function is a
|
|
reimplementation of another function, or this typedef is \e
|
|
related to some class or header file. There is also a command
|
|
for documenting that a QML element inherits some other QML
|
|
element.
|
|
|
|
\section1 Commands
|
|
|
|
\target inherits-command
|
|
\section2 \\inherits \span {class="newStuff"} {(new)}
|
|
|
|
The \\inherits command is for documenting that one QML element
|
|
inherits some other QML element. It must be included in the
|
|
inheriting element's \l{qmlclass-command}{\\qmlclass} comment.
|
|
The argument is the name of the inherited QML element.
|
|
|
|
\code
|
|
/ *!
|
|
\qmlclass PauseAnimation QDeclarativePauseAnimation
|
|
\ingroup qml-animation-transition
|
|
\since 4.7
|
|
\inherits Animation
|
|
\brief The PauseAnimation element provides a pause for an animation.
|
|
|
|
When used in a SequentialAnimation, PauseAnimation is a step
|
|
when nothing happens, for a specified duration.
|
|
|
|
A 500ms animation sequence, with a 100ms pause between two animations:
|
|
|
|
SequentialAnimation {
|
|
NumberAnimation { ... duration: 200 }
|
|
PauseAnimation { duration: 100 }
|
|
NumberAnimation { ... duration: 200 }
|
|
}
|
|
|
|
\sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example}
|
|
* /
|
|
\endcode
|
|
|
|
QDoc includes this line on the reference page for the
|
|
\l{http://doc.trolltech.com/4.7/qml-pauseanimation.html} {PauseAnimation}
|
|
element:
|
|
|
|
\quotation
|
|
Inherits \l{http://doc.trolltech.com/4.7/qml-animation.html} {Animation}
|
|
\endquotation
|
|
|
|
\target overload-command
|
|
\section2 \\overload
|
|
|
|
The \\overload command is for indicating that a function is a
|
|
secondary overload of its name.
|
|
|
|
The command must stand on its own line.
|
|
|
|
For a function name that is overloaded (except constructors), QDoc
|
|
expects one primary version of the function, and all the others
|
|
marked with the \bold {\\overload command}. The primary version
|
|
should be fully documented. Each overload can have whatever extra
|
|
documentation you want to add for just that overloaded version.
|
|
|
|
From Qt 4.5, you can include the function name plus '()' as a
|
|
parameter to the \bold{\\overload} command, which will include a
|
|
standard \e{This function overloads...} line of text with a link
|
|
to the documentation for the primary version of the function.
|
|
|
|
\code
|
|
/ *!
|
|
\overload addAction()
|
|
|
|
This convenience function creates a new action with an
|
|
\a icon and some \a text. The function adds the newly
|
|
created action to the menu's list of actions, and
|
|
returns it.
|
|
|
|
\sa QWidget::addAction()
|
|
* /
|
|
QAction *QMenu::addAction(const QIcon &icon, const QString &text)
|
|
{
|
|
QAction *ret = new QAction(icon, text, this);
|
|
addAction(ret);
|
|
return ret;
|
|
}
|
|
\endcode
|
|
|
|
QDoc renders this as:
|
|
|
|
\quotation
|
|
\raw HTML
|
|
<h3><a href="http://qt.nokia.com/doc/4.0/qaction.html">QAction</a>
|
|
* QMenu::addAction ( const QIcon & <i>icon</i>,
|
|
const QString & <i>text</i> )
|
|
</h3>
|
|
\endraw
|
|
|
|
This function overloads \l {http://qt.nokia.com/doc/4.0/qwidget.html#addAction} {addAction()}
|
|
|
|
This convenience function creates a new action with an
|
|
\e icon and some \e text. The function adds the newly
|
|
created action to the menu's list of actions, and
|
|
returns it.
|
|
|
|
See also
|
|
\l {http://qt.nokia.com/doc/4.0/qwidget.html#addAction}
|
|
{QWidget::addAction}().
|
|
\endquotation
|
|
|
|
If you don't include the function name with the \bold{\\overlaod}
|
|
command, then instead of the "This function overloads..." line
|
|
with the link to the documentation for the primary version, you
|
|
get the old standard line:
|
|
|
|
\quotation
|
|
This is an overloaded member function, provided for
|
|
convenience.
|
|
\endquotation.
|
|
|
|
\target reimp-command
|
|
\section2 \\reimp
|
|
|
|
The \\reimp command is for indicating that a function is a
|
|
reimplementation of a virtual function.
|
|
|
|
The command must stand on its own line.
|
|
|
|
QDoc will omit the reimplemented function from the class
|
|
reference.
|
|
|
|
\code
|
|
/ *!
|
|
\reimp
|
|
* /
|
|
void QToolButton::nextCheckState()
|
|
{
|
|
Q_D(QToolButton);
|
|
if (!d->defaultAction)
|
|
QAbstractButton::nextCheckState();
|
|
else
|
|
d->defaultAction->trigger();
|
|
}
|
|
\endcode
|
|
|
|
This function will not be included in the documentation. Instead,
|
|
a link to the base function QAbstractButton::nextCheckState() will
|
|
appear in the documentation.
|
|
|
|
\target relates-command
|
|
\section2 \\relates
|
|
|
|
The \\relates command is for including the documentation of a
|
|
global element to some class or header file. The argument is a
|
|
class name or header file.
|
|
|
|
\code
|
|
/ *!
|
|
\relates QChar
|
|
|
|
Reads a char from the stream \a in into char \a chr.
|
|
|
|
\sa {Format of the QDataStream operators}
|
|
* /
|
|
QDataStream &operator>>(QDataStream &in, QChar &chr)
|
|
{
|
|
quint16 u;
|
|
in >> u;
|
|
chr.unicode() = ushort(u);
|
|
return in;
|
|
}
|
|
\endcode
|
|
|
|
The documentation for this function will be included on the reference page
|
|
for class QChra.
|
|
*/
|
|
|
|
/*!
|
|
\page 19-qdoc-commands-grouping.html
|
|
\previouspage Relating Things
|
|
\contentspage Table of Contents
|
|
\nextpage Naming Things
|
|
|
|
\title Grouping Things
|
|
|
|
The grouping commands relate classes to defined groups and
|
|
modules. The groups are used when generating lists of related
|
|
classes in the documentation, while the modules are elements of
|
|
Qt's structure.
|
|
|
|
\section1 Commands
|
|
|
|
\target mainclass-command
|
|
\section2 \\mainclass
|
|
|
|
The \\mainclass command relates the documented class to
|
|
a group called mainclasses.
|
|
|
|
The command must stand on its own line.
|
|
|
|
\code
|
|
/ *!
|
|
\class QWidget qwidget.h
|
|
\brief The QWidget class is the base class of
|
|
all user interface objects.
|
|
|
|
\mainclass
|
|
|
|
...
|
|
* /
|
|
\endcode
|
|
|
|
This will include the QWidget class in the \e mainclasses
|
|
group, which means, for example, that the class will appear on the
|
|
list created by calling the \l {generatelist-command}
|
|
{\\generatelist} command with the \c mainclasses argument:
|
|
|
|
\l http://qt.nokia.com/doc/4.0/mainclasses.html
|
|
|
|
\note The Qt documentation no longer includes the \e mainclasses
|
|
page.
|
|
|
|
See also \l {generatelist-command} {\\generatelist}.
|
|
|
|
\target ingroup-command
|
|
\section2 \\ingroup
|
|
|
|
The \\ingroup command indicates that the given
|
|
overview or documented class belongs to a certain group of
|
|
related docmentation.
|
|
|
|
A class or overview may belong to many groups.
|
|
|
|
The \\ingroup command's argument is a group name, but note
|
|
that the command considers the rest of the line as part of
|
|
its argument. Make sure that the group name is followed by
|
|
a linebreak.
|
|
|
|
\code
|
|
/ *!
|
|
\class QDir
|
|
\brief The QDir class provides access to directory
|
|
structures and their contents.
|
|
|
|
\ingroup io
|
|
...
|
|
* /
|
|
\endcode
|
|
|
|
This will include the QDir class in the \c io group, which means,
|
|
for example, that QDir will appear on the list created by calling
|
|
the \l {group-command} {\\group} command with the \c io argument.
|
|
|
|
To list overviews that are related to a certain group, you must
|
|
generate the list explicitly using the \l {generatelist-command}
|
|
{\\generatelist} command with the \c related argument.
|
|
|
|
See also \l {group-command} {\\group}.
|
|
|
|
\target inmodule-command
|
|
\section2 \\inmodule
|
|
|
|
The \\inmodule command relates a class to the module specified by
|
|
the command's argument.
|
|
|
|
For the basic classes in Qt, a class's module is determined by its
|
|
location, i.e. its directory. However, for extensions, like
|
|
ActiveQt and Qt Designer, a class must be related to a module
|
|
explicitly.
|
|
|
|
The command's argument is a module name, but note that the command
|
|
considers the rest of the line as part of its argument. Make sure
|
|
that the module name is followed by a linebreak.
|
|
|
|
\code
|
|
/*!
|
|
\class QDesignerTaskMenuExtension
|
|
\inmodule QtDesigner
|
|
* /
|
|
\endcode
|
|
|
|
This ensures that the QDesignerTaskMenuExtension class is included
|
|
in the \c QtDesigner module, which means, for example, that the
|
|
class will appear on the list created by calling the \l
|
|
{generatelist-command} {\\generatelist} command with the \c
|
|
{{classesbymodule QtDesigner}} argument.
|
|
|
|
See also \l {module-command} {\\module} and \l
|
|
{generatelist-command} {\\generatelist}.
|
|
*/
|
|
|
|
/*!
|
|
\page 20-qdoc-commands-namingthings.html
|
|
\previouspage Grouping Things
|
|
\contentspage Table of Contents
|
|
\nextpage Markup Commands
|
|
|
|
\title Naming Things
|
|
|
|
In general, a title command considers everything that follows it
|
|
until the first line break as its argument. If the title is so
|
|
long it must span multiple lines, end each line (except the last
|
|
one) with a backslash.
|
|
|
|
\section1 Commands
|
|
|
|
\target title-command
|
|
\section2 \\title
|
|
|
|
The \\title command sets the title for a documentation page, or
|
|
allows you to override it.
|
|
|
|
\code
|
|
/ *!
|
|
\page signalandslots.html
|
|
|
|
\title Signals & Slots
|
|
|
|
Signals and slots are used for communication between
|
|
objects. The signals and slots mechanism is a central
|
|
feature of Qt and probably the part that differs most
|
|
from the features provided by other frameworks.
|
|
|
|
...
|
|
* /
|
|
\endcode
|
|
|
|
QDoc renders this as:
|
|
|
|
\quotation
|
|
\raw HTML
|
|
<h1><center>Signal and Slots</center></h1>
|
|
\endraw
|
|
|
|
Signals and slots are used for communication between
|
|
objects. The signals and slots mechanism is a central
|
|
feature of Qt and probably the part that differs most
|
|
from the features provided by other frameworks.
|
|
...
|
|
\endquotation
|
|
See also \l {subtitle-command} {\\subtitle}.
|
|
|
|
\target subtitle-command
|
|
\section2 \\subtitle
|
|
|
|
The \\subtitle command sets a subtitle for a documentation page.
|
|
|
|
\code
|
|
/ *!
|
|
\page qtopiacore-overview.html
|
|
|
|
\title Qtopia Core
|
|
\subtitle Qt for Embedded Linux
|
|
|
|
Qt/Embedded, the embedded Linux port of Qt, is a
|
|
complete and self-contained C++ GUI and platform
|
|
development tool for Linux-based embedded development.
|
|
...
|
|
* /
|
|
\endcode
|
|
|
|
QDoc renders this as:
|
|
|
|
\quotation
|
|
\raw HTML
|
|
<h1><center>Qtopia Core</center></h1>
|
|
<h2><center>Qt for Embedded Linux</center></h2>
|
|
\endraw
|
|
|
|
Qt/Embedded, the embedded Linux port of Qt, is a
|
|
complete and self-contained C++ GUI and platform
|
|
development tool for Linux-based embedded development.
|
|
...
|
|
\endquotation
|
|
|
|
See also \l {title-command} {\\title}.
|
|
|
|
*/
|
|
|
|
/*!
|
|
\page 21-0-qdoc-configuration.html
|
|
\previouspage Miscellaneous
|
|
\contentspage Table of Contents
|
|
\nextpage Generic Configuration Variables
|
|
|
|
\title The QDoc Configuration File
|
|
|
|
Before running QDoc, you must create a QDoc configuration file to
|
|
tell QDoc where to find the source files that contain the QDoc
|
|
comments. The pathname to your configuration file is passed to
|
|
QDoc on the command line:
|
|
|
|
\quotation
|
|
\c {/current/dir$ ../../bin/qdoc3 ./config.qdocconf}
|
|
\endquotation
|
|
|
|
\section1 General Description
|
|
|
|
The configuration file is a list of entries of the form \e
|
|
{"variable = value"}. Using the configuration variables, you can
|
|
define where QDoc should find the various source files, images and
|
|
examples, where to put generated documentation etc. The
|
|
configuration file can also contain directives like \c
|
|
include. For an example, see the \l minimum.qdocconf file.
|
|
|
|
You can also use configuration variables to get QDoc to support
|
|
\l{Supporting Derived Projects} {derived projects}, i.e QDoc can
|
|
generate links in your project's documentation to elements in the
|
|
Qt online documentation. See the \l {Supporting Derived projects}
|
|
section.
|
|
|
|
The value of a configuration variable can be set using either '='
|
|
or '+='. The difference is that '=' overrides the previous value,
|
|
while '+=' adds a new value to the current one.
|
|
|
|
Some configuration variables accept a list of strings as their
|
|
value, e.g.
|
|
\l {22-qdoc-configuration-generalvariables.html#sourcedirs-variable}
|
|
{\c{sourcedirs}}, while others accept only a single string. Double
|
|
quotes around a value string are optional, but including them allows
|
|
you to use special characters like '=' and ' \" ' within the valuem
|
|
string, e.g.:
|
|
|
|
\code
|
|
HTML.postheader = "<a href=\"index.html\">Home</a>"
|
|
\endcode
|
|
|
|
If an entry spans many lines, use a backslash at the end of every
|
|
line but the last:
|
|
|
|
\code
|
|
sourcedirs = kernel \
|
|
tools \
|
|
widgets
|
|
\endcode
|
|
|
|
\section1 Configuration Variables
|
|
|
|
\section1 Variable List
|
|
|
|
\list
|
|
\o \l {22-qdoc-configuration-generalvariables.html#alias-variable} {alias}
|
|
\o \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoredirectives-variable} {Cpp.ignoredirectives}
|
|
\o \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoretokens-variable} {Cpp.ignoretokens}
|
|
\o \l {22-qdoc-configuration-generalvariables.html#defines-variable} {defines}
|
|
\o \l {22-qdoc-configuration-generalvariables.html#edition-variable} {edition}
|
|
\o \l {22-qdoc-configuration-generalvariables.html#exampledirs-variable} {exampledirs}
|
|
\o \l {22-qdoc-configuration-generalvariables.html#examples-variable} {examples}
|
|
\o \l {22-qdoc-configuration-generalvariables.html#examples.fileextensions-variable} {examples.fileextensions}
|
|
\o \l {22-qdoc-configuration-generalvariables.html#extraimages-variable} {extraimages}
|
|
\o \l {22-qdoc-configuration-generalvariables.html#falsehoods-variable} {falsehoods}
|
|
\o \l {22-qdoc-configuration-generalvariables.html#headerdirs-variable} {headerdirs}
|
|
\o \l {22-qdoc-configuration-generalvariables.html#headers-variable} {headers}
|
|
\o \l {22-qdoc-configuration-generalvariables.html#headers.fileextensions-variable} {headers.fileextensions}
|
|
\o \l {24-qdoc-configuration-htmlvariables.html#HTML.footer-variable} {HTML.footer}
|
|
\o \l {24-qdoc-configuration-htmlvariables.html#HTML.postheader-variable} {HTML.postheader}
|
|
\o \l {24-qdoc-configuration-htmlvariables.html#HTML.style-variable} {HTML.style}
|
|
\o \l {22-qdoc-configuration-generalvariables.html#imagedirs-variable} {imagedirs}
|
|
\o \l {22-qdoc-configuration-generalvariables.html#images-variable} {images}
|
|
\o \l {22-qdoc-configuration-generalvariables.html#images.fileextensions-variable} {images.fileextensions}
|
|
\o \l {22-qdoc-configuration-generalvariables.html#language-variable} {language}
|
|
\o \l {22-qdoc-configuration-generalvariables.html#macro-variable} {macro}
|
|
\o \l {22-qdoc-configuration-generalvariables.html#outputdir-variable} {outputdir}
|
|
\o \l {22-qdoc-configuration-generalvariables.html#outputformats-variable} {outputformats}
|
|
\o \l {22-qdoc-configuration-generalvariables.html#slow-variable} {slow}
|
|
\o \l {22-qdoc-configuration-generalvariables.html#sourcedirs-variable} {sourcedirs}
|
|
\o \l {22-qdoc-configuration-generalvariables.html#sources-variable} {sources}
|
|
\o \l {22-qdoc-configuration-generalvariables.html#sources.fileextensions-variable} {sources.fileextensions}
|
|
\o \l {22-qdoc-configuration-generalvariables.html#spurious-variable} {spurious}
|
|
\o \l {22-qdoc-configuration-generalvariables.html#tabsize-variable} {tabsize}
|
|
\o \l {22-qdoc-configuration-generalvariables.html#version-variable} {version}
|
|
\o \l {22-qdoc-configuration-generalvariables.html#versionsym-variable} {versionsym}
|
|
\endlist
|
|
|
|
\section1 Categories
|
|
|
|
\list
|
|
\o \l {Generic Configuration Variables}
|
|
\o \l {C++ Specific Configuration Variables}
|
|
\o \l {HTML Specific Configuration Variables}
|
|
\endlist
|
|
|
|
\section1 Configuration File Examples
|
|
|
|
\list
|
|
\o A minimum configuration file: \l minimum.qdocconf
|
|
\o The Qt configuration file: \l qt.qdocconf
|
|
\endlist
|
|
*/
|
|
|
|
/*!
|
|
\page 21-1-minimum-qdocconf.html
|
|
\previouspage qt.qdocconf
|
|
\contentspage Table of Contents
|
|
\nextpage Generating DITA XML Output
|
|
|
|
\title minimum.qdocconf
|
|
|
|
\quotefile examples/minimum.qdocconf
|
|
*/
|
|
|
|
/*!
|
|
\page 21-2-qt-qdocconf.html
|
|
\previouspage Compatibility Issues
|
|
\contentspage Table of Contents
|
|
\nextpage minimum.qdocconf
|
|
|
|
\title qt.qdocconf
|
|
|
|
\quotefile files/qt.qdocconf
|
|
*/
|
|
|
|
/*!
|
|
\page 21-3-qt-dita-xml-output.html
|
|
\previouspage minimum.qdocconf
|
|
\contentspage Table of Contents
|
|
\nextpage Table of Contents
|
|
|
|
\title Generating DITA XML Output
|
|
|
|
QDoc can generate \l {http://dita.xml.org} {DITA XML output}.
|
|
|
|
In your confifiguration file, set your \c {outputformats} variable
|
|
to \c {DITAXML}, and send the output to an appropriate directory:
|
|
|
|
\code
|
|
outputdir = $QTDIR/doc/ditaxml
|
|
outputformats = DITAXML
|
|
\endcode
|
|
|
|
And include these macros in your configuration file to prevent
|
|
QDoc from doing some escaping that doesn't validate in XML:
|
|
|
|
\code
|
|
macro.aacute.DITAXML = "á"
|
|
macro.Aring.DITAXML = "Å"
|
|
macro.aring.DITAXML = "å"
|
|
macro.Auml.DITAXML = "Ä"
|
|
macro.br.DITAXML = " "
|
|
macro.BR.DITAXML = " "
|
|
macro.copyright.DITAXML = "©"
|
|
macro.eacute.DITAXML = "é"
|
|
macro.hr.DITAXML = " "
|
|
macro.iacute.DITAXML = "í"
|
|
macro.oslash.DITAXML = "ø"
|
|
macro.ouml.DITAXML = "ö"
|
|
macro.raisedaster.DITAXML = "<sup>*</sup>"
|
|
macro.rarrow.DITAXML = "→"
|
|
macro.reg.DITAXML = "<sup>®</sup>"
|
|
macro.uuml.DITAXML = "ü"
|
|
macro.mdash.DITAXML = "—"
|
|
macro.emptyspan.DITAXML = " "
|
|
\endcode
|
|
|
|
You can also set default values for some of the tags in the DITA
|
|
\c {<prolog>} and \c {<metadata>} elements:
|
|
|
|
\code
|
|
dita.metadata.default.author = Qt Development Frameworks
|
|
dita.metadata.default.permissions = all
|
|
dita.metadata.default.publisher = The Qt Company
|
|
dita.metadata.default.copyryear = 2015
|
|
dita.metadata.default.copyrholder = The Qt Company Ltd
|
|
dita.metadata.default.audience = programmer
|
|
\endcode
|
|
|
|
See the \l {12-0-qdoc-commands-miscellaneous.html#meta-command}
|
|
{\\meta} command for more details on DITA metadata.
|
|
|
|
*/
|
|
|
|
/*!
|
|
\page 22-qdoc-configuration-generalvariables.html
|
|
\previouspage The QDoc Configuration File
|
|
\contentspage Table of Contents
|
|
\nextpage Creating Help Project Files
|
|
|
|
\title Generic Configuration Variables
|
|
|
|
With the general QDoc configuration variables, you can define
|
|
where QDoc will find the various source files it needs to generate
|
|
the documentation, as well as the directory to put the generated
|
|
documentation. You can also do some minor manipulation of QDoc
|
|
itself, controlling its output and processing behavior.
|
|
|
|
\target alias-variable
|
|
\section1 alias
|
|
|
|
The \c alias variable renames a QDoc command.
|
|
|
|
The general syntax is \tt {alias.\e{original-command-name} = \e
|
|
temporary-command-name}.
|
|
|
|
\code
|
|
alias.i = e
|
|
\endcode
|
|
|
|
This renames the built-in command \\i (italics) to \\e. The \c
|
|
alias variable is often used for compatibility reasons; for more
|
|
information see the \l {Compatibility Issues} {compatibility
|
|
section}.
|
|
|
|
See also \l {macro-variable} {macro}.
|
|
|
|
\target codeindent-variable
|
|
\section1 codeindent
|
|
|
|
The \c codeindent variable specifies the level of indentation that
|
|
QDoc uses when writing code snippets.
|
|
|
|
QDoc originally used a hard-coded value of four spaces for code
|
|
indentation to ensure that code snippets could be easily
|
|
distinguished from surrounding text. Since we can use \l{HTML
|
|
Specific Configuration Variables#HTML.stylesheets} {stylesheets}
|
|
to adjust the appearance of certain types of HTML elements, this
|
|
level of indentation is not always required.
|
|
|
|
\target defines-variable
|
|
\section1 defines
|
|
|
|
The \c defines variable specifies the C++ preprocessor symbols
|
|
that QDoc will recognize and respond to.
|
|
|
|
When a preprocessor symbol is specified using the \c defines
|
|
variable, you can also use the \l {if-command} {\\if} command to
|
|
enclose documentation that only will be included if the
|
|
preprocessor symbol is defined.
|
|
|
|
The values of the variable are regular expressions (see QRegExp
|
|
for details). By default, no symbol is defined, meaning that code
|
|
protected with #ifdef...#endif will be ignored.
|
|
|
|
\code
|
|
defines = Q_QDOC \
|
|
QT_.*_SUPPORT \
|
|
QT_.*_LIB \
|
|
QT_COMPAT \
|
|
QT3_SUPPORT \
|
|
Q_WS_.* \
|
|
Q_OS_.* \
|
|
Q_BYTE_ORDER \
|
|
__cplusplus
|
|
\endcode
|
|
|
|
This ensures that QDoc will process the code that requires these
|
|
symbols to be defined. For example:
|
|
|
|
\code
|
|
#ifdef Q_WS_WIN
|
|
HDC getDC() const;
|
|
void releaseDC(HDC) const;
|
|
#endif
|
|
\endcode
|
|
|
|
Since the Q_WS_.* regular expression (specified using the \c
|
|
defines variable) matches Q_WS_WIN, QDoc will process the code
|
|
within #ifdef and #endif in our example.
|
|
|
|
You can also define preprocessor symbols manually on the command
|
|
line using the -D option. For example:
|
|
|
|
\code
|
|
currentdirectory$ qdoc3 -Dconsoleedition qt.qdocconf
|
|
\endcode
|
|
|
|
In this case the -D option ensures that the \c consoleedition
|
|
preprocessor symbol is defined when QDoc processes the source
|
|
files defined in the qt.qdocconf file.
|
|
|
|
See also \l {falsehoods-variable} {falsehoods} and \l {if-command} {\\if}.
|
|
|
|
\target edition-variable
|
|
\section1 edition
|
|
|
|
The \c edition variable specifies which modules are included in
|
|
each edition of a package, and provides QDoc with information to
|
|
provide class lists for each edition.
|
|
|
|
This feature is mostly used when providing documentation for Qt
|
|
packages.
|
|
|
|
The \c edition variable is always used with a particular edition
|
|
name to define the modules for that edition:
|
|
|
|
\code
|
|
edition.Console = QtCore QtNetwork QtSql QtXml
|
|
edition.Desktop = QtCore QtGui QtNetwork QtOpenGL QtSql QtXml \
|
|
QtDesigner QtAssistant Qt3Support QAxContainer \
|
|
QAxServer
|
|
edition.DesktopLight = QtCore QtGui Qt3SupportLight
|
|
\endcode
|
|
|
|
In the above examples, the \c Console edition only includes the
|
|
contents of four modules. Only the classes from these modules will
|
|
be used when the \l{Miscellaneous#generatelist-command}
|
|
{generatelist} command is used to generate a list of classes for
|
|
this edition:
|
|
|
|
\code
|
|
\generatelist{classesbyedition Console}
|
|
\endcode
|
|
|
|
\target exampledirs-variable
|
|
\section1 exampledirs
|
|
|
|
The \c exampledirs variable specifies the directories containing
|
|
the source code of the example files.
|
|
|
|
The \l {examples-variable} {examples} {examples} and \l
|
|
{exampledirs-variable} {exampledirs} variables are used by the \l
|
|
{quotefromfile-command} {\\quotefromfile}, \l {quotefile-command}
|
|
{\\quotefile} and \l {example-command} {\\example} commands. If
|
|
both the \l {examples-variable} {examples} and \l
|
|
{exampledirs-variable} {exampledirs} variables are defined, QDoc
|
|
will search in both, first in \l {examples-variable} {examples}
|
|
then in \l {exampledirs-variable} {exampledirs}.
|
|
|
|
QDoc will search through the directories in the specified order,
|
|
and accept the first matching file it finds. It will only search
|
|
in the specified directories, \e not in subdirectories.
|
|
|
|
\code
|
|
exampledirs = $QTDIR/doc/src \
|
|
$QTDIR/examples \
|
|
$QTDIR \
|
|
$QTDIR/qmake/examples
|
|
|
|
examples = $QTDIR/examples/widgets/analogclock/analogclock.cpp
|
|
\endcode
|
|
|
|
When processing
|
|
|
|
\code
|
|
\quotefromfile widgets/calculator/calculator.cpp
|
|
\endcode
|
|
|
|
QDoc will then see if there exists a file called \c calculator.cpp
|
|
listed as a value in the \l {examples} {\c examples} variable. If
|
|
it doesn't, it will search in the \c exampledirs variable, and
|
|
first see if there exists a file called
|
|
|
|
\code
|
|
$QTDIR/doc/src/widgets/calculator/calculator.cpp
|
|
\endcode
|
|
|
|
If it doesn't, QDoc will continue looking for a file called
|
|
|
|
\code
|
|
$QTDIR/examples/widgets/calculator/calculator.cpp
|
|
\endcode
|
|
|
|
and so forth.
|
|
|
|
See also \l examples.
|
|
|
|
\target examples-variable
|
|
\section1 examples
|
|
|
|
The \c examples variable allows you to specify individual example
|
|
files in addition to those located in the directories specified by
|
|
the \l {exampledirs-variable} {\c exampledirs} variable.
|
|
|
|
The \c examples and \l {exampledirs-variable} {\c exampledirs}
|
|
variables are used by the \l {quotefromfile-command}
|
|
{\\quotefromfile}, \l {quotefile-command} {\\quotefile} and \l
|
|
{example} {\\example} commands. If both the \c examples and \l
|
|
{exampledirs-variable} {\c exampledirs} variables are defined,
|
|
QDoc will search in both, first in \c examples then in \l
|
|
{exampledirs-variable} {\c exampledirs}.
|
|
|
|
QDoc will search through the values listed for the \c examples
|
|
variable, in the specified order, and accept the first one it
|
|
finds.
|
|
|
|
For an extensive example, see the \l {exampledirs-variable} {\c
|
|
exampledirs} command. But note that if you know the file is listed
|
|
in the \c examples variable, you don't need to specify its path:
|
|
|
|
\code
|
|
\quotefromfile calculator.cpp
|
|
\endcode
|
|
|
|
See also \l {exampledirs-variable} {exampledirs}.
|
|
|
|
\target examples.fileextensions-variable
|
|
\section1 examples.fileextensions
|
|
|
|
The \c examples.fileextensions variable specifies the file
|
|
extensions that qdoc will look for when collecting example files
|
|
for display in the documentation.
|
|
|
|
The default extensions are *.cpp, *.h, *.js, *.xq, *.svg, *.xml
|
|
and *.ui. However, if
|
|
|
|
The extensions are given as standard wildcard expressions. You
|
|
can add a file extension to the filter using '+='. For example:
|
|
|
|
\code
|
|
examples.fileextensions += *.qrc
|
|
\endcode
|
|
|
|
See also \l{headers.fileextensions}.
|
|
|
|
\target extraimages-variable
|
|
\section1 extraimages
|
|
|
|
The \c extraimages variable tells QDoc to incorporate specific
|
|
images in the generated documentation.
|
|
|
|
QDoc will not recognize images used within HTML (or any other
|
|
markup language). If we want the images to be copied from the
|
|
directories specified by \l {imagedirs} {\c imagedirs} (the images
|
|
in question must be located in these directories) to the output
|
|
directory, we must specify the images using the \c extraimages
|
|
variable.
|
|
|
|
The general syntax is \tt {extraimages.\e{format} = \e image}. The
|
|
file extension is optional.
|
|
|
|
For example, in \l qt.qdocconf we use a couple of images within
|
|
the HTML.postheader variable which value is pure HTML. For that
|
|
reason, these images are specified using the \c extraimages
|
|
variable:
|
|
|
|
\code
|
|
extraimages.HTML = qt-logo
|
|
\endcode
|
|
|
|
See also \l images and \l imagedirs.
|
|
|
|
\target falsehoods-variable
|
|
\section1 falsehoods
|
|
|
|
The \c falsehoods variable defines the truth value of specified
|
|
preprocessor symbols as false.
|
|
|
|
If this variable is not set for a preprocessor symbol, QDoc
|
|
assumes its truth value is true. The exception is '0', which value
|
|
always is false.
|
|
|
|
QDoc will recognize, and is able to evaluate, the following
|
|
preprocessor syntax:
|
|
|
|
\code
|
|
#ifdef NOTYET
|
|
...
|
|
#endif
|
|
|
|
#if defined (NOTYET)
|
|
...
|
|
#end if
|
|
\endcode
|
|
|
|
However, faced with unknown syntax like
|
|
|
|
\code
|
|
#if NOTYET
|
|
...
|
|
#endif
|
|
\endcode
|
|
|
|
QDoc will evaluate it as true by default, \e unless the
|
|
preprocessor symbol is specified within the \c falsehoods variable
|
|
entry:
|
|
|
|
\code
|
|
falsehoods = NOTYET
|
|
\endcode
|
|
|
|
See also \l defines.
|
|
|
|
\target generateindex-variable
|
|
\section1 generateindex
|
|
|
|
The \c generateindex variable contains a boolean value that
|
|
specifies whether to generate an index file when HTML
|
|
documentation is generated.
|
|
|
|
By default, an index file is always generated with HTML
|
|
documentation, so this variable is typically only used when
|
|
disabling this feature (by setting the value to \c false) or when
|
|
enabling index generation for the WebXML output (by setting the
|
|
value to \c true).
|
|
|
|
\target headerdirs-variable
|
|
\section1 headerdirs
|
|
|
|
The \c headerdirs variable specifies the directories containing
|
|
the header files associated with the \c .cpp source files used in
|
|
the documentation.
|
|
|
|
\code
|
|
headerdirs = $QTDIR/src \
|
|
$QTDIR/extensions/activeqt \
|
|
$QTDIR/extensions/motif \
|
|
$QTDIR/tools/designer/src/lib/extension \
|
|
$QTDIR/tools/designer/src/lib/sdk \
|
|
$QTDIR/tools/designer/src/lib/uilib
|
|
\endcode
|
|
|
|
When executed, the first QDoc will do is to read through the
|
|
headers specified in the \l {headers} {\c headers} variable, and
|
|
the ones located in the directories specified in the \c headerdir
|
|
variable (including all subdirectories), building an internal
|
|
structure of the classes and their functions.
|
|
|
|
Then it will read through the sources specified in the \l
|
|
{sources-variable} {\c sources}, and the ones located in the
|
|
directories specified in the \l {sourcedirs-variable} {\c
|
|
sourcedirs} varible (including all subdirectories), merging the
|
|
documentation with the structure it retrieved from the header
|
|
files.
|
|
|
|
If both the \c headers and \c headerdirs variables are defined,
|
|
QDoc will read through both, first \l {headers} {\c headers} then
|
|
\c headerdirs.
|
|
|
|
In the specified directories, QDoc will only read the files with
|
|
the fileextensions specified in the \l {headers.fileextensions}
|
|
{\c headers.fileextensions} variable. The default extensions are
|
|
*.ch, *.h, *.h++, *.hh, *.hpp and *.hxx". The files specified by
|
|
\l {headers} {\c headers} will be read independent of their
|
|
fileextensions.
|
|
|
|
See also \l headers and \l headers.fileextensions.
|
|
|
|
\target headers-variable
|
|
\section1 headers
|
|
|
|
The \c headers variable allows you to specify individual header
|
|
files in addition to those located in the directories specified by
|
|
the \l {headerdirs} {\c headerdirs} variable.
|
|
|
|
\code
|
|
headers = $QTDIR/src/gui/widgets/qlineedit.h \
|
|
$QTDIR/src/gui/widgets/qpushbutton.h
|
|
\endcode
|
|
|
|
When processing the \c headers variable, QDoc behaves in the same
|
|
way as it does when processing the \l {headerdirs} {\c headerdirs}
|
|
variable. For more information, see the \l {headerdirs} {\c
|
|
headerdirs} variable.
|
|
|
|
See also \l headerdirs.
|
|
|
|
\target headers.fileextensions-variable
|
|
\section1 headers.fileextensions
|
|
|
|
The \c headers.fileextensions variable specify the extension used
|
|
by the headers.
|
|
|
|
When processing the header files specified in the \l {headerdirs}
|
|
{\c headerdirs} variable, QDoc will only read the files with the
|
|
fileextensions specified in the \c headers.fileextensions
|
|
variable. In this way QDoc avoid spending time reading irrelevant
|
|
files.
|
|
|
|
The default extensions are *.ch, *.h, *.h++, *.hh, *.hpp and
|
|
*.hxx.
|
|
|
|
The extensions are given as standard wildcard expressions. You
|
|
can add a file extension to the filter using '+='. For example:
|
|
|
|
\code
|
|
header.fileextensions += *.H
|
|
\endcode
|
|
|
|
\warning The above assignment may not work as described.
|
|
|
|
See also \l headerdirs.
|
|
|
|
\target imagedirs-variable
|
|
\section1 imagedirs
|
|
|
|
The \c imagedirs variable specifies the directories containing the
|
|
images used in the documentation.
|
|
|
|
The \l {images} {\c images} and \c imagedirs variables are used by
|
|
the \l {image-command} {\\image} and \l {inlineimage-command}
|
|
{\\inlineimage} commands. If both the \l {images} {\c images} and
|
|
\c imagedirs variables are defined, QDoc will search in both,
|
|
first in \l {images} {\c images} then in \c imagedirs.
|
|
|
|
QDoc will search through the directories in the specified order,
|
|
and accept the first matching file it finds. It will only search
|
|
in the specified directories, \e not in subdirectories.
|
|
|
|
\code
|
|
imagedirs = $QTDIR/doc/src/images \
|
|
$QTDIR/examples
|
|
|
|
images = $QTDIR/doc/src/images/calculator-example.png
|
|
\endcode
|
|
|
|
When processing
|
|
|
|
\code
|
|
\image calculator-example.png
|
|
\endcode
|
|
|
|
QDoc will then see if there exists a file called
|
|
calculator-example.png listed as a value in the \c images
|
|
variable. If it doesn't, it will search in the \c imagedirs
|
|
variable, and first see if there exists a file called
|
|
|
|
\code
|
|
$QTDIR/doc/src/images/calculator-example.png
|
|
\endcode
|
|
|
|
If it doesn't, QDoc will look for a file called
|
|
|
|
\code
|
|
$QTDIR/examples/calculator-example.png
|
|
\endcode
|
|
|
|
You can filter the images in an image directory using the \l
|
|
{images.fileextensions} {\c images.fileextensions} variable. The
|
|
general idea behind the \l {images.fileextensions} {\c images.fileextensions}
|
|
variable is to enable different image format for different output format.
|
|
|
|
\warning The \l {images.fileextensions} {\c images.fileextensions}
|
|
variable's functionality is preliminay since QDoc at this point
|
|
only support HTML.
|
|
|
|
See also \l images and \l images.fileextensions.
|
|
|
|
\target images-variable
|
|
\section1 images
|
|
|
|
The \c images variable allows you to specify individual image
|
|
files in addition to those located in the directories specified by
|
|
the \l {imagedirs} {\c imagedirs} variable.
|
|
|
|
\code
|
|
images = $QTDIR/doc/src/images/calculator-example.png
|
|
\endcode
|
|
|
|
When processing the \c images variable, QDoc behaves in the same
|
|
way as it does when processing the \l {imagedirs} {\c imagedirs}
|
|
variable. For more information, see the \l {imagedirs} {\c
|
|
imagedirs} variable.
|
|
|
|
See also \l imagedirs and \l images.fileextensions.
|
|
|
|
\target images.fileextensions-variable
|
|
\section1 images.fileextensions
|
|
|
|
The images.fileextensions variable filters the files within an
|
|
image directory.
|
|
|
|
The variable's values (the extensions) are given as standard
|
|
wildcard expressions. The general syntax is: \tt
|
|
{images.fileextensions.\e{format} = *.\e{extension}}.
|
|
|
|
The idea is to enable different image format for different output
|
|
format.
|
|
|
|
\code
|
|
images.fileextensions.HTML = *.png
|
|
images.fileextensions.LOUT = *.eps
|
|
\endcode
|
|
|
|
Then, when processing the \l {image-command} {\\image} and \l
|
|
{inlineimage-command} {\\inlineimage} commands, QDoc will only
|
|
search for files with extensions specified in the output format's
|
|
associated image extension variable.
|
|
|
|
\warning This is preliminary functionality since QDoc at this
|
|
point only support HTML.
|
|
|
|
The default extensions for HTML are *.png, *.jpg, *.jpeg and
|
|
*.gif.
|
|
|
|
You can add a file extension to the filter using '+='. For
|
|
example:
|
|
|
|
\code
|
|
images.fileextensions.HTML += *.eps
|
|
\endcode
|
|
|
|
See also \l imagedirs and \l images.
|
|
|
|
\target language-variable
|
|
\section1 language
|
|
|
|
The \c language variable specifies the language of the source code
|
|
that is used in the documentation.
|
|
|
|
Currently, C++ is the only language that QDoc understands. It is
|
|
also the default language, and doesn't really need to be
|
|
specified. But for example in \l qt.qdocconf:
|
|
|
|
\code
|
|
language = Cpp
|
|
\endcode
|
|
|
|
identifies the language of the Qt source code as C++.
|
|
|
|
\target macro-variable
|
|
\section1 macro
|
|
|
|
The \c macro variable is used to create your own simple QDoc
|
|
commands. The syntax is \tt {macro.\e{command} = \e{definition}},
|
|
where the definition is written using QDoc syntax.
|
|
|
|
A macro variable can be restricted for use in one type of output
|
|
generation. By appending \c {.HTML} to the macro name, for
|
|
example, the macro is only used when generating HTML output. By
|
|
appending \c {.DITAXML} to the macro name, the macro is only used
|
|
when generating DITA XML.
|
|
|
|
\code
|
|
macro.gui = "\\bold"
|
|
macro.raisedaster.HTML = "<sup>*</sup>"
|
|
\endcode
|
|
|
|
The first macro defines the \\gui command to render its argument
|
|
using a bold font. The second macro defines the \\raisedaster
|
|
command to render a superscript asterisk, but only when generating
|
|
HTML.
|
|
|
|
See also \l {alias-variable} {alias}.
|
|
|
|
\target naturallanguage-variable
|
|
\section1 naturallanguage
|
|
|
|
The \c naturallanguage variable specifies the natural language
|
|
used for the documentation generated by qdoc.
|
|
|
|
\code
|
|
naturallanguage = zh-Hans
|
|
\endcode
|
|
|
|
By default, the natural language is \c en for compatibility with
|
|
legacy documentation.
|
|
|
|
qdoc will add the natural language information to the HTML it
|
|
generates, using the \c lang and \c xml:lang attributes.
|
|
|
|
See also \l {sourceencoding-variable} {sourceencoding},
|
|
\l {outputencoding-variable} {outputencoding},
|
|
\l{http://www.w3.org/TR/xhtml1/#C_7}
|
|
{C.7. The lang and xml:lang Attributes} and
|
|
\l{http://www.w3.org/TR/i18n-html-tech-lang/#ri20040429.113217290}
|
|
{Best Practice 13: Using Hans and Hant codes}.
|
|
|
|
\target outputdir-variable
|
|
\section1 outputdir
|
|
|
|
The \c outputdir variable specifies the directory where QDoc will
|
|
put the generated documentation.
|
|
|
|
In qt.qdocconf:
|
|
|
|
\code
|
|
outputdir = $QTDIR/doc/html
|
|
\endcode
|
|
|
|
locates the generated Qt reference documentation in
|
|
$QTDIR/doc/html. For example, the documentation of the QWidget
|
|
class is located in
|
|
|
|
\code
|
|
$QTDIR/doc/html/qwidget.html
|
|
\endcode
|
|
|
|
The associated images will be put in an \c images subdirectory.
|
|
|
|
\warning When running QDoc multiple times using the same output
|
|
directory, all files from the previous run will be lost.
|
|
|
|
\target outputencoding-variable
|
|
\section1 outputencoding
|
|
|
|
The \c outputencoding variable specifies the encoding used for the
|
|
documentation generated by qdoc.
|
|
|
|
\code
|
|
outputencoding = UTF-8
|
|
\endcode
|
|
|
|
By default, the output encoding is \c ISO-8859-1 (Latin1) for
|
|
compatibility with legacy documentation. When generating
|
|
documentation for some languages, particularly non-European
|
|
languages, this is not sufficient and an encoding such as UTF-8 is
|
|
required.
|
|
|
|
qdoc will encode HTML using this encoding and generate the correct
|
|
declarations to indicate to browsers which encoding is being
|
|
used. The \l naturallanguage configuration variable should also be
|
|
specified to provide browsers with a complete set of character
|
|
encoding and language information.
|
|
|
|
See also \l outputencoding and \l naturallanguage.
|
|
|
|
\target outputformats-variable
|
|
\section1 outputformats
|
|
|
|
The \c outputformats variable specifies the format of
|
|
the generated documentation.
|
|
|
|
Currently, QDoc only supports the HTML format. It is also
|
|
the default format, and doesn't need to be specified.
|
|
|
|
\target outputprefixes
|
|
\section1 outputprefixes
|
|
|
|
The \c outputprefixes variable specifies a mapping between types of files
|
|
and the prefixes to prepend to the HTML file names in the generated
|
|
documentation.
|
|
|
|
\code
|
|
outputprefixes = QML
|
|
outputprefixes.QML = qt-components-
|
|
\endcode
|
|
|
|
By default, files containing the API documentation for QML elements
|
|
or components are prefixed with "qml-". In the above example, the
|
|
prefix "qt-components-" is used instead.
|
|
|
|
\target qhp-variable
|
|
\section1 qhp
|
|
|
|
The \c qhp variable is used to define the information to be
|
|
written out to Qt Help Project (\c{qhp}) files.
|
|
|
|
See the \l{Creating Help Project Files} chapter for information
|
|
about this process.
|
|
|
|
|
|
\target slow-variable
|
|
\section1 slow
|
|
|
|
The \c slow variable specifies whether QDoc should do
|
|
time-consuming processing, such as syntax highlighting. The
|
|
default value is false.
|
|
|
|
\note This option has been replaced by the \l{syntaxhighlighting} option.
|
|
|
|
For compatibility, the \c -slow command-line option has been
|
|
retained. This has the effect of enabling syntax highlighting.
|
|
|
|
\target sourcedirs-variable
|
|
\section1 sourcedirs
|
|
|
|
The \c sourcedirs variable specifies the directories containing
|
|
the \c .cpp or \c .qdoc files used in the documentation.
|
|
|
|
For example in \l qt.qdocconf
|
|
|
|
\code
|
|
sourcedirs = $QTDIR/src \
|
|
$QTDIR/doc/src \
|
|
$QTDIR/extensions/activeqt \
|
|
$QTDIR/extensions/motif \
|
|
$QTDIR/tools/designer/src/lib/extension \
|
|
$QTDIR/tools/designer/src/lib/sdk \
|
|
$QTDIR/tools/designer/src/lib/uilib
|
|
\endcode
|
|
|
|
When executed, the first QDoc will do is to read through the
|
|
headers specified in the \l {header-command} {\c header} variable,
|
|
and the ones located in the directories specified in the \c
|
|
headerdir variable (including all subdirectories), building an
|
|
internal structure of the classes and their functions.
|
|
|
|
Then it will read through the sources specified in the \l
|
|
{sources} {\c sources}, and the ones located in the directories
|
|
specified in the \l {sourcedirs} {\c sourcedirs} varible
|
|
(including all subdirectories), merging the documentation with the
|
|
structure it retrieved from the header files.
|
|
|
|
If both the \c sources and \c sourcedirs variables are defined,
|
|
QDoc will read through both, first \l {sources} {\c sources} then
|
|
\c sourcedirs.
|
|
|
|
In the specified directories, QDoc will only read the files with
|
|
the fileextensions specified in the \l {sources.fileextensions}
|
|
{\c sources.fileextensions} variable. The default extensions are
|
|
*.c++, *.cc, *.cpp and *.cxx. The files specified by \l {sources}
|
|
{\c sources} will be read independent of their fileextensions.
|
|
|
|
See also \l {sources-variable} {sources} and
|
|
\l {sources.fileextensions-variable} {sources.fileextensions}.
|
|
|
|
\target sourceencoding-variable
|
|
\section1 sourceencoding
|
|
|
|
The \c sourceencoding variable specifies the encoding used for the
|
|
source code and documentation.
|
|
|
|
\code
|
|
sourceencoding = UTF-8
|
|
\endcode
|
|
|
|
By default, the source encoding is \c ISO-8859-1 (Latin1) for
|
|
compatibility with legacy documentation. For some languages,
|
|
particularly non-European languages, this is not sufficient and an
|
|
encoding such as UTF-8 is required.
|
|
|
|
Although qdoc will use the encoding to read source and
|
|
documentation files, limitations of C++ compilers may prevent you
|
|
from using non-ASCII characters in source code comments. In cases
|
|
like these, it is possible to write API documentation completely
|
|
in documentation files.
|
|
|
|
See also \l {naturallanguage-variable} {naturallanguage} and
|
|
\l {outputencoding-variable} {outputencoding}.
|
|
|
|
\target sources-variable
|
|
\section1 sources
|
|
|
|
The \c sources variable allows you to specify individual source
|
|
files in addition to those located in the directories specified by
|
|
the \l {sourcedirs-variable} {sourcedirs} variable.
|
|
|
|
\code
|
|
sources = $QTDIR/src/gui/widgets/qlineedit.cpp \
|
|
$QTDIR/src/gui/widgets/qpushbutton.cpp
|
|
\endcode
|
|
|
|
When processing the \c sources variable, QDoc behaves in the same
|
|
way as it does when processing the \l {sourcedirs-variable}
|
|
{sourcedirs} variable. For more information, see the \l
|
|
{sourcedirs-variable} {sourcedirs} variable.
|
|
|
|
See also \l {sourcedirs-variable} {sourcedirs}.
|
|
|
|
\target sources.fileextensions-variable
|
|
\section1 sources.fileextensions
|
|
|
|
The \c sources.fileextensions variable filters the files within a
|
|
source directory.
|
|
|
|
When processing the source files specified in the \l {sourcedirs}
|
|
{\c sourcedirs} variable, QDoc will only read the files with the
|
|
fileextensions specified in the \c sources.fileextensions
|
|
variable. In this way QDoc avoid spending time reading irrelevant
|
|
files.
|
|
|
|
The default extensions are *.c++, *.cc, *.cpp and *.cxx.
|
|
|
|
The extensions are given as standard wildcard expressions. You
|
|
can add a file extension to the filter using '+='. For example:
|
|
|
|
\code
|
|
sources.fileextensions += *.CC
|
|
\endcode
|
|
|
|
\warning The above assignment may not work as described.
|
|
|
|
See also \l {sourcedirs-variable} {sourcedirs} and \l
|
|
(sources-variable} {sources}.
|
|
|
|
|
|
\target spurious-variable
|
|
\section1 spurious
|
|
|
|
The \c spurious variable excludes specified QDoc warnings from the
|
|
output. The warnings are specified using standard wildcard
|
|
expressions.
|
|
|
|
\code
|
|
spurious = "Cannot find .*" \
|
|
"Missing .*"
|
|
\endcode
|
|
|
|
makes sure that warnings matching either of these expressions,
|
|
will not be part of the output when running QDoc. For example
|
|
would the following warning be omitted from the output:
|
|
|
|
\code
|
|
qt-4.0/src/opengl/qgl_mac.cpp:156: Missing parameter name
|
|
\endcode
|
|
|
|
\target syntaxhighlighting
|
|
\section1 syntaxhighlighting
|
|
|
|
The \c syntaxhighlighting variable specifies whether QDoc should
|
|
perform syntax highlighting on source code quoted in the
|
|
documentation it generates.
|
|
|
|
\code
|
|
syntaxhighlighting = true
|
|
\endcode
|
|
|
|
will enable syntax highlighting for all supported programming
|
|
languages.
|
|
|
|
\target tabsize-variable
|
|
\section1 tabsize
|
|
|
|
The \c tabsize variable defines the size of a tab character.
|
|
|
|
\code
|
|
tabsize = 4
|
|
\endcode
|
|
|
|
will give the tab character the size of 4 spaces. The default
|
|
value of the variable is 8, and doesn't need to be specified.
|
|
|
|
\target tagfile-variable
|
|
\section1 tagfile
|
|
|
|
The \c tagfile variable specifies the Doxygen tag file to be
|
|
written when HTML is generated.
|
|
|
|
\target version-variable
|
|
\section1 version
|
|
|
|
The \c version variable specifies the version number of the
|
|
documented software.
|
|
|
|
\code
|
|
version = 4.0.1
|
|
\endcode
|
|
|
|
When a version number is specified (using the \tt{\l version} or
|
|
\tt {\l versionsym} variables in a \c .qdocconf file), it is
|
|
accessible through the corresponding \\version command for use in
|
|
the documentation.
|
|
|
|
\warning The \\version command's functionality is not fully
|
|
implemented; currently it only works within raw HTML code.
|
|
|
|
See also \l versionsym.
|
|
|
|
\target versionsym-variable
|
|
\section1 versionsym
|
|
|
|
The \c versionsym variable specifies a C++ preprocessor symbol
|
|
that defines the version number of the documented software.
|
|
|
|
For example in \l qt.qdocconf:
|
|
|
|
\code
|
|
versionsym = QT_VERSION_STR
|
|
\endcode
|
|
|
|
QT_VERSION_STR is defined in qglobal.h as follows
|
|
|
|
\code
|
|
#define QT_VERSION_STR "4.8.7"
|
|
\endcode
|
|
|
|
When a version number is specified (using the \tt{\l version} or
|
|
\tt {\l versionsym} variables in a \c .qdocconf file), it is
|
|
accessible through the corresponding \\version command for use in
|
|
the documentation.
|
|
|
|
\warning The \\version command's functionality is not fully
|
|
implemented; currently it only works within raw HTML code.
|
|
|
|
See also \l {version} {\\version}.
|
|
*/
|
|
|
|
/*!
|
|
\page 22-creating-help-project-files.html
|
|
\previouspage Generic Configuration Variables
|
|
\contentspage Table of Contents
|
|
\nextpage C++ Specific Configuration Variables
|
|
|
|
\title Creating Help Project Files
|
|
|
|
\section1 Overview
|
|
|
|
Starting with Qt 4.4, Qt Assistant uses a different system for managing
|
|
Qt documentation that requires QDoc to generate inventories of files in a
|
|
format that is similar to the old style DCF format, but with additional
|
|
features.
|
|
|
|
Instead of hard-coding information about the documentation sets for Qt,
|
|
QDoc allows configuration variables to be used to specify which pages are
|
|
to be used in each documentation set it generates. These are specified as
|
|
subvariables of the \c qch variable with each set declared using a unique
|
|
identifier as a subvariable.
|
|
|
|
For example, the configuration file for the Qt documentation defines a
|
|
\c Qt documentation set by specifying information about the set as
|
|
subvariables with the \c{qhp.Qt} prefix:
|
|
|
|
\code
|
|
qhp.Qt.file = qt.qhp
|
|
qhp.Qt.namespace = com.trolltech.qt.440
|
|
qhp.Qt.virtualFolder = qdoc
|
|
qhp.Qt.indexTitle = Qt Reference Documentation
|
|
qhp.Qt.indexRoot =
|
|
qhp.Qt.extraFiles = classic.css images/qt-logo.png
|
|
qhp.Qt.filterAttributes = qt 4.4.0 qtrefdoc
|
|
qhp.Qt.customFilters.Qt.name = Qt 4.4.0
|
|
qhp.Qt.customFilters.Qt.filterAttributes = qt 4.4.0
|
|
qhp.Qt.subprojects = classes overviews examples
|
|
qhp.Qt.subprojects.classes.title = Classes
|
|
qhp.Qt.subprojects.classes.indexTitle = Qt's Classes
|
|
qhp.Qt.subprojects.classes.selectors = class
|
|
qhp.Qt.subprojects.overviews.title = Overviews
|
|
qhp.Qt.subprojects.overviews.indexTitle = All Overviews and HOWTOs
|
|
qhp.Qt.subprojects.overviews.selectors = fake:page,group,module
|
|
qhp.Qt.subprojects.examples.title = Tutorials and Examples
|
|
qhp.Qt.subprojects.examples.indexTitle = Qt Examples
|
|
qhp.Qt.subprojects.examples.selectors = fake:example
|
|
\endcode
|
|
|
|
To create a table of contents for a manual, create a subproject with
|
|
a \c{type} property and set it to \c{manual}. The page in the documentation
|
|
referred to by the \c{indexTitle} property must contain a list of links
|
|
that acts as a table of contents for the whole manual. QDoc will take the
|
|
information in this list and create a table of contents for the subproject.
|
|
|
|
For example, the configuration file for Qt Creator defines only one
|
|
subproject for its documentation, including all the documentation in a
|
|
single manual:
|
|
|
|
\code
|
|
qhp.QtCreator.subprojects = manual
|
|
qhp.QtCreator.subprojects.manual.title = Qt Creator Manual
|
|
qhp.QtCreator.subprojects.manual.indexTitle = Qt Creator Manual
|
|
qhp.QtCreator.subprojects.manual.type = manual
|
|
\endcode
|
|
|
|
In this example, the page entitled "Qt Creator Manual" contains a nested
|
|
list of links to pages in the documentation which is duplicated in
|
|
Qt Assistant's Contents tab.
|
|
*/
|
|
|
|
/*!
|
|
\page 23-qdoc-configuration-cppvariables.html
|
|
\previouspage Creating Help Project Files
|
|
\contentspage Table of Contents
|
|
\nextpage HTML Specific Configuration Variables
|
|
|
|
\title C++ Specific Configuration Variables
|
|
|
|
The C++ specific configuration variables are provided to avoid
|
|
erroneous documentation due to non-standard C++ constructs.
|
|
|
|
\target Cpp.ignoredirectives-variable
|
|
\section1 Cpp.ignoredirectives
|
|
|
|
The \c Cpp.ignoredirectives variable makes QDoc ignore the
|
|
specified non-standard constructs, within C++ source code.
|
|
|
|
If not specified by the \tt {\l Cpp.ignoretokens} or \tt {\l
|
|
Cpp.ignoredirectives} variables, non-standard constructs
|
|
(typically macros) can result in erroneous documentation.
|
|
|
|
In \l qt.qdocconf:
|
|
|
|
\code
|
|
Cpp.ignoredirectives = Q_DECLARE_INTERFACE \
|
|
Q_DECLARE_OPERATORS_FOR_FLAGS \
|
|
Q_DECLARE_PRIVATE \
|
|
Q_DECLARE_PUBLIC \
|
|
Q_DISABLE_COPY \
|
|
Q_DUMMY_COMPARISON_OPERATOR \
|
|
Q_ENUMS \
|
|
Q_FLAGS \
|
|
Q_INTERFACES \
|
|
__attribute__
|
|
\endcode
|
|
|
|
makes sure that when processing the code below, for example, QDoc
|
|
will simply ignore the 'Q_ENUMS' and 'Q_FLAGS' expressions:
|
|
|
|
\code
|
|
class Q_CORE_EXPORT Qt {
|
|
Q_OBJECT
|
|
Q_ENUMS(Orientation TextFormat BackgroundMode
|
|
DateFormat ScrollBarPolicy FocusPolicy
|
|
ContextMenuPolicy CaseSensitivity
|
|
LayoutDirection ArrowType)
|
|
Q_ENUMS(ToolButtonStyle)
|
|
Q_FLAGS(Alignment)
|
|
Q_FLAGS(Orientations)
|
|
Q_FLAGS(DockWidgetAreas)
|
|
|
|
public:
|
|
...
|
|
};
|
|
\endcode
|
|
|
|
The Q_OBJECT macro, however, is an exception: QDoc recognizes this
|
|
particular non-standard construct, so there is no need specifying
|
|
it using the \tt {\l Cpp.ignoredirectives} variable.
|
|
|
|
Regarding the Q_CORE_EXPORT macro; see the documentation of the
|
|
\tt {\l Cpp.ignoretokens} variable.
|
|
|
|
See also \l Cpp.ignoretokens.
|
|
|
|
\target Cpp.ignoretokens-variable
|
|
\section1 Cpp.ignoretokens
|
|
|
|
The \c Cpp.ignoretokens variable makes QDoc ignore the specified
|
|
non-standard constructs, within C++ source code.
|
|
|
|
If not specified by the \tt {\l Cpp.ignoretokens} or \tt {\l
|
|
Cpp.ignoredirectives} variables, non-standard constructs
|
|
(typically macros) can result in erroneous documentation.
|
|
|
|
In \l qt.qdocconf:
|
|
|
|
\code
|
|
Cpp.ignoretokens = QAXFACTORY_EXPORT \
|
|
QM_EXPORT_CANVAS \
|
|
...
|
|
Q_COMPAT_EXPORT \
|
|
Q_CORE_EXPORT \
|
|
Q_EXPLICIT \
|
|
Q_EXPORT \
|
|
...
|
|
Q_TYPENAME \
|
|
Q_XML_EXPORT
|
|
\endcode
|
|
|
|
makes sure that when processing the code below, for example, QDoc
|
|
will simply ignore the 'Q_CORE_EXPORT' expression:
|
|
|
|
\code
|
|
class Q_CORE_EXPORT Qt {
|
|
Q_OBJECT
|
|
Q_ENUMS(Orientation TextFormat BackgroundMode
|
|
DateFormat ScrollBarPolicy FocusPolicy
|
|
ContextMenuPolicy CaseSensitivity
|
|
LayoutDirection ArrowType)
|
|
Q_ENUMS(ToolButtonStyle)
|
|
Q_FLAGS(Alignment)
|
|
Q_FLAGS(Orientations)
|
|
Q_FLAGS(DockWidgetAreas)
|
|
public:
|
|
...
|
|
};
|
|
\endcode
|
|
|
|
Regarding the Q_OBJECT, Q_ENUMS and Q_FLAGS macros; see the
|
|
documentation of the \tt {\l Cpp.ignoredirectives} variable.
|
|
|
|
See also \l Cpp.ignoredirectives.
|
|
*/
|
|
|
|
/*!
|
|
\page 24-qdoc-configuration-htmlvariables.html
|
|
\previouspage C++ Specific Configuration Variables
|
|
\contentspage Table of Contents
|
|
\nextpage Supporting Derived Projects
|
|
|
|
\title HTML Specific Configuration Variables
|
|
|
|
The HTML specific configuration variables define the generated
|
|
documentation's style, or define the contents of the
|
|
documentation's footer or postheader. The format of the variable
|
|
values are raw HTML.
|
|
|
|
\target HTML.footer-variable
|
|
\section1 HTML.footer
|
|
|
|
The \c HTML.footer variable defines the content of the generated
|
|
HTML documentation's footer.
|
|
|
|
The footer is rendered at the bottom of the generated
|
|
documentation page.
|
|
|
|
The variable's value is given as raw HTML code enclosed by
|
|
quotation marks. Note that if the value spans several lines, each
|
|
line needs to be enclosed by quotation marks.
|
|
|
|
For example in \l qt.qdocconf:
|
|
|
|
\code
|
|
HTML.footer = "<p /><address><hr /><div align=\"center\">\n" \
|
|
...
|
|
"</tr></table></div></address>"
|
|
\endcode
|
|
|
|
The complete variable entry in \l qt.qdocconf provides the
|
|
standard footer of the \l {http://qt.nokia.com/doc/4.0/index.html}
|
|
{Qt Reference Documentation}.
|
|
|
|
\target HTML.postheader-variable
|
|
\section1 HTML.postheader
|
|
|
|
The \c HTML.postheader variable defines the content of the
|
|
generated HTML documentation's postheader.
|
|
|
|
The header is rendered at the top of the generated documentation
|
|
page.
|
|
|
|
The variable's value is given as raw HTML enclosed by quotation
|
|
marks. Note that if the value spans several lines, each line needs
|
|
to be enclosed by quotation marks.
|
|
|
|
For example in \l qt.qdocconf:
|
|
|
|
\code
|
|
HTML.postheader = "<table border=\"0\"..." \
|
|
...
|
|
"<img src=\"images/trolltech-logo.png\" \
|
|
"align=\"right\" width=\"203\" height=\"32\""\
|
|
"border=\"0\" />" \
|
|
"</td></tr>" \
|
|
"</table>"
|
|
\endcode
|
|
|
|
The complete variable entry in \l qt.qdocconf provides the
|
|
standard header of the \l {http://qt.nokia.com/doc/4.0/index.html}
|
|
{Qt Reference Documentation}.
|
|
|
|
\target HTML.style-variable
|
|
\section1 HTML.style
|
|
|
|
The HTML.style variable defines the style for
|
|
the generated HTML documentation.
|
|
|
|
The variable's value is given as raw HTML enclosed by quotation
|
|
marks. Note that if the value spans several lines, each line needs
|
|
to be enclosed by quotation marks.
|
|
|
|
For example in \l qt.qdocconf:
|
|
|
|
\code
|
|
HTML.style = "h3.fn,span.fn" \
|
|
"{ margin-left: 1cm; text-indent: -1cm; }\n" \
|
|
"a:link { color: #004faf; text-decoration: none }\n" \
|
|
"a:visited" \
|
|
"{ color: #672967; text-decoration: none }\n" \
|
|
"td.postheader { font-family: sans-serif }\n" \
|
|
"tr.address { font-family: sans-serif }\n" \
|
|
"body { background: #ffffff; color: black; }"
|
|
\endcode
|
|
|
|
provides the HTML style for the \l
|
|
{http://qt.nokia.com/doc/4.0/index.html} {Qt Reference
|
|
Documentation}.
|
|
|
|
\target HTML.stylesheets-variable
|
|
\section1 HTML.stylesheets
|
|
|
|
The HTML.stylesheets variable defines a list of stylesheets
|
|
to use for the generated HTML documentation.
|
|
|
|
Using separate stylesheets for the documentation makes it easier
|
|
to customize and experiment with the style used once the contents
|
|
has been generated. Typically, it is only necessary to define a
|
|
single stylesheet for any set of documentation; for example:
|
|
|
|
\code
|
|
HTML.stylesheets = classic.css
|
|
\endcode
|
|
|
|
QDoc expects to find stylesheets in the directory containing the
|
|
\l qt.qdocconf file, and it will copy those specified to the output
|
|
directory alongside the HTML pages.
|
|
|
|
*/
|
|
|
|
/*!
|
|
\page 25-qdoc-configuration-derivedprojects.html
|
|
\previouspage HTML Specific Configuration Variables
|
|
\contentspage Table of Contents
|
|
\nextpage Compatibility Issues
|
|
|
|
\title Supporting Derived Projects
|
|
|
|
Some configuration variables allow you to use QDoc to support
|
|
Qt-based projects; i.e allow your project to contain links to the
|
|
online Qt documentation. This means that QDoc will be able to
|
|
create links to the class reference documentation, without any
|
|
explicit linking command.
|
|
|
|
\target description-variable
|
|
\section1 description
|
|
|
|
The description variable holds a short description of the
|
|
associated project.
|
|
|
|
See also \l project.
|
|
|
|
\target indexes-variable
|
|
\section1 indexes
|
|
|
|
The \c indexes variable lists the index files that will be used to
|
|
generate references.
|
|
|
|
For example. to make a derived Qt project contain links to the Qt
|
|
Reference documentation, you need to specify the associated index
|
|
file:
|
|
|
|
\code
|
|
indexes = $QTDIR/doc/html/qt.index
|
|
\endcode
|
|
|
|
See also \l project and \l url.
|
|
|
|
\target project-variable
|
|
\section1 project
|
|
|
|
The \c project variable provides a name for the project associated
|
|
with the \c .qdocconf file.
|
|
|
|
The project's name is used to form a file name for the associated
|
|
project's \e index file.
|
|
|
|
\code
|
|
project = QtMotif
|
|
\endcode
|
|
|
|
This will cause an index file called \c qtmotif.index to be
|
|
created.
|
|
|
|
See also \l description and \l indexes.
|
|
|
|
\target url-variable
|
|
\section1 url
|
|
|
|
The \c url variable holds the base URL for the reference
|
|
documentation associated with the current project.
|
|
|
|
The URL is stored in the generated index file for the
|
|
project. When we use the index on its own, QDoc will use this as
|
|
the base URL when constructing links to classes, functions, and
|
|
other things listed in the index.
|
|
|
|
\code
|
|
project = Qt
|
|
description = Qt Reference Documentation
|
|
url = http://qt.nokia.com/doc/4.0
|
|
|
|
...
|
|
\endcode
|
|
|
|
This makes sure that whenever \c qt.index is used to generate
|
|
references to for example Qt classes, the base URL is \c
|
|
http://qt.nokia.com/doc/4.0.
|
|
|
|
See also \l indexes.
|
|
|
|
\target howto
|
|
\section1 How to Support Derived Projects
|
|
|
|
This feature makes use of the comprehensive indexes generated by
|
|
QDoc when it creates the Qt reference documentation.
|
|
|
|
For example, \l qt.qdocconf (the configuration file for Qt)
|
|
contains the following variable definitions:
|
|
|
|
\code
|
|
project = Qt
|
|
description = Qt Reference Documentation
|
|
url = http://qt.nokia.com/doc/4.0
|
|
|
|
...
|
|
\endcode
|
|
|
|
The \l project variable name is used to form a file name for the
|
|
index file; in this case the \c qt.index file is created. The \l
|
|
url is stored in the index file. Later, when we use the index on
|
|
its own, QDoc will use this as the base URL when constructing
|
|
links to classes, functions, and other things listed in the index.
|
|
|
|
In a mini-project, you can use an index file by defining an \l
|
|
indexes configuration variable in your \c .qdocconf file.
|
|
|
|
For example, you can create a \c qtmotif.qdocconf file to help you
|
|
check the QtMotif documentation (which is part of Qt Solutions):
|
|
|
|
\code
|
|
include($QTDIR/tools/qdoc3/test/compat.qdocconf)
|
|
|
|
project = QtMotif
|
|
description = QtMotif Class Documentation
|
|
url = http://www.trolltech.com/products/solutions/catalog/4/Migration/qtmotifextension
|
|
|
|
indexes = $QTDIR/doc/html/qt.index
|
|
|
|
outputdir = html
|
|
|
|
headerdirs = src
|
|
sourcedirs = src \
|
|
examples
|
|
sources.fileextensions = "*.cpp *.qdoc *.doc"
|
|
|
|
exampledirs = examples
|
|
\endcode
|
|
|
|
The code above requires that you run QDoc from the directory that
|
|
contains this file. You need to include the compat.qdocconf
|
|
file for compatibility reasons; this is further explained in the
|
|
\l {Compatibility Issues} section.
|
|
|
|
\bold {To resolve the actual links to Qt classes, the
|
|
mini-project's \c .qdocconf file needs to assign a value to the \l
|
|
indexes variable; \c $QTDIR/doc/html/qt.index makes sure that you
|
|
always use the updated index file for the Qt documentation.}
|
|
|
|
The only disadvantages with this approach are the extra file that
|
|
QDoc has to generate and the time it takes to do so. Reading the
|
|
index back again later isn't instantaneous either, but it's
|
|
quicker than processing all the Qt classes each time you need to
|
|
write a new document.
|
|
*/
|
|
|
|
/*!
|
|
\page 26-qdoc-commands-compatibility.html
|
|
\previouspage Supporting Derived Projects
|
|
\contentspage Table of Contents
|
|
\nextpage qt.qdocconf
|
|
|
|
\title Compatibility Issues
|
|
|
|
\section1 General Description
|
|
|
|
\target reason
|
|
|
|
Because QDoc evolves to suit our documentation needs, there can be
|
|
some compatibility issues when converting to a new version.
|
|
|
|
To allow you to proceed at your own speed when converting your
|
|
qdoc comments to use new qdoc commands and formats, the ability to
|
|
include a configuration file called \c {compat.qdocconf} is
|
|
provided.
|
|
|
|
A \c {compat.qdocconf} file is a separate configuration file,
|
|
which you include in your main configuration file. It typically
|
|
contains the mappings from old qdoc commands to new ones using
|
|
\l {alias} and
|
|
\l {22-qdoc-configuration-generalvariables.html#macro-variable}
|
|
{macro} configuration variables.
|
|
|
|
\section1 Qt Compatibility
|
|
|
|
In Qt's documentation there still exist occurrences of old
|
|
commands, and the Qt \l {qt.qdocconf} {configuration file} needs to
|
|
include the compat.qdocconf file tailored for Qt. For more
|
|
detailed information about the commands creating compatibility
|
|
issues, see the \l {Command Comments} {command comments}.
|
|
|
|
\section1 Qt's current compat.qdocconf file
|
|
|
|
\quotefile files/compat.qdocconf
|
|
|
|
\section1 Command Comments
|
|
|
|
\table
|
|
\header
|
|
\o New Command
|
|
\o Old Command
|
|
\o Description
|
|
|
|
\row
|
|
\o \\i \target i-versus-e
|
|
\o \\e
|
|
\o Earlier we
|
|
used the \\i command to indicate a list or table item, and
|
|
the \\e command for rendering in italic. Now we want the
|
|
\\i command to render in italic discarding the
|
|
\\e command name.
|
|
|
|
\bold {We still need to use the \\e command to render in
|
|
italic in new documentation for \l {reason} {compatibility
|
|
reasons}}.
|
|
|
|
\row
|
|
\o \\include \target include-versus-input
|
|
\o \\input
|
|
\o The \\include command was previously used to quote the
|
|
complete contents of a source file, now we want to use the
|
|
command to include separate documentation.
|
|
That is the functionality of the old \\input command
|
|
which name we want to discard.
|
|
|
|
\bold {We still need to use the \\input command to include
|
|
plain text in new documentation for \l
|
|
{reason} {compatibility reasons}}.
|
|
|
|
\row
|
|
\o \\quotefile \target quotefile-versus-include
|
|
\o \\include
|
|
\o Earlier, we have used the \\quotefile command to
|
|
quote from file, i.e. quote parts from file, and the
|
|
\\include command to quote the entire file. Since we now want
|
|
\\include to include separate documentation, we change the use of
|
|
\\quotefile to quote a complete source file.
|
|
|
|
\bold {We still need to use the \\include command to quote
|
|
the entire contents of a source file in new documentation
|
|
for \l {reason} {compatibility reasons}}.
|
|
|
|
\row
|
|
\o \\quotefromfile \target quotefromfile-versus-quotefile
|
|
\o \\quotefile
|
|
\o Earlier, we have used the \\quotefile command to
|
|
quote from file, i.e. quote parts from file. Since we now want
|
|
that command to quote an entire file, we introduce the new
|
|
\\quotefromfile command to quote from file.
|
|
|
|
\bold {Use \l {quotefromfile-command} {\\quotefromfile} to quote
|
|
parts from a source file in new documentation}.
|
|
|
|
\row
|
|
\o \\o \target o-versus-i
|
|
\o \\i
|
|
\o Earlier we used the \\i command to indicate list items
|
|
and table items. Since we now want the \\i command to render
|
|
in italic instead, we introduce the new \\o command for
|
|
this purpose.
|
|
|
|
\bold {Use \l {o-command} {\\o} to indicate list and table items in
|
|
new documentation}.
|
|
|
|
\row
|
|
\o \\quotation \target quotation-versus-quote
|
|
\o \\quote
|
|
\o These commands are equivalent, and represent a simple name
|
|
change.
|
|
|
|
\bold {Use \l {quotation} {\\quotation} in new
|
|
documentation}.
|
|
|
|
\row
|
|
\o \\image \target image-versus-img
|
|
\o \\img
|
|
\o These commands are equivalent, and represent a simple name
|
|
change.
|
|
|
|
\bold {Use \l {image-command} {\\image} in new documentation}.
|
|
|
|
\endtable
|
|
*/
|
|
|
|
/*!
|
|
\page 27-qdoc-commmands-alphabetical.html
|
|
\previouspage Introduction to QDoc
|
|
\contentspage Table of Contents
|
|
\nextpage Topic Commands
|
|
|
|
\title Command Index
|
|
|
|
This is a complete, alphabetized list of the QDoc commands.
|
|
|
|
\list
|
|
|
|
\o \l {04-qdoc-commands-textmarkup.html#a-command} {\\a}
|
|
\o \l {11-qdoc-commands-specialcontent.html#abstract-command} {\\abstract}
|
|
\o \l {06-qdoc-commands-includecodeinline.html#badcode-command} {\\badcode}
|
|
\o \l {04-qdoc-commands-textmarkup.html#bold-command} {\\bold}
|
|
\o \l {11-qdoc-commands-specialcontent.html#brief-command} {\\brief}
|
|
\o \l {04-qdoc-commands-textmarkup.html#c-command} {\\c}
|
|
\o \l {09-qdoc-commands-includingimages.html#caption-command} {\\caption}
|
|
\o \l {05-qdoc-commands-documentstructure.html#chapter-command} {\\chapter}
|
|
\o \l {13-qdoc-commands-topics.html#class-command} {\\class}
|
|
\o \l {06-qdoc-commands-includecodeinline.html#code-command} {\\code}
|
|
\o \l {07-0-qdoc-commands-includingexternalcode.html#codeline-command} {\\codeline},
|
|
\o \l {16-qdoc-commands-status.html#compat-command} {\\compat}
|
|
\o \l {15-qdoc-commands-navigation.html#contentspage-command} {\\contentspage}
|
|
\o \l {16-qdoc-commands-status.html#default-command} {\\default} \span {class="newStuff"} {(new)}
|
|
\o \l {04-qdoc-commands-textmarkup.html#div-command} {\\div} \span {class="newStuff"} {(new)}
|
|
\o \l {07-0-qdoc-commands-includingexternalcode.html#dots-command} {\\dots}
|
|
\o \l {12-0-qdoc-commands-miscellaneous.html#else-command} {\\else}
|
|
\o \l {12-0-qdoc-commands-miscellaneous.html#endif-command} {\\endif}
|
|
\o \l {13-qdoc-commands-topics.html#enum-command} {\\enum}
|
|
\o \l {13-qdoc-commands-topics.html#example-command} {\\example}
|
|
\o \l {12-0-qdoc-commands-miscellaneous.html#expire-command} {\\expire}
|
|
\o \l {13-qdoc-commands-topics.html#externalpage-command} {\\externalpage}
|
|
\o \l {13-qdoc-commands-topics.html#fn-command} {\\fn}
|
|
\o \l {11-qdoc-commands-specialcontent.html#footnote-command} {\\footnote}
|
|
\o \l {12-0-qdoc-commands-miscellaneous.html#generatelist-command} {\\generatelist}
|
|
\o \l {13-qdoc-commands-topics.html#group-command} {\\group}
|
|
\o \l {10-qdoc-commands-tablesandlists.html#header-command} {\\header}
|
|
\o \l {13-qdoc-commands-topics.html#headerfile-command} {\\headerfile}
|
|
\o \l {04-qdoc-commands-textmarkup.html#i-command} {\\i}
|
|
\o \l {12-0-qdoc-commands-miscellaneous.html#if-command} {\\if}
|
|
\o \l {09-qdoc-commands-includingimages.html#image-command} {\\image}
|
|
\o \l {12-0-qdoc-commands-miscellaneous.html#include-command} {\\include}
|
|
\o \l {15-qdoc-commands-navigation.html#indexpage-command} {\\indexpage}
|
|
\o \l {19-qdoc-commands-grouping.html#ingroup-command} {\\ingroup}
|
|
\o \l {18-qdoc-commands-relating.html#inherits-command}{\\inherits} \span {class="newStuff"} {(new)}
|
|
\o \l {19-qdoc-commands-grouping.html#inmodule-command} {\\inmodule}
|
|
\o \l {09-qdoc-commands-includingimages.html#inlineimage-command} {\\inlineimage}
|
|
\o \l {16-qdoc-commands-status.html#internal-command} {\\internal}
|
|
\o \l {08-qdoc-commands-creatinglinks.html#keyword-command} {\\keyword}
|
|
\o \l {08-qdoc-commands-creatinglinks.html#l-command} {\\l}
|
|
\o \l {11-qdoc-commands-specialcontent.html#legalese-command} {\\legalese}
|
|
\o \l {10-qdoc-commands-tablesandlists.html#list-command} {\\list}
|
|
\o \l {13-qdoc-commands-topics.html#macro-command} {\\macro}
|
|
\o \l {19-qdoc-commands-grouping.html#mainclass-command} {\\mainclass}
|
|
\o \l {12-0-qdoc-commands-miscellaneous.html#meta-command} {\\meta}
|
|
\o \l {13-qdoc-commands-topics.html#module-command} {\\module}
|
|
\o \l {13-qdoc-commands-topics.html#namespace-command} {\\namespace}
|
|
\o \l {15-qdoc-commands-navigation.html#nextpage-command} {\\nextpage}
|
|
\o \l {06-qdoc-commands-includecodeinline.html#newcode-command} {\\newcode}
|
|
\o \l {17-qdoc-commands-thread.html#nonreentrant-command} {\\nonreentrant}
|
|
\o \l {10-qdoc-commands-tablesandlists.html#o-command} {\\o}
|
|
\o \l {16-qdoc-commands-status.html#obsolete-command} {\\obsolete}
|
|
\o \l {06-qdoc-commands-includecodeinline.html#oldcode-command} {\\oldcode}
|
|
\o \l {12-0-qdoc-commands-miscellaneous.html#omit-command} {\\omit}
|
|
\o \l {10-qdoc-commands-tablesandlists.html#omitvalue-command} {\\omitvalue}
|
|
\o \l {18-qdoc-commands-relating.html#overload-command} {\\overload}
|
|
\o \l {13-qdoc-commands-topics.html#page-command} {\\page}
|
|
\o \l {05-qdoc-commands-documentstructure.html#part-command} {\\part}
|
|
\o \l {16-qdoc-commands-status.html#preliminary-command} {\\preliminary}
|
|
\o \l {15-qdoc-commands-navigation.html#previouspage-command} {\\previouspage}
|
|
\o \l {07-0-qdoc-commands-includingexternalcode.html#printline-command} {\\printline}
|
|
\o \l {07-0-qdoc-commands-includingexternalcode.html#printto-command} {\\printto}
|
|
\o \l {07-0-qdoc-commands-includingexternalcode.html#printuntil-command} {\\printuntil}
|
|
\o \l {13-qdoc-commands-topics.html#property-command} {\\property}
|
|
\o \l {13-qdoc-commands-topics.html#qmlattachedproperty-command} {\\qmlattachedproperty} \span {class="newStuff"} {(new)}
|
|
\o \l {13-qdoc-commands-topics.html#qmlattachedsignal-command} {\\qmlattachedsignal} \span {class="newStuff"} {(new)}
|
|
\o \l {13-qdoc-commands-topics.html#qmlbasictype-command} {\\qmlbasictype} \span {class="newStuff"} {(new)}
|
|
\o \l {13-qdoc-commands-topics.html#qmlclass-command} {\\qmlclass} \span {class="newStuff"} {(new)}
|
|
\o \l {13-qdoc-commands-topics.html#qmlmethod-command} {\\qmlmethod} \span {class="newStuff"} {(new)}
|
|
\o \l {13-qdoc-commands-topics.html#qmlproperty-command} {\\qmlproperty} \span {class="newStuff"} {(new)}
|
|
\o \l {13-qdoc-commands-topics.html#qmlsignal-command} {\\qmlsignal} \span {class="newStuff"} {(new)}
|
|
\o \l {11-qdoc-commands-specialcontent.html#quotation-command} {\\quotation}
|
|
\o \l {07-0-qdoc-commands-includingexternalcode.html#quotefile-command} {\\quotefile}
|
|
\o \l {07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command} {\\quotefromfile}
|
|
\o \l {12-0-qdoc-commands-miscellaneous.html#raw-command} {\\raw} \span {class="newStuff"} {(avoid)}
|
|
\o \l {17-qdoc-commands-thread.html#reentrant-command} {\\reentrant}
|
|
\o \l {18-qdoc-commands-relating.html#reimp-command} {\\reimp}
|
|
\o \l {18-qdoc-commands-relating.html#relates-command} {\\relates}
|
|
\o \l {10-qdoc-commands-tablesandlists.html#row-command} {\\row}
|
|
\o \l {08-qdoc-commands-creatinglinks.html#sa-command} {\\sa}
|
|
\o \l {05-qdoc-commands-documentstructure.html#sectionOne-command} {\\section1}
|
|
\o \l {05-qdoc-commands-documentstructure.html#sectionTwo-command} {\\section2}
|
|
\o \l {05-qdoc-commands-documentstructure.html#sectionThree-command} {\\section3}
|
|
\o \l {05-qdoc-commands-documentstructure.html#sectionFour-command} {\\section4}
|
|
\o \l {13-qdoc-commands-topics.html#service-command} {\\service}
|
|
\o \l {16-qdoc-commands-status.html#since-command} {\\since}
|
|
\o \l {07-0-qdoc-commands-includingexternalcode.html#skipline-command} {\\skipline}
|
|
\o \l {07-0-qdoc-commands-includingexternalcode.html#skipto-command} {\\skipto}
|
|
\o \l {07-0-qdoc-commands-includingexternalcode.html#skipuntil-command} {\\skipuntil}
|
|
\o \l {07-0-qdoc-commands-includingexternalcode.html#snippet-command} {\\snippet},
|
|
\o \l {04-qdoc-commands-textmarkup.html#span-command} {\\span} \span {class="newStuff"} {(new)}
|
|
\o \l {15-qdoc-commands-navigation.html#startpage-command} {\\startpage}
|
|
\o \l {04-qdoc-commands-textmarkup.html#sub-command} {\\sub}
|
|
\o \l {20-qdoc-commands-namingthings.html#subtitle-command} {\\subtitle}
|
|
\o \l {04-qdoc-commands-textmarkup.html#sup-command} {\\sup}
|
|
\o \l {10-qdoc-commands-tablesandlists.html#table-command} {\\table}
|
|
\o \l {11-qdoc-commands-specialcontent.html#tableofcontents-command} {\\tableofcontents}
|
|
\o \l {08-qdoc-commands-creatinglinks.html#target-command} {\\target}
|
|
\o \l {17-qdoc-commands-thread.html#threadsafe-command} {\\threadsafe}
|
|
\o \l {20-qdoc-commands-namingthings.html#title-command} {\\title}
|
|
\o \l {04-qdoc-commands-textmarkup.html#tt-command} {\\tt}
|
|
\o \l {13-qdoc-commands-topics.html#typedef-command} {\\typedef}
|
|
\o \l {04-qdoc-commands-textmarkup.html#underline-command} {\\underline}
|
|
\o \l {13-qdoc-commands-topics.html#variable-command} {\\variable}
|
|
\o \l {10-qdoc-commands-tablesandlists.html#value-command} {\\value}
|
|
\o \l {11-qdoc-commands-specialcontent.html#warning-command} {\\warning}
|
|
\endlist
|
|
*/
|
|
|
|
/*!
|
|
\externalpage http://qt.nokia.com/about
|
|
\title About Qt
|
|
*/
|