summaryrefslogtreecommitdiffstats
path: root/tools/qdoc3/doc/qdoc-manual.qdoc
diff options
context:
space:
mode:
Diffstat (limited to 'tools/qdoc3/doc/qdoc-manual.qdoc')
-rw-r--r--tools/qdoc3/doc/qdoc-manual.qdoc8695
1 files changed, 8695 insertions, 0 deletions
diff --git a/tools/qdoc3/doc/qdoc-manual.qdoc b/tools/qdoc3/doc/qdoc-manual.qdoc
new file mode 100644
index 0000000..e2f670c
--- /dev/null
+++ b/tools/qdoc3/doc/qdoc-manual.qdoc
@@ -0,0 +1,8695 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights. These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page index.html
+ \nextpage QDoc Manual
+
+ \title QDoc Manual - Table of Contents
+
+ \list
+ \o \l{QDoc Manual}
+ \o \l{QDoc Commands}
+ \list
+ \o \l{Markup Commands}
+ \o \l{Text Formatting Commands}
+ \o \l{Document Structuring Commands}
+ \o \l{Verbatim Code Commands}
+ \o \l{Quoting External Code Commands}
+ \list
+ \o \l{Example File}
+ \endlist
+ \o \l{Linking Commands}
+ \o \l{Graphic Commands}
+ \o \l{Container Commands}
+ \o \l{Document Contents Commands}
+ \o \l{Miscellaneous Commands}
+ \list
+ \o \l{signalandslots.qdocinc}
+ \o \l{objectmodel.qdocinc}
+ \o \l{layoutmanagement.qdocinc}
+ \endlist
+ \o \l{Topical Commands}
+ \o \l{Contextual Commands}
+ \o \l{Navigation Commands}
+ \o \l{Status Commands}
+ \o \l{Thread Support Commands}
+ \o \l{Relating Commands}
+ \o \l{Grouping Commands}
+ \o \l{Title Commands}
+ \endlist
+ \o \l{QDoc Configuration}
+ \list
+ \o \l{General Variables}
+ \o \l{Creating Help Project Files}
+ \o \l{C++ Specific Variables}
+ \o \l{HTML Specific Variables}
+ \o \l{Supporting Derived Projects}
+ \o \l{QDoc Compatibility}
+ \o \l{qt.qdocconf}
+ \o \l{minimum.qdocconf}
+ \endlist
+ \o \l{QDoc Commands - Alphabetical List}
+ \endlist
+*/
+
+/*!
+ \page 01-qdoc-manual.html
+ \contentspage QDoc Manual - Table of Contents
+ \previouspage QDoc Manual - Table of Contents
+ \nextpage QDoc Commands
+
+ \title QDoc Manual
+
+ QDoc is the internal tool used by Qt Development Frameworks for generating
+ documentation. This document is a reference for QDoc command syntax and
+ configuration.
+
+ \section1 Overview
+
+ \list I
+ \o \section2 \l {QDoc Commands}
+
+ \l {QDoc Commands - Alphabetical List}{A complete alphabetical
+ list}.
+
+ There are two main categories of commands for QDoc: markup
+ commands and meta-commands.
+
+ The markup commands indicate the generated documentation's
+ appearance and logical structure. The meta-commands provide
+ information about the document as well as the documented
+ item. The meta-commands can be further categorized as topical
+ commands and contextual commands.
+
+ \list
+ \o \l {Markup Commands}
+ \list
+ \o \l {Text Formatting Commands}{Text Formatting}
+ \o \l {Document Structuring Commands}{Document Structuring}
+ \o \l {Verbatim Code Commands}{Verbatim Code}
+ \o \l {Quoting External Code Commands}{Quoting External Code}
+ \o \l {Linking Commands}{Linking}
+ \o \l {Graphic Commands}{Graphic}
+ \o \l {Container Commands}{Container}
+ \o \l {Document Contents Commands}{Document Contents}
+ \o \l {Miscellaneous Commands}{Miscellaneous}
+ \endlist
+ \o \l {Topical Commands}
+ \o \l {Contextual Commands}
+ \list
+ \o \l {Navigation Commands}{Navigation}
+ \o \l {Status Commands}{Status}
+ \o \l {Thread Support Commands}{Thread Support}
+ \o \l {Relating Commands}{Relating}
+ \o \l {Grouping Commands}{Grouping}
+ \o \l {Title Commands}{Title}
+ \endlist
+ \endlist
+ \endlist
+
+ \list II
+ \o \section2 \l {QDoc Configuration}
+
+ When running QDoc to generate the documentation, you must
+ specify a configuration file on the command line. The
+ configuration file is a list of entries of entries of the form
+ "variable = value".
+
+ \list
+ \o \l {Configuration Variables}
+ \o \l {Configuration File Examples}
+ \endlist
+
+ Some particular configuration variables allow you to use QDoc
+ to support Qt-based projects; i.e to make projects, such as Qt
+ Solutions, contain references to the online Qt documentation.
+
+ \list
+ \o \l {Supporting Derived Projects}
+ \endlist
+
+ QDoc is a tool that constantly evolves to suit our needs, for
+ that reason there are some compatibility issues between old and
+ new practices.
+
+ \list
+ \o \l {QDoc Compatibility}
+ \endlist
+ \endlist
+*/
+
+/*!
+ \page 02-qdoc-commands.html
+ \previouspage QDoc Manual
+ \contentspage QDoc Manual - Table of Contents
+ \nextpage Markup Commands
+
+ \title QDoc Commands
+
+ There are two main categories of commands for QDoc: markup
+ commands and meta-commands.
+
+ The markup commands indicate the generated documentation's visual
+ appearance and logical structure. The meta-commands provide
+ information about the documentation unit as well as the documented
+ item. The meta-commands can be further categorized as topical
+ commands and contextual commands.
+
+ \section1 Alphabetical List
+
+ A complete \l{QDoc Commands - Alphabetical List }
+ {alphabetical list of the QDoc commands}.
+
+ \section1 Categories
+
+ \list
+ \o \l {Markup Commands}
+ \o \l {Topical Commands}
+ \o \l {Contextual Commands}
+ \endlist
+*/
+
+/*!
+ \page 03-qdoc-commands-markup.html
+ \contentspage QDoc Manual - Table of Contents
+ \previouspage QDoc Commands
+ \nextpage Text Formatting Commands
+
+ \title Markup Commands
+
+ The markup commands indicate the generated documentation's visual
+ appearance and logical structure.
+
+ \section1 Alphabetical List
+
+ \l {04-qdoc-commands-textformatting.html#backslash}{\\\\},
+ \l {04-qdoc-commands-textformatting.html#a}{\\a},
+ \l {11-qdoc-commands-documentcontents.html#abstract}{\\abstract},
+ \l {06-qdoc-commands-verbatimcode.html#badcode}{\\badcode},
+ \l {04-qdoc-commands-textformatting.html#bold}{\\bold},
+ \l {11-qdoc-commands-documentcontents.html#brief}{\\brief},
+ \l {04-qdoc-commands-textformatting.html#c}{\\c},
+ \l {09-qdoc-commands-graphic.html#caption}{\\caption},
+ \l {05-qdoc-commands-documentstructuring.html#chapter}{\\chapter},
+ \l {06-qdoc-commands-verbatimcode.html#code}{\\code},
+ \l {07-0-qdoc-commands-quoting.html#codeline}{\\codeline},
+ \l {07-0-qdoc-commands-quoting.html#dots}{\\dots},
+ \l {12-0-qdoc-commands-miscellaneous.html#else}{\\else},
+ \l {12-0-qdoc-commands-miscellaneous.html#endif}{\\endif},
+ \l {12-0-qdoc-commands-miscellaneous.html#expire}{\\expire},
+ \l {11-qdoc-commands-documentcontents.html#footnote}{\\footnote},
+ \l {12-0-qdoc-commands-miscellaneous.html#generatelist}{\\generatelist},
+ \l {10-qdoc-commands-container.html#header}{\\header},
+ \l {04-qdoc-commands-textformatting.html#i}{\\i},
+ \l {12-0-qdoc-commands-miscellaneous.html#if}{\\if},
+ \l {09-qdoc-commands-graphic.html#image}{\\image},
+ \l {12-0-qdoc-commands-miscellaneous.html#include}{\\include},
+ \l {09-qdoc-commands-graphic.html#inlineimage}{\\inlineimage},
+ \l {08-qdoc-commands-linking.html#keyword}{\\keyword},
+ \l {08-qdoc-commands-linking.html#l}{\\l},
+ \l {11-qdoc-commands-documentcontents.html#legalese}{\\legalese},
+ \l {10-qdoc-commands-container.html#list}{\\list},
+ \l {12-0-qdoc-commands-miscellaneous.html#meta}{\\meta},
+ \l {06-qdoc-commands-verbatimcode.html#newcode}{\\newcode},
+ \l {10-qdoc-commands-container.html#o}{\\o},
+ \l {06-qdoc-commands-verbatimcode.html#oldcode}{\\oldcode},
+ \l {12-0-qdoc-commands-miscellaneous.html#omit}{\\omit},
+ \l {05-qdoc-commands-documentstructuring.html#part}{\\part},
+ \l {07-0-qdoc-commands-quoting.html#printline}{\\printline},
+ \l {07-0-qdoc-commands-quoting.html#printto}{\\printto},
+ \l {07-0-qdoc-commands-quoting.html#printuntil}{\\printuntil},
+ \l {11-qdoc-commands-documentcontents.html#quotation}{\\quotation},
+ \l {07-0-qdoc-commands-quoting.html#quotefile}{\\quotefile},
+ \l {07-0-qdoc-commands-quoting.html#quotefromfile}{\\quotefromfile},
+ \l {12-0-qdoc-commands-miscellaneous.html#raw}{\\raw},
+ \l {10-qdoc-commands-container.html#row}{\\row},
+ \l {08-qdoc-commands-linking.html#sa}{\\sa},
+ \l {05-qdoc-commands-documentstructuring.html#sectionOne}{\\section1},
+ \l {05-qdoc-commands-documentstructuring.html#sectionTwo}{\\section2},
+ \l {05-qdoc-commands-documentstructuring.html#sectionThree}{\\section3},
+ \l {05-qdoc-commands-documentstructuring.html#sectionFour}{\\section4},
+ \l {07-0-qdoc-commands-quoting.html#skipline}{\\skipline},
+ \l {07-0-qdoc-commands-quoting.html#skipto}{\\skipto},
+ \l {07-0-qdoc-commands-quoting.html#skipuntil}{\\skipuntil},
+ \l {07-0-qdoc-commands-quoting.html#snippet}{\\snippet},
+ \l {04-qdoc-commands-textformatting.html#sub}{\\sub},
+ \l {04-qdoc-commands-textformatting.html#sup}{\\sup},
+ \l {10-qdoc-commands-container.html#table}{\\table},
+ \l {11-qdoc-commands-documentcontents.html#tableofcontents}
+ {\\tableofcontents},
+ \l {08-qdoc-commands-linking.html#target}{\\target},
+ \l {04-qdoc-commands-textformatting.html#tt}{\\tt},
+ \l {04-qdoc-commands-textformatting.html#underline}{\\underline},
+ \l {12-0-qdoc-commands-miscellaneous.html#raw}{\\unicode},
+ \l {11-qdoc-commands-documentcontents.html#warning}{\\warning}
+
+ \section1 Categories
+ \list
+ \o \l {Text Formatting Commands}
+ \o \l {Document Structuring Commands}
+ \o \l {Verbatim Code Commands}
+ \o \l {Quoting External Code Commands}
+ \o \l {Linking Commands}
+ \o \l {Graphic Commands}
+ \o \l {Container Commands}
+ \o \l {Document Contents Commands}
+ \o \l {Miscellaneous Commands}
+ \endlist
+
+*/
+
+/*!
+ \page 04-qdoc-commands-textformatting.html
+ \contentspage QDoc Manual - Table of Contents
+ \previouspage Markup Commands
+ \nextpage Document Structuring Commands
+
+ \title Text Formatting Commands
+
+ The text formatting commands indicate how the regular text in the
+ documentation is rendered.
+
+ \section1 Alphabetical List
+
+ \l {04-qdoc-commands-textformatting.html#backslash}{\\\\},
+ \l {04-qdoc-commands-textformatting.html#a}{\\a},
+ \l {04-qdoc-commands-textformatting.html#bold}{\\bold},
+ \l {04-qdoc-commands-textformatting.html#c}{\\c},
+ \l {04-qdoc-commands-textformatting.html#i}{\\i},
+ \l {04-qdoc-commands-textformatting.html#sub}{\\sub},
+ \l {04-qdoc-commands-textformatting.html#sup}{\\sup},
+ \l {04-qdoc-commands-textformatting.html#tt}{\\tt},
+ \l {04-qdoc-commands-textformatting.html#underline}{\\underline}
+
+ \section1 Command Descriptions
+
+ \table
+ \header
+ \o Command
+ \o Description
+
+ \row
+
+ \o \bold \\\\ \target backslash
+ \o \bold {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. For example:
+
+ \code
+ / *!
+ The \\\\ command is useful if you want a
+ backslash to appear verbatim, for example,
+ writing C:\\windows\\home\\.
+ * /
+ \endcode
+
+ will be rendered 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}{\\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
+
+ will be rendered 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
+
+ \row
+ \o \bold \\a \target a
+ \o \bold {The \\a command indicates that the next word
+ is a parameter when documenting functions.}
+
+ Warnings are emitted when function parameters are
+ undocumented or misspelled, so whenever you write
+ documentation for functions you should make sure you
+ mention all the parameters and precede each of these by the
+ \\a command. The parameter is then rendered in italic. For
+ example:
+
+ \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
+
+ will be rendered 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
+
+ The \\a command follows the same conventions as the \l
+ {i}{\\i} command for \l {argument}{punctuation, parentheses
+ and use of braces} for the argument. However, a parameter
+ is always a single word, so braces are rarely
+ necessary. And for the same reason, parentheses seldom
+ occur.
+
+ \row
+ \o \bold \\c \target c
+ \o \bold {The \\c command can be used to render variables,
+ user-defined classes and C++ keywords like \c int,
+ \c for, etc.}
+
+ 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
+
+ will be rendered as
+
+ \quotation
+ The \c AnalogClock class provides a clock widget with hour
+ and minute hands that is automatically updated every
+ few seconds.
+ \endquotation
+
+ The \\c command follows the same conventions as the \l
+ {i}{\\i} command for \l {argument}{punctuation, parentheses
+ and use of braces} for the argument.
+
+ 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}{teletype (\\tt)} command instead.
+
+ See also \l {tt}{\\tt} and \l {code}{\\code}.
+
+ \row
+ \o \bold \\tt \target tt
+ \o \bold {The \\tt command can be used to render variables,
+ user-defined classes and C++ keywords like \c int, \c
+ for, etc.}
+
+ The \\tt command behaves just like the \l {c}{\\c} command,
+ except that \\tt parses QDoc commands (like \l {i}{\\i}, \l
+ {bold}{\\bold} and \l {underline}{\\underline}) contained
+ within its argument.
+
+ The command renders its argument using a monospace
+ font. For example:
+
+ \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_\i{objectName}_\i{signalName}().}
+ * /
+ \endcode
+
+ will be rendered 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_\i{objectName}_\i{signalName}().}
+ \endquotation
+
+ The \\tt command follows the same conventions as the \l
+ {i}{\\i} command for \l {argument}{punctuation, parentheses
+ and use of braces} for the argument.
+
+ See also \l {c}{\\c}.
+
+ \row
+ \o \bold \\bold \target bold
+ \o \bold {The \\bold command renders its argument using
+ a bold font.}
+
+ For example:
+
+ \code
+ / *!
+ This is regular text; \bold {this text is
+ rendered using the \\bold command}.
+ * /
+ \endcode
+
+ will be rendered as
+
+ \quotation
+ This is regular text; \bold {this text is rendered using
+ the \\bold command}.
+ \endquotation
+
+ The command follows the same conventions as the \l {i}{\\i}
+ command for \l {argument}{punctuation, parentheses and use
+ of braces} for the argument.
+
+ \row
+ \o \bold \\i \target i
+ \o \bold {The \\i command renders its argument in italic.}
+
+ \warning This is preliminary functionality. For
+ more information, see the \l
+ {26-qdoc-commands-compatibility.html#i-versus-e}{compatibility}
+ section.
+
+ \target argument
+ Normally, a command argument ends at the next whitespace [1],
+ but braces can be used to group words [2]. For example:
+
+ \code
+ / *!
+ Here, we render \i {a few words} in italic.
+ * /
+ \endcode
+
+ will be rendered as
+
+ \quotation
+ Here, we render \i {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
+
+ will be rendered as
+
+ \quotation
+ An argument can sometimes contain whitespaces,
+ for example: \i 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 \i 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
+ \i {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
+ \i (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 \i clicked().</td>
+ <td>A push button emits the signal <i>clicked</i>().</td>
+ </tr>
+
+ <tr valign="top" bgcolor="#d0d0d0">
+ <td>5</td>
+ <td>The \i 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
+
+ \row
+ \o \bold \\sub \target sub
+ \o \bold {The \\sub command renders its argument lower
+ than the baseline of the regular text, using a smaller font.}
+
+ For example:
+
+ \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
+
+ will be rendered 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
+
+ The \\sub command follows the same conventions as the \l
+ {i}{\\i} command for \l {argument}{punctuation, parentheses
+ and use of braces} for the argument.
+
+ \row
+ \o \bold \\sup \target sup
+ \o \bold {The \\sup command renders its argument higher than
+ the baseline of the regular text, using a smaller font.}
+
+ For example:
+
+ \code
+ / *!
+ The series
+
+ 1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ...
+
+ is called the \i {geometric series}.
+ * /
+ \endcode
+
+ will be rendered as
+
+ \quotation
+ The series
+
+ 1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ...
+
+ is called the \i {geometric series}.
+ \endquotation
+
+ The \\sup command follows the same conventions as the \l
+ {i}{\\i} command for \l {argument}{punctuation, parentheses
+ and use of braces} for the argument.
+
+ \row
+ \o \bold \\underline \target underline
+ \o \bold {The \\underline command renders its argument underlined.}
+
+ For example:
+
+ \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
+
+ will be rendered 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
+
+ The \\underline command follows the same conventions as the
+ \l {i}{\\i} command for \l {argument}{punctuation,
+ parentheses and use of braces} for the argument. \endtable
+*/
+
+/*!
+ \page 05-qdoc-commands-documentstructuring.html
+ \previouspage Text Formatting Commands
+ \contentspage QDoc Manual - Table of Contents
+ \nextpage Verbatim Code Commands
+
+ \title Document Structuring Commands
+
+ The document structuring commands divide the documentation into
+ sections. 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.
+
+ \section1 Alphabetical List
+
+ \l {05-qdoc-commands-documentstructuring.html#chapter}{\\chapter},
+ \l {05-qdoc-commands-documentstructuring.html#part}{\\part},
+ \l {05-qdoc-commands-documentstructuring.html#sectionOne}{\\section1},
+ \l {05-qdoc-commands-documentstructuring.html#sectionTwo}{\\section2},
+ \l {05-qdoc-commands-documentstructuring.html#sectionThree}{\\section3},
+ \l {05-qdoc-commands-documentstructuring.html#sectionFour}{\\section4}
+
+ \section1 Command Descriptions
+
+ \table
+ \header
+ \o Command
+ \o Description
+
+ \row
+ \o \bold \\part \target part
+ \o \bold {The \\part command is intended for use in
+ larger documents, and divides the document into parts.}
+
+ 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 \i begin with either of the three: \c part, \c
+ chapter or \c section1. For example:
+
+
+ \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
+
+ will be rendered 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 level is a logical unit within the
+ document. Its title will appear on the table of contents
+ generated by the \l
+ {11-qdoc-commands-documentcontents.html#tableofcontents}
+ {\\tableofcontents} command. For example:
+
+ \code
+ / *!
+ Contents:
+
+ \tableofcontents
+
+ ...
+ * /
+ \endcode
+
+ will expand to
+
+ \quotation
+ \raw HTML
+ <p>Contents:</p>
+
+ <ul>
+ <li><a href="#Basic Qt">Basic Qt</a></li>
+ <ul>
+ <li><a href="#Getting Started">Getting Started</a></li>
+ <ul>
+ <li><a href="#Hello Qt">Hello Qt</a></li>
+ <li><a href="#Making Connections">
+ Making Connections</a></li>
+ <li><a href="#Using the Reference Documentation">
+ Using the Reference Documentation</a></li>
+ </ul>
+ <li><a href="#Creating Dialogs">Creating Dialogs</a></li>
+ <ul>
+ <li><a href="#Subclassing QDialog">
+ Subclassing QDialog</a></li>
+ </ul>
+ </ul>
+ <li><a href="#Intermediate Qt">Intermediate Qt</a></li>
+ <ul>
+ <li><a href="#Layout Management">
+ Layout Management</a></li>
+ <ul>
+ <li><a href="#Basic Layouts">Basic Layouts</a></li>
+ </ul>
+ </ul>
+ </ul>
+
+ ...
+ \endraw
+ \endquotation
+
+ \row
+ \o \bold \\chapter \target chapter
+ \o \bold {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.
+
+ \row
+ \o \bold \\section1 \target sectionOne
+ \o \bold {The \\section1 command starts a new section.}
+
+ See \l{part}{\\part} for an explanation of the various
+ section units, command argument and rendering.
+ \row
+ \o \bold \\section2 \target sectionTwo
+ \o \bold {The \\section2 command starts a new section.}
+
+ See \l{part}{\\part} for an explanation of the various
+ section units, command argument and rendering.
+
+ \row
+ \o \bold \\section3 \target sectionThree
+ \o \bold {The \\section3 command starts a new section.}
+
+ See \l{part}{\\part} for an explanation of the various
+ section units, command argument and rendering.
+
+ \row
+ \o \bold \\section4 \target sectionFour
+ \o \bold {The \\section4 command starts a new section.}
+
+ See \l{part}{\\part} for an explanation of the various
+ section units, command argument and rendering.
+
+ \endtable
+*/
+
+/*!
+ \page 06-qdoc-commands-verbatimcode.html
+ \previouspage Document Structuring Commands
+ \contentspage QDoc Manual - Table of Contents
+ \nextpage Quoting External Code Commands
+
+ \title Verbatim Code Commands
+
+ The following commands are used to render verbatim code within the
+ documentation. The code is rendered on a new line, using a
+ typewriter font and the standard indentation.
+
+ \bold{Note:} Although all of these commands can be used to present
+ C++ code, the \l{07-0-qdoc-commands-quoting.html#snippet}{\\snippet}
+ and \l{07-0-qdoc-commands-quoting.html#codeline}{\\codeline} commands
+ should be used in preference to
+ the others when presenting valid code. This allows auxilliary tools
+ for Qt language bindings to substitute the relevant code snippets in
+ place of the C++ ones.
+
+ \section1 Alphabetical List
+
+ \l {06-qdoc-commands-verbatimcode.html#badcode}{\\badcode},
+ \l {06-qdoc-commands-verbatimcode.html#code}{\\code},
+ \l {06-qdoc-commands-verbatimcode.html#newcode}{\\newcode},
+ \l {06-qdoc-commands-verbatimcode.html#oldcode}{\\oldcode}
+
+ \section1 Command Descriptions
+
+ \table
+ \header
+ \o Command
+ \o Description
+
+ \row
+ \o \bold \\code \target code
+ \o \bold {The \\code command and the corresponding
+ \\endcode command delimit a piece of verbatim code.}
+
+ Whereas the \l {c}{\\c} command can be used for short code
+ fragments within a sentence, the \\code command is for
+ longer code snippets and renders the code verbatim in a
+ separate paragraph using a typewriter font and the standard
+ indentation.
+
+ When processing any of the \\code, \l {badcode}{\\badcode},
+ \l {newcode}{\\newcode} and \l {oldcode}{\\oldcode}
+ commands, QDoc basically 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 that this doesn't apply to externally
+ quoted code using the \l {quotefromfile}{\\quotefromfile}
+ or \l {quotefile}{\\quotefile} command).
+
+ For example:
+
+ \code
+ / *!
+ \code
+ #include <QApplication>
+ #include <QPushButton>
+
+ int main(int argc, char *argv[])
+ {
+ ...
+ }
+ \ endcode
+ * /
+ \endcode
+
+ will be rendered 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.
+
+ You need to type the code manually between the \\code and
+ \\endcode commands. If you want to include code snippets
+ from a particular file, use the \l
+ {07-0-qdoc-commands-quoting.html#quotefromfile}{\\quotefromfile}
+ command instead.
+
+ See also \l {c}{\\c}, \l
+ {07-0-qdoc-commands-quoting.html#quotefromfile}{\\quotefromfile},
+ \l {badcode}{\\badcode}, \l {newcode}{\\newcode} and \l
+ {oldcode}{\\oldcode}.
+
+ \row
+ \o \bold \\badcode \target badcode
+ \o \bold {The \\badcode command and the corresponding
+ \\endcode command delimit a piece of code that doesn't
+ compile or is wrong for some other reason.}
+
+ The \\badcode command is similar the \l {code}{\\code}
+ command, but renders the code using a grey font instead of
+ black (the default).
+
+ Like the \l {code}{\\code} command, it renders its code on
+ a new line in the documentation using a typewriter font and
+ the standard indentation. For example:
+
+ \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
+
+ will be rendered 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}{\\code}, \l {newcode}{\\newcode} and \l
+ {oldcode}{\\oldcode}.
+
+ \row
+ \o \bold \\newcode \target newcode
+ \o \bold {The \\newcode command, and the associated \\oldcode
+ and \\endcode commands, indicate how to port a piece 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}{\\code} and \l {badcode}{\\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}{\\code} and \l {badcode}{\\badcode}
+ commands, the \\newcode command renders its code on a new
+ line in the documentation using a typewriter font and the
+ standard indentation. For example:
+
+ \code
+ / *!
+ \oldcode
+ if (printer->setup(parent))
+ ...
+ \newcode
+ QPrintDialog dialog(printer, parent);
+ if (dialog.exec())
+ ...
+ \ endcode
+ * /
+ \endcode
+
+ is rendered like this:
+
+ \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.
+
+ \row
+ \o \bold \\oldcode \target oldcode
+ \o \bold {The \\oldcode command requires a corresponding
+ \\newcode statement; otherwise QDoc fails to parse the command
+ and emits a warning.}
+
+ See also \l {newcode}{\\newcode} and \l {badcode}{\\badcode}.
+ \endtable
+*/
+
+/*!
+ \page 07-0-qdoc-commands-quoting.html
+ \previouspage Verbatim Code Commands
+ \contentspage QDoc Manual - Table of Contents
+ \nextpage Linking Commands
+
+ \title Quoting External Code Commands
+
+ The following commands enable quoting from files in the
+ documentation: 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 of these commands can be used to present
+ C++ code, the \l{#snippet}{\\snippet} and \l{#codeline}{\\codeline}
+ commands should be used in preference to
+ the others when presenting valid code. This allows auxilliary tools
+ for Qt language bindings to substitute the relevant code snippets in
+ place of the C++ ones.
+
+ \section1 Alphabetical List
+
+ \l {07-0-qdoc-commands-quoting.html#codeline}{\\codeline},
+ \l {07-0-qdoc-commands-quoting.html#dots}{\\dots},
+ \l {07-0-qdoc-commands-quoting.html#printline}{\\printline},
+ \l {07-0-qdoc-commands-quoting.html#printto}{\\printto},
+ \l {07-0-qdoc-commands-quoting.html#printuntil}{\\printuntil},
+ \l {07-0-qdoc-commands-quoting.html#quotefile}{\\quotefile},
+ \l {07-0-qdoc-commands-quoting.html#quotefromfile}{\\quotefromfile},
+ \l {07-0-qdoc-commands-quoting.html#skipline}{\\skipline},
+ \l {07-0-qdoc-commands-quoting.html#skipto}{\\skipto},
+ \l {07-0-qdoc-commands-quoting.html#skipuntil}{\\skipuntil},
+ \l {07-0-qdoc-commands-quoting.html#snippet}{\\snippet}
+
+ \section1 Command Descriptions
+
+ \table
+ \header
+ \o Command
+ \o Description
+
+ \row
+ \o \bold \\quotefile \target quotefile
+ \o \bold {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.
+
+ For example:
+
+ \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
+
+ will be rendered 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
+
+ \warning If you use the \l {QDoc
+ Compatibility}{compat.qdocconf} file this command is called
+ \\include.
+
+ See also \l {quotefromfile}{\\quotefromfile} and \l
+ {code}{\\code}.
+
+ \row
+ \o \bold \\quotefromfile \target quotefromfile
+ \o \bold {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}{\\printline}, \l {printto}{\\printto}, \l
+ {printuntil}{\\printuntil}, \l {skipline}{\\skipline}, \l
+ {skipto}{\\skipto}, \l {skipuntil}{\\skipuntil}. This
+ enables you to quote specific portions of a file. For
+ example:
+
+ \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
+
+ will be rendered 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}{\\quotefile}, \l {code}{\\code} and
+ \l {dots}{\\dots}.
+
+ \row
+ \o \bold \\printline \target printline
+ \o \bold {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 always is 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.
+
+ For example:
+
+ \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
+
+ will be rendered as
+
+ \quotation
+ 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...
+ \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}{\\skip...} commands. To move the current
+ position backward, you can use the \l
+ {quotefromfile}{\\quotefromfile} command again.
+
+ \target substring
+
+ If the substring argument is surrounded by slashes it is
+ interpreted as a \l {regular expression}.
+
+ For example:
+
+ \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
+
+ will be rendered 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}{\\printto} and \l
+ {printuntil}{\\printuntil}.
+
+ \row
+ \o \bold \\printto \target printto
+ \o \bold {The \\printto command expands to all the lines
+ from the current position up to and \i 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}{\\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.
+
+ For example:
+
+ \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
+
+ will be rendered 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}{\\printline} and \l
+ {printuntil}{\\printuntil}.
+
+ \row
+ \o \bold \\printuntil \target printuntil
+ \o \bold {The \\printuntil command expands to all the lines
+ from the current position up to and \i 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}{\\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.
+
+ For example:
+
+ \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
+
+ will be rendered 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}{\\printline} and \l
+ {printto}{\\printto}.
+
+ \row
+ \o \bold \\skipline \target skipline
+ \o \bold {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}{\\printline}
+ command, and it is used in conjunction with the \l
+ {quotefromfile}{\\quotefromfile} command. For example:
+
+ \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
+
+ will be rendered as
+
+ \quotation
+ \l
+ 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.
+ \endquotation
+
+ (\l {Example File}{The complete example file...})
+
+ See also \l {skipto}{\\skipto}, \l
+ {skipuntil}{\\skipuntil} and \l {dots}{\\dots}.
+
+ \row
+ \o \bold \\skipto \target skipto
+ \o \bold {The \\skipto command ignores all the lines from the
+ current position up to and \i 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}{\\printline}
+ command, and it is used in conjunction with the \l
+ {quotefromfile}{\\quotefromfile} command. For example:
+
+ \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
+
+ will be rendered 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}{\\skipline}, \l
+ {skipuntil}{\\skipuntil} and \l {dots}{\\dots}.
+
+ \row
+ \o \bold \\skipuntil \target skipuntil
+ \o \bold {The \\skipuntil command ignores all the lines from
+ the current position up to and \i 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}{\\printline}
+ command, and it is used in conjunction with the \l
+ {quotefromfile}{\\quotefromfile} command. For example:
+
+ \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
+
+ will be rendered 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}{\\skipline}, \l {skipto}{\\skipto}
+ and \l {dots}{\\dots}.
+
+ \row
+ \o \bold \\dots \target dots
+ \o \bold {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}{\\quotefromfile} command, and should be
+ stated on its own line. The dots are rendered on a new
+ line, using a typewriter font. For example:
+
+ \code
+ / *!
+ \quotefromfile examples/main.cpp
+ \skipto main
+ \printuntil {
+ \dots
+ \skipuntil exec
+ \printline }
+ * /
+ \endcode
+
+ will be rendered 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. For
+ example:
+
+ \code
+ / *!
+ \dots 0
+ \dots
+ \dots 8
+ \dots 12
+ \dots 16
+ * /
+ \endcode
+
+ will be rendered as
+
+ \dots 0
+ \dots
+ \dots 8
+ \dots 12
+ \dots 16
+
+ See also \l {skipline}{\\skipline}, \l
+ {skipto}{\\skipto} and \l {skipuntil}{\\skipuntil}.
+
+ \row
+ \o \bold \\snippet \target snippet
+ \o \bold {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
+ \row
+ \o \bold \\codeline \target codeline
+ \o \bold{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.}
+ \endtable
+*/
+
+/*!
+ \page 07-1-example.html
+ \previouspage Quoting External Code Commands
+ \contentspage QDoc Manual - Table of Contents
+
+ \title Example File
+
+ \quotefile examples/main.cpp
+*/
+
+/*!
+ \page 08-qdoc-commands-linking.html
+ \previouspage Quoting External Code Commands
+ \contentspage QDoc Manual - Table of Contents
+ \nextpage Graphic Commands
+
+ \title Linking Commands
+
+ The linking commands make it possible to create hyperlinks to
+ classes, functions, header files and examples. They also make it
+ possible to link to targets within a document, as well as to other
+ documents and URLs.
+
+ \section1 Alphabetical List
+
+ \l {08-qdoc-commands-linking.html#keyword}{\\keyword},
+ \l {08-qdoc-commands-linking.html#l}{\\l},
+ \l {08-qdoc-commands-linking.html#sa}{\\sa},
+ \l {08-qdoc-commands-linking.html#target}{\\target}
+
+ \section1 Command Descriptions
+
+ \table
+ \header
+ \o Command
+ \o Description
+
+ \row
+ \o \bold \\l \target l
+ \o \bold {The \\l command is used to create hyperlinks. }
+
+ The command's general syntax is
+
+ \code
+ \l {link target}{link text}
+ \endcode
+
+ For example:
+
+ \code
+ / *!
+ Read the \l {http://qt.nokia.com/doc/4.0/}
+ {Qt's Reference Documentation} carefully.
+ * /
+ \endcode
+
+ will be rendered 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 rewrite it as
+
+ \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. See the \l {i}{\\i} command for the \l
+ {argument}{argument conventions}.
+
+ The \\l command supports several kinds of links:
+
+ \list
+ \o \c {\l QWidget} - a defined \l {class}{\\class}
+ \o \c {\l QWidget::sizeHint()} - a defined member
+ function (\l {fn}{\\fn})
+ \o \c {\l <QtGlobal>} - a defined \l {headerfile}{\\headerfile}
+ \o \c {\l widgets/wiggly} - a defined
+ \l {example-command}{\\example}
+ \o \c {\l {QWidget Class Reference}} - a defined \l {title}{\\title}
+ \o \c {\l {Introduction}}- a defined \l{part}{\\part},
+ \l{chapter}{\\chapter} or \l {sectionOne}{\\section...}
+ \o \c {\l fontmatching} - a defined \l {target}{\\target}
+ \o \c {\l {Shared Classes}} - a defined \l {keyword}{\\keyword}
+ \o \c {\l network.html} - a defined \l {page}{\\page}
+ \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
+
+ See also \l {sa}{\\sa}, \l {target}{\\target} and \l
+ {keyword}{\\keyword}.
+
+ \row
+ \o \bold \\sa \target sa
+ \o \bold {The \\sa command defines a list of links that will
+ be rendered in a separate "See also" section at the bottom
+ of the documentation.}
+
+ The command takes a comma-separated list of links as its
+ argument. If the line ends with a comma, you can continue
+ on a second 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, an 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}{\\l} command. For example:
+
+ \code
+ / *!
+ Appends the actions \a actions to this widget's
+ list of actions.
+
+ \sa removeAction(), QMenu, addAction()
+ * /
+ void QWidget::addActions(QList<QAction *> actions)
+ {
+ ...
+ }
+ \endcode
+
+ will be rendered as
+
+ \quotation
+ \bold {void QWidget::addActions ( QList<QAction*>
+ \i actions )}
+
+ Appends the actions \i 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}{\\l}, \l {target}{\\target} and \l
+ {keyword}{\\keyword}.
+
+ \row
+ \o \bold \\target \target target
+ \o \bold {The \\target command defines an explicit point in the
+ documentation that you can later link to using the \l {l}{\\l}
+ and \l {sa}{\\sa} commands.}
+
+ The command considers the rest of the line as part of its
+ argument, make sure to follow the target name with a line
+ break.
+
+ For example:
+
+ \code
+ / *!
+ \target capturing parentheses
+ \section1 Capturing Text
+
+ Parentheses allow us to group elements together so that
+ we can quantify and capture them.
+
+ ...
+ * /
+ \endcode
+
+ can be referenced with
+
+ \list
+ \o \c {\l {capturing parentheses}}
+ (from elsewhere in the same comment)
+ \o \c {\l qregexp.html#capturing-parentheses}
+ (from anywhere else)
+ \endlist
+
+ within a documentation unit, and with
+
+ \list
+ \o \c {\l http://www.trolltech.com/4.0/doc/html/qregexp.html#capturing-parentheses}
+ \endlist
+
+ on a more global scale.
+
+ If the target name does't contain any spaces, the brackets can
+ be omitted as well.
+
+ See also \l {l}{\\l}, \l {sa}{\\sa} and \l
+ {keyword}{\\keyword}.
+
+ \row
+ \o \bold \\keyword \target keyword
+ \o \bold {The \\keyword command defines an explicit point in the
+ documentation that you can later link to using the \l {l}{\\l}
+ and \l {sa}{\\sa} commands.}
+
+ Keywords must be unique within the entire set of
+ documentation processed in on QDoc run. The command
+ considers the rest of the line as part of its argument,
+ make sure to follow the keyword with a line break.
+
+ The \\keyword command is similar to \l {target}{\\target},
+ but stronger. A keyword can be referenced from anywhere
+ using a simple syntax. For example:
+
+ \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
+
+ can be referenced like this
+
+ \code
+ / *!
+ When a string is surrounded by slashes, it's
+ interpreted as a \l regular expression.
+ * /
+ \endcode
+
+ which will be rendered as
+
+ \quotation
+ When a string is surrounded by slashes, it's
+ interpreted as a \l {regular expression}.
+ \endquotation
+
+ If the keyword does't contain any spaces, the brackets can
+ be omitted as well.
+
+ See also \l {l}{\\l}, \l {sa}{\\sa} and \l
+ {target}{\\target}.
+ \endtable
+*/
+
+/*!
+ \page 09-qdoc-commands-graphic.html
+ \previouspage Linking Commands
+ \contentspage QDoc Manual - Table of Contents
+ \nextpage Container Commands
+
+ \title Graphic Commands
+
+ The graphic commands makes it possible to include images in the
+ documentation. The images can be rendered as separate paragraphs,
+ or within running text.
+
+ \section1 Alphabetical List
+
+ \l {09-qdoc-commands-graphic.html#caption}{\\caption},
+ \l {09-qdoc-commands-graphic.html#image}{\\image},
+ \l {09-qdoc-commands-graphic.html#inlineimage}{\\inlineimage}
+
+ \section1 Command Descriptions
+
+ \table
+ \header
+ \o Command
+ \o Description
+
+ \row
+ \o \bold \\image \target image
+ \o \bold {The \\image command expands to the image specified by its
+ 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 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 when a browser doesn't support images like
+ the Lynx text browser.
+
+ The command considers the rest of the line after the file
+ name its second argument, make sure that you follow the
+ filename or description with a line break. Braces are only
+ necessary if the description spans several lines.
+
+ For example:
+
+ \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
+
+ will be rendered 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}{\\inlineimage} and \l
+ {caption}{\\caption}.
+
+ \row
+ \o \bold \\inlineimage \target inlineimage
+ \o \bold {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 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 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. For example:
+
+ \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
+
+ will be rendered 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
+
+ And
+
+ \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
+
+ will be rendered 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 regular text. For example:
+
+ \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
+
+ will be rendered 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}{\\image} and \l {caption}{\\caption}.
+
+ \row
+ \o \bold \\caption \target caption
+ \o \bold {The \\caption command provides a caption for an image.}
+
+ The command follows the same conventions for parentheses and use
+ of braces for its \l argument as the \l {i}{\\i} command.
+
+ \warning This is preliminary functionality. The
+ command is not fully implemented.
+
+ See also \l {image}{\\image} and \l
+ {inlineimage}{\\inlineimage}
+
+ \endtable
+*/
+
+/*!
+ \page 10-qdoc-commands-container.html
+ \previouspage Graphic Commands
+ \contentspage QDoc Manual - Table of Contents
+ \nextpage Document Contents Commands
+
+ \title Container Commands
+
+ The container commands create tables and lists with associated
+ items and contents. A list is rendered left aligned as a separate
+ paragraph. A table is rendered centered as a separate paragraph,
+ and its width depends on its content.
+
+ \section1 Alphabetical List
+
+ \l {10-qdoc-commands-container.html#header}{\\header},
+ \l {10-qdoc-commands-container.html#list}{\\list},
+ \l {10-qdoc-commands-container.html#o}{\\o},
+ \l {10-qdoc-commands-container.html#omitvalue}{\\omitvalue},
+ \l {10-qdoc-commands-container.html#row}{\\row},
+ \l {10-qdoc-commands-container.html#table}{\\table},
+ \l {10-qdoc-commands-container.html#value}{\\value}
+
+ \section1 Command Descriptions
+
+ \table
+ \header
+ \o Command
+ \o Description
+
+ \row
+ \o \bold \\table \target table
+ \o \bold {The \\table command and the corresponding \\endtable
+ command delimit the contents of a table.}
+
+ The command accepts a single argument specifying the
+ table's width in percentage:
+
+ \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}{\\row} command and consists of cells, which
+ starts with a \l {o}{\\o} command. There is also a \l
+ {header}{\\header} command which is a special kind of row
+ with a special formatting. For example:
+
+ \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
+
+ will be rendered 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
+
+ will be rendered 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}{\\header}, \l {row}{\\row} and \l {o}{\\o}.
+
+ \row
+ \o \bold \\header \target header
+ \o \bold {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}
+ {\\table...\\endtable} commands. A header can contain
+ several cells. A cell is created with the \l {o}{\\o}
+ command.
+
+ A header cell's text is centered within the table cell and
+ rendered using a bold font. For example:
+
+ \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
+
+ will be rendered 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}{\\table}, \l {row}{\\row} and \l {o}{\\o}.
+
+ \row
+ \o \bold \\row \target row
+ \o \bold {The \\row command indicates that the following table
+ cells belong to the same row in the current table.}
+
+ The command can only be used within the \l{table}
+ {\\table...\\endtable} commands. A row can contain
+ several cells. A cell is created with the \l {o}{\\o}
+ command.
+
+ The background cell color of each row alternate between two
+ shades of grey, making it easier to distinguish the rows
+ from each other. The cells' contents is left aligned.
+
+ For example:
+
+ \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
+
+ will be rendered 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}{\\table}, \l {header}{\\header} and \l
+ {o}{\\o}.
+
+ \row
+ \o \bold \\value \target value
+ \o \bold {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}{\\enum} documentation for an example.
+
+ See also \l {enum}{\\enum} and \l {omitvalue}{\\omitvalue}.
+
+ \row
+ \o \bold \\omitvalue \target omitvalue
+ \o \bold {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}{\\enum}
+ documentation for an example.
+
+ See also \l {enum}{\\enum} and \l {value}{\\value}.
+
+ \row
+ \o \bold \\list \target list
+ \o \bold {The \\list command and the corresponding \\endlist
+ command delimit a list of items.}
+
+ You need to create each list item explicitly using the \l
+ {o}{\\o} command. A list can contain one or more items; it
+ can also 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
+
+ will be rendered 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. For example:
+
+ \code
+ / *!
+ \list
+ \o How to Learn Qt
+ \o Installation
+ \o Tutorial and Examples
+ \endlist
+ * /
+ \endcode
+
+ will render the list items with bullets (the default):
+
+ \list
+ \o How to Learn Qt
+ \o Installation
+ \o Tutorial and Examples
+ \endlist
+
+ If you provide 'A' as an argument to the \\list command,
+ the bullets are replaced with characters following 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 rendered
+ with numbers following 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 default bullets are
+ replaced with roman numerals:
+
+ \list i
+ \o How to Learn Qt
+ \o Installation
+ \o Tutorial and Examples
+ \endlist
+
+ Or 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
+
+ will be rendered as
+
+ \list G
+ \o How to Learn Qt
+ \o Installation
+ \o Tutorial and Examples
+ \endlist
+
+ See also \l {o}{\\o}.
+
+ \row
+ \o \bold \\o \target o
+ \o \bold {The \\o command announce a table or list item.}
+
+ Earlier we used the \l {i}{\\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}
+ {\\table...\\endtable} or \l{list}{\\list... \\endlist}
+ commands.
+
+ It considers everything until the next occurrence
+ of the \\o command, or the currently applicable \l
+ {table}{\\endtable} or \l {list}{\\endlist} command, as its
+ argument. For examples, see \l {table}{\\table} and \l
+ {list}{\\list}.
+
+ If the command is used within a table, you can in addition
+ specify how many rows or columns the item should span. For
+ example:
+
+ \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
+
+ will be rendered 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}{\\table}, \l {header}{\\header},
+ \l {list}{\\list} and \l {o}{\\o}.
+ \endtable
+*/
+
+/*!
+ \page 11-qdoc-commands-documentcontents.html
+ \previouspage Container Commands
+ \contentspage QDoc Manual - Table of Contents
+ \nextpage Miscellaneous Commands
+
+ \title Document Contents Commands
+
+ The document contents commands identify parts of the documentation,
+ i.e. parts with a special rendering, conceptual meaning or
+ function.
+
+ \section1 Alphabetical List
+
+ \l {11-qdoc-commands-documentcontents.html#abstract}{\\abstract},
+ \l {11-qdoc-commands-documentcontents.html#brief}{\\brief},
+ \l {11-qdoc-commands-documentcontents.html#footnote}{\\footnote},
+ \l {11-qdoc-commands-documentcontents.html#legalese}{\\legalese},
+ \l {11-qdoc-commands-documentcontents.html#tableofcontents}
+ {\\tableofcontents},
+ \l {11-qdoc-commands-documentcontents.html#quotation}{\\quotation},
+ \l {11-qdoc-commands-documentcontents.html#warning}{\\warning}
+
+ \section1 Command Descriptions
+
+ \table
+ \header
+ \o Command
+ \o Description
+
+ \row
+ \o \bold \\abstract \target abstract
+ \o \bold {The \\abstract command and the corresponding \\endabstract
+ command delimit a document's abstract section.}
+
+ The abstract section is rendered as an indented italicized
+ paragraph.
+
+ \warning This is preliminary funcionality. The
+ command is not fully implemented. Currently, the abstract
+ section is rendered as a regular HTML paragraph. For
+ example:
+
+ \code
+ / *!
+ \abstract
+ 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. It is also available for embedded
+ devices.
+ \endabstract
+ * /
+ \endcode
+
+ will be rendered as
+
+ \abstract
+ 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. It is also
+ available for embedded devices.
+ \endabstract
+
+ \row
+ \o \bold \\quotation \target quotation
+ \o \bold { The \\quotation command and the corresponding
+ \\endquotation command delimit a quotation remark.}
+
+ This command replaces the old \\quote command. For more
+ information see the \l
+ {26-qdoc-commands-compatibility.html#quotation-versus-quote}
+ {compatibility} section.
+
+ The remark is rendered as a separate centered
+ paragraph. For example:
+
+ \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
+
+ will be rendered as
+
+ 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
+
+ \row
+ \o \bold \\footnote \target footnote
+ \o \bold {The \\footnote command and the corresponding
+ \\endfootnote command delimit a footnote.}
+
+ The footnote follows the standard conventions, rendered at the
+ bottom of the page.
+
+ \warning This is preliminary funcionality. The
+ command is not fully implemented.
+
+ For example:
+
+ \code
+ / *!
+ In Qt 4 we have tried to simplify the constructors of
+ QObject/QWidget subclasses. This makes subclassing
+ easier, at the same time as it helps make the Qt
+ library more efficient.
+
+ \footnote
+ Constructors no longer take a "const char *name"
+ parameter. If you want to specify a name for a QObject,
+ you must call QObject::setObjectName() after
+ construction. The object name is now a QString.
+ \endfootnote
+
+ QWidget's WFlags data type has been split in two:
+ Qt::WindowFlags specifies low-level window flags (the
+ type of window and the frame style), whereas
+ Qt::WidgetAttribute specifies various higher-level
+ attributes about the widget (e.g.,
+ WA_StaticContents).
+ * /
+ \endcode
+
+ will be rendered as
+
+ \quotation
+ In Qt 4 we have tried to simplify the constructors of
+ QObject/QWidget subclasses. This makes subclassing
+ easier, at the same time as it helps make the Qt
+ library more efficient.
+
+ \footnote
+ Constructors no longer take a "const char *name"
+ parameter. If you want to specify a name for a QObject,
+ you must call QObject::setObjectName() after
+ construction. The object name is now a QString.
+ \endfootnote
+
+ QWidget's WFlags data type has been split in two:
+ Qt::WindowFlags specifies low-level window flags (the
+ type of window and the frame style), whereas
+ Qt::WidgetAttribute specifies various higher-level
+ attributes about the widget (e.g.,
+ WA_StaticContents).
+ \endquotation
+
+ \row
+ \o \bold \\tableofcontents \target tableofcontents
+ \o \bold {The \\tableofcontents command generates a
+ table displaying the titles of the current documentation
+ unit's parts, chapters, sections, etc.}
+
+ The command accepts a single optional argument:
+
+ \code
+ \tableofcontents sectionN
+ \endcode
+
+ where \c sectionN is the deepest section to include (by
+ default all sections are included).
+
+ For example, it the documentation unit's structure looks
+ something like this:
+
+ \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
+
+ Then
+
+ \code
+ / *!
+ Contents:
+
+ \tableofcontents
+
+ ...
+ * /
+ \endcode
+
+ will expand to
+
+ \quotation
+ \raw HTML
+ <p>Contents:</p>
+
+ <ul>
+ <li><a href="#Basic Qt">Basic Qt</a></li>
+ <ul>
+ <li><a href="#Getting Started">Getting Started</a></li>
+ <ul>
+ <li><a href="#Hello Qt">Hello Qt</a></li>
+ <li><a href="#Making Connections">
+ Making Connections</a></li>
+ <li><a href="#Using the Reference Documentation">
+ Using the Reference Documentation</a></li>
+ </ul>
+ <li><a href="#Creating Dialogs">Creating Dialogs</a></li>
+ <ul>
+ <li><a href="#Subclassing QDialog">
+ Subclassing QDialog</a></li>
+ </ul>
+ </ul>
+ <li><a href="#Intermediate Qt">Intermediate Qt</a></li>
+ <ul>
+ <li><a href="#Layout Management">Layout Management</a></li>
+ <ul>
+ <li><a href="#Basic Layouts">Basic Layouts</a></li>
+ </ul>
+ </ul>
+ </ul>
+
+ ...
+ \endraw
+ \endquotation
+
+ Each table entry becomes a link to the corresponding part,
+ chapter or section.
+
+ \row
+ \o \bold \\brief \target brief
+ \o \bold {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}{\\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 only be a sentence fragment
+ and start with "whether" (for boolean properties and
+ variables) or "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
+
+ The latter will be rendered 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
+
+ and likewise when the command is used for namespaces or
+ header files.
+
+ \warning The brief statement is used as the first
+ paragraph of the detailed description. Do not repeat the
+ sentence.
+
+ For 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.
+
+ 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
+
+ will be rendered 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 \i 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 with a namespace can for example look like this:
+
+ \code
+ / *!
+ \namespace Qt
+
+ \brief The Qt namespace contains miscellaneous identifiers
+ used throughout the Qt library.
+ * /
+ \endcode
+
+ and finally using \\brief with a header file can look
+ something like this:
+
+ \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}{\\property}, \l{class}{\\class},
+ \l{namespace}{\\namespace} and \l{headerfile}{\\headerfile}.
+
+ \row
+ \o \bold \\legalese \target legalese
+ \o \bold {The \\legalese command, and the corresponding \\endlegalese
+ command, delimit a licence agreement.}
+
+ If the \\endlegalese command is omitted, QDoc will still
+ process the \\legalese command but considers the rest of
+ the documentation page as the license agreement.
+
+ Ideally, the license documentation is located where the
+ licensed code is used.
+
+ Later the documentation identified by the \\legalese
+ command can be accumulated into a list using the \l
+ {generatelist}{\\generatelist} command with the \c legalese
+ argument. This is useful to generate an overview of all the
+ licenses associated with the source code.
+
+ For example:
+
+ \code
+ \ * !
+ ...
+
+ On X11, Qt also supports drops via the Motif Drag \&
+ Drop Protocol. The implementation incorporates some
+ code that was originally written by Daniel Dardailler,
+ and adapted for Qt by Matt Koss \<koss@napri.sk\> and
+ Trolltech. Here is the original copyright notice:
+
+ \legalese
+ \code
+
+ 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.
+
+ \ endcode
+ \endlegalese
+ * /
+ \endcode
+
+ will be rendered as
+
+ \quotation
+ ...
+
+ On X11, Qt also supports drops via the Motif Drag \&
+ Drop Protocol. The implementation incorporates some
+ code that was originally written by Daniel Dardailler,
+ and adapted for Qt by Matt Koss \<koss@napri.sk\> and
+ Trolltech. Here is the original copyright notice:
+
+ \legalese
+ \code
+
+ 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.
+
+ \endcode
+ \endlegalese
+ \endquotation
+
+ \row
+ \o \bold \\warning \target warning
+ \o \bold {The \\warning command renders a "Warning:" prefix to
+ the command's argument.}
+
+ For example:
+
+ \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
+
+ will be rendered 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
+ \endtable
+*/
+
+/*!
+ \page 12-0-qdoc-commands-miscellaneous.html
+ \previouspage Document Contents Commands
+ \contentspage QDoc Manual - Table of Contents
+ \nextpage Topical Commands
+
+ \title Miscellaneous Commands
+
+ These commands provide miscellaneous functions
+ connected to the visual appearance of the documentation, and to the
+ process of generating the documentation.
+
+ \section1 Alphabetical List
+
+ \l {12-0-qdoc-commands-miscellaneous.html#else}{\\else},
+ \l {12-0-qdoc-commands-miscellaneous.html#endif}{\\endif},
+ \l {12-0-qdoc-commands-miscellaneous.html#expire}{\\expire},
+ \l {12-0-qdoc-commands-miscellaneous.html#generatelist}{\\generatelist},
+ \l {12-0-qdoc-commands-miscellaneous.html#if}{\\if},
+ \l {12-0-qdoc-commands-miscellaneous.html#include}{\\include},
+ \l {12-0-qdoc-commands-miscellaneous.html#meta}{\\meta},
+ \l {12-0-qdoc-commands-miscellaneous.html#omit}{\\omit},
+ \l {12-0-qdoc-commands-miscellaneous.html#raw}{\\raw},
+ \l {12-0-qdoc-commands-miscellaneous.html#raw}{\\unicode}
+
+ \section1 Command Descriptions
+
+ \table
+ \header
+ \o Command
+ \o Description
+
+ \row
+ \o \bold \\expire \target expire
+ \o \bold {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
+
+ \row
+ \o \bold \\generatelist \target generatelist
+ \o \bold {The \\generatelist command expands to a list of
+ various documentation or links to documentation.}
+
+ For example in the Qt Reference Documentation:
+
+ \code
+ / *!
+ \page classes.html
+ \title All Qt Classes (main index)
+
+ 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
+
+ is used to generate \l {All Qt Classes (main index)}.
+
+ The command accepts the following arguments:
+
+ \target table example
+
+ \list
+ \o \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:
+
+ \quotation
+ \raw HTML
+ <table align="center" cellpadding="2"
+ cellspacing="1" border="0">
+
+ <tr valign="top" bgcolor="#d0d0d0">
+ <td>
+ <a href="http://qt.nokia.com/doc/4.0/qdial.html">
+ QDial</a>
+ </td>
+ <td>Rounded range control (like a speedometer
+ or potentiometer)</td>
+ </tr>
+
+ <tr valign="top" bgcolor="#d0d0d0">
+ <td>
+ <a href="http://qt.nokia.com/doc/4.0/qdialog.html">
+ QDialog</a>
+ </td>
+ <td>The base class of dialog windows</td>
+ </tr>
+
+ <tr valign="top" bgcolor="#d0d0d0">
+ <td>
+ <a href="http://qt.nokia.com/doc/4.0/qdir.html">
+ QDir</a>
+ </td>
+ <td>Access to directory structures and their
+ contents</td>
+ </tr>
+ </table>
+ \endraw
+ \endquotation
+
+ A class is identified within the documentation by the
+ the \l {class}{\\class} command, and the descriptions
+ are based on the argument of the \l {brief}{\\brief}
+ commands in the class documentation.
+
+ \target list example
+
+ \o \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.
+
+ For example:
+
+ \quotation
+ \raw HTML
+ <p><table width="100%">
+
+ <tr>
+ <td align="right"><b>A&nbsp;</b></td>
+ <td><a href="http://qt.nokia.com/doc/4.0/qabstractbutton.html">QAbstractButton</a></td>
+
+ <td align="right"></td>
+ <td><a href="http://qt.nokia.com/doc/4.0/qabstractextensionmanager.html">QAbstractExtensionManager</a></td>
+
+ <td align="right"></td>
+ <td><a href="http://qt.nokia.com/doc/4.0/qabstractitemmodel.html">QAbstractItemModel</a></td>
+ </tr>
+
+ <tr>
+ <td align="right"></td>
+ <td><a href="http://qt.nokia.com/doc/4.0/qabstracteventdispatcher.html">QAbstractEventDispatcher</a></td>
+
+ <td align="right"></td>
+ <td><a href="http://qt.nokia.com/doc/4.0/qabstractformbuilder.html">QAbstractFormBuilder</a></td>
+
+ <td align="right"></td>
+ <td><a href="http://qt.nokia.com/doc/4.0/qabstractitemview.html">QAbstractItemView</a></td>
+ </tr>
+
+ <tr>
+ <td align="right"></td>
+ <td><a href="http://qt.nokia.com/doc/4.0/qabstractextensionfactory.html">QAbstractExtensionFactory</a></td>
+
+ <td align="right"></td>
+ <td><a href="http://qt.nokia.com/doc/4.0/qabstractitemdelegate.html">QAbstractItemDelegate</a></td>
+
+ <td align="right"></td>
+ <td><a href="http://qt.nokia.com/doc/4.0/qabstractlistmodel.html">QAbstractListModel</a></td>
+ </tr>
+ </table></p>
+ \endraw
+ \endquotation
+
+ A class is identified within the documentation by the
+ the \l {class}{\\class} command.
+
+ \o \c classesbymodule
+
+ This particular argument requests an additional argument,
+ i.e. a specification of the module.
+
+ For example:
+
+ \code
+ / *!
+ \page qtgui.html
+ \contentspage Qt Classes by Module
+ \previouspage QtCore Classes
+ \nextpage QtNetwork Classes
+
+ \title QtGui Classes
+
+ \keyword QtGui
+
+ \generatelist {classesbymodule QtGui}
+ * /
+ \endcode
+
+ Together, these arguments provide a table containing the
+ classes considered members of the specified module,
+ accompanied with a brief description. Each class name is
+ a link to the class's reference documentation.
+
+ The generated table is rendered similarily to the one
+ generated when using the \l {table example}{\c
+ annotatedclasses} 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
+ is related to a module with the \l
+ {inmodule}{\\inmodule} command.
+
+ \o \c classesbyedition
+
+ This particular argument requests an additional argument,
+ i.e. a specification of the edition.
+
+ For example:
+
+ \code
+ / *!
+ \page console-edition-classes.html
+ \title Qt Console Edition Classes
+
+ \generatelist{classesbyedition Console}
+ * /
+ \endcode
+
+ Together, these arguments provide a table containing the
+ classes considered members of the specified edition,
+ accompanied with a brief description. Each class name is
+ a link to the class's reference documentation.
+
+ The edition a given class can be found in is determined by
+ the module it belongs to.
+
+ \o \c compatclasses
+
+ The \c compatclasses argument provides a complete and
+ alphabetical list of the support classes. A support
+ class is identified within the documentation by the \l
+ {compat}{\\compat} command. Each class name is a link to
+ the class's reference documentation. The list is
+ rendered similarily to the list generated by the \l
+ {list example}{\c classes} argument.
+
+ \warning The \c classesbymodule argument will at some
+ point replace the this argument.
+
+ \o \c functionindex
+
+ The \c functionindex argument provides a complete
+ alphabetical list of all the documented member
+ functions.
+
+ For example:
+
+ \quotation
+ \raw HTML
+ <p><center><font size="+1"><b><a href="#a">A</a>&nbsp;<a href="#b">B</a>&nbsp;<a href="#c">C</a>&nbsp;<a href="#d">D</a>&nbsp;<a href="#e">E</a>&nbsp;<a href="#f">F</a>&nbsp;<a href="#g">G</a>&nbsp;<a href="#h">H</a>&nbsp;<a href="#i">I</a>&nbsp;<a href="#j">J</a>&nbsp;<a href="#k">K</a>&nbsp;<a href="#l">L</a>&nbsp;<a href="#m">M</a>&nbsp;<a href="#n">N</a>&nbsp;<a href="#o">O</a>&nbsp;<a href="#p">P</a>&nbsp;<a href="#q">Q</a>&nbsp;<a href="#r">R</a>&nbsp;<a href="#s">S</a>&nbsp;<a href="#t">T</a>&nbsp;<a href="#u">U</a>&nbsp;<a href="#v">V</a>&nbsp;<a href="#w">W</a>&nbsp;<a href="#x">X</a>&nbsp;<a href="#y">Y</a>&nbsp;<a href="#z">Z</a>&nbsp;</b></font></center></p>
+
+ <p>DTDHandler: <a href="http://qt.nokia.com/doc/4.0/qxmlreader.html#DTDHandler">QXmlReader</a></p>
+
+ <p>QAXCLASS: <a href="http://qt.nokia.com/doc/4.0/qaxfactory.html#QAXCLASS">global</a></p>
+
+ <p>QAXFACTORY_BEGIN: <a href="http://qt.nokia.com/doc/4.0/qaxfactory.html#QAXFACTORY_BEGIN">global</a></p>
+
+ <p>QAXFACTORY_DEFAULT: <a href="http://qt.nokia.com/doc/4.0/qaxfactory.html#QAXFACTORY_DEFAULT">global</a></p>
+
+ <p>QAXFACTORY_END: <a href="http://qt.nokia.com/doc/4.0/qaxfactory.html#QAXFACTORY_END">global</a></p>
+
+ \endraw
+
+ ...
+ \endquotation
+
+ \o \c legalese
+
+ The \c legalese argument provides a complete list of all
+ the licenses. The licenses are identified within the
+ documentation using the \l {legalese}{\\legalese}
+ command.
+
+ For example:
+
+ \quotation
+ \raw HTML
+ <hr />
+ <p>
+ Copyright (c) 1989 The Regents of the
+ University of California. All rights reserved.
+ </p>
+
+ <p>
+ Redistribution and use in source and binary
+ forms are permitted provided that the above
+ copyright notice and this paragraph are
+ duplicated in all such forms and that any
+ documentation, advertising materials, and other
+ materials related to such distribution and use
+ acknowledge that the software was developed by
+ the University of California, Berkeley...
+ </p>
+
+ <ul>
+ <li>
+ <a href="http://qt.nokia.com/doc/4.0/qdate.html#weekNumber">QDate::weekNumber()</a>
+ </li>
+ </ul>
+
+ <hr />
+ <p>
+ Copyright (c) 1991 by AT&amp;T.
+ </p>
+
+ <p>
+ Permission to use, copy, modify, and distribute
+ this software for any purpose without fee is
+ hereby granted, provided that this entire notice
+ is included in all copies of any software which
+ is or includes a copy or modification of this
+ software and in all copies of the supporting
+ documentation for such software...
+ </p>
+
+ <ul>
+ <li>
+ <a href="http://qt.nokia.com/doc/4.0/qlocale.html">QLocale</a>
+ </li>
+ </ul>
+ <hr />
+ \endraw
+ ...
+ \endquotation
+
+ \o \c mainclasses
+
+ The \c mainclasses argument provides a complete
+ alphabetical list of the main classes. Each class name
+ is a link to the class's reference documentation. A
+ class is related to the group of main classes by using
+ the \l {mainclass}{\\mainclass} command.
+
+ The list is rendered similarily to the list generated by
+ the \l {list example}{\c classes} argument.
+
+ \o \c overviews
+
+ The \c overviews argument provides a complete
+ alphabetical overview of the documentation. Each list
+ entry is a link to the respective documentation page.
+
+ The list includes pages declared using commands like \l
+ {page}{\\page} and \l {group}{\\group}. The list omits
+ examples and classes, and only lists the first page of
+ documentation that contains two or more pages using
+ commands like \l {nextpage}{\\nextpage}.
+
+ For example:
+
+ \quotation
+ \raw HTML
+ <ul>
+
+ <li>
+ <a href="http://qt.nokia.com/doc/4.0/qtalgorithms.html">
+ &lt;QtAlgorithms&gt; - Generic Algorithms
+ </a>
+ </li>
+
+ <li>
+ <a href="http://qt.nokia.com/doc/4.0/qtglobal.html">
+ &lt;QtGlobal&gt; - Global Qt Declarations
+ </a>
+ </li>
+
+ <li>
+ <a href="http://qt.nokia.com/doc/4.0/qaxserver-demo-simple.html">
+ A standard ActiveX and the &quot;simple&quot; ActiveQt widget
+ </a>
+ </li>
+
+ <li>
+ <a href="http://qt.nokia.com/doc/4.0/aboutqt.html">
+ About Qt
+ </a>
+ </li>
+
+ <li>
+ <a href="http://qt.nokia.com/doc/4.0/trolltech.html">
+ About Trolltech
+ </a>
+ </li>
+
+ <li>
+ <a href="http://qt.nokia.com/doc/4.0/abstractwidgets.html">
+ Abstract Widget Classes
+ </a>
+ </li>
+
+ <li>
+ <a href="http://qt.nokia.com/doc/4.0/accessibility.html">
+ Accessibility Classes
+ </a>
+ </li>
+ ...
+ </ul>
+ \endraw
+ \endquotation
+
+ \o \c related
+
+ The \c related argument is used in combination with the
+ \l {group}{\\group} command to list all the overviews
+ related to the given group. Each list entry is a link to
+ the respective documentation page.
+
+ \o \c relatedinline
+
+ The \c related argument is used in combination with the
+ \l {group}{\\group} command to collect all documentation
+ related to the given group. The various documentation
+ snippets are copied directly into the group page.
+
+ \o \c service
+
+ The \c service argument provides a complete alphabetical
+ list of the services. Each service name is a link to the
+ service's reference documentation.
+
+ A service is identified within the documentation by the
+ \l {service}{\\service} command.
+
+ \endlist
+
+
+ \row
+ \o \bold \\if \target if
+ \o \bold {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. For example:
+
+ \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 {definesvariable}{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 {definesvariable}{defines} variable.
+
+ See also \l{endif}{\\endif}, \l{else}{\\else}, \l
+ {definesvariable}{defines} and \l falsehoods.
+
+ \row
+ \o \bold \\endif \target endif
+ \o \bold {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}{\\if} command's
+ argument is true.}
+
+ For more information, see the documentation of the \l
+ {if}{\\if} command.
+
+ See also \l{if}{\\if}, \l{else}{\\else}, \l
+ {definesvariable}{defines} and \l falsehoods.
+
+ \row
+ \o \bold \\else \target else
+ \o \bold {The \\else command specifies an alternative if the
+ condition in the \l {if}{\\if} command is false.}
+
+ The \\else command can only be used within \l
+ {if}{\\if...\\endif} commands, but is useful when there is
+ only two alternatives. For example:
+
+ \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
+ as
+
+ \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 isn't defined but \c QT3_SUPPORT_WARNINGS
+ is, the comment will be rendered as
+
+ \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}{\\if}, \l{endif}{\\endif}, \l
+ {definesvariable}{defines} and \l falsehoods.
+
+ \row
+ \o \bold \\include \target include
+ \o \bold {The \\include command expands to the contents of the
+ file specified by the command's argument.}
+
+ \warning This is preliminary functionality. For more
+ information, see the \l
+ {26-qdoc-commands-compatibility.html#include-versus-input}
+ {compatibility} section.
+
+ The command takes a file name as an argument, and is
+ useful when some piece of the documentation is used
+ repeatedly: Move the repetetive text into a separate file,
+ and use the \\include command whenever you want to insert
+ the separate documentation.
+
+ The contents of such a file should follow QDoc syntax,
+ excluding the enclosing \c{/}\c{*!} ... \c{*}\c{/} marks.
+ To ensure that QDoc won't attempt to read the file as a
+ stand-alone piece of documentation, we recommend that you
+ use the \c .qdocinc extension.
+
+ For example:
+
+ \code
+ / *!
+ \page corefeatures.html
+ \title Core Features
+
+ \include examples/signalandslots.qdocinc
+ \include examples/objectmodel.qdocinc
+ \include examples/layoutmanagement.qdocinc
+ * /
+ \endcode
+
+ will be rendered as
+
+ \quotation
+ \raw HTML
+ <h1>Core Features</h1>
+ \endraw
+
+ \include examples/signalandslots.qdocinc
+ \include examples/objectmodel.qdocinc
+ \include examples/layoutmanagement.qdocinc
+ \endquotation
+
+ Here is the actual \c .qdocinc files: \l
+ signalandslots.qdocinc, \l objectmodel.qdocinc, \l
+ layoutmanagement.qdocinc
+
+ \row
+ \o \bold \\meta \target meta
+ \o \bold {The \\meta command is the QDoc equivalent to the HTML
+ \c meta tag.}
+
+ The command accepts two arguments: The first argument (the
+ following word) is equivalent to the HTML meta tag's \i
+ name variable, and the second argument (the rest of the
+ line) is equivalent to the tag's \i contents variable.
+
+ For example:
+
+ \code
+ / *!
+ \meta author Summerfield
+
+ \section1 Automatic Dialogs
+
+ \abstract
+ This article shows how to maintain sets of
+ "attributes" (QVariant values), and how to allow
+ users to view and edit them using dialogs that are
+ created dynamically based on the attributes and
+ their types.
+ \endabstract
+
+ The Attributes class described in this article holds a
+ set of QVariants, and can create a dialog to present
+ the QVariants to the user in an appropriate way.
+
+ ...
+ * /
+ \endcode
+
+ will be included in the generated HTML page as
+
+ \code
+ <head>
+ ...
+ <meta name="author" content="Summerfield" />
+ ...
+ </head>
+ \endcode
+
+ \row
+ \o \bold \\omit \target omit
+ \o \bold {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
+
+ will be rendered 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
+
+
+ \row
+ \o \bold \\raw \target raw
+ \o \bold {The \\raw command and the corresponding
+ \\endraw command delimit a block of raw mark-up language code.}
+
+ 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. For example:
+
+ \code
+ / *!
+ Qt has some predefined QColor objects. For example:
+
+ \raw HTML
+ <style type="text/css" id="colorstyles">
+ #blue { background-color: #0000ff; color: #ffffff }
+ #darkBlue { background-color: #000080; color: #ffffff }
+ #cyan { background-color: #00ffff; color: #000000 }
+ </style>
+
+ <p>
+ <tt id="blue">Blue(#0000ff)</tt>,
+ <tt id="darkBlue">dark blue(#000080)</tt> and
+ <tt id="cyan">cyan(#00ffff)</tt>.
+ \endraw
+ * /
+ \endcode
+
+ will be rendered as
+
+ \quotation
+ Qt has some predefined QColor objects. For example:
+
+ \raw HTML
+ <style type="text/css" id="colorstyles">
+ #blue { background-color: #0000ff; color: #ffffff }
+ #darkBlue { background-color: #000080; color: #ffffff }
+ #cyan { background-color: #00ffff; color: #000000 }
+ </style>
+
+ <p>
+ <tt id="blue">Blue(#0000ff)</tt>,
+ <tt id="darkBlue">dark blue(#000080)</tt> and
+ <tt id="cyan">cyan(#00ffff)</tt>.
+ \endraw
+ \endquotation
+
+ \row
+ \o \bold \\unicode \target unicode
+ \o \bold {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 \i{a}\sub{\i{i}}
+ \endcode
+
+ will be rendered as
+
+ \quotation
+ O G\unicode{0xEA}nio e as Rosas
+
+ \unicode 0xC0 table en famille avec 15 \unicode 0x20AC par jour
+
+ \unicode 0x3A3 \i{a}\sub{\i{i}}
+ \endquotation
+
+ The \\raw command follows the same conventions as the \l
+ {i}{\\i} command for \l {argument}{punctuation and use of
+ braces} for the argument.
+ \endtable
+*/
+
+/*!
+ \page 12-1-signalandslots.html
+ \previouspage Miscellaneous Commands
+ \contentspage QDoc Manual - Table of Contents
+
+ \title signalandslots.qdocinc
+
+ \quotefile examples/signalandslots.qdocinc
+*/
+
+/*!
+ \page 12-2-objectmodel.html
+ \previouspage Miscellaneous Commands
+ \contentspage QDoc Manual - Table of Contents
+
+ \title objectmodel.qdocinc
+
+ \quotefile examples/objectmodel.qdocinc
+*/
+
+/*!
+ \page 12-3-layoutmanagement.html
+ \previouspage Miscellaneous Commands
+ \contentspage QDoc Manual - Table of Contents
+
+ \title layoutmanagement.qdocinc
+
+ \quotefile examples/layoutmanagement.qdocinc
+*/
+
+/*!
+ \page 13-qdoc-commands-topical.html
+ \previouspage Miscellaneous Commands
+ \contentspage QDoc Manual - Table of Contents
+ \nextpage Contextual Commands
+
+ \title Topical Commands
+
+ The topical commands tell QDoc what is being documented
+ (i.e. existing units like classes, functions and examples), and
+ some of the commands allows you to create extra pages.
+
+ \section1 Alphabetical List
+
+ \l {13-qdoc-commands-topical.html#class}{\\class},
+ \l {13-qdoc-commands-topical.html#enum}{\\enum},
+ \l {13-qdoc-commands-topical.html#example-command}{\\example},
+ \l {13-qdoc-commands-topical.html#externalpage}{\\externalpage},
+ \l {13-qdoc-commands-topical.html#fn}{\\fn},
+ \l {13-qdoc-commands-topical.html#group}{\\group},
+ \l {13-qdoc-commands-topical.html#headerfile}{\\headerfile},
+ \l {13-qdoc-commands-topical.html#macro}{\\macro},
+ \l {13-qdoc-commands-topical.html#module}{\\module},
+ \l {13-qdoc-commands-topical.html#namespace}{\\namespace},
+ \l {13-qdoc-commands-topical.html#page}{\\page},
+ \l {13-qdoc-commands-topical.html#property}{\\property},
+ \l {13-qdoc-commands-topical.html#service}{\\service},
+ \l {13-qdoc-commands-topical.html#typedef}{\\typedef},
+ \l {13-qdoc-commands-topical.html#variable}{\\variable},
+
+ \section1 General Description
+
+ When QDoc is processing a comment, it will try to connect the
+ documentation to the source code. For that reason it will first
+ look for the topical commands. If there is no such command, it
+ will try to tie the documentation to the immediately following
+ code. If there is no topical command, and the documentation cannot
+ be tied to following code, the documentation is simply lost.
+
+ \target topical argument
+
+ The documented unit's name is passed as the unique argument for
+ all the topical commands. The argument's naming convention is the
+ documented unit's complete name. For example:
+
+ \code
+ \enum QComboBox::InsertPolicy
+ \endcode
+
+ Functions is a special case, the argument's naming convention for
+ the \l {fn}{\\fn} command is that of the function's definition
+ outside the class definition. For example:
+
+ \code
+ \fn void PreviewWindow::setWindowFlags()
+ \endcode
+
+ A topical command can appear anywhere in a comment, but must stand
+ alone on its own line. 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 topical command is repeated with different arguments, the
+ same documentation will appear for both the units. For example:
+
+ \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.
+
+ \section1 Command Descriptions
+
+ \table
+ \header
+ \o Command
+ \o Description
+
+ \row
+ \o \bold \\class \target class
+ \o \bold {The \\class command tells QDoc that a class is
+ part of the public API, and lets you enter a detailed
+ description.}
+
+ The command follows \l {topical argument}{the general
+ topical command convention} for the argument, and supports
+ nested classes, for example:
+
+ \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 generated HTML documentation for the specified class is
+ put in \c <lower-case>classname.html. For example, the
+ documentation for the \c PreviewWindow class is located in
+ \c previewwindow.html.
+
+ \target framework
+
+ In addition to render the detailed description, the \\class
+ comand will generate the documentation framework, i.e. a
+ list of the class's types, properties, functions, signals
+ and slots with empty documentation.
+
+ The command is typically accompanied with a \l
+ {brief}{\\brief} command, a \l {mainclass}{\\mainclass}
+ command, an \l {ingroup}{\\ingroup} command and a \l
+ {sa}{\\sa} command. For 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.
+
+ \mainclass
+ \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
+
+ will be rendered 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 \i 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
+
+ \row
+ \o \bold \\enum \target enum
+ \o \bold {The \\enum command allows you to document a C++ enum.}
+
+ The command follows \l {topical argument}{the general
+ topical command convention} for the argument.
+
+ The enum items are documented using the \l {value}{\\value}
+ command. If an item isn't documented, QDoc will emit a
+ warning. This can be avoided using the \l
+ {omitvalue}{\\omitvalue} command excluding an item from the
+ documentation. The enum documentation will be located in
+ the associated class, header file or namespace
+ documentation.
+
+ For example:
+
+ \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
+
+ In case of the Qt::Corner enum,
+
+ \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
+
+ this associated QDoc comment will be rendered as
+
+ \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
+
+ in qt.html.
+
+ See also \l {value}{\\value} and \l {omitvalue}{\\omitvalue}.
+
+ \row
+ \o \bold \\example \target example-command
+ \o \bold {The \\example command allows you to document an
+ example.}
+
+ The command follows \l {topical argument}{the general
+ topical command convention} for the argument. In particular
+ the command's argument is the example's path relative to
+ the paths listed in the \l exampledirs configuration
+ variable.
+
+ The documentation will be located in \i
+ {path-to-example}.html, and QDoc will add a list of all the
+ example files at the top of this documentation page.
+
+ For example, if \l exampledirs contain \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
+
+ will be rendered as
+
+ \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
+
+ in widgets-imageviewer.html.
+
+ \row
+ \o \bold \\fn \target fn
+ \o \bold {The \\fn command allows you to document a function.}
+
+ The command follows \l {topical argument}{the general
+ topical command convention} for the argument. In particular
+ it is important that the return type of the function,
+ whether it is \c const or not and the complete set of
+ arguments with type are included in the argument. If the
+ referenced function doesn't exist, QDoc will emit a
+ warning.
+
+ Also, the \\fn command is QDoc's default command, i.e. when
+ no topical command can be found within a QDoc comment, QDoc
+ tries to tie the documentation to the following code as if
+ it was function documentation.
+
+ This means that the command normally isn't necessary since
+ the recommended style is to write the function
+ documentation directly before the function implementation
+ in the \c .cpp file. In fact, it should only be used for
+ inline functions implemented in the \c .h file.
+
+ For example:
+
+ \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
+
+ will be rendered 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}{\\overload}.
+
+ \row
+ \o \bold \\group \target group
+ \o \bold {The \\group command creates a separate page that
+ lists the classes belonging to the group specified by the
+ command's argument.}
+
+ The command follows \l {topical argument}{the general
+ topical command convention} for the argument. The \\group
+ command is typically followed by a \l {title}{\\title}
+ command and a short introduction to the group. The
+ generated HTML documentation for the specified group is put
+ in <lower-case>\i{group}.html.
+
+ A class can be related to a group by using the \l
+ {ingroup}{\\ingroup} command. In addition, overviews can be
+ related to a group using the same command, but these must
+ be listed explicitly using the \l
+ {generatelist}{\\generatelist} command (see example below).
+
+ Each class is listed with a link to the class reference
+ page and a brief description based on the classes' \l
+ {brief}{\\brief} texts. For example:
+
+ \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
+
+ will be rendered as
+
+ \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
+
+ in io.html.
+
+ Note that overviews related to the given group, must be
+ listed explicitly using the \l
+ {generatelist}{\\generatelist} command with the \c related
+ argument. For example:
+
+ \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}{\\ingroup} and \l
+ {generatelist}{\\generatelist}.
+
+ \row
+ \o \bold \\headerfile \target headerfile
+ \o \bold {The \\headerfile command allows you to document
+ global functions, types and macros declared in a header file.}
+
+ The command follows \l {topical argument}{the general
+ topical command convention} for the argument, and the
+ generated HTML documentation for the specified header file
+ is put in <lower-case>\i{headerfilename}.html.
+
+ A function, type or macro can be associated with a
+ headerfile using the \l {relates}{\\relates} command.
+
+ If the referenced header file doesn't exist, the
+ \\headerfile command will still create a documentation page
+ for a header file with the referenced file's name.
+
+ For example:
+
+ \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
+
+ will be rendered as
+
+ \quotation
+ \raw HTML
+ <center><h1>&lt;QtAlgorithms&gt; -
+ Generic Algorithms</h1></center>
+ <p>The <QtAlgorithms> header file provides generic
+ template-based algorithms.
+ <a href="13-qdoc-commands-topical.html#header">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
+
+ in qtalgorithms.html.
+
+ \row
+ \o \bold \\macro \target macro
+ \o \bold {The \\macro command allows you to document a C++ macro.}
+
+ The command follows \l {topical argument}{the general
+ topical command convention} for the argument.
+
+ QDoc recognizes three different macro syntax: function-like
+ macros like Q_ASSERT(), declaration-style macros like
+ Q_PROPERTY() and macros without parentheses like Q_OBJECT.
+
+ The \\macro command must be followed by a \l
+ {relates}{\\relates} command which attaches the
+ documentation to that of a related class, header file. or
+ namespace. Otherwise the documentation will be lost.
+
+ For example:
+
+ \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
+
+ will be rendered as
+
+ \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
+
+ in qtglobal.html. And
+
+ \code
+ / *!
+ \macro Q_PROPERTY(...)
+ \relates QObject
+
+ This macro declares a QObject property. The syntax is:
+
+ ...
+
+ \sa {Qt's Property System}
+ * /
+ \endcode
+
+ will be rendered as
+
+ \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
+
+ in qobject.html. And
+
+ \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
+
+ will be rendered as
+
+ \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 and
+ Slots} and \l {Qt's Property System}.
+ \endquotation
+
+ in qobject.html.
+
+ \row
+ \o \bold \\module \target module
+ \o \bold {The \\module creates a separate page that lists the
+ classes belonging to the module specified by the command's
+ argument.}
+
+ The command follows \l {topical argument}{the general
+ topical command convention} for the argument.
+
+ A class can be related to a module using the \l
+ {inmodule}{\\inmodule} command.
+
+ The \\module command is typically followed by the \l
+ {title}{\\title} and \l {brief}{\\brief} commands. Each
+ class is listed with a link to the class reference page and
+ a brief description based on the classes' \l
+ {brief}{\\brief} texts.
+
+ 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
+
+ will be rendered as
+
+ \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
+
+ in qtnetwork.html.
+
+ See also \l {inmodule}{\\inmodule}
+
+ \row
+ \o \bold \\namespace \target namespace
+ \o \bold {The \\namespace command allows you to document a C++
+ namespace.}
+
+ The command follows \l {topical argument}{the general
+ topical command convention} for the argument.
+
+ QDoc will generate the same additional links and
+ documentation for all the members of the namespace as it
+ does for \l {framework}{classes}. The documentation for
+ the specified namespace is put in <lower-case>\i
+ {namespace}.html.
+
+ For example:
+
+ \code
+ / *!
+ \namespace Qt
+
+ \brief The Qt namespace contains miscellaneous
+ identifiers used throughout the Qt library.
+ * /
+ \endcode
+
+ will be rendered as
+
+ \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-topical.html#name">More...</a>
+ </p>
+
+ <pre>#include &lt;Qt&gt;</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
+
+ in qt.html.
+
+ \row
+ \o \bold \\page \target page
+ \o \bold {The \\page command allows you to create a stand-alone
+ documentation page.}
+
+ The command follows \l {topical argument}{the general
+ topical command convention} for the argument.
+
+ The page's title can be set using the \l {title}{\\title}
+ command. For example:
+
+ \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
+
+ will be rendered in its own HTML file: \l{About Qt}.
+
+ \row
+ \o \bold {\\externalpage} \target externalpage
+ \o \bold {The \\externalpage command gives a title to
+ an external URL.}
+
+ The command follows \l {topical argument}{the general
+ topical command convention} for the argument.
+
+ For example:
+
+ \code
+ / *!
+ \externalpage http://www.trolltech.com/products/embedded/index.html
+ \title Qtopia Core
+ * /
+ \endcode
+
+ The QDoc comment above allows you to link to the Qtopia
+ Core webpage by simply linking to the given title. For
+ example:
+
+ \code
+ / *!
+ The broad scope of the \l {Qtopia Core} API enables it to
+ be used across a wide variety of development projects.
+ * /
+ \endcode
+
+ will be rendered as
+
+ \quotation
+ The broad scope of the \l
+ {http://www.trolltech.com/products/embedded/index.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://www.trolltech.com/products/embedded/index.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.
+
+ \row
+ \o \bold \\property \target property
+ \o \bold {The \\property command allows you to document a Qt
+ property.}
+
+ The command follows \l {topical argument}{the general
+ topical command convention} for the argument.
+
+ 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. For example:
+
+ \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 is typically accompanied with a \l
+ {brief}{\\brief} command. In the case of a property, the
+ \l {brief}{\\brief} command's argument is a sentence
+ fragment that will be included in a one-sentence
+ description of the property generated by QDoc. The command
+ follows the same rules for the \l {brief
+ property}{description} as the \l {variable}{\\variable}
+ command.
+
+ For example:
+
+ \code
+ / *!
+ \property QPushButton::flat
+ \brief whether the border is disabled
+
+ This property's default is false.
+ * /
+ \endcode
+
+ will be rendered as
+
+ \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
+
+ in qpushbutton.html. And
+
+ \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
+
+ will be rendered as
+
+ \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
+
+ in qwidget.html.
+
+ \row
+ \o \bold \\service \target service
+
+ \o \bold {The \\service command tells QDoc that a class is a
+ service class and specifies its alias, i.e. the associated
+ service's name.}
+
+ The command takes two arguments, the service class's name
+ and the associated alias. For example:
+
+ \code
+ / *!
+ \service TimeService Time
+ ...
+ * /
+ class TimeService : public QCopObjectService
+ {
+ ...
+ }
+ \endcode
+
+ See also \l {class}{\\class} and \l
+ {generatelist}{\\generatelist}.
+
+ \row
+ \o \bold \\typedef \target typedef
+ \o \bold {The \\typedef command allows you to document a C++ type
+ definition.}
+
+ The command follows \l {topical argument}{the general
+ topical command convention} for the argument.
+
+ The documentation will be located in the associated class,
+ header file or namespace documentation. When documenting a
+ global type definition, the \\typedef command must be
+ accompanied with a \l {relates}{\\relates} command. For
+ example:
+
+ \code
+ / *!
+ \typedef QObjectList
+ \relates QObject
+
+ Synonym for QList<QObject>.
+ * /
+ \endcode
+
+ will be rendered as
+
+ \quotation
+ \raw HTML
+ <h3>typedef QObjectList</h3>
+ \endraw
+
+ Synonym for QList<QObject>.
+ \endquotation
+
+ in qobject.html. Another, although more rare, example is
+
+ \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
+
+ will be rendered 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
+
+ in qtglobal.html. Other type definitions are located in the
+ documentation of the class that defines it, for example:
+
+ \code
+ / *!
+ \typedef QLinkedList::Iterator
+
+ Qt-style synonym for QList::iterator.
+ * /
+ \endcode
+
+ will be rendered as
+
+ \quotation
+ \raw HTML
+ <h3>typedef QLinkedList::Iterator</h3>
+ \endraw
+
+ Qt-style synonym for QList::iterator.
+ \endquotation
+
+ in qlinkedlist.html.
+
+ \row
+ \o \bold \\variable \target variable
+ \o \bold {The \\variable command allows you to document a
+ member variable or a constant.}
+
+ The command follows \l {topical argument}{the general
+ topical command convention} for the argument.
+
+ The \\variable command is typically followed by a \l
+ {brief}{\\brief} command; QDoc will generate the
+ documentation for the variable based on the brief
+ description. The command follows the same rules for the \l
+ {brief property}{description} as the \l
+ {property}{\\property} 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
+
+ will be rendered 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
+
+ in qstyleoption.html.
+
+ But you can also use the \\variable command to document
+ constants like for example the \c Type and \c UserType
+ constants in the QTreeWidgetItem class:
+
+ \code
+ enum { Type = 0, UserType = 1000 };
+ \endcode
+
+ Then
+
+ \code
+ / *!
+ \variable QTreeWidgetItem::Type
+
+ The default type for tree widget items.
+
+ \sa UserType, type()
+ * /
+ \endcode
+
+ and
+
+ \code
+ / *!
+ \variable QTreeWidgetItem::UserType
+
+ The minimum value for custom types. Values below
+ UserType are reserved by Qt.
+
+ \sa Type, type()
+ * /
+ \endcode
+
+ will be rendered 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
+
+ in qtreewidget.html.
+ \endtable
+*/
+
+/*!
+ \page 14-qdoc-commands-contextualcommands.html
+ \previouspage Topical Commands
+ \contentspage QDoc Manual - Table of Contents
+ \nextpage Navigation Commands
+
+ \title Contextual Commands
+
+ The contextual commands provide QDoc with information, that it
+ wouldn't figure out otherwise, about the documented object. For
+ example whether a class is thread-safe or not.
+
+ These commands can appear anywhere within a QDoc comment.
+
+ \section1 Alphabetical List
+
+ \l {16-qdoc-commands-status.html#compat}{\\compat},
+ \l {15-qdoc-commands-navigation.html#contentspage}{\\contentspage},
+ \l {15-qdoc-commands-navigation.html#indexpage}{\\indexpage},
+ \l {19-qdoc-commands-grouping.html#ingroup}{\\ingroup},
+ \l {19-qdoc-commands-grouping.html#inmodule}{\\inmodule},
+ \l {16-qdoc-commands-status.html#internal}{\\internal},
+ \l {19-qdoc-commands-grouping.html#mainclass}{\\mainclass},
+ \l {15-qdoc-commands-navigation.html#nextpage}{\\nextpage},
+ \l {17-qdoc-commands-thread.html#nonreentrant}{\\nonreentrant},
+ \l {16-qdoc-commands-status.html#obsolete}{\\obsolete},
+ \l {18-qdoc-commands-relating.html#overload}{\\overload},
+ \l {16-qdoc-commands-status.html#preliminary}{\\preliminary},
+ \l {15-qdoc-commands-navigation.html#previouspage}{\\previouspage},
+ \l {17-qdoc-commands-thread.html#reentrant}{\\reentrant},
+ \l {18-qdoc-commands-relating.html#reimp}{\\reimp},
+ \l {18-qdoc-commands-relating.html#relates}{\\relates},
+ \l {15-qdoc-commands-navigation.html#startpage}{\\startpage},
+ \l {17-qdoc-commands-thread.html#threadsafe}{\\threadsafe},
+ \l {20-qdoc-commands-title.html#title}{\\title}
+
+ \section1 Categories
+ \list
+ \o \l {Navigation Commands}
+ \o \l {Status Commands}
+ \o \l {Thread Support Commands}
+ \o \l {Relating Commands}
+ \o \l {Grouping Commands}
+ \o \l {Title Commands}
+ \endlist
+*/
+
+/*!
+ \page 15-qdoc-commands-navigation.html
+ \previouspage Contextual Commands
+ \contentspage QDoc Manual - Table of Contents
+ \nextpage Status Commands
+
+ \title Navigation Commands
+
+ The navigation commands allow you to link the pages of a multipage
+ document together. They provide the components of a navigation bar
+ at the top and bottom of the document. They also provide browser
+ and search engine support.
+
+ \section1 Alphabetical List
+
+ \l {15-qdoc-commands-navigation.html#contentspage}{\\contentspage},
+ \l {15-qdoc-commands-navigation.html#indexpage}{\\indexpage},
+ \l {15-qdoc-commands-navigation.html#nextpage}{\\nextpage},
+ \l {15-qdoc-commands-navigation.html#previouspage}{\\previouspage},
+ \l {15-qdoc-commands-navigation.html#startpage}{\\startpage}
+
+ \section1 General Description
+
+ The QDoc comments below shows a typical example using the
+ navigation commands.
+
+ \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
+
+ The second page of this multipage document, "Getting Started",
+ will be rendered as
+
+ \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
+
+ in creatingdialogs.html.
+
+ In addition, the \l {indexpage}{\\indexpage} and \l
+ {startpage}{\\startpage} commands specifies links to the page's
+ index page and start page. These links are 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 has
+ no visual effect on the documentation:
+
+ \code
+ <head>
+ ...
+ <link rel="index" href="index.html" />
+ <link rel="start" href="basicqt.html" />
+ ...
+ </head>
+ \endcode
+
+ \section1 Command Descriptions
+
+ \table
+ \header
+ \o Command
+ \o Description
+
+ \row
+ \o \bold \\previouspage \target previouspage
+ \o \bold {The \\previouspage command links the current page
+ to the previous one in an ordered series of documents}.
+
+ 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.
+
+ In the end, the link is rendered at the top and bottom of
+ the current page. For an example, see the \l {General
+ Description} section.
+
+ \row
+ \o \bold \\nextpage \target nextpage
+ \o \bold {The \\nextpage command links the current
+ page to the next page in an ordered series of documents}.
+
+ The command follows the same syntax and argument convention
+ as the \l {previouspage}{\\previouspage} command.
+
+ For an example, see the \l {General Description} section.
+
+ \row
+ \o \bold \\startpage \target startpage
+ \o \bold {The \\startpage command specifies the first document
+ in a collection of documents.}
+
+ 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 specified document which
+ is included in the HTML file but 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.
+
+ For an example, see the \l {General Description} section.
+
+ \row
+ \o \bold \\contentspage \target contentspage
+ \o \bold {The \\contentspage command links the current
+ page to a contents page}.
+
+ The command follows the same syntax and argument convention
+ as the \l {previouspage}{\\previouspage} command.
+
+ For an example, see the \l {General Description} section.
+
+ \row
+ \o \bold \\indexpage \target indexpage
+ \o \bold {The \\indexpage command specifies a document providing
+ an index 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 specified document which
+ is included in the HTML file but 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 for the current document.
+
+ For an example, see the \l {General Description} section.
+
+ \endtable
+*/
+
+/*!
+ \page 16-qdoc-commands-status.html
+ \previouspage Navigation Commands
+ \contentspage QDoc Manual - Table of Contents
+ \nextpage Thread Support Commands
+
+ \title Status Commands
+
+ The usage commands can indicate whether a documented object is
+ under development, becoming obsolete, provided for compatibility
+ reasons or simply not part of the public interface. They can
+ describe the history of minor versions. And they can also describe
+ a documented object's ability to handle multithreaded programming.
+
+ \section1 Alphabetical List
+
+ \l {16-qdoc-commands-status.html#compat}{\\compat},
+ \l {16-qdoc-commands-status.html#internal}{\\internal},
+ \l {16-qdoc-commands-status.html#obsolete}{\\obsolete},
+ \l {16-qdoc-commands-status.html#preliminary}{\\preliminary},
+ \l {16-qdoc-commands-status.html#since}{\\since}
+
+ \section1 Command Description
+
+ \table
+ \header
+ \o Command
+ \o Description
+
+ \row
+ \o \bold \\preliminary \target preliminary
+ \o \bold {The \\preliminary command indicates that the
+ referenced function is 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. For example:
+
+ \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
+
+ will be rendered 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
+ is 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
+
+ \row
+ \o \bold \\obsolete \target obsolete
+ \o \bold {The \\obsolete command indicates that the referenced
+ function no longer should 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.
+
+ For example:
+
+ \code
+ / *!
+ \fn MyClass::MyObsoleteFunction
+ \obsolete
+
+ Use MyNewFunction() instead.
+ * /
+ \endcode
+
+ will be rendered 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
+
+ in myclass-obsolete.html
+
+
+ \row
+ \o \bold \\compat \target compat
+ \o \bold {The \\compat command indicates that the referenced 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 within 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 on
+ top of the associated documentation. For example:
+
+ \code
+ / *!
+ \class MyQt3SupportClass
+ \compat
+ * /
+ \endcode
+
+ will be rendered as
+
+ \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
+
+ on the top of the MyQt3SupportClass class reference.
+
+ 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. For example:
+
+ \code
+ / *!
+ \fn MyClass::MyQt3SupportMemberFunction
+ \compat
+
+ Use MyNewFunction() instead.
+ * /
+ \endcode
+
+ will be rendered 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
+
+ in myclass-qt3.html
+
+
+ \row
+ \o \bold \\internal \target internal
+ \o \bold {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. For example:
+
+ \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
+
+ in qspinbox.cpp, will not be rendered at all.
+
+ \row
+ \o \bold \\since \target since
+ \o \bold {The \\since command tells in which minor release
+ the associated functionality was added.}
+
+ For example:
+
+ \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
+
+ will be rendered 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}.
+
+ \endtable
+*/
+
+/*!
+ \page 17-qdoc-commands-thread.html
+ \previouspage Status Commands
+ \contentspage QDoc Manual - Table of Contents
+ \nextpage Relating Commands
+
+ \title Thread Support Commands
+
+ The thread support commands specify the level of support for
+ multithreaded programming of a class or function.
+
+ \section1 Alphabetical List
+
+ \l {17-qdoc-commands-thread.html#nonreentrant}{\\nonreentrant},
+ \l {17-qdoc-commands-thread.html#reentrant}{\\reentrant},
+ \l {17-qdoc-commands-thread.html#threadsafe}{\\threadsafe}
+
+ \section1 General Description
+
+ There are three levels of support for multithreaded programming of
+ a class or function: \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 declared \c reentrant or \c threadsafe, using the
+ \l {reentrant}{\\reentrant} and \l {threadsafe}{\\threadsafe}
+ commands respectively, functions in the referenced class can be
+ declared \c nonreentrant, using the \l
+ {nonreentrant}{\\nonreentrant} command, excluding the functions
+ from the general view.
+
+ For 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
+
+ will be rendered 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 Command Descriptions
+
+ \table
+ \header
+ \o Command
+ \o Description
+
+ \row
+ \o \bold \\threadsafe \target threadsafe
+ \o \bold {The \\threadsafe command indicates that the
+ associated class or function can be called simultaneously by
+ multiple threads even when each invocation references
+ shared data.}
+
+ The command must stand on its own line.
+
+ The generated documentation resulting from using the
+ \\threadsafe command is similar to the result of using the
+ \l {reentrant}{\\reentrant} command. For an example, see
+ the \l {General Description} section.
+
+ See also \l{reentrant}{\\reentrant} and
+ \l{nonreentrant}{\\nonreentrant}.
+
+ \row
+ \o \bold \\reentrant \target reentrant
+ \o \bold {The \\reentrant command indicates that the associated
+ class or function can be called simultaneously
+ by multiple threads, provided that each invocation of the
+ functions reference unique data.}
+
+ The command must stand on its own line.
+
+ For an example, see the \l {General Description} section.
+
+ See also \l{nonreentrant}{\\nonreentrant} and
+ \l{threadsafe}{\\threadsafe}.
+
+ \row
+ \o \bold \\nonreentrant \target nonreentrant
+ \o \bold {The \\nonreentrant command indicates that the
+ associated class or function cannot be called by
+ multiple threads.}
+
+ The command must stand on its own line.
+
+ For an example, see the \l {General Description} section.
+
+ See also \l{reentrant}{\\reentrant} and
+ \l{threadsafe}{\\threadsafe}.
+
+ \endtable
+*/
+
+/*!
+ \page 18-qdoc-commands-relating.html
+ \previouspage Thread Support Commands
+ \contentspage QDoc Manual - Table of Contents
+ \nextpage Grouping Commands
+
+ \title Relating Commands
+
+ The relation commands discribe how the documented object relates
+ to its context: Whether it is an overloaded function, a
+ reimplemented function or a global function related to a specified
+ class or header file.
+
+ \section1 Alphabetical List
+
+ \l {18-qdoc-commands-relating.html#overload}{\\overload},
+ \l {18-qdoc-commands-relating.html#reimp}{\\reimp},
+ \l {18-qdoc-commands-relating.html#relates}{\\relates},
+
+ \section1 Command Descriptions
+
+ \table
+ \header
+ \o Command
+ \o Description
+
+ \row
+ \o \bold \\overload \target overload
+ \o \bold {The \\overload command indicates that the
+ function is a secondary overload of its name.}
+
+ The command must stand on its own line.
+
+ For any overloaded function (except constructors), QDoc
+ expects one primary version of the function and all the
+ the overloads 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 overload.
+
+ From Qt 4.5, you can include the function name plus '()'
+ as a parameter to the \bold{\\overload} command, which
+ will include a standard \i{This function overloads...}
+ line of text with a link to the documentation for the
+ primary version of the function.
+
+ For example:
+
+ \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
+
+ will be rendered 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
+ \i icon and some \i 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.
+
+ \row
+ \o \bold \\reimp \target reimp
+ \o \bold {The \\reimp command indicates that the
+ referenced function is a reimplementation of a virtual function,
+ where the reimplementation has no effect on the interface.}
+
+ The command must stand on its own line.
+
+ QDoc will omit the reimplemented function from the class
+ reference. For example:
+
+ \code
+ / *!
+ \reimp
+ * /
+ void QToolButton::nextCheckState()
+ {
+ Q_D(QToolButton);
+ if (!d->defaultAction)
+ QAbstractButton::nextCheckState();
+ else
+ d->defaultAction->trigger();
+ }
+ \endcode
+
+ will not be rendered at all; only a link to the inherited
+ QAbstractButton::nextCheckState() will appear in the
+ documentation.
+
+ \row
+ \o \bold \\relates \target relates
+ \o \bold {The \\relates command attaches the documentation of
+ a global function to that of a related class or header file.}
+
+ The command's argument is a class name, an the command (and
+ its argument) must stand on its own line.
+
+ \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
+
+ will be rendered with the QChar documentation.
+
+ \endtable
+*/
+
+/*!
+ \page 19-qdoc-commands-grouping.html
+ \previouspage Relating Commands
+ \contentspage QDoc Manual - Table of Contents
+ \nextpage Title Commands
+
+ \title Grouping Commands
+
+ 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 Alphabetical List
+
+ \l {19-qdoc-commands-grouping.html#ingroup}{\\ingroup},
+ \l {19-qdoc-commands-grouping.html#inmodule}{\\inmodule},
+ \l {19-qdoc-commands-grouping.html#mainclass}{\\mainclass},
+
+ \section1 Command Descriptions
+
+ \table
+ \header
+ \o Command
+ \o Description
+
+ \row
+ \o \bold \\mainclass \target mainclass
+ \o \bold {The \\mainclass command relates the documented class to
+ a group called mainclasses.}
+
+ The command must stand on its own line.
+
+ For example:
+
+ \code
+ / *!
+ \class QWidget qwidget.h
+ \brief The QWidget class is the base class of
+ all user interface objects.
+
+ \mainclass
+
+ ...
+ * /
+ \endcode
+
+ will ensure that the QWidget class is included in the \c
+ mainclasses group, which means, for example, that the class
+ will appear on the list created by calling the \l
+ {generatelist}{\\generatelist} command with the \c
+ mainclasses argument:
+
+ \l http://qt.nokia.com/doc/4.0/mainclasses.html
+
+ See also \l {generatelist}{\\generatelist}.
+
+ \row
+ \o \bold \\ingroup \target ingroup
+
+ \o \bold {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. For example:
+
+ \code
+ / *!
+ \class QDir
+ \brief The QDir class provides access to directory
+ structures and their contents.
+
+ \ingroup io
+ ...
+ * /
+ \endcode
+
+ will ensure that the QDir class is included in the \c io
+ group, which means, for example, that QDir will appear on
+ the list created by calling the \l {group}{\\group} command
+ with the \c io argument.
+
+ Note that to list overviews that are related to a given
+ group, you must generate the list exlicitly by using the \l
+ {generatelist}{\\generatelist} command with the \c related
+ argument.
+
+ See also \l {group}{\\group}.
+ \row
+ \o \bold \\inmodule \target inmodule
+ \o \bold {The \\inmodule command relates the documented 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 needs to
+ 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. For example:
+
+ \code
+ /*!
+ \class QDesignerTaskMenuExtension
+ \inmodule QtDesigner
+ * /
+ \endcode
+
+ will ensure 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}{\\generatelist} command with
+ the \c {{classesbymodule QtDesigner}} argument.
+
+ See also \l {module}{\\module} and \l
+ {generatelist}{\\generatelist}.
+ \endtable
+*/
+
+/*!
+ \page 20-qdoc-commands-title.html
+ \previouspage Grouping Commands
+ \contentspage QDoc Manual - Table of Contents
+ \nextpage QDoc Configuration
+
+ \title Title Commands
+
+ In general a title command considers everything that follows it
+ until the first line break as its argument. If the title needs to
+ be spanned over several lines, make sure to end each line (except
+ the last one) with a backslash.
+
+ \section1 Alphabetical List
+
+ \l {20-qdoc-commands-title.html#title}{\\title},
+ \l {20-qdoc-commands-title.html#subtitle}{\\subtitle}
+
+ \section1 Command Descriptions
+
+ \table
+ \header
+ \o Command
+ \o Description
+
+ \row
+ \o \bold \\title \target title
+ \o \bold {The \\title command sets the title for a
+ documentation page, or allows you to override it.}
+
+ For example:
+
+ \code
+ / *!
+ \page signalandslots.html
+
+ \title Signals and 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
+
+ will be rendered 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}{\\subtitle}.
+
+ \row
+ \o \bold \\subtitle \target subtitle
+ \o \bold {The \\subtitle command sets a subtitle for a
+ documentation page.}
+
+ For example:
+
+ \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
+
+ will be rendered 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}{\\title}.
+ \endtable
+*/
+
+/*!
+ \page 21-0-qdoc-configuration.html
+ \previouspage Title Commands
+ \contentspage QDoc Manual - Table of Contents
+ \nextpage General Variables
+
+ \title QDoc Configuration
+
+ \tableofcontents
+
+ \list
+ \o \l {Supporting Derived Projects}
+ \o \l {QDoc Compatibility}
+ \endlist
+
+ When running QDoc to generate the documentation, you must specify
+ a configuration file on the command line:
+
+ \quotation
+ \bold {/currentdirectory$ qdoc3 my-documentation.qdocconf}
+ \endquotation
+
+ \section1 General Description
+
+ The configuration file is a list of entries of entries of the form
+ \i {"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.
+
+ In addition, you can use some particular configuration variables
+ to make QDoc support derived projects, i.e make the projects, for
+ example Qt Solutions, contain links to the online Qt
+ documentation. These variables are documented in the \l
+ {Supporting Derived projects} section. In this section you can
+ also find out how to use these variables to support your derived
+ projects.
+
+ If some of the variable keys have the same values, they can be set
+ at the same time. For example:
+
+ \code
+ {header, source}dirs = kernel
+ \endcode
+
+ is equivalent to
+
+ \code
+ headerdirs = kernel
+ sourcedirs = kernel
+ \endcode
+
+ A variable's value can be set using either '=' or '+='. The
+ difference is that '=' overrides any previously set value, while
+ '+=' only adds the value to the previously set ones.
+
+ In general, some of the variables accepts a list of strings as
+ their value, while others only accept a single string. If you
+ provide a variable of the latter type with several strings they
+ will simply be concatenated. The quotes around the value string
+ are optional. But applying them allows you to use special
+ characters like '=' and ' \" ' within the string. For example:
+
+ \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
+
+ \section2 Alphabetical List
+
+ \l {22-qdoc-configuration-generalvariables.html#alias}{alias},
+ \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoredirectives}
+ {Cpp.ignoredirectives},
+ \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoretoken}
+ {Cpp.ignoretokens},
+ \l {22-qdoc-configuration-generalvariables.html#definesvariable}{defines},
+ \l {22-qdoc-configuration-generalvariables.html#edition}{edition},
+ \l {22-qdoc-configuration-generalvariables.html#exampledirs}{exampledirs},
+ \l {22-qdoc-configuration-generalvariables.html#examples}{examples},
+ \l {22-qdoc-configuration-generalvariables.html#examples.fileextensions}
+ {examples.fileextensions},
+ \l {22-qdoc-configuration-generalvariables.html#extraimages}{extraimages},
+ \l {22-qdoc-configuration-generalvariables.html#falsehoods}{falsehoods},
+ \l {22-qdoc-configuration-generalvariables.html#headerdirs}{headerdirs},
+ \l {22-qdoc-configuration-generalvariables.html#headers}{headers},
+ \l {22-qdoc-configuration-generalvariables.html#headers.fileextensions}
+ {headers.fileextensions},
+ \l {24-qdoc-configuration-htmlvariables.html#HTML.footer}{HTML.footer},
+ \l {24-qdoc-configuration-htmlvariables.html#HTML.postheader}
+ {HTML.postheader},
+ \l {24-qdoc-configuration-htmlvariables.html#HTML.style}{HTML.style},
+ \l {22-qdoc-configuration-generalvariables.html#imagedirs}{imagedirs},
+ \l {22-qdoc-configuration-generalvariables.html#images}{images},
+ \l {22-qdoc-configuration-generalvariables.html#images.fileextensions}
+ {images.fileextensions},
+ \l {22-qdoc-configuration-generalvariables.html#language}{language},
+ \l {22-qdoc-configuration-generalvariables.html#macro}{macro},
+ \l {22-qdoc-configuration-generalvariables.html#outputdir}{outputdir},
+ \l {22-qdoc-configuration-generalvariables.html#outputformats}
+ {outputformats},
+ \l {22-qdoc-configuration-generalvariables.html#slow}{slow},
+ \l {22-qdoc-configuration-generalvariables.html#sourcedirs}{sourcedirs},
+ \l {22-qdoc-configuration-generalvariables.html#sources}{sources},
+ \l {22-qdoc-configuration-generalvariables.html#sources.fileextensions}
+ {sources.fileextensions},
+ \l {22-qdoc-configuration-generalvariables.html#spurious}{spurious},
+ \l {22-qdoc-configuration-generalvariables.html#tabsize}{tabsize},
+ \l {22-qdoc-configuration-generalvariables.html#version}{version},
+ \l {22-qdoc-configuration-generalvariables.html#versionsym}{versionsym}
+
+ \section2 Categories
+
+ \list
+ \o \l {General Variables}
+ \o \l {C++ Specific Variables}
+ \o \l {HTML Specific 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 QDoc Configuration
+ \contentspage QDoc Manual - Table of Contents
+
+ \title minimum.qdocconf
+
+ \quotefile examples/minimum.qdocconf
+*/
+
+/*!
+ \page 21-2-qt-qdocconf.html
+ \previouspage QDoc Configuration
+ \contentspage QDoc Manual - Table of Contents
+
+ \title qt.qdocconf
+
+ \quotefile files/qt.qdocconf
+*/
+
+/*!
+ \page 22-qdoc-configuration-generalvariables.html
+ \previouspage QDoc Configuration
+ \contentspage QDoc Manual - Table of Contents
+ \nextpage Creating Help Project Files
+
+ \title General 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.
+
+ \section1 Alphabetical List
+
+ \l {22-qdoc-configuration-generalvariables.html#alias}{alias},
+ \l {22-qdoc-configuration-generalvariables.html#codeindent}{codeindent},
+ \l {22-qdoc-configuration-generalvariables.html#definesvariable}{defines},
+ \l {22-qdoc-configuration-generalvariables.html#edition}{edition},
+ \l {22-qdoc-configuration-generalvariables.html#exampledirs}{exampledirs},
+ \l {22-qdoc-configuration-generalvariables.html#examples}{examples},
+ \l {22-qdoc-configuration-generalvariables.html#examples.fileextensions}
+ {examples.fileextensions},
+ \l {22-qdoc-configuration-generalvariables.html#extraimages}{extraimages},
+ \l {22-qdoc-configuration-generalvariables.html#falsehoods}{falsehoods},
+ \l {22-qdoc-configuration-generalvariables.html#generateindex}{generateindex},
+ \l {22-qdoc-configuration-generalvariables.html#headerdirs}{headerdirs},
+ \l {22-qdoc-configuration-generalvariables.html#headers}{headers},
+ \l {22-qdoc-configuration-generalvariables.html#headers.fileextensions}
+ {headers.fileextensions},
+ \l {22-qdoc-configuration-generalvariables.html#imagedirs}{imagedirs},
+ \l {22-qdoc-configuration-generalvariables.html#images}{images},
+ \l {22-qdoc-configuration-generalvariables.html#images.fileextensions}
+ {images.fileextensions},
+ \l {22-qdoc-configuration-generalvariables.html#language}{language},
+ \l {22-qdoc-configuration-generalvariables.html#macro}{macro},
+ \l {22-qdoc-configuration-generalvariables.html#outputdir}{outputdir},
+ \l {22-qdoc-configuration-generalvariables.html#outputformats}
+ {outputformats},
+ \l {22-qdoc-configuration-generalvariables.html#slow}{slow},
+ \l {22-qdoc-configuration-generalvariables.html#sourcedirs}{sourcedirs},
+ \l {22-qdoc-configuration-generalvariables.html#sources}{sources},
+ \l {22-qdoc-configuration-generalvariables.html#sources.fileextensions}
+ {sources.fileextensions},
+ \l {22-qdoc-configuration-generalvariables.html#spurious}{spurious},
+ \l {22-qdoc-configuration-generalvariables.html#tabsize}{tabsize},
+ \l {22-qdoc-configuration-generalvariables.html#tagfile}{tagfile},
+ \l {22-qdoc-configuration-generalvariables.html#version}{version},
+ \l {22-qdoc-configuration-generalvariables.html#versionsym}{versionsym}
+
+ \section1 Variable Descriptions
+
+ \table
+
+ \header
+ \o Variable
+ \o Description
+
+ \row
+ \o \bold alias \target alias
+ \o \bold {The \c alias variable renames a QDoc command.}
+
+ The general syntax is \tt {alias.\i{original-command-name}
+ = \i temporary-command-name}.
+
+ For example:
+
+ \code
+ alias.i = e
+ \endcode
+
+ 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 {QDoc
+ Compatibility}{compatibility section}.
+
+ See also \l macro.
+
+ \row
+ \o \bold codeindent \target codeindent
+ \o \bold {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 Variables#HTML.stylesheets}{stylesheets} to
+ adjust the appearance of certain types of HTML elements, this
+ level of indentation is not always required.
+
+ \row
+ \o \bold defines \target definesvariable
+ \o \bold {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}{\\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.
+
+ For example:
+
+ \code
+ defines = Q_QDOC \
+ QT_.*_SUPPORT \
+ QT_.*_LIB \
+ QT_COMPAT \
+ QT3_SUPPORT \
+ Q_WS_.* \
+ Q_OS_.* \
+ Q_BYTE_ORDER \
+ __cplusplus
+ \endcode
+
+ 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 and \l {if}{\\if}.
+
+ \row
+ \o \bold edition \target edition
+ \o \bold {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 Commands#generatelist}{generatelist} command
+ is used to generate a list of classes for this edition:
+
+ \code
+ \generatelist{classesbyedition Console}
+ \endcode
+
+ \row
+ \o \bold exampledirs \target exampledirs
+ \o \bold {The \c exampledirs variable specifies the directories
+ containing the source code of the example files.}
+
+ The \l {examples}{\c examples} and \c exampledirs variables
+ are used by the \l {quotefromfile}{\\quotefromfile}, \l
+ {quotefile}{\\quotefile} and \l {example}{\\example}
+ commands. If both the \l {examples}{\c examples} and \c
+ exampledirs variables are defined, QDoc will search in
+ both, first in \l {examples}{\c examples} then in \c
+ 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, \i not in
+ subdirectories.
+
+ For example:
+
+ \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.
+
+ \row
+ \o \bold examples \target examples
+ \o \bold {The \c examples variable allows you to specify individual
+ example files in addition to those located in the directories
+ specified by the \l {exampledirs}{\c exampledirs} variable.}
+
+ The \c examples and \l {exampledirs}{\c exampledirs}
+ variables are used by the \l
+ {quotefromfile}{\\quotefromfile}, \l
+ {quotefile}{\\quotefile} and \l {example}{\\example}
+ commands. If both the \c examples and \l {exampledirs}{\c
+ exampledirs} variables are defined, QDoc will search in
+ both, first in \c examples then in \l {exampledirs}{\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}{\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.
+
+ \row
+ \o \bold examples.fileextensions \target examples.fileextensions
+ \o \bold {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}.
+
+ \row
+ \o \bold extraimages \target extraimages
+ \o \bold {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.\i{format} = \i
+ 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.
+
+ \row
+ \o \bold falsehoods \target falsehoods
+ \o \bold {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, \i unless the
+ preprocessor symbol is specified within the \c falsehoods
+ variable entry:
+
+ \code
+ falsehoods = NOTYET
+ \endcode
+
+ See also \l defines.
+
+ \row
+ \o \bold generateindex \target generateindex
+ \o \bold{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).
+ \row
+ \o \bold headerdirs \target headerdirs
+ \o \bold {The \c headerdirs variable specifies the directories
+ containing the header files associated with the \c .cpp source
+ files used in the documentation.}
+
+ For example:
+
+ \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}{\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 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.
+
+ \row
+ \o \bold headers \target headers
+ \o \bold {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.}
+
+ For example:
+
+ \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.
+
+ \row
+ \o \bold headers.fileextensions \target headers.fileextensions
+ \o \bold {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.
+
+ \row
+ \o \bold imagedirs \target imagedirs
+ \o \bold {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}{\\image} and \l
+ {inlineimage}{\\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, \i not in
+ subdirectories.
+
+ For example:
+
+ \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.
+
+ \row
+ \o \bold images \target images
+ \o \bold {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.}
+
+ For example:
+
+ \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.
+
+ \row
+ \o \bold images.fileextensions \target images.fileextensions
+ \o \bold {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.\i{format} = *.\i{extension}}.
+
+ The idea is to enable different image format for different
+ output format. For example:
+
+ \code
+ images.fileextensions.HTML = *.png
+ images.fileextensions.LOUT = *.eps
+ \endcode
+
+ Then, when processing the \l {image}{\\image} and \l
+ {inlineimage}{\\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.
+
+ \row
+ \o \bold language \target language
+ \o \bold {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++.
+
+ \row
+ \o \bold macro \target macro
+ \o \bold {The \c macro variable can be used to create your
+ own QDoc commands.}
+
+ The general syntax is \tt {macro.\i{command} =
+ "\i{definition}}". The definition can be described using
+ QDoc syntax. In addition it is possible to provide an HTML
+ definition by appending .HTML to the variable.
+
+ For example in \l qt.qdocconf:
+
+ \code
+ macro.gui = "\\bold"
+ macro.raisedaster.HTML = "<sup>*</sup>"
+ \endcode
+
+ makes sure that the \\gui command renders its argument using a
+ bold font, and that \\raisedaster renders a '*'.
+
+ \row
+ \o \bold outputdir \target outputdir
+ \o \bold {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.
+
+ \row
+ \o \bold outputformats \target outputformats
+ \o \bold {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.
+
+ \row
+ \o \bold qhp \target qhp
+ \o \bold{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.
+
+ \row
+ \o \bold slow \target slow
+ \o \bold {The \c slow variable specifies whether QDoc should do
+ time-consuming processing, such as syntax highlighting.}
+
+ By default, this setting is false.
+
+ Example:
+
+ \code
+ slow = true
+ \endcode
+
+ Another way to turn on "slowness" is to invoke QDoc with the
+ \c -slow command-line option.
+
+ \row
+ \o \bold sourcedirs \target sourcedirs
+ \o \bold {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}{\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 and \l sources.fileextensions.
+
+ \row
+ \o \bold sources \target sources
+ \o \bold {The \c sources variable allows you to specify
+ individual source files in addition to those located in the
+ directories specified by the \l {sourcedir}{\c sourcedir}
+ variable.}
+
+ For example:
+
+ \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}{\c
+ sourcedirs} variable. For more information, see the \l
+ {sourcedirs}{\c sourcedirs} variable.
+
+ See also \l sourcedirs.
+
+ \row
+ \o \bold sources.fileextensions \target sources.fileextensions
+ \o \bold {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 and \l sources.
+
+ \row
+ \o \bold spurious \target spurious
+ \o \bold {The \c spurious variable excludes specified
+ QDoc warnings from the output.}
+
+ The warnings are specified using standard wildcard
+ expressions. For example:
+
+ \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
+
+ \row
+ \o \bold tabsize \target tabsize
+ \o \bold {The \c tabsize variable defines the size of a tab
+ character.}
+
+ For example:
+
+ \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.
+
+ \row
+ \o \bold tagfile \target tagfile
+ \o \bold{The \c tagfile variable specifies the Doxygen tag file to be written
+ when HTML is generated.}
+ \row
+ \o \bold version \target version
+ \o \bold {The \c version variable specifies the version number of the
+ documented software.}
+
+ For example:
+
+ \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.
+
+ \row
+ \o \bold versionsym \target versionsym
+ \o \bold {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.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 {version}{\\version}.
+
+ \endtable
+*/
+
+/*!
+ \page 22-creating-help-project-files.html
+ \previouspage General Variables
+ \contentspage QDoc Manual - Table of Contents
+ \nextpage C++ Specific 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
+*/
+
+/*!
+ \page 23-qdoc-configuration-cppvariables.html
+ \previouspage Creating Help Project Files
+ \contentspage QDoc Manual - Table of Contents
+ \nextpage HTML Specific Variables
+
+ \title C++ Specific Variables
+
+ The C++ specific configuration variables are provided to avoid
+ erroneous documentation due to non-standard C++ constructs.
+
+ \section1 Alphabetical List
+
+ \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoredirectives}
+ {Cpp.ignoredirectives},
+ \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoretoken}
+ {Cpp.ignoretokens}
+
+ \section1 Variable Descriptions
+
+ \table
+
+ \header
+ \o Variable
+ \o Description
+
+ \row
+ \o \bold Cpp.ignoredirectives \target Cpp.ignoredirectives
+ \o \bold {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.
+
+ \row
+ \o \bold Cpp.ignoretokens \target Cpp.ignoretokens
+ \o \bold {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.
+
+ \endtable
+*/
+
+
+/*!
+ \page 24-qdoc-configuration-htmlvariables.html
+ \previouspage C++ Specific Variables
+ \contentspage QDoc Manual - Table of Contents
+ \nextpage Supporting Derived Projects
+
+ \title HTML Specific 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.
+
+ \section1 Alphabetical List
+
+ \l {24-qdoc-configuration-htmlvariables.html#HTML.footer}{HTML.footer},
+ \l {24-qdoc-configuration-htmlvariables.html#HTML.postheader}
+ {HTML.postheader},
+ \l {24-qdoc-configuration-htmlvariables.html#HTML.style}{HTML.style},
+ \l {24-qdoc-configuration-htmlvariables.html#HTML.stylesheets}{HTML.stylesheets}
+
+
+ \section1 Variable Descriptions
+
+ \table
+
+ \header
+ \o Variable
+ \o Description
+
+ \row
+ \o \bold HTML.footer \target HTML.footer
+ \o \bold {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}.
+
+ \row
+ \o \bold HTML.postheader \target HTML.postheader
+ \o \bold {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}.
+
+ \row
+ \o \bold HTML.style \target HTML.style
+ \o \bold {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}.
+
+ \row
+ \o \bold HTML.stylesheets \target HTML.stylesheets
+ \o \bold {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.
+ \endtable
+*/
+
+/*!
+ \page 25-qdoc-configuration-derivedprojects.html
+ \previouspage HTML Specific Variables
+ \contentspage QDoc Manual - Table of Contents
+ \nextpage QDoc Compatibility
+
+ \title Supporting Derived Projects
+
+ \tableofcontents
+
+ Some particular configuration variables allow you to use QDoc to
+ support Qt-based projects; i.e to make projects, such as Qt Solutions,
+ contain references 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.
+
+ \section1 The Configuration Variables
+
+ \section2 Alphabetical List
+
+ \l{25-qdoc-configuration-derivedprojects.html#description}{description},
+ \l{25-qdoc-configuration-derivedprojects.html#indexes}{indexes},
+ \l{25-qdoc-configuration-derivedprojects.html#project}{project},
+ \l{25-qdoc-configuration-derivedprojects.html#url}{url}
+
+ \section2 Variable Descriptions
+
+ \table
+ \header
+ \o Variable
+ \o Description
+ \row
+ \o \bold description \target description
+ \o \bold {The description variable holds a short description of
+ the associated project.}
+
+ See also \l project.
+
+ \row
+ \o \bold indexes \target indexes
+ \o \bold {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.
+
+ \row
+ \o \bold project \target project
+ \o \bold {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 \i index file. For example:
+
+ \code
+ project = QtMotif
+ \endcode
+
+ This will cause an index file called \c qtmotif.index to be
+ created.
+
+ See also \l description and \l indexes.
+ \row
+ \o \bold url \target url
+ \o \bold {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.
+
+ For example:
+
+ \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.
+
+ \endtable
+
+ \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 {QDoc Compatibility} 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 QDoc Manual - Table of Contents
+ \nextpage QDoc Commands - Alphabetical List
+
+ \title QDoc Compatibility
+
+ \tableofcontents
+
+ \section1 General Description
+
+ \target reason
+
+ QDoc is a tool that constantly evolves to suit our needs, for that
+ reason there are some compatibility issues in the transition
+ between old and new practices.
+
+ To make the transition as smooth and rapid as possible, the
+ general idea is to adopt the new commands and usage in new
+ documentation. While waiting for the occurrences of the old
+ practices to be eliminated from the old parts of the
+ documentation, you can map the new commands and usage to the old
+ ones using a compat.qdocconf file.
+
+ A compat.qdocconf file is a separate \c .qdocconf file which you
+ can include in your main configuration file. It typically contains
+ the mapping between old and new commands using the \l alias and \l
+ {22-qdoc-configuration-generalvariables.html#macro}{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}.
+
+ \section2 Qt's current compat.qdocconf file
+
+ \quotefile files/compat.qdocconf
+
+ \section2 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}{\\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}{\\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}{\\image} in new documentation}.
+
+ \endtable
+*/
+
+/*!
+ \page 27-qdoc-commmands-alphabetical.html
+ \previouspage QDoc Compatibility
+ \contentspage QDoc Manual - Table of Contents
+
+ \title QDoc Commands - Alphabetical List
+
+ \list
+
+ \o \l {04-qdoc-commands-textformatting.html#a}{\\a}
+ \o \l {11-qdoc-commands-documentcontents.html#abstract}{\\abstract}
+ \o \l {06-qdoc-commands-verbatimcode.html#badcode}{\\badcode}
+ \o \l {04-qdoc-commands-textformatting.html#bold}{\\bold}
+ \o \l {11-qdoc-commands-documentcontents.html#brief}{\\brief}
+ \o \l {04-qdoc-commands-textformatting.html#c}{\\c}
+ \o \l {09-qdoc-commands-graphic.html#caption}{\\caption}
+ \o \l {05-qdoc-commands-documentstructuring.html#chapter}{\\chapter}
+ \o \l {13-qdoc-commands-topical.html#class}{\\class}
+ \o \l {06-qdoc-commands-verbatimcode.html#code}{\\code}
+ \o \l {07-0-qdoc-commands-quoting.html#codeline}{\\codeline},
+ \o \l {16-qdoc-commands-status.html#compat}{\\compat}
+ \o \l {15-qdoc-commands-navigation.html#contentspage}{\\contentspage}
+ \o \l {07-0-qdoc-commands-quoting.html#dots}{\\dots}
+ \o \l {12-0-qdoc-commands-miscellaneous.html#else}{\\else}
+ \o \l {12-0-qdoc-commands-miscellaneous.html#endif}{\\endif}
+ \o \l {13-qdoc-commands-topical.html#enum}{\\enum}
+ \o \l {13-qdoc-commands-topical.html#example-command}{\\example}
+ \o \l {12-0-qdoc-commands-miscellaneous.html#expire}{\\expire}
+ \o \l {13-qdoc-commands-topical.html#externalpage}{\\externalpage}
+ \o \l {13-qdoc-commands-topical.html#fn}{\\fn}
+ \o \l {11-qdoc-commands-documentcontents.html#footnote}{\\footnote}
+ \o \l {12-0-qdoc-commands-miscellaneous.html#generatelist}{\\generatelist}
+ \o \l {13-qdoc-commands-topical.html#group}{\\group}
+ \o \l {10-qdoc-commands-container.html#header}{\\header}
+ \o \l {13-qdoc-commands-topical.html#headerfile}{\\headerfile}
+ \o \l {04-qdoc-commands-textformatting.html#i}{\\i}
+ \o \l {12-0-qdoc-commands-miscellaneous.html#if}{\\if}
+ \o \l {09-qdoc-commands-graphic.html#image}{\\image}
+ \o \l {12-0-qdoc-commands-miscellaneous.html#include}{\\include}
+ \o \l {15-qdoc-commands-navigation.html#indexpage}{\\indexpage}
+ \o \l {19-qdoc-commands-grouping.html#ingroup}{\\ingroup}
+ \o \l {19-qdoc-commands-grouping.html#inmodule}{\\inmodule}
+ \o \l {09-qdoc-commands-graphic.html#inlineimage}{\\inlineimage}
+ \o \l {16-qdoc-commands-status.html#internal}{\\internal}
+ \o \l {08-qdoc-commands-linking.html#keyword}{\\keyword}
+ \o \l {08-qdoc-commands-linking.html#l}{\\l}
+ \o \l {11-qdoc-commands-documentcontents.html#legalese}{\\legalese}
+ \o \l {10-qdoc-commands-container.html#list}{\\list}
+ \o \l {13-qdoc-commands-topical.html#macro}{\\macro}
+ \o \l {19-qdoc-commands-grouping.html#mainclass}{\\mainclass}
+ \o \l {12-0-qdoc-commands-miscellaneous.html#meta}{\\meta}
+ \o \l {13-qdoc-commands-topical.html#module}{\\module}
+ \o \l {13-qdoc-commands-topical.html#namespace}{\\namespace}
+ \o \l {15-qdoc-commands-navigation.html#nextpage}{\\nextpage}
+ \o \l {06-qdoc-commands-verbatimcode.html#newcode}{\\newcode}
+ \o \l {17-qdoc-commands-thread.html#nonreentrant}{\\nonreentrant}
+ \o \l {10-qdoc-commands-container.html#o}{\\o}
+ \o \l {16-qdoc-commands-status.html#obsolete}{\\obsolete}
+ \o \l {06-qdoc-commands-verbatimcode.html#oldcode}{\\oldcode}
+ \o \l {12-0-qdoc-commands-miscellaneous.html#omit}{\\omit}
+ \o \l {10-qdoc-commands-container.html#omitvalue}{\\omitvalue}
+ \o \l {18-qdoc-commands-relating.html#overload}{\\overload}
+ \o \l {13-qdoc-commands-topical.html#page}{\\page}
+ \o \l {05-qdoc-commands-documentstructuring.html#part}{\\part}
+ \o \l {16-qdoc-commands-status.html#preliminary}{\\preliminary}
+ \o \l {15-qdoc-commands-navigation.html#previouspage}{\\previouspage}
+ \o \l {07-0-qdoc-commands-quoting.html#printline}{\\printline}
+ \o \l {07-0-qdoc-commands-quoting.html#printto}{\\printto}
+ \o \l {07-0-qdoc-commands-quoting.html#printuntil}{\\printuntil}
+ \o \l {13-qdoc-commands-topical.html#property}{\\property}
+ \o \l {11-qdoc-commands-documentcontents.html#quotation}{\\quotation}
+ \o \l {07-0-qdoc-commands-quoting.html#quotefile}{\\quotefile}
+ \o \l {07-0-qdoc-commands-quoting.html#quotefromfile}{\\quotefromfile}
+ \o \l {12-0-qdoc-commands-miscellaneous.html#raw}{\\raw}
+ \o \l {17-qdoc-commands-thread.html#reentrant}{\\reentrant}
+ \o \l {18-qdoc-commands-relating.html#reimp}{\\reimp}
+ \o \l {18-qdoc-commands-relating.html#relates}{\\relates}
+ \o \l {10-qdoc-commands-container.html#row}{\\row}
+ \o \l {08-qdoc-commands-linking.html#sa}{\\sa}
+ \o \l {05-qdoc-commands-documentstructuring.html#sectionOne}{\\section1}
+ \o \l {05-qdoc-commands-documentstructuring.html#sectionTwo}{\\section2}
+ \o \l {05-qdoc-commands-documentstructuring.html#sectionThree}{\\section3}
+ \o \l {05-qdoc-commands-documentstructuring.html#sectionFour}{\\section4}
+ \o \l {13-qdoc-commands-topical.html#service}{\\service}
+ \o \l {16-qdoc-commands-status.html#since}{\\since}
+ \o \l {07-0-qdoc-commands-quoting.html#skipline}{\\skipline}
+ \o \l {07-0-qdoc-commands-quoting.html#skipto}{\\skipto}
+ \o \l {07-0-qdoc-commands-quoting.html#skipuntil}{\\skipuntil}
+ \o \l {07-0-qdoc-commands-quoting.html#snippet}{\\snippet},
+ \o \l {15-qdoc-commands-navigation.html#startpage}{\\startpage}
+ \o \l {04-qdoc-commands-textformatting.html#sub}{\\sub}
+ \o \l {20-qdoc-commands-title.html#subtitle}{\\subtitle}
+ \o \l {04-qdoc-commands-textformatting.html#sup}{\\sup}
+ \o \l {10-qdoc-commands-container.html#table}{\\table}
+ \o \l {11-qdoc-commands-documentcontents.html#tableofcontents}
+ {\\tableofcontents}
+ \o \l {08-qdoc-commands-linking.html#target}{\\target}
+ \o \l {17-qdoc-commands-thread.html#threadsafe}{\\threadsafe}
+ \o \l {20-qdoc-commands-title.html#title}{\\title}
+ \o \l {04-qdoc-commands-textformatting.html#tt}{\\tt}
+ \o \l {13-qdoc-commands-topical.html#typedef}{\\typedef}
+ \o \l {04-qdoc-commands-textformatting.html#underline}{\\underline}
+ \o \l {13-qdoc-commands-topical.html#variable}{\\variable}
+ \o \l {10-qdoc-commands-container.html#value}{\\value}
+ \o \l {11-qdoc-commands-documentcontents.html#warning}{\\warning}
+ \endlist
+*/
+
+/*!
+ \externalpage http://qt.nokia.com/about
+ \title About Qt
+*/