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 QDoc Manual \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. \b{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 {newcode-command} {\\newcode} or \l {oldcode-command} {\\oldcode} commands, QDoc removes all indentation that is common for the verbatim code blocks within a \c{/}\c{*!} ... \c{*}\c{/} comment before it adds the standard indentation. For that reason the recommended style is to use 8 spaces for the verbatim code contained within these commands \note This doesn't apply to externally quoted code using the \l {quotefromfile-command} {\\quotefromfile} or \l {quotefile-command} {\\quotefile} command. \code / *! \code #include| Qt | Qt Creator |
|---|---|
|
|
|
|
|
| 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 \b{} 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 \b{\\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 \b{} tag in your style.css file. \target footnote-command \section1 \\footnote The \\footnote and \\endfootnote commands delimit a footnote. The footnote is rendered at the bottom of the page. \warning The \b{\\footnote} and \b{\\endfootnote} commands have not been implemented. The footnote is rendered as a regular HTML paragraph. \target tableofcontents-command \section1 \\tableofcontents The \\tableofcontents command has been disabled because QDoc now generates a table of contents automatically. The automatically generated table of contents appears in the upper righthand corner of the page. \target brief-command \section1 \\brief The \\brief command introduces a one-sentence description of a class, namespace, header file, property or variable. The brief text is used to introduce the documentation of the associated object, and in lists generated using the \l {generatelist-command} {\\generatelist} command and the \l {annotatedlist-command} {\\annotatedlist} command. The \\brief command can be used in two significant different ways: \l {brief class} {One for classes, namespaces and header files}, and \l {brief-property} {one for properties and variables}. \target brief-property When the \\brief command is used to describe a property or a variable, the brief text must be a sentence fragment starting with "whether" (for a boolean property or variable) or starting with "the" (for any other property or variable). For example the boolean QWidget::isWindow property: \code / *! \property QWidget::isActiveWindow \brief whether this widget's window is the active window The active window is the window that contains the widget that has keyboard focus. When popup windows are visible, this property is 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 \li \b {const QRect & geometry () const} \li \b {void setGeometry ( int x, int y, int w, int h )} \li \b {void setGeometry ( const QRect & )} \endlist See also \l {QWidget::frameGeometry()} {frameGeometry()}, \l {QWidget::rect()} {rect()}, ... \endquotation \target brief class When the \\brief command is used to describe a class, 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. \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 \li 52 properties inherited from QWidget \li 1 property inherited from QObject \endlist \raw HTMLPublic Functions
\endraw \list \li \l {constructor} {PreviewWindow}(QWidget *parent = 0) \li void \l {function} {setWindowFlags}(Qt::WindowFlags flags) \endlist \list \li 183 public functions inherited from QWidget \li 28 public functions inherited from QObject \endlist \raw HTMLPublic Slots
\endraw \list \li 17 public slots inherited from QWidget \li 1 public slot inherited from QObject \endlist \raw HTMLAdditional Inherited Members
\endraw \list \li 1 signal inherited from QWidget \li 1 signal inherited from QObject \li 4 static public members inherited from QWidget \li 4 static public members inherited from QObject \li 39 protected functions inherited from QWidget \li 7 protected functions inherited from QObject \endlist \target preview window \raw HTML
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 license agreement. In the generated HTML, the delimited text is surrounded by a \b { } and \b {} 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. \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 QDoc Manual \nextpage Creating DITA Maps \title Miscellaneous These commands provide miscellaneous functions connected to the visual appearance of the documentation, and to the process of generating the documentation. \target annotatedlist-command \section1 \\annotatedlist The \\annotatedlist command expands to a list of the members of a group, each member listed with its \e {brief} text. Below is an example from the Qt Reference Documentation: \code / *! ... \section1 Drag and Drop Classes These classes deal with drag and drop and the necessary mime type encoding and decoding. \annotatedlist draganddrop * / \endcode This generates a list of all the C++ classes and/or QML types in the \e{draganddrop} group. A C++ class or QML type in the \e{draganddrop} group will have \e{\\ingroup draganddrop} in its \e{\\class} or \e{\\qmltype} comment. \target generatelist-command \section1 \\generatelist The \\generatelist command expands to a list of 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}. \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 \li QDial \li Rounded range control (like a speedometer or potentiometer) \row \li QDialog \li The base class of dialog windows \row \li QDir \li Access to directory structures and their contents \endtable A C++ class is documented with the \l {class-command} {\\class} command. The annotation for the class is taken from the argument of the class comment's \l {brief-command} {\\brief} command. \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 Digia and others originated from third parties. This page lists the licenses used, names the authors, and links to the places where it is used. Digia gratefully acknowledges these and other contributions to Qt. We recommend that programs that use Qt also acknowledge these contributions, and quote these license statements in an appendix to the documentation. See also: \l{Licenses for Fonts Used in Qt for Embedded Linux} \generatelist legalese * / \endcode \section2 \c mainclasses The \c mainclasses argument tells QDoc to generate an alphabetical list of the main classes. A class is marked as a main class by including a \l {mainclass-command} {\\mainclass} command in the \\class comment. \note The Qt documentation no longer includes a main classes page, but you can generate one for your main classes if you want it. \section2 \c overviews The \c overviews argument is used to tell QDoc to generate a list by concatenating the contents of all the \l {group-command} {\\group} pages. Qt uses it to generate the \l {overviews.html} {overviews} page this way: \code / *! \page overviews.html \title All Overviews and HOWTOs \generatelist overviews * / \endcode \section2 \c related The \c related argument is used in combination with the \l {group-command} {\\group} and \l {ingroup-command} {\\ingroup} commands to list all the overviews related to a specified group. For example, the page for the \l {Programming with Qt} {Programming with Qt} page is generated this way: \code / *! \group qt-basic-concepts \title Programming with Qt \brief The basic architecture of the Qt cross-platform application and UI framework. Qt is a cross-platform application and UI framework for writing web-enabled applications for desktop, mobile, and embedded operating systems. This page contains links to articles and overviews explaining key components and techniuqes used in Qt development. \generatelist {related} * / \endcode Each page listed on this group page contains the command: \code \ingroup qt-basic-concepts \endcode \section2 \c service The \c service argument tells QDoc to generate an alphabetical list of the services. Each service name is a link to the service's reference documentation. A service is identified with the \l {service-command} {\\service} command. \note This command and the \l {service-command} {\\service} command are not used in the Qt documentation. \target if-command \section1 \\if The \\if command and the corresponding \\endif command enclose parts of a QDoc comment that only will be included if the condition specified by the command's argument is true. The command reads the rest of the line and parses it as an C++ #if statement. \code / *! \if defined(opensourceedition) \b{Note:} This edition is for the development of \l{Qt Open Source Edition} {Free and Open Source} software only; see \l{Qt Commercial Editions}. \endif * / \endcode This QDoc comment will only be rendered if the \c opensourceedition preprocessor symbol is defined, and specified in the \l {defines-variable} {defines} variable in the configuration file to make QDoc process the code within #ifdef and #endif: \code defines = opensourceedition \endcode You can also define the preprocessor symbol manually on the command line. For more information see the documentation of the \l {defines-variable} {defines} variable. See also \l{endif-command} {\\endif}, \l{else-command} {\\else}, \l {defines-variable} {defines} and \l {falsehoods-variable} {falsehoods}. \target endif-command \section1 \\endif The \\endif command and the corresponding \\if command enclose parts of a QDoc comment that will be included if the condition specified by the \l {if-command} {\\if} command's argument is true. For more information, see the documentation of the \l {if-command} {\\if} command. See also \l{if-command} {\\if}, \l{else-command} {\\else}, \l {defines-variable} {defines} and \l {falsehoods-variable} {falsehoods}. \target else-command \section1 \\else The \\else command specifies an alternative if the condition in the \l {if-command} {\\if} command is false. The \\else command can only be used within \l {if-command} {\\if...\\endif} commands, but is useful when there is only two alternatives. \code / *! The Qt 3 support library is provided to keep old source code working. In addition to the \c Qt3Support classes, Qt 4 provides compatibility functions when it's possible for an old API to cohabit with the new one. \if !defined(QT3_SUPPORT) \if defined(QT3_SUPPORTWARNINGS) The compiler emits a warning when a compatibility function is called. (This works only with GCC 3.2+ and MSVC 7.) \else To use the Qt 3 support library, you need to have the line QT += qt3support in your .pro file (qmake automatically define the QT3_SUPPORT symbol, turning on compatibility function support). You can also define the symbol manually (e.g., if you don't want to link against the \c Qt3Support library), or you can define \c QT3_SUPPORT_WARNINGS instead, telling the compiler to emit a warning when a compatibility function is called. (This works only with GCC 3.2+ and MSVC 7.) \endif \endif * / \endcode If the \c QT3_SUPPORT is defined, the comment will be rendered like this: \quotation The Qt 3 support library is provided to keep old source code working. In addition to the Qt3Support classes, Qt 4 provides compatibility functions when it's possible for an old API to cohabit with the new one. \endquotation If \c QT3_SUPPORT is not defined but \c QT3_SUPPORT_WARNINGS is defined, the comment will be rendered like this: \quotation The Qt 3 support library is provided to keep old source code working. In addition to the Qt3Support classes, Qt 4 provides compatibility functions when it's possible for an old API to cohabit with the new one. The compiler emits a warning when a compatibility function is called. (This works only with GCC 3.2+ and MSVC 7.) \endquotation If none of the symbols are defined, the comment will be rendered as \quotation The Qt 3 support library is provided to keep old source code working. In addition to the \c Qt3Support classes, Qt 4 provides compatibility functions when it's possible for an old API to cohabit with the new one. To use the Qt 3 support library, you need to have the line QT += qt3support in your .pro file (qmake automatically define the QT3_SUPPORT symbol, turning on compatibility function support). You can also define the symbol manually (e.g., if you don't want to link against the \c Qt3Support library), or you can define \c QT3_SUPPORT_WARNINGS instead, telling the compiler to emit a warning when a compatibility function is called. (This works only with GCC 3.2+ and MSVC 7.) \endquotation See also \l{if-command} {\\if}, \l{endif-command} {\\endif}, \l {defines-variable} {defines} and \l {falsehoods-variable} {falsehoods}. \target include-command \section1 \\include The \\include command sends all or part of the file specified by its first argument to the QDoc input stream to be processed as a qdoc comment snippet. This command is often assigned the alias, \e {input}, in the QDoc configuration file, e.g. \e {alias.include = input}. The command is useful when some snippet of commands and text is to be used in multiple places in the documentation. In that case, move the snippet into a separate file and use the \\include command wherever you want to insert the snippet into the documentation. To prevent QDoc from reading the file as a stand-alone page of documentation, we recommend that you use the \c .qdocinc extension for these \e {include} files. The command can have either one or two arguments. The first argument is always a file name. The contents of the file must be QDoc input, i.e. a sequence of QDoc commands and text, but without the enclosing qdoc comment \c{/}\c{*!} ... \c{*}\c{/} delimeters. If you want to include the entire named file, don't use the second argument. If you want to include only part of the file, see the \l{2-argument-form}{two argument form} below. Here is an example of the one argument form: \code / *! \page corefeatures.html \title Core Features \include examples/signalandslots.qdocinc \include examples/objectmodel.qdocinc \include examples/layoutmanagement.qdocinc * / \endcode Here are links to the \c .qdocinc files used above: \l{signalandslots.qdocinc}, \l{objectmodel.qdocinc}, \l{layoutmanagement.qdocinc}. QDoc renders this page \l{corefeatures.html} {as shown here}. \target 2-argument-form} \section2 \\include filename snippet-identifier It is kind of a pain to make a separate \c .qdocinc file for every QDoc include snippet you want to use in multiple places in the documentation, especially given that you probably have to put the copyright/license notice in every one of these files. So if you have lots of these include snippets, you can put them all in a single file if you want, and surround each one with: \code //! [snippet-id1] QDoc commands and text... //! [snippet-id1] //! [snippet-id2] More QDoc commands and text... //! [snippet-id2] \endcode Then you can use the two-argument form of the command: \code \input examples/signalandslots.qdocinc snippet-id2 \input examples/objectmodel.qdocinc another-snippet-id \endcode It works as expected. The sequence of QDoc commands and text found between the two tags with the same name as the second argument is sent to the QDoc input stream. You can even nest these snippets, although it's not clear why you would want to do that. \target meta-command \section1 \\meta The \\meta command is mainly used for including metadata in DITA XML files. It is also used when generating HTML output for specifying the \e maintainer(s) of a C++ class. The command has two arguments: The first argument is the name of the metadata attribute you wish to set, and the second argument is the value for the attribute. Each argument should be enclosed in curly brackets, as shown in this example: \code / *! \class QWidget \brief The QWidget class is the base class of all user interface objects. \ingroup basicwidgets \meta {technology} {User Interface} \meta {platform} {OS X 10.6} \meta {platform} {Symbian} \meta {platform} {MeeGo} \meta {audience} {user} \meta {audience} {programmer} \meta {audience} {designer} * / \endcode When running QDoc to generate HTML, the example above will have no effect on the generated output, but if you run QDoc to generate DITA XML, the example will generate the following: \codeCopyright 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.
QWidget the QWidget class is the base class of all user interface objects. \endcode In the example output, several values have been set using defualt values obtained from the QDoc configuration file. See \l {Generating DITA XML Output} for details. \target omit-command \section1 \\omit The \\omit command and the correspondning \\endomit command delimit parts of the documentation that you want QDoc to skip. For example: \code / *! \table \row \li Basic Widgets \li Basic GUI widgets such as buttons, comboboxes and scrollbars. \omit \row \li Component Model \li Interfaces and helper classes for the Qt Component Model. \endomit \row \li Database Classes \li Database related classes, e.g. for SQL databases. \endtable * / \endcode QDoc renders this as: \raw HTML Qt Development Frameworks Qt Project Qt Project Class reference Qt Reference Documentation QtGui \endraw \target raw-command \section1 \\raw \span {class="newStuff"} {(avoid)} The \\raw command and the corresponding \\endraw command delimit a block of raw mark-up language code. \note Avoid using this command if possible, because it generates DITA XML code that causes problems. If you are trying to generate special table or list behavior, try to get the behavior you want using the \l {span-command} {\\span} and \l {div-command} {\\div} commands in your \l {table-command} {\\table} or \l {list-command} {\\list}. The command takes an argument specifying the code's format; currently the only supported format is HTML. The \\raw command is useful if you want some special HTML effects in your documentation. \code / *! Qt has some predefined QColor objects. \raw HTML
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. \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 QDoc Manual \title signalandslots.qdocinc \quotefile examples/signalandslots.qdocinc */ /*! \page 12-2-objectmodel.html \previouspage Miscellaneous \contentspage QDoc Manual \title objectmodel.qdocinc \quotefile examples/objectmodel.qdocinc */ /*! \page 12-3-layoutmanagement.html \previouspage Miscellaneous \contentspage QDoc Manual \title layoutmanagement.qdocinc \quotefile examples/layoutmanagement.qdocinc */ /*! \page 13-qdoc-commands-topics.html \previouspage Command Index \contentspage QDoc Manual \nextpage Context Commands \title Topic Commands A topic command tells QDoc which source code element is being documented. Some topic commands allow you to create documentation pages that aren't tied to any underlying source code element. When QDoc processes a QDoc comment, it tries to connect the comment to an element in the source code by first looking for a topic command that names the source code element. If there is no topic command, QDoc tries to connect the comment to the source code element that immediately follows the comment. If it can't do either of these and if there is no topic command that indicates the comment does not have an underlying source code element (e.g. \l{page-command} {\\page}), then the comment is discarded. \target topic argument The name of the entity being documented is usually the only argument for a topic command. Use the complete name. Sometimes there can be a second parameter in the argument. See e.g. \l {page-command} {\\page}. \code \enum QComboBox::InsertPolicy \endcode The \l {fn-command} {\\fn} command is a special case. For the \l {fn-command} {\\fn} command, use the function's signature including the class qualifier. \code \fn void QGraphicsWidget::setWindowFlags(Qt::WindowFlags wFlags) \endcode A topic command can appear anywhere in a comment but must stand alone on its own line. Best practice is to let the topic commend be the first line of the comment. If the argument spans several lines, make sure that each line (except the last one) is ended with a backslash. In addition QDoc counts parentheses, which means that if it encounters a '(' it considers everything until the closing ')' as its argument. If a topic command is repeated with different arguments, the same documentation will appear for both the units. \code / *! \fn void PreviewWindow::setWindowFlags() \fn void ControllerWindow::setWindowFlags() Sets the widgets flags using the QWidget::setWindowFlags() function. Then runs through the available window flags, creating a text that contains the names of the flags that matches the flags parameter, displaying the text in the widgets text editor. * / \endcode The \c PreviewWindow::setWindowFlags() and \c ControllerWindow::setWindowFlags() functions will get the same documentation. \target class-command \section1 \\class The \\class command is for documenting a C++ class. The argument is the complete name of the class. The command tells QDoc that a class is part of the public API, and lets you enter a detailed description. \code / *! \class QMap::iterator \brief The QMap::iterator class provides an STL-style non-const iterator for QMap and QMultiMap. QMap features both \l{STL-style iterators} and \l{Java-style iterators}. The STL-style iterators ... * / \endcode The HTML documentation for the named class is written to a \c{.html} file named from the class name, in lower case, and with the double colon qulifier(s) replaced with '-'. For example, the documentation for the \c QMap::Iterator class is written to \c qmap-iterator.html. \target framework The file contains the class description from the \\class comment, plus the documentation generated from QDoc comments for all the class members, i.e. a list of the class's types, properties, functions, signals, and slots. In addition to the detailed description of the class, the \\class comment typically contains a \l {brief-command} {\\brief} command and one or more \l{Markup Commands}. See the \\class command for any of the Qt class for examples. Here is a very simple example: \code / *! \class PreviewWindow \brief The PreviewWindow class is a custom widget displaying the names of its currently set window flags in a read-only text editor. \ingroup miscellaneous The PreviewWindow class inherits QWidget. The widget displays the names of its window flags set with the \l {function} {setWindowFlags()} function. It is also provided with a QPushButton that closes the window. ... \sa QWidget * / \endcode The way QDoc renders this \\class will depend a lot on your \c {style.css} file, but the general outline of the class reference page will look like this: \quotation \raw 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 \li 52 properties inherited from QWidget \li 1 property inherited from QObject \endlist \raw HTMLPublic Functions
\endraw \list \li \l {constructor} {PreviewWindow}(QWidget *parent = 0) \li void \l {function} {setWindowFlags}(Qt::WindowFlags flags) \endlist \list \li 183 public functions inherited from QWidget \li 28 public functions inherited from QObject \endlist \raw HTMLPublic Slots
\endraw \list \li 17 public slots inherited from QWidget \li 1 public slot inherited from QObject \endlist \raw HTMLAdditional Inherited Members
\endraw \list \li 1 signal inherited from QWidget \li 1 signal inherited from QObject \li 4 static public members inherited from QWidget \li 4 static public members inherited from QObject \li 39 protected functions inherited from QWidget \li 7 protected functions inherited from QObject \endlist \target preview window \raw HTML
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 \li \l{http://qt-project.org/doc/qt-5.0/qtwidgets/widgets-imageviewer-imageviewer-cpp.html} {widgets/imageviewer/imageviewer.cpp} \li \l{http://qt-project.org/doc/qt-5.0/qtwidgets/widgets-imageviewer-imageviewer-h.html} {widgets/imageviewer/imageviewer.h} \li \l{http://qt-project.org/doc/qt-5.0/qtwidgets/widgets-imageviewer-main-cpp.html} {widgets/imageviewer/main.cpp} \endlist The example shows how to combine QLabel and QScrollArea to display an image. ... \endquotation \target externalpage-command \section1 \\externalpage The \\externalpage command assigns a title to an external URL. \code / *! \externalpage http://qt-project.org/doc/ \title Qt Documentation Site * / \endcode This allows you to include a link to the external page in your documentation this way: \code / *! At the \l {Qt Documentation Site} you can find the latest documentation for Qt, Qt Creator, the Qt SDK and much more. * / \endcode QDoc renders this as: \quotation At the \l {http://qt-project.org/doc/}{Qt Documentation Site} you can find the latest documentation for Qt, Qt Creator, the Qt SDK and much more. \endquotation To achieve the same result without using the \\externalpage command, you would have to hard code the address into your documentation: \code / *! At the \l {http://qt-project.org/doc/}{Qt Documentation Site} you can find the latest documentation for Qt, Qt Creator, the Qt SDK and much more. * / \endcode The \\externalpage command makes it easier to maintain the documentation. If the address changes, you only need to change the argument of the \\externalpage command. \target fn-command \section1 \\fn (function) The \\fn command is for documenting a function. The argument is the function's signature, including its return type, const-ness, and list of formal arguments with types. If the named function doesn't exist, QDoc emits a warning. \note The \\fn command is QDoc's default command, i.e. when no topic command can be found in a QDoc comment, QDoc tries to tie the documentation to the following code as if it is the documentation for a function. Hence, it is normally not necessary to include this command when documenting a function, if the function's QDoc comment is written immediately above the function implementation in the \c .cpp file. But it must be present when documenting an inline function in the \c .cpp file that is implemented in the \c .h file. \code / *! \fn bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const Returns true if this toolbar is dockable in the given \a area; otherwise returns false. * / \endcode QDoc renders this as: \quotation \raw HTML 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. \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. \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 argument. The documentation for a function, type, or macro that is declared in the header file being documented is included in the header file page using the \l {relates-command} {\\relates} command. If the argument doesn't exist as a header file, the \\headerfile command creates a documentation page for the header file anyway. \code / *! \headerfile
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 documenting 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 Qt Network Module \brief The Qt Network 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 QNetworkAccessManager that implements 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 Qt Network module offers classes that allow you to write TCP/IP clients and servers.\l {module details} {More...} \raw HTML
Qt Network Module
QAbstractSocket The base functionality common to all socket types QFtp Implementation of the FTP protocol ... ...
\endraw \target module details \raw HTMLDetailed Description
The Qt Network 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 QNetworkAccessManager that implements 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. \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 can consist of two parts separated by a space. The first part is the name of the file where QDoc should store the page. The second part, if present, is a word that specifies the page type. Currently, the second part can be one of the following list of words: \list \li faq - A frequently asked question. \li howto - A user guide for how to use some component of the software. \li example - A page that describes a working example. \li overview - For text pages that provide an overview of some important subject. \li tutorial - For text pages that are part of a tutorial. \li api - This is the type of page used for C++ class references and QML type references, etc. You should never use this one for the pages you write, because this one is reserved for qdoc. \endlist The page title is set using the \l {title-command} {\\title} command. \code / *! \page aboutqt.html \title About Qt Qt 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. Qt provides application developers with all the functionality needed to build applications with state-of-the-art graphical user interfaces. Qt is fully object-oriented, easily extensible, and allows true component programming. ... * / \endcode QDoc renders this page in \c {aboutqt.html}. \target property-command \section1 \\property The \\property command is for documenting a Qt property. The argument is the full property name. A property is defined using the Q_PROPERTY() macro. The macro takes as arguments the property's name and its set, reset and get functions. \code Q_PROPERTY(QString state READ state WRITE setState) \endcode The set, reset and get functions don't need to be documented, documenting the property is sufficient. QDoc will generate a list of the access function that will appear in the property documentation which in turn will be located in the documentation of the class that defines the property. The \\property command comment typically includes a \l {brief-command} {\\brief} command. For properties the \l {brief-command} {\\brief} command's argument is a sentence fragment that will be included in a one line description of the property. The command follows the same rules for the \l {brief-property} {description} as the \l {variable-command} {\\variable} command. \code / *! \property QPushButton::flat \brief whether the border is disabled This property's default is false. * / \endcode QDoc includes this in \c {qpushbutton.html} like this: \quotation \raw HTMLflat : bool
\endraw This property holds whether the border is disabled. This property's default is false. Access functions: \list \li \b { bool isFlat () const} \li \b { 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 \li \b { int width () const} \endlist See also \l{QWidget::geometry} {geometry}, \l{QWidget::height} {height}, and \l{QWidget::size} {size}. \endquotation \target service-command \section1 \\service The \\service command tells QDoc that a class is a service class and names the service. The command takes two arguments, the name of the class and the name of the service. Currently, this command is not used in the Qt documentation. \code / *! \service TimeService Time ... * / class TimeService : public QCopObjectService { ... } \endcode See also \l {class-command} {\\class} and \l {generatelist-command} {\\generatelist}. \target qmlattachedproperty-command \section1 \\qmlattachedproperty The \\qmlattachedproperty command is for documenting a QML property that will be attached to some QML type. See \l{http://qt-project.org/doc/qt-4.7/qdeclarativeintroduction.html#attached-properties} {Attached Properties}. The argument is the rest of the line. The argument text should be the property type, followed by the QML element name where the property is being declared, the \c{::} qualifier, and finally the property name. If we have a QML attached property named \c isCurrentItem in QML \c ListView, and the property has type \c {bool}, the \\qmlattachedproperty for it would look like this: \code / *! \qmlattachedproperty bool ListView::isCurrentItem This attached property is true if this delegate is the current item; otherwise false. It is attached to each instance of the delegate. This property may be used to adjust the appearance of the current item, for example: \snippet doc/src/snippets/declarative/listview/listview.qml isCurrentItem * / \endcode QDoc includes this attached property on the QML reference page for the \l{http://qt-project.org/doc/qt-4.7/qml-listview.html#isCurrentItem-prop} {ListView} element. \target qmlattachedsignal-command \section1 \\qmlattachedsignal The \\qmlattachedsignal command is for documenting an attachable \l{http://qt-project.org/doc/qt-4.7/qdeclarativeintroduction.html#signal-handlers} {signal handler}. The \\qmlattachedsignal command is used just like the \l{qmlsignal-command} {\\qmlsignal} command. The argument is the rest of the line. It should be the name of the QML type where the signal handler is declared, the \c{::} qualifier, and finally the signal handler name. If we have a QML attached signal handler named \c onAdd() in the \c GridView element, the \\qmlattachedsignal for it would look like this: \code / *! \qmlattachedsignal GridView::onAdd() This attached handler is called immediately after an item is added to the view. * / \endcode QDoc includes this documentation on the QML reference page for the \l{http://qt-project.org/doc/qt-4.7/qml-gridview.html#onAdd-signal} {GridView} element. \target qmlbasictype-command \section1 \\qmlbasictype The \\qmlbasictype command is for documenting a basic type for QML. The argument is the type name. The type must be included in the QML basic types group using the \l{ingroup-command}{\\ingroup} command as shown below. This will cause QDoc to include the documentation for the type on the \l{http://qt-project.org/doc/qt-4.7/qdeclarativebasictypes.html} {QML Basic Types} page. The \l{brief-command} {\\brief} command is also required, because it appears on the \l{http://qt-project.org/doc/qt-4.7/qdeclarativebasictypes.html} {QML Basic Types} page as well. \code / *! \qmlbasictype int \ingroup qmlbasictypes \brief An integer is a whole number, e.g. 0, 10, or -20. An integer is a whole number, e.g. 0, 10, or -20. The possible \c int values range from around -2000000000 to around 2000000000, although most elements will only accept a reduced range (which they mention in their documentation). Example: \qml Item { width: 100; height: 200 } \endqml \sa {QML Basic Types} * / \endcode QDoc outputs this as \l{http://qt-project.org/doc/qt-4.7/qml-int.html} {qml-int.html}. \target qmlclass-command \section1 \\qmlclass This command is deprecated. Use \l{qmltype-command} {\\qmltype} instead. The \\qmlclass command is for documenting a QML type that is instantiated by a C++ class. The command has two arguments. The first argument is the name of the QML type. The second argument is the name of the C++ class that instantiates the QML type. \code / *! \qmlclass Transform QGraphicsTransform \ingroup qml-transform-elements \since 4.7 \brief The Transform elements provide a way of building advanced transformations on Items. The Transform element is a base type which cannot be instantiated directly. The following concrete Transform types are available: \list \li \l Rotation \li \l Scale \li \l Translate \endlist The Transform elements let you create and control advanced transformations that can be configured independently using specialized properties. You can assign any number of Transform elements to an \l Item. Each Transform is applied in order, one at a time. * / \endcode This example generates the \l {http://qt-project.org/doc/qt-4.7/qml-transform.html} {QML Transform} page. The \\qmlclass comment should include the \l {since-command} {\\since} command, because all QML types are new. It should also include the \l{brief-command} {\\brief} command. And if a type is a member of a group of QML types, it should also include one or more \l{ingroup-command} {\\ingroup} commands. \target qmlmethod-command \section1 \\qmlmethod The \\qmlmethod command is for documenting a QML method. The argument is the complete method signature, including return type and parameter names and types. \code / *! \qmlmethod void TextInput::select(int start, int end) Causes the text from \a start to \a end to be selected. If either start or end is out of range, the selection is not changed. After calling this, selectionStart will become the lesser and selectionEnd will become the greater (regardless of the order passed to this method). \sa selectionStart, selectionEnd * / \endcode QDoc includes this documentation on the element refence page for the \l{http://qt-project.org/doc/qt-4.7/qml-textinput.html#select-method} {TextInput} element. \target qmltype-command \section1 \\qmltype The \\qmltype command is for documenting a QML type. The command has one argument, which is the name of the QML type. If the QML type is instantiated by a C++ class, that class must be specified using the \l{instantiates-command} {\\instantiates} context command. \code / *! \qmltype Transform \instantiates QGraphicsTransform \ingroup qml-transform-elements \since 4.7 \brief The Transform elements provide a way to build advanced transformations on Items. The Transform element is a base type which cannot be instantiated directly. The concrete Transform types are: \list \li \l Rotation \li \l Scale \li \l Translate \endlist The Transform elements let you create and control advanced transformations that can be configured independently using specialized properties. You can assign any number of Transform elements to an \l Item. Each Transform is applied in order, one at a time. * / \endcode The example generates the \l {http://qt-project.org/doc/qt-4.7/qml-transform.html} {QML Transform} page. The \e{\\qmltype} comment includes \l{instantiates-command} {\\instantiates} to specify that a Transform is instantiated by the C++ class QGraphicsTransform. A \\qmltype comment should always include a \l {since-command} {\\since} command, because all QML types are new. It should also include a \l{brief-command} {\\brief} description. And if a QML type is a member of a group of QML types, the \\qmltype comment should include one or more \l{ingroup-command} {\\ingroup} commands. \target qmlmethod-command \section1 \\qmlmethod The \\qmlmethod command is for documenting a QML method. The argument is the complete method signature, including return type and parameter names and types. \code / *! \qmlmethod void TextInput::select(int start, int end) Causes the text from \a start to \a end to be selected. If either start or end is out of range, the selection is not changed. After calling this, selectionStart will become the lesser and selectionEnd will become the greater (regardless of the order passed to this method). \sa selectionStart, selectionEnd * / \endcode QDoc includes this documentation on the element refence page for the \l{http://qt-project.org/doc/qt-4.7/qml-textinput.html#select-method} {TextInput} element. \target qmlproperty-command \section1 \\qmlproperty The \\qmlproperty command is for documenting a QML property. The argument is the rest of the line. The argument text should be the property type, followed by the QML type name, the \c{::} qualifier, and finally the property name. If we have a QML property named \c x in QML type \c Translate, and the property has type \c {real}, the \\qmlproperty for it would look like this: \code / *! \qmlproperty real Translate::x The translation along the X axis. * / \endcode QDoc includes this QML property on the QML reference page for the \l {http://qt-project.org/doc/qt-4.7/qml-translate.html} {Translate} element. \target qmlsignal-command \section1 \\qmlsignal The \\qmlsignal command is for documenting a QML signal. The argument is the rest of the line. The arguments should be: the QML type where the signal is declared, the \c{::} qualifier, and finally the signal name. If we have a QML signal named \c clicked(), the documentation for it would look like this: \code / *! \qmlsignal UIComponents::Button::clicked() This signal is emitted when the user clicks the button. A click is defined as a press followed by a release. The corresponding handler is \c onClicked. * / \endcode QDoc includes this documentation on the QML reference page for the \l{http://qt-project.org/doc/qt-4.7/qml-mousearea.html#onEntered-signal} {MouseArea} element. \target qmlmodule-command \section1 \\qmlmodule Insert the \c{\\qmlmodule} command to create a \c QML module page. A QML module is a collection of QML types or any related material. This command is similar to the \l{group-command}. A QML class may belong to a module by inserting the \l{inqmlmodule-command}{\\inqmlmodule} command as a topic command. Every member of a group must be linked to using the module name and two colons (\c{::}). \code A link to the UI Component's TabWidget is \l {UIComponent::TabWidget}. \endcode QDoc will generate a page for the module with a listing of the members of the module. \code \qmlmodule ClickableComponents This is a list of the Clickable Components set. A Clickable component responds to a \c clicked() event. \endcode The \l{componentset}{UIComponents} example demonstrates proper usage of QDoc commands to document QML types and QML modules. \target inqmlmodule-command \section1 \\inqmlmodule A QML class may belong to a \l{qmlmodule-command}{QML module} by inserting the \l{inqmlmodule-command}{\\inqmlmodule} command as a topic command. Every member of a group must be linked to using the module name and two colons (\c{::}). \code \qmltype ClickableButton \inqmlmodule ClickableComponents A clickable button that responds to the \c click() event. \endcode To link to the \c ClickableButton, use the \c{\l ClickableComponents::ClickableButton} format. The \l{componentset}{UIComponents} example demonstrates proper usage of QDoc commands to document QML types and QML modules. \target instantiates-command \section1 \\instantiates The \\instantiates command is used in the \l{qmltype-command} {QML type} comment of an elemental QML type to specify the name of the C++ class that instantiates the QML type. If the QML type is not instantiated by a C++ class, this command is not used. \code / *! \qmltype Transform \instantiates QGraphicsTransform \ingroup qml-transform-elements \since 4.7 \brief The Transform elements provide a way to build advanced transformations on Items. The Transform element is a base type which cannot be instantiated directly. * / \endcode The example generates the \l {http://qt-project.org/doc/qt-4.7/qml-transform.html} {QML Transform} page. The \e{\\qmltype} comment includes \l{instantiates-command} {\\instantiates} to specify that a Transform is instantiated by the C++ class QGraphicsTransform. A \\qmltype comment should \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 reference documentation for the class, namespace, or header file in which the typedef is declared. To relat the \\typedef to a class, namespace, or header file, the \\typedef comment must contain a \l {relates-command} {\\relates} command. \code / *! \typedef QObjectList \relates QObject Synonym for QList. * / \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. \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 QDoc Manual \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 \li \l {16-qdoc-commands-status.html#compat-command}{\\compat}, \li \l {15-qdoc-commands-navigation.html#contentspage-command}{\\contentspage}, \li \l {15-qdoc-commands-navigation.html#indexpage-command}{\\indexpage}, \li \l {19-qdoc-commands-grouping.html#ingroup-command}{\\ingroup}, \li \l {18-qdoc-commands-relating.html#inherits-command}{\\inherits}, \li \l {19-qdoc-commands-grouping.html#inmodule-command}{\\inmodule}, \li \l {16-qdoc-commands-status.html#internal-command}{\\internal}, \li \l {19-qdoc-commands-grouping.html#mainclass-command}{\\mainclass}, \li \l {15-qdoc-commands-navigation.html#nextpage-command}{\\nextpage}, \li \l {17-qdoc-commands-thread.html#nonreentrant-command}{\\nonreentrant}, \li \l {16-qdoc-commands-status.html#obsolete-command}{\\obsolete}, \li \l {18-qdoc-commands-relating.html#overload-command}{\\overload}, \li \l {16-qdoc-commands-status.html#preliminary-command}{\\preliminary}, \li \l {15-qdoc-commands-navigation.html#previouspage-command}{\\previouspage}, \li \l {17-qdoc-commands-thread.html#reentrant-command}{\\reentrant}, \li \l {18-qdoc-commands-relating.html#reimp-command}{\\reimp}, \li \l {18-qdoc-commands-relating.html#relates-command}{\\relates}, \li \l {16-qdoc-commands-status.html#since-command}{\\since}, \li \l {15-qdoc-commands-navigation.html#startpage-command}{\\startpage}, \li \l {20-qdoc-commands-namingthings.html#subtitle-command}{\\subtitle} \li \l {17-qdoc-commands-thread.html#threadsafe-command}{\\threadsafe}, \li \l {20-qdoc-commands-namingthings.html#title-command}{\\title} \endlist */ /*! \page 15-qdoc-commands-navigation.html \previouspage Context Commands \contentspage QDoc Manual \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 \li \l {Getting Started} \li \l {Creating Dialogs} \li \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 \li \l {Basic Qt} \li \l {Creating Dialogs} \li \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 QDoc Manual \nextpage Thread Support \title Reporting Status These commands are for indicating that a documented element is still under development, is becoming obsolete, is provided for compatibility reasons, or is simply not to be included in the public interface. The \l {since-command}{\\since} command is for including information about the version when a function or class first appeared. \target compat-command \section1 \\compat The \\compat command is for indicating that a class or function is part of the support library provided to keep old source code working. The command must stand on its own line. Usually an equivalent function or class is provided as an alternative. If the command is used in the documentation of a class, the command expands to a warning that the referenced class is part of the support library. The warning is located at the top of the documentation page. \code / *! \class MyQt3SupportClass \compat * / \endcode QDoc renders this at the top of the MyQt3SupportClass class reference page. \quotation \b {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://doc.qt.digia.com/4.0/porting4.html} {Porting Guide} for more information. \endquotation If the command is used when documenting a function, QDoc will create and link to a separate page documenting Qt 3 support members when generating the reference documentation for the associated class. \code / *! \fn MyClass::MyQt3SupportMemberFunction \compat Use MyNewFunction() instead. * / \endcode QDoc renders this in \c{myclass-qt3.html} as: \quotation \raw HTML
[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]
Qt 3 Support Members for MyClass
\endraw \b {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 \li void MyQt3SupportMemberFunction() \li ... \endlist \raw HTML
Member Function Documentation
void MyQt3SupportMemberFunction ()
Use MyNewFunction() instead.
\endraw ... \endquotation \target default-command \section1 \\default The \\default command is for marking a QML property as the \l {http://qt-project.org/doc/qt-4.7/qdeclarativeintroduction.html#default-properties} {default property}. The word \span {class="newStuff"} {default} is shown in red in the documentation of the property. \code / *! \qmlproperty listState::changes This property holds the changes to apply for this state \default By default these changes are applied against the default state. If the state extends another state, then the changes are applied against the state being extended. * / \endcode See how QDoc renders this property on the reference page for the \l {http://qt-project.org/doc/qt-4.7/qml-state.html#changes-prop} {State} type. \target obsolete-command \section1 \\obsolete The \\obsolete command is for indicating that a function is being deprecated, and it should no longer be used in new code. There is no guarantee for how long it will remain in the library. The command must stand on its own line. When generating the reference documentation for a class, QDoc will create and link to a separate page documenting its obsolete functions. Usually an equivalent function is provided as an alternative. \code / *! \fn MyClass::MyObsoleteFunction \obsolete Use MyNewFunction() instead. * / \endcode QDoc renders this in \c{myclass-obsolete.html} as: \quotation \raw HTML Obsolete Members for MyClass
\endraw \b {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 \li void MyObsoleteFunction() \c (obsolete) \li ... \endlist \raw HTML
Member Function Documentation
void MyObsoleteFunction ()
Use MyNewFunction() instead.
\endraw ... \endquotation \target internal-command \section1 \\internal The \\internal command indicates that the referenced function is not part of the public interface. The command must stand on its own line. QDoc ignores the documentation as well as the documented item, when generating the associated class reference documentation. \code / *! \internal Tries to find the decimal separator. If it can't find it and the thousand delimiter is != '.' it will try to find a '.'; * / int QDoubleSpinBoxPrivate::findDelimiter (const QString &str, int index) const { int dotindex = str.indexOf(delimiter, index); if (dotindex == -1 && thousand != dot && delimiter != dot) dotindex = str.indexOf(dot, index); return dotindex; } \endcode This function will not be included in the documentation. \target preliminary-command \section1 \\preliminary The \\preliminary command is for indicating that a referenced function is still under development. The command must stand on its own line. The \\preliminary command expands to a notification in the function documentation, and marks the function as preliminary when it appears in lists. \code / *! \preliminary Returns information about the joining properties of the character (needed for certain languages such as Arabic). * / QChar::Joining QChar::joining() const { return ::joining(*this); } \endcode QDoc renders this as: \quotation \raw HTMLJoining QChar::joining () const
\endraw \b {This function is under development and subject to change.} Returns information about the joining properties of the character (needed for certain languages such as Arabic). \endquotation And the function's entry in QChar's list of functions will be rendered as: \quotation \list \li ... \li Joining \l {http://qt-project.org/doc/qt-5.0/qtcore/qchar.html#Joining-enum} {joining}() const \c (preliminary) \li ... \endlist \endquotation \target since-command \section1 \\since The \\since command tells in which minor release the associated functionality was added. \code / *! \since 4.1 Returns an icon for \a standardIcon. ... \sa standardIconImplementation(), standardPixmap() * / QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const { } \endcode QDoc renders this as: \quotation \raw 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 QDoc Manual \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 \b {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, "\b 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 QDoc Manual \nextpage Grouping Things \title Relating Things The relating commands are for specifying how one documented element relates to another documented element. e.g., This function is an overload of another function, or this function is a reimplementation of another function, or this typedef is \e related to some class or header file. There is also a command for documenting that a QML type inherits some other QML type. \section1 Commands \target inherits-command \section2 \\inherits The \\inherits command is for documenting that one QML type inherits some other QML type. It must be included in the inheriting element's \l{qmltype-command}{\\qmltype} comment. The argument is the name of the inherited QML type. \code / *! \qmltype PauseAnimation \instantiates QDeclarativePauseAnimation \ingroup qml-animation-transition \since 4.7 \inherits Animation \brief The PauseAnimation element provides a pause for an animation. When used in a SequentialAnimation, PauseAnimation is a step when nothing happens, for a specified duration. A 500ms animation sequence, with a 100ms pause between two animations: SequentialAnimation { NumberAnimation { ... duration: 200 } PauseAnimation { duration: 100 } NumberAnimation { ... duration: 200 } } \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example} * / \endcode QDoc includes this line on the reference page for the \l{http://qt-project.org/doc/qt-4.7/qml-pauseanimation.html} {PauseAnimation} element: \quotation Inherits \l{http://qt-project.org/doc/qt-4.7/qml-animation.html} {Animation} \endquotation \target overload-command \section2 \\overload The \\overload command is for indicating that a function is a secondary overload of its name. The command must stand on its own line. For a function name that is overloaded (except constructors), QDoc expects one primary version of the function, and all the others marked with the \b {\\overload command}. The primary version should be fully documented. Each overload can have whatever extra documentation you want to add for just that overloaded version. From Qt 4.5, you can include the function name plus '()' as a parameter to the \b{\\overload} command, which will include a standard \e{This function overloads...} line of text with a link to the documentation for the primary version of the function. \code / *! \overload addAction() This convenience function creates a new action with an \a icon and some \a text. The function adds the newly created action to the menu's list of actions, and returns it. \sa QWidget::addAction() * / QAction *QMenu::addAction(const QIcon &icon, const QString &text) { QAction *ret = new QAction(icon, text, this); addAction(ret); return ret; } \endcode QDoc renders this as: \quotation \raw HTMLQAction * QMenu::addAction ( const QIcon & icon, const QString & text )
\endraw This function overloads \l {http://qt-project.org/doc/qt-5.0/qtwidgets/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-project.org/doc/qt-5.0/qtwidgets/qwidget.html#addAction} {QWidget::addAction}(). \endquotation If you don't include the function name with the \b{\\overlaod} command, then instead of the "This function overloads..." line with the link to the documentation for the primary version, you get the old standard line: \quotation This is an overloaded member function, provided for convenience. \endquotation. \target reimp-command \section2 \\reimp The \\reimp command is for indicating that a function is a reimplementation of a virtual function. The command must stand on its own line. QDoc will omit the reimplemented function from the class reference. \code / *! \reimp * / void QToolButton::nextCheckState() { Q_D(QToolButton); if (!d->defaultAction) QAbstractButton::nextCheckState(); else d->defaultAction->trigger(); } \endcode This function will not be included in the documentation. Instead, a link to the base function QAbstractButton::nextCheckState() will appear in the documentation. \target relates-command \section2 \\relates The \\relates command is for including the documentation of a global element to some class or header file. The argument is a class name or header file. \code / *! \relates QChar Reads a char from the stream \a in into char \a chr. \sa {Format of the QDataStream operators} * / QDataStream &operator>>(QDataStream &in, QChar &chr) { quint16 u; in >> u; chr.unicode() = ushort(u); return in; } \endcode The documentation for this function will be included on the reference page for class QChar. */ /*! \page 19-qdoc-commands-grouping.html \previouspage Relating Things \contentspage QDoc Manual \nextpage Naming Things \title Grouping Things The grouping commands relate classes to defined groups and modules. The groups are used when generating lists of related classes in the documentation, while the modules are elements of Qt's structure. \section1 Commands \target mainclass-command \section2 \\mainclass The \\mainclass command relates the documented class to a group called mainclasses. The command must stand on its own line. \code / *! \class QWidget qwidget.h \brief The QWidget class is the base class of all user interface objects. \mainclass ... * / \endcode This will include the QWidget class in the \e mainclasses group, which means, for example, that the class will appear on the list created by calling the \l {generatelist-command} {\\generatelist} command with the \c mainclasses argument: \l http://doc.qt.digia.com/4.0/mainclasses.html \note The Qt documentation no longer includes the \e mainclasses page. See also \l {generatelist-command} {\\generatelist}. \target ingroup-command \section2 \\ingroup The \\ingroup command indicates that the given overview or documented class belongs to a certain group of related docmentation. A class or overview may belong to many groups. The \\ingroup command's argument is a group name, but note that the command considers the rest of the line as part of its argument. Make sure that the group name is followed by a linebreak. \code / *! \class QDir \brief The QDir class provides access to directory structures and their contents. \ingroup io ... * / \endcode This will include the QDir class in the \c io group, which means, for example, that QDir will appear on the list created by calling the \l {group-command} {\\group} command with the \c io argument. To list overviews that are related to a certain group, you must generate the list explicitly using the \l {generatelist-command} {\\generatelist} command with the \c related argument. See also \l {group-command} {\\group}. \target inmodule-command \section2 \\inmodule The \\inmodule command relates a class to the module specified by the command's argument. For the basic classes in Qt, a class's module is determined by its location, i.e. its directory. However, for extensions, like ActiveQt and Qt Designer, a class must be related to a module explicitly. The command's argument is a module name, but note that the command considers the rest of the line as part of its argument. Make sure that the module name is followed by a linebreak. \code /*! \class QDesignerTaskMenuExtension \inmodule QtDesigner * / \endcode This ensures that the QDesignerTaskMenuExtension class is included in the Qt Designer 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 QDoc Manual \nextpage Markup Commands \title Naming Things In general, a title command considers everything that follows it until the first line break as its argument. If the title is so long it must span multiple lines, end each line (except the last one) with a backslash. \section1 Commands \target title-command \section2 \\title The \\title command sets the title for a documentation page, or allows you to override it. \code / *! \page signalandslots.html \title Signals & Slots Signals and slots are used for communication between objects. The signals and slots mechanism is a central feature of Qt and probably the part that differs most from the features provided by other frameworks. ... * / \endcode QDoc renders this as: \quotation \raw HTML\endraw Signals and slots are used for communication between objects. The signals and slots mechanism is a central feature of Qt and probably the part that differs most from the features provided by other frameworks. ... \endquotation See also \l {subtitle-command} {\\subtitle}. \target subtitle-command \section2 \\subtitle The \\subtitle command sets a subtitle for a documentation page. \code / *! \page qtopiacore-overview.html \title Qtopia Core \subtitle Qt for Embedded Linux Qt/Embedded, the embedded Linux port of Qt, is a complete and self-contained C++ GUI and platform development tool for Linux-based embedded development. ... * / \endcode QDoc renders this as: \quotation \raw HTML
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-creating-dita-maps.html \previouspage Miscellaneous \contentspage QDoc Manual \nextpage The QDoc Configuration File \title Creating DITA Maps You can create DITA map files using three new qdoc commands, the \l{ditamap-command} {ditamap} command, the \l{topicref-command} {topicref} command, and the \l{mapref-command} {mapref} command. How these DITA maps will be used automatically or manually by the documentation build process is still under consideration. This section will be updated as the decisions are made. \section1 What is a DITA map? A complete description of DITA can be found at the \l{http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita} {OASIS Darwin Information Typing Architecture} site. An explanation of the DITA map is found at that site \l{http://docs.oasis-open.org/dita/v1.2/os/spec/langref/map.html}{here}. \target ditamap-command \section1 \\ditamap The \\ditamap command is for creating a DITA map using qdoc commands. The \\ditamap command is a kind of \\page command that produces a \e{.ditamap} instead of a \e{.html} or \e{.xml} file. The file that is created actually contains XML text, but the \e{.ditamap} suffix is used to identify the file as containing a DITA MAP. The argument is the name of the file to be created. In the following example, the file \e{creator.ditamap} is output: \code \ditamap creator.ditamap \endcode \target topicref-command \section1 \\topicref \\endtopicref The \\topicref \\endtopicref commands are for creating a topicref in the ditamap. The \\endtopicref command is required because \\topicref commands can be nested. \\topicref has two arguments. The first argument becomes the value of the \e navtitle attribute. Normally, you use the title of the topic being referenced. This title is often what will appear in a table of contents constructed from the ditamap. The second argument is the name of the page being referenced. The second argument is actually optional, for example if you are using a topicref as a container for other topicrefs and maprefs. It is also optional if you want qdoc to find the page name for you by looking up the title in its internal data structure. It is recommended that you provide the second parameter if you know the page name. \code \topicref {QML Module QtQuick 2} {qtquick-2.xml} \mapref {Creator Manual} {creator-manual.ditamap} \endmapref \topicref {QML Mouse Events} {qtquick2-mouseevents.xml} \endtopicref \topicref {Property Binding} {qtquick2-propertybinding.xml} \endtopicref \endtopicref \endcode \target mapref-command \section1 \\mapref The \\mapref command is for creating a mapref in the ditamap. A mapref refers to another ditamap, which you want to include in your ditamap. Like the \\topicref command, the \\mapref command has two arguments, but for the \\mapref command, both arguments are required. The arguments are essentially the same as described for \\topicref, but for \\mapref, the second command must be the name of another ditamap, i.e. it must have the \e{.ditamap} suffix. You must provide the file name. qdoc can't look up the file name for you. \code \mapref {Creator Manual} {creator-manual.ditamap} \endmapref \endcode \section1 An example ditamap page The following example uses the three qdoc ditamap commands described above. \code \ditamap creator.ditamap \title The DITA Map For Creator \topicref {QML Module QtQuick 1} \topicref {QML Mouse Events} \endtopicref \topicref {Property Binding} \endtopicref \endtopicref \topicref {QML Module QtQuick 2} {qtquick-2.xml} \mapref {Creator Manual} {creator-manual.ditamap} \endmapref \topicref {QML Mouse Events} {qtquick2-mouseevents.xml} \endtopicref \topicref {Property Binding} {qtquick2-propertybinding.xml} \endtopicref \endtopicref \topicref {QML Module QtQuick.Particles 2} {qtquick-particles-2.xml} \topicref {Age} {qml-qtquick-particles2-age.xml} \endtopicref \endtopicref \endcode \section1 The resulting ditamap file This is the \e{.ditamap} file you get when you input the qdoc ditamap page shown above. Note that you can write ditamap files directly in XML just as easily as you can write them using the qdoc commands. The choice is yours. \code \endcode */ /*! \page 21-0-qdoc-configuration.html \previouspage Creating DITA Maps \contentspage QDoc Manual \nextpage Generic Configuration Variables \title The QDoc Configuration File Before running QDoc, you must create a QDoc configuration file to tell QDoc where to find the source files that contain the QDoc comments. The pathname to your configuration file is passed to QDoc on the command line: \quotation \c {/current/dir$ ../../bin/qdoc ./config.qdocconf} \endquotation \section1 General Description The configuration file is a list of entries of the form \e {"variable = value"}. Using the configuration variables, you can define where QDoc should find the various source files, images and examples, where to put generated documentation etc. The configuration file can also contain directives like \c include. For an example, see the \l minimum.qdocconf file. You can also use configuration variables to get QDoc to support \l{Supporting Derived Projects} {derived projects}, i.e QDoc can generate links in your project's documentation to elements in the Qt online documentation. See the \l {Supporting Derived projects} section. The value of a configuration variable can be set using either '=' or '+='. The difference is that '=' overrides the previous value, while '+=' adds a new value to the current one. Some configuration variables accept a list of strings as their value, e.g. \l {22-qdoc-configuration-generalvariables.html#sourcedirs-variable} {\c{sourcedirs}}, while others accept only a single string. Double quotes around a value string are optional, but including them allows you to use special characters like '=' and ' \" ' within the valuem string, e.g.: \code HTML.postheader = "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 \li \l {22-qdoc-configuration-generalvariables.html#alias-variable} {alias} \li \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoredirectives-variable} {Cpp.ignoredirectives} \li \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoretokens-variable} {Cpp.ignoretokens} \li \l {22-qdoc-configuration-generalvariables.html#defines-variable} {defines} \li \l {22-qdoc-configuration-generalvariables.html#edition-variable} {edition} \li \l {22-qdoc-configuration-generalvariables.html#exampledirs-variable} {exampledirs} \li \l {22-qdoc-configuration-generalvariables.html#examples-variable} {examples} \li \l {22-qdoc-configuration-generalvariables.html#examples.fileextensions-variable} {examples.fileextensions} \li \l {22-qdoc-configuration-generalvariables.html#excludedirs-variable} {excludedirs} \li \l {22-qdoc-configuration-generalvariables.html#excludefiles-variable} {excludefiles} \li \l {22-qdoc-configuration-generalvariables.html#extraimages-variable} {extraimages} \li \l {22-qdoc-configuration-generalvariables.html#falsehoods-variable} {falsehoods} \li \l {22-qdoc-configuration-generalvariables.html#headerdirs-variable} {headerdirs} \li \l {22-qdoc-configuration-generalvariables.html#headers-variable} {headers} \li \l {22-qdoc-configuration-generalvariables.html#headers.fileextensions-variable} {headers.fileextensions} \li \l {24-qdoc-configuration-htmlvariables.html#HTML.footer-variable} {HTML.footer} \li \l {24-qdoc-configuration-htmlvariables.html#HTML.postheader-variable} {HTML.postheader} \li \l {24-qdoc-configuration-htmlvariables.html#HTML.style-variable} {HTML.style} \li \l {22-qdoc-configuration-generalvariables.html#imagedirs-variable} {imagedirs} \li \l {22-qdoc-configuration-generalvariables.html#images-variable} {images} \li \l {22-qdoc-configuration-generalvariables.html#images.fileextensions-variable} {images.fileextensions} \li \l {22-qdoc-configuration-generalvariables.html#language-variable} {language} \li \l {22-qdoc-configuration-generalvariables.html#macro-variable} {macro} \li \l {22-qdoc-configuration-generalvariables.html#manifestmeta-variable} {manifestmeta} \li \l {22-qdoc-configuration-generalvariables.html#outputdir-variable} {outputdir} \li \l {22-qdoc-configuration-generalvariables.html#outputformats-variable} {outputformats} \li \l {22-qdoc-configuration-generalvariables.html#sourcedirs-variable} {sourcedirs} \li \l {22-qdoc-configuration-generalvariables.html#sources-variable} {sources} \li \l {22-qdoc-configuration-generalvariables.html#sources.fileextensions-variable} {sources.fileextensions} \li \l {22-qdoc-configuration-generalvariables.html#spurious-variable} {spurious} \li \l {22-qdoc-configuration-generalvariables.html#tabsize-variable} {tabsize} \li \l {22-qdoc-configuration-generalvariables.html#version-variable} {version} \li \l {22-qdoc-configuration-generalvariables.html#versionsym-variable} {versionsym} \endlist \section1 Categories \list \li \l {Generic Configuration Variables} \li \l {C++ Specific Configuration Variables} \li \l {HTML Specific Configuration Variables} \endlist \section1 Configuration File Examples \list \li A minimum configuration file: \l minimum.qdocconf \li The Qt configuration file: \l qt.qdocconf \endlist */ /*! \page 21-1-minimum-qdocconf.html \previouspage qt.qdocconf \contentspage QDoc Manual \nextpage Generating DITA XML Output \title minimum.qdocconf \quotefile examples/minimum.qdocconf */ /*! \page 21-2-qt-qdocconf.html \previouspage Supporting Derived Projects \contentspage QDoc Manual \nextpage minimum.qdocconf \title qt.qdocconf \quotefile files/qt.qdocconf */ /*! \page 21-3-qt-dita-xml-output.html \previouspage minimum.qdocconf \contentspage QDoc Manual \nextpage QDoc Manual \title Generating DITA XML Output QDoc can generate \l {http://dita.xml.org} {DITA XML output}. In your confifiguration file, set your \c {outputformats} variable to \c {DITAXML}, and send the output to an appropriate directory: \code outputdir = $QTDIR/doc/ditaxml outputformats = DITAXML \endcode And include these macros in your configuration file to prevent QDoc from doing some escaping that doesn't validate in XML: \code macro.aacute.DITAXML = "á" macro.Aring.DITAXML = "Å" macro.aring.DITAXML = "å" macro.Auml.DITAXML = "Ä" macro.br.DITAXML = " " macro.BR.DITAXML = " " macro.copyright.DITAXML = "©" macro.eacute.DITAXML = "é" macro.hr.DITAXML = " " macro.iacute.DITAXML = "í" macro.oslash.DITAXML = "ø" macro.ouml.DITAXML = "ö" macro.raisedaster.DITAXML = "*" macro.rarrow.DITAXML = "→" macro.reg.DITAXML = "®" macro.uuml.DITAXML = "ü" macro.mdash.DITAXML = "—" macro.emptyspan.DITAXML = " " \endcode You can also set default values for some of the tags in the DITA \c {
Qt for Embedded Linux } and \c { } elements: \code dita.metadata.default.author = Qt Development Frameworks dita.metadata.default.permissions = all dita.metadata.default.publisher = Qt Project dita.metadata.default.copyryear = 2013 dita.metadata.default.copyrholder = Qt Project dita.metadata.default.audience = programmer \endcode See the \l {12-0-qdoc-commands-miscellaneous.html#meta-command} {\\meta} command for more details on DITA metadata. */ /*! \page 22-qdoc-configuration-generalvariables.html \previouspage The QDoc Configuration File \contentspage QDoc Manual \nextpage Creating Help Project Files \title Generic Configuration Variables With the general QDoc configuration variables, you can define where QDoc will find the various source files it needs to generate the documentation, as well as the directory to put the generated documentation. You can also do some minor manipulation of QDoc itself, controlling its output and processing behavior. \target alias-variable \section1 alias The \c alias variable renames a QDoc command. The general syntax is \tt {alias.\e{original-command-name} = \e temporary-command-name}. \code alias.e = i \endcode This renames the built-in command \\e (italics) to be \\i. The \c alias variable is often used for compatibility reasons. See also \l {macro-variable} {macro}. \target codeindent-variable \section1 codeindent The \c codeindent variable specifies the level of indentation that QDoc uses when writing code snippets. QDoc originally used a hard-coded value of four spaces for code indentation to ensure that code snippets could be easily distinguished from surrounding text. Since we can use \l{HTML Specific Configuration Variables#HTML.stylesheets} {stylesheets} to adjust the appearance of certain types of HTML elements, this level of indentation is not always required. \target defines-variable \section1 defines The \c defines variable specifies the C++ preprocessor symbols that QDoc will recognize and respond to. When a preprocessor symbol is specified using the \c defines variable, you can also use the \l {if-command} {\\if} command to enclose documentation that only will be included if the preprocessor symbol is defined. The values of the variable are regular expressions (see QRegExp for details). By default, no symbol is defined, meaning that code protected with #ifdef...#endif will be ignored. \code defines = Q_QDOC \ QT_.*_SUPPORT \ QT_.*_LIB \ QT_COMPAT \ QT3_SUPPORT \ Q_WS_.* \ Q_OS_.* \ Q_BYTE_ORDER \ __cplusplus \endcode This ensures that QDoc will process the code that requires these symbols to be defined. For example: \code #ifdef Q_WS_WIN HDC getDC() const; void releaseDC(HDC) const; #endif \endcode Since the Q_WS_.* regular expression (specified using the \c defines variable) matches Q_WS_WIN, QDoc will process the code within #ifdef and #endif in our example. You can also define preprocessor symbols manually on the command line using the -D option. For example: \code currentdirectory$ qdoc -Dconsoleedition qt.qdocconf \endcode In this case the -D option ensures that the \c consoleedition preprocessor symbol is defined when QDoc processes the source files defined in the qt.qdocconf file. See also \l {falsehoods-variable} {falsehoods} and \l {if-command} {\\if}. \target edition-variable \section1 edition The \c edition variable specifies which modules are included in each edition of a package, and provides QDoc with information to provide class lists for each edition. This feature is mostly used when providing documentation for Qt packages. The \c edition variable is always used with a particular edition name to define the modules for that edition: \code edition.Console = QtCore QtNetwork QtSql QtXml edition.Desktop = QtCore QtGui QtNetwork QtOpenGL QtSql QtXml \ QtDesigner QtAssistant Qt3Support QAxContainer \ QAxServer edition.DesktopLight = QtCore QtGui Qt3SupportLight \endcode In the above examples, the \c Console edition only includes the contents of four modules. Only the classes from these modules will be used when the \l{Miscellaneous#generatelist-command} {generatelist} command is used to generate a list of classes for this edition: \code \generatelist{classesbyedition Console} \endcode \target exampledirs-variable \section1 exampledirs The \c exampledirs variable specifies the directories containing the source code of the example files. The \l {examples-variable} {examples} {examples} and \l {exampledirs-variable} {exampledirs} variables are used by the \l {quotefromfile-command} {\\quotefromfile}, \l {quotefile-command} {\\quotefile} and \l {example-command} {\\example} commands. If both the \l {examples-variable} {examples} and \l {exampledirs-variable} {exampledirs} variables are defined, QDoc will search in both, first in \l {examples-variable} {examples} then in \l {exampledirs-variable} {exampledirs}. QDoc will search through the directories in the specified order, and accept the first matching file it finds. It will only search in the specified directories, \e not in subdirectories. \code exampledirs = $QTDIR/doc/src \ $QTDIR/examples \ $QTDIR \ $QTDIR/qmake/examples examples = $QTDIR/examples/widgets/analogclock/analogclock.cpp \endcode When processing \code \quotefromfile widgets/calculator/calculator.cpp \endcode QDoc will then see if there exists a file called \c calculator.cpp listed as a value in the \l {examples} {\c examples} variable. If it doesn't, it will search in the \c exampledirs variable, and first see if there exists a file called \code $QTDIR/doc/src/widgets/calculator/calculator.cpp \endcode If it doesn't, QDoc will continue looking for a file called \code $QTDIR/examples/widgets/calculator/calculator.cpp \endcode and so forth. See also \l examples. \target examples-variable \section1 examples The \c examples variable allows you to specify individual example files in addition to those located in the directories specified by the \l {exampledirs-variable} {\c exampledirs} variable. The \c examples and \l {exampledirs-variable} {\c exampledirs} variables are used by the \l {quotefromfile-command} {\\quotefromfile}, \l {quotefile-command} {\\quotefile} and \l {example} {\\example} commands. If both the \c examples and \l {exampledirs-variable} {\c exampledirs} variables are defined, QDoc will search in both, first in \c examples then in \l {exampledirs-variable} {\c exampledirs}. QDoc will search through the values listed for the \c examples variable, in the specified order, and accept the first one it finds. For an extensive example, see the \l {exampledirs-variable} {\c exampledirs} command. But note that if you know the file is listed in the \c examples variable, you don't need to specify its path: \code \quotefromfile calculator.cpp \endcode See also \l {exampledirs-variable} {exampledirs}. \target examples.fileextensions-variable \section1 examples.fileextensions The \c examples.fileextensions variable specifies the file extensions that qdoc will look for when collecting example files for display in the documentation. The default extensions are *.cpp, *.h, *.js, *.xq, *.svg, *.xml and *.ui. 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 excludedirs-variable \section1 excludedirs The \c excludedirs variable is for listing directories that should \e{not} be processed by qdoc, even if the same directories are included by the \l {sourcedirs-variable} {sourcedirs} or \l {headerdirs-variable} {headerdirs} variables. For example, \code sourcedirs = src/corelib excludedirs = src/corelib/tmp \endcode When executed, QDoc will exclude the listed directories from further consideration. Files in these directories will not be read by qdoc. See also \l {excludefiles-variable} {excludefiles}. \target excludefiles-variable \section1 excludefiles The \c excludefiles variable allows you to specify individual files that should \e{not} be processed by qdoc. \code excludefiles += $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.h \ $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.cpp \endcode If you include the above in your qdocconf file for qtbase, there will be no qwidget.html generated for html and no qwidget.xml generated for DITA XML. See also \l {excludedirs-variable} {excludedirs}. \target extraimages-variable \section1 extraimages The \c extraimages variable tells QDoc to incorporate specific images in the generated documentation. QDoc will not recognize images used within HTML (or any other markup language). If we want the images to be copied from the directories specified by \l {imagedirs} {\c imagedirs} (the images in question must be located in these directories) to the output directory, we must specify the images using the \c extraimages variable. The general syntax is \tt {extraimages.\e{format} = \e image}. The file extension is optional. For example, in \l qt.qdocconf we use a couple of images within the HTML.postheader variable which value is pure HTML. For that reason, these images are specified using the \c extraimages variable: \code extraimages.HTML = qt-logo \endcode See also \l images and \l imagedirs. \target falsehoods-variable \section1 falsehoods The \c falsehoods variable defines the truth value of specified preprocessor symbols as false. If this variable is not set for a preprocessor symbol, QDoc assumes its truth value is true. The exception is '0', which value always is false. QDoc will recognize, and is able to evaluate, the following preprocessor syntax: \code #ifdef NOTYET ... #endif #if defined (NOTYET) ... #end if \endcode However, faced with unknown syntax like \code #if NOTYET ... #endif \endcode QDoc will evaluate it as true by default, \e unless the preprocessor symbol is specified within the \c falsehoods variable entry: \code falsehoods = NOTYET \endcode See also \l defines. \target generateindex-variable \section1 generateindex The \c generateindex variable contains a boolean value that specifies whether to generate an index file when HTML documentation is generated. By default, an index file is always generated with HTML documentation, so this variable is typically only used when disabling this feature (by setting the value to \c false) or when enabling index generation for the WebXML output (by setting the value to \c true). \target headerdirs-variable \section1 headerdirs The \c headerdirs variable specifies the directories containing the header files associated with the \c .cpp source files used in the documentation. \code headerdirs = $QTDIR/src \ $QTDIR/extensions/activeqt \ $QTDIR/extensions/motif \ $QTDIR/tools/designer/src/lib/extension \ $QTDIR/tools/designer/src/lib/sdk \ $QTDIR/tools/designer/src/lib/uilib \endcode When executed, the first thing QDoc will do is to read through the headers specified in the \l {headers} {\c headers} variable, and the ones located in the directories specified in the \c headerdir variable (including all subdirectories), building an internal structure of the classes and their functions. Then it will read through the sources specified in the \l {sources-variable} {\c sources}, and the ones located in the directories specified in the \l {sourcedirs-variable} {\c sourcedirs} varible (including all subdirectories), merging the documentation with the structure it retrieved from the header files. If both the \c headers and \c headerdirs variables are defined, QDoc will read through both, first \l {headers} {\c headers} then \c headerdirs. In the specified directories, QDoc will only read the files with the fileextensions specified in the \l {headers.fileextensions} {\c headers.fileextensions} variable. The default extensions are *.ch, *.h, *.h++, *.hh, *.hpp and *.hxx". The files specified by \l {headers} {\c headers} will be read independent of their fileextensions. See also \l headers and \l headers.fileextensions. \target headers-variable \section1 headers The \c headers variable allows you to specify individual header files in addition to those located in the directories specified by the \l {headerdirs} {\c headerdirs} variable. \code headers = $QTDIR/src/gui/widgets/qlineedit.h \ $QTDIR/src/gui/widgets/qpushbutton.h \endcode When processing the \c headers variable, QDoc behaves in the same way as it does when processing the \l {headerdirs} {\c headerdirs} variable. For more information, see the \l {headerdirs} {\c headerdirs} variable. See also \l headerdirs. \target headers.fileextensions-variable \section1 headers.fileextensions The \c headers.fileextensions variable specify the extension used by the headers. When processing the header files specified in the \l {headerdirs} {\c headerdirs} variable, QDoc will only read the files with the fileextensions specified in the \c headers.fileextensions variable. In this way QDoc avoid spending time reading irrelevant files. The default extensions are *.ch, *.h, *.h++, *.hh, *.hpp and *.hxx. The extensions are given as standard wildcard expressions. You can add a file extension to the filter using '+='. For example: \code header.fileextensions += *.H \endcode \warning The above assignment may not work as described. See also \l headerdirs. \target imagedirs-variable \section1 imagedirs The \c imagedirs variable specifies the directories containing the images used in the documentation. The \l {images} {\c images} and \c imagedirs variables are used by the \l {image-command} {\\image} and \l {inlineimage-command} {\\inlineimage} commands. If both the \l {images} {\c images} and \c imagedirs variables are defined, QDoc will search in both, first in \l {images} {\c images} then in \c imagedirs. QDoc will search through the directories in the specified order, and accept the first matching file it finds. It will only search in the specified directories, \e not in subdirectories. \code imagedirs = $QTDIR/doc/src/images \ $QTDIR/examples images = $QTDIR/doc/src/images/calculator-example.png \endcode When processing \code \image calculator-example.png \endcode QDoc will then see if there exists a file called calculator-example.png listed as a value in the \c images variable. If it doesn't, it will search in the \c imagedirs variable, and first see if there exists a file called \code $QTDIR/doc/src/images/calculator-example.png \endcode If it doesn't, QDoc will look for a file called \code $QTDIR/examples/calculator-example.png \endcode You can filter the images in an image directory using the \l {images.fileextensions} {\c images.fileextensions} variable. The general idea behind the \l {images.fileextensions} {\c images.fileextensions} variable is to enable different image format for different output format. \warning The \l {images.fileextensions} {\c images.fileextensions} variable's functionality is preliminay since QDoc at this point only support HTML. See also \l images and \l images.fileextensions. \target images-variable \section1 images The \c images variable allows you to specify individual image files in addition to those located in the directories specified by the \l {imagedirs} {\c imagedirs} variable. \code images = $QTDIR/doc/src/images/calculator-example.png \endcode When processing the \c images variable, QDoc behaves in the same way as it does when processing the \l {imagedirs} {\c imagedirs} variable. For more information, see the \l {imagedirs} {\c imagedirs} variable. See also \l imagedirs and \l images.fileextensions. \target images.fileextensions-variable \section1 images.fileextensions The images.fileextensions variable filters the files within an image directory. The variable's values (the extensions) are given as standard wildcard expressions. The general syntax is: \tt {images.fileextensions.\e{format} = *.\e{extension}}. The idea is to enable different image format for different output format. \code images.fileextensions.HTML = *.png images.fileextensions.LOUT = *.eps \endcode Then, when processing the \l {image-command} {\\image} and \l {inlineimage-command} {\\inlineimage} commands, QDoc will only search for files with extensions specified in the output format's associated image extension variable. \warning This is preliminary functionality since QDoc at this point only support HTML. The default extensions for HTML are *.png, *.jpg, *.jpeg and *.gif. You can add a file extension to the filter using '+='. For example: \code images.fileextensions.HTML += *.eps \endcode See also \l imagedirs and \l images. \target language-variable \section1 language The \c language variable specifies the language of the source code that is used in the documentation. Currently, C++ is the only language that QDoc understands. It is also the default language, and doesn't really need to be specified. But for example in \l qt.qdocconf: \code language = Cpp \endcode identifies the language of the Qt source code as C++. \target macro-variable \section1 macro The \c macro variable is used to create your own simple QDoc commands. The syntax is \tt {macro.\e{command} = \e{definition}}, where the definition is written using QDoc syntax. A macro variable can be restricted for use in one type of output generation. By appending \c {.HTML} to the macro name, for example, the macro is only used when generating HTML output. By appending \c {.DITAXML} to the macro name, the macro is only used when generating DITA XML. \code macro.gui = "\\b" macro.raisedaster.HTML = "*" \endcode The first macro defines the \\gui command to render its argument using a bold font. The second macro defines the \\raisedaster command to render a superscript asterisk, but only when generating HTML. See also \l {alias-variable} {alias}. \target manifestmeta-variable \section1 manifestmeta The \c manifestmeta variable specifies additional meta-content for the example manifest files generated by QDoc. See the \l{Manifest Meta Content} section for more information. \target naturallanguage-variable \section1 naturallanguage The \c naturallanguage variable specifies the natural language used for the documentation generated by qdoc. \code naturallanguage = zh-Hans \endcode By default, the natural language is \c en for compatibility with legacy documentation. qdoc will add the natural language information to the HTML it generates, using the \c lang and \c xml:lang attributes. See also \l {sourceencoding-variable} {sourceencoding}, \l {outputencoding-variable} {outputencoding}, \l{http://www.w3.org/TR/xhtml1/#C_7} {C.7. The lang and xml:lang Attributes} and \l{http://www.w3.org/TR/i18n-html-tech-lang/#ri20040429.113217290} {Best Practice 13: Using Hans and Hant codes}. \target outputdir-variable \section1 outputdir The \c outputdir variable specifies the directory where QDoc will put the generated documentation. In qt.qdocconf: \code outputdir = $QTDIR/doc/html \endcode locates the generated Qt reference documentation in $QTDIR/doc/html. For example, the documentation of the QWidget class is located in \code $QTDIR/doc/html/qwidget.html \endcode The associated images will be put in an \c images subdirectory. \warning When running QDoc multiple times using the same output directory, all files from the previous run will be lost. \target outputencoding-variable \section1 outputencoding The \c outputencoding variable specifies the encoding used for the documentation generated by qdoc. \code outputencoding = UTF-8 \endcode By default, the output encoding is \c ISO-8859-1 (Latin1) for compatibility with legacy documentation. When generating documentation for some languages, particularly non-European languages, this is not sufficient and an encoding such as UTF-8 is required. qdoc will encode HTML using this encoding and generate the correct declarations to indicate to browsers which encoding is being used. The \l naturallanguage configuration variable should also be specified to provide browsers with a complete set of character encoding and language information. See also \l outputencoding and \l naturallanguage. \target outputformats-variable \section1 outputformats The \c outputformats variable specifies the format of the generated documentation. Currently, QDoc only supports the HTML format. It is also the default format, and doesn't need to be specified. \target outputprefixes \section1 outputprefixes The \c outputprefixes variable specifies a mapping between types of files and the prefixes to prepend to the HTML file names in the generated documentation. \code outputprefixes = QML outputprefixes.QML = uicomponents- \endcode By default, files containing the API documentation for QML types are prefixed with "qml-". In the above example, the prefix \c "uicomponents" is used instead. \target qhp-variable \section1 qhp The \c qhp variable is used to define the information to be written out to Qt Help Project (\c{qhp}) files. See the \l{Creating Help Project Files} chapter for information about this process. \target 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 thing QDoc will do is to read through the headers specified in the \l {header-command} {\c header} variable, and the ones located in the directories specified in the \c headerdir variable (including all subdirectories), building an internal structure of the classes and their functions. Then it will read through the sources specified in the \l {sources} {\c sources}, and the ones located in the directories specified in the \l {sourcedirs} {\c sourcedirs} varible (including all subdirectories), merging the documentation with the structure it retrieved from the header files. If both the \c sources and \c sourcedirs variables are defined, QDoc will read through both, first \l {sources} {\c sources} then \c sourcedirs. In the specified directories, QDoc will only read the files with the fileextensions specified in the \l {sources.fileextensions} {\c sources.fileextensions} variable. The default extensions are *.c++, *.cc, *.cpp and *.cxx. The files specified by \l {sources} {\c sources} will be read independent of their fileextensions. See also \l {sources-variable} {sources} and \l {sources.fileextensions-variable} {sources.fileextensions}. \target sourceencoding-variable \section1 sourceencoding The \c sourceencoding variable specifies the encoding used for the source code and documentation. \code sourceencoding = UTF-8 \endcode By default, the source encoding is \c ISO-8859-1 (Latin1) for compatibility with legacy documentation. For some languages, particularly non-European languages, this is not sufficient and an encoding such as UTF-8 is required. Although qdoc will use the encoding to read source and documentation files, limitations of C++ compilers may prevent you from using non-ASCII characters in source code comments. In cases like these, it is possible to write API documentation completely in documentation files. See also \l {naturallanguage-variable} {naturallanguage} and \l {outputencoding-variable} {outputencoding}. \target sources-variable \section1 sources The \c sources variable allows you to specify individual source files in addition to those located in the directories specified by the \l {sourcedirs-variable} {sourcedirs} variable. \code sources = $QTDIR/src/gui/widgets/qlineedit.cpp \ $QTDIR/src/gui/widgets/qpushbutton.cpp \endcode When processing the \c sources variable, QDoc behaves in the same way as it does when processing the \l {sourcedirs-variable} {sourcedirs} variable. For more information, see the \l {sourcedirs-variable} {sourcedirs} variable. See also \l {sourcedirs-variable} {sourcedirs}. \target sources.fileextensions-variable \section1 sources.fileextensions The \c sources.fileextensions variable filters the files within a source directory. When processing the source files specified in the \l {sourcedirs} {\c sourcedirs} variable, QDoc will only read the files with the fileextensions specified in the \c sources.fileextensions variable. In this way QDoc avoid spending time reading irrelevant files. The default extensions are *.c++, *.cc, *.cpp and *.cxx. The extensions are given as standard wildcard expressions. You can add a file extension to the filter using '+='. For example: \code sources.fileextensions += *.CC \endcode \warning The above assignment may not work as described. See also \l {sourcedirs-variable} {sourcedirs} and \l (sources-variable} {sources}. \target spurious-variable \section1 spurious The \c spurious variable excludes specified QDoc warnings from the output. The warnings are specified using standard wildcard expressions. \code spurious = "Cannot find .*" \ "Missing .*" \endcode makes sure that warnings matching either of these expressions, will not be part of the output when running QDoc. For example would the following warning be omitted from the output: \code qt-4.0/src/opengl/qgl_mac.cpp:156: Missing parameter name \endcode \target syntaxhighlighting \section1 syntaxhighlighting The \c syntaxhighlighting variable specifies whether QDoc should perform syntax highlighting on source code quoted in the documentation it generates. \code syntaxhighlighting = true \endcode will enable syntax highlighting for all supported programming languages. \target tabsize-variable \section1 tabsize The \c tabsize variable defines the size of a tab character. \code tabsize = 4 \endcode will give the tab character the size of 4 spaces. The default value of the variable is 8, and doesn't need to be specified. \target tagfile-variable \section1 tagfile The \c tagfile variable specifies the Doxygen tag file to be written when HTML is generated. \target version-variable \section1 version The \c version variable specifies the version number of the documented software. \code version = 4.0.1 \endcode When a version number is specified (using the \tt{\l version} or \tt {\l versionsym} variables in a \c .qdocconf file), it is accessible through the corresponding \\version command for use in the documentation. \warning The \\version command's functionality is not fully implemented; currently it only works within raw HTML code. See also \l versionsym. \target versionsym-variable \section1 versionsym The \c versionsym variable specifies a C++ preprocessor symbol that defines the version number of the documented software. For example in \l qt.qdocconf: \code versionsym = QT_VERSION_STR \endcode QT_VERSION_STR is defined in qglobal.h as follows \code #define QT_VERSION_STR "4.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 Generic Configuration Variables \contentspage QDoc Manual \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 QDoc Manual \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_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 QDoc Manual \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 = " \n" \ ... "" \endcode The complete variable entry in \l qt.qdocconf provides the standard footer of the \l {http://doc.qt.digia.com/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://doc.qt.digia.com/} {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://doc.qt.digia.com/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 QDoc Manual \nextpage Example Manifest Files \title Supporting Derived Projects Some configuration variables allow you to use QDoc to support Qt-based projects; i.e allow your project to contain links to the online Qt documentation. This means that QDoc will be able to create links to the class reference documentation, without any explicit linking command. \target description-variable \section1 description The description variable holds a short description of the associated project. See also \l project. \target indexes-variable \section1 indexes The \c indexes variable lists the index files that will be used to generate references. For example. to make a derived Qt project contain links to the Qt Reference documentation, you need to specify the associated index file: \code indexes = $QTDIR/doc/html/qt.index \endcode See also \l project and \l url. \target project-variable \section1 project The \c project variable provides a name for the project associated with the \c .qdocconf file. The project's name is used to form a file name for the associated project's \e index file. \code project = QtCreator \endcode This will cause an index file called \c qtcreator.index to be created. See also \l description and \l indexes. \target url-variable \section1 url The \c url variable holds the base URL for the reference documentation associated with the current project. The URL is stored in the generated index file for the project. When we use the index on its own, QDoc will use this as the base URL when constructing links to classes, functions, and other things listed in the index. \code project = Qt description = Qt Reference Documentation url = http://qt-project.org/doc/qt-4.8/ ... \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://doc.qt.digia.com/4.7. 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-project.org/doc/qt-4.8/ ... \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 qtcreator.qdocconf file to help you check the Qt Creator documentation: \code project = QtCreator description = Qt Creator Manual url = http://qt-project.org/doc/qtcreator-2.6/ 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. \b {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-configuration-example-manifest-files.html \previouspage Supporting Derived Projects \contentspage QDoc Manual \title Example Manifest Files QDoc generates XML files that contain information about all documented examples and demos. These files, named \c {examples-manifest.xml} and \c {demos-manifest.xml}, are used by Qt Creator to present a list of examples in its welcome screen and to link to their documentation. \section1 Manifest XML Structure A manifest file has the following structure: \code
\endcode Each \c { ... analog,clock,window gui/analogclock/main.cpp } element contains information about a name, description, the location of the project file and documentation, as well as a list of tags associated with the example. \target metacontent \section1 Manifest Meta Content It is possible to augment the manifest files with additional meta-content - that is, extra attributes and tags for selected examples, using the \c manifestmeta configuration command. One use case for meta-content is highlighting a number of prominent examples. Another is improving search functionality by adding relevant keywords as tags for a certain category of examples. The examples for which meta-content is applied to is specified using one or more filters. Matching examples to filters is done based on names, with each example name prefixed with a module name and a slash. Simple wildcard matching is supported; by using \c {*} at the end it's possible to match multiple examples with a single string. Example: \code manifestmeta.filters = highlighted sql webkit global manifestmeta.highlighted.names = "QtGui/Analog Clock Window Example" \ "QtWidgets/Analog Clock Example" manifestmeta.highlighted.attributes = isHighlighted:true manifestmeta.sql.names = "QtSql/*" manifestmeta.sql.tags = database,sql manifestmeta.webkit.names = "QtWebKitExamples/*" manifestmeta.webkit.tags = webkit manifestmeta.global.names = * manifestmeta.global.tags = qt5 \endcode Above, an \c isHighlighted attribute is added to two examples. If the attribute value is omitted, QDoc uses the string \c {true} by default. Extra tags are added for Qt WebKit and Qt SQL examples, and another tag is applied to all examples by using just \c {*} as the match string. */ /*! \page 27-qdoc-commands-alphabetical.html \previouspage Introduction to QDoc \contentspage QDoc Manual \nextpage Topic Commands \title Command Index This is a complete, alphabetized list of the QDoc commands. \list \li \l {04-qdoc-commands-textmarkup.html#a-command} {\\a} \li \l {11-qdoc-commands-specialcontent.html#abstract-command} {\\abstract} \li \l {12-0-qdoc-commands-miscellaneous.html#annotatedlist-command} {\\annotatedlist} \li \l {04-qdoc-commands-textmarkup.html#b-command} {\\b} \span {class="newStuff"} {(new 5/3/2012)} \li \l { 22-qdoc-configuration-generalvariables.html#basedir-variable} {basedir} \span {class="newStuff"} {(experimental)} \li \l {04-qdoc-commands-textmarkup.html#b-command} {\\bold} \span {class="newStuff"} {(deprecated, use \\b)} \li \l {11-qdoc-commands-specialcontent.html#brief-command} {\\brief} \li \l {04-qdoc-commands-textmarkup.html#c-command} {\\c} \li \l {09-qdoc-commands-includingimages.html#caption-command} {\\caption} \li \l {05-qdoc-commands-documentstructure.html#chapter-command} {\\chapter} \li \l {13-qdoc-commands-topics.html#class-command} {\\class} \li \l {06-qdoc-commands-includecodeinline.html#code-command} {\\code} \li \l {07-0-qdoc-commands-includingexternalcode.html#codeline-command} {\\codeline}, \li \l {16-qdoc-commands-status.html#compat-command} {\\compat} \li \l {15-qdoc-commands-navigation.html#contentspage-command} {\\contentspage} \li \l {16-qdoc-commands-status.html#default-command} {\\default} \li \l {21-0-qdoc-creating-dita-maps.html#ditamap-command} {\\ditamap} \span {class="newStuff"} {(new 05/03/12)} \li \l {04-qdoc-commands-textmarkup.html#div-command} {\\div} \li \l {07-0-qdoc-commands-includingexternalcode.html#dots-command} {\\dots} \li \l {04-qdoc-commands-textmarkup.html#e-command} {\\e} \span {class="newStuff"} {(new 5/3/2012)} \li \l {12-0-qdoc-commands-miscellaneous.html#else-command} {\\else} \li \l {12-0-qdoc-commands-miscellaneous.html#endif-command} {\\endif} \li \l {13-qdoc-commands-topics.html#enum-command} {\\enum} \li \l {13-qdoc-commands-topics.html#example-command} {\\example} \li \l {13-qdoc-commands-topics.html#externalpage-command} {\\externalpage} \li \l {13-qdoc-commands-topics.html#fn-command} {\\fn} \li \l {11-qdoc-commands-specialcontent.html#footnote-command} {\\footnote} \li \l {12-0-qdoc-commands-miscellaneous.html#generatelist-command} {\\generatelist} \li \l {13-qdoc-commands-topics.html#group-command} {\\group} \li \l {10-qdoc-commands-tablesandlists.html#header-command} {\\header} \li \l {13-qdoc-commands-topics.html#headerfile-command} {\\headerfile} \li \l {04-qdoc-commands-textmarkup.html#e-command} {\\i} \span {class="newStuff"} {(deprecated, use \\e)} \li \l {12-0-qdoc-commands-miscellaneous.html#if-command} {\\if} \li \l {09-qdoc-commands-includingimages.html#image-command} {\\image} \li \l {12-0-qdoc-commands-miscellaneous.html#include-command} {\\include} \li \l {15-qdoc-commands-navigation.html#indexpage-command} {\\indexpage} \li \l {19-qdoc-commands-grouping.html#ingroup-command} {\\ingroup} \li \l {18-qdoc-commands-relating.html#inherits-command}{\\inherits} \li \l {09-qdoc-commands-includingimages.html#inlineimage-command} {\\inlineimage} \li \l {19-qdoc-commands-grouping.html#inmodule-command} {\\inmodule} \li \l {13-qdoc-commands-topics.html#inqmlmodule-command} {\\inqmlmodule} \li \l {13-qdoc-commands-topics.html#instantiates-command} {\\instantiates} \span {class="newStuff"} {(new 27/7/2012)} \li \l {16-qdoc-commands-status.html#internal-command} {\\internal} \li \l {08-qdoc-commands-creatinglinks.html#keyword-command} {\\keyword} \li \l {08-qdoc-commands-creatinglinks.html#l-command} {\\l} \li \l {11-qdoc-commands-specialcontent.html#legalese-command} {\\legalese} \li \l {10-qdoc-commands-tablesandlists.html#li-command} {\\li} \span {class="newStuff"} {(new 5/3/2012)} \li \l {10-qdoc-commands-tablesandlists.html#list-command} {\\list} \li \l {13-qdoc-commands-topics.html#macro-command} {\\macro} \li \l {19-qdoc-commands-grouping.html#mainclass-command} {\\mainclass} \li \l {21-0-qdoc-creating-dita-maps.html#mapref-command} {\\mapref} \span {class="newStuff"} {(new 05/03/12)} \li \l {12-0-qdoc-commands-miscellaneous.html#meta-command} {\\meta} \li \l {13-qdoc-commands-topics.html#module-command} {\\module} \li \l {13-qdoc-commands-topics.html#namespace-command} {\\namespace} \li \l {15-qdoc-commands-navigation.html#nextpage-command} {\\nextpage} \li \l {06-qdoc-commands-includecodeinline.html#newcode-command} {\\newcode} \li \l {17-qdoc-commands-thread.html#nonreentrant-command} {\\nonreentrant} \li \l {10-qdoc-commands-tablesandlists.html#li-command} {\\o} \span {class="newStuff"} {(deprecated, use \\li)} \li \l {16-qdoc-commands-status.html#obsolete-command} {\\obsolete} \li \l {06-qdoc-commands-includecodeinline.html#oldcode-command} {\\oldcode} \li \l {12-0-qdoc-commands-miscellaneous.html#omit-command} {\\omit} \li \l {10-qdoc-commands-tablesandlists.html#omitvalue-command} {\\omitvalue} \li \l {18-qdoc-commands-relating.html#overload-command} {\\overload} \li \l {13-qdoc-commands-topics.html#page-command} {\\page} \li \l {05-qdoc-commands-documentstructure.html#part-command} {\\part} \li \l {16-qdoc-commands-status.html#preliminary-command} {\\preliminary} \li \l {15-qdoc-commands-navigation.html#previouspage-command} {\\previouspage} \li \l {07-0-qdoc-commands-includingexternalcode.html#printline-command} {\\printline} \li \l {07-0-qdoc-commands-includingexternalcode.html#printto-command} {\\printto} \li \l {07-0-qdoc-commands-includingexternalcode.html#printuntil-command} {\\printuntil} \li \l {13-qdoc-commands-topics.html#property-command} {\\property} \li \l {13-qdoc-commands-topics.html#qmlattachedproperty-command} {\\qmlattachedproperty} \li \l {13-qdoc-commands-topics.html#qmlattachedsignal-command} {\\qmlattachedsignal} \li \l {13-qdoc-commands-topics.html#qmlbasictype-command} {\\qmlbasictype} \li \l {13-qdoc-commands-topics.html#qmlclass-command} {\\qmlclass} \span {class="newStuff"} {(deprecated, use \\qmltype)} \li \l {13-qdoc-commands-topics.html#qmltype-command} {\\qmltype} \span {class="newStuff"} {(new 27/7/2012)} \li \l {13-qdoc-commands-topics.html#qmlmethod-command} {\\qmlmethod} \li \l {13-qdoc-commands-topics.html#qmlproperty-command} {\\qmlproperty} \li \l {13-qdoc-commands-topics.html#qmlsignal-command} {\\qmlsignal} \li \l {13-qdoc-commands-topics.html#qmlmodule-command} {\\qmlmodule} \li \l {11-qdoc-commands-specialcontent.html#quotation-command} {\\quotation} \li \l {07-0-qdoc-commands-includingexternalcode.html#quotefile-command} {\\quotefile} \li \l {07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command} {\\quotefromfile} \li \l {12-0-qdoc-commands-miscellaneous.html#raw-command} {\\raw} \span {class="newStuff"} {(avoid)} \li \l {17-qdoc-commands-thread.html#reentrant-command} {\\reentrant} \li \l {18-qdoc-commands-relating.html#reimp-command} {\\reimp} \li \l {18-qdoc-commands-relating.html#relates-command} {\\relates} \li \l {10-qdoc-commands-tablesandlists.html#row-command} {\\row} \li \l {08-qdoc-commands-creatinglinks.html#sa-command} {\\sa} \li \l {05-qdoc-commands-documentstructure.html#sectionOne-command} {\\section1} \li \l {05-qdoc-commands-documentstructure.html#sectionTwo-command} {\\section2} \li \l {05-qdoc-commands-documentstructure.html#sectionThree-command} {\\section3} \li \l {05-qdoc-commands-documentstructure.html#sectionFour-command} {\\section4} \li \l {13-qdoc-commands-topics.html#service-command} {\\service} \li \l {16-qdoc-commands-status.html#since-command} {\\since} \li \l {07-0-qdoc-commands-includingexternalcode.html#skipline-command} {\\skipline} \li \l {07-0-qdoc-commands-includingexternalcode.html#skipto-command} {\\skipto} \li \l {07-0-qdoc-commands-includingexternalcode.html#skipuntil-command} {\\skipuntil} \li \l {07-0-qdoc-commands-includingexternalcode.html#snippet-command} {\\snippet}, \li \l {04-qdoc-commands-textmarkup.html#span-command} {\\span} \li \l {15-qdoc-commands-navigation.html#startpage-command} {\\startpage} \li \l {04-qdoc-commands-textmarkup.html#sub-command} {\\sub} \li \l {20-qdoc-commands-namingthings.html#subtitle-command} {\\subtitle} \li \l {04-qdoc-commands-textmarkup.html#sup-command} {\\sup} \li \l {10-qdoc-commands-tablesandlists.html#table-command} {\\table} \li \l {11-qdoc-commands-specialcontent.html#tableofcontents-command} {\\tableofcontents} \li \l {08-qdoc-commands-creatinglinks.html#target-command} {\\target} \li \l {17-qdoc-commands-thread.html#threadsafe-command} {\\threadsafe} \li \l {20-qdoc-commands-namingthings.html#title-command} {\\title} \li \l {21-0-qdoc-creating-dita-maps.html#topicref-command} {\\topicref} \span {class="newStuff"} {(new 05/03/12)} \li \l {04-qdoc-commands-textmarkup.html#tt-command} {\\tt} \li \l {13-qdoc-commands-topics.html#typedef-command} {\\typedef} \li \l {04-qdoc-commands-textmarkup.html#uicontrol-command} {\\uicontrol} {(new 25/3/2012)} \li \l {04-qdoc-commands-textmarkup.html#underline-command} {\\underline} \li \l {13-qdoc-commands-topics.html#variable-command} {\\variable} \li \l {10-qdoc-commands-tablesandlists.html#value-command} {\\value} \li \l {11-qdoc-commands-specialcontent.html#warning-command} {\\warning} \endlist */ /*! \externalpage http://qt-project.org/about \title About Qt */