Qt Developer Guide
Qt is a cross-platform application and UI framework. Using Qt, you can write web-enabled applications once and deploy them across desktop, mobile and embedded operating systems without rewriting the source code.
| QDoc Syntax | Generated Documentation | |
|---|---|---|
| 1 | A variation of a command button is a \e menu button. | A variation of a command button is a menu button. |
| 2 | The QPushButton widget provides a \e {command button}. | The QPushButton widget provides a command button. |
| 3 | Another class of buttons are option buttons \e (see QRadioButton). | Another class of buttons are option buttons (see QRadioButton). |
| 4 | A push button emits the signal \e clicked(). | A push button emits the signal clicked(). |
| 5 | The \e QPushButton's checked property is false by default. | The QPushButton's checked property is false by default. |
This is the first part.
This is the first chapter's first section.
This is the first chapter's second section.
This is the first chapter's third section.
This is the first part's second chapter.
This is the second chapter's first section.
...This is the second part.
This is the second part's first chapter.
This is the first chapter's first section.
... \endraw \endquotation Each section is a logical unit in the document. The section heading appears in the automatically generated table of contents that normally appears in the upper righthand corner of the page. \target chapter-command \section1 \\chapter The \\chapter command is intended for use in larger documents, and divides the document into chapters. See \l{part} {\\part} for an explanation of the various section units, command argument and rendering. \target sectionOne-command \section1 \\section1 The \\section1 command starts a new section. See \l{part} {\\part} for an explanation of the various section units, command argument and rendering. \target sectionTwo-command \section1 \\section2 The \\section2 command starts a new section. See \l{part} {\\part} for an explanation of the various section units, command argument and rendering. \target sectionThree-command \section1 \\section3 The \\section3 command starts a new section. See \l{part} {\\part} for an explanation of the various section units, command argument and rendering. \target sectionFour-command \section1 \\section4 The \\section4 command starts a new section. See \l{part} {\\part} for an explanation of the various section units, command argument and rendering. */ /*! \page 06-qdoc-commands-includecodeinline.html \previouspage Document Structure \contentspage Table of Contents \nextpage Including External Code \title Including Code Inline The following commands are used to render source code without formatting. The source code begins on a new line, rendered in the code. \bold{Note:} Although all these commands are for rendering C++ code, the \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command} {\\snippet} and \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command} {\\codeline} commands are preferred over the others. These commands allow equivalent code snippets for other Qt language bindings to be substituted for the C++ snippets in the documentation. \target code-command \section1 \\code The \\code and \\endcode commands enclose a snippet of source code. \note The \l {c-command} {\\c} command can be used for short code fragments within a sentence. The \\code command is for longer code snippets. It renders the code verbatim in a separate paragraph in the code font. When processing any of the \\code, \l {badcode-command} {\\badcode}, \l {newcode-command} {\\newcode} or \l {oldcode-command} {\\oldcode} commands, QDoc removes all indentation that is common for the verbatim code blocks within a \c{/}\c{*!} ... \c{*}\c{/} comment before it adds the standard indentation. For that reason the recommended style is to use 8 spaces for the verbatim code contained within these commands \note This doesn't apply to externally quoted code using the \l {quotefromfile-command} {\\quotefromfile} or \l {quotefile-command} {\\quotefile} command. For example: \code / *! \code #include| Trolltech | Trolltech |
|---|---|
|
|
|
|
|
| Qt Core Feature | Brief Description |
|---|---|
| Signals and Slots | Signals and slots are used for communication between objects. |
| Layout Management | The Qt layout system provides a simple and powerful way of specifying the layout of child widgets. |
| Drag and Drop | Drag and drop provides a simple visual mechanism which users can use to transfer information between and within applications. |
| This header cell spans three columns but only one row | ||
|---|---|---|
| This table cell spans two columns but only one row | This table cell spans only one column, but two rows. | |
| A regular table cell | A regular table cell | |
| Qt Core Feature | Brief Description |
|---|---|
| Signals and Slots | Signals and slots are used for communication between objects. |
| Qt Core Feature | Brief Description |
|---|---|
| Signals and Slots | Signals and slots are used for communication between objects. |
| Layout Management | The Qt layout system provides a simple and powerful way of specifying the layout of child widgets. |
| Drag and Drop | Drag and drop provides a simple visual mechanism which users can use to transfer information between and within applications. |
| This header cell spans three columns but only one row | ||
|---|---|---|
| This table item spans two columns but only one row | This table item spans only one column, but two rows. | |
| A regular table item | A regular table item | |
} and \bold{} in the html output, e.g.: \code / *! While the prospect of a significantly broader market is good news for Firstlogic, the notion also posed some challenges. Dave Dobson, director of technology for the La Crosse, Wisconsin-based company, said: \quotation As our solutions were being adopted into new environments, we saw an escalating need for easier integration with a wider range of enterprise applications. \endquotation * / \endcode The text in the \bold{\\quotation} block will appear in the generated HTML as: \code
\endcode The built-in style sheet for most browsers will render the contents of theAs our solutions were being adopted into new environments, we saw an escalating need for easier integration with a wider range of enterprise applications.
tag with left and right indentations. The example above would be rendered as: \quotation As our solutions were being adopted into new environments, we saw an escalating need for easier integration with a wider range of enterprise applications. \endquotation But you can redefine the \bold{} tag in your style.css file. This command replaces the old \\quote command. For more information see the \l {26-qdoc-commands-compatibility.html#quotation-versus-quote} {compatibility} section. \target footnote-command \section1 \\footnote The \\footnote and \\endfootnote commands delimit a footnote. The footnote is rendered at the bottom of the page. \warning The \bold{\\footnote} and \bold{\\endfootnote} commands have not been implemented. The footnote is rendered as a regular HTML paragraph. \target tableofcontents-command \section1 \\tableofcontents The \\tableofcontents command has been disabled because QDoc now generates a table of contents automatically. The automatically generated table of contents appears in the upper righthand corner of the page. \target brief-command \section1 \\brief The \\brief command introduces a one-sentence description of a class, namespace, header file, property or variable. The brief text is used to introduce the documentation of the associated object, and in lists generated using the \l {generatelist-command} {\\generatelist} command. The \\brief command can be used in two significant different ways: \l {brief class} {One for classes, namespaces and header files}, and \l {brief-property} {one for properties and variables}. \target brief-property When the \\brief command is used to describe a property or a variable, the brief text must be a sentence fragment starting with "whether" (for a boolean property or variable) or starting with "the" (for any other property or variable). For example the boolean QWidget::isWindow property: \code / *! \property QWidget::isActiveWindow \brief whether this widget's window is the active window The active window is the window that contains the widget that has keyboard focus. When popup windows are visible, this property is true for both the active window \e and for the popup. \sa activateWindow(), QApplication::activeWindow() * / \endcode and the QWidget::geometry property \code / *! \property QWidget::geometry \brief the geometry of the widget relative to its parent and excluding the window frame When changing the geometry, the widget, if visible, receives a move event (moveEvent()) and/or a resize event (resizeEvent()) immediately. ... \sa frameGeometry(), rect(), ... * / \endcode QDoc renders this as: \quotation \raw HTMLgeometry : QRect
\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 Theclass is|provides|contains|specifies... \endcode \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 QDoc renders this as: \quotation \raw HTML PreviewWindow Class Reference
\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 HTMLProperties
\endraw \list \o 52 properties inherited from QWidget \o 1 property inherited from QObject \endlist \raw HTMLPublic Functions
\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 HTMLPublic Slots
\endraw \list \o 17 public slots inherited from QWidget \o 1 public slot inherited from QObject \endlist \raw HTMLAdditional Inherited Members
\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
Detailed Description
\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
Member Function Documentation
\endraw \target constructor \raw HTMLPreviewWindow(QWidget *parent = 0)
\endraw Constructs a preview window widget with \e parent. \target function \raw HTMLsetWindowFlags(Qt::WindowFlags flags)
\endraw Sets the widgets flags using the QWidget::setWindowFlags() function. Then runs through the available window flags, creating a text that contains the names of the flags that matches the flags parameter, displaying the text in the widgets text editor. \endquotation Using \\brief in a \l{namespace-command}{\\namespace}: \code / *! \namespace Qt \brief The Qt namespace contains miscellaneous identifiers used throughout the Qt library. * / \endcode Using \\brief in a \l{headerfile-command}{\\headerfile}: \code / *! \headerfile\title Global Qt Declarations \brief The header file provides basic declarations and is included by all other Qt headers. \sa * / \endcode See also \l{property-command} {\\property}, \l{class-command} {\\class}, \l{namespace-command} {\\namespace} and \l{headerfile-command} {\\headerfile}. \target legalese-command \section1 \\legalese The \\legalese and \\endlegalese commands delimit a licence agreement. In the generated HTML, the delimited text is surrounded by a \bold { } and \bold {} tags. For example, here is a license agreement enclosed in \\legalese and \\endlegalese: \code / *! \legalese Copyright 1996 Daniel Dardailler. Permission to use, copy, modify, distribute, and sell this software for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of Daniel Dardailler not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. Daniel Dardailler makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. Modifications Copyright 1999 Matt Koss, under the same license as above. \endlegalese * / \endcode It will appear in the generated HTML as: \code\endcode If the \\endlegalese command is omitted, QDoc will process the \\legalese command but considers the rest of the documentation page as the license agreement. Ideally, the license text is located with the licensed code. Elsewhere, the documentation identified as \e{\\legalese} command can be accumulated using \l {generatelist-command} {\\generatelist} with \c {legalese-command} as the argument. This is useful for generating an overview of the license agreements associated with the source code. \target warning-command \section1 \\warning The \\warning command prepends "Warning:" to the command's argument, in bold font. 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 QDoc renders this as: \quotation Qt::HANDLE is a platform-specific handle type for system objects. This is equivalent to \c{void *} on Windows and Mac OS X, and to \c{unsigned long} on X11. \warning Using this type is not portable. \endquotation */ /*! \page 12-0-qdoc-commands-miscellaneous.html \previouspage Special Content \contentspage Table of Contents \nextpage The QDoc Configuration File \title Miscellaneous These commands provide miscellaneous functions connected to the visual appearance of the documentation, and to the process of generating the documentation. \target expire-command \section1 \\expire The \\expire command allows you to define an expiration date for your documentation. When using the \\expire command, QDoc will emit a warning when the current date is larger than the specified date. The command accepts one argument; the argument's format is yyyy-mm-dd. For example: \code / *! \page porting.html \title Porting to Qt 3.x \expire 2004-12-31 This document describes porting applications from Qt 2.x to Qt 3.x. The Qt 3.x series is not binary compatible with the 2.x series. ... * / \endcode If you run QDoc on 4 July 2005, it will emit the warning \quotation porting.qdoc:6: Documentation expired 185 days ago \endquotation \target generatelist-command \section1 \\generatelist The \\generatelist command expands to a list of various documentation or links to documentation. Below is an example from the Qt Reference Documentation: \code / *! \page classes.html \title All Classes For a shorter list that only includes the most frequently used classes, see \l{Qt's Main Classes}. For a list of Qt 3 support classes, see \l{Qt3Support Classes}. \generatelist classes * / \endcode This generates the \l {All Classes} page. The command accepts the following arguments: \target table example \section2 \c annotatedclasses The \c annotatedclasses argument provides a table containing the names of all the classes, and a description of each class. Each class name is a link to the class's reference documentation. For example: \table \row \o QDial \o Rounded range control (like a speedometer or potentiometer) \row \o QDialog \o The base class of dialog windows \row \o QDir \o Access to directory structures and their contents \endtable A C++ class is documented with the \l {class-command} {\\class} command. The annotation for the class is taken from the argument of the class comment's \l {brief-command} {\\brief} command. \target list example \section2 \c classes The \c classes argument provides a complete alphabetical list of the classes. Each class name is a link to the class's reference documentation. This command is uded to generate the \l {classes.html} {All Classes} page this way: \code / *! \page classes.html \title All Classes \ingroup classlists \brief If you know the name of the class you want, find it here. This is a list of all Qt classes. For a list of the classes provided for compatibility with Qt3, see \l{Qt3 Support Classes}. For classes that have been deprecated, see the \l{Obsolete Classes} list. \generatelist classes * / \endcode A C++ class is documented with the \l {class-command} {\\class} command. \section2 \c classesbymodule When this argument is used, a second argument is required, which specifies the module whose classes are to be listed. QDoc generates a table containing those classes. Each class is listed with the text of its \l{brief-command} {\\brief} command. This command is used to generate the \l {phonon-module.html} {Phonon Module} page this way. \code / *! \page phonon-module.html \module Phonon \title Phonon Module \ingroup modules \brief The Phonon module contains namespaces and classes for multimedia functionality. \generatelist{classesbymodule Phonon} ... * / \endcode Each class that is a member of the specified module must be marked with the \l {inmodule-command} {\\inmodule} command in its \\class comment. \section2 \c compatclasses The \c compatclasses argument generates a list in alphabetical order of the support classes. It is normally used only to generate the \l {compatclasses.html} {Qt3 Support Classes} page this way: \code / *! \page compatclasses.html \title Qt3 Support Classes \ingroup classlists \brief These classes ease the porting of code from Qt 3 to Qt 4. These are the classes that Qt provides for compatibility with Qt 3. Most of these are provided by the Qt3Support module. \generatelist compatclasses * / \endcode A support class is identified in the \\class comment with the \l {compat-command} {\\compat} command. \section2 \c functionindex The \c functionindex argument provides a complete alphabetical list of all the documented member functions. It is normally used only to generate the \l {functions.html} {Qt function index} page this way: \code / *! \page functions.html \title All Functions \ingroup funclists \brief All documented Qt functions listed alphabetically with a link to where each one is declared. This is the list of all documented member functions and global functions in the Qt API. Each function has a link to the class or header file where it is declared and documented. \generatelist functionindex * / \endcode \section2 \c legalese The \c legalese argument tells QDoc to generate a complete list of licenses in the documentation. Each license is identified using the \l {legalese-command} {\\legalese} command. This command is used to generate the \l {licenses.html} {Qt license information} page this way: \code / *! \page licenses.html \title Other Licenses Used in Qt \ingroup licensing \brief Information about other licenses used for Qt components and third-party code. Qt contains some code that is not provided under the \l{GNU General Public License (GPL)}, \l{GNU Lesser General Public License (LGPL)} or the \l{Qt Commercial Edition}{Qt Commercial License Agreement}, but rather under specific licenses from the original authors. Some pieces of code were developed by Nokia and others originated from third parties. This page lists the licenses used, names the authors, and links to the places where it is used. Nokia gratefully acknowledges these and other contributions to Qt. We recommend that programs that use Qt also acknowledge these contributions, and quote these license statements in an appendix to the documentation. See also: \l{Licenses for Fonts Used in Qt for Embedded Linux} \generatelist legalese * / \endcode \section2 \c mainclasses The \c mainclasses argument tells QDoc to generate an alphabetical list of the main classes. A class is marked as a main class by including a \l {mainclass-command} {\\mainclass} command in the \\class comment. \note The Qt documentation no longer includes a main classes page, but you can generate one for your main classes if you want it. \section2 \c overviews The \c overviews argument is used to tell QDoc to generate a list by concatenating the contents of all the \l {group-command} {\\group} pages. Qt uses it to generate the \l {overviews.html} {overviews} page this way: \code / *! \page overviews.html \title All Overviews and HOWTOs \generatelist overviews * / \endcode \section2 \c related The \c related argument is used in combination with the \l {group-command} {\\group} and \l {ingroup-command} {\\ingroup} commands to list all the overviews related to a specified group. For example, the page for the \l {Programming with Qt} {Programming with Qt} page is generated this way: \code / *! \group qt-basic-concepts \title Programming with Qt \brief The basic architecture of the Qt cross-platform application and UI framework. Qt is a cross-platform application and UI framework for writing web-enabled applications for desktop, mobile, and embedded operating systems. This page contains links to articles and overviews explaining key components and techniuqes used in Qt development. \generatelist {related} * / \endcode Each page listed on this group page contains the command: \code \ingroup qt-basic-concepts \endcode \section2 \c service The \c service argument tells QDoc to generate an alphabetical list of the services. Each service name is a link to the service's reference documentation. A service is identified with the \l {service-command} {\\service} command. \note This command and the \l {service-command} {\\service} command are not used in the Qt documentation. \target if-command \section1 \\if The \\if command and the corresponding \\endif command enclose parts of a QDoc comment that only will be included if the condition specified by the command's argument is true. The command reads the rest of the line and parses it as an C++ #if statement. 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 {defines-variable} {defines} variable in the configuration file to make QDoc process the code within #ifdef and #endif: \code defines = opensourceedition \endcode You can also define the preprocessor symbol manually on the command line. For more information see the documentation of the \l {defines-variable} {defines} variable. See also \l{endif-command} {\\endif}, \l{else-command} {\\else}, \l {defines-variable} {defines} and \l {falsehoods-variable} {falsehoods}. \target endif-command \section1 \\endif The \\endif command and the corresponding \\if command enclose parts of a QDoc comment that will be included if the condition specified by the \l {if-command} {\\if} command's argument is true. For more information, see the documentation of the \l {if-command} {\\if} command. See also \l{if-command} {\\if}, \l{else-command} {\\else}, \l {defines-variable} {defines} and \l {falsehoods-variable} {falsehoods}. \target else-command \section1 \\else The \\else command specifies an alternative if the condition in the \l {if-command} {\\if} command is false. The \\else command can only be used within \l {if-command} {\\if...\\endif} commands, but is useful when there is only two alternatives. 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 like this: \quotation The Qt 3 support library is provided to keep old source code working. In addition to the Qt3Support classes, Qt 4 provides compatibility functions when it's possible for an old API to cohabit with the new one. \endquotation If \c QT3_SUPPORT is not defined but \c QT3_SUPPORT_WARNINGS is defined, the comment will be rendered like this: \quotation The Qt 3 support library is provided to keep old source code working. In addition to the Qt3Support classes, Qt 4 provides compatibility functions when it's possible for an old API to cohabit with the new one. The compiler emits a warning when a compatibility function is called. (This works only with GCC 3.2+ and MSVC 7.) \endquotation If none of the symbols are defined, the comment will be rendered as \quotation The Qt 3 support library is provided to keep old source code working. In addition to the \c Qt3Support classes, Qt 4 provides compatibility functions when it's possible for an old API to cohabit with the new one. To use the Qt 3 support library, you need to have the line QT += qt3support in your .pro file (qmake automatically define the QT3_SUPPORT symbol, turning on compatibility function support). You can also define the symbol manually (e.g., if you don't want to link against the \c Qt3Support library), or you can define \c QT3_SUPPORT_WARNINGS instead, telling the compiler to emit a warning when a compatibility function is called. (This works only with GCC 3.2+ and MSVC 7.) \endquotation See also \l{if-command} {\\if}, \l{endif-command} {\\endif}, \l {defines-variable} {defines} and \l {falsehoods-variable} {falsehoods}. \target include-command \section1 \\include The \\include command 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 QDoc renders this as: \quotation \raw HTMLCopyright 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.
Core Features
\endraw \input examples/signalandslots.qdocinc \input examples/objectmodel.qdocinc \input examples/layoutmanagement.qdocinc \endquotation Here is the actual \c .qdocinc files: \l signalandslots.qdocinc, \l objectmodel.qdocinc, \l layoutmanagement.qdocinc \target meta-command \section1 \\meta 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 \e name variable, and the second argument (the rest of the line) is equivalent to the tag's \e 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 QDoc renders this as: \code ... ... \endcode \target omit-command \section1 \\omit The \\omit command and the correspondning \\endomit command delimit parts of the documentation that you want QDoc to skip. For example: \code / *! \table \row \o Basic Widgets \o Basic GUI widgets such as buttons, comboboxes and scrollbars. \omit \row \o Component Model \o Interfaces and helper classes for the Qt Component Model. \endomit \row \o Database Classes \o Database related classes, e.g. for SQL databases. \endtable * / \endcode QDoc renders this as: \raw HTML\endraw \target raw-command \section1 \\raw \span {class="newStuff"} {(avoid)} The \\raw command and the corresponding \\endraw command delimit a block of raw mark-up language code. \note Avoid using this command if possible, because it generates DITA XML code that causes problems. If you are trying to generate special table or list behavior, try to get the behavior you want using the \l {span-command} {\\span} and \l {div-command} {\\div} commands in your \l {table-command} {\\table} or \l {list-command} {\\list}. The command takes an argument specifying the code's format; currently the only supported format is HTML. The \\raw command is useful if you want some special HTML effects in your documentation. For example: \code / *! Qt has some predefined QColor objects. For example: \raw HTML
Basic Widgets Basic GUI widgets such as buttons, comboboxes and scrollbars. Database Classes Database related classes, e.g. for SQL databases. Blue(#0000ff), dark blue(#000080) and cyan(#00ffff).
\endraw * / \endcode QDoc renders this as: \quotation Qt has some predefined QColor objects. For example: \raw HTMLBlue(#0000ff), dark blue(#000080) and cyan(#00ffff).
\endraw \endquotation \note But you can achieve the exact same thing using qdoc commands. In this case, all you have to do is include the color styles in your style.css file. Then you can write: \code \tt {\span {id="color-blue"} {Blue(#0000ff)}}, \tt {\span {id="color-darkBlue"} {dark blue(#000080)}} and \tt {\span {id="color-cyan"} {cyan(#00ffff)}}. \endcode ...which is rendered again as: \tt {\span {id="color-blue"} {Blue(#0000ff)}}, \tt {\span {id="color-darkBlue"} {dark blue(#000080)}} and \tt {\span {id="color-cyan"} {cyan(#00ffff)}}. \target unicode-command \section1 \\unicode The \\unicode command allows you to insert an arbitrary Unicode character in the document. The command takes an argument specifying the character as an integer. By default, base 10 is assumed, unless a '0x' or '0' prefix is specified (for base 16 and 8, respectively). For example: \code O G\unicode{0xEA}nio e as Rosas \unicode 0xC0 table en famille avec 15 \unicode 0x20AC par jour \unicode 0x3A3 \e{a}\sub{\e{i}} \endcode QDoc renders this as: \quotation O G\unicode{0xEA}nio e as Rosas \unicode 0xC0 table en famille avec 15 \unicode 0x20AC par jour \unicode 0x3A3 \e{a}\sub{\e{i}} \endquotation */ /*! \page 12-1-signalandslots.html \previouspage Miscellaneous \contentspage Table of Contents \title signalandslots.qdocinc \quotefile examples/signalandslots.qdocinc */ /*! \page 12-2-objectmodel.html \previouspage Miscellaneous \contentspage Table of Contents \title objectmodel.qdocinc \quotefile examples/objectmodel.qdocinc */ /*! \page 12-3-layoutmanagement.html \previouspage Miscellaneous \contentspage Table of Contents \title layoutmanagement.qdocinc \quotefile examples/layoutmanagement.qdocinc */ /*! \page 13-qdoc-commands-topics.html \previouspage The QDoc Commands \contentspage Table of Contents \nextpage Context Commands \title Topic Commands A topic command tells QDoc which source code element is being documented. Some topic commands allow you to create documentation pages that aren't tied to any underlying source code element. \section1 General Description When QDoc processes a QDoc comment, it tries to connect the comment to an element in the source code by first looking for a topic command that names the source code element. If there is no topic command, QDoc tries to connect the comment to the source code element that immediately follows the comment. If it can't do either of these and if there is no topic command that indicates the comment does not have an underlying source code element (e.g. \l{page-command} {\\page}), then the comment is discarded. \target topic argument The name of the thing being documented is the unique argument for each topic command. The naming convention is to use the complete name. For example: \code \enum QComboBox::InsertPolicy \endcode The \l {fn-command} {\\fn} command is a special case. For the \l {fn-command} {\\fn} command, use the function's signature including the class qualifier. For example: \code \fn void QGraphicsWidget::setWindowFlags(Qt::WindowFlags wFlags) \endcode A topic command can appear anywhere in a comment but must stand alone on its own line. Best practice is to put the topic commend at the top of the comment. If the argument spans several lines, make sure that each line (except the last one) is ended with a backslash. In addition QDoc counts parentheses, which means that if it encounters a '(' it considers everything until the closing ')' as its argument. If a topic command is repeated with different arguments, the same documentation will appear for both the units. 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. \target class-command \section1 \\class The \\class command is for documenting a C++ class. The argument is the complete name of the class. The command tells QDoc that a class is part of the public API, and lets you enter a detailed description. \code / *! \class QMap::iterator \brief The QMap::iterator class provides an STL-style non-const iterator for QMap and QMultiMap. QMap features both \l{STL-style iterators} and \l{Java-style iterators}. The STL-style iterators ... * / \endcode The HTML documentation for the named class is written to a \c{.html} file named from the class name, in lower case, and with the double colon qulifier(s) replaced with '-'. For example, the documentation for the \c QMap::Iterator class is written to \c qmap-iterator.html. \target framework The file contains the class description from the \\class comment, plus the documentation generated from QDoc comments for all the class members, i.e. a list of the class's types, properties, functions, signals, and slots. In addition to the detailed description of the class, the \\class comment typically contains a \l {brief-command} {\\brief} command and one or more \l{Markup Commands}. See the \\class command for any of the Qt class for examples. Here is a very simple example: \code / *! \class PreviewWindow \brief The PreviewWindow class is a custom widget displaying the names of its currently set window flags in a read-only text editor. \ingroup miscellaneous The PreviewWindow class inherits QWidget. The widget displays the names of its window flags set with the \l {function} {setWindowFlags()} function. It is also provided with a QPushButton that closes the window. ... \sa QWidget * / \endcode The way QDoc renders this \\class will depend a lot on your \c {style.css} file, but the general outline of the class reference page will look like this: \quotation \raw HTMLPreviewWindow Class Reference
\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 HTMLProperties
\endraw \list \o 52 properties inherited from QWidget \o 1 property inherited from QObject \endlist \raw HTMLPublic Functions
\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 HTMLPublic Slots
\endraw \list \o 17 public slots inherited from QWidget \o 1 public slot inherited from QObject \endlist \raw HTMLAdditional Inherited Members
\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
Detailed Description
\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
Member Function Documentation
\endraw \target constructor \raw HTMLPreviewWindow(QWidget *parent = 0)
\endraw Constructs a preview window widget with \e parent. \target function \raw HTMLsetWindowFlags(Qt::WindowFlags flags)
\endraw Sets the widgets flags using the QWidget::setWindowFlags() function. Then runs through the available window flags, creating a text that contains the names of the flags that matches the flags parameter, displaying the text in the widgets text editor. \endquotation \target enum-command \section1 \\enum The \\enum command is for documenting a C++ enum type. The argument is the full name of the enum type. The enum values are documented in the \\enum comment using the \l {value-command} {\\value} command. If an enum value is not documented with \\value, QDoc emits a warning. These warnings can be avoided using the \l {omitvalue-command} {\\omitvalue} command to tell QDoc that an enum value should not be documented. The enum documentation will be included on the class reference page, header file page, or namespace page where the enum type is defined. For example, consider the enum type \c {Corner} in the Qt namespace: \code enum Corner { TopLeftCorner = 0x00000, TopRightCorner = 0x00001, BottomLeftCorner = 0x00002, BottomRightCorner = 0x00003 #if defined(QT3_SUPPORT) && !defined(Q_MOC_RUN) ,TopLeft = TopLeftCorner, TopRight = TopRightCorner, BottomLeft = BottomLeftCorner, BottomRight = BottomRightCorner #endif }; \endcode This enum can be cocumented this way: \code / *! \enum Qt::Corner This enum type specifies a corner in a rectangle: \value TopLeftCorner The top-left corner of the rectangle. \value TopRightCorner The top-right corner of the rectangle. \value BottomLeftCorner The bottom-left corner of the rectangle. \value BottomRightCorner The bottom-right corner of the rectangle. \omitvalue TopLeft \omitvalue TopRight \omitvalue BottomLeft \omitvalue BottomRight * / \endcode Note the inclusion of the namespace qualifier. QDoc will render this enum type in \c {qt.html} like this: \quotation \raw HTMLenum Qt::Corner
This enum type specifies a corner in a rectangle:
\endraw \endquotation See also \l {value-command} {\\value} and \l {omitvalue-command} {\\omitvalue}. \target example-command \section1 \\example The \\example command is for documenting an example. The argument is the example's path relative to omne of the paths listed in the \l {exampledirs-variable} {exampledirs} variable in the QDoc configuration file. The documentation page will be output to \c {path-to-example}.html. QDoc will add a list of all the example's source files at the top of the page. For example, if \l {exampledirs-variable} {exampledirs} contains \c $QTDIR/examples/widgets/imageviewer, then \code / *! \example widgets/imageviewer \title ImageViewer Example \subtitle The example shows how to combine QLabel and QScrollArea to display an image. ... * / \endcode QDoc renders this example in widgets-imageviewer.html: \quotation \raw HTML
Constant Value Description Qt::TopLeftCorner 0x00000 The top-left corner of the rectangle. Qt::TopRightCorner 0x00001 The top-right corner of the rectangle. Qt::BottomLeftCorner 0x00002 The bottom-left corner of the rectangle. Qt::BottomRightCorner 0x00003 The bottom-right corner of the rectangle. \endraw Files: \list \o \l{http://qt.nokia.com/doc/4.0/widgets-imageviewer-imageviewer-cpp.html} {widgets/imageviewer/imageviewer.cpp} \o \l{http://qt.nokia.com/doc/4.0/widgets-imageviewer-imageviewer-h.html} {widgets/imageviewer/imageviewer.h} \o \l{http://qt.nokia.com/doc/4.0/widgets-imageviewer-main-cpp.html} {widgets/imageviewer/main.cpp} \endlist The example shows how to combine QLabel and QScrollArea to display an image. ... \endquotation \target fn-command \section1 \\fn (function) The \\fn command is for documenting a function. The argument is the function's signature, including its return type, const-ness, and list of formal arguments with types. If the named function doesn't exist, QDoc emits a warning. \note The \\fn command is QDoc's default command, i.e. when no topic command can be found in a QDoc comment, QDoc tries to tie the documentation to the following code as if it is the documentation for a function. Hence, it is normally not necessary to include this command when documenting a function, if the function's QDoc comment is written immediately above the function implementation in the \c .cpp file. But it must be present when documenting an inline function in the \c .cpp file that is implemented in the \c .h file. 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 QDoc renders this as: \quotation \raw HTML Image Viewer Example
bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const
\endraw Returns true if this toolbar is dockable in the given \a area; otherwise returns false. \endquotation See also \l {overload-command} {\\overload}. \target group-command \section1 \\group The \\group command creates a separate page that lists the classes belonging to the group. The argument is the group name. A class is included in a group by using the \l {ingroup-command} {\\ingroup} command. Overview pages can also be related to a group using the same command, but the list of overview pages must be requested explicitly using the \l {generatelist-command} {\\generatelist} command (see example below). The \\group command is typically followed by a \l {title-command} {\\title} command and a short introduction to the group. The HTML page for the group is written to a \c {.html} file put in\e{group}.html. Each class name is listed as a link to the class reference page followed by the text from the class's \l {brief-command} {\\brief} texts. 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 QDoc generates a group page in \c{io.html} that will look like this: \quotation \raw HTML 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.
\endraw \endquotation Note that overview pages related to the group, must be listed explicitly using the \l {generatelist-command} {\\generatelist} command with the \c related argument. 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-command} {\\ingroup} and \l {generatelist-command} {\\generatelist}. \target headerfile-command \section1 \\headerfile The \\headerfile command is for documenting the global functions, types and macros that are declared in a header file but not in a namespace. The argument is the name of the header file. The HTML page is written to a \c {.html} file constructed from the header file aregument. The documentation for a function, type, or macro that is declared in the header file being documented is included in the header file page using the \l {relates-command} {\\relates} command. If the argument doesn't exist as a header file, the \\headerfile command creates a documentation page for the header file anyway. For example: \code / *! \headerfile
QAbstractSocket The base functionality common to all socket types QBuffer QIODevice interface for a QByteArray QClipboard Access to the window system clipboard \title Generic Algorithms \brief The header file provides generic template-based algorithms. Qt provides a number of global template functions in \c that work on containers and perform well-know algorithms. * / \endcode QDoc generates a header file page \c{qtalgorithms.html} that looks like this: \quotation \raw HTML <QtAlgorithms> - Generic Algorithms
The
header file provides generic template-based algorithms. More... Functions
- RandomAccessIterator qBinaryFind (RandomAccessIterator begin, RandomAccessIterator end, const T & value)
- ...
\endraw \target header \raw HTMLDetailed Description
The
\endraw Qt provides a number of global template functions in \cheader file provides generic template-based algorithms. that work on containers and perform well-know algorithms. ... \endquotation \target macro-command \section1 \\macro The \\macro command is for documententin a C++ macro. The argument is the macro in one of three styles: function-like macros like Q_ASSERT(), declaration-style macros like Q_PROPERTY(), and macros without parentheses like Q_OBJECT. The \\macro comment must contain a \l {relates-command} {\\relates} command that attaches the macro comment to a class, header file, or namespace. Otherwise, the documentation will be lost. Here are three example macro comments followed by what they might look like in \c {qtglobal.html} or \c {qobject.html}: \code / *! \macro void Q_ASSERT(bool test) \relates Prints a warning message containing the source code file name and line number if \a test is false. ... \sa Q_ASSERT_X(), qFatal(), {Debugging Techniques} * / \endcode \quotation \raw HTML void Q_ASSERT ( bool test )
\endraw Prints a warning message containing the source code file name and line number if \a test is false. ... See also Q_ASSERT_X(), qFatal() and \l {Debugging Techniques}. \endquotation \code / *! \macro Q_PROPERTY(...) \relates QObject This macro declares a QObject property. The syntax is: ... \sa {Qt's Property System} * / \endcode \quotation \raw HTMLQ_PROPERTY ( ... )
\endraw This macro declares a QObject property. The syntax is: ... See also \l {Qt's Property System}. \endquotation \code / *! \macro Q_OBJECT \relates QObject The Q_OBJECT macro must appear in the private section of a class definition that declares its own signals and slots or that uses other services provided by Qt's meta-object system. ... \sa {Meta-Object System}, {Signals and Slots}, {Qt's Property System} * / \endcode \quotation \raw HTMLQ_OBJECT
\endraw The Q_OBJECT macro must appear in the private section of a class definition that declares its own signals and slots or that uses other services provided by Qt's meta-object system. ... See also \l {Meta-Object System}, \l {Signals & Slots} and \l {Qt's Property System}. \endquotation \target module-command \section1 \\module The \\module creates a page that lists the classes belonging to the module specified by the command's argument. A class included in the module by including the \l {inmodule-command} {\\inmodule} command in the \\class comment. The \\module command is typically followed by a \l {title-command} {\\title} and a \l {brief-command} {\\brief} command. Each class is listed as a link to the class reference page followed by the text from the class's \l {brief-command} {\\brief} command. For example: \code / *! \module QtNetwork \title QtNetwork Module \brief The QtNetwork module offers classes that allow you to write TCP/IP clients and servers. The network module provides classes to make network programming easier and portable. It offers both high-level classes such as QHttp and QFtp that implement specific application-level protocols, and lower-level classes such as QTcpSocket, QTcpServer, and QUdpSocket. * / \endcode QDoc renders this in \c {qtnetwork.html} like this: \quotation \raw HTML\endraw The QtNetwork module offers classes that allow you to write TCP/IP clients and servers.\l {module details} {More...} \raw HTML
QtNetwork Module
QAbstractSocket The base functionality common to all socket types QFtp Implementation of the FTP protocol ... ...
\endraw \target module details \raw HTMLDetailed Description
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.
\endraw ... \endquotation See also \l {inmodule-command} {\\inmodule} \target namespace-command \section1 \\namespace The \\namespace command is for documenting the contents of the C++ namespace named as its argument. The documentation outline QDoc generates for a namespace is similar to the outline it generates for a C++ class. For example: \code / *! \namespace Qt \brief The Qt namespace contains miscellaneous identifiers used throughout the Qt library. * / \endcode QDoc renders this in \c{qt.html} like this: \quotation \raw HTMLQt Namespace Reference
The Qt namespace contains miscellaneous identifiers used throughout the Qt library. More...
#include <Qt>Types
- flags Alignment
- ...
\endraw \target name \raw HTMLDetailed Description
The Qt namespace contains miscellaneous identifiers used throughout the Qt library.
\endraw ... \endquotation \target page-command \section1 \\page The \\page command is for creating a stand-alone documentation page. The argument is the name of the file where QDoc should store the page. The page title is set using the \l {title-command} {\\title} command. 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 QDoc renders this page in \c {aboutqt.html}. \target externalpage-command \section1 \\externalpage The \\externalpage command assigns a title to an external URL. For example: \code / *! \externalpage http://doc.trolltech.com/4.3/qtopiacore.html \title Qtopia Core * / \endcode This allows you to include a link to the external page in your documentation this way: \code / *! The broad scope of the \l {Qtopia Core} API enables it to be used across a wide variety of development projects. * / \endcode QDoc renders this as: \quotation The broad scope of the \l {http://doc.trolltech.com/4.3/qtopiacore.html} {Qtopia Core} API enables it to be used across a wide variety of development projects. \endquotation To achieve the same result without using the \\externalpage command, you would have to hard code the adress into your documentation: \code / *! The broad scope of the \l {http://doc.trolltech.com/4.3/qtopiacore.html} {Qtopia Core} API enables it to be used across a wide variety of development projects. * / \endcode The \\externalpage command makes it easier to maintain the documentation. If the adress changes, you only need to change the argument of the \\externalpage command. \target property-command \section1 \\property The \\property command is for documenting a Qt property. The argument is the full property name. A property is defined using the Q_PROPERTY() macro. The macro takes as arguments the property's name and its set, reset and get functions. 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 comment typically includes a \l {brief-command} {\\brief} command. Forproperties the \l {brief-command} {\\brief} command's argument is a sentence fragment that will be included in a one line description of the property. The command follows the same rules for the \l {brief-property} {description} as the \l {variable-command} {\\variable} command. For example: \code / *! \property QPushButton::flat \brief whether the border is disabled This property's default is false. * / \endcode QDoc includes this in \c {qpushbutton.html} like this: \quotation \raw HTMLflat : bool
\endraw This property holds whether the border is disabled. This property's default is false. Access functions: \list \o \bold { bool isFlat () const} \o \bold { void setFlat ( bool )} \endlist \endquotation \code / *! \property QWidget::width \brief the width of the widget excluding any window frame See the \l {Window Geometry} documentation for an overview of window geometry. \sa geometry, height, size * / \endcode QDoc includes this in \c {qwidget.html} like this: \quotation \raw HTMLwidth : const int
\endraw This property holds the width of the widget excluding any window frame. See the \l {Window Geometry} documentation for an overview of window geometry. Access functions: \list \o \bold { int width () const} \endlist See also \l{QWidget::geometry} {geometry}, \l{QWidget::height} {height}, and \l{QWidget::size} {size}. \endquotation \target service-command \section1 \\service The \\service command tells QDoc that a class is a service class and names the service. The command takes two arguments, the name of the class and the name of the service. Currently, this command is not used in the Qt documentation. \code / *! \service TimeService Time ... * / class TimeService : public QCopObjectService { ... } \endcode See also \l {class-command} {\\class} and \l {generatelist-command} {\\generatelist}. \target typedef-command \section1 \\typedef The \\typedef command is for documenting a C++ typedef. The argument is the name of the typedef. The documentation for the typedef will be included in the refernece documentation for the class, namespace, or header file in which the typedef is declared. To relat the \\typedef to a class, namespace, or header file, the \\typedef comment must contain a \l {relates-command} {\\relates} command. For example: \code / *! \typedef QObjectList \relates QObject Synonym for QList. * / \endcode QDoc includes this in \c {qobject.html} as: \quotation \raw HTML typedef QObjectList
\endraw Synonym for QList. \endquotation Another, although more rare, example: \code / *! \typedef QMsgHandler \relates QtGlobal This is a typedef for a pointer to a function with the following signature: \code void myMsgHandler(QtMsgType, const char *); \ endcode \sa QtMsgType, qInstallMsgHandler() * / \endcode QDoc includes this in \c {qtglobal.html} as: \quotation \raw HTML typedef QtMsgHandler
\endraw This is a typedef for a pointer to a function with the following signature: \raw HTMLvoid myMsgHandler(QtMsgType, const char *);\endraw See also QtMsgType and qInstallMsgHandler(). \endquotation Other typedefs are located on the reference page for the class that defines them. For example: \code / *! \typedef QLinkedList::Iterator Qt-style synonym for QList::iterator. * / \endcode QDoc includes this one on the reference page for class QLinkedList as: \quotation \raw HTMLtypedef QLinkedList::Iterator
\endraw Qt-style synonym for QList::iterator. \endquotation \target variable-command \section1 \\variable The \\variable command is for documenting a class member variable or a constant. The argument is the variable or constant name. The \\variable command comment includes a \l {brief-command} {\\brief} command. QDoc generates the documentation based on the text from \\brief command. The documentation will be located in the in the associated class, header file or namespace documentation. In case of a member variable: \code / *! \variable QStyleOption::palette \brief the palette that should be used when painting the control * / \endcode QDoc includes this in qstyleoption.html as: \quotation \raw HTMLQPalette QStyleOption::palette
\endraw This variable holds the palette that should be used when painting the control. \endquotation You can also document constants with the \\variable command. For example, suppose you have the \c Type and \c UserType constants in the QTreeWidgetItem class: \code enum { Type = 0, UserType = 1000 }; \endcode For these, the \\vaqriable command can be used this way: \code / *! \variable QTreeWidgetItem::Type The default type for tree widget items. \sa UserType, type() * / \endcode \code / *! \variable QTreeWidgetItem::UserType The minimum value for custom types. Values below UserType are reserved by Qt. \sa Type, type() * / \endcode QDoc includes these in qtreewidget.html as: \quotation \raw HTMLconst int QTreeWidgetItem::Type
\endraw The default type for tree widget items. See also \l {QTreeWidgetItem::UserType} {UserType} and \l {QTreeWidgetItem::type()} {type()}. \raw HTMLconst int QTreeWidgetItem::UserType
\endraw The minimum value for custom types. Values below UserType are reserved by Qt. See also \l {QTreeWidgetItem::Type} {Type} and \l{QTreeWidgetItem::type()} {type()}. \endquotation */ /*! \page 14-qdoc-commands-contextcommands.html \previouspage Topic Commands \contentspage Table of Contents \nextpage Document Navigation \title Context Commands The context commands provide information about the element being documented that QDoc can't deduce on its own. e.g. Is a class thread-safe? Is a function reentrant? Which module is the class a member of? Context commands can appear anywhere in a QDoc comment, but they are normally placed near the top of the comment, just below the \l {Topic Commands} {topic} command. \list \o \l {16-qdoc-commands-status.html#compat-command}{\\compat}, \o \l {15-qdoc-commands-navigation.html#contentspage-command}{\\contentspage}, \o \l {15-qdoc-commands-navigation.html#indexpage-command}{\\indexpage}, \o \l {19-qdoc-commands-grouping.html#ingroup-command}{\\ingroup}, \o \l {19-qdoc-commands-grouping.html#inmodule-command}{\\inmodule}, \o \l {16-qdoc-commands-status.html#internal-command}{\\internal}, \o \l {19-qdoc-commands-grouping.html#mainclass-command}{\\mainclass}, \o \l {15-qdoc-commands-navigation.html#nextpage-command}{\\nextpage}, \o \l {17-qdoc-commands-thread.html#nonreentrant-command}{\\nonreentrant}, \o \l {16-qdoc-commands-status.html#obsolete-command}{\\obsolete}, \o \l {18-qdoc-commands-relating.html#overload-command}{\\overload}, \o \l {16-qdoc-commands-status.html#preliminary-command}{\\preliminary}, \o \l {15-qdoc-commands-navigation.html#previouspage-command}{\\previouspage}, \o \l {17-qdoc-commands-thread.html#reentrant-command}{\\reentrant}, \o \l {18-qdoc-commands-relating.html#reimp-command}{\\reimp}, \o \l {18-qdoc-commands-relating.html#relates-command}{\\relates}, \o \l {16-qdoc-commands-status.html#since-command}{\\since}, \o \l {15-qdoc-commands-navigation.html#startpage-command}{\\startpage}, \o \l {20-qdoc-commands-namingthings.html#subtitle-command}{\\subtitle} \o \l {17-qdoc-commands-thread.html#threadsafe-command}{\\threadsafe}, \o \l {20-qdoc-commands-namingthings.html#title-command}{\\title} \endlist */ /*! \page 15-qdoc-commands-navigation.html \previouspage Context Commands \contentspage Table of Contents \nextpage Reporting Status \title Document Navigation The navigation commands are for linking the pages of a document in a meaningful sequence. Below is a sequence of QDoc comments that shows a typical use of the navigation commands. \section1 Example \code / *! \page basicqt.html \contentspage {Basic Qt} {Contents} \nextpage Getting Started \indexpage Index \startpage Basic Qt \title Basic Qt The Qt toolkit is a C++ class library and a set of tools for building multiplatform GUI programs using a "write once, compile anywhere approach". Table of contents: \list \o \l {Getting Started} \o \l {Creating Dialogs} \o \l {Creating Main Windows} \endlist * / / *! \page gettingstarted.html \previouspage Basic Qt \contentspage {Basic Qt} {Contents} \nextpage Creating Dialogs \indexpage Index \startpage Basic Qt \title Getting Started This chapter shows how to combine basic C++ with the functionality provided by Qt to create a few small graphical interface (GUI) applications. * / / *! \page creatingdialogs.html \previouspage Getting Started \contentspage {Basic Qt} {Contents} \indexpage Index \startpage Basic Qt \title Creating Dialogs This chapter will teach you how to create dialog boxes using Qt. * / / *! \page index.html \indexpage Index \startpage Basic Qt \title Index \list \o \l {Basic Qt} \o \l {Creating Dialogs} \o \l {Getting Started} \endlist * / \endcode QDoc renders the "Getting Started" page in \c{creatingdialogs.html}: \quotation \raw HTML\endraw \endquotation The \l {indexpage-command} {\\indexpage} and \l {startpage-command} {\\startpage} commands create links to the page's index page and start page. These links can be used by browsers and search engines. The index page is typically an alphabetical list of the document's titles and topics, while the start page is the page considered by the author to be the starting point of a multipage document. The links are included in the generated HTML source code but have no visual effect on the documentation: \code ... ... \endcode \section1 Commands \target previouspage-command \section2 \\previouspage The \\previouspage command links the current page to the previous page in a sequence.a The command has two arguments, each enclosed by curly braces: The first is the link target, i.e. the title of the previous page, the second is the link text. If the page's title is equivalent to the link text, the second argument can be omitted. The command must stand alone on its own line. \target nextpage-command \section2 \\nextpage The \\nextpage command links the current page to the next page in a sequence. The command follows the same syntax and argument convention as the \l {previouspage-command} {\\previouspage} command. \target startpage-command \section2 \\startpage The \\startpage command specifies the first page of a sequence of pages. The command must stand alone on its own line, and its unique argument is the title of the first document. QDoc will generate a link to the start page and include it in the generated HTML file, but this has no visual effect on the documentation. The generated link type tells browsers and search engines which document is considered by the author to be the starting point of the collection. \target contentspage-command \section2 \\contentspage The \\contentspage command links the current page to a table of contents page. The command follows the same syntax and argument convention as the \l {previouspage-command} {\\previouspage} command. \target indexpage-command \section2 \\indexpage The \\indexpage command specifies an index page for the current document. The command must stand alone on its own line, and its unique argument is the title of the index document. QDoc will generate a link to the index page and include it in the generated HTML file, but this has no visual effect on the documentation. The generated link type tells browsers and search engines which document is considered by the author to be the index page of the collection. */ /*! \page 16-qdoc-commands-status.html \previouspage Document Navigation \contentspage Table of Contents \nextpage Thread Support \title Reporting Status 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. \target preliminary-command \section1 \\preliminary 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 QDoc renders this as: \quotation \raw HTML
[Previous: Basic Qt] [Contents] [Next: Creating Dialogs]
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.
[Previous: Basic Qt] [Contents] [Next: Creating Dialogs]
Joining QChar::joining () const
\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 \target obsolete-command \section1 \\obsolete 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 QDoc renders this as: \quotation \raw HTMLObsolete Members for MyClass
\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
Member Function Documentation
void MyObsoleteFunction ()
Use MyNewFunction() instead.
\endraw ... \endquotation in myclass-obsolete.html \target compat-command \section1 \\compat 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 QDoc renders this 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 QDoc renders this as: \quotation \raw HTMLQt 3 Support Members for MyClass
\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
Member Function Documentation
void MyQt3SupportMemberFunction ()
Use MyNewFunction() instead.
\endraw ... \endquotation in myclass-qt3.html \target internal-command \section1 \\internal The \\internal command indicates that the referenced function is not part of the public interface. The command must stand on its own line. QDoc ignores the documentation as well as the documented item, when generating the associated class reference documenation. 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. \target since-command \section1 \\since 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 QDoc renders this as: \quotation \raw HTMLQIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const
\endraw This function was introduced in Qt version 4.1 Returns an icon for \a standardIcon. ... See also \l {QStyle::standardIconImplementation()} {standardIconImplementation()} and \l {QStyle::standardPixmap()} {standardPixmap()}. \endquotation QDoc generates the "Qt" reference from the \l {25-qdoc-configuration-derivedprojects.html#project} {\c project} configuration variable. For that reason this reference will change according to the current documentation project. See also \l {25-qdoc-configuration-derivedprojects.html#project} {\c project}. */ /*! \page 17-qdoc-commands-thread.html \previouspage Reporting Status \contentspage Table of Contents \nextpage Relating Things \title Thread Support The thread support commands are for specifying the level of support for multithreaded programming in a class or function. There are three levels of support: \c threadsafe, \c reentrant and \c nonreentrant. The default is \c nonreentrant which means that the associated class or function cannot be called by multiple threads. \c Reentrant and \c threadsafe are levels primarily used for classes. \c Reentrant means that all the functions in the referenced class can be called simultaneously by multiple threads, provided that each invocation of the functions reference unique data. While \c threadsafe means that all the functions in the referenced class can be called simultaneously by multiple threads even when each invocation references shared data. When a class is marked \l {reentrant-command} {\\reentrant} or \l {threadsafe-command} {\\threadsafe}, functions in that class can be marked \c nonreentrant using the \l {nonreentrant-command} {\\nonreentrant} command. \section1 Example \target reentrant-example \code / *! \class QLocale \brief The QLocale class converts between numbers and their string representations in various languages. \reentrant \ingroup i18n \ingroup text \mainclass QLocale is initialized with a language/country pair in its constructor and offers number-to-string and string-to-number conversion functions similar to those in QString. ... * / / *! \nonreentrant Sets the global default locale to \a locale. These values are used when a QLocale object is constructed with no arguments. If this function is not called, the system's locale is used. \warning In a multithreaded application, the default locale should be set at application startup, before any non-GUI threads are created. \sa system() c() * / void QLocale::setDefault(const QLocale &locale) { default_d = locale.d; } \endcode QDoc renders this as: \quotation \raw HTML\endraw The QLocale class converts between numbers and their string representations in various languages. More... \code #include
QLocale Class Reference \endcode \bold {Note:} All the functions in this class are \l {threads.html#reentrant} {reentrant}, except \l {QLocale::setDefault()} {setDefault()}. ... \raw HTML
Member Type Documentation
\endraw ... \raw HTMLvoid QLocale::setDefault ( const QLocale & locale )
\endraw Sets the global default locale to locale. These values are used when a QLocale object is constructed with no arguments. If this function is not called, the system's locale is used. \warning In a multithreaded application, the default locale should be set at application startup, before any non-GUI threads are created. \warning This function is not reentrant. See also \l {QLocale::system()} {system()} and \l {QLocale::c()} {c()}. ... \endquotation As shown above, QDoc generates a notification when a class is declared reentrant, and lists the exceptions (the declared nonreentrant functions). A link to the general documentation on \l {threads.html#reentrant} {reentrancy and thread-safety} is included. In addition a warning, "\bold Warning: This function is not reentrant.", is generated in the nonreentrant functions' documentation. QDoc will generate the same notification and warnings when a class is declared threadsafe. For more information see the general documentation on \l {threads.html#reentrant} {reentrancy and thread-safety}. \section1 Commands \target threadsafe-command \section2 \\threadsafe The \\threadsafe command includes a line in the documentation to indicate that the associated class or function is \e threadsafe and can be called simultaneously by multiple threads, even when separate invocations reference shared data. The command must stand on its own line. The documentation generated from this command will be similar to the what is generated for the \l {reentrant-command} {\\reentrant} command. See the example above in the \l {reentrant-example} {introduction}. See also \l{reentrant-command} {\\reentrant} and \l{nonreentrant-command} {\\nonreentrant}. \target reentrant-command \section2 \\reentrant The \\reentrant command indicates that the associated class or function can be called simultaneously by multiple threads, provided that each invocation references its own data. See the \l {reentrant-example} {example} above. The command must stand on its own line. See also \l{nonreentrant-command} {\\nonreentrant} and \l{threadsafe-command} {\\threadsafe}. \target nonreentrant-command \section2 \\nonreentrant The \\nonreentrant command indicates that the associated class or function cannot be called by multiple threads. Nonreentrant is the default case. The command must stand on its own line. When a class is marked \l {reentrant-command} {\\reentrant} or \l {threadsafe-command} {\\threadsafe}, functions in that class can be marked \c nonreentrant using this command in the \l{fn-command} {\\fn} comment of the functions to be excluded. See also \l{reentrant-command} {\\reentrant} and \l{threadsafe-command} {\\threadsafe}. */ /*! \page 18-qdoc-commands-relating.html \previouspage Thread Support \contentspage Table of Contents \nextpage Grouping Things \title Relating Things The 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. \target overload-command \section1 \\overload 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 \e{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 QDoc renders this as: \quotation \raw HTMLQAction * QMenu::addAction ( const QIcon & icon, const QString & text )
\endraw This function overloads \l {http://qt.nokia.com/doc/4.0/qwidget.html#addAction} {addAction()} This convenience function creates a new action with an \e icon and some \e text. The function adds the newly created action to the menu's list of actions, and returns it. See also \l {http://qt.nokia.com/doc/4.0/qwidget.html#addAction} {QWidget::addAction}(). \endquotation If you don't include the function name with the \bold{\\overlaod} command, then instead of the "This function overloads..." line with the link to the documentation for the primary version, you get the old standard line: \quotation This is an overloaded member function, provided for convenience. \endquotation. \target reimp-command \section1 \\reimp 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. \target relates-command \section1 \\relates 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. */ /*! \page 19-qdoc-commands-grouping.html \previouspage Relating Things \contentspage Table of Contents \nextpage Naming Things \title Grouping Things The grouping commands relate classes to defined groups and modules. The groups are used when generating lists of related classes in the documentation, while the modules are elements of Qt's structure. \target mainclass-command \section1 \\mainclass 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-command} {\\generatelist} command with the \c mainclasses argument: \l http://qt.nokia.com/doc/4.0/mainclasses.html See also \l {generatelist-command} {\\generatelist}. \target ingroup-command \section1 \\ingroup The \\ingroup command indicates that the given overview or documented class belongs to a certain group of related docmentation. A class or overview may belong to many groups. The \\ingroup command's argument is a group name, but note that the command considers the rest of the line as part of its argument. Make sure that the group name is followed by a linebreak. 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-command} {\\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-command} {\\generatelist} command with the \c related argument. See also \l {group-command} {\\group}. \target inmodule-command \section1 \\inmodule 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-command} {\\generatelist} command with the \c {{classesbymodule QtDesigner}} argument. See also \l {module-command} {\\module} and \l {generatelist-command} {\\generatelist}. */ /*! \page 20-qdoc-commands-namingthings.html \previouspage Grouping Things \contentspage Table of Contents \nextpage Markup Commands \title Naming Things In general a title command considers everything that follows it until the first line break as its argument. If the title needs to be spanned over several lines, make sure to end each line (except the last one) with a backslash. \target title-command \section1 \\title The \\title command sets the title for a documentation page, or allows you to override it. For example: \code / *! \page signalandslots.html \title Signals & Slots Signals and slots are used for communication between objects. The signals and slots mechanism is a central feature of Qt and probably the part that differs most from the features provided by other frameworks. ... * / \endcode QDoc renders this as: \quotation \raw HTML\endraw Signals and slots are used for communication between objects. The signals and slots mechanism is a central feature of Qt and probably the part that differs most from the features provided by other frameworks. ... \endquotation See also \l {subtitle-command} {\\subtitle}. \target subtitle-command \section1 \\subtitle 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 QDoc renders this as: \quotation \raw HTML
Signal and Slots
Qtopia Core \endraw Qt/Embedded, the embedded Linux port of Qt, is a complete and self-contained C++ GUI and platform development tool for Linux-based embedded development. ... \endquotation See also \l {title-command} {\\title}. */ /*! \page 21-0-qdoc-configuration.html \previouspage Miscellaneous \contentspage Table of Contents \nextpage General Configuration Variables \title The QDoc Configuration File Before running QDoc to to extract and format your QDOC comments, you must create a QDoc configuration file to tell QDoc where to find them. \list \o \l {Supporting Derived Projects} \o \l {Compatibility Issues} \endlist When running QDoc to generate the documentation, you must specify a configuration file on the command line: \section1 General Description The configuration file is a list of entries of entries of the form \e {"variable = value"}. Using the configuration variables, you can define where QDoc should find the various source files, images and examples, where to put generated documentation etc. The configuration file can also contain directives like \c include. For an example, see the \l minimum.qdocconf file. 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 = "Home" \endcode If an entry spans many lines, use a backslash at the end of every line but the last: \code sourcedirs = kernel \ tools \ widgets \endcode \section1 Configuration Variables \section1 Variable List \list \o \l {22-qdoc-configuration-generalvariables.html#alias-variable} {alias} \o \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoredirectives-variable} {Cpp.ignoredirectives} \o \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoretokens-variable} {Cpp.ignoretokens} \o \l {22-qdoc-configuration-generalvariables.html#defines-variable} {defines} \o \l {22-qdoc-configuration-generalvariables.html#edition-variable} {edition} \o \l {22-qdoc-configuration-generalvariables.html#exampledirs-variable} {exampledirs} \o \l {22-qdoc-configuration-generalvariables.html#examples-variable} {examples} \o \l {22-qdoc-configuration-generalvariables.html#examples.fileextensions-variable} {examples.fileextensions} \o \l {22-qdoc-configuration-generalvariables.html#extraimages-variable} {extraimages} \o \l {22-qdoc-configuration-generalvariables.html#falsehoods-variable} {falsehoods} \o \l {22-qdoc-configuration-generalvariables.html#headerdirs-variable} {headerdirs} \o \l {22-qdoc-configuration-generalvariables.html#headers-variable} {headers} \o \l {22-qdoc-configuration-generalvariables.html#headers.fileextensions-variable} {headers.fileextensions} \o \l {24-qdoc-configuration-htmlvariables.html#HTML.footer-variable} {HTML.footer} \o \l {24-qdoc-configuration-htmlvariables.html#HTML.postheader-variable} {HTML.postheader} \o \l {24-qdoc-configuration-htmlvariables.html#HTML.style-variable} {HTML.style} \o \l {22-qdoc-configuration-generalvariables.html#imagedirs-variable} {imagedirs} \o \l {22-qdoc-configuration-generalvariables.html#images-variable} {images} \o \l {22-qdoc-configuration-generalvariables.html#images.fileextensions-variable} {images.fileextensions} \o \l {22-qdoc-configuration-generalvariables.html#language-variable} {language} \o \l {22-qdoc-configuration-generalvariables.html#macro-variable} {macro} \o \l {22-qdoc-configuration-generalvariables.html#outputdir-variable} {outputdir} \o \l {22-qdoc-configuration-generalvariables.html#outputformats-variable} {outputformats} \o \l {22-qdoc-configuration-generalvariables.html#slow-variable} {slow} \o \l {22-qdoc-configuration-generalvariables.html#sourcedirs-variable} {sourcedirs} \o \l {22-qdoc-configuration-generalvariables.html#sources-variable} {sources} \o \l {22-qdoc-configuration-generalvariables.html#sources.fileextensions-variable} {sources.fileextensions} \o \l {22-qdoc-configuration-generalvariables.html#spurious-variable} {spurious} \o \l {22-qdoc-configuration-generalvariables.html#tabsize-variable} {tabsize} \o \l {22-qdoc-configuration-generalvariables.html#version-variable} {version} \o \l {22-qdoc-configuration-generalvariables.html#versionsym-variable} {versionsym} \endlist \section1 Categories \list \o \l {General Configuration Variables} \o \l {C++ Specific Configuration Variables} \o \l {HTML Specific Configuration Variables} \endlist \section1 Configuration File Examples \list \o A minimum configuration file: \l minimum.qdocconf \o The Qt configuration file: \l qt.qdocconf \endlist */ /*! \page 21-1-minimum-qdocconf.html \previouspage qt.qdocconf \contentspage Table of Contents \nextpage Table of Contents \title minimum.qdocconf \quotefile examples/minimum.qdocconf */ /*! \page 21-2-qt-qdocconf.html \previouspage Compatibility Issues \contentspage Table of Contents \nextpage minimum.qdocconf \title qt.qdocconf \quotefile files/qt.qdocconf */ /*! \page 22-qdoc-configuration-generalvariables.html \previouspage The QDoc Configuration File \contentspage Table of Contents \nextpage Creating Help Project Files \title General Configuration Variables With the general QDoc configuration variables, you can define where QDoc will find the various source files it needs to generate the documentation, as well as the directory to put the generated documentation. You can also do some minor manipulation of QDoc itself, controlling its output and processing behavior. \target alias-variable \section1 alias The \c alias variable renames a QDoc command. The general syntax is \tt {alias.\e{original-command-name} = \e temporary-command-name}. 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 {Compatibility Issues} {compatibility section}. See also \l {macro-command} {macro}. \target codeindent-variable \section1 codeindent The \c codeindent variable specifies the level of indentation that QDoc uses when writing code snippets. QDoc originally used a hard-coded value of four spaces for code indentation to ensure that code snippets could be easily distinguished from surrounding text. Since we can use \l{HTML Specific Configuration Variables#HTML.stylesheets} {stylesheets} to adjust the appearance of certain types of HTML elements, this level of indentation is not always required. \target defines-variable \section1 defines The \c defines variable specifies the C++ preprocessor symbols that QDoc will recognize and respond to. When a preprocessor symbol is specified using the \c defines variable, you can also use the \l {if-command} {\\if} command to enclose documentation that only will be included if the preprocessor symbol is defined. The values of the variable are regular expressions (see QRegExp for details). By default, no symbol is defined, meaning that code protected with #ifdef...#endif will be ignored. 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-variable} {falsehoods} and \l {if-command} {\\if}. \target edition-variable \section1 edition The \c edition variable specifies which modules are included in each edition of a package, and provides QDoc with information to provide class lists for each edition. This feature is mostly used when providing documentation for Qt packages. The \c edition variable is always used with a particular edition name to define the modules for that edition: \code edition.Console = QtCore QtNetwork QtSql QtXml edition.Desktop = QtCore QtGui QtNetwork QtOpenGL QtSql QtXml \ QtDesigner QtAssistant Qt3Support QAxContainer \ QAxServer edition.DesktopLight = QtCore QtGui Qt3SupportLight \endcode In the above examples, the \c Console edition only includes the contents of four modules. Only the classes from these modules will be used when the \l{Miscellaneous#generatelist-command} {generatelist} command is used to generate a list of classes for this edition: \code \generatelist{classesbyedition Console} \endcode \target exampledirs-variable \section1 exampledirs The \c exampledirs variable specifies the directories containing the source code of the example files. The \l {examples-variable} {examples} {examples} and \l {exampledirs-variable} {exampledirs} variables are used by the \l {quotefromfile-command} {\\quotefromfile}, \l {quotefile-command} {\\quotefile} and \l {example-command} {\\example} commands. If both the \l {examples-variable} {examples} and \l {exampledirs-variable} {exampledirs} variables are defined, QDoc will search in both, first in \l {examples-variable} {examples} then in \l {exampledirs-variable} {exampledirs}. QDoc will search through the directories in the specified order, and accept the first matching file it finds. It will only search in the specified directories, \e not in subdirectories. 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. \target examples-variable \section1 examples The \c examples variable allows you to specify individual example files in addition to those located in the directories specified by the \l {exampledirs-variable} {\c exampledirs} variable. The \c examples and \l {exampledirs-variable} {\c exampledirs} variables are used by the \l {quotefromfile-command} {\\quotefromfile}, \l {quotefile-command} {\\quotefile} and \l {example} {\\example} commands. If both the \c examples and \l {exampledirs-variable} {\c exampledirs} variables are defined, QDoc will search in both, first in \c examples then in \l {exampledirs-variable} {\c exampledirs}. QDoc will search through the values listed for the \c examples variable, in the specified order, and accept the first one it finds. For an extensive example, see the \l {exampledirs-variable} {\c exampledirs} command. But note that if you know the file is listed in the \c examples variable, you don't need to specify its path: \code \quotefromfile calculator.cpp \endcode See also \l {exampledirs-variable} {exampledirs}. \target examples.fileextensions-variable \section1 examples.fileextensions The \c examples.fileextensions variable specifies the file extensions that qdoc will look for when collecting example files for display in the documentation. The default extensions are *.cpp, *.h, *.js, *.xq, *.svg, *.xml and *.ui. However, if The extensions are given as standard wildcard expressions. You can add a file extension to the filter using '+='. For example: \code examples.fileextensions += *.qrc \endcode See also \l{headers.fileextensions}. \target extraimages-variable \section1 extraimages The \c extraimages variable tells QDoc to incorporate specific images in the generated documentation. QDoc will not recognize images used within HTML (or any other markup language). If we want the images to be copied from the directories specified by \l {imagedirs} {\c imagedirs} (the images in question must be located in these directories) to the output directory, we must specify the images using the \c extraimages variable. The general syntax is \tt {extraimages.\e{format} = \e image}. The file extension is optional. For example, in \l qt.qdocconf we use a couple of images within the HTML.postheader variable which value is pure HTML. For that reason, these images are specified using the \c extraimages variable: \code extraimages.HTML = qt-logo \endcode See also \l images and \l imagedirs. \target falsehoods-variable \section1 falsehoods The \c falsehoods variable defines the truth value of specified preprocessor symbols as false. If this variable is not set for a preprocessor symbol, QDoc assumes its truth value is true. The exception is '0', which value always is false. QDoc will recognize, and is able to evaluate, the following preprocessor syntax: \code #ifdef NOTYET ... #endif #if defined (NOTYET) ... #end if \endcode However, faced with unknown syntax like \code #if NOTYET ... #endif \endcode QDoc will evaluate it as true by default, \e unless the preprocessor symbol is specified within the \c falsehoods variable entry: \code falsehoods = NOTYET \endcode See also \l defines. \target generateindex-variable \section1 generateindex The \c generateindex variable contains a boolean value that specifies whether to generate an index file when HTML documentation is generated. By default, an index file is always generated with HTML documentation, so this variable is typically only used when disabling this feature (by setting the value to \c false) or when enabling index generation for the WebXML output (by setting the value to \c true). \target headerdirs-variable \section1 headerdirs The \c headerdirs variable specifies the directories containing the header files associated with the \c .cpp source files used in the documentation. 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-variable} {\c sources}, and the ones located in the directories specified in the \l {sourcedirs-variable} {\c sourcedirs} varible (including all subdirectories), merging the documentation with the structure it retrieved from the header files. If both the \c headers and \c headerdirs variables are defined, QDoc will read through both, first \l {headers} {\c headers} then \c headerdirs. In the specified directories, QDoc will only read the files with the fileextensions specified in the \l {headers.fileextensions} {\c headers.fileextensions} variable. The default extensions are *.ch, *.h, *.h++, *.hh, *.hpp and *.hxx". The files specified by \l {headers} {\c headers} will be read independent of their fileextensions. See also \l headers and \l headers.fileextensions. \target headers-variable \section1 headers The \c headers variable allows you to specify individual header files in addition to those located in the directories specified by the \l {headerdirs} {\c headerdirs} variable. 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. \target headers.fileextensions-variable \section1 headers.fileextensions The \c headers.fileextensions variable specify the extension used by the headers. When processing the header files specified in the \l {headerdirs} {\c headerdirs} variable, QDoc will only read the files with the fileextensions specified in the \c headers.fileextensions variable. In this way QDoc avoid spending time reading irrelevant files. The default extensions are *.ch, *.h, *.h++, *.hh, *.hpp and *.hxx. The extensions are given as standard wildcard expressions. You can add a file extension to the filter using '+='. For example: \code header.fileextensions += *.H \endcode \warning The above assignment may not work as described. See also \l headerdirs. \target imagedirs-variable \section1 imagedirs The \c imagedirs variable specifies the directories containing the images used in the documentation. The \l {images} {\c images} and \c imagedirs variables are used by the \l {image-command} {\\image} and \l {inlineimage-command} {\\inlineimage} commands. If both the \l {images} {\c images} and \c imagedirs variables are defined, QDoc will search in both, first in \l {images} {\c images} then in \c imagedirs. QDoc will search through the directories in the specified order, and accept the first matching file it finds. It will only search in the specified directories, \e not in subdirectories. 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. \target images-variable \section1 images The \c images variable allows you to specify individual image files in addition to those located in the directories specified by the \l {imagedirs} {\c imagedirs} variable. 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. \target images.fileextensions-variable \section1 images.fileextensions The images.fileextensions variable filters the files within an image directory. The variable's values (the extensions) are given as standard wildcard expressions. The general syntax is: \tt {images.fileextensions.\e{format} = *.\e{extension}}. The idea is to enable different image format for different output format. For example: \code images.fileextensions.HTML = *.png images.fileextensions.LOUT = *.eps \endcode Then, when processing the \l {image-command} {\\image} and \l {inlineimage-command} {\\inlineimage} commands, QDoc will only search for files with extensions specified in the output format's associated image extension variable. \warning This is preliminary functionality since QDoc at this point only support HTML. The default extensions for HTML are *.png, *.jpg, *.jpeg and *.gif. You can add a file extension to the filter using '+='. For example: \code images.fileextensions.HTML += *.eps \endcode See also \l imagedirs and \l images. \target language-variable \section1 language The \c language variable specifies the language of the source code that is used in the documentation. Currently, C++ is the only language that QDoc understands. It is also the default language, and doesn't really need to be specified. But for example in \l qt.qdocconf: \code language = Cpp \endcode identifies the language of the Qt source code as C++. \target macro-variable \section1 macro The \c macro variable can be used to create your own QDoc commands. The general syntax is \tt {macro.\e{command} = "\e{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 = "*" \endcode makes sure that the \\gui command renders its argument using a bold font, and that \\raisedaster renders a '*'. \target naturallanguage-variable \section1 naturallanguage The \c naturallanguage variable specifies the natural language used for the documentation generated by qdoc. For example: \code naturallanguage = zh-Hans \endcode By default, the natural language is \c en for compatibility with legacy documentation. qdoc will add the natural language information to the HTML it generates, using the \c lang and \c xml:lang attributes. See also \l {sourceencoding-variable} {sourceencoding}, \l {outputencoding-variable} {outputencoding}, \l{http://www.w3.org/TR/xhtml1/#C_7} {C.7. The lang and xml:lang Attributes} and \l{http://www.w3.org/TR/i18n-html-tech-lang/#ri20040429.113217290} {Best Practice 13: Using Hans and Hant codes}. \target outputdir-variable \section1 outputdir The \c outputdir variable specifies the directory where QDoc will put the generated documentation. In qt.qdocconf: \code outputdir = $QTDIR/doc/html \endcode locates the generated Qt reference documentation in $QTDIR/doc/html. For example, the documentation of the QWidget class is located in \code $QTDIR/doc/html/qwidget.html \endcode The associated images will be put in an \c images subdirectory. \warning When running QDoc multiple times using the same output directory, all files from the previous run will be lost. \target outputencoding-variable \section1 outputencoding The \c outputencoding variable specifies the encoding used for the documentation generated by qdoc. For example: \code outputencoding = UTF-8 \endcode By default, the output encoding is \c ISO-8859-1 (Latin1) for compatibility with legacy documentation. When generating documentation for some languages, particularly non-European languages, this is not sufficient and an encoding such as UTF-8 is required. qdoc will encode HTML using this encoding and generate the correct declarations to indicate to browsers which encoding is being used. The \l naturallanguage configuration variable should also be specified to provide browsers with a complete set of character encoding and language information. See also \l outputencoding and \l naturallanguage. \target outputformats-variable \section1 outputformats The \c outputformats variable specifies the format of the generated documentation. Currently, QDoc only supports the HTML format. It is also the default format, and doesn't need to be specified. \target qhp-variable \section1 qhp The \c qhp variable is used to define the information to be written out to Qt Help Project (\c{qhp}) files. See the \l{Creating Help Project Files} chapter for information about this process. \target slow-variable \section1 slow The \c slow variable specifies whether QDoc should do time-consuming processing, such as syntax highlighting. 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. \target sourcedirs-variable \section1 sourcedirs The \c sourcedirs variable specifies the directories containing the \c .cpp or \c .qdoc files used in the documentation. For example in \l qt.qdocconf \code sourcedirs = $QTDIR/src \ $QTDIR/doc/src \ $QTDIR/extensions/activeqt \ $QTDIR/extensions/motif \ $QTDIR/tools/designer/src/lib/extension \ $QTDIR/tools/designer/src/lib/sdk \ $QTDIR/tools/designer/src/lib/uilib \endcode When executed, the first QDoc will do is to read through the headers specified in the \l {header-command} {\c header} variable, and the ones located in the directories specified in the \c headerdir variable (including all subdirectories), building an internal structure of the classes and their functions. Then it will read through the sources specified in the \l {sources} {\c sources}, and the ones located in the directories specified in the \l {sourcedirs} {\c sourcedirs} varible (including all subdirectories), merging the documentation with the structure it retrieved from the header files. If both the \c sources and \c sourcedirs variables are defined, QDoc will read through both, first \l {sources} {\c sources} then \c sourcedirs. In the specified directories, QDoc will only read the files with the fileextensions specified in the \l {sources.fileextensions} {\c sources.fileextensions} variable. The default extensions are *.c++, *.cc, *.cpp and *.cxx. The files specified by \l {sources} {\c sources} will be read independent of their fileextensions. See also \l {sources-variable} {sources} and \l {sources.fileextensions-variable} {sources.fileextensions}. \target sourceencoding-variable \section1 sourceencoding The \c sourceencoding variable specifies the encoding used for the source code and documentation. For example: \code sourceencoding = UTF-8 \endcode By default, the source encoding is \c ISO-8859-1 (Latin1) for compatibility with legacy documentation. For some languages, particularly non-European languages, this is not sufficient and an encoding such as UTF-8 is required. Although qdoc will use the encoding to read source and documentation files, limitations of C++ compilers may prevent you from using non-ASCII characters in source code comments. In cases like these, it is possible to write API documentation completely in documentation files. See also \l {naturallanguage-variable} {naturallanguage} and \l {outputencoding-variable} {outputencoding}. \target sources-variable \section1 sources The \c sources variable allows you to specify individual source files in addition to those located in the directories specified by the \l {sourcedirs-variable} {sourcedirs} variable. 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-variable} {sourcedirs} variable. For more information, see the \l {sourcedirs-variable} {sourcedirs} variable. See also \l {sourcedirs-variable} {sourcedirs}. \target sources.fileextensions-variable \section1 sources.fileextensions The \c sources.fileextensions variable filters the files within a source directory. When processing the source files specified in the \l {sourcedirs} {\c sourcedirs} variable, QDoc will only read the files with the fileextensions specified in the \c sources.fileextensions variable. In this way QDoc avoid spending time reading irrelevant files. The default extensions are *.c++, *.cc, *.cpp and *.cxx. The extensions are given as standard wildcard expressions. You can add a file extension to the filter using '+='. For example: \code sources.fileextensions += *.CC \endcode \warning The above assignment may not work as described. See also \l {sourcedirs-variable} {sourcedirs} and \l (sources-variable} {sources}. \target spurious-variable \section1 spurious The \c spurious variable excludes specified QDoc warnings from the output. The warnings are specified using standard wildcard expressions. 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 \target tabsize-variable \section1 tabsize 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. \target tagfile-variable \section1 tagfile The \c tagfile variable specifies the Doxygen tag file to be written when HTML is generated. \target version-variable \section1 version The \c version variable specifies the version number of the documented software. 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. \target versionsym-variable \section1 versionsym The \c versionsym variable specifies a C++ preprocessor symbol that defines the version number of the documented software. For example in \l qt.qdocconf: \code versionsym = QT_VERSION_STR \endcode QT_VERSION_STR is defined in qglobal.h as follows \code #define QT_VERSION_STR "4.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}. */ /*! \page 22-creating-help-project-files.html \previouspage General Configuration Variables \contentspage Table of Contents \nextpage C++ Specific Configuration Variables \title Creating Help Project Files \section1 Overview Starting with Qt 4.4, Qt Assistant uses a different system for managing Qt documentation that requires QDoc to generate inventories of files in a format that is similar to the old style DCF format, but with additional features. Instead of hard-coding information about the documentation sets for Qt, QDoc allows configuration variables to be used to specify which pages are to be used in each documentation set it generates. These are specified as subvariables of the \c qch variable with each set declared using a unique identifier as a subvariable. For example, the configuration file for the Qt documentation defines a \c Qt documentation set by specifying information about the set as subvariables with the \c{qhp.Qt} prefix: \code qhp.Qt.file = qt.qhp qhp.Qt.namespace = com.trolltech.qt.440 qhp.Qt.virtualFolder = qdoc qhp.Qt.indexTitle = Qt Reference Documentation qhp.Qt.indexRoot = qhp.Qt.extraFiles = classic.css images/qt-logo.png qhp.Qt.filterAttributes = qt 4.4.0 qtrefdoc qhp.Qt.customFilters.Qt.name = Qt 4.4.0 qhp.Qt.customFilters.Qt.filterAttributes = qt 4.4.0 qhp.Qt.subprojects = classes overviews examples qhp.Qt.subprojects.classes.title = Classes qhp.Qt.subprojects.classes.indexTitle = Qt's Classes qhp.Qt.subprojects.classes.selectors = class qhp.Qt.subprojects.overviews.title = Overviews qhp.Qt.subprojects.overviews.indexTitle = All Overviews and HOWTOs qhp.Qt.subprojects.overviews.selectors = fake:page,group,module qhp.Qt.subprojects.examples.title = Tutorials and Examples qhp.Qt.subprojects.examples.indexTitle = Qt Examples qhp.Qt.subprojects.examples.selectors = fake:example \endcode To create a table of contents for a manual, create a subproject with a \c{type} property and set it to \c{manual}. The page in the documentation referred to by the \c{indexTitle} property must contain a list of links that acts as a table of contents for the whole manual. QDoc will take the information in this list and create a table of contents for the subproject. For example, the configuration file for Qt Creator defines only one subproject for its documentation, including all the documentation in a single manual: \code qhp.QtCreator.subprojects = manual qhp.QtCreator.subprojects.manual.title = Qt Creator Manual qhp.QtCreator.subprojects.manual.indexTitle = Qt Creator Manual qhp.QtCreator.subprojects.manual.type = manual \endcode In this example, the page entitled "Qt Creator Manual" contains a nested list of links to pages in the documentation which is duplicated in Qt Assistant's Contents tab. */ /*! \page 23-qdoc-configuration-cppvariables.html \previouspage Creating Help Project Files \contentspage Table of Contents \nextpage HTML Specific Configuration Variables \title C++ Specific Configuration Variables The C++ specific configuration variables are provided to avoid erroneous documentation due to non-standard C++ constructs. \target Cpp.ignoredirectives-variable \section1 Cpp.ignoredirectives The \c Cpp.ignoredirectives variable makes QDoc ignore the specified non-standard constructs, within C++ source code. If not specified by the \tt {\l Cpp.ignoretokens} or \tt {\l Cpp.ignoredirectives} variables, non-standard constructs (typically macros) can result in erroneous documentation. In \l qt.qdocconf: \code Cpp.ignoredirectives = Q_DECLARE_INTERFACE \ Q_DECLARE_OPERATORS_FOR_FLAGS \ Q_DECLARE_PRIVATE \ Q_DECLARE_PUBLIC \ Q_DISABLE_COPY \ Q_DUMMY_COMPARISON_OPERATOR \ Q_ENUMS \ Q_FLAGS \ Q_INTERFACES \ __attribute__ \endcode makes sure that when processing the code below, for example, QDoc will simply ignore the 'Q_ENUMS' and 'Q_FLAGS' expressions: \code class Q_CORE_EXPORT Qt { Q_OBJECT Q_ENUMS(Orientation TextFormat BackgroundMode DateFormat ScrollBarPolicy FocusPolicy ContextMenuPolicy CaseSensitivity LayoutDirection ArrowType) Q_ENUMS(ToolButtonStyle) Q_FLAGS(Alignment) Q_FLAGS(Orientations) Q_FLAGS(DockWidgetAreas) public: ... }; \endcode The Q_OBJECT macro, however, is an exception: QDoc recognizes this particular non-standard construct, so there is no need specifying it using the \tt {\l Cpp.ignoredirectives} variable. Regarding the Q_CORE_EXPORT macro; see the documentation of the \tt {\l Cpp.ignoretokens} variable. See also \l Cpp.ignoretokens. \target Cpp.ignoretokens-variable \section1 Cpp.ignoretokens The \c Cpp.ignoretokens variable makes QDoc ignore the specified non-standard constructs, within C++ source code. If not specified by the \tt {\l Cpp.ignoretokens} or \tt {\l Cpp.ignoredirectives} variables, non-standard constructs (typically macros) can result in erroneous documentation. In \l qt.qdocconf: \code Cpp.ignoretokens = QAXFACTORY_EXPORT \ QM_EXPORT_CANVAS \ ... Q_COMPAT_EXPORT \ Q_CORE_EXPORT \ Q_EXPLICIT \ Q_EXPORT \ ... Q_TYPENAME \ Q_XML_EXPORT \endcode makes sure that when processing the code below, for example, QDoc will simply ignore the 'Q_CORE_EXPORT' expression: \code class Q_CORE_EXPORT Qt { Q_OBJECT Q_ENUMS(Orientation TextFormat BackgroundMode DateFormat ScrollBarPolicy FocusPolicy ContextMenuPolicy CaseSensitivity LayoutDirection ArrowType) Q_ENUMS(ToolButtonStyle) Q_FLAGS(Alignment) Q_FLAGS(Orientations) Q_FLAGS(DockWidgetAreas) public: ... }; \endcode Regarding the Q_OBJECT, Q_ENUMS and Q_FLAGS macros; see the documentation of the \tt {\l Cpp.ignoredirectives} variable. See also \l Cpp.ignoredirectives. */ /*! \page 24-qdoc-configuration-htmlvariables.html \previouspage C++ Specific Configuration Variables \contentspage Table of Contents \nextpage Supporting Derived Projects \title HTML Specific Configuration Variables The HTML specific configuration variables define the generated documentation's style, or define the contents of the documentation's footer or postheader. The format of the variable values are raw HTML. \target HTML.footer-variable \section1 HTML.footer The \c HTML.footer variable defines the content of the generated HTML documentation's footer. The footer is rendered at the bottom of the generated documentation page. The variable's value is given as raw HTML code enclosed by quotation marks. Note that if the value spans several lines, each line needs to be enclosed by quotation marks. For example in \l qt.qdocconf: \code HTML.footer = "
Qt for Embedded Linux \n" \ ... "" \endcode The complete variable entry in \l qt.qdocconf provides the standard footer of the \l {http://qt.nokia.com/doc/4.0/index.html} {Qt Reference Documentation}. \target HTML.postheader-variable \section1 HTML.postheader The \c HTML.postheader variable defines the content of the generated HTML documentation's postheader. The header is rendered at the top of the generated documentation page. The variable's value is given as raw HTML enclosed by quotation marks. Note that if the value spans several lines, each line needs to be enclosed by quotation marks. For example in \l qt.qdocconf: \code HTML.postheader = "" \ "" \ "" \endcode The complete variable entry in \l qt.qdocconf provides the standard header of the \l {http://qt.nokia.com/doc/4.0/index.html} {Qt Reference Documentation}. \target HTML.style-variable \section1 HTML.style The HTML.style variable defines the style for the generated HTML documentation. The variable's value is given as raw HTML enclosed by quotation marks. Note that if the value spans several lines, each line needs to be enclosed by quotation marks. For example in \l qt.qdocconf: \code HTML.style = "h3.fn,span.fn" \ "{ margin-left: 1cm; text-indent: -1cm; }\n" \ "a:link { color: #004faf; text-decoration: none }\n" \ "a:visited" \ "{ color: #672967; text-decoration: none }\n" \ "td.postheader { font-family: sans-serif }\n" \ "tr.address { font-family: sans-serif }\n" \ "body { background: #ffffff; color: black; }" \endcode provides the HTML style for the \l {http://qt.nokia.com/doc/4.0/index.html} {Qt Reference Documentation}. \target HTML.stylesheets-variable \section1 HTML.stylesheets The HTML.stylesheets variable defines a list of stylesheets to use for the generated HTML documentation. Using separate stylesheets for the documentation makes it easier to customize and experiment with the style used once the contents has been generated. Typically, it is only necessary to define a single stylesheet for any set of documentation; for example: \code HTML.stylesheets = classic.css \endcode QDoc expects to find stylesheets in the directory containing the \l qt.qdocconf file, and it will copy those specified to the output directory alongside the HTML pages. */ /*! \page 25-qdoc-configuration-derivedprojects.html \previouspage HTML Specific Configuration Variables \contentspage Table of Contents \nextpage Compatibility Issues \title Supporting Derived Projects Some 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. \target description-variable \section1 description The description variable holds a short description of the associated project. See also \l project. \target indexes-variable \section1 indexes The \c indexes variable lists the index files that will be used to generate references. For example. to make a derived Qt project contain links to the Qt Reference documentation, you need to specify the associated index file: \code indexes = $QTDIR/doc/html/qt.index \endcode See also \l project and \l url. \target project-variable \section1 project The \c project variable provides a name for the project associated with the \c .qdocconf file. The project's name is used to form a file name for the associated project's \e index file. 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. \target url-variable \section1 url The \c url variable holds the base URL for the reference documentation associated with the current project. The URL is stored in the generated index file for the project. When we use the index on its own, QDoc will use this as the base URL when constructing links to classes, functions, and other things listed in the index. 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. \target howto \section1 How to Support Derived Projects This feature makes use of the comprehensive indexes generated by QDoc when it creates the Qt reference documentation. For example, \l qt.qdocconf (the configuration file for Qt) contains the following variable definitions: \code project = Qt description = Qt Reference Documentation url = http://qt.nokia.com/doc/4.0 ... \endcode The \l project variable name is used to form a file name for the index file; in this case the \c qt.index file is created. The \l url is stored in the index file. Later, when we use the index on its own, QDoc will use this as the base URL when constructing links to classes, functions, and other things listed in the index. In a mini-project, you can use an index file by defining an \l indexes configuration variable in your \c .qdocconf file. For example, you can create a \c qtmotif.qdocconf file to help you check the QtMotif documentation (which is part of Qt Solutions): \code include($QTDIR/tools/qdoc3/test/compat.qdocconf) project = QtMotif description = QtMotif Class Documentation url = http://www.trolltech.com/products/solutions/catalog/4/Migration/qtmotifextension indexes = $QTDIR/doc/html/qt.index outputdir = html headerdirs = src sourcedirs = src \ examples sources.fileextensions = "*.cpp *.qdoc *.doc" exampledirs = examples \endcode The code above requires that you run QDoc from the directory that contains this file. You need to include the compat.qdocconf file for compatibility reasons; this is further explained in the \l {Compatibility Issues} section. \bold {To resolve the actual links to Qt classes, the mini-project's \c .qdocconf file needs to assign a value to the \l indexes variable; \c $QTDIR/doc/html/qt.index makes sure that you always use the updated index file for the Qt documentation.} The only disadvantages with this approach are the extra file that QDoc has to generate and the time it takes to do so. Reading the index back again later isn't instantaneous either, but it's quicker than processing all the Qt classes each time you need to write a new document. */ /*! \page 26-qdoc-commands-compatibility.html \previouspage Supporting Derived Projects \contentspage Table of Contents \nextpage qt.qdocconf \title Compatibility Issues \section1 General Description \target reason Because QDoc evolves to suit our documentation needs, there can be some compatibility issues when converting to a new version. To allow you to proceed at your own speed when converting your qdoc comments to use new qdoc commands and formats, the ability to include a configuration file called \c {compat.qdocconf} is provided. A \c {compat.qdocconf} file is a separate configuration file, which you include in your main configuration file. It typically contains the mappings from old qdoc commands to new ones using \l {alias} and \l {22-qdoc-configuration-generalvariables.html#macro-variable} {macro} configuration variables. \section1 Qt Compatibility In Qt's documentation there still exist occurrences of old commands, and the Qt \l {qt.qdocconf} {configuration file} needs to include the compat.qdocconf file tailored for Qt. For more detailed information about the commands creating compatibility issues, see the \l {Command Comments} {command comments}. \section1 Qt's current compat.qdocconf file \quotefile files/compat.qdocconf \section1 Command Comments \table \header \o New Command \o Old Command \o Description \row \o \\i \target i-versus-e \o \\e \o Earlier we used the \\i command to indicate a list or table item, and the \\e command for rendering in italic. Now we want the \\i command to render in italic discarding the \\e command name. \bold {We still need to use the \\e command to render in italic in new documentation for \l {reason} {compatibility reasons}}. \row \o \\include \target include-versus-input \o \\input \o The \\include command was previously used to quote the complete contents of a source file, now we want to use the command to include separate documentation. That is the functionality of the old \\input command which name we want to discard. \bold {We still need to use the \\input command to include plain text in new documentation for \l {reason} {compatibility reasons}}. \row \o \\quotefile \target quotefile-versus-include \o \\include \o Earlier, we have used the \\quotefile command to quote from file, i.e. quote parts from file, and the \\include command to quote the entire file. Since we now want \\include to include separate documentation, we change the use of \\quotefile to quote a complete source file. \bold {We still need to use the \\include command to quote the entire contents of a source file in new documentation for \l {reason} {compatibility reasons}}. \row \o \\quotefromfile \target quotefromfile-versus-quotefile \o \\quotefile \o Earlier, we have used the \\quotefile command to quote from file, i.e. quote parts from file. Since we now want that command to quote an entire file, we introduce the new \\quotefromfile command to quote from file. \bold {Use \l {quotefromfile-command} {\\quotefromfile} to quote parts from a source file in new documentation}. \row \o \\o \target o-versus-i \o \\i \o Earlier we used the \\i command to indicate list items and table items. Since we now want the \\i command to render in italic instead, we introduce the new \\o command for this purpose. \bold {Use \l {o-command} {\\o} to indicate list and table items in new documentation}. \row \o \\quotation \target quotation-versus-quote \o \\quote \o These commands are equivalent, and represent a simple name change. \bold {Use \l {quotation} {\\quotation} in new documentation}. \row \o \\image \target image-versus-img \o \\img \o These commands are equivalent, and represent a simple name change. \bold {Use \l {image-command} {\\image} in new documentation}. \endtable */ /*! \page 27-qdoc-commmands-alphabetical.html \previouspage Introduction to QDoc \contentspage Table of Contents \nextpage Topic Commands \title The QDoc Commands This is a complete, alphabetized list of the QDoc commands. \list \o \l {04-qdoc-commands-textmarkup.html#a-command} {\\a} \o \l {11-qdoc-commands-specialcontent.html#abstract-command} {\\abstract} \o \l {06-qdoc-commands-includecodeinline.html#badcode-command} {\\badcode} \o \l {04-qdoc-commands-textmarkup.html#bold-command} {\\bold} \o \l {11-qdoc-commands-specialcontent.html#brief-command} {\\brief} \o \l {04-qdoc-commands-textmarkup.html#c-command} {\\c} \o \l {09-qdoc-commands-includingimages.html#caption-command} {\\caption} \o \l {05-qdoc-commands-documentstructure.html#chapter-command} {\\chapter} \o \l {13-qdoc-commands-topics.html#class-command} {\\class} \o \l {06-qdoc-commands-includecodeinline.html#code-command} {\\code} \o \l {07-0-qdoc-commands-includingexternalcode.html#codeline-command} {\\codeline}, \o \l {16-qdoc-commands-status.html#compat-command} {\\compat} \o \l {15-qdoc-commands-navigation.html#contentspage-command} {\\contentspage} \o \l {04-qdoc-commands-textmarkup.html#div-command} {\\div} \span {class="newStuff"} {(new)} \o \l {07-0-qdoc-commands-includingexternalcode.html#dots-command} {\\dots} \o \l {12-0-qdoc-commands-miscellaneous.html#else-command} {\\else} \o \l {12-0-qdoc-commands-miscellaneous.html#endif-command} {\\endif} \o \l {13-qdoc-commands-topics.html#enum-command} {\\enum} \o \l {13-qdoc-commands-topics.html#example-command} {\\example} \o \l {12-0-qdoc-commands-miscellaneous.html#expire-command} {\\expire} \o \l {13-qdoc-commands-topics.html#externalpage-command} {\\externalpage} \o \l {13-qdoc-commands-topics.html#fn-command} {\\fn} \o \l {11-qdoc-commands-specialcontent.html#footnote-command} {\\footnote} \o \l {12-0-qdoc-commands-miscellaneous.html#generatelist-command} {\\generatelist} \o \l {13-qdoc-commands-topics.html#group-command} {\\group} \o \l {10-qdoc-commands-tablesandlists.html#header-command} {\\header} \o \l {13-qdoc-commands-topics.html#headerfile-command} {\\headerfile} \o \l {04-qdoc-commands-textmarkup.html#i-command} {\\i} \o \l {12-0-qdoc-commands-miscellaneous.html#if-command} {\\if} \o \l {09-qdoc-commands-includingimages.html#image-command} {\\image} \o \l {12-0-qdoc-commands-miscellaneous.html#include-command} {\\include} \o \l {15-qdoc-commands-navigation.html#indexpage-command} {\\indexpage} \o \l {19-qdoc-commands-grouping.html#ingroup-command} {\\ingroup} \o \l {19-qdoc-commands-grouping.html#inmodule-command} {\\inmodule} \o \l {09-qdoc-commands-includingimages.html#inlineimage-command} {\\inlineimage} \o \l {16-qdoc-commands-status.html#internal-command} {\\internal} \o \l {08-qdoc-commands-creatinglinks.html#keyword-command} {\\keyword} \o \l {08-qdoc-commands-creatinglinks.html#l-command} {\\l} \o \l {11-qdoc-commands-specialcontent.html#legalese-command} {\\legalese} \o \l {10-qdoc-commands-tablesandlists.html#list-command} {\\list} \o \l {13-qdoc-commands-topics.html#macro-command} {\\macro} \o \l {19-qdoc-commands-grouping.html#mainclass-command} {\\mainclass} \o \l {12-0-qdoc-commands-miscellaneous.html#meta-command} {\\meta} \o \l {13-qdoc-commands-topics.html#module-command} {\\module} \o \l {13-qdoc-commands-topics.html#namespace-command} {\\namespace} \o \l {15-qdoc-commands-navigation.html#nextpage-command} {\\nextpage} \o \l {06-qdoc-commands-includecodeinline.html#newcode-command} {\\newcode} \o \l {17-qdoc-commands-thread.html#nonreentrant-command} {\\nonreentrant} \o \l {10-qdoc-commands-tablesandlists.html#o-command} {\\o} \o \l {16-qdoc-commands-status.html#obsolete-command} {\\obsolete} \o \l {06-qdoc-commands-includecodeinline.html#oldcode-command} {\\oldcode} \o \l {12-0-qdoc-commands-miscellaneous.html#omit-command} {\\omit} \o \l {10-qdoc-commands-tablesandlists.html#omitvalue-command} {\\omitvalue} \o \l {18-qdoc-commands-relating.html#overload-command} {\\overload} \o \l {13-qdoc-commands-topics.html#page-command} {\\page} \o \l {05-qdoc-commands-documentstructure.html#part-command} {\\part} \o \l {16-qdoc-commands-status.html#preliminary-command} {\\preliminary} \o \l {15-qdoc-commands-navigation.html#previouspage-command} {\\previouspage} \o \l {07-0-qdoc-commands-includingexternalcode.html#printline-command} {\\printline} \o \l {07-0-qdoc-commands-includingexternalcode.html#printto-command} {\\printto} \o \l {07-0-qdoc-commands-includingexternalcode.html#printuntil-command} {\\printuntil} \o \l {13-qdoc-commands-topics.html#property-command} {\\property} \o \l {11-qdoc-commands-specialcontent.html#quotation-command} {\\quotation} \o \l {07-0-qdoc-commands-includingexternalcode.html#quotefile-command} {\\quotefile} \o \l {07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command} {\\quotefromfile} \o \l {12-0-qdoc-commands-miscellaneous.html#raw-command} {\\raw} \span {class="newStuff"} {(avoid)} \o \l {17-qdoc-commands-thread.html#reentrant-command} {\\reentrant} \o \l {18-qdoc-commands-relating.html#reimp-command} {\\reimp} \o \l {18-qdoc-commands-relating.html#relates-command} {\\relates} \o \l {10-qdoc-commands-tablesandlists.html#row-command} {\\row} \o \l {08-qdoc-commands-creatinglinks.html#sa-command} {\\sa} \o \l {05-qdoc-commands-documentstructure.html#sectionOne-command} {\\section1} \o \l {05-qdoc-commands-documentstructure.html#sectionTwo-command} {\\section2} \o \l {05-qdoc-commands-documentstructure.html#sectionThree-command} {\\section3} \o \l {05-qdoc-commands-documentstructure.html#sectionFour-command} {\\section4} \o \l {13-qdoc-commands-topics.html#service-command} {\\service} \o \l {16-qdoc-commands-status.html#since-command} {\\since} \o \l {07-0-qdoc-commands-includingexternalcode.html#skipline-command} {\\skipline} \o \l {07-0-qdoc-commands-includingexternalcode.html#skipto-command} {\\skipto} \o \l {07-0-qdoc-commands-includingexternalcode.html#skipuntil-command} {\\skipuntil} \o \l {07-0-qdoc-commands-includingexternalcode.html#snippet-command} {\\snippet}, \o \l {04-qdoc-commands-textmarkup.html#span-command} {\\span} \span {class="newStuff"} {(new)} \o \l {15-qdoc-commands-navigation.html#startpage-command} {\\startpage} \o \l {04-qdoc-commands-textmarkup.html#sub-command} {\\sub} \o \l {20-qdoc-commands-namingthings.html#subtitle-command} {\\subtitle} \o \l {04-qdoc-commands-textmarkup.html#sup-command} {\\sup} \o \l {10-qdoc-commands-tablesandlists.html#table-command} {\\table} \o \l {11-qdoc-commands-specialcontent.html#tableofcontents-command} {\\tableofcontents} \o \l {08-qdoc-commands-creatinglinks.html#target-command} {\\target} \o \l {17-qdoc-commands-thread.html#threadsafe-command} {\\threadsafe} \o \l {20-qdoc-commands-namingthings.html#title-command} {\\title} \o \l {04-qdoc-commands-textmarkup.html#tt-command} {\\tt} \o \l {13-qdoc-commands-topics.html#typedef-command} {\\typedef} \o \l {04-qdoc-commands-textmarkup.html#underline-command} {\\underline} \o \l {13-qdoc-commands-topics.html#variable-command} {\\variable} \o \l {10-qdoc-commands-tablesandlists.html#value-command} {\\value} \o \l {11-qdoc-commands-specialcontent.html#warning-command} {\\warning} \endlist */ /*! \externalpage http://qt.nokia.com/about \title About Qt */