diff options
Diffstat (limited to 'tools/qdoc3')
45 files changed, 9855 insertions, 128 deletions
diff --git a/tools/qdoc3/codeparser.cpp b/tools/qdoc3/codeparser.cpp index 3ad3372..5ae63ac 100644 --- a/tools/qdoc3/codeparser.cpp +++ b/tools/qdoc3/codeparser.cpp @@ -59,6 +59,7 @@ QT_BEGIN_NAMESPACE #define COMMAND_MAINCLASS Doc::alias(QLatin1String("mainclass")) #define COMMAND_NONREENTRANT Doc::alias(QLatin1String("nonreentrant")) #define COMMAND_OBSOLETE Doc::alias(QLatin1String("obsolete")) +#define COMMAND_PAGEKEYWORDS Doc::alias(QLatin1String("pagekeywords")) #define COMMAND_PRELIMINARY Doc::alias(QLatin1String("preliminary")) #define COMMAND_INPUBLICGROUP Doc::alias(QLatin1String("inpublicgroup")) #define COMMAND_REENTRANT Doc::alias(QLatin1String("reentrant")) @@ -170,6 +171,7 @@ QSet<QString> CodeParser::commonMetaCommands() << COMMAND_MAINCLASS << COMMAND_NONREENTRANT << COMMAND_OBSOLETE + << COMMAND_PAGEKEYWORDS << COMMAND_PRELIMINARY << COMMAND_INPUBLICGROUP << COMMAND_REENTRANT @@ -230,6 +232,9 @@ void CodeParser::processCommonMetaCommand(const Location &location, else if (command == COMMAND_SINCE) { node->setSince(arg); } + else if (command == COMMAND_PAGEKEYWORDS) { + node->addPageKeywords(arg); + } else if (command == COMMAND_SUBTITLE) { if (node->type() == Node::Fake) { FakeNode *fake = static_cast<FakeNode *>(node); diff --git a/tools/qdoc3/config.cpp b/tools/qdoc3/config.cpp index f62ec24..acb1576 100644 --- a/tools/qdoc3/config.cpp +++ b/tools/qdoc3/config.cpp @@ -671,7 +671,9 @@ void Config::load(Location location, const QString& fileName) location.fatal(tr("Cannot open file '%1': %2").arg(fileName).arg(fin.errorString())); } - QString text = fin.readAll(); + QTextStream stream(&fin); + stream.setCodec("UTF-8"); + QString text = stream.readAll(); text += QLatin1String("\n\n"); text += QChar('\0'); fin.close(); diff --git a/tools/qdoc3/config.h b/tools/qdoc3/config.h index 5e7e6f1..6f23469 100644 --- a/tools/qdoc3/config.h +++ b/tools/qdoc3/config.h @@ -140,8 +140,10 @@ class Config #define CONFIG_INDEXES "indexes" #define CONFIG_LANGUAGE "language" #define CONFIG_MACRO "macro" +#define CONFIG_NATURALLANGUAGE "naturallanguage" #define CONFIG_OBSOLETELINKS "obsoletelinks" #define CONFIG_OUTPUTDIR "outputdir" +#define CONFIG_OUTPUTENCODING "outputencoding" #define CONFIG_OUTPUTLANGUAGE "outputlanguage" #define CONFIG_OUTPUTFORMATS "outputformats" #define CONFIG_PROJECT "project" @@ -150,6 +152,7 @@ class Config #define CONFIG_SLOW "slow" #define CONFIG_SHOWINTERNAL "showinternal" #define CONFIG_SOURCEDIRS "sourcedirs" +#define CONFIG_SOURCEENCODING "sourceencoding" #define CONFIG_SOURCES "sources" #define CONFIG_SPURIOUS "spurious" #define CONFIG_STYLESHEETS "stylesheets" diff --git a/tools/qdoc3/cppcodemarker.cpp b/tools/qdoc3/cppcodemarker.cpp index 22562f3..657cfbb 100644 --- a/tools/qdoc3/cppcodemarker.cpp +++ b/tools/qdoc3/cppcodemarker.cpp @@ -881,8 +881,7 @@ QString CppCodeMarker::addMarkUp(const QString& protectedCode, static QRegExp globalX("[\n{()=] *([a-zA-Z_][a-zA-Z_0-9]*)[ \n]*\\("); static QRegExp multiLineComment("/(?:( )?\\*(?:[^*]+|\\*(?! /))*\\*\\1/)"); multiLineComment.setMinimal(true); - static QRegExp singleLineCommentLine("(?:^|\n)(?:[^\n&]|&(?!quot;)|"(?:[^&\n\\\\]|&(?!quot;)|\\\\"|\\\\(?!"))*")*//(?!!)[^!\n]*"); - static QRegExp singleLineComment("//(?!!)[^!\n]*"); + static QRegExp singleLineComment("[^:]//(?!!)[^!\\n]*"); static QRegExp preprocessor("(?:^|\n)(#[ \t]*(?:include|if|elif|endif|error|pragma|define" "|warning)(?:(?:\\\\\n|\\n#)[^\n]*)*)"); static QRegExp literals(""(?:[^\\\\&]|\\\\[^\n]|&(?!quot;))*"" @@ -1057,8 +1056,7 @@ QString CppCodeMarker::addMarkUp(const QString& protectedCode, int mlpos; int slpos; int len; - int sllpos = singleLineCommentLine.indexIn(result, pos); - slpos = sllpos == -1 ? -1 : singleLineComment.indexIn(result, sllpos); + slpos = singleLineComment.indexIn(result, pos); mlpos = multiLineComment.indexIn(result, pos); if (slpos == -1 && mlpos == -1) @@ -1069,13 +1067,13 @@ QString CppCodeMarker::addMarkUp(const QString& protectedCode, len = multiLineComment.matchedLength(); } else if (mlpos == -1) { - pos = slpos; - len = singleLineComment.matchedLength(); + pos = slpos + 1; + len = singleLineComment.matchedLength() - 1; } else { if (slpos < mlpos) { - pos = slpos; - len = singleLineComment.matchedLength(); + pos = slpos + 1; + len = singleLineComment.matchedLength() - 1; } else { pos = mlpos; diff --git a/tools/qdoc3/cppcodeparser.cpp b/tools/qdoc3/cppcodeparser.cpp index 7d08c77..c8655a4 100644 --- a/tools/qdoc3/cppcodeparser.cpp +++ b/tools/qdoc3/cppcodeparser.cpp @@ -281,8 +281,8 @@ void CppCodeParser::parseHeaderFile(const Location& location, const QString& filePath, Tree *tree) { - FILE *in = fopen(QFile::encodeName(filePath), "r"); - if (!in) { + QFile in(filePath); + if (!in.open(QIODevice::ReadOnly)) { location.error(tr("Cannot open C++ header file '%1'").arg(filePath)); return; } @@ -295,7 +295,7 @@ void CppCodeParser::parseHeaderFile(const Location& location, matchDeclList(tree->root()); if (!fileTokenizer.version().isEmpty()) tree->setVersion(fileTokenizer.version()); - fclose(in); + in.close(); if (fileLocation.fileName() == "qiterator.h") parseQiteratorDotH(location, filePath); @@ -312,8 +312,8 @@ void CppCodeParser::parseSourceFile(const Location& location, const QString& filePath, Tree *tree) { - FILE *in = fopen(QFile::encodeName(filePath), "r"); - if (!in) { + QFile in(filePath); + if (!in.open(QIODevice::ReadOnly)) { location.error(tr("Cannot open C++ source file '%1' (%2)").arg(filePath).arg(strerror(errno))); return; } @@ -325,7 +325,7 @@ void CppCodeParser::parseSourceFile(const Location& location, readToken(); usedNamespaces.clear(); matchDocsAndStuff(); - fclose(in); + in.close(); } /*! diff --git a/tools/qdoc3/doc.cpp b/tools/qdoc3/doc.cpp index 17a6efd..ad4cdde 100644 --- a/tools/qdoc3/doc.cpp +++ b/tools/qdoc3/doc.cpp @@ -3056,7 +3056,8 @@ QString Doc::canonicalTitle(const QString &title) slurping = true; } else { - // !alnum && slurping -> nothin + result += title[i]; + lastAlnum = result.size(); } } result.truncate(lastAlnum); diff --git a/tools/qdoc3/doc/classic.css b/tools/qdoc3/doc/classic.css new file mode 100644 index 0000000..b8cae8e --- /dev/null +++ b/tools/qdoc3/doc/classic.css @@ -0,0 +1,284 @@ +BODY,H1,H2,H3,H4,H5,H6,P,CENTER,TD,TH,UL,DL,DIV { + font-family: Arial, Geneva, Helvetica, sans-serif; +} +H1 { + text-align: center; + font-size: 160%; +} +H2 { + font-size: 120%; +} +H3 { + font-size: 100%; +} + +h3.fn,span.fn +{ + background-color: #eee; + border-width: 1px; + border-style: solid; + border-color: #ddd; + font-weight: bold; + padding: 6px 0px 6px 10px; + margin: 42px 0px 0px 0px; +} + +hr { + border: 0; + color: #a0a0a0; + background-color: #ccc; + height: 1px; + width: 100%; + text-align: left; + margin: 34px 0px 34px 0px; +} + +table.valuelist { + border-width: 1px 1px 1px 1px; + border-style: solid; + border-color: #dddddd; + border-collapse: collapse; + background-color: #f0f0f0; +} + +table.indextable { + border-width: 1px 1px 1px 1px; + border-style: solid; + border-collapse: collapse; + background-color: #f0f0f0; + border-color:#555; + font-size: 100%; +} + +table td.largeindex { + border-width: 1px 1px 1px 1px; + border-collapse: collapse; + background-color: #f0f0f0; + border-color:#555; + font-size: 120%; +} + +table.valuelist th { + border-width: 1px 1px 1px 2px; + padding: 4px; + border-style: solid; + border-color: #666; + color:white; + background-color:#666; +} + +th.titleheader { + border-width: 1px 0px 1px 0px; + padding: 2px; + border-style: solid; + border-color: #666; + color:white; + background-color:#555; + background-image:url('images/gradient.png')}; + background-repeat: repeat-x; + font-size: 100%; +} + + +th.largeheader { + border-width: 1px 0px 1px 0px; + padding: 4px; + border-style: solid; + border-color: #444; + color:white; + background-color:#555555; + font-size: 120%; +} + +p { + + margin-left: 4px; + margin-top: 8px; + margin-bottom: 8px; +} + +a:link +{ + color: #0046ad; + text-decoration: none +} + +a:visited +{ + color: #672967; + text-decoration: none +} + +a.obsolete +{ + color: #661100; + text-decoration: none +} + +a.compat +{ + color: #661100; + text-decoration: none +} + +a.obsolete:visited +{ + color: #995500; + text-decoration: none +} + +a.compat:visited +{ + color: #995500; + text-decoration: none +} + +body +{ + background: #ffffff; + color: black +} + +table.generic, table.annotated +{ + border-width: 1px; + border-color:#bbb; + border-style:solid; + border-collapse:collapse; +} + +table td.memItemLeft { + width: 180px; + padding: 2px 0px 0px 8px; + margin: 4px; + border-width: 1px; + border-color: #E0E0E0; + border-style: none; + font-size: 100%; + white-space: nowrap +} + +table td.memItemRight { + padding: 2px 8px 0px 8px; + margin: 4px; + border-width: 1px; + border-color: #E0E0E0; + border-style: none; + font-size: 100%; +} + +table tr.odd { + background: #f0f0f0; + color: black; +} + +table tr.even { + background: #e4e4e4; + color: black; +} + +table.annotated th { + padding: 3px; + text-align: left +} + +table.annotated td { + padding: 3px; +} + +table tr pre +{ + padding-top: 0px; + padding-bottom: 0px; + padding-left: 0px; + padding-right: 0px; + border: none; + background: none +} + +tr.qt-style +{ + background: #96E066; + color: black +} + +body pre +{ + padding: 0.2em; + border: #e7e7e7 1px solid; + background: #f1f1f1; + color: black +} + +table tr.qt-code pre +{ + padding: 0.2em; + border: #e7e7e7 1px solid; + background: #f1f1f1; + color: black +} + +span.preprocessor, span.preprocessor a +{ + color: darkblue; +} + +span.comment +{ + color: darkred; + font-style: italic +} + +span.string,span.char +{ + color: darkgreen; +} + +.title +{ + text-align: center +} + +.subtitle +{ + font-size: 0.8em +} + +.small-subtitle +{ + font-size: 0.65em +} + +.qmlitem { + padding: 0; +} + +.qmlname { + white-space: nowrap; +} + +.qmltype { + text-align: center; + font-size: 160%; +} + +.qmlproto { + background-color: #eee; + border-width: 1px; + border-style: solid; + border-color: #ddd; + font-weight: bold; + padding: 6px 10px 6px 10px; + margin: 42px 0px 0px 0px; +} + +.qmlreadonly { + float: right; + color: red +} + +.qmldoc { +} + +*.qmlitem p { +} diff --git a/tools/qdoc3/doc/examples/layoutmanagement.qdocinc b/tools/qdoc3/doc/examples/layoutmanagement.qdocinc new file mode 100644 index 0000000..01f8acf --- /dev/null +++ b/tools/qdoc3/doc/examples/layoutmanagement.qdocinc @@ -0,0 +1,13 @@ +\section1 Layout Classes + +The Qt layout system provides a simple and powerful way of specifying +the layout of child widgets. + +By specifying the logical layout once, you get the following benefits: + +\list + \o Positioning of child widgets. + \o Sensible default sizes for windows. + \o Sensible minimum sizes for windows. + \o ... +\endlist diff --git a/tools/qdoc3/doc/examples/main.cpp b/tools/qdoc3/doc/examples/main.cpp new file mode 100644 index 0000000..e2cf6c5 --- /dev/null +++ b/tools/qdoc3/doc/examples/main.cpp @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the tools applications of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QApplication> +#include <QPushButton> + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + + QPushButton *hello("Hello world!"); + hello.resize(100, 30); + + hello.show(); + return app.exec(); +} diff --git a/tools/qdoc3/doc/examples/minimum.qdocconf b/tools/qdoc3/doc/examples/minimum.qdocconf new file mode 100644 index 0000000..e5e9e67 --- /dev/null +++ b/tools/qdoc3/doc/examples/minimum.qdocconf @@ -0,0 +1,42 @@ +# QDoc is a tool that constantly evolves to suit our needs, +# and there are some compatibility issues between old and new +# practices. For that reason, any QDoc configuration file needs to +# include compat.qdocconf. + +#include(compat.qdocconf) + + +# The outputdir variable specifies the directory +# where QDoc will put the generated documentation. + +outputdir = html + + +# The headerdirs variable specifies the directories +# containing the header files associated +# with the .cpp source files used in the documentation. + +headerdirs = . + + +# The sourcedirs variable specifies the +# directories containing the .cpp or .qdoc +# files used in the documentation. + +#sourcedirs = . + + +# The exampledirs variable specifies the directories containing +# the source code of the example files. + +exampledirs = . + + +# The imagedirs variable specifies the +# directories containing the images used in the documentation. + +imagedirs = ./images + + + + diff --git a/tools/qdoc3/doc/examples/objectmodel.qdocinc b/tools/qdoc3/doc/examples/objectmodel.qdocinc new file mode 100644 index 0000000..02b5991 --- /dev/null +++ b/tools/qdoc3/doc/examples/objectmodel.qdocinc @@ -0,0 +1,11 @@ +\section1 Qt Object Model + +The standard C++ object model provides very efficient runtime support +for the object paradigm. But its static nature is inflexibile in +certain problem domains. Graphical user interface programming is a +domain that requires both runtime efficiency and a high level of +flexibility. Qt provides this, by combining the speed of C++ with the +flexibility of the Qt Object Model. + +... + diff --git a/tools/qdoc3/doc/examples/signalandslots.qdocinc b/tools/qdoc3/doc/examples/signalandslots.qdocinc new file mode 100644 index 0000000..cfae43a --- /dev/null +++ b/tools/qdoc3/doc/examples/signalandslots.qdocinc @@ -0,0 +1,9 @@ +\section1 Signals and Slots + +Signals and slots are used for communication between objects. The signals and +slots mechanism is a central feature of Qt and probably the part that differs +most from the features provided by other frameworks. + +\section2 Introduction + +In GUI programming, when we ... diff --git a/tools/qdoc3/doc/files/compat.qdocconf b/tools/qdoc3/doc/files/compat.qdocconf new file mode 100644 index 0000000..5745ed9 --- /dev/null +++ b/tools/qdoc3/doc/files/compat.qdocconf @@ -0,0 +1,31 @@ +alias.i = e +alias.include = input + +macro.0 = "\\\\0" +macro.b = "\\\\b" +macro.n = "\\\\n" +macro.r = "\\\\r" +macro.i = "\\o" +macro.i11 = "\\o{1,1}" +macro.i12 = "\\o{1,2}" +macro.i13 = "\\o{1,3}" +macro.i14 = "\\o{1,4}" +macro.i15 = "\\o{1,5}" +macro.i16 = "\\o{1,6}" +macro.i17 = "\\o{1,7}" +macro.i18 = "\\o{1,8}" +macro.i19 = "\\o{1,9}" +macro.i21 = "\\o{2,1}" +macro.i31 = "\\o{3,1}" +macro.i41 = "\\o{4,1}" +macro.i51 = "\\o{5,1}" +macro.i61 = "\\o{6,1}" +macro.i71 = "\\o{7,1}" +macro.i81 = "\\o{8,1}" +macro.i91 = "\\o{9,1}" +macro.img = "\\image" +macro.endquote = "\\endquotation" +macro.relatesto = "\\relates" + +spurious = "Missing comma in .*" \ + "Missing pattern .*" diff --git a/tools/qdoc3/doc/files/qt.qdocconf b/tools/qdoc3/doc/files/qt.qdocconf new file mode 100644 index 0000000..942d023 --- /dev/null +++ b/tools/qdoc3/doc/files/qt.qdocconf @@ -0,0 +1,115 @@ +include(compat.qdocconf) +include(macros.qdocconf) +include(qt-cpp-ignore.qdocconf) +include(qt-html-templates.qdocconf) +include(qt-defines.qdocconf) + +project = Qt +versionsym = +version = %VERSION% +description = Qt Reference Documentation +url = http://qt.nokia.com/doc/4.6 + +edition.Console.modules = QtCore QtDBus QtNetwork QtScript QtSql QtXml \ + QtXmlPatterns QtTest +edition.Desktop.modules = QtCore QtDBus QtGui QtNetwork QtOpenGL QtScript QtScriptTools QtSql QtSvg \ + QtWebKit QtXml QtXmlPatterns Qt3Support QtHelp \ + QtDesigner QtAssistant QAxContainer Phonon \ + QAxServer QtUiTools QtTest QtDBus +edition.DesktopLight.modules = QtCore QtDBus QtGui Qt3SupportLight QtTest +edition.DesktopLight.groups = -graphicsview-api + +qhp.projects = Qt + +qhp.Qt.file = qt.qhp +qhp.Qt.namespace = com.trolltech.qt.460 +qhp.Qt.virtualFolder = qdoc +qhp.Qt.indexTitle = Qt Reference Documentation +qhp.Qt.indexRoot = + +# Files not referenced in any qdoc file (last four are needed by qtdemo) +# See also extraimages.HTML +qhp.Qt.extraFiles = classic.css \ + images/qt-logo.png \ + images/taskmenuextension-example.png \ + images/coloreditorfactoryimage.png \ + images/dynamiclayouts-example.png \ + images/stylesheet-coffee-plastique.png + +qhp.Qt.filterAttributes = qt 4.6.0 qtrefdoc +qhp.Qt.customFilters.Qt.name = Qt 4.6.0 +qhp.Qt.customFilters.Qt.filterAttributes = qt 4.6.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 fake:headerfile +qhp.Qt.subprojects.classes.sortPages = true +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 + +language = Cpp + +headerdirs = $QTDIR/src \ + $QTDIR/extensions/activeqt \ + $QTDIR/tools/assistant/lib \ + $QTDIR/tools/assistant/compat/lib \ + $QTDIR/tools/designer/src/uitools \ + $QTDIR/tools/designer/src/lib/extension \ + $QTDIR/tools/designer/src/lib/sdk \ + $QTDIR/tools/designer/src/lib/uilib \ + $QTDIR/tools/qtestlib/src \ + $QTDIR/tools/qdbus/src +sourcedirs = $QTDIR/src \ + $QTDIR/doc/src \ + $QTDIR/extensions/activeqt \ + $QTDIR/tools/assistant/lib \ + $QTDIR/tools/assistant/compat/lib \ + $QTDIR/tools/designer/src/uitools \ + $QTDIR/tools/designer/src/lib/extension \ + $QTDIR/tools/designer/src/lib/sdk \ + $QTDIR/tools/designer/src/lib/uilib \ + $QTDIR/tools/qtestlib/src \ + $QTDIR/tools/qdbus + +excludedirs = $QTDIR/src/3rdparty/clucene \ + $QTDIR/src/3rdparty/des \ + $QTDIR/src/3rdparty/freetype \ + $QTDIR/src/3rdparty/harfbuzz \ + $QTDIR/src/3rdparty/kdebase \ + $QTDIR/src/3rdparty/libjpeg \ + $QTDIR/src/3rdparty/libmng \ + $QTDIR/src/3rdparty/libpng \ + $QTDIR/src/3rdparty/libtiff \ + $QTDIR/src/3rdparty/md4 \ + $QTDIR/src/3rdparty/md5 \ + $QTDIR/src/3rdparty/patches \ + $QTDIR/src/3rdparty/sha1 \ + $QTDIR/src/3rdparty/sqlite \ + $QTDIR/src/3rdparty/webkit/JavaScriptCore \ + $QTDIR/src/3rdparty/webkit/WebCore \ + $QTDIR/src/3rdparty/wintab \ + $QTDIR/src/3rdparty/zlib \ + $QTDIR/doc/src/snippets \ + $QTDIR/src/3rdparty/phonon/gstreamer \ + $QTDIR/src/3rdparty/phonon/ds9 \ + $QTDIR/src/3rdparty/phonon/qt7 \ + $QTDIR/src/3rdparty/phonon/waveout + +sources.fileextensions = "*.cpp *.qdoc *.mm" +examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp" + +exampledirs = $QTDIR/doc/src \ + $QTDIR/examples \ + $QTDIR/examples/tutorials \ + $QTDIR \ + $QTDIR/qmake/examples \ + $QTDIR/src/3rdparty/webkit/WebKit/qt/docs +imagedirs = $QTDIR/doc/src/images \ + $QTDIR/examples +outputdir = $QTDIR/doc/html +tagfile = $QTDIR/doc/html/qt.tags +base = file:$QTDIR/doc/html diff --git a/tools/qdoc3/doc/images/happy.gif b/tools/qdoc3/doc/images/happy.gif Binary files differnew file mode 100644 index 0000000..a4597f6 --- /dev/null +++ b/tools/qdoc3/doc/images/happy.gif diff --git a/tools/qdoc3/doc/images/happyguy.jpg b/tools/qdoc3/doc/images/happyguy.jpg Binary files differnew file mode 100644 index 0000000..e860479 --- /dev/null +++ b/tools/qdoc3/doc/images/happyguy.jpg diff --git a/tools/qdoc3/doc/images/qt-logo.png b/tools/qdoc3/doc/images/qt-logo.png Binary files differnew file mode 100644 index 0000000..14ddf2a --- /dev/null +++ b/tools/qdoc3/doc/images/qt-logo.png diff --git a/tools/qdoc3/doc/images/training.jpg b/tools/qdoc3/doc/images/training.jpg Binary files differnew file mode 100644 index 0000000..c2ce5c3 --- /dev/null +++ b/tools/qdoc3/doc/images/training.jpg diff --git a/tools/qdoc3/doc/qdoc-manual.qdoc b/tools/qdoc3/doc/qdoc-manual.qdoc new file mode 100644 index 0000000..e2f670c --- /dev/null +++ b/tools/qdoc3/doc/qdoc-manual.qdoc @@ -0,0 +1,8695 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page index.html + \nextpage QDoc Manual + + \title QDoc Manual - Table of Contents + + \list + \o \l{QDoc Manual} + \o \l{QDoc Commands} + \list + \o \l{Markup Commands} + \o \l{Text Formatting Commands} + \o \l{Document Structuring Commands} + \o \l{Verbatim Code Commands} + \o \l{Quoting External Code Commands} + \list + \o \l{Example File} + \endlist + \o \l{Linking Commands} + \o \l{Graphic Commands} + \o \l{Container Commands} + \o \l{Document Contents Commands} + \o \l{Miscellaneous Commands} + \list + \o \l{signalandslots.qdocinc} + \o \l{objectmodel.qdocinc} + \o \l{layoutmanagement.qdocinc} + \endlist + \o \l{Topical Commands} + \o \l{Contextual Commands} + \o \l{Navigation Commands} + \o \l{Status Commands} + \o \l{Thread Support Commands} + \o \l{Relating Commands} + \o \l{Grouping Commands} + \o \l{Title Commands} + \endlist + \o \l{QDoc Configuration} + \list + \o \l{General Variables} + \o \l{Creating Help Project Files} + \o \l{C++ Specific Variables} + \o \l{HTML Specific Variables} + \o \l{Supporting Derived Projects} + \o \l{QDoc Compatibility} + \o \l{qt.qdocconf} + \o \l{minimum.qdocconf} + \endlist + \o \l{QDoc Commands - Alphabetical List} + \endlist +*/ + +/*! + \page 01-qdoc-manual.html + \contentspage QDoc Manual - Table of Contents + \previouspage QDoc Manual - Table of Contents + \nextpage QDoc Commands + + \title QDoc Manual + + QDoc is the internal tool used by Qt Development Frameworks for generating + documentation. This document is a reference for QDoc command syntax and + configuration. + + \section1 Overview + + \list I + \o \section2 \l {QDoc Commands} + + \l {QDoc Commands - Alphabetical List}{A complete alphabetical + list}. + + There are two main categories of commands for QDoc: markup + commands and meta-commands. + + The markup commands indicate the generated documentation's + appearance and logical structure. The meta-commands provide + information about the document as well as the documented + item. The meta-commands can be further categorized as topical + commands and contextual commands. + + \list + \o \l {Markup Commands} + \list + \o \l {Text Formatting Commands}{Text Formatting} + \o \l {Document Structuring Commands}{Document Structuring} + \o \l {Verbatim Code Commands}{Verbatim Code} + \o \l {Quoting External Code Commands}{Quoting External Code} + \o \l {Linking Commands}{Linking} + \o \l {Graphic Commands}{Graphic} + \o \l {Container Commands}{Container} + \o \l {Document Contents Commands}{Document Contents} + \o \l {Miscellaneous Commands}{Miscellaneous} + \endlist + \o \l {Topical Commands} + \o \l {Contextual Commands} + \list + \o \l {Navigation Commands}{Navigation} + \o \l {Status Commands}{Status} + \o \l {Thread Support Commands}{Thread Support} + \o \l {Relating Commands}{Relating} + \o \l {Grouping Commands}{Grouping} + \o \l {Title Commands}{Title} + \endlist + \endlist + \endlist + + \list II + \o \section2 \l {QDoc Configuration} + + When running QDoc to generate the documentation, you must + specify a configuration file on the command line. The + configuration file is a list of entries of entries of the form + "variable = value". + + \list + \o \l {Configuration Variables} + \o \l {Configuration File Examples} + \endlist + + Some particular configuration variables allow you to use QDoc + to support Qt-based projects; i.e to make projects, such as Qt + Solutions, contain references to the online Qt documentation. + + \list + \o \l {Supporting Derived Projects} + \endlist + + QDoc is a tool that constantly evolves to suit our needs, for + that reason there are some compatibility issues between old and + new practices. + + \list + \o \l {QDoc Compatibility} + \endlist + \endlist +*/ + +/*! + \page 02-qdoc-commands.html + \previouspage QDoc Manual + \contentspage QDoc Manual - Table of Contents + \nextpage Markup Commands + + \title QDoc Commands + + There are two main categories of commands for QDoc: markup + commands and meta-commands. + + The markup commands indicate the generated documentation's visual + appearance and logical structure. The meta-commands provide + information about the documentation unit as well as the documented + item. The meta-commands can be further categorized as topical + commands and contextual commands. + + \section1 Alphabetical List + + A complete \l{QDoc Commands - Alphabetical List } + {alphabetical list of the QDoc commands}. + + \section1 Categories + + \list + \o \l {Markup Commands} + \o \l {Topical Commands} + \o \l {Contextual Commands} + \endlist +*/ + +/*! + \page 03-qdoc-commands-markup.html + \contentspage QDoc Manual - Table of Contents + \previouspage QDoc Commands + \nextpage Text Formatting Commands + + \title Markup Commands + + The markup commands indicate the generated documentation's visual + appearance and logical structure. + + \section1 Alphabetical List + + \l {04-qdoc-commands-textformatting.html#backslash}{\\\\}, + \l {04-qdoc-commands-textformatting.html#a}{\\a}, + \l {11-qdoc-commands-documentcontents.html#abstract}{\\abstract}, + \l {06-qdoc-commands-verbatimcode.html#badcode}{\\badcode}, + \l {04-qdoc-commands-textformatting.html#bold}{\\bold}, + \l {11-qdoc-commands-documentcontents.html#brief}{\\brief}, + \l {04-qdoc-commands-textformatting.html#c}{\\c}, + \l {09-qdoc-commands-graphic.html#caption}{\\caption}, + \l {05-qdoc-commands-documentstructuring.html#chapter}{\\chapter}, + \l {06-qdoc-commands-verbatimcode.html#code}{\\code}, + \l {07-0-qdoc-commands-quoting.html#codeline}{\\codeline}, + \l {07-0-qdoc-commands-quoting.html#dots}{\\dots}, + \l {12-0-qdoc-commands-miscellaneous.html#else}{\\else}, + \l {12-0-qdoc-commands-miscellaneous.html#endif}{\\endif}, + \l {12-0-qdoc-commands-miscellaneous.html#expire}{\\expire}, + \l {11-qdoc-commands-documentcontents.html#footnote}{\\footnote}, + \l {12-0-qdoc-commands-miscellaneous.html#generatelist}{\\generatelist}, + \l {10-qdoc-commands-container.html#header}{\\header}, + \l {04-qdoc-commands-textformatting.html#i}{\\i}, + \l {12-0-qdoc-commands-miscellaneous.html#if}{\\if}, + \l {09-qdoc-commands-graphic.html#image}{\\image}, + \l {12-0-qdoc-commands-miscellaneous.html#include}{\\include}, + \l {09-qdoc-commands-graphic.html#inlineimage}{\\inlineimage}, + \l {08-qdoc-commands-linking.html#keyword}{\\keyword}, + \l {08-qdoc-commands-linking.html#l}{\\l}, + \l {11-qdoc-commands-documentcontents.html#legalese}{\\legalese}, + \l {10-qdoc-commands-container.html#list}{\\list}, + \l {12-0-qdoc-commands-miscellaneous.html#meta}{\\meta}, + \l {06-qdoc-commands-verbatimcode.html#newcode}{\\newcode}, + \l {10-qdoc-commands-container.html#o}{\\o}, + \l {06-qdoc-commands-verbatimcode.html#oldcode}{\\oldcode}, + \l {12-0-qdoc-commands-miscellaneous.html#omit}{\\omit}, + \l {05-qdoc-commands-documentstructuring.html#part}{\\part}, + \l {07-0-qdoc-commands-quoting.html#printline}{\\printline}, + \l {07-0-qdoc-commands-quoting.html#printto}{\\printto}, + \l {07-0-qdoc-commands-quoting.html#printuntil}{\\printuntil}, + \l {11-qdoc-commands-documentcontents.html#quotation}{\\quotation}, + \l {07-0-qdoc-commands-quoting.html#quotefile}{\\quotefile}, + \l {07-0-qdoc-commands-quoting.html#quotefromfile}{\\quotefromfile}, + \l {12-0-qdoc-commands-miscellaneous.html#raw}{\\raw}, + \l {10-qdoc-commands-container.html#row}{\\row}, + \l {08-qdoc-commands-linking.html#sa}{\\sa}, + \l {05-qdoc-commands-documentstructuring.html#sectionOne}{\\section1}, + \l {05-qdoc-commands-documentstructuring.html#sectionTwo}{\\section2}, + \l {05-qdoc-commands-documentstructuring.html#sectionThree}{\\section3}, + \l {05-qdoc-commands-documentstructuring.html#sectionFour}{\\section4}, + \l {07-0-qdoc-commands-quoting.html#skipline}{\\skipline}, + \l {07-0-qdoc-commands-quoting.html#skipto}{\\skipto}, + \l {07-0-qdoc-commands-quoting.html#skipuntil}{\\skipuntil}, + \l {07-0-qdoc-commands-quoting.html#snippet}{\\snippet}, + \l {04-qdoc-commands-textformatting.html#sub}{\\sub}, + \l {04-qdoc-commands-textformatting.html#sup}{\\sup}, + \l {10-qdoc-commands-container.html#table}{\\table}, + \l {11-qdoc-commands-documentcontents.html#tableofcontents} + {\\tableofcontents}, + \l {08-qdoc-commands-linking.html#target}{\\target}, + \l {04-qdoc-commands-textformatting.html#tt}{\\tt}, + \l {04-qdoc-commands-textformatting.html#underline}{\\underline}, + \l {12-0-qdoc-commands-miscellaneous.html#raw}{\\unicode}, + \l {11-qdoc-commands-documentcontents.html#warning}{\\warning} + + \section1 Categories + \list + \o \l {Text Formatting Commands} + \o \l {Document Structuring Commands} + \o \l {Verbatim Code Commands} + \o \l {Quoting External Code Commands} + \o \l {Linking Commands} + \o \l {Graphic Commands} + \o \l {Container Commands} + \o \l {Document Contents Commands} + \o \l {Miscellaneous Commands} + \endlist + +*/ + +/*! + \page 04-qdoc-commands-textformatting.html + \contentspage QDoc Manual - Table of Contents + \previouspage Markup Commands + \nextpage Document Structuring Commands + + \title Text Formatting Commands + + The text formatting commands indicate how the regular text in the + documentation is rendered. + + \section1 Alphabetical List + + \l {04-qdoc-commands-textformatting.html#backslash}{\\\\}, + \l {04-qdoc-commands-textformatting.html#a}{\\a}, + \l {04-qdoc-commands-textformatting.html#bold}{\\bold}, + \l {04-qdoc-commands-textformatting.html#c}{\\c}, + \l {04-qdoc-commands-textformatting.html#i}{\\i}, + \l {04-qdoc-commands-textformatting.html#sub}{\\sub}, + \l {04-qdoc-commands-textformatting.html#sup}{\\sup}, + \l {04-qdoc-commands-textformatting.html#tt}{\\tt}, + \l {04-qdoc-commands-textformatting.html#underline}{\\underline} + + \section1 Command Descriptions + + \table + \header + \o Command + \o Description + + \row + + \o \bold \\\\ \target backslash + \o \bold {The \\\\ command expands to a single backslash.} + + QDoc commands always start with a backslash alone. To + display an actual backslash in the text you need to type + two of the kind. If you want to display two backslashes, + you need to type four, and so forth. For example: + + \code + / *! + The \\\\ command is useful if you want a + backslash to appear verbatim, for example, + writing C:\\windows\\home\\. + * / + \endcode + + will be rendered as + + \quotation + The \\\\ command is useful if you want a + backslash to appear verbatim, for example, + writing C:\\windows\\home\\. + \endquotation + + However, if you want your text to appear in a typewriter + font as well, you can use the \l {c}{\\c} command instead, + which accepts and renders the backslash as any other + character. For example: + + \code + / *! + The \\c command is useful if you want a + backslash to appear verbatim, and the word + that contains it written in a typewriter font, + like this: \c {C:\windows\home\}. + * / + \endcode + + will be rendered as + + \quotation + The \\c command is useful if you want a + backslash to appear verbatim, and the word + that contains it written in a typewriter font, + like this: \c {C:\windows\home\}. + \endquotation + + \row + \o \bold \\a \target a + \o \bold {The \\a command indicates that the next word + is a parameter when documenting functions.} + + Warnings are emitted when function parameters are + undocumented or misspelled, so whenever you write + documentation for functions you should make sure you + mention all the parameters and precede each of these by the + \\a command. The parameter is then rendered in italic. For + example: + + \code + / *! + Constructs a line edit containing the text + \a contents. + + The \a parent parameter is sent to the + QWidget constructor. + * / + + QLineEdit::QLineEdit(const QString &contents, QWidget *parent) + :QWidget(parent) + { + ... + } + + \endcode + + will be rendered as + + \quotation + \bold {QLineEdit::QLineEdit ( const QString & + contents, QWidget *parent )} + + Constructs a line edit containing the text \a contents. + + The \a parent parameter is sent to the QWidget + constructor. + + \endquotation + + The \\a command follows the same conventions as the \l + {i}{\\i} command for \l {argument}{punctuation, parentheses + and use of braces} for the argument. However, a parameter + is always a single word, so braces are rarely + necessary. And for the same reason, parentheses seldom + occur. + + \row + \o \bold \\c \target c + \o \bold {The \\c command can be used to render variables, + user-defined classes and C++ keywords like \c int, + \c for, etc.} + + The command renders its argument using a typewriter font. For + example: + + \code + / *! + The \c AnalogClock class provides a clock widget with hour + and minute hands that is automatically updated every + few seconds. + * / + \endcode + + will be rendered as + + \quotation + The \c AnalogClock class provides a clock widget with hour + and minute hands that is automatically updated every + few seconds. + \endquotation + + The \\c command follows the same conventions as the \l + {i}{\\i} command for \l {argument}{punctuation, parentheses + and use of braces} for the argument. + + The \\c command accepts the special character \c \ within + its argument, i.e. it renders it as a normal character. So + if you want to use nested commands, you must use the \l + {tt}{teletype (\\tt)} command instead. + + See also \l {tt}{\\tt} and \l {code}{\\code}. + + \row + \o \bold \\tt \target tt + \o \bold {The \\tt command can be used to render variables, + user-defined classes and C++ keywords like \c int, \c + for, etc.} + + The \\tt command behaves just like the \l {c}{\\c} command, + except that \\tt parses QDoc commands (like \l {i}{\\i}, \l + {bold}{\\bold} and \l {underline}{\\underline}) contained + within its argument. + + The command renders its argument using a monospace + font. For example: + + \code + / *! + After \c setupUi() populates the main container with + child widgets it scans the main container's list of + slots for names with the form + \tt{on_\i{objectName}_\i{signalName}().} + * / + \endcode + + will be rendered as + + \quotation + After \c setupUi() populates the main container with + child widgets it scans the main container's list of + slots for names with the form + \tt{on_\i{objectName}_\i{signalName}().} + \endquotation + + The \\tt command follows the same conventions as the \l + {i}{\\i} command for \l {argument}{punctuation, parentheses + and use of braces} for the argument. + + See also \l {c}{\\c}. + + \row + \o \bold \\bold \target bold + \o \bold {The \\bold command renders its argument using + a bold font.} + + For example: + + \code + / *! + This is regular text; \bold {this text is + rendered using the \\bold command}. + * / + \endcode + + will be rendered as + + \quotation + This is regular text; \bold {this text is rendered using + the \\bold command}. + \endquotation + + The command follows the same conventions as the \l {i}{\\i} + command for \l {argument}{punctuation, parentheses and use + of braces} for the argument. + + \row + \o \bold \\i \target i + \o \bold {The \\i command renders its argument in italic.} + + \warning This is preliminary functionality. For + more information, see the \l + {26-qdoc-commands-compatibility.html#i-versus-e}{compatibility} + section. + + \target argument + Normally, a command argument ends at the next whitespace [1], + but braces can be used to group words [2]. For example: + + \code + / *! + Here, we render \i {a few words} in italic. + * / + \endcode + + will be rendered as + + \quotation + Here, we render \i {a few words} in italic. + \endquotation + + If you want to use other QDoc commands within an argument + that contains spaces, you always need to enclose the + argument with braces. But QDoc is smart enough to count + parentheses [3], so you don't need braces in cases like this: + + \code + / *! + An argument can sometimes contain whitespaces, + for example: \i QPushButton(tr("A Brand New Button")) + * / + \endcode + + will be rendered as + + \quotation + An argument can sometimes contain whitespaces, + for example: \i QPushButton(tr("A Brand New Button")) + \endquotation + + Finally, trailing punctuation is not included in an + argument [4], nor is 's [5] + + \raw HTML + <table align="center" cellpadding="2" + cellspacing="1" border="0"> + <tr valign="top" bgcolor="#a2c511"> + <th></th> + <th>QDoc Syntax</th> + <th>Generated Documentation</th> + </tr> + + <tr valign="top" bgcolor="#d0d0d0"> + <td>1</td> + <td>A variation of a command button is a \i menu + button.</td> + <td>A variation of a command button is a <i>menu</i> + button.</td> + </tr> + + <tr valign="top" bgcolor="#c0c0c0"> + <td>2</td> + <td>The QPushButton widget provides a + \i {command button}.</td> + <td>The QPushButton widget provides a + <i>command button</i>.</td> + </tr> + + <tr valign="top" bgcolor="#d0d0d0"> + <td>3</td> + <td>Another class of buttons are option buttons + \i (see QRadioButton).</td> + <td>Another class of buttons are option buttons + <i> (see QRadioButton)</i>.</td> + </tr> + + <tr valign="top" bgcolor="#c0c0c0"> + <td>4</td> + <td>A push button emits the signal \i clicked().</td> + <td>A push button emits the signal <i>clicked</i>().</td> + </tr> + + <tr valign="top" bgcolor="#d0d0d0"> + <td>5</td> + <td>The \i QPushButton's checked property is + false by default.</td> + <td>The <i>QPushButton</i>'s checked property is + false by default.</td> + </tr> + + </table> + \endraw + + \row + \o \bold \\sub \target sub + \o \bold {The \\sub command renders its argument lower + than the baseline of the regular text, using a smaller font.} + + For example: + + \code + / *! + Definition (Range): Consider the sequence + {x\sub n}\sub {n > 1} . The set + + {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...} + + is called the range of the sequence. + * / + \endcode + + will be rendered as + + \quotation + Definition (Range): Consider the sequence + {x\sub n}\sub {n > 1} . The set + + {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...} + + is called the range of the sequence. + \endquotation + + The \\sub command follows the same conventions as the \l + {i}{\\i} command for \l {argument}{punctuation, parentheses + and use of braces} for the argument. + + \row + \o \bold \\sup \target sup + \o \bold {The \\sup command renders its argument higher than + the baseline of the regular text, using a smaller font.} + + For example: + + \code + / *! + The series + + 1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ... + + is called the \i {geometric series}. + * / + \endcode + + will be rendered as + + \quotation + The series + + 1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ... + + is called the \i {geometric series}. + \endquotation + + The \\sup command follows the same conventions as the \l + {i}{\\i} command for \l {argument}{punctuation, parentheses + and use of braces} for the argument. + + \row + \o \bold \\underline \target underline + \o \bold {The \\underline command renders its argument underlined.} + + For example: + + \code + / *! + The \underline {F}ile menu gives the users the possibility + to open, and edit, an existing file, save a new or modified + file, and exit the application. + * / + \endcode + + will be rendered as + + \quotation + The \underline {F}ile menu gives the users the possibility + to open, and edit, an existing file, save a new or modified + file, and exit the application. + \endquotation + + The \\underline command follows the same conventions as the + \l {i}{\\i} command for \l {argument}{punctuation, + parentheses and use of braces} for the argument. \endtable +*/ + +/*! + \page 05-qdoc-commands-documentstructuring.html + \previouspage Text Formatting Commands + \contentspage QDoc Manual - Table of Contents + \nextpage Verbatim Code Commands + + \title Document Structuring Commands + + The document structuring commands divide the documentation into + sections. In total, there are six levels of sections in QDoc: \c + \part, \c \chapter, \c \section1, \c \section2, \c \section3 and + \c \section4. \c \section1 to \c \section4 correspond to the + traditional section, subsection, subsubsection and + subsubsubsection. + + \section1 Alphabetical List + + \l {05-qdoc-commands-documentstructuring.html#chapter}{\\chapter}, + \l {05-qdoc-commands-documentstructuring.html#part}{\\part}, + \l {05-qdoc-commands-documentstructuring.html#sectionOne}{\\section1}, + \l {05-qdoc-commands-documentstructuring.html#sectionTwo}{\\section2}, + \l {05-qdoc-commands-documentstructuring.html#sectionThree}{\\section3}, + \l {05-qdoc-commands-documentstructuring.html#sectionFour}{\\section4} + + \section1 Command Descriptions + + \table + \header + \o Command + \o Description + + \row + \o \bold \\part \target part + \o \bold {The \\part command is intended for use in + larger documents, and divides the document into parts.} + + In general a document structuring command considers + everything that follows it until the first line break as + its argument. The argument is rendered as the unit's + title. If the title needs to be spanned over several lines, + make sure that each line (except the last one) is ended + with a backslash. + + In total, there are six levels of sections in QDoc: \c + \part, \c \chapter, \c \section1, \c \section2, \c + \section3 and \c \section4. \c \section1 to \c \section4 + correspond to the traditional section, subsection, + subsubsection and subsubsubsection. + + There is a strict ordering of the section units: + + \code + part + | + chapter + | + section1 + | + section2 + | + section3 + | + section4 + \endcode + + For example, a \c section1 unit can only appear as the top + level section or inside a \c chapter unit. Skipping a + section unit, for example from \c part to \c section1, is + not allowed. + + You can \i begin with either of the three: \c part, \c + chapter or \c section1. For example: + + + \code + / *! + \part Basic Qt + + This is the first part. + + + \chapter Getting Started + + This is the first part's first chapter. + + + \section1 Hello Qt + + This is the first chapter's first section. + + + \section1 Making Connections + + This is the first chapter's second section. + + + \section1 Using the Reference Documentation + + This is the first chapter's third section. + + + \chapter Creating Dialogs + + This is the first part's second chapter. + + + \section1 Subclassing QDialog + + This is the second chapter's first section. + + ... + + + \part Intermediate Qt + + This is the second part. + + + \chapter Layout Management + + This is the second part's first chapter. + + + \section1 Basic Layouts + + This is the first chapter's first section. + + ... + * / + \endcode + + will be rendered as + + \quotation + \raw HTML + <a name="Basic Qt"> + <h1>Basic Qt</h1> + </a> + <p>This is the first part.</p> + + <a name="Getting started"> + <h2>Getting Started</h2> + </a> + This is the first part's first chapter.</p> + + <a name="Hello Qt"> + <h3>Hello Qt</h3> + </a> + <p>This is the first chapter's first section.</p> + + <a name="Making Connections"> + <h3>Making Connections</h3> + </a> + <p>This is the first chapter's second section.</p> + + <a name="Using the Reference Documentation"> + <h3>Using the Reference Documentation</h3> + </a> + <p>This is the first chapter's third section.</p> + + <a name="Creating Dialogs"> + <h2>Creating Dialogs</h2> + </a> + <p>This is the first part's second chapter.</p> + + <a name="Subclassing QDialog"> + <h3>Subclassing QDialog</h3> + </a> + <p>This is the second chapter's first section.</p> + + ... + + <a name="Intermediate Qt"> + <h1>Intermediate Qt</h1> + </a> + <p>This is the second part.</p> + + <a name="Layout Management"> + <h2>Layout Management</h2> + </a> + <p>This is the second part's first chapter.</p> + + <a name="Basic Layouts"> + <h3>Basic Layouts</h3> + </a> + <p>This is the first chapter's first section.</p> + + ... + + \endraw + \endquotation + + Each section level is a logical unit within the + document. Its title will appear on the table of contents + generated by the \l + {11-qdoc-commands-documentcontents.html#tableofcontents} + {\\tableofcontents} command. For example: + + \code + / *! + Contents: + + \tableofcontents + + ... + * / + \endcode + + will expand to + + \quotation + \raw HTML + <p>Contents:</p> + + <ul> + <li><a href="#Basic Qt">Basic Qt</a></li> + <ul> + <li><a href="#Getting Started">Getting Started</a></li> + <ul> + <li><a href="#Hello Qt">Hello Qt</a></li> + <li><a href="#Making Connections"> + Making Connections</a></li> + <li><a href="#Using the Reference Documentation"> + Using the Reference Documentation</a></li> + </ul> + <li><a href="#Creating Dialogs">Creating Dialogs</a></li> + <ul> + <li><a href="#Subclassing QDialog"> + Subclassing QDialog</a></li> + </ul> + </ul> + <li><a href="#Intermediate Qt">Intermediate Qt</a></li> + <ul> + <li><a href="#Layout Management"> + Layout Management</a></li> + <ul> + <li><a href="#Basic Layouts">Basic Layouts</a></li> + </ul> + </ul> + </ul> + + ... + \endraw + \endquotation + + \row + \o \bold \\chapter \target chapter + \o \bold {The \\chapter command is intended for use in + larger documents, and divides the document into chapters.} + + See \l{part}{\\part} for an explanation of the various + section units, command argument and rendering. + + \row + \o \bold \\section1 \target sectionOne + \o \bold {The \\section1 command starts a new section.} + + See \l{part}{\\part} for an explanation of the various + section units, command argument and rendering. + \row + \o \bold \\section2 \target sectionTwo + \o \bold {The \\section2 command starts a new section.} + + See \l{part}{\\part} for an explanation of the various + section units, command argument and rendering. + + \row + \o \bold \\section3 \target sectionThree + \o \bold {The \\section3 command starts a new section.} + + See \l{part}{\\part} for an explanation of the various + section units, command argument and rendering. + + \row + \o \bold \\section4 \target sectionFour + \o \bold {The \\section4 command starts a new section.} + + See \l{part}{\\part} for an explanation of the various + section units, command argument and rendering. + + \endtable +*/ + +/*! + \page 06-qdoc-commands-verbatimcode.html + \previouspage Document Structuring Commands + \contentspage QDoc Manual - Table of Contents + \nextpage Quoting External Code Commands + + \title Verbatim Code Commands + + The following commands are used to render verbatim code within the + documentation. The code is rendered on a new line, using a + typewriter font and the standard indentation. + + \bold{Note:} Although all of these commands can be used to present + C++ code, the \l{07-0-qdoc-commands-quoting.html#snippet}{\\snippet} + and \l{07-0-qdoc-commands-quoting.html#codeline}{\\codeline} commands + should be used in preference to + the others when presenting valid code. This allows auxilliary tools + for Qt language bindings to substitute the relevant code snippets in + place of the C++ ones. + + \section1 Alphabetical List + + \l {06-qdoc-commands-verbatimcode.html#badcode}{\\badcode}, + \l {06-qdoc-commands-verbatimcode.html#code}{\\code}, + \l {06-qdoc-commands-verbatimcode.html#newcode}{\\newcode}, + \l {06-qdoc-commands-verbatimcode.html#oldcode}{\\oldcode} + + \section1 Command Descriptions + + \table + \header + \o Command + \o Description + + \row + \o \bold \\code \target code + \o \bold {The \\code command and the corresponding + \\endcode command delimit a piece of verbatim code.} + + Whereas the \l {c}{\\c} command can be used for short code + fragments within a sentence, the \\code command is for + longer code snippets and renders the code verbatim in a + separate paragraph using a typewriter font and the standard + indentation. + + When processing any of the \\code, \l {badcode}{\\badcode}, + \l {newcode}{\\newcode} and \l {oldcode}{\\oldcode} + commands, QDoc basically removes all indentation that is + common for the verbatim code blocks within a \c{/}\c{*!} ... + \c{*}\c{/} comment before it adds the standard + indentation. For that reason the recommended style is to + use 8 spaces for the verbatim code contained within these + commands (note that this doesn't apply to externally + quoted code using the \l {quotefromfile}{\\quotefromfile} + or \l {quotefile}{\\quotefile} command). + + For example: + + \code + / *! + \code + #include <QApplication> + #include <QPushButton> + + int main(int argc, char *argv[]) + { + ... + } + \ endcode + * / + \endcode + + will be rendered as + + \code + #include <QApplication> + #include <QPushButton> + + int main(int argc, char *argv[]) + { + ... + } + \endcode + + Other QDoc commands are disabled within + \\code... \\endcode, and the special character '\\' is + accepted and rendered like the rest of the code. + + You need to type the code manually between the \\code and + \\endcode commands. If you want to include code snippets + from a particular file, use the \l + {07-0-qdoc-commands-quoting.html#quotefromfile}{\\quotefromfile} + command instead. + + See also \l {c}{\\c}, \l + {07-0-qdoc-commands-quoting.html#quotefromfile}{\\quotefromfile}, + \l {badcode}{\\badcode}, \l {newcode}{\\newcode} and \l + {oldcode}{\\oldcode}. + + \row + \o \bold \\badcode \target badcode + \o \bold {The \\badcode command and the corresponding + \\endcode command delimit a piece of code that doesn't + compile or is wrong for some other reason.} + + The \\badcode command is similar the \l {code}{\\code} + command, but renders the code using a grey font instead of + black (the default). + + Like the \l {code}{\\code} command, it renders its code on + a new line in the documentation using a typewriter font and + the standard indentation. For example: + + \code + / *! + The statement below is rendered using the + regular \\code command: + + \code + statusbar()->message(tr("Host %1 found").arg(hostName)); + \ endcode + + While the following statement is rendered using + the \\badcode command: + + \badcode + statusbar()->message(tr("Host" + hostName + " found")); + \ endcode + * / + \endcode + + will be rendered as + + \quotation + The statement below is rendered using the + regular \\code command: + + \code + statusbar()->message(tr("Host %1 found").arg(hostName)); + \endcode + + While the following statement is rendered using + the \\badcode command: + + \badcode + statusbar()->message(tr("Host" + hostName + " found")); + \endcode + \endquotation + + Other QDoc commands are disabled within + \\badcode... \\endcode, and the special character '\\' is + accepted and rendered like the rest of the code. + + See also \l {code}{\\code}, \l {newcode}{\\newcode} and \l + {oldcode}{\\oldcode}. + + \row + \o \bold \\newcode \target newcode + \o \bold {The \\newcode command, and the associated \\oldcode + and \\endcode commands, indicate how to port a piece of + code to a new version of an API.} + + The \\newcode command, and its companion the \\oldcode + command, is a convenience combination of the \l + {code}{\\code} and \l {badcode}{\\badcode} commands: The + combination provides a text relating the two code snippets + to each other. The command requires a preceding \\oldcode + statement. + + Like the \l {code}{\\code} and \l {badcode}{\\badcode} + commands, the \\newcode command renders its code on a new + line in the documentation using a typewriter font and the + standard indentation. For example: + + \code + / *! + \oldcode + if (printer->setup(parent)) + ... + \newcode + QPrintDialog dialog(printer, parent); + if (dialog.exec()) + ... + \ endcode + * / + \endcode + + is rendered like this: + + \quotation + \oldcode + if (printer->setup(parent)) + ... + \newcode + QPrintDialog dialog(printer, parent); + if (dialog.exec()) + ... + \endcode + \endquotation + + Other QDoc commands are disabled within + \\oldcode ... \\endcode, and the '\\' character doesn't need + to be escaped. + + \row + \o \bold \\oldcode \target oldcode + \o \bold {The \\oldcode command requires a corresponding + \\newcode statement; otherwise QDoc fails to parse the command + and emits a warning.} + + See also \l {newcode}{\\newcode} and \l {badcode}{\\badcode}. + \endtable +*/ + +/*! + \page 07-0-qdoc-commands-quoting.html + \previouspage Verbatim Code Commands + \contentspage QDoc Manual - Table of Contents + \nextpage Linking Commands + + \title Quoting External Code Commands + + The following commands enable quoting from files in the + documentation: You can make QDoc include the complete contents of + a file, or you can quote specific parts of the file and skip + others. The typical use of the latter is to quote a file chunk by + chunk. + + \bold{Note:} Although all of these commands can be used to present + C++ code, the \l{#snippet}{\\snippet} and \l{#codeline}{\\codeline} + commands should be used in preference to + the others when presenting valid code. This allows auxilliary tools + for Qt language bindings to substitute the relevant code snippets in + place of the C++ ones. + + \section1 Alphabetical List + + \l {07-0-qdoc-commands-quoting.html#codeline}{\\codeline}, + \l {07-0-qdoc-commands-quoting.html#dots}{\\dots}, + \l {07-0-qdoc-commands-quoting.html#printline}{\\printline}, + \l {07-0-qdoc-commands-quoting.html#printto}{\\printto}, + \l {07-0-qdoc-commands-quoting.html#printuntil}{\\printuntil}, + \l {07-0-qdoc-commands-quoting.html#quotefile}{\\quotefile}, + \l {07-0-qdoc-commands-quoting.html#quotefromfile}{\\quotefromfile}, + \l {07-0-qdoc-commands-quoting.html#skipline}{\\skipline}, + \l {07-0-qdoc-commands-quoting.html#skipto}{\\skipto}, + \l {07-0-qdoc-commands-quoting.html#skipuntil}{\\skipuntil}, + \l {07-0-qdoc-commands-quoting.html#snippet}{\\snippet} + + \section1 Command Descriptions + + \table + \header + \o Command + \o Description + + \row + \o \bold \\quotefile \target quotefile + \o \bold {The \\quotefile command expands to the complete + contents of the file given as argument.} + + The command considers the rest of the line as part of its + argument, make sure to follow the file name with a line + break. + + The file's contents is rendered in a separate paragraph, + using a typewriter font and the standard indentation. The + code is shown verbatim. + + For example: + + \code + / *! + This is a simple "Hello world" example: + + \quotefile examples/main.cpp + + It contains only the bare minimum you need + to get a Qt application up and running. + * / + \endcode + + will be rendered as + + \quotation + This is a simple "Hello world" example: + + \quotefile examples/main.cpp + + It contains only the bare minimum you need to get a Qt + application up and running. + \endquotation + + \warning If you use the \l {QDoc + Compatibility}{compat.qdocconf} file this command is called + \\include. + + See also \l {quotefromfile}{\\quotefromfile} and \l + {code}{\\code}. + + \row + \o \bold \\quotefromfile \target quotefromfile + \o \bold {The \\quotefromfile command opens the file + given as argument for quoting.} + + The command considers the rest of the line as part of its + argument, make sure to follow the file name with a line + break. + + The command is intended for use when quoting parts from + file with the walkthrough commands: \l + {printline}{\\printline}, \l {printto}{\\printto}, \l + {printuntil}{\\printuntil}, \l {skipline}{\\skipline}, \l + {skipto}{\\skipto}, \l {skipuntil}{\\skipuntil}. This + enables you to quote specific portions of a file. For + example: + + \code + / *! + The whole application is contained within + the \c main() function: + + \quotefromfile examples/main.cpp + + \skipto main + \printuntil app(argc, argv) + + First we create a QApplication object using + the \c argc and \c argv parameters. + + \skipto QPushButton + \printuntil resize + + Then we create a QPushButton, and give it a reasonable + size using the QWidget::resize() function. + + ... + * / + \endcode + + will be rendered as + + \quotation + The whole application is contained within + the \c main() function: + + \quotefromfile examples/main.cpp + + \skipto main + \printuntil app(argc, argv) + + First we create a QApplication object using the \c argc + and \c argv parameters. + + \skipto QPushButton + \printuntil resize + + Then we create a QPushButton, and give it a reasonable + size using the QWidget::resize() function. + + ... + \endquotation + + (\l {Example File}{The complete example file...}) + + QDoc remembers which file it's quoting, and the current + position within that file (see \l {file}{\\printline} for + more information). There is no need to "close" the file. + + Earlier we called this command \\quotefile. For more + information, see the \l + {26-qdoc-commands-compatibility.html#quotefromfile-versus-quotefile} + {compatibility} section. + + See also \l {quotefile}{\\quotefile}, \l {code}{\\code} and + \l {dots}{\\dots}. + + \row + \o \bold \\printline \target printline + \o \bold {The \\printline command expands to the line + from the current position to the next non-blank line of + the current souce file.} + + To ensure that the documentation always is synchronized + with the source file, a substring of the line must be + specified as an argument to the command. Note that the + command considers the rest of the line as part of its + argument, make sure to follow the substring with a line + break. + + The line from the source file is rendered as a separate + paragraph, using a typewriter font and the standard + indentation. The code is shown verbatim. + + For example: + + \code + / *! + There has to be exactly one QApplication object + in every GUI application that uses Qt. + + \quotefromfile examples/main.cpp + + \printline QApplication + + This line includes the QApplication class + definition. QApplication manages various + application-wide resources, such as the + default font and cursor. + + \printline QPushButton + + This line includes the QPushButton class + definition. The QPushButton widget provides a command + button. + + \printline main + + The main function... + * / + \endcode + + will be rendered as + + \quotation + There has to be exactly one QApplication object + in every GUI application that uses Qt. + + \quotefromfile examples/main.cpp + + \printline QApplication + + This line includes the QApplication class + definition. QApplication manages various + application-wide resources, such as the + default font and cursor. + + \printline QPushButton + + This line includes the QPushButton class + definition. The QPushButton widget provides a command + button. + + \printline main + + The main function... + \endquotation + + (\l {Example File}{The complete example file...}) + + \target file + + QDoc reads the file sequentially. To move the current + position forward you can use either of the \l + {skipline}{\\skip...} commands. To move the current + position backward, you can use the \l + {quotefromfile}{\\quotefromfile} command again. + + \target substring + + If the substring argument is surrounded by slashes it is + interpreted as a \l {regular expression}. + + For example: + + \code + / *! + \quotefromfile widgets/scribble/mainwindow.cpp + + \skipto closeEvent + \printuntil /^\}/ + + Close events are sent to widgets that the users want to + close, usually by clicking \c File|Exit or by clicking + the \c X title bar button. By reimplementing the event + handler, we can intercept attempts to close the + application. + * / + \endcode + + will be rendered as + + \quotation + \quotefromfile widgets/scribble/mainwindow.cpp + + \skipto closeEvent + \printuntil /^\}/ + + Close events are sent to widgets that the users want to + close, usually by clicking \c File|Exit or by clicking + the \c X title bar button. By reimplementing the event + handler, we can intercept attempts to close the + application. + \endquotation + + (\l {widgets/scribble}{The complete example file...}) + + The regular expression \c /^\}/ makes QDoc print until the + first '}' character occurring at the beginning of the line + without indentation. /.../ encloses the regular expression, + and '^' means the beginning of the line. The '}' character + must be escaped since it is a special character in regular + expressions. + + QDoc will emit a warning if the specified substring or + regular expression cannot be located, i.e. if the source + code has changed. + + See also \l {printto}{\\printto} and \l + {printuntil}{\\printuntil}. + + \row + \o \bold \\printto \target printto + \o \bold {The \\printto command expands to all the lines + from the current position up to and \i excluding the + next line containing a given substring.} + + The command considers the rest of the line as part of its + argument, make sure to follow the substring with a line + break. The command also follows the same conventions for \l + {file}{positioning} and \l {substring}{argument} as the \l + {printline}{\\printline} command. + + The lines from the source file are rendered in a separate + paragraph, using a typewriter font and the standard + indentation. The code is shown verbatim. + + For example: + + \code + / *! + The whole application is contained within the + \c main() function: + + \quotefromfile examples/main.cpp + \printto hello + + First we create a QApplication object using the \c argc and + \c argv parameters... + * / + \endcode + + will be rendered as + + \quotation + The whole application is contained within the + \c main() function: + + \quotefromfile examples/main.cpp + \skipto main + \printto hello + + First we create a QApplication object using the \c argc + and \c argv parameters... + \endquotation + + (\l {Example File}{The complete example file...}) + + See also \l {printline}{\\printline} and \l + {printuntil}{\\printuntil}. + + \row + \o \bold \\printuntil \target printuntil + \o \bold {The \\printuntil command expands to all the lines + from the current position up to and \i including the next line + containing a given substring.} + + The command considers the rest of the line as part of its + argument, make sure to follow the substring with a line + break. The command also follows the same conventions for \l + {file}{positioning} and \l {substring}{argument} as the \l + {printline}{\\printline} command. + + The lines from the source file are rendered in a separate + paragraph, using a typewriter font and the standard + indentation. The code is shown verbatim. + + For example: + + \code + / *! + The whole application is contained within the + \c main() function: + + \quotefromfile examples/main.cpp + \skipto main + \printuntil hello + + First we create a QApplication object using the + \c argc and \c argv parameters, then we create + a QPushButton. + * / + \endcode + + will be rendered as + + \quotation + The whole application is contained within the + \c main() function: + + \quotefromfile examples/main.cpp + \skipto main + \printuntil hello + + First we create a \l + {http://qt.nokia.com/doc/4.0/qapplication}{QApplication} + object using the \c argc and \c argv parameters, then we + create a \l + {http://qt.nokia.com/doc/4.0/qpushbutton}{QPushButton}. + \endquotation + + (\l {Example File}{The complete example file...}) + + See also \l {printline}{\\printline} and \l + {printto}{\\printto}. + + \row + \o \bold \\skipline \target skipline + \o \bold {The \\skipline command ignores the next non-blank + line in the current source file.} + + Doc reads the file sequentially, and the \\skipline command + is used to move the current position (omitting a line of + the source file). See the remark about \l {file}{file + positioning} above. + + The command considers the rest of the line as part of its + argument, make sure to follow the substring with a line + break. The command also follows the same conventions for \l + {substring}{argument} as the \l {printline}{\\printline} + command, and it is used in conjunction with the \l + {quotefromfile}{\\quotefromfile} command. For example: + + \code + / *! + QPushButton is a GUI push button that the user + can press and release. + + \quotefromfile examples/main.cpp + \skipline QApplication + \printline QPushButton + + This line includes the QPushButton class + definition. For each class that is part of the + public Qt API, there exists a header file of + the same name that contains its definition. + * / + \endcode + + will be rendered as + + \quotation + \l + QPushButton is a GUI push button that the user + can press and release. + + \quotefromfile examples/main.cpp + \skipline QApplication + \printline QPushButton + + This line includes the QPushButton class + definition. For each class that is part of the public + Qt API, there exists a header file of the same name + that contains its definition. + \endquotation + + (\l {Example File}{The complete example file...}) + + See also \l {skipto}{\\skipto}, \l + {skipuntil}{\\skipuntil} and \l {dots}{\\dots}. + + \row + \o \bold \\skipto \target skipto + \o \bold {The \\skipto command ignores all the lines from the + current position up to and \i excluding the next line + containing a given substring.} + + QDoc reads the file sequentially, and the \\skipto command + is used to move the current position (omitting one or + several lines of the source file). See the remark about \l + {file}{file positioning} above. + + The command considers the rest of the line as part of its + argument, make sure to follow the substring with a line + break. + + The command also follows the same conventions for \l + {substring}{argument} as the \l {printline}{\\printline} + command, and it is used in conjunction with the \l + {quotefromfile}{\\quotefromfile} command. For example: + + \code + / *! + The whole application is contained within + the \c main() function: + + \quotefromfile examples/main.cpp + \skipto main + \printuntil } + + First we create a QApplication object. There + has to be exactly one such object in + every GUI application that uses Qt. Then + we create a QPushButton, resize it to a reasonable + size... + * / + \endcode + + will be rendered as + + \quotation + The whole application is contained within + the \c main() function: + + \quotefromfile examples/main.cpp + \skipto main + \printuntil } + + First we create a QApplication object. There has to be + exactly one such object in every GUI application that + uses Qt. Then we create a QPushButton, resize it to a + reasonable size ... + \endquotation + + (\l {Example File}{The complete example file...}) + + See also \l {skipline}{\\skipline}, \l + {skipuntil}{\\skipuntil} and \l {dots}{\\dots}. + + \row + \o \bold \\skipuntil \target skipuntil + \o \bold {The \\skipuntil command ignores all the lines from + the current position up to and \i including the next line + containing a given substring.} + + QDoc reads the file sequentially, and the \\skipuntil + command is used to move the current position (omitting one + or several lines of the source file). See the remark about + \l {file}{file positioning} above. + + The command considers the rest of the line as part of its + argument, make sure to follow the substring with a line + break. + + The command also follows the same conventions for \l + {substring}{argument} as the \l {printline}{\\printline} + command, and it is used in conjunction with the \l + {quotefromfile}{\\quotefromfile} command. For example: + + \code + / *! + The first thing we did in the \c main() function + was to create a QApplication object \c app. + + \quotefromfile examples/main.cpp + \skipuntil show + \dots + \printuntil } + + In the end we must remember to make \c main() pass the + control to Qt. QCoreApplication::exec() will return when + the application exits... + * / + \endcode + + will be rendered as + + \quotation + The first thing we did in the \c main() function was to + create a QApplication object \c app. + + \quotefromfile examples/main.cpp + \skipuntil show + \dots + \printuntil } + + In the end we must remember to make \c main() pass the + control to Qt. QCoreApplication::exec() + will return when the application exits... + \endquotation + + (\l {Example File}{The complete example file...}) + + See also \l {skipline}{\\skipline}, \l {skipto}{\\skipto} + and \l {dots}{\\dots}. + + \row + \o \bold \\dots \target dots + \o \bold {The \\dots command indicates that parts of the + source file have been omitted when quoting a file.} + + The command is used in conjunction with the \l + {quotefromfile}{\\quotefromfile} command, and should be + stated on its own line. The dots are rendered on a new + line, using a typewriter font. For example: + + \code + / *! + \quotefromfile examples/main.cpp + \skipto main + \printuntil { + \dots + \skipuntil exec + \printline } + * / + \endcode + + will be rendered as + + \quotefromfile examples/main.cpp + \skipto main + \printuntil { + \dots + \skipuntil exec + \printline } + + (\l {Example File}{The complete example file...}) + + The default indentation is 4 spaces, but this can be + adjusted using the command's optional argument. For + example: + + \code + / *! + \dots 0 + \dots + \dots 8 + \dots 12 + \dots 16 + * / + \endcode + + will be rendered as + + \dots 0 + \dots + \dots 8 + \dots 12 + \dots 16 + + See also \l {skipline}{\\skipline}, \l + {skipto}{\\skipto} and \l {skipuntil}{\\skipuntil}. + + \row + \o \bold \\snippet \target snippet + \o \bold {The \\snippet command causes a code snippet to be included + verbatim as preformatted text, which may be syntax highlighted.} + + Each code snippet are referenced by the file that holds it and by + a unique identifier for that file. Snippet files are typically + stored in a \c{snippets} directory inside the documentation + directory (e.g., \c{$QTDIR/doc/src/snippets}). + + For example, the following documentation references a snippet in + a file residing in a subdirectory of the documentation directory: + + \code + \snippet snippets/textdocument-resources/main.cpp Adding a resource + \endcode + + The text following the file name is the unique identifier for the + snippet. This is used to delimit the quoted code in the relevant + snippet file as shown in the following example that corresponds to + the above \c{\\snippet} command: + + \dots + \code + QImage image(64, 64, QImage::Format_RGB32); + image.fill(qRgb(255, 160, 128)); + + //! [Adding a resource] + document->addResource(QTextDocument::ImageResource, + QUrl("mydata://image.png"), QVariant(image)); + //! [Adding a resource] + \endcode + \dots + \row + \o \bold \\codeline \target codeline + \o \bold{The \\codeline command inserts a blank line of preformatted + text. It is used to insert gaps between snippets without closing + the current preformatted text area and opening a new one.} + \endtable +*/ + +/*! + \page 07-1-example.html + \previouspage Quoting External Code Commands + \contentspage QDoc Manual - Table of Contents + + \title Example File + + \quotefile examples/main.cpp +*/ + +/*! + \page 08-qdoc-commands-linking.html + \previouspage Quoting External Code Commands + \contentspage QDoc Manual - Table of Contents + \nextpage Graphic Commands + + \title Linking Commands + + The linking commands make it possible to create hyperlinks to + classes, functions, header files and examples. They also make it + possible to link to targets within a document, as well as to other + documents and URLs. + + \section1 Alphabetical List + + \l {08-qdoc-commands-linking.html#keyword}{\\keyword}, + \l {08-qdoc-commands-linking.html#l}{\\l}, + \l {08-qdoc-commands-linking.html#sa}{\\sa}, + \l {08-qdoc-commands-linking.html#target}{\\target} + + \section1 Command Descriptions + + \table + \header + \o Command + \o Description + + \row + \o \bold \\l \target l + \o \bold {The \\l command is used to create hyperlinks. } + + The command's general syntax is + + \code + \l {link target}{link text} + \endcode + + For example: + + \code + / *! + Read the \l {http://qt.nokia.com/doc/4.0/} + {Qt's Reference Documentation} carefully. + * / + \endcode + + will be rendered as + + \quotation + Read the \l {http://qt.nokia.com/doc/4.0/} + {Qt's Reference Documentation} carefully. + \endquotation + + If the link target is equivalent to the link text, the + second argument can be omitted. + + For example, if you have documentation like: + + \code + / *! + \target assertions + + Assertions make some statement about the text at the + point where they occur in the regexp but they do not + match any characters. + + ... + + Regexps are built up from expressions, quantifiers, and + \l {assertions}{assertions}. + * / + \endcode + + you can rewrite it as + + \code + / *! + \target assertions + + Assertions make some statement about the text at the + point where they occur in the regexp but they do not + match any characters. + + ... + + Regexps are built up from expressions, quantifiers, and + \l assertions. + * / + \endcode + + For the one-parameter version the braces can often + be omitted. See the \l {i}{\\i} command for the \l + {argument}{argument conventions}. + + The \\l command supports several kinds of links: + + \list + \o \c {\l QWidget} - a defined \l {class}{\\class} + \o \c {\l QWidget::sizeHint()} - a defined member + function (\l {fn}{\\fn}) + \o \c {\l <QtGlobal>} - a defined \l {headerfile}{\\headerfile} + \o \c {\l widgets/wiggly} - a defined + \l {example-command}{\\example} + \o \c {\l {QWidget Class Reference}} - a defined \l {title}{\\title} + \o \c {\l {Introduction}}- a defined \l{part}{\\part}, + \l{chapter}{\\chapter} or \l {sectionOne}{\\section...} + \o \c {\l fontmatching} - a defined \l {target}{\\target} + \o \c {\l {Shared Classes}} - a defined \l {keyword}{\\keyword} + \o \c {\l network.html} - a defined \l {page}{\\page} + \o \c {\l http://www.trolltech.com/} - a URL + \endlist + + QDoc also tries to make a link out of any words that don't + resemble any normal English words, for example Qt class + names or functions, like QWidget or QWidget::sizeHint(). In + these cases, the \\l command can actually be omitted, but + by using the command, you ensure that QDoc will emit a + warning if it cannot find the link target. In addition, if + you only want the function name to appear in the link, you + can use the following syntax: + + \list + \o \c {\l {QWidget::}{sizeHint()}} + \endlist + + See also \l {sa}{\\sa}, \l {target}{\\target} and \l + {keyword}{\\keyword}. + + \row + \o \bold \\sa \target sa + \o \bold {The \\sa command defines a list of links that will + be rendered in a separate "See also" section at the bottom + of the documentation.} + + The command takes a comma-separated list of links as its + argument. If the line ends with a comma, you can continue + on a second line. The general syntax is: + + \code + \sa {the first link}, {the second link}, + {the third link}, ... + \endcode + + QDoc will automatically try to generate "See also" links + interconnecting a property's various functions. For + example, an setVisible() function will automatically get a + link to visible() and vice versa. + + In general, QDoc will generate "See also" links that + interconnect the functions that access the same + property. It recognizes four different syntax versions: + + \list + \o \c property() + \o \c setProperty() + \o \c isProperty() + \o \c hasProperty() + \endlist + + The \\sa command supports the same kind + of links as the \l {l}{\\l} command. For example: + + \code + / *! + Appends the actions \a actions to this widget's + list of actions. + + \sa removeAction(), QMenu, addAction() + * / + void QWidget::addActions(QList<QAction *> actions) + { + ... + } + \endcode + + will be rendered as + + \quotation + \bold {void QWidget::addActions ( QList<QAction*> + \i actions )} + + Appends the actions \i actions to this widget's + list of actions. + + See also \l {QWidget::removeAction()}{removeAction()}, + \l QMenu, and \l {QWidget::addAction()}{addAction()}. + \endquotation + + See also \l {l}{\\l}, \l {target}{\\target} and \l + {keyword}{\\keyword}. + + \row + \o \bold \\target \target target + \o \bold {The \\target command defines an explicit point in the + documentation that you can later link to using the \l {l}{\\l} + and \l {sa}{\\sa} commands.} + + The command considers the rest of the line as part of its + argument, make sure to follow the target name with a line + break. + + For example: + + \code + / *! + \target capturing parentheses + \section1 Capturing Text + + Parentheses allow us to group elements together so that + we can quantify and capture them. + + ... + * / + \endcode + + can be referenced with + + \list + \o \c {\l {capturing parentheses}} + (from elsewhere in the same comment) + \o \c {\l qregexp.html#capturing-parentheses} + (from anywhere else) + \endlist + + within a documentation unit, and with + + \list + \o \c {\l http://www.trolltech.com/4.0/doc/html/qregexp.html#capturing-parentheses} + \endlist + + on a more global scale. + + If the target name does't contain any spaces, the brackets can + be omitted as well. + + See also \l {l}{\\l}, \l {sa}{\\sa} and \l + {keyword}{\\keyword}. + + \row + \o \bold \\keyword \target keyword + \o \bold {The \\keyword command defines an explicit point in the + documentation that you can later link to using the \l {l}{\\l} + and \l {sa}{\\sa} commands.} + + Keywords must be unique within the entire set of + documentation processed in on QDoc run. The command + considers the rest of the line as part of its argument, + make sure to follow the keyword with a line break. + + The \\keyword command is similar to \l {target}{\\target}, + but stronger. A keyword can be referenced from anywhere + using a simple syntax. For example: + + \code + / *! + \class QRegExp + \reentrant + \brief The QRegExp class provides pattern + matching using regular expressions. + \ingroup tools + \ingroup misc + \ingroup shared + \mainclass + + \keyword regular expression + + Regular expressions, or "regexps", provide a way to + find patterns within text. + + ... + * / + \endcode + + can be referenced like this + + \code + / *! + When a string is surrounded by slashes, it's + interpreted as a \l regular expression. + * / + \endcode + + which will be rendered as + + \quotation + When a string is surrounded by slashes, it's + interpreted as a \l {regular expression}. + \endquotation + + If the keyword does't contain any spaces, the brackets can + be omitted as well. + + See also \l {l}{\\l}, \l {sa}{\\sa} and \l + {target}{\\target}. + \endtable +*/ + +/*! + \page 09-qdoc-commands-graphic.html + \previouspage Linking Commands + \contentspage QDoc Manual - Table of Contents + \nextpage Container Commands + + \title Graphic Commands + + The graphic commands makes it possible to include images in the + documentation. The images can be rendered as separate paragraphs, + or within running text. + + \section1 Alphabetical List + + \l {09-qdoc-commands-graphic.html#caption}{\\caption}, + \l {09-qdoc-commands-graphic.html#image}{\\image}, + \l {09-qdoc-commands-graphic.html#inlineimage}{\\inlineimage} + + \section1 Command Descriptions + + \table + \header + \o Command + \o Description + + \row + \o \bold \\image \target image + \o \bold {The \\image command expands to the image specified by its + argument, and renders it centered as a separate paragraph.} + + The \\image command replaces the old \\img command. For more + information, see the \l + {26-qdoc-commands-compatibility.html#image-versus-img} + {compatibility} section. + + The command takes two arguments. The first is the name of + the image file. The second argument is optional and is a + simple description of the image equivalent to the HTML + alt="" in an image tag. The description is used for + tooltips, and when a browser doesn't support images like + the Lynx text browser. + + The command considers the rest of the line after the file + name its second argument, make sure that you follow the + filename or description with a line break. Braces are only + necessary if the description spans several lines. + + For example: + + \code + / *! + Qt by Trolltech is a C++ toolkit for cross-platform GUI + application development. + + \image happyguy.jpg "Happy guy" + + Qt provides single-source portability across Microsoft + Windows, Mac OS X, Linux, and all major commercial Unix + variants. It is also available for embedded devices. + * / + \endcode + + will be rendered as + + \quotation + Qt by Trolltech is a C++ toolkit for cross-platform GUI + application development. + + \image happyguy.jpg image "Happy guy" + + Qt provides single-source portability across Microsoft + Windows, Mac OS X, Linux, and all major commercial Unix + variants. It is also available for embedded devices. + \endquotation + + See also \l {inlineimage}{\\inlineimage} and \l + {caption}{\\caption}. + + \row + \o \bold \\inlineimage \target inlineimage + \o \bold {The \\inlineimage command expands to the image + specified by its argument; the image is rendered inline + with the rest of the text.} + + The command takes two arguments. The first is the name of + the image file. The second argument is optional and is a + simple description of the image equivalent to the HTML + alt="" in an image tag. The description is used for + tooltips, and when a browser doesn't support images like + the Lynx text browser. + + The most common use of the \\inlineimage command is in + lists and tables. For example: + + \code + / *! + \list 1 + \o \inlineimage happy.gif Oh so happy! + \o \inlineimage happy.gif Oh so happy! + \o \inlineimage happy.gif Oh so happy! + \endlist + * / + \endcode + + will be rendered as + + \list 1 + \o \inlineimage happy.gif Oh so happy! + \o \inlineimage happy.gif Oh so happy! + \o \inlineimage happy.gif Oh so happy! + \endlist + + And + + \code + / *! + \table + \header + \o Trolltech + \o Trolltech + \row + \o \inlineimage happy.gif Oh so happy! + \o \inlineimage happy.gif Oh so happy! + \row + \o \inlineimage happy.gif Oh so happy! + \o \inlineimage happy.gif Oh so happy! + \endtable + * / + \endcode + + will be rendered as + + \raw HTML + <table align="center" cellpadding="2" + cellspacing="1" border="0"> + <tr valign="top" bgcolor="#a2c511"> + <th>Trolltech</th> + <th>Trolltech</th> + </tr> + + <tr valign="top" bgcolor="#f0f0f0"> + <td><img src="images/happy.gif" alt="Oh so happy!" /> + </td> + <td><img src="images/happy.gif" alt="Oh so happy!" /> + </td> + </tr> + + <tr valign="top" bgcolor="#f0f0f0"> + <td><img src="images/happy.gif" alt="Oh so happy!"/> + </td> + <td><img src="images/happy.gif" alt="Oh so happy!" /> + </td> + </tr> + + </table> + \endraw + + The command can also be used to insert an image + inline with the regular text. For example: + + \code + / *! + \inlineimage training.jpg Training by Trolltech + The Qt Programming course is offered as a + five day Open Enrollment Course. The classes + are open to the public.While the course is open + to anyone who wants to learn, attendees should + have significant experience in C++ development + to derive maximum benefit from the course. + * / + \endcode + + will be rendered as + + \quotation + \inlineimage training.jpg Training by Trolltech + The Qt Programming course is offered as a + five day Open Enrollment Course. The classes + are open to the public.While the course is open + to anyone who wants to learn, attendees should + have significant experience in C++ development + to derive maximum benefit from the course. + \endquotation + + See also \l {image}{\\image} and \l {caption}{\\caption}. + + \row + \o \bold \\caption \target caption + \o \bold {The \\caption command provides a caption for an image.} + + The command follows the same conventions for parentheses and use + of braces for its \l argument as the \l {i}{\\i} command. + + \warning This is preliminary functionality. The + command is not fully implemented. + + See also \l {image}{\\image} and \l + {inlineimage}{\\inlineimage} + + \endtable +*/ + +/*! + \page 10-qdoc-commands-container.html + \previouspage Graphic Commands + \contentspage QDoc Manual - Table of Contents + \nextpage Document Contents Commands + + \title Container Commands + + The container commands create tables and lists with associated + items and contents. A list is rendered left aligned as a separate + paragraph. A table is rendered centered as a separate paragraph, + and its width depends on its content. + + \section1 Alphabetical List + + \l {10-qdoc-commands-container.html#header}{\\header}, + \l {10-qdoc-commands-container.html#list}{\\list}, + \l {10-qdoc-commands-container.html#o}{\\o}, + \l {10-qdoc-commands-container.html#omitvalue}{\\omitvalue}, + \l {10-qdoc-commands-container.html#row}{\\row}, + \l {10-qdoc-commands-container.html#table}{\\table}, + \l {10-qdoc-commands-container.html#value}{\\value} + + \section1 Command Descriptions + + \table + \header + \o Command + \o Description + + \row + \o \bold \\table \target table + \o \bold {The \\table command and the corresponding \\endtable + command delimit the contents of a table.} + + The command accepts a single argument specifying the + table's width in percentage: + + \code + / *! + \table 100 % + + ... + + \endtable + * / + \endcode + + The code above ensures that the table will fill all + available space. If the table's width is smaller than 100 %, + the table will be centered in the generated documentation. + + A table can contain headers, rows and columns. A row starts + with a \l {row}{\\row} command and consists of cells, which + starts with a \l {o}{\\o} command. There is also a \l + {header}{\\header} command which is a special kind of row + with a special formatting. For example: + + \code + / *! + \table + \header + \o Qt Core Feature + \o Brief Description + \row + \o \l {Signal and Slots} + \o Signals and slots are used for communication + between objects. + \row + \o \l {Layout Management} + \o The Qt layout system provides a simple + and powerful way of specifying the layout + of child widgets. + \row + \o \l {Drag and Drop} + \o Drag and drop provides a simple visual + mechanism which users can use to transfer + information between and within applications. + \endtable + * / + \endcode + + will be rendered as + + \raw HTML + <table align="center" cellpadding="2" + cellspacing="1" border="0"> + <tr valign="top" bgcolor="#a2c511"> + <th>Qt Core Feature</th> + <th>Brief Description</th> + </tr> + + <tr valign="top" bgcolor="#d0d0d0"> + <td> + <a href="http://qt.nokia.com/doc/4.0/signalsandslots.html"> + Signals and Slots</a> + </td> + <td>Signals and slots are used for communication + between objects.</td> + </tr> + + <tr valign="top" bgcolor="#c0c0c0"> + <td> + <a href=http://qt.nokia.com/doc/4.0/layout.html"> + Layout Management</a></td> + <td>The Qt layout system provides a simple + and powerful way of specifying the layout + of child widgets.</td> + </tr> + + <tr valign="top" bgcolor="#d0d0d0"> + <td> + <a href=http://qt.nokia.com/doc/4.0/dnd.html"> + Drag and Drop</a></td> + <td>Drag and drop provides a simple visual + mechanism which users can use to transfer + information between and within applications.</td> + </tr> + + </table> + \endraw + + You can also make cells span several rows and columns. For + example: + + \code + / *! + \table + \header + \o {3,1} This header cell spans three columns + but only one row. + \row + \o {2, 1} This table cell spans two columns + but only one row + \o {1, 2} This table cell spans only one column, + but two rows. + \row + \o A regular table cell + \o A regular table cell + \endtable + * / + \endcode + + will be rendered as + + \raw HTML + <table align="center" cellpadding="2" cellspacing="1" + border="0"> + + <tr valign="top" bgcolor="#a2c511"> + <th colspan="3" rowspan=" 1"> + This header cell spans three columns but only one row + </th> + </tr> + + <tr valign="top" bgcolor="#d0d0d0"> + <td colspan="2" rowspan=" 1"> + This table cell spans two columns but only one row + </td> + <td rowspan=" 2"> + This table cell spans only one column, but two rows. + </td> + </tr> + + <tr valign="top" bgcolor="#c0c0c0"> + <td>A regular table cell</td> + <td>A regular table cell</td> + </tr> + + </table> + \endraw + + See also \l {header}{\\header}, \l {row}{\\row} and \l {o}{\\o}. + + \row + \o \bold \\header \target header + \o \bold {The \\header command indicates that the following + table cells are the current table's column headers.} + + The command can only be used within the \l{table} + {\\table...\\endtable} commands. A header can contain + several cells. A cell is created with the \l {o}{\\o} + command. + + A header cell's text is centered within the table cell and + rendered using a bold font. For example: + + \code + / *! + \table + \header + \o Qt Core Feature + \o Brief Description + \row + \o \l {Signal and Slots} + \o Signals and slots are used for communication + between objects. + \endtable + * / + \endcode + + will be rendered as + + \raw HTML + <table align="center" cellpadding="2" + cellspacing="1" border="0"> + <tr valign="top" bgcolor="#a2c511"> + <th>Qt Core Feature</th> + <th>Brief Description</th> + </tr> + + <tr valign="top" bgcolor="#d0d0d0"> + <td> + <a href="http://qt.nokia.com/doc/4.0/signalsandslots.html"> + Signals and Slots</a> + </td> + <td>Signals and slots are used for communication + between objects.</td> + </tr> + </table> + \endraw + + See also \l {table}{\\table}, \l {row}{\\row} and \l {o}{\\o}. + + \row + \o \bold \\row \target row + \o \bold {The \\row command indicates that the following table + cells belong to the same row in the current table.} + + The command can only be used within the \l{table} + {\\table...\\endtable} commands. A row can contain + several cells. A cell is created with the \l {o}{\\o} + command. + + The background cell color of each row alternate between two + shades of grey, making it easier to distinguish the rows + from each other. The cells' contents is left aligned. + + For example: + + \code + / *! + \table + \header + \o Qt Core Feature + \o Brief Description + \row + \o \l {Signal and Slots} + \o Signals and slots are used for communication + between objects. + \row + \o \l {Layout Management} + \o The Qt layout system provides a simple + and powerful way of specifying the layout + of child widgets. + \row + \o \l {Drag and Drop} + \o Drag and drop provides a simple visual + mechanism which users can use to transfer + information between and within applications. + \endtable + * / + \endcode + + will be rendered as + + \raw HTML + <table align="center" cellpadding="2" + cellspacing="1" border="0"> + <tr valign="top" bgcolor="#a2c511"> + <th>Qt Core Feature</th> + <th>Brief Description</th> + </tr> + + <tr valign="top" bgcolor="#d0d0d0"> + <td> + <a href="http://qt.nokia.com/doc/4.0/signalsandslots.html"> + Signals and Slots</a> + </td> + <td>Signals and slots are used for communication + between objects.</td> + </tr> + + <tr valign="top" bgcolor="#c0c0c0"> + <td> + <a href=http://qt.nokia.com/doc/4.0/layout.html"> + Layout Management</a></td> + <td>The Qt layout system provides a simple + and powerful way of specifying the layout + of child widgets.</td> + </tr> + + <tr valign="top" bgcolor="#d0d0d0"> + <td> + <a href=http://qt.nokia.com/doc/4.0/dnd.html"> + Drag and Drop</a></td> + <td>Drag and drop provides a simple visual + mechanism which users can use to transfer + information between and within applications.</td> + </tr> + + </table> + \endraw + + See also \l {table}{\\table}, \l {header}{\\header} and \l + {o}{\\o}. + + \row + \o \bold \\value \target value + \o \bold {The \\value command starts the documentation of a C++ enum + item}. + + The command's first argument is the enum item. Then follows + its associated description. The description argument ends + at the next blank line or \\value. The arguments are + rendered within a table. + + The documentation will be located in the associated class, + header file or namespace documentation. See the \l + {enum}{\\enum} documentation for an example. + + See also \l {enum}{\\enum} and \l {omitvalue}{\\omitvalue}. + + \row + \o \bold \\omitvalue \target omitvalue + \o \bold {The \\omitvalue command excludes a C++ enum item + from the documentation}. + + The command's only argument is the name of the enum item + that will be omitted. See the \l {enum}{\\enum} + documentation for an example. + + See also \l {enum}{\\enum} and \l {value}{\\value}. + + \row + \o \bold \\list \target list + \o \bold {The \\list command and the corresponding \\endlist + command delimit a list of items.} + + You need to create each list item explicitly using the \l + {o}{\\o} command. A list can contain one or more items; it + can also be nested. For example: + + \code + / *! + \list + \o Qt Reference Documentation: Getting Started + \list + \o How to Learn Qt + \o Installation + \list + \o Qt/X11 + \o Qt/Windows + \o Qt/Mac + \o Qt/Embedded + \endlist + \o Tutorial and Examples + \endlist + \endlist + * / + \endcode + + will be rendered as + + \list + \o Qt Reference Documentation: Getting Started + \list + \o How to Learn Qt + \o Installation + \list + \o Qt/X11 + \o Qt/Windows + \o Qt/Mac + \o Qt/Embedded + \endlist + \o Tutorial and Examples + \endlist + \endlist + + The \\list command takes an optional argument providing + alternative appearances for the list items. For example: + + \code + / *! + \list + \o How to Learn Qt + \o Installation + \o Tutorial and Examples + \endlist + * / + \endcode + + will render the list items with bullets (the default): + + \list + \o How to Learn Qt + \o Installation + \o Tutorial and Examples + \endlist + + If you provide 'A' as an argument to the \\list command, + the bullets are replaced with characters following in + alphabetical order: + + \list A + \o How to Learn Qt + \o Installation + \o Tutorial and Examples + \endlist + + If you replace 'A' with '1', the list items are rendered + with numbers following in ascending order: + + \list 1 + \o How to Learn Qt + \o Installation + \o Tutorial and Examples + + \endlist + + If you provide 'i' as the argument, the default bullets are + replaced with roman numerals: + + \list i + \o How to Learn Qt + \o Installation + \o Tutorial and Examples + \endlist + + Or finally, you can make the list items appear with roman + numbers following in ascending order if you provide 'I' as + the optional argument: + + \list I + \o How to Learn Qt + \o Installation + \o Tutorial and Examples + \endlist + + You can also make the listing start at any character or + number by simply provide the number or character you want + to start at. For example: + + \code + / *! + \list G + \o How to Learn Qt + \o Installation + \o Tutorial and Examples + \endlist + * / + \endcode + + will be rendered as + + \list G + \o How to Learn Qt + \o Installation + \o Tutorial and Examples + \endlist + + See also \l {o}{\\o}. + + \row + \o \bold \\o \target o + \o \bold {The \\o command announce a table or list item.} + + Earlier we used the \l {i}{\\i} command for this purpose. For more + information see the \l + {26-qdoc-commands-compatibility.html#o-versus-i}{compatibility} + section. + + The command can only be used within the \l{table} + {\\table...\\endtable} or \l{list}{\\list... \\endlist} + commands. + + It considers everything until the next occurrence + of the \\o command, or the currently applicable \l + {table}{\\endtable} or \l {list}{\\endlist} command, as its + argument. For examples, see \l {table}{\\table} and \l + {list}{\\list}. + + If the command is used within a table, you can in addition + specify how many rows or columns the item should span. For + example: + + \code + / *! + \table + \header + \o {3,1} This header cell spans three columns + but only one row. + \row + \o {2, 1} This table item spans two columns + but only one row + \o {1, 2} This table item spans only one column, + but two rows. + \row + \o A regular table item + \o A regular table item + \endtable + * / + \endcode + + will be rendered as + + \raw HTML + <table align="center" cellpadding="2" cellspacing="1" + border="0"> + + <tr valign="top" bgcolor="#a2c511"> + <th colspan="3" rowspan=" 1"> + This header cell spans three columns but only one row + </th> + </tr> + + <tr valign="top" bgcolor="#d0d0d0"> + <td colspan="2" rowspan=" 1"> + This table item spans two columns but only one row + </td> + <td rowspan=" 2"> + This table item spans only one column, but two rows. + </td> + </tr> + + <tr valign="top" bgcolor="#c0c0c0"> + <td>A regular table item</td> + <td>A regular table item</td> + </tr> + + </table> + \endraw + + If not specified, the item will span one column and one row. + + See also \l {table}{\\table}, \l {header}{\\header}, + \l {list}{\\list} and \l {o}{\\o}. + \endtable +*/ + +/*! + \page 11-qdoc-commands-documentcontents.html + \previouspage Container Commands + \contentspage QDoc Manual - Table of Contents + \nextpage Miscellaneous Commands + + \title Document Contents Commands + + The document contents commands identify parts of the documentation, + i.e. parts with a special rendering, conceptual meaning or + function. + + \section1 Alphabetical List + + \l {11-qdoc-commands-documentcontents.html#abstract}{\\abstract}, + \l {11-qdoc-commands-documentcontents.html#brief}{\\brief}, + \l {11-qdoc-commands-documentcontents.html#footnote}{\\footnote}, + \l {11-qdoc-commands-documentcontents.html#legalese}{\\legalese}, + \l {11-qdoc-commands-documentcontents.html#tableofcontents} + {\\tableofcontents}, + \l {11-qdoc-commands-documentcontents.html#quotation}{\\quotation}, + \l {11-qdoc-commands-documentcontents.html#warning}{\\warning} + + \section1 Command Descriptions + + \table + \header + \o Command + \o Description + + \row + \o \bold \\abstract \target abstract + \o \bold {The \\abstract command and the corresponding \\endabstract + command delimit a document's abstract section.} + + The abstract section is rendered as an indented italicized + paragraph. + + \warning This is preliminary funcionality. The + command is not fully implemented. Currently, the abstract + section is rendered as a regular HTML paragraph. For + example: + + \code + / *! + \abstract + Qt by Trolltech is a C++ toolkit for cross-platform + GUI application development. Qt provides + single-source portability across Microsoft Windows, + Mac OS X, Linux, and all major commercial Unix + variants. It is also available for embedded + devices. + \endabstract + * / + \endcode + + will be rendered as + + \abstract + Qt by Trolltech is a C++ toolkit for cross-platform GUI + application development. Qt provides single-source + portability across Microsoft Windows, Mac OS X, Linux, + and all major commercial Unix variants. It is also + available for embedded devices. + \endabstract + + \row + \o \bold \\quotation \target quotation + \o \bold { The \\quotation command and the corresponding + \\endquotation command delimit a quotation remark.} + + This command replaces the old \\quote command. For more + information see the \l + {26-qdoc-commands-compatibility.html#quotation-versus-quote} + {compatibility} section. + + The remark is rendered as a separate centered + paragraph. For example: + + \code + / *! + While the prospect of a significantly broader market is + good news for Firstlogic, the notion also posed some + challenges. Dave Dobson, director of technology for the La + Crosse, Wisconsin-based company, said: + + + \quotation + As our solutions were being adopted into new + environments, we saw an escalating need for easier + integration with a wider range of enterprise + applications. + \endquotation + * / + \endcode + + will be rendered as + + While the prospect of a significantly broader market is + good news for Firstlogic, the notion also posed some + challenges. Dave Dobson, director of technology for the La + Crosse, Wisconsin-based company, said: + + \quotation + As our solutions were being adopted into new + environments, we saw an escalating need for easier + integration with a wider range of enterprise + applications. + \endquotation + + \row + \o \bold \\footnote \target footnote + \o \bold {The \\footnote command and the corresponding + \\endfootnote command delimit a footnote.} + + The footnote follows the standard conventions, rendered at the + bottom of the page. + + \warning This is preliminary funcionality. The + command is not fully implemented. + + For example: + + \code + / *! + In Qt 4 we have tried to simplify the constructors of + QObject/QWidget subclasses. This makes subclassing + easier, at the same time as it helps make the Qt + library more efficient. + + \footnote + Constructors no longer take a "const char *name" + parameter. If you want to specify a name for a QObject, + you must call QObject::setObjectName() after + construction. The object name is now a QString. + \endfootnote + + QWidget's WFlags data type has been split in two: + Qt::WindowFlags specifies low-level window flags (the + type of window and the frame style), whereas + Qt::WidgetAttribute specifies various higher-level + attributes about the widget (e.g., + WA_StaticContents). + * / + \endcode + + will be rendered as + + \quotation + In Qt 4 we have tried to simplify the constructors of + QObject/QWidget subclasses. This makes subclassing + easier, at the same time as it helps make the Qt + library more efficient. + + \footnote + Constructors no longer take a "const char *name" + parameter. If you want to specify a name for a QObject, + you must call QObject::setObjectName() after + construction. The object name is now a QString. + \endfootnote + + QWidget's WFlags data type has been split in two: + Qt::WindowFlags specifies low-level window flags (the + type of window and the frame style), whereas + Qt::WidgetAttribute specifies various higher-level + attributes about the widget (e.g., + WA_StaticContents). + \endquotation + + \row + \o \bold \\tableofcontents \target tableofcontents + \o \bold {The \\tableofcontents command generates a + table displaying the titles of the current documentation + unit's parts, chapters, sections, etc.} + + The command accepts a single optional argument: + + \code + \tableofcontents sectionN + \endcode + + where \c sectionN is the deepest section to include (by + default all sections are included). + + For example, it the documentation unit's structure looks + something like this: + + \quotation + \raw HTML + <a name="Basic Qt"> + <h1>Basic Qt</h1> + </a> + <p>This is the first part.</p> + + <a name="Getting started"> + <h2>Getting Started</h2> + </a> + This is the first part's first chapter.</p> + + <a name="Hello Qt"> + <h3>Hello Qt</h3> + </a> + <p>This is the first chapter's first section.</p> + + <a name="Making Connections"> + <h3>Making Connections</h3> + </a> + <p>This is the first chapter's second section.</p> + + <a name="Using the Reference Documentation"> + <h3>Using the Reference Documentation</h3> + </a> + <p>This is the first chapter's third section.</p> + + <a name="Creating Dialogs"> + <h2>Creating Dialogs</h2> + </a> + <p>This is the first part's second chapter.</p> + + <a name="Subclassing QDialog"> + <h3>Subclassing QDialog</h3> + </a> + <p>This is the second chapter's first section.</p> + + ... + + <a name="Intermediate Qt"> + <h1>Intermediate Qt</h1> + </a> + <p>This is the second part.</p> + + <a name="Layout Management"> + <h2>Layout Management</h2> + </a> + <p>This is the second part's first chapter.</p> + + <a name="Basic Layouts"> + <h3>Basic Layouts</h3> + </a> + <p>This is the first chapter's first section.</p> + + ... + + \endraw + \endquotation + + Then + + \code + / *! + Contents: + + \tableofcontents + + ... + * / + \endcode + + will expand to + + \quotation + \raw HTML + <p>Contents:</p> + + <ul> + <li><a href="#Basic Qt">Basic Qt</a></li> + <ul> + <li><a href="#Getting Started">Getting Started</a></li> + <ul> + <li><a href="#Hello Qt">Hello Qt</a></li> + <li><a href="#Making Connections"> + Making Connections</a></li> + <li><a href="#Using the Reference Documentation"> + Using the Reference Documentation</a></li> + </ul> + <li><a href="#Creating Dialogs">Creating Dialogs</a></li> + <ul> + <li><a href="#Subclassing QDialog"> + Subclassing QDialog</a></li> + </ul> + </ul> + <li><a href="#Intermediate Qt">Intermediate Qt</a></li> + <ul> + <li><a href="#Layout Management">Layout Management</a></li> + <ul> + <li><a href="#Basic Layouts">Basic Layouts</a></li> + </ul> + </ul> + </ul> + + ... + \endraw + \endquotation + + Each table entry becomes a link to the corresponding part, + chapter or section. + + \row + \o \bold \\brief \target brief + \o \bold {The \\brief command introduces a one-sentence + description of a class, namespace, header file, property + or variable.} + + The brief text is used to introduce the documentation of + the associated object, and in lists generated using the \l + {generatelist}{\\generatelist} command. + + The \\brief command can be used in two significant + different ways: \l {brief class}{One for classes, + namespaces and header files}, and \l {brief property}{one + for properties and variables}. + + \target brief property + + When the \\brief command is used to describe a property or + a variable, the brief text must only be a sentence fragment + and start with "whether" (for boolean properties and + variables) or "the" (for any other property or variable). + + For example the boolean QWidget::isWindow property: + + \code + / *! + \property QWidget::isActiveWindow + \brief whether this widget's window is the active window + + The active window is the window that contains the widget that + has keyboard focus. + + When popup windows are visible, this property is true + for both the active window \e and for the popup. + + \sa activateWindow(), QApplication::activeWindow() + * / + \endcode + + and the QWidget::geometry property + + \code + / *! + \property QWidget::geometry + \brief the geometry of the widget relative to its parent and + excluding the window frame + + When changing the geometry, the widget, if visible, + receives a move event (moveEvent()) and/or a resize + event (resizeEvent()) immediately. + + ... + + \sa frameGeometry(), rect(), ... + * / + \endcode + + The latter will be rendered as + + \quotation + \raw HTML + <h3>geometry : + <a href="http://qt.nokia.com/doc/4.0/qrect.html">QRect</a> + </h3> + \endraw + + This property holds the geometry of the widget relative + to its parent and excluding the window frame. + + ... + + Access functions: + \list + \o \bold {const QRect & geometry () const} + \o \bold {void setGeometry ( int x, int y, int w, int h )} + \o \bold {void setGeometry ( const QRect & )} + \endlist + + See also \l + {QWidget::frameGeometry()}{frameGeometry()}, \l + {QWidget::rect()}{rect()}, ... + \endquotation + + \target brief class + + When the \\brief command is used to describe a class, the + brief text should be a complete sentence and must start + like this: + + \code + The <classname> class is|provides|contains|specifies... + \endcode + + and likewise when the command is used for namespaces or + header files. + + \warning The brief statement is used as the first + paragraph of the detailed description. Do not repeat the + sentence. + + For example: + + \code + / *! + \class PreviewWindow + \brief The PreviewWindow class is a custom widget + displaying the names of its currently set + window flags in a read-only text editor. + + The PreviewWindow class inherits QWidget. The widget + displays the names of its window flags set with the + setWindowFlags() function. It is also provided with a + QPushButton that closes the window. + + ... + + \sa QWidget + * / + \endcode + + will be rendered as + + \quotation + \raw HTML + <h1>PreviewWindow Class Reference</h1> + \endraw + + The PreviewWindow class is a custom widget displaying + the names of its currently set window flags in a + read-only text editor. \l {preview window}{More...} + + \raw HTML + <h3>Properties</h3> + \endraw + + \list + \o 52 properties inherited from QWidget + \o 1 property inherited from QObject + \endlist + + \raw HTML + <h3>Public Functions</h3> + \endraw + + \list + \o \l {constructor}{PreviewWindow}(QWidget *parent = 0) + \o void \l {function}{setWindowFlags}(Qt::WindowFlags flags) + \endlist + + \list + \o 183 public functions inherited from QWidget + \o 28 public functions inherited from QObject + \endlist + + \raw HTML + <h3>Public Slots</h3> + \endraw + + \list + \o 17 public slots inherited from QWidget + \o 1 public slot inherited from QObject + \endlist + + \raw HTML + <h3>Additional Inherited Members</h3> + \endraw + + \list + \o 1 signal inherited from QWidget + \o 1 signal inherited from QObject + \o 4 static public members inherited from QWidget + \o 4 static public members inherited from QObject + \o 39 protected functions inherited from QWidget + \o 7 protected functions inherited from QObject + \endlist + + \target preview window + + \raw HTML + <hr /> + <h2>Detailed Description</h2> + \endraw + The PreviewWindow class is a custom widget displaying + the names of its currently set window flags in a + read-only text editor. + + The PreviewWindow class inherits QWidget. The widget + displays the names of its window flags set with the \l + {function}{setWindowFlags()} function. It is also + provided with a QPushButton that closes the window. + + ... + + See also QWidget. + + \raw HTML + <hr /> + <h2>Member Function Documentation</h2> + \endraw + + \target constructor + \raw HTML + <h3>PreviewWindow(QWidget *parent = 0)</h3> + \endraw + + Constructs a preview window widget with \i parent. + + \target function + \raw HTML + <h3>setWindowFlags(Qt::WindowFlags flags)</h3> + \endraw + + Sets the widgets flags using the + QWidget::setWindowFlags() function. + + Then runs through the available window flags, + creating a text that contains the names of the flags + that matches the flags parameter, displaying + the text in the widgets text editor. + \endquotation + + Using \\brief with a namespace can for example look like this: + + \code + / *! + \namespace Qt + + \brief The Qt namespace contains miscellaneous identifiers + used throughout the Qt library. + * / + \endcode + + and finally using \\brief with a header file can look + something like this: + + \code + / *! + \headerfile <QtGlobal> + \title Global Qt Declarations + + \brief The <QtGlobal> header file provides basic + declarations and is included by all other Qt headers. + + \sa <QtAlgorithms> + * / + \endcode + + See also \l{property}{\\property}, \l{class}{\\class}, + \l{namespace}{\\namespace} and \l{headerfile}{\\headerfile}. + + \row + \o \bold \\legalese \target legalese + \o \bold {The \\legalese command, and the corresponding \\endlegalese + command, delimit a licence agreement.} + + If the \\endlegalese command is omitted, QDoc will still + process the \\legalese command but considers the rest of + the documentation page as the license agreement. + + Ideally, the license documentation is located where the + licensed code is used. + + Later the documentation identified by the \\legalese + command can be accumulated into a list using the \l + {generatelist}{\\generatelist} command with the \c legalese + argument. This is useful to generate an overview of all the + licenses associated with the source code. + + For example: + + \code + \ * ! + ... + + On X11, Qt also supports drops via the Motif Drag \& + Drop Protocol. The implementation incorporates some + code that was originally written by Daniel Dardailler, + and adapted for Qt by Matt Koss \<koss@napri.sk\> and + Trolltech. Here is the original copyright notice: + + \legalese + \code + + Copyright 1996 Daniel Dardailler. + + Permission to use, copy, modify, distribute, and sell + this software for any purpose is hereby granted without + fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, + and that the name of Daniel Dardailler not be used in + advertising or publicity pertaining to distribution of + the software without specific, written prior + permission. Daniel Dardailler makes no representations + about the suitability of this software for any + purpose. It is provided "as is" without express or + implied warranty. + + Modifications Copyright 1999 Matt Koss, under the same + license as above. + + \ endcode + \endlegalese + * / + \endcode + + will be rendered as + + \quotation + ... + + On X11, Qt also supports drops via the Motif Drag \& + Drop Protocol. The implementation incorporates some + code that was originally written by Daniel Dardailler, + and adapted for Qt by Matt Koss \<koss@napri.sk\> and + Trolltech. Here is the original copyright notice: + + \legalese + \code + + Copyright 1996 Daniel Dardailler. + + Permission to use, copy, modify, distribute, and sell + this software for any purpose is hereby granted without + fee, provided that the above copyright notice appear in + all copies and that both that copyright notice and this + permission notice appear in supporting documentation, + and that the name of Daniel Dardailler not be used in + advertising or publicity pertaining to distribution of + the software without specific, written prior + permission. Daniel Dardailler makes no representations + about the suitability of this software for any + purpose. It is provided "as is" without express or + implied warranty. + + Modifications Copyright 1999 Matt Koss, under the same + license as above. + + \endcode + \endlegalese + \endquotation + + \row + \o \bold \\warning \target warning + \o \bold {The \\warning command renders a "Warning:" prefix to + the command's argument.} + + For example: + + \code + / *! + Qt::HANDLE is a platform-specific handle type + for system objects. This is equivalent to + \c{void *} on Windows and Mac OS X, and to + \c{unsigned long} on X11. + + \warning Using this type is not portable. + * / + \endcode + + will be rendered as + + \quotation + Qt::HANDLE is a platform-specific handle type + for system objects. This is equivalent to + \c{void *} on Windows and Mac OS X, and to + \c{unsigned long} on X11. + + \warning Using this type is not portable. + \endquotation + \endtable +*/ + +/*! + \page 12-0-qdoc-commands-miscellaneous.html + \previouspage Document Contents Commands + \contentspage QDoc Manual - Table of Contents + \nextpage Topical Commands + + \title Miscellaneous Commands + + These commands provide miscellaneous functions + connected to the visual appearance of the documentation, and to the + process of generating the documentation. + + \section1 Alphabetical List + + \l {12-0-qdoc-commands-miscellaneous.html#else}{\\else}, + \l {12-0-qdoc-commands-miscellaneous.html#endif}{\\endif}, + \l {12-0-qdoc-commands-miscellaneous.html#expire}{\\expire}, + \l {12-0-qdoc-commands-miscellaneous.html#generatelist}{\\generatelist}, + \l {12-0-qdoc-commands-miscellaneous.html#if}{\\if}, + \l {12-0-qdoc-commands-miscellaneous.html#include}{\\include}, + \l {12-0-qdoc-commands-miscellaneous.html#meta}{\\meta}, + \l {12-0-qdoc-commands-miscellaneous.html#omit}{\\omit}, + \l {12-0-qdoc-commands-miscellaneous.html#raw}{\\raw}, + \l {12-0-qdoc-commands-miscellaneous.html#raw}{\\unicode} + + \section1 Command Descriptions + + \table + \header + \o Command + \o Description + + \row + \o \bold \\expire \target expire + \o \bold {The \\expire command allows you to define an expiration + date for your documentation.} + + When using the \\expire command, QDoc will emit a warning + when the current date is larger than the specified + date. The command accepts one argument; the argument's + format is yyyy-mm-dd. For example: + + \code + / *! + \page porting.html + + \title Porting to Qt 3.x + + \expire 2004-12-31 + + This document describes porting applications from Qt + 2.x to Qt 3.x. + + The Qt 3.x series is not binary compatible with the + 2.x series. + ... + * / + \endcode + + If you run QDoc on 4 July 2005, it will emit the warning + + \quotation + porting.qdoc:6: Documentation expired 185 days ago + \endquotation + + \row + \o \bold \\generatelist \target generatelist + \o \bold {The \\generatelist command expands to a list of + various documentation or links to documentation.} + + For example in the Qt Reference Documentation: + + \code + / *! + \page classes.html + \title All Qt Classes (main index) + + For a shorter list that only includes the most + frequently used classes, see \l{Qt's Main Classes}. For + a list of Qt 3 support classes, see \l{Qt3Support + Classes}. + + \generatelist classes + * / + \endcode + + is used to generate \l {All Qt Classes (main index)}. + + The command accepts the following arguments: + + \target table example + + \list + \o \c annotatedclasses + + The \c annotatedclasses argument provides a table + containing the names of all the classes, and a + description of each class. Each class name is a link to + the class's reference documentation. + + For example: + + \quotation + \raw HTML + <table align="center" cellpadding="2" + cellspacing="1" border="0"> + + <tr valign="top" bgcolor="#d0d0d0"> + <td> + <a href="http://qt.nokia.com/doc/4.0/qdial.html"> + QDial</a> + </td> + <td>Rounded range control (like a speedometer + or potentiometer)</td> + </tr> + + <tr valign="top" bgcolor="#d0d0d0"> + <td> + <a href="http://qt.nokia.com/doc/4.0/qdialog.html"> + QDialog</a> + </td> + <td>The base class of dialog windows</td> + </tr> + + <tr valign="top" bgcolor="#d0d0d0"> + <td> + <a href="http://qt.nokia.com/doc/4.0/qdir.html"> + QDir</a> + </td> + <td>Access to directory structures and their + contents</td> + </tr> + </table> + \endraw + \endquotation + + A class is identified within the documentation by the + the \l {class}{\\class} command, and the descriptions + are based on the argument of the \l {brief}{\\brief} + commands in the class documentation. + + \target list example + + \o \c classes + + The \c classes argument provides a complete alphabetical + list of the classes. Each class name is a link to the + class's reference documentation. + + For example: + + \quotation + \raw HTML + <p><table width="100%"> + + <tr> + <td align="right"><b>A </b></td> + <td><a href="http://qt.nokia.com/doc/4.0/qabstractbutton.html">QAbstractButton</a></td> + + <td align="right"></td> + <td><a href="http://qt.nokia.com/doc/4.0/qabstractextensionmanager.html">QAbstractExtensionManager</a></td> + + <td align="right"></td> + <td><a href="http://qt.nokia.com/doc/4.0/qabstractitemmodel.html">QAbstractItemModel</a></td> + </tr> + + <tr> + <td align="right"></td> + <td><a href="http://qt.nokia.com/doc/4.0/qabstracteventdispatcher.html">QAbstractEventDispatcher</a></td> + + <td align="right"></td> + <td><a href="http://qt.nokia.com/doc/4.0/qabstractformbuilder.html">QAbstractFormBuilder</a></td> + + <td align="right"></td> + <td><a href="http://qt.nokia.com/doc/4.0/qabstractitemview.html">QAbstractItemView</a></td> + </tr> + + <tr> + <td align="right"></td> + <td><a href="http://qt.nokia.com/doc/4.0/qabstractextensionfactory.html">QAbstractExtensionFactory</a></td> + + <td align="right"></td> + <td><a href="http://qt.nokia.com/doc/4.0/qabstractitemdelegate.html">QAbstractItemDelegate</a></td> + + <td align="right"></td> + <td><a href="http://qt.nokia.com/doc/4.0/qabstractlistmodel.html">QAbstractListModel</a></td> + </tr> + </table></p> + \endraw + \endquotation + + A class is identified within the documentation by the + the \l {class}{\\class} command. + + \o \c classesbymodule + + This particular argument requests an additional argument, + i.e. a specification of the module. + + For example: + + \code + / *! + \page qtgui.html + \contentspage Qt Classes by Module + \previouspage QtCore Classes + \nextpage QtNetwork Classes + + \title QtGui Classes + + \keyword QtGui + + \generatelist {classesbymodule QtGui} + * / + \endcode + + Together, these arguments provide a table containing the + classes considered members of the specified module, + accompanied with a brief description. Each class name is + a link to the class's reference documentation. + + The generated table is rendered similarily to the one + generated when using the \l {table example}{\c + annotatedclasses} argument. + + For the basic classes in Qt, a class's module is + determined by its location, i.e. its directory. However, + for extensions, like ActiveQt and Qt Designer, a class + is related to a module with the \l + {inmodule}{\\inmodule} command. + + \o \c classesbyedition + + This particular argument requests an additional argument, + i.e. a specification of the edition. + + For example: + + \code + / *! + \page console-edition-classes.html + \title Qt Console Edition Classes + + \generatelist{classesbyedition Console} + * / + \endcode + + Together, these arguments provide a table containing the + classes considered members of the specified edition, + accompanied with a brief description. Each class name is + a link to the class's reference documentation. + + The edition a given class can be found in is determined by + the module it belongs to. + + \o \c compatclasses + + The \c compatclasses argument provides a complete and + alphabetical list of the support classes. A support + class is identified within the documentation by the \l + {compat}{\\compat} command. Each class name is a link to + the class's reference documentation. The list is + rendered similarily to the list generated by the \l + {list example}{\c classes} argument. + + \warning The \c classesbymodule argument will at some + point replace the this argument. + + \o \c functionindex + + The \c functionindex argument provides a complete + alphabetical list of all the documented member + functions. + + For example: + + \quotation + \raw HTML + <p><center><font size="+1"><b><a href="#a">A</a> <a href="#b">B</a> <a href="#c">C</a> <a href="#d">D</a> <a href="#e">E</a> <a href="#f">F</a> <a href="#g">G</a> <a href="#h">H</a> <a href="#i">I</a> <a href="#j">J</a> <a href="#k">K</a> <a href="#l">L</a> <a href="#m">M</a> <a href="#n">N</a> <a href="#o">O</a> <a href="#p">P</a> <a href="#q">Q</a> <a href="#r">R</a> <a href="#s">S</a> <a href="#t">T</a> <a href="#u">U</a> <a href="#v">V</a> <a href="#w">W</a> <a href="#x">X</a> <a href="#y">Y</a> <a href="#z">Z</a> </b></font></center></p> + + <p>DTDHandler: <a href="http://qt.nokia.com/doc/4.0/qxmlreader.html#DTDHandler">QXmlReader</a></p> + + <p>QAXCLASS: <a href="http://qt.nokia.com/doc/4.0/qaxfactory.html#QAXCLASS">global</a></p> + + <p>QAXFACTORY_BEGIN: <a href="http://qt.nokia.com/doc/4.0/qaxfactory.html#QAXFACTORY_BEGIN">global</a></p> + + <p>QAXFACTORY_DEFAULT: <a href="http://qt.nokia.com/doc/4.0/qaxfactory.html#QAXFACTORY_DEFAULT">global</a></p> + + <p>QAXFACTORY_END: <a href="http://qt.nokia.com/doc/4.0/qaxfactory.html#QAXFACTORY_END">global</a></p> + + \endraw + + ... + \endquotation + + \o \c legalese + + The \c legalese argument provides a complete list of all + the licenses. The licenses are identified within the + documentation using the \l {legalese}{\\legalese} + command. + + For example: + + \quotation + \raw HTML + <hr /> + <p> + Copyright (c) 1989 The Regents of the + University of California. All rights reserved. + </p> + + <p> + Redistribution and use in source and binary + forms are permitted provided that the above + copyright notice and this paragraph are + duplicated in all such forms and that any + documentation, advertising materials, and other + materials related to such distribution and use + acknowledge that the software was developed by + the University of California, Berkeley... + </p> + + <ul> + <li> + <a href="http://qt.nokia.com/doc/4.0/qdate.html#weekNumber">QDate::weekNumber()</a> + </li> + </ul> + + <hr /> + <p> + Copyright (c) 1991 by AT&T. + </p> + + <p> + Permission to use, copy, modify, and distribute + this software for any purpose without fee is + hereby granted, provided that this entire notice + is included in all copies of any software which + is or includes a copy or modification of this + software and in all copies of the supporting + documentation for such software... + </p> + + <ul> + <li> + <a href="http://qt.nokia.com/doc/4.0/qlocale.html">QLocale</a> + </li> + </ul> + <hr /> + \endraw + ... + \endquotation + + \o \c mainclasses + + The \c mainclasses argument provides a complete + alphabetical list of the main classes. Each class name + is a link to the class's reference documentation. A + class is related to the group of main classes by using + the \l {mainclass}{\\mainclass} command. + + The list is rendered similarily to the list generated by + the \l {list example}{\c classes} argument. + + \o \c overviews + + The \c overviews argument provides a complete + alphabetical overview of the documentation. Each list + entry is a link to the respective documentation page. + + The list includes pages declared using commands like \l + {page}{\\page} and \l {group}{\\group}. The list omits + examples and classes, and only lists the first page of + documentation that contains two or more pages using + commands like \l {nextpage}{\\nextpage}. + + For example: + + \quotation + \raw HTML + <ul> + + <li> + <a href="http://qt.nokia.com/doc/4.0/qtalgorithms.html"> + <QtAlgorithms> - Generic Algorithms + </a> + </li> + + <li> + <a href="http://qt.nokia.com/doc/4.0/qtglobal.html"> + <QtGlobal> - Global Qt Declarations + </a> + </li> + + <li> + <a href="http://qt.nokia.com/doc/4.0/qaxserver-demo-simple.html"> + A standard ActiveX and the "simple" ActiveQt widget + </a> + </li> + + <li> + <a href="http://qt.nokia.com/doc/4.0/aboutqt.html"> + About Qt + </a> + </li> + + <li> + <a href="http://qt.nokia.com/doc/4.0/trolltech.html"> + About Trolltech + </a> + </li> + + <li> + <a href="http://qt.nokia.com/doc/4.0/abstractwidgets.html"> + Abstract Widget Classes + </a> + </li> + + <li> + <a href="http://qt.nokia.com/doc/4.0/accessibility.html"> + Accessibility Classes + </a> + </li> + ... + </ul> + \endraw + \endquotation + + \o \c related + + The \c related argument is used in combination with the + \l {group}{\\group} command to list all the overviews + related to the given group. Each list entry is a link to + the respective documentation page. + + \o \c relatedinline + + The \c related argument is used in combination with the + \l {group}{\\group} command to collect all documentation + related to the given group. The various documentation + snippets are copied directly into the group page. + + \o \c service + + The \c service argument provides a complete alphabetical + list of the services. Each service name is a link to the + service's reference documentation. + + A service is identified within the documentation by the + \l {service}{\\service} command. + + \endlist + + + \row + \o \bold \\if \target if + \o \bold {The \\if command and the corresponding \\endif command + enclose parts of a QDoc comment that only will be included if + the condition specified by the command's argument is true.} + + The command reads the rest of the line and parses it as an + C++ #if statement. For example: + + \code + / *! + \if defined(opensourceedition) + + \bold{Note:} This edition is for the development of + \l{Qt Open Source Edition}{Free and Open Source} + software only; see \l{Qt Commercial Editions}. + + \endif + * / + \endcode + + This QDoc comment will only be rendered if the \c + opensourceedition preprocessor symbol is defined, and + specified in the \l {definesvariable}{defines} variable in + the configuration file to make QDoc process + the code within #ifdef and #endif: + + \code + defines = opensourceedition + \endcode + + You can also define the preprocessor symbol manually on the + command line. For more information see the documentation of + the \l {definesvariable}{defines} variable. + + See also \l{endif}{\\endif}, \l{else}{\\else}, \l + {definesvariable}{defines} and \l falsehoods. + + \row + \o \bold \\endif \target endif + \o \bold {The \\endif command and the corresponding \\if command + enclose parts of a QDoc comment that will be included if + the condition specified by the \l {if}{\\if} command's + argument is true.} + + For more information, see the documentation of the \l + {if}{\\if} command. + + See also \l{if}{\\if}, \l{else}{\\else}, \l + {definesvariable}{defines} and \l falsehoods. + + \row + \o \bold \\else \target else + \o \bold {The \\else command specifies an alternative if the + condition in the \l {if}{\\if} command is false.} + + The \\else command can only be used within \l + {if}{\\if...\\endif} commands, but is useful when there is + only two alternatives. For example: + + \code + / *! + The Qt 3 support library is provided to keep old + source code working. + + In addition to the \c Qt3Support classes, Qt 4 provides + compatibility functions when it's possible for an old + API to cohabit with the new one. + + \if !defined(QT3_SUPPORT) + \if defined(QT3_SUPPORTWARNINGS) + The compiler emits a warning when a + compatibility function is called. (This works + only with GCC 3.2+ and MSVC 7.) + \else + To use the Qt 3 support library, you need to + have the line QT += qt3support in your .pro + file (qmake automatically define the + QT3_SUPPORT symbol, turning on compatibility + function support). + + You can also define the symbol manually (e.g., + if you don't want to link against the \c + Qt3Support library), or you can define \c + QT3_SUPPORT_WARNINGS instead, telling the + compiler to emit a warning when a compatibility + function is called. (This works only with GCC + 3.2+ and MSVC 7.) + \endif + \endif + * / + \endcode + + If the \c QT3_SUPPORT is defined, the comment will be rendered + as + + \quotation + The Qt 3 support library is provided to keep old source + code working. + + In addition to the Qt3Support classes, Qt 4 provides + compatibility functions when it's possible for an old + API to cohabit with the new one. + \endquotation + + If \c QT3_SUPPORT isn't defined but \c QT3_SUPPORT_WARNINGS + is, the comment will be rendered as + + \quotation + The Qt 3 support library is provided to keep old source + code working. + + In addition to the Qt3Support classes, Qt 4 provides + compatibility functions when it's possible for an old + API to cohabit with the new one. + + The compiler emits a warning when a compatibility + function is called. (This works only with GCC 3.2+ and + MSVC 7.) + \endquotation + + If none of the symbols are defined, the comment will be + rendered as + + \quotation + The Qt 3 support library is provided to keep old + source code working. + + In addition to the \c Qt3Support classes, Qt 4 provides + compatibility functions when it's possible for an old + API to cohabit with the new one. + + To use the Qt 3 support library, you need to have the + line QT += qt3support in your .pro file (qmake + automatically define the QT3_SUPPORT symbol, turning on + compatibility function support). + + You can also define the symbol manually (e.g., if you + don't want to link against the \c Qt3Support library), + or you can define \c QT3_SUPPORT_WARNINGS instead, + telling the compiler to emit a warning when a + compatibility function is called. (This works only with + GCC 3.2+ and MSVC 7.) + \endquotation + + See also \l{if}{\\if}, \l{endif}{\\endif}, \l + {definesvariable}{defines} and \l falsehoods. + + \row + \o \bold \\include \target include + \o \bold {The \\include command expands to the contents of the + file specified by the command's argument.} + + \warning This is preliminary functionality. For more + information, see the \l + {26-qdoc-commands-compatibility.html#include-versus-input} + {compatibility} section. + + The command takes a file name as an argument, and is + useful when some piece of the documentation is used + repeatedly: Move the repetetive text into a separate file, + and use the \\include command whenever you want to insert + the separate documentation. + + The contents of such a file should follow QDoc syntax, + excluding the enclosing \c{/}\c{*!} ... \c{*}\c{/} marks. + To ensure that QDoc won't attempt to read the file as a + stand-alone piece of documentation, we recommend that you + use the \c .qdocinc extension. + + For example: + + \code + / *! + \page corefeatures.html + \title Core Features + + \include examples/signalandslots.qdocinc + \include examples/objectmodel.qdocinc + \include examples/layoutmanagement.qdocinc + * / + \endcode + + will be rendered as + + \quotation + \raw HTML + <h1>Core Features</h1> + \endraw + + \include examples/signalandslots.qdocinc + \include examples/objectmodel.qdocinc + \include examples/layoutmanagement.qdocinc + \endquotation + + Here is the actual \c .qdocinc files: \l + signalandslots.qdocinc, \l objectmodel.qdocinc, \l + layoutmanagement.qdocinc + + \row + \o \bold \\meta \target meta + \o \bold {The \\meta command is the QDoc equivalent to the HTML + \c meta tag.} + + The command accepts two arguments: The first argument (the + following word) is equivalent to the HTML meta tag's \i + name variable, and the second argument (the rest of the + line) is equivalent to the tag's \i contents variable. + + For example: + + \code + / *! + \meta author Summerfield + + \section1 Automatic Dialogs + + \abstract + This article shows how to maintain sets of + "attributes" (QVariant values), and how to allow + users to view and edit them using dialogs that are + created dynamically based on the attributes and + their types. + \endabstract + + The Attributes class described in this article holds a + set of QVariants, and can create a dialog to present + the QVariants to the user in an appropriate way. + + ... + * / + \endcode + + will be included in the generated HTML page as + + \code + <head> + ... + <meta name="author" content="Summerfield" /> + ... + </head> + \endcode + + \row + \o \bold \\omit \target omit + \o \bold {The \\omit command and the correspondning \\endomit + command delimit parts of the documentation that + you want QDoc to skip.} + + For example: + + \code + / *! + \table + \row + \o Basic Widgets + \o Basic GUI widgets such as buttons, comboboxes + and scrollbars. + + \omit + \row + \o Component Model + \o Interfaces and helper classes for the Qt + Component Model. + \endomit + + \row + \o Database Classes + \o Database related classes, e.g. for SQL databases. + \endtable + * / + \endcode + + will be rendered as + + \raw HTML + <table align="center" cellpadding="2" + cellspacing="1" border="0"> + + <tr valign="top" bgcolor="#d0d0d0"> + <td>Basic Widgets</td> + <td>Basic GUI widgets such as buttons, comboboxes + and scrollbars.</td> + </tr> + + <tr valign="top" bgcolor="#c0c0c0"> + <td>Database Classes</td> + <td>Database related classes, e.g. for SQL databases.</td> + </tr> + </table> + \endraw + + + \row + \o \bold \\raw \target raw + \o \bold {The \\raw command and the corresponding + \\endraw command delimit a block of raw mark-up language code.} + + The command takes an argument specifying the code's format; + currently the only supported format is HTML. + + The \\raw command is useful if you want some special HTML + effects in your documentation. For example: + + \code + / *! + Qt has some predefined QColor objects. For example: + + \raw HTML + <style type="text/css" id="colorstyles"> + #blue { background-color: #0000ff; color: #ffffff } + #darkBlue { background-color: #000080; color: #ffffff } + #cyan { background-color: #00ffff; color: #000000 } + </style> + + <p> + <tt id="blue">Blue(#0000ff)</tt>, + <tt id="darkBlue">dark blue(#000080)</tt> and + <tt id="cyan">cyan(#00ffff)</tt>. + \endraw + * / + \endcode + + will be rendered as + + \quotation + Qt has some predefined QColor objects. For example: + + \raw HTML + <style type="text/css" id="colorstyles"> + #blue { background-color: #0000ff; color: #ffffff } + #darkBlue { background-color: #000080; color: #ffffff } + #cyan { background-color: #00ffff; color: #000000 } + </style> + + <p> + <tt id="blue">Blue(#0000ff)</tt>, + <tt id="darkBlue">dark blue(#000080)</tt> and + <tt id="cyan">cyan(#00ffff)</tt>. + \endraw + \endquotation + + \row + \o \bold \\unicode \target unicode + \o \bold {The \\unicode command allows you to insert an + arbitrary Unicode character in the document.} + + The command takes an argument specifying the character as + an integer. By default, base 10 is assumed, unless a '0x' + or '0' prefix is specified (for base 16 and 8, + respectively). For example: + + \code + O G\unicode{0xEA}nio e as Rosas + + \unicode 0xC0 table en famille avec 15 \unicode 0x20AC par jour + + \unicode 0x3A3 \i{a}\sub{\i{i}} + \endcode + + will be rendered as + + \quotation + O G\unicode{0xEA}nio e as Rosas + + \unicode 0xC0 table en famille avec 15 \unicode 0x20AC par jour + + \unicode 0x3A3 \i{a}\sub{\i{i}} + \endquotation + + The \\raw command follows the same conventions as the \l + {i}{\\i} command for \l {argument}{punctuation and use of + braces} for the argument. + \endtable +*/ + +/*! + \page 12-1-signalandslots.html + \previouspage Miscellaneous Commands + \contentspage QDoc Manual - Table of Contents + + \title signalandslots.qdocinc + + \quotefile examples/signalandslots.qdocinc +*/ + +/*! + \page 12-2-objectmodel.html + \previouspage Miscellaneous Commands + \contentspage QDoc Manual - Table of Contents + + \title objectmodel.qdocinc + + \quotefile examples/objectmodel.qdocinc +*/ + +/*! + \page 12-3-layoutmanagement.html + \previouspage Miscellaneous Commands + \contentspage QDoc Manual - Table of Contents + + \title layoutmanagement.qdocinc + + \quotefile examples/layoutmanagement.qdocinc +*/ + +/*! + \page 13-qdoc-commands-topical.html + \previouspage Miscellaneous Commands + \contentspage QDoc Manual - Table of Contents + \nextpage Contextual Commands + + \title Topical Commands + + The topical commands tell QDoc what is being documented + (i.e. existing units like classes, functions and examples), and + some of the commands allows you to create extra pages. + + \section1 Alphabetical List + + \l {13-qdoc-commands-topical.html#class}{\\class}, + \l {13-qdoc-commands-topical.html#enum}{\\enum}, + \l {13-qdoc-commands-topical.html#example-command}{\\example}, + \l {13-qdoc-commands-topical.html#externalpage}{\\externalpage}, + \l {13-qdoc-commands-topical.html#fn}{\\fn}, + \l {13-qdoc-commands-topical.html#group}{\\group}, + \l {13-qdoc-commands-topical.html#headerfile}{\\headerfile}, + \l {13-qdoc-commands-topical.html#macro}{\\macro}, + \l {13-qdoc-commands-topical.html#module}{\\module}, + \l {13-qdoc-commands-topical.html#namespace}{\\namespace}, + \l {13-qdoc-commands-topical.html#page}{\\page}, + \l {13-qdoc-commands-topical.html#property}{\\property}, + \l {13-qdoc-commands-topical.html#service}{\\service}, + \l {13-qdoc-commands-topical.html#typedef}{\\typedef}, + \l {13-qdoc-commands-topical.html#variable}{\\variable}, + + \section1 General Description + + When QDoc is processing a comment, it will try to connect the + documentation to the source code. For that reason it will first + look for the topical commands. If there is no such command, it + will try to tie the documentation to the immediately following + code. If there is no topical command, and the documentation cannot + be tied to following code, the documentation is simply lost. + + \target topical argument + + The documented unit's name is passed as the unique argument for + all the topical commands. The argument's naming convention is the + documented unit's complete name. For example: + + \code + \enum QComboBox::InsertPolicy + \endcode + + Functions is a special case, the argument's naming convention for + the \l {fn}{\\fn} command is that of the function's definition + outside the class definition. For example: + + \code + \fn void PreviewWindow::setWindowFlags() + \endcode + + A topical command can appear anywhere in a comment, but must stand + alone on its own line. If the argument spans several lines, make + sure that each line (except the last one) is ended with a + backslash. In addition QDoc counts parentheses, which means that + if it encounters a '(' it considers everything until the closing + ')' as its argument. + + If a topical command is repeated with different arguments, the + same documentation will appear for both the units. For example: + + \code + / *! + \fn void PreviewWindow::setWindowFlags() + \fn void ControllerWindow::setWindowFlags() + + Sets the widgets flags using the QWidget::setWindowFlags() + function. + + Then runs through the available window flags, creating a text + that contains the names of the flags that matches the flags + parameter, displaying the text in the widgets text editor. + * / + \endcode + + The \c PreviewWindow::setWindowFlags() and \c + ControllerWindow::setWindowFlags() functions will get the same + documentation. + + \section1 Command Descriptions + + \table + \header + \o Command + \o Description + + \row + \o \bold \\class \target class + \o \bold {The \\class command tells QDoc that a class is + part of the public API, and lets you enter a detailed + description.} + + The command follows \l {topical argument}{the general + topical command convention} for the argument, and supports + nested classes, for example: + + \code + / *! + \class QMap::iterator + + \brief The QMap::iterator class provides an STL-style + non-const iterator for QMap and QMultiMap. + + QMap features both \l{STL-style iterators} and + \l{Java-style iterators}. The STL-style iterators ... + * / + \endcode + + The generated HTML documentation for the specified class is + put in \c <lower-case>classname.html. For example, the + documentation for the \c PreviewWindow class is located in + \c previewwindow.html. + + \target framework + + In addition to render the detailed description, the \\class + comand will generate the documentation framework, i.e. a + list of the class's types, properties, functions, signals + and slots with empty documentation. + + The command is typically accompanied with a \l + {brief}{\\brief} command, a \l {mainclass}{\\mainclass} + command, an \l {ingroup}{\\ingroup} command and a \l + {sa}{\\sa} command. For example: + + \code + / *! + \class PreviewWindow + \brief The PreviewWindow class is a custom widget + displaying the names of its currently set + window flags in a read-only text editor. + + \mainclass + \ingroup miscellaneous + + The PreviewWindow class inherits QWidget. The widget + displays the names of its window flags set with the \l + {function}{setWindowFlags()} function. It is also + provided with a QPushButton that closes the window. + + ... + + \sa QWidget + * / + \endcode + + will be rendered as + + \quotation + \raw HTML + <h1>PreviewWindow Class Reference</h1> + \endraw + + The PreviewWindow class is a custom widget displaying + the names of its currently set window flags in a + read-only text editor. \l {preview window}{More...} + + \raw HTML + <h3>Properties</h3> + \endraw + + \list + \o 52 properties inherited from QWidget + \o 1 property inherited from QObject + \endlist + + \raw HTML + <h3>Public Functions</h3> + \endraw + + \list + \o \l {constructor}{PreviewWindow}(QWidget *parent = 0) + \o void \l {function}{setWindowFlags}(Qt::WindowFlags flags) + \endlist + + \list + \o 183 public functions inherited from QWidget + \o 28 public functions inherited from QObject + \endlist + + \raw HTML + <h3>Public Slots</h3> + \endraw + + \list + \o 17 public slots inherited from QWidget + \o 1 public slot inherited from QObject + \endlist + + \raw HTML + <h3>Additional Inherited Members</h3> + \endraw + + \list + \o 1 signal inherited from QWidget + \o 1 signal inherited from QObject + \o 4 static public members inherited from QWidget + \o 4 static public members inherited from QObject + \o 39 protected functions inherited from QWidget + \o 7 protected functions inherited from QObject + \endlist + + \target preview window + + \raw HTML + <hr /> + <h2>Detailed Description</h2> + \endraw + + The PreviewWindow class is a custom widget displaying + the names of its currently set window flags in a + read-only text editor. + + The PreviewWindow class inherits QWidget. The widget + displays the names of its window flags set with the \l + {function}{setWindowFlags()} function. It is also + provided with a QPushButton that closes the window. + + ... + + See also QWidget. + + \raw HTML + <hr /> + <h2>Member Function Documentation</h2> + \endraw + + \target constructor + \raw HTML + <h3>PreviewWindow(QWidget *parent = 0)</h3> + \endraw + + Constructs a preview window widget with \i parent. + + \target function + \raw HTML + <h3>setWindowFlags(Qt::WindowFlags flags)</h3> + \endraw + + Sets the widgets flags using the + QWidget::setWindowFlags() function. + + Then runs through the available window flags, + creating a text that contains the names of the flags + that matches the flags parameter, displaying + the text in the widgets text editor. + \endquotation + + \row + \o \bold \\enum \target enum + \o \bold {The \\enum command allows you to document a C++ enum.} + + The command follows \l {topical argument}{the general + topical command convention} for the argument. + + The enum items are documented using the \l {value}{\\value} + command. If an item isn't documented, QDoc will emit a + warning. This can be avoided using the \l + {omitvalue}{\\omitvalue} command excluding an item from the + documentation. The enum documentation will be located in + the associated class, header file or namespace + documentation. + + For example: + + \code + enum Corner { + TopLeftCorner = 0x00000, + TopRightCorner = 0x00001, + BottomLeftCorner = 0x00002, + BottomRightCorner = 0x00003 + #if defined(QT3_SUPPORT) && !defined(Q_MOC_RUN) + ,TopLeft = TopLeftCorner, + TopRight = TopRightCorner, + BottomLeft = BottomLeftCorner, + BottomRight = BottomRightCorner + #endif + }; + \endcode + + In case of the Qt::Corner enum, + + \code + / *! + \enum Qt::Corner + + This enum type specifies a corner in a rectangle: + + \value TopLeftCorner + The top-left corner of the rectangle. + \value TopRightCorner + The top-right corner of the rectangle. + \value BottomLeftCorner + The bottom-left corner of the rectangle. + \value BottomRightCorner + The bottom-right corner of the rectangle. + + \omitvalue TopLeft + \omitvalue TopRight + \omitvalue BottomLeft + \omitvalue BottomRight + * / + \endcode + + this associated QDoc comment will be rendered as + + \quotation + \raw HTML + <h3 class="fn"><a name="Corner-enum"></a>enum Qt::Corner</h3> + + <p>This enum type specifies a corner in a rectangle:</p> + + <table border="1" cellpadding="2" cellspacing="1" width="100%"> + <tr> + <th width="25%">Constant</th> + <th width="15%">Value</th> + <th width="60%">Description</th> + </tr> + + <tr> + <td valign="top"><tt>Qt::TopLeftCorner</tt></td> + <td align="center" valign="top"><tt>0x00000</tt></td> + <td valign="top">The top-left corner of the rectangle.</td> + </tr> + + <tr> + <td valign="top"><tt>Qt::TopRightCorner</tt></td> + <td align="center" valign="top"><tt>0x00001</tt></td> + <td valign="top">The top-right corner of the rectangle.</td> + </tr> + + <tr> + <td valign="top"><tt>Qt::BottomLeftCorner</tt></td> + <td align="center" valign="top"><tt>0x00002</tt></td> + <td valign="top">The bottom-left corner of the rectangle.</td> + </tr> + + <tr> + <td valign="top"><tt>Qt::BottomRightCorner</tt></td> + <td align="center" valign="top"><tt>0x00003</tt></td> + <td valign="top">The bottom-right corner of the rectangle.</td> + </tr> + + </table> + \endraw + \endquotation + + in qt.html. + + See also \l {value}{\\value} and \l {omitvalue}{\\omitvalue}. + + \row + \o \bold \\example \target example-command + \o \bold {The \\example command allows you to document an + example.} + + The command follows \l {topical argument}{the general + topical command convention} for the argument. In particular + the command's argument is the example's path relative to + the paths listed in the \l exampledirs configuration + variable. + + The documentation will be located in \i + {path-to-example}.html, and QDoc will add a list of all the + example files at the top of this documentation page. + + For example, if \l exampledirs contain \c + $QTDIR/examples/widgets/imageviewer, then + + \code + / *! + \example widgets/imageviewer + \title ImageViewer Example + \subtitle + + The example shows how to combine QLabel and QScrollArea + to display an image. + + ... + * / + \endcode + + will be rendered as + + \quotation + \raw HTML + <center><h1>Image Viewer Example</h1></center> + \endraw + + Files: + \list + \o \l{http://qt.nokia.com/doc/4.0/widgets-imageviewer-imageviewer-cpp.html} + {widgets/imageviewer/imageviewer.cpp} + \o \l{http://qt.nokia.com/doc/4.0/widgets-imageviewer-imageviewer-h.html} + {widgets/imageviewer/imageviewer.h} + \o \l{http://qt.nokia.com/doc/4.0/widgets-imageviewer-main-cpp.html} + {widgets/imageviewer/main.cpp} + \endlist + + The example shows how to combine QLabel and QScrollArea + to display an image. + + ... + \endquotation + + in widgets-imageviewer.html. + + \row + \o \bold \\fn \target fn + \o \bold {The \\fn command allows you to document a function.} + + The command follows \l {topical argument}{the general + topical command convention} for the argument. In particular + it is important that the return type of the function, + whether it is \c const or not and the complete set of + arguments with type are included in the argument. If the + referenced function doesn't exist, QDoc will emit a + warning. + + Also, the \\fn command is QDoc's default command, i.e. when + no topical command can be found within a QDoc comment, QDoc + tries to tie the documentation to the following code as if + it was function documentation. + + This means that the command normally isn't necessary since + the recommended style is to write the function + documentation directly before the function implementation + in the \c .cpp file. In fact, it should only be used for + inline functions implemented in the \c .h file. + + For example: + + \code + / *! + \fn bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const + + Returns true if this toolbar is dockable in the given + \a area; otherwise returns false. + * / + \endcode + + will be rendered as + + \quotation + \raw HTML + <h3>bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const + </h3> + \endraw + + Returns true if this toolbar is dockable in the given + \a area; otherwise returns false. + \endquotation + + See also \l {overload}{\\overload}. + + \row + \o \bold \\group \target group + \o \bold {The \\group command creates a separate page that + lists the classes belonging to the group specified by the + command's argument.} + + The command follows \l {topical argument}{the general + topical command convention} for the argument. The \\group + command is typically followed by a \l {title}{\\title} + command and a short introduction to the group. The + generated HTML documentation for the specified group is put + in <lower-case>\i{group}.html. + + A class can be related to a group by using the \l + {ingroup}{\\ingroup} command. In addition, overviews can be + related to a group using the same command, but these must + be listed explicitly using the \l + {generatelist}{\\generatelist} command (see example below). + + Each class is listed with a link to the class reference + page and a brief description based on the classes' \l + {brief}{\\brief} texts. For example: + + \code + / *! + \group io + + \title Input/Output and Networking + + These classes are used to handle input and output to + and from external devices, processes, files etc. as + well as manipulating files and directories. + * / + \endcode + + will be rendered as + + \quotation + \raw HTML + + <h1>Input/Output and Networking</h1> + + <p>These classes are used to handle input and output + to and from external devices, processes, files etc. as + well as manipulating files and directories.</p> + + <p> + <table width="100%"> + <tr valign="top" bgcolor="#e0e0e0"> + <td><b> + <a href="http://qt.nokia.com/doc/4.0/qabstractsocket.html">QAbstractSocket</a> + </b></td> + <td> + The base functionality common to all socket types + </td></tr> + + <tr valign="top" bgcolor="#e0e0e0"> + <td><b> + <a href="http://qt.nokia.com/doc/4.0/qbuffer.html">QBuffer</a> + </b></td> + <td> + QIODevice interface for a QByteArray + </td></tr> + + <tr valign="top" bgcolor="#e0e0e0"> + <td><b> + <a href="http://qt.nokia.com/doc/4.0/qclipboard.html">QClipboard</a> + </b></td> + <td> + Access to the window system clipboard + </td></tr> + </table> + \endraw + \endquotation + + in io.html. + + Note that overviews related to the given group, must be + listed explicitly using the \l + {generatelist}{\\generatelist} command with the \c related + argument. For example: + + \code + / *! + \group architecture + + \title Architecture + + These documents describe aspects of Qt's architecture + and design, including overviews of core Qt features and + technologies. + + \generatelist{related} + * / + \endcode + + See also \l {ingroup}{\\ingroup} and \l + {generatelist}{\\generatelist}. + + \row + \o \bold \\headerfile \target headerfile + \o \bold {The \\headerfile command allows you to document + global functions, types and macros declared in a header file.} + + The command follows \l {topical argument}{the general + topical command convention} for the argument, and the + generated HTML documentation for the specified header file + is put in <lower-case>\i{headerfilename}.html. + + A function, type or macro can be associated with a + headerfile using the \l {relates}{\\relates} command. + + If the referenced header file doesn't exist, the + \\headerfile command will still create a documentation page + for a header file with the referenced file's name. + + For example: + + \code + / *! + \headerfile <QtAlgorithms> + + \title Generic Algorithms + + \brief The <QtAlgorithms> header file provides + generic template-based algorithms. + + Qt provides a number of global template functions in \c + <QtAlgorithms> that work on containers and perform + well-know algorithms. + * / + \endcode + + will be rendered as + + \quotation + \raw HTML + <center><h1><QtAlgorithms> - + Generic Algorithms</h1></center> + <p>The <QtAlgorithms> header file provides generic + template-based algorithms. + <a href="13-qdoc-commands-topical.html#header">More...</a> + </p> + + <h3>Functions</h3> + <ul> + <li>RandomAccessIterator + <a href="http://qt.nokia.com/doc/4.0/qlineedit.html#EchoMode-enum">qBinaryFind</a></b> + (RandomAccessIterator begin, RandomAccessIterator end, + const T & value)</li> + <li>...</li></ul> + <hr /> + \endraw + + \target header + + \raw HTML + <h2>Detailed Description</h2> + <p>The <QtAlgorithms> header file provides generic + template-based algorithms. </p> + \endraw + + Qt provides a number of global template functions in \c + <QtAlgorithms> that work on containers and perform + well-know algorithms. + + ... + \endquotation + + in qtalgorithms.html. + + \row + \o \bold \\macro \target macro + \o \bold {The \\macro command allows you to document a C++ macro.} + + The command follows \l {topical argument}{the general + topical command convention} for the argument. + + QDoc recognizes three different macro syntax: function-like + macros like Q_ASSERT(), declaration-style macros like + Q_PROPERTY() and macros without parentheses like Q_OBJECT. + + The \\macro command must be followed by a \l + {relates}{\\relates} command which attaches the + documentation to that of a related class, header file. or + namespace. Otherwise the documentation will be lost. + + For example: + + \code + / *! + \macro void Q_ASSERT(bool test) + \relates <QtGlobal> + + Prints a warning message containing the source code + file name and line number if \a test is false. + + ... + + \sa Q_ASSERT_X(), qFatal(), {Debugging Techniques} + * / + \endcode + + will be rendered as + + \quotation + \raw HTML + <h3>void Q_ASSERT ( bool <i>test</i> )</h3> + \endraw + + Prints a warning message containing the source code + file name and line number if \a test is false. + + ... + + See also Q_ASSERT_X(), qFatal() and \l {Debugging + Techniques}. + \endquotation + + in qtglobal.html. And + + \code + / *! + \macro Q_PROPERTY(...) + \relates QObject + + This macro declares a QObject property. The syntax is: + + ... + + \sa {Qt's Property System} + * / + \endcode + + will be rendered as + + \quotation + \raw HTML + <h3>Q_PROPERTY ( ... )</h3> + \endraw + + This macro declares a QObject property. The syntax is: + + ... + + See also \l {Qt's Property System}. + \endquotation + + in qobject.html. And + + \code + / *! + \macro Q_OBJECT + \relates QObject + + The Q_OBJECT macro must appear in the private section + of a class definition that declares its own signals and + slots or that uses other services provided by Qt's + meta-object system. + + ... + + \sa {Meta-Object System}, {Signals and Slots}, {Qt's + Property System} + * / + \endcode + + will be rendered as + + \quotation + \raw HTML + <h3>Q_OBJECT</h3> + \endraw + + The Q_OBJECT macro must appear in the private section + of a class definition that declares its own signals and + slots or that uses other services provided by Qt's + meta-object system. + + ... + + See also \l {Meta-Object System}, \l {Signals and + Slots} and \l {Qt's Property System}. + \endquotation + + in qobject.html. + + \row + \o \bold \\module \target module + \o \bold {The \\module creates a separate page that lists the + classes belonging to the module specified by the command's + argument.} + + The command follows \l {topical argument}{the general + topical command convention} for the argument. + + A class can be related to a module using the \l + {inmodule}{\\inmodule} command. + + The \\module command is typically followed by the \l + {title}{\\title} and \l {brief}{\\brief} commands. Each + class is listed with a link to the class reference page and + a brief description based on the classes' \l + {brief}{\\brief} texts. + + For example: + + \code + / *! + \module QtNetwork + + \title QtNetwork Module + + \brief The QtNetwork module offers classes that allow + you to write TCP/IP clients and servers. + + The network module provides classes to make network + programming easier and portable. It offers both + high-level classes such as QHttp and QFtp that + implement specific application-level protocols, and + lower-level classes such as QTcpSocket, QTcpServer, and + QUdpSocket. + * / + \endcode + + will be rendered as + + \quotation + \raw HTML + <h1><center>QtNetwork Module</center></h1> + \endraw + + The QtNetwork module offers classes that allow you to + write TCP/IP clients and servers.\l {module + details}{More...} + + \raw HTML + <p> + <table width="100%"> + <tr valign="top" bgcolor="#d0d0d0"> + <td><b> + <a href="http://qt.nokia.com/doc/4.0/qabstractsocket.html">QAbstractSocket</a> + </b></td> + <td> + The base functionality common to all socket types + </td></tr> + + <tr valign="top" bgcolor="#d0d0d0"> + <td><b> + <a href="http://qt.nokia.com/doc/4.0/qftp.html">QFtp</a> + </b></td> + <td> + Implementation of the FTP protocol + </td></tr> + + <tr valign="top" bgcolor="#d0d0d0"> + <td>...</td> + <td>...</td> + </tr> + </table> + + <p><hr /></p> + \endraw + + \target module details + + \raw HTML + <h2>Detailed Description</h2> + + <p> + The QtNetwork module offers classes that allow you to + write TCP/IP clients and servers. + </p> + + <p> + The network module provides classes to make network + programming easier and portable. It offers both + high-level classes such as QHttp and QFtp that + implement specific application-level protocols, and + lower-level classes such as QTcpSocket, QTcpServer, and + QUdpSocket. + </p> + \endraw + + ... + + \endquotation + + in qtnetwork.html. + + See also \l {inmodule}{\\inmodule} + + \row + \o \bold \\namespace \target namespace + \o \bold {The \\namespace command allows you to document a C++ + namespace.} + + The command follows \l {topical argument}{the general + topical command convention} for the argument. + + QDoc will generate the same additional links and + documentation for all the members of the namespace as it + does for \l {framework}{classes}. The documentation for + the specified namespace is put in <lower-case>\i + {namespace}.html. + + For example: + + \code + / *! + \namespace Qt + + \brief The Qt namespace contains miscellaneous + identifiers used throughout the Qt library. + * / + \endcode + + will be rendered as + + \quotation + \raw HTML + <center><h1>Qt Namespace Reference</h1></center> + <p>The Qt namespace contains miscellaneous + identifiers used throughout the Qt library. + <a href="13-qdoc-commands-topical.html#name">More...</a> + </p> + + <pre>#include <Qt></pre> + <ul> + <li> + <a href="http://qt.nokia.com/doc/4.0/qt-qt3.html"> + Qt 3 support members</a></li> + </ul> + + + <h3>Types</h3> + <ul> + <li>flags + <a href="http://qt.nokia.com/doc/4.0/qt.html#AlignmentFlag-enum">Alignment</a></b></li> + <li>...</li></ul> + <hr /> + \endraw + + \target name + + \raw HTML + <h2>Detailed Description</h2> + <p>The Qt namespace contains miscellaneous identifiers + used throughout the Qt library.</p> + \endraw + + ... + \endquotation + + in qt.html. + + \row + \o \bold \\page \target page + \o \bold {The \\page command allows you to create a stand-alone + documentation page.} + + The command follows \l {topical argument}{the general + topical command convention} for the argument. + + The page's title can be set using the \l {title}{\\title} + command. For example: + + \code + / *! + \page aboutqt.html + + \title About Qt + + Qt by Trolltech is a C++ toolkit for cross-platform GUI + application development. Qt provides single-source + portability across Microsoft Windows, Mac OS X, Linux, + and all major commercial Unix variants. (A version of + Qt 4 for embedded Linux will be available in + August/September 2005.) + + Qt provides application developers with all the + functionality needed to build applications with + state-of-the-art graphical user interfaces. Qt is fully + object-oriented, easily extensible, and allows true + component programming. + + ... + * / + \endcode + + will be rendered in its own HTML file: \l{About Qt}. + + \row + \o \bold {\\externalpage} \target externalpage + \o \bold {The \\externalpage command gives a title to + an external URL.} + + The command follows \l {topical argument}{the general + topical command convention} for the argument. + + For example: + + \code + / *! + \externalpage http://www.trolltech.com/products/embedded/index.html + \title Qtopia Core + * / + \endcode + + The QDoc comment above allows you to link to the Qtopia + Core webpage by simply linking to the given title. For + example: + + \code + / *! + The broad scope of the \l {Qtopia Core} API enables it to + be used across a wide variety of development projects. + * / + \endcode + + will be rendered as + + \quotation + The broad scope of the \l + {http://www.trolltech.com/products/embedded/index.html}{Qtopia + Core} API enables it to be used across a wide variety + of development projects. + \endquotation + + To achieve the same result without using the + \\externalpage command, you would have to hard code the + adress into your documentation: + + \code + / *! + The broad scope of the \l + {http://www.trolltech.com/products/embedded/index.html}{Qtopia + Core} API enables it to be used across a wide variety + of development projects. + * / + \endcode + + The \\externalpage command makes it easier to maintain the + documentation. If the adress changes, you only need to change the + argument of the \\externalpage command. + + \row + \o \bold \\property \target property + \o \bold {The \\property command allows you to document a Qt + property.} + + The command follows \l {topical argument}{the general + topical command convention} for the argument. + + A property is defined using the Q_PROPERTY() macro. The + macro takes as arguments the property's name and its set, + reset and get functions. For example: + + \code + Q_PROPERTY(QString state READ state WRITE setState) + \endcode + + The set, reset and get functions don't need to be + documented, documenting the property is sufficient. QDoc + will generate a list of the access function that will + appear in the property documentation which in turn will be + located in the documentation of the class that defines the + property. + + The \\property command is typically accompanied with a \l + {brief}{\\brief} command. In the case of a property, the + \l {brief}{\\brief} command's argument is a sentence + fragment that will be included in a one-sentence + description of the property generated by QDoc. The command + follows the same rules for the \l {brief + property}{description} as the \l {variable}{\\variable} + command. + + For example: + + \code + / *! + \property QPushButton::flat + \brief whether the border is disabled + + This property's default is false. + * / + \endcode + + will be rendered as + + \quotation + \raw HTML + <h3>flat : bool</h3> + \endraw + + This property holds whether the border is disabled. + + This property's default is false. + + Access functions: + + \list + \o \bold { bool isFlat () const} + \o \bold { void setFlat ( bool )} + \endlist + + \endquotation + + in qpushbutton.html. And + + \code + / *! + \property QWidget::width + \brief the width of the widget excluding any window frame + + See the \l {Window Geometry} documentation for an + overview of window geometry. + + \sa geometry, height, size + * / + \endcode + + will be rendered as + + \quotation + \raw HTML + <h3>width : const int</h3> + \endraw + + This property holds the width of the widget excluding + any window frame. + + See the \l {Window Geometry} documentation for an + overview of window geometry. + + Access functions: + + \list + \o \bold { int width () const} + \endlist + + See also \l{QWidget::geometry}{geometry}, + \l{QWidget::height}{height}, and \l{QWidget::size}{size}. + \endquotation + + in qwidget.html. + + \row + \o \bold \\service \target service + + \o \bold {The \\service command tells QDoc that a class is a + service class and specifies its alias, i.e. the associated + service's name.} + + The command takes two arguments, the service class's name + and the associated alias. For example: + + \code + / *! + \service TimeService Time + ... + * / + class TimeService : public QCopObjectService + { + ... + } + \endcode + + See also \l {class}{\\class} and \l + {generatelist}{\\generatelist}. + + \row + \o \bold \\typedef \target typedef + \o \bold {The \\typedef command allows you to document a C++ type + definition.} + + The command follows \l {topical argument}{the general + topical command convention} for the argument. + + The documentation will be located in the associated class, + header file or namespace documentation. When documenting a + global type definition, the \\typedef command must be + accompanied with a \l {relates}{\\relates} command. For + example: + + \code + / *! + \typedef QObjectList + \relates QObject + + Synonym for QList<QObject>. + * / + \endcode + + will be rendered as + + \quotation + \raw HTML + <h3>typedef QObjectList</h3> + \endraw + + Synonym for QList<QObject>. + \endquotation + + in qobject.html. Another, although more rare, example is + + \code + / *! + \typedef QMsgHandler + \relates QtGlobal + + This is a typedef for a pointer to a function with the + following signature: + + \code + void myMsgHandler(QtMsgType, const char *); + \ endcode + + \sa QtMsgType, qInstallMsgHandler() + * / + \endcode + + will be rendered as + + \quotation + \raw HTML + <h3>typedef QtMsgHandler</h3> + \endraw + + This is a typedef for a pointer to a function with the + following signature: + + \raw HTML + <tt> + <pre> void myMsgHandler(QtMsgType, const char *);</pre> + </tt> + \endraw + + See also QtMsgType and qInstallMsgHandler(). + + \endquotation + + in qtglobal.html. Other type definitions are located in the + documentation of the class that defines it, for example: + + \code + / *! + \typedef QLinkedList::Iterator + + Qt-style synonym for QList::iterator. + * / + \endcode + + will be rendered as + + \quotation + \raw HTML + <h3>typedef QLinkedList::Iterator</h3> + \endraw + + Qt-style synonym for QList::iterator. + \endquotation + + in qlinkedlist.html. + + \row + \o \bold \\variable \target variable + \o \bold {The \\variable command allows you to document a + member variable or a constant.} + + The command follows \l {topical argument}{the general + topical command convention} for the argument. + + The \\variable command is typically followed by a \l + {brief}{\\brief} command; QDoc will generate the + documentation for the variable based on the brief + description. The command follows the same rules for the \l + {brief property}{description} as the \l + {property}{\\property} command. + + The documentation will be located in the in the associated + class, header file or namespace documentation. + + In case of a member variable: + + \code + / *! + \variable QStyleOption::palette + \brief the palette that should be used when painting + the control + * / + \endcode + + will be rendered as + + \quotation + \raw HTML + <h3> + <a href="http://qt.nokia.com/doc/4.0/qpalette.html"> + QPalette + </a> + QStyleOption::palette + </h3> + \endraw + + This variable holds the palette that should be used + when painting the control. + \endquotation + + in qstyleoption.html. + + But you can also use the \\variable command to document + constants like for example the \c Type and \c UserType + constants in the QTreeWidgetItem class: + + \code + enum { Type = 0, UserType = 1000 }; + \endcode + + Then + + \code + / *! + \variable QTreeWidgetItem::Type + + The default type for tree widget items. + + \sa UserType, type() + * / + \endcode + + and + + \code + / *! + \variable QTreeWidgetItem::UserType + + The minimum value for custom types. Values below + UserType are reserved by Qt. + + \sa Type, type() + * / + \endcode + + will be rendered as + + \quotation + \raw HTML + <h3> + const int QTreeWidgetItem::Type + </h3> + \endraw + + The default type for tree widget items. + + See also \l {QTreeWidgetItem::UserType}{UserType} and + \l {QTreeWidgetItem::type()}{type()}. + + \raw HTML + <h3> + const int QTreeWidgetItem::UserType + </h3> + \endraw + + The minimum value for custom types. Values below + UserType are reserved by Qt. + + See also \l {QTreeWidgetItem::Type}{Type} and + \l{QTreeWidgetItem::type()}{type()}. + + \endquotation + + in qtreewidget.html. + \endtable +*/ + +/*! + \page 14-qdoc-commands-contextualcommands.html + \previouspage Topical Commands + \contentspage QDoc Manual - Table of Contents + \nextpage Navigation Commands + + \title Contextual Commands + + The contextual commands provide QDoc with information, that it + wouldn't figure out otherwise, about the documented object. For + example whether a class is thread-safe or not. + + These commands can appear anywhere within a QDoc comment. + + \section1 Alphabetical List + + \l {16-qdoc-commands-status.html#compat}{\\compat}, + \l {15-qdoc-commands-navigation.html#contentspage}{\\contentspage}, + \l {15-qdoc-commands-navigation.html#indexpage}{\\indexpage}, + \l {19-qdoc-commands-grouping.html#ingroup}{\\ingroup}, + \l {19-qdoc-commands-grouping.html#inmodule}{\\inmodule}, + \l {16-qdoc-commands-status.html#internal}{\\internal}, + \l {19-qdoc-commands-grouping.html#mainclass}{\\mainclass}, + \l {15-qdoc-commands-navigation.html#nextpage}{\\nextpage}, + \l {17-qdoc-commands-thread.html#nonreentrant}{\\nonreentrant}, + \l {16-qdoc-commands-status.html#obsolete}{\\obsolete}, + \l {18-qdoc-commands-relating.html#overload}{\\overload}, + \l {16-qdoc-commands-status.html#preliminary}{\\preliminary}, + \l {15-qdoc-commands-navigation.html#previouspage}{\\previouspage}, + \l {17-qdoc-commands-thread.html#reentrant}{\\reentrant}, + \l {18-qdoc-commands-relating.html#reimp}{\\reimp}, + \l {18-qdoc-commands-relating.html#relates}{\\relates}, + \l {15-qdoc-commands-navigation.html#startpage}{\\startpage}, + \l {17-qdoc-commands-thread.html#threadsafe}{\\threadsafe}, + \l {20-qdoc-commands-title.html#title}{\\title} + + \section1 Categories + \list + \o \l {Navigation Commands} + \o \l {Status Commands} + \o \l {Thread Support Commands} + \o \l {Relating Commands} + \o \l {Grouping Commands} + \o \l {Title Commands} + \endlist +*/ + +/*! + \page 15-qdoc-commands-navigation.html + \previouspage Contextual Commands + \contentspage QDoc Manual - Table of Contents + \nextpage Status Commands + + \title Navigation Commands + + The navigation commands allow you to link the pages of a multipage + document together. They provide the components of a navigation bar + at the top and bottom of the document. They also provide browser + and search engine support. + + \section1 Alphabetical List + + \l {15-qdoc-commands-navigation.html#contentspage}{\\contentspage}, + \l {15-qdoc-commands-navigation.html#indexpage}{\\indexpage}, + \l {15-qdoc-commands-navigation.html#nextpage}{\\nextpage}, + \l {15-qdoc-commands-navigation.html#previouspage}{\\previouspage}, + \l {15-qdoc-commands-navigation.html#startpage}{\\startpage} + + \section1 General Description + + The QDoc comments below shows a typical example using the + navigation commands. + + \code + / *! + \page basicqt.html + \contentspage {Basic Qt}{Contents} + \nextpage Getting Started + + \indexpage Index + \startpage Basic Qt + + \title Basic Qt + + The Qt toolkit is a C++ class library and a set of tools for + building multiplatform GUI programs using a "write once, + compile anywhere approach". + + Table of contents: + + \list + \o \l {Getting Started} + \o \l {Creating Dialogs} + \o \l {Creating Main Windows} + \endlist + * / + + / *! + \page gettingstarted.html + \previouspage Basic Qt + \contentspage {Basic Qt}{Contents} + \nextpage Creating Dialogs + + \indexpage Index + \startpage Basic Qt + + \title Getting Started + + This chapter shows how to combine basic C++ with the + functionality provided by Qt to create a few small graphical + interface (GUI) applications. + * / + + / *! + \page creatingdialogs.html + \previouspage Getting Started + \contentspage {Basic Qt}{Contents} + + \indexpage Index + \startpage Basic Qt + + \title Creating Dialogs + + This chapter will teach you how to create dialog boxes using Qt. + * / + + / *! + \page index.html + + \indexpage Index + \startpage Basic Qt + + \title Index + + \list + \o \l {Basic Qt} + \o \l {Creating Dialogs} + \o \l {Getting Started} + \endlist + * / + \endcode + + The second page of this multipage document, "Getting Started", + will be rendered as + + \quotation + \raw HTML + <table border="0" cellpadding="0" cellspacing="5" width="100%"> + + <tr> + <p> + [Previous: <a href="15-qdoc-commands-navigation.html#deadlink"> + Basic Qt</a>] + [<a href="15-qdoc-commands-navigation.html#deadlink">Contents</a>] + [Next: <a href="15-qdoc-commands-navigation.html#deadlink"> + Creating Dialogs</a>] + </p> + + <h1 align="center">Getting Started<br /></h1> + + <p> + This chapter shows how to combine basic C++ with the + functionality provided by Qt to create a few small graphical + interface (GUI) applications. + </p> + + <p> + [Previous: <a href="15-qdoc-commands-navigation.html#deadlink"> + Basic Qt</a>] + [<a href="15-qdoc-commands-navigation.html#deadlink">Contents</a>] + [Next: <a href="15-qdoc-commands-navigation.html#deadlink"> + Creating Dialogs</a>] + </p> + + </table> + \endraw + \endquotation + + in creatingdialogs.html. + + In addition, the \l {indexpage}{\\indexpage} and \l + {startpage}{\\startpage} commands specifies links to the page's + index page and start page. These links are used by browsers and + search engines. + + The index page is typically an alphabetical list of the document's + titles and topics, while the start page is the page considered by + the author to be the starting point of a multipage document. + + The links are included in the generated HTML source code but has + no visual effect on the documentation: + + \code + <head> + ... + <link rel="index" href="index.html" /> + <link rel="start" href="basicqt.html" /> + ... + </head> + \endcode + + \section1 Command Descriptions + + \table + \header + \o Command + \o Description + + \row + \o \bold \\previouspage \target previouspage + \o \bold {The \\previouspage command links the current page + to the previous one in an ordered series of documents}. + + The command has two arguments, each enclosed by curly + braces: The first is the link target, i.e. the title of the + previous page, the second is the link text. If the page's + title is equivalent to the link text, the second argument + can be omitted. + + The command must stand alone on its own line. + + In the end, the link is rendered at the top and bottom of + the current page. For an example, see the \l {General + Description} section. + + \row + \o \bold \\nextpage \target nextpage + \o \bold {The \\nextpage command links the current + page to the next page in an ordered series of documents}. + + The command follows the same syntax and argument convention + as the \l {previouspage}{\\previouspage} command. + + For an example, see the \l {General Description} section. + + \row + \o \bold \\startpage \target startpage + \o \bold {The \\startpage command specifies the first document + in a collection of documents.} + + The command must stand alone on its own line, and its + unique argument is the title of the first document. + + QDoc will generate a link to the specified document which + is included in the HTML file but has no visual effect on + the documentation. The generated link type tells browsers + and search engines which document is considered by the + author to be the starting point of the collection. + + For an example, see the \l {General Description} section. + + \row + \o \bold \\contentspage \target contentspage + \o \bold {The \\contentspage command links the current + page to a contents page}. + + The command follows the same syntax and argument convention + as the \l {previouspage}{\\previouspage} command. + + For an example, see the \l {General Description} section. + + \row + \o \bold \\indexpage \target indexpage + \o \bold {The \\indexpage command specifies a document providing + an index for the current document}. + + The command must stand alone on its own line, and its + unique argument is the title of the index document. + + QDoc will generate a link to the specified document which + is included in the HTML file but has no visual effect on + the documentation. The generated link type tells browsers + and search engines which document is considered by the + author to be the index page for the current document. + + For an example, see the \l {General Description} section. + + \endtable +*/ + +/*! + \page 16-qdoc-commands-status.html + \previouspage Navigation Commands + \contentspage QDoc Manual - Table of Contents + \nextpage Thread Support Commands + + \title Status Commands + + The usage commands can indicate whether a documented object is + under development, becoming obsolete, provided for compatibility + reasons or simply not part of the public interface. They can + describe the history of minor versions. And they can also describe + a documented object's ability to handle multithreaded programming. + + \section1 Alphabetical List + + \l {16-qdoc-commands-status.html#compat}{\\compat}, + \l {16-qdoc-commands-status.html#internal}{\\internal}, + \l {16-qdoc-commands-status.html#obsolete}{\\obsolete}, + \l {16-qdoc-commands-status.html#preliminary}{\\preliminary}, + \l {16-qdoc-commands-status.html#since}{\\since} + + \section1 Command Description + + \table + \header + \o Command + \o Description + + \row + \o \bold \\preliminary \target preliminary + \o \bold {The \\preliminary command indicates that the + referenced function is under development.} + + The command must stand on its own line. + + The \\preliminary command expands to a notification in the + function documentation, and marks the function as + preliminary when it appears in lists. For example: + + \code + / *! + \preliminary + + Returns information about the joining properties of the + character (needed for certain languages such as + Arabic). + * / + QChar::Joining QChar::joining() const + { + return ::joining(*this); + } + \endcode + + will be rendered as + + \quotation + \raw HTML + <h3> + <a href="http://qt.nokia.com/doc/4.0/qchar.html#Joining-enum">Joining</a> + QChar::joining () const</h3> + \endraw + + \bold {This function is under development and + is subject to change.} + + Returns information about the joining properties of the + character (needed for certain languages such as + Arabic). + \endquotation + + And the function's entry in QChar's list of functions will + be rendered as + + \quotation + \list + \o ... + \o Joining + \l {http://qt.nokia.com/doc/4.0/qchar.html#Joining-enum} + {joining}() + const \c (preliminary) + \o ... + \endlist + \endquotation + + \row + \o \bold \\obsolete \target obsolete + \o \bold {The \\obsolete command indicates that the referenced + function no longer should be used in new code; + there is no guarantee for how long it will remain in + the library.} + + The command must stand on its own line. + + When generating the reference documentation for a class, + QDoc will create and link to a separate page documenting + its obsolete functions. Usually an equivalent function is + provided as an alternative. + + For example: + + \code + / *! + \fn MyClass::MyObsoleteFunction + \obsolete + + Use MyNewFunction() instead. + * / + \endcode + + will be rendered as + + \quotation + \raw HTML + <h1>Obsolete Members for MyClass</h1> + \endraw + + \bold {The following class members are obsolete.} They + are provided to keep old source code working. We + strongly advise against using them in new code. + + ... + + \list + \o void MyObsoleteFunction() \c (obsolete) + \o ... + \endlist + + \raw HTML + <hr /> + <h2>Member Function Documentation</h2> + <h3>void MyObsoleteFunction ()</h3> + <p>Use MyNewFunction() instead.</p> + \endraw + + ... + \endquotation + + in myclass-obsolete.html + + + \row + \o \bold \\compat \target compat + \o \bold {The \\compat command indicates that the referenced class + or function is part of the support library provided to keep + old source code working.} + + The command must stand on its own line. + + Usually an equivalent function or class is provided as an + alternative. + + If the command is used within the documentation of a class, + the command expands to a warning that the referenced class + is part of the support library. The warning is located on + top of the associated documentation. For example: + + \code + / *! + \class MyQt3SupportClass + \compat + * / + \endcode + + will be rendered as + + \quotation + \bold {This class is part of the Qt 3 support + library.} It is provided to keep old source code + working. We strongly advise against using it in new + code. See the \l + {http://qt.nokia.com/doc/4.0/porting4.html}{Porting + Guide} for more information. + \endquotation + + on the top of the MyQt3SupportClass class reference. + + If the command is used when documenting a function, QDoc + will create and link to a separate page documenting Qt 3 + support members when generating the reference documentation + for the associated class. For example: + + \code + / *! + \fn MyClass::MyQt3SupportMemberFunction + \compat + + Use MyNewFunction() instead. + * / + \endcode + + will be rendered as + + \quotation + \raw HTML + <h1>Qt 3 Support Members for MyClass</h1> + \endraw + + \bold {The following class members are part of the Qt + 3 support layer.} They are provided to help you port + old code to Qt 4. We advise against using them in new + code. + + ... + + \list + \o void MyQt3SupportMemberFunction() + \o ... + \endlist + + \raw HTML + <hr /> + <h2>Member Function Documentation</h2> + <h3>void MyQt3SupportMemberFunction ()</h3> + <p>Use MyNewFunction() instead.</p> + \endraw + + ... + \endquotation + + in myclass-qt3.html + + + \row + \o \bold \\internal \target internal + \o \bold {The \\internal command indicates that the referenced + function is not part of the public interface.} + + The command must stand on its own line. + + QDoc ignores the documentation as well as the documented + item, when generating the associated class reference + documenation. For example: + + \code + / *! + \internal + + Tries to find the decimal separator. If it can't find + it and the thousand delimiter is != '.' it will try to + find a '.'; + * / + int QDoubleSpinBoxPrivate::findDelimiter + (const QString &str, int index) const + { + int dotindex = str.indexOf(delimiter, index); + if (dotindex == -1 && thousand != dot && delimiter != dot) + dotindex = str.indexOf(dot, index); + return dotindex; + } + \endcode + + in qspinbox.cpp, will not be rendered at all. + + \row + \o \bold \\since \target since + \o \bold {The \\since command tells in which minor release + the associated functionality was added.} + + For example: + + \code + / *! + \since 4.1 + + Returns an icon for \a standardIcon. + + ... + + \sa standardIconImplementation(), standardPixmap() + * / + QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const + { + } + \endcode + + will be rendered as + + \quotation + \raw HTML + <h3>QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const</h3> + \endraw + + This function was introduced in Qt version 4.1 + + Returns an icon for \a standardIcon. + + ... + + See also \l + {QStyle::standardIconImplementation()}{standardIconImplementation()} + and \l {QStyle::standardPixmap()}{standardPixmap()}. + \endquotation + + QDoc generates the "Qt" reference from the \l + {25-qdoc-configuration-derivedprojects.html#project}{\c + project} configuration variable. For that reason this + reference will change according to the current + documentation project. + + See also \l + {25-qdoc-configuration-derivedprojects.html#project}{\c + project}. + + \endtable +*/ + +/*! + \page 17-qdoc-commands-thread.html + \previouspage Status Commands + \contentspage QDoc Manual - Table of Contents + \nextpage Relating Commands + + \title Thread Support Commands + + The thread support commands specify the level of support for + multithreaded programming of a class or function. + + \section1 Alphabetical List + + \l {17-qdoc-commands-thread.html#nonreentrant}{\\nonreentrant}, + \l {17-qdoc-commands-thread.html#reentrant}{\\reentrant}, + \l {17-qdoc-commands-thread.html#threadsafe}{\\threadsafe} + + \section1 General Description + + There are three levels of support for multithreaded programming of + a class or function: \c threadsafe, \c reentrant and \c + nonreentrant. + + The default is \c nonreentrant which means that the associated + class or function cannot be called by multiple threads. \c + Reentrant and \c threadsafe are levels primarily used for classes. + + \c Reentrant means that all the functions in the referenced class + can be called simultaneously by multiple threads, provided that + each invocation of the functions reference unique data. While \c + threadsafe means that all the functions in the referenced class + can be called simultaneously by multiple threads even when each + invocation references shared data. + + When a class is declared \c reentrant or \c threadsafe, using the + \l {reentrant}{\\reentrant} and \l {threadsafe}{\\threadsafe} + commands respectively, functions in the referenced class can be + declared \c nonreentrant, using the \l + {nonreentrant}{\\nonreentrant} command, excluding the functions + from the general view. + + For example: + + \code + / *! + \class QLocale + \brief The QLocale class converts between numbers and their + string representations in various languages. + + \reentrant + \ingroup i18n + \ingroup text + \mainclass + + QLocale is initialized with a language/country pair in its + constructor and offers number-to-string and string-to-number + conversion functions similar to those in QString. + + ... + * / + + / *! + \nonreentrant + + Sets the global default locale to \a locale. These values are + used when a QLocale object is constructed with no + arguments. If this function is not called, the system's locale + is used. + + \warning In a multithreaded application, the default locale + should be set at application startup, before any non-GUI + threads are created. + + \sa system() c() + * / + void QLocale::setDefault(const QLocale &locale) + { + default_d = locale.d; + } + \endcode + + will be rendered as + + \quotation + \raw HTML + <h1><center>QLocale Class Reference</center></h1> + \endraw + + The QLocale class converts between numbers and their string + representations in various languages. More... + + \code + #include <QLocale> + \endcode + + \bold {Note:} All the functions in this class are \l + {threads.html#reentrant}{reentrant}, except \l + {QLocale::setDefault()}{setDefault()}. + + ... + + \raw HTML + <hr /> + <h2>Member Type Documentation</h2> + \endraw + + ... + + \raw HTML + <h3>void QLocale::setDefault ( const QLocale & locale ) </h3> + \endraw + + Sets the global default locale to locale. These values are + used when a QLocale object is constructed with no + arguments. If this function is not called, the system's locale + is used. + + \warning In a multithreaded application, the default locale + should be set at application startup, before any non-GUI + threads are created. + + \warning This function is not reentrant. + + See also \l {QLocale::system()}{system()} and \l + {QLocale::c()}{c()}. + + ... + \endquotation + + As shown above, QDoc generates a notification when a class is + declared reentrant, and lists the exceptions (the declared + nonreentrant functions). A link to the general documentation on \l + {threads.html#reentrant}{reentrancy and thread-safety} is + included. In addition a warning, "\bold Warning: This function is + not reentrant.", is generated in the nonreentrant functions' + documentation. + + QDoc will generate the same notification and warnings when a class + is declared threadsafe. + + For more information see the general documentation on \l + {threads.html#reentrant}{reentrancy and thread-safety}. + + \section1 Command Descriptions + + \table + \header + \o Command + \o Description + + \row + \o \bold \\threadsafe \target threadsafe + \o \bold {The \\threadsafe command indicates that the + associated class or function can be called simultaneously by + multiple threads even when each invocation references + shared data.} + + The command must stand on its own line. + + The generated documentation resulting from using the + \\threadsafe command is similar to the result of using the + \l {reentrant}{\\reentrant} command. For an example, see + the \l {General Description} section. + + See also \l{reentrant}{\\reentrant} and + \l{nonreentrant}{\\nonreentrant}. + + \row + \o \bold \\reentrant \target reentrant + \o \bold {The \\reentrant command indicates that the associated + class or function can be called simultaneously + by multiple threads, provided that each invocation of the + functions reference unique data.} + + The command must stand on its own line. + + For an example, see the \l {General Description} section. + + See also \l{nonreentrant}{\\nonreentrant} and + \l{threadsafe}{\\threadsafe}. + + \row + \o \bold \\nonreentrant \target nonreentrant + \o \bold {The \\nonreentrant command indicates that the + associated class or function cannot be called by + multiple threads.} + + The command must stand on its own line. + + For an example, see the \l {General Description} section. + + See also \l{reentrant}{\\reentrant} and + \l{threadsafe}{\\threadsafe}. + + \endtable +*/ + +/*! + \page 18-qdoc-commands-relating.html + \previouspage Thread Support Commands + \contentspage QDoc Manual - Table of Contents + \nextpage Grouping Commands + + \title Relating Commands + + The relation commands discribe how the documented object relates + to its context: Whether it is an overloaded function, a + reimplemented function or a global function related to a specified + class or header file. + + \section1 Alphabetical List + + \l {18-qdoc-commands-relating.html#overload}{\\overload}, + \l {18-qdoc-commands-relating.html#reimp}{\\reimp}, + \l {18-qdoc-commands-relating.html#relates}{\\relates}, + + \section1 Command Descriptions + + \table + \header + \o Command + \o Description + + \row + \o \bold \\overload \target overload + \o \bold {The \\overload command indicates that the + function is a secondary overload of its name.} + + The command must stand on its own line. + + For any overloaded function (except constructors), QDoc + expects one primary version of the function and all the + the overloads marked with the \bold{\\overload command}. + The primary version should be fully documented. Each + overload can have whatever extra documentation you want + to add for just that overload. + + From Qt 4.5, you can include the function name plus '()' + as a parameter to the \bold{\\overload} command, which + will include a standard \i{This function overloads...} + line of text with a link to the documentation for the + primary version of the function. + + For example: + + \code + / *! + \overload addAction() + + This convenience function creates a new action with an + \a icon and some \a text. The function adds the newly + created action to the menu's list of actions, and + returns it. + + \sa QWidget::addAction() + * / + QAction *QMenu::addAction(const QIcon &icon, const QString &text) + { + QAction *ret = new QAction(icon, text, this); + addAction(ret); + return ret; + } + \endcode + + will be rendered as + + \quotation + \raw HTML + <h3><a href="http://qt.nokia.com/doc/4.0/qaction.html">QAction</a> + * QMenu::addAction ( const QIcon & <i>icon</i>, + const QString & <i>text</i> ) + </h3> + \endraw + + This function overloads \l {http://qt.nokia.com/doc/4.0/qwidget.html#addAction}{addAction()} + + This convenience function creates a new action with an + \i icon and some \i text. The function adds the newly + created action to the menu's list of actions, and + returns it. + + See also + \l {http://qt.nokia.com/doc/4.0/qwidget.html#addAction} + {QWidget::addAction}(). + \endquotation + + If you don't include the function name with the + \bold{\\overlaod} command, then instead of the "This + function overloads..." line with the link to the + documentation for the primary version, you get the old + standard line: + + \quotation + This is an overloaded member function, provided for + convenience. + \endquotation. + + \row + \o \bold \\reimp \target reimp + \o \bold {The \\reimp command indicates that the + referenced function is a reimplementation of a virtual function, + where the reimplementation has no effect on the interface.} + + The command must stand on its own line. + + QDoc will omit the reimplemented function from the class + reference. For example: + + \code + / *! + \reimp + * / + void QToolButton::nextCheckState() + { + Q_D(QToolButton); + if (!d->defaultAction) + QAbstractButton::nextCheckState(); + else + d->defaultAction->trigger(); + } + \endcode + + will not be rendered at all; only a link to the inherited + QAbstractButton::nextCheckState() will appear in the + documentation. + + \row + \o \bold \\relates \target relates + \o \bold {The \\relates command attaches the documentation of + a global function to that of a related class or header file.} + + The command's argument is a class name, an the command (and + its argument) must stand on its own line. + + \code + / *! + \relates QChar + + Reads a char from the stream \a in into char \a chr. + + \sa {Format of the QDataStream operators} + * / + QDataStream &operator>>(QDataStream &in, QChar &chr) + { + quint16 u; + in >> u; + chr.unicode() = ushort(u); + return in; + } + \endcode + + will be rendered with the QChar documentation. + + \endtable +*/ + +/*! + \page 19-qdoc-commands-grouping.html + \previouspage Relating Commands + \contentspage QDoc Manual - Table of Contents + \nextpage Title Commands + + \title Grouping Commands + + The grouping commands relate classes to defined groups and + modules. The groups are used when generating lists of related + classes in the documentation, while the modules are elements of + Qt's structure. + + \section1 Alphabetical List + + \l {19-qdoc-commands-grouping.html#ingroup}{\\ingroup}, + \l {19-qdoc-commands-grouping.html#inmodule}{\\inmodule}, + \l {19-qdoc-commands-grouping.html#mainclass}{\\mainclass}, + + \section1 Command Descriptions + + \table + \header + \o Command + \o Description + + \row + \o \bold \\mainclass \target mainclass + \o \bold {The \\mainclass command relates the documented class to + a group called mainclasses.} + + The command must stand on its own line. + + For example: + + \code + / *! + \class QWidget qwidget.h + \brief The QWidget class is the base class of + all user interface objects. + + \mainclass + + ... + * / + \endcode + + will ensure that the QWidget class is included in the \c + mainclasses group, which means, for example, that the class + will appear on the list created by calling the \l + {generatelist}{\\generatelist} command with the \c + mainclasses argument: + + \l http://qt.nokia.com/doc/4.0/mainclasses.html + + See also \l {generatelist}{\\generatelist}. + + \row + \o \bold \\ingroup \target ingroup + + \o \bold {The \\ingroup command indicates that the given + overview or documented class belongs to a certain group of + related docmentation.} + + A class or overview may belong to many groups. + + The \\ingroup command's argument is a group name, but note + that the command considers the rest of the line as part of + its argument. Make sure that the group name is followed by + a linebreak. For example: + + \code + / *! + \class QDir + \brief The QDir class provides access to directory + structures and their contents. + + \ingroup io + ... + * / + \endcode + + will ensure that the QDir class is included in the \c io + group, which means, for example, that QDir will appear on + the list created by calling the \l {group}{\\group} command + with the \c io argument. + + Note that to list overviews that are related to a given + group, you must generate the list exlicitly by using the \l + {generatelist}{\\generatelist} command with the \c related + argument. + + See also \l {group}{\\group}. + \row + \o \bold \\inmodule \target inmodule + \o \bold {The \\inmodule command relates the documented class + to the module specified by the command's argument.} + + For the basic classes in Qt, a class's module is determined + by its location, i.e. its directory. However, for + extensions, like ActiveQt and Qt Designer, a class needs to + be related to a module explicitly. + + The command's argument is a module name, but note that the + command considers the rest of the line as part of its + argument. Make sure that the module name is followed by a + linebreak. For example: + + \code + /*! + \class QDesignerTaskMenuExtension + \inmodule QtDesigner + * / + \endcode + + will ensure that the QDesignerTaskMenuExtension class is + included in the \c QtDesigner module, which means, for + example, that the class will appear on the list created by + calling the \l {generatelist}{\\generatelist} command with + the \c {{classesbymodule QtDesigner}} argument. + + See also \l {module}{\\module} and \l + {generatelist}{\\generatelist}. + \endtable +*/ + +/*! + \page 20-qdoc-commands-title.html + \previouspage Grouping Commands + \contentspage QDoc Manual - Table of Contents + \nextpage QDoc Configuration + + \title Title Commands + + In general a title command considers everything that follows it + until the first line break as its argument. If the title needs to + be spanned over several lines, make sure to end each line (except + the last one) with a backslash. + + \section1 Alphabetical List + + \l {20-qdoc-commands-title.html#title}{\\title}, + \l {20-qdoc-commands-title.html#subtitle}{\\subtitle} + + \section1 Command Descriptions + + \table + \header + \o Command + \o Description + + \row + \o \bold \\title \target title + \o \bold {The \\title command sets the title for a + documentation page, or allows you to override it.} + + For example: + + \code + / *! + \page signalandslots.html + + \title Signals and Slots + + Signals and slots are used for communication between + objects. The signals and slots mechanism is a central + feature of Qt and probably the part that differs most + from the features provided by other frameworks. + + ... + * / + \endcode + + will be rendered as + + \quotation + \raw HTML + <h1><center>Signal and Slots</center></h1> + \endraw + + Signals and slots are used for communication between + objects. The signals and slots mechanism is a central + feature of Qt and probably the part that differs most + from the features provided by other frameworks. + + ... + \endquotation + See also \l {subtitle}{\\subtitle}. + + \row + \o \bold \\subtitle \target subtitle + \o \bold {The \\subtitle command sets a subtitle for a + documentation page.} + + For example: + + \code + / *! + \page qtopiacore-overview.html + + \title Qtopia Core + \subtitle Qt for Embedded Linux + + Qt/Embedded, the embedded Linux port of Qt, is a + complete and self-contained C++ GUI and platform + development tool for Linux-based embedded development. + + ... + * / + \endcode + + will be rendered as + + \quotation + \raw HTML + <h1><center>Qtopia Core</center></h1> + <h2><center>Qt for Embedded Linux</center></h2> + \endraw + + Qt/Embedded, the embedded Linux port of Qt, is a + complete and self-contained C++ GUI and platform + development tool for Linux-based embedded development. + + ... + \endquotation + + See also \l {title}{\\title}. + \endtable +*/ + +/*! + \page 21-0-qdoc-configuration.html + \previouspage Title Commands + \contentspage QDoc Manual - Table of Contents + \nextpage General Variables + + \title QDoc Configuration + + \tableofcontents + + \list + \o \l {Supporting Derived Projects} + \o \l {QDoc Compatibility} + \endlist + + When running QDoc to generate the documentation, you must specify + a configuration file on the command line: + + \quotation + \bold {/currentdirectory$ qdoc3 my-documentation.qdocconf} + \endquotation + + \section1 General Description + + The configuration file is a list of entries of entries of the form + \i {"variable = value"}. Using the configuration variables, you + can define where QDoc should find the various source files, images + and examples, where to put generated documentation etc. The + configuration file can also contain directives like \c + include. For an example, see the \l minimum.qdocconf file. + + In addition, you can use some particular configuration variables + to make QDoc support derived projects, i.e make the projects, for + example Qt Solutions, contain links to the online Qt + documentation. These variables are documented in the \l + {Supporting Derived projects} section. In this section you can + also find out how to use these variables to support your derived + projects. + + If some of the variable keys have the same values, they can be set + at the same time. For example: + + \code + {header, source}dirs = kernel + \endcode + + is equivalent to + + \code + headerdirs = kernel + sourcedirs = kernel + \endcode + + A variable's value can be set using either '=' or '+='. The + difference is that '=' overrides any previously set value, while + '+=' only adds the value to the previously set ones. + + In general, some of the variables accepts a list of strings as + their value, while others only accept a single string. If you + provide a variable of the latter type with several strings they + will simply be concatenated. The quotes around the value string + are optional. But applying them allows you to use special + characters like '=' and ' \" ' within the string. For example: + + \code + HTML.postheader = "<a href=\"index.html\">Home</a>" + \endcode + + If an entry spans many lines, use a backslash at the end of every + line but the last: + + \code + sourcedirs = kernel \ + tools \ + widgets + \endcode + + \section1 Configuration Variables + + \section2 Alphabetical List + + \l {22-qdoc-configuration-generalvariables.html#alias}{alias}, + \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoredirectives} + {Cpp.ignoredirectives}, + \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoretoken} + {Cpp.ignoretokens}, + \l {22-qdoc-configuration-generalvariables.html#definesvariable}{defines}, + \l {22-qdoc-configuration-generalvariables.html#edition}{edition}, + \l {22-qdoc-configuration-generalvariables.html#exampledirs}{exampledirs}, + \l {22-qdoc-configuration-generalvariables.html#examples}{examples}, + \l {22-qdoc-configuration-generalvariables.html#examples.fileextensions} + {examples.fileextensions}, + \l {22-qdoc-configuration-generalvariables.html#extraimages}{extraimages}, + \l {22-qdoc-configuration-generalvariables.html#falsehoods}{falsehoods}, + \l {22-qdoc-configuration-generalvariables.html#headerdirs}{headerdirs}, + \l {22-qdoc-configuration-generalvariables.html#headers}{headers}, + \l {22-qdoc-configuration-generalvariables.html#headers.fileextensions} + {headers.fileextensions}, + \l {24-qdoc-configuration-htmlvariables.html#HTML.footer}{HTML.footer}, + \l {24-qdoc-configuration-htmlvariables.html#HTML.postheader} + {HTML.postheader}, + \l {24-qdoc-configuration-htmlvariables.html#HTML.style}{HTML.style}, + \l {22-qdoc-configuration-generalvariables.html#imagedirs}{imagedirs}, + \l {22-qdoc-configuration-generalvariables.html#images}{images}, + \l {22-qdoc-configuration-generalvariables.html#images.fileextensions} + {images.fileextensions}, + \l {22-qdoc-configuration-generalvariables.html#language}{language}, + \l {22-qdoc-configuration-generalvariables.html#macro}{macro}, + \l {22-qdoc-configuration-generalvariables.html#outputdir}{outputdir}, + \l {22-qdoc-configuration-generalvariables.html#outputformats} + {outputformats}, + \l {22-qdoc-configuration-generalvariables.html#slow}{slow}, + \l {22-qdoc-configuration-generalvariables.html#sourcedirs}{sourcedirs}, + \l {22-qdoc-configuration-generalvariables.html#sources}{sources}, + \l {22-qdoc-configuration-generalvariables.html#sources.fileextensions} + {sources.fileextensions}, + \l {22-qdoc-configuration-generalvariables.html#spurious}{spurious}, + \l {22-qdoc-configuration-generalvariables.html#tabsize}{tabsize}, + \l {22-qdoc-configuration-generalvariables.html#version}{version}, + \l {22-qdoc-configuration-generalvariables.html#versionsym}{versionsym} + + \section2 Categories + + \list + \o \l {General Variables} + \o \l {C++ Specific Variables} + \o \l {HTML Specific Variables} + \endlist + + \section1 Configuration File Examples + + \list + \o A minimum configuration file: \l minimum.qdocconf + \o The Qt configuration file: \l qt.qdocconf + \endlist +*/ + +/*! + \page 21-1-minimum-qdocconf.html + \previouspage QDoc Configuration + \contentspage QDoc Manual - Table of Contents + + \title minimum.qdocconf + + \quotefile examples/minimum.qdocconf +*/ + +/*! + \page 21-2-qt-qdocconf.html + \previouspage QDoc Configuration + \contentspage QDoc Manual - Table of Contents + + \title qt.qdocconf + + \quotefile files/qt.qdocconf +*/ + +/*! + \page 22-qdoc-configuration-generalvariables.html + \previouspage QDoc Configuration + \contentspage QDoc Manual - Table of Contents + \nextpage Creating Help Project Files + + \title General Variables + + With the general QDoc configuration variables, you can define + where QDoc will find the various source files it needs to generate + the documentation, as well as the directory to put the generated + documentation. You can also do some minor manipulation of QDoc + itself, controlling its output and processing behavior. + + \section1 Alphabetical List + + \l {22-qdoc-configuration-generalvariables.html#alias}{alias}, + \l {22-qdoc-configuration-generalvariables.html#codeindent}{codeindent}, + \l {22-qdoc-configuration-generalvariables.html#definesvariable}{defines}, + \l {22-qdoc-configuration-generalvariables.html#edition}{edition}, + \l {22-qdoc-configuration-generalvariables.html#exampledirs}{exampledirs}, + \l {22-qdoc-configuration-generalvariables.html#examples}{examples}, + \l {22-qdoc-configuration-generalvariables.html#examples.fileextensions} + {examples.fileextensions}, + \l {22-qdoc-configuration-generalvariables.html#extraimages}{extraimages}, + \l {22-qdoc-configuration-generalvariables.html#falsehoods}{falsehoods}, + \l {22-qdoc-configuration-generalvariables.html#generateindex}{generateindex}, + \l {22-qdoc-configuration-generalvariables.html#headerdirs}{headerdirs}, + \l {22-qdoc-configuration-generalvariables.html#headers}{headers}, + \l {22-qdoc-configuration-generalvariables.html#headers.fileextensions} + {headers.fileextensions}, + \l {22-qdoc-configuration-generalvariables.html#imagedirs}{imagedirs}, + \l {22-qdoc-configuration-generalvariables.html#images}{images}, + \l {22-qdoc-configuration-generalvariables.html#images.fileextensions} + {images.fileextensions}, + \l {22-qdoc-configuration-generalvariables.html#language}{language}, + \l {22-qdoc-configuration-generalvariables.html#macro}{macro}, + \l {22-qdoc-configuration-generalvariables.html#outputdir}{outputdir}, + \l {22-qdoc-configuration-generalvariables.html#outputformats} + {outputformats}, + \l {22-qdoc-configuration-generalvariables.html#slow}{slow}, + \l {22-qdoc-configuration-generalvariables.html#sourcedirs}{sourcedirs}, + \l {22-qdoc-configuration-generalvariables.html#sources}{sources}, + \l {22-qdoc-configuration-generalvariables.html#sources.fileextensions} + {sources.fileextensions}, + \l {22-qdoc-configuration-generalvariables.html#spurious}{spurious}, + \l {22-qdoc-configuration-generalvariables.html#tabsize}{tabsize}, + \l {22-qdoc-configuration-generalvariables.html#tagfile}{tagfile}, + \l {22-qdoc-configuration-generalvariables.html#version}{version}, + \l {22-qdoc-configuration-generalvariables.html#versionsym}{versionsym} + + \section1 Variable Descriptions + + \table + + \header + \o Variable + \o Description + + \row + \o \bold alias \target alias + \o \bold {The \c alias variable renames a QDoc command.} + + The general syntax is \tt {alias.\i{original-command-name} + = \i temporary-command-name}. + + For example: + + \code + alias.i = e + \endcode + + renames the built-in command \\i (italics) to \\e. + + The \c alias variable is often used for compatibility + reasons; for more information see the \l {QDoc + Compatibility}{compatibility section}. + + See also \l macro. + + \row + \o \bold codeindent \target codeindent + \o \bold {The \c codeindent variable specifies the level of + indentation that QDoc uses when writing code snippets.} + + QDoc originally used a hard-coded value of four spaces for + code indentation to ensure that code snippets could be easily + distinguished from surrounding text. Since we can use + \l{HTML Specific Variables#HTML.stylesheets}{stylesheets} to + adjust the appearance of certain types of HTML elements, this + level of indentation is not always required. + + \row + \o \bold defines \target definesvariable + \o \bold {The \c defines variable specifies the C++ preprocessor + symbols that QDoc will recognize and respond to.} + + When a preprocessor symbol is specified using the \c + defines variable, you can also use the \l {if}{\\if} + command to enclose documentation that only will be included + if the preprocessor symbol is defined. + + The values of the variable are regular expressions (see + QRegExp for details). By default, no symbol is defined, + meaning that code protected with #ifdef...#endif will be + ignored. + + For example: + + \code + defines = Q_QDOC \ + QT_.*_SUPPORT \ + QT_.*_LIB \ + QT_COMPAT \ + QT3_SUPPORT \ + Q_WS_.* \ + Q_OS_.* \ + Q_BYTE_ORDER \ + __cplusplus + \endcode + + ensures that QDoc will process the code that requires these + symbols to be defined. For example: + + \code + #ifdef Q_WS_WIN + HDC getDC() const; + void releaseDC(HDC) const; + #endif + \endcode + + Since the Q_WS_.* regular expression (specified using the + \c defines variable) matches Q_WS_WIN, QDoc will process + the code within #ifdef and #endif in our example. + + You can also define preprocessor symbols manually on the + command line using the -D option. For example: + + \code + currentdirectory$ qdoc3 -Dconsoleedition qt.qdocconf + \endcode + + In this case the -D option ensures that the \c + consoleedition preprocessor symbol is defined when QDoc + processes the source files defined in the qt.qdocconf file. + + See also \l falsehoods and \l {if}{\\if}. + + \row + \o \bold edition \target edition + \o \bold {The \c edition variable specifies which modules are + included in each edition of a package, and provides QDoc + with information to provide class lists for each edition.} + + This feature is mostly used when providing documentation + for Qt packages. + + The \c edition variable is always used with a particular + edition name to define the modules for that edition: + + \code + edition.Console = QtCore QtNetwork QtSql QtXml + edition.Desktop = QtCore QtGui QtNetwork QtOpenGL QtSql QtXml \ + QtDesigner QtAssistant Qt3Support QAxContainer \ + QAxServer + edition.DesktopLight = QtCore QtGui Qt3SupportLight + \endcode + + In the above examples, the \c Console edition only includes + the contents of four modules. Only the classes from these + modules will be used when the + \l{Miscellaneous Commands#generatelist}{generatelist} command + is used to generate a list of classes for this edition: + + \code + \generatelist{classesbyedition Console} + \endcode + + \row + \o \bold exampledirs \target exampledirs + \o \bold {The \c exampledirs variable specifies the directories + containing the source code of the example files.} + + The \l {examples}{\c examples} and \c exampledirs variables + are used by the \l {quotefromfile}{\\quotefromfile}, \l + {quotefile}{\\quotefile} and \l {example}{\\example} + commands. If both the \l {examples}{\c examples} and \c + exampledirs variables are defined, QDoc will search in + both, first in \l {examples}{\c examples} then in \c + exampledirs. + + QDoc will search through the directories in the specified + order, and accept the first matching file it finds. It will + only search in the specified directories, \i not in + subdirectories. + + For example: + + \code + exampledirs = $QTDIR/doc/src \ + $QTDIR/examples \ + $QTDIR \ + $QTDIR/qmake/examples + + examples = $QTDIR/examples/widgets/analogclock/analogclock.cpp + \endcode + + When processing + + \code + \quotefromfile widgets/calculator/calculator.cpp + \endcode + + QDoc will then see if there exists a file called \c + calculator.cpp listed as a value in the \l {examples}{\c + examples} variable. If it doesn't, it will search in the \c + exampledirs variable, and first see if there exists a file + called + + \code + $QTDIR/doc/src/widgets/calculator/calculator.cpp + \endcode + + If it doesn't, QDoc will continue looking for a file + called + + \code + $QTDIR/examples/widgets/calculator/calculator.cpp + \endcode + + and so forth. + + See also \l examples. + + \row + \o \bold examples \target examples + \o \bold {The \c examples variable allows you to specify individual + example files in addition to those located in the directories + specified by the \l {exampledirs}{\c exampledirs} variable.} + + The \c examples and \l {exampledirs}{\c exampledirs} + variables are used by the \l + {quotefromfile}{\\quotefromfile}, \l + {quotefile}{\\quotefile} and \l {example}{\\example} + commands. If both the \c examples and \l {exampledirs}{\c + exampledirs} variables are defined, QDoc will search in + both, first in \c examples then in \l {exampledirs}{\c + exampledirs}. + + QDoc will search through the values listed for the \c + examples variable, in the specified order, and accept + the first one it finds. + + For an extensive example, see the \l {exampledirs}{\c + exampledirs} command. But note that if you know the file is + listed in the \c examples variable, you don't need to + specify its path: + + \code + \quotefromfile calculator.cpp + \endcode + + See also \l exampledirs. + + \row + \o \bold examples.fileextensions \target examples.fileextensions + \o \bold {The \c examples.fileextensions variable specifies the + file extensions that qdoc will look for when collecting example + files for display in the documentation.} + + The default extensions are *.cpp, *.h, *.js, *.xq, *.svg, *.xml + and *.ui. However, if + + The extensions are given as standard wildcard expressions. + You can add a file extension to the filter using '+='. For + example: + + \code + examples.fileextensions += *.qrc + \endcode + + See also \l{headers.fileextensions}. + + \row + \o \bold extraimages \target extraimages + \o \bold {The \c extraimages variable tells QDoc to incorporate + specific images in the generated documentation.} + + QDoc will not recognize images used within HTML (or any + other markup language). If we want the images to be copied + from the directories specified by \l {imagedirs}{\c + imagedirs} (the images in question must be located in these + directories) to the output directory, we must specify the + images using the \c extraimages variable. + + The general syntax is \tt {extraimages.\i{format} = \i + image}. The file extension is optional. + + For example, in \l qt.qdocconf we use a couple of images + within the HTML.postheader variable which value is pure + HTML. For that reason, these images are specified using the + \c extraimages variable: + + \code + extraimages.HTML = qt-logo + \endcode + + See also \l images and \l imagedirs. + + \row + \o \bold falsehoods \target falsehoods + \o \bold {The \c falsehoods variable defines the truth value of + specified preprocessor symbols as false.} + + If this variable is not set for a preprocessor symbol, QDoc + assumes its truth value is true. The exception is '0', + which value always is false. + + QDoc will recognize, and is able to evaluate, the following + preprocessor syntax: + + \code + #ifdef NOTYET + ... + #endif + + #if defined (NOTYET) + ... + #end if + \endcode + + However, faced with unknown syntax like + + \code + #if NOTYET + ... + #endif + \endcode + + QDoc will evaluate it as true by default, \i unless the + preprocessor symbol is specified within the \c falsehoods + variable entry: + + \code + falsehoods = NOTYET + \endcode + + See also \l defines. + + \row + \o \bold generateindex \target generateindex + \o \bold{The \c generateindex variable contains a boolean value that + specifies whether to generate an index file when HTML documentation + is generated.} + + By default, an index file is always generated with HTML documentation, + so this variable is typically only used when disabling this feature + (by setting the value to \c false) or when enabling index generation + for the WebXML output (by setting the value to \c true). + \row + \o \bold headerdirs \target headerdirs + \o \bold {The \c headerdirs variable specifies the directories + containing the header files associated with the \c .cpp source + files used in the documentation.} + + For example: + + \code + headerdirs = $QTDIR/src \ + $QTDIR/extensions/activeqt \ + $QTDIR/extensions/motif \ + $QTDIR/tools/designer/src/lib/extension \ + $QTDIR/tools/designer/src/lib/sdk \ + $QTDIR/tools/designer/src/lib/uilib + \endcode + + When executed, the first QDoc will do is to read through + the headers specified in the \l {headers}{\c headers} + variable, and the ones located in the directories specified + in the \c headerdir variable (including all + subdirectories), building an internal structure of the + classes and their functions. + + Then it will read through the sources specified in the \l + {sources}{\c sources}, and the ones located in the + directories specified in the \l {sourcedirs}{\c sourcedirs} + varible (including all subdirectories), merging the + documentation with the structure it retrieved from the + header files. + + If both the \c headers and \c headerdirs variables are + defined, QDoc will read through both, first \l {headers}{\c + headers} then \c headerdirs. + + In the specified directories, QDoc will only read the files + with the fileextensions specified in the \l + {headers.fileextensions}{\c headers.fileextensions} + variable. The default extensions are *.ch, *.h, *.h++, + *.hh, *.hpp and *.hxx". The files specified by \l + {headers}{\c headers} will be read independent of their + fileextensions. + + See also \l headers and \l headers.fileextensions. + + \row + \o \bold headers \target headers + \o \bold {The \c headers variable allows you to specify individual + header files in addition to those located in the directories + specified by the \l {headerdirs}{\c headerdirs} variable.} + + For example: + + \code + headers = $QTDIR/src/gui/widgets/qlineedit.h \ + $QTDIR/src/gui/widgets/qpushbutton.h + \endcode + + When processing the \c headers variable, QDoc behaves in the + same way as it does when processing the \l {headerdirs}{\c + headerdirs} variable. For more information, see the \l + {headerdirs}{\c headerdirs} variable. + + See also \l headerdirs. + + \row + \o \bold headers.fileextensions \target headers.fileextensions + \o \bold {The \c headers.fileextensions variable specify the + extension used by the headers.} + + When processing the header files specified in the \l + {headerdirs}{\c headerdirs} variable, QDoc will only read + the files with the fileextensions specified in the \c + headers.fileextensions variable. In this way QDoc avoid + spending time reading irrelevant files. + + The default extensions are *.ch, *.h, *.h++, *.hh, *.hpp + and *.hxx. + + The extensions are given as standard wildcard expressions. + You can add a file extension to the filter using '+='. For + example: + + \code + header.fileextensions += *.H + \endcode + + \warning The above assignment may not work as described. + + See also \l headerdirs. + + \row + \o \bold imagedirs \target imagedirs + \o \bold {The \c imagedirs variable specifies the directories + containing the images used in the documentation.} + + The \l {images}{\c images} and \c imagedirs variables are + used by the \l {image}{\\image} and \l + {inlineimage}{\\inlineimage} commands. If both the \l + {images}{\c images} and \c imagedirs variables are defined, + QDoc will search in both, first in \l {images}{\c images} + then in \c imagedirs. + + QDoc will search through the directories in the specified + order, and accept the first matching file it finds. It will + only search in the specified directories, \i not in + subdirectories. + + For example: + + \code + imagedirs = $QTDIR/doc/src/images \ + $QTDIR/examples + + images = $QTDIR/doc/src/images/calculator-example.png + \endcode + + When processing + + \code + \image calculator-example.png + \endcode + + QDoc will then see if there exists a file called + calculator-example.png listed as a value in the \c images + variable. If it doesn't, it will search in the \c imagedirs + variable, and first see if there exists a file called + + \code + $QTDIR/doc/src/images/calculator-example.png + \endcode + + If it doesn't, QDoc will look for a file called + + \code + $QTDIR/examples/calculator-example.png + \endcode + + You can filter the images in an image directory using the + \l {images.fileextensions}{\c images.fileextensions} + variable. The general idea behind the \l + {images.fileextensions}{\c images.fileextensions} variable + is to enable different image format for different output + format. + + \warning The \l {images.fileextensions}{\c + images.fileextensions} variable's functionality is + preliminay since QDoc at this point only support HTML. + + See also \l images and \l images.fileextensions. + + \row + \o \bold images \target images + \o \bold {The \c images variable allows you to specify individual + image files in addition to those located in the directories + specified by the \l {imagedirs}{\c imagedirs} variable.} + + For example: + + \code + images = $QTDIR/doc/src/images/calculator-example.png + \endcode + + When processing the \c images variable, QDoc behaves in the + same way as it does when processing the \l {imagedirs}{\c + imagedirs} variable. For more information, see the \l + {imagedirs}{\c imagedirs} variable. + + See also \l imagedirs and \l images.fileextensions. + + \row + \o \bold images.fileextensions \target images.fileextensions + \o \bold {The images.fileextensions variable filters the files within + an image directory.} + + The variable's values (the extensions) are given as + standard wildcard expressions. The general syntax is: \tt + {images.fileextensions.\i{format} = *.\i{extension}}. + + The idea is to enable different image format for different + output format. For example: + + \code + images.fileextensions.HTML = *.png + images.fileextensions.LOUT = *.eps + \endcode + + Then, when processing the \l {image}{\\image} and \l + {inlineimage}{\\inlineimage} commands, QDoc will only + search for files with extensions specified in the output + format's associated image extension variable. + + \warning This is preliminary functionality since QDoc at + this point only support HTML. + + The default extensions for HTML are *.png, *.jpg, *.jpeg + and *.gif. + + You can add a file extension to the filter using '+='. For + example: + + \code + images.fileextensions.HTML += *.eps + \endcode + + See also \l imagedirs and \l images. + + \row + \o \bold language \target language + \o \bold {The \c language variable specifies the language of the + source code that is used in the documentation.} + + Currently, C++ is the only language that QDoc + understands. It is also the default language, and doesn't + really need to be specified. But for example in \l + qt.qdocconf: + + \code + language = Cpp + \endcode + + identifies the language of the Qt source code as C++. + + \row + \o \bold macro \target macro + \o \bold {The \c macro variable can be used to create your + own QDoc commands.} + + The general syntax is \tt {macro.\i{command} = + "\i{definition}}". The definition can be described using + QDoc syntax. In addition it is possible to provide an HTML + definition by appending .HTML to the variable. + + For example in \l qt.qdocconf: + + \code + macro.gui = "\\bold" + macro.raisedaster.HTML = "<sup>*</sup>" + \endcode + + makes sure that the \\gui command renders its argument using a + bold font, and that \\raisedaster renders a '*'. + + \row + \o \bold outputdir \target outputdir + \o \bold {The \c outputdir variable specifies the directory + where QDoc will put the generated documentation.} + + In qt.qdocconf: + + \code + outputdir = $QTDIR/doc/html + \endcode + + locates the generated Qt reference documentation in + $QTDIR/doc/html. For example, the documentation of the + QWidget class is located in + + \code + $QTDIR/doc/html/qwidget.html + \endcode + + The associated images will be put in an \c images subdirectory. + + \warning When running QDoc multiple times using the same output + directory, all files from the previous run will be lost. + + \row + \o \bold outputformats \target outputformats + \o \bold {The \c outputformats variable specifies the format of + the generated documentation.} + + Currently, QDoc only supports the HTML format. It is also + the default format, and doesn't need to be specified. + + \row + \o \bold qhp \target qhp + \o \bold{The \c qhp variable is used to define the information to be + written out to Qt Help Project (\c{qhp}) files.} + + See the \l{Creating Help Project Files} chapter for information + about this process. + + \row + \o \bold slow \target slow + \o \bold {The \c slow variable specifies whether QDoc should do + time-consuming processing, such as syntax highlighting.} + + By default, this setting is false. + + Example: + + \code + slow = true + \endcode + + Another way to turn on "slowness" is to invoke QDoc with the + \c -slow command-line option. + + \row + \o \bold sourcedirs \target sourcedirs + \o \bold {The \c sourcedirs variable specifies the directories + containing the \c .cpp or \c .qdoc files used in + the documentation.} + + For example in \l qt.qdocconf + + \code + sourcedirs = $QTDIR/src \ + $QTDIR/doc/src \ + $QTDIR/extensions/activeqt \ + $QTDIR/extensions/motif \ + $QTDIR/tools/designer/src/lib/extension \ + $QTDIR/tools/designer/src/lib/sdk \ + $QTDIR/tools/designer/src/lib/uilib + \endcode + + When executed, the first QDoc will do is to read through + the headers specified in the \l {header}{\c header} + variable, and the ones located in the directories specified + in the \c headerdir variable (including all + subdirectories), building an internal structure of the + classes and their functions. + + Then it will read through the sources specified in the \l + {sources}{\c sources}, and the ones located in the + directories specified in the \l {sourcedirs}{\c sourcedirs} + varible (including all subdirectories), merging the + documentation with the structure it retrieved from the + header files. + + If both the \c sources and \c sourcedirs variables are + defined, QDoc will read through both, first \l {sources}{\c + sources} then \c sourcedirs. + + In the specified directories, QDoc will only read the files + with the fileextensions specified in the \l + {sources.fileextensions}{\c sources.fileextensions} + variable. The default extensions are *.c++, *.cc, *.cpp and + *.cxx. The files specified by \l {sources}{\c sources} will + be read independent of their fileextensions. + + See also \l sources and \l sources.fileextensions. + + \row + \o \bold sources \target sources + \o \bold {The \c sources variable allows you to specify + individual source files in addition to those located in the + directories specified by the \l {sourcedir}{\c sourcedir} + variable.} + + For example: + + \code + sources = $QTDIR/src/gui/widgets/qlineedit.cpp \ + $QTDIR/src/gui/widgets/qpushbutton.cpp + \endcode + + When processing the \c sources variable, QDoc behaves in the + same way as it does when processing the \l {sourcedirs}{\c + sourcedirs} variable. For more information, see the \l + {sourcedirs}{\c sourcedirs} variable. + + See also \l sourcedirs. + + \row + \o \bold sources.fileextensions \target sources.fileextensions + \o \bold {The \c sources.fileextensions variable filters the + files within a source directory.} + + When processing the source files specified in the \l + {sourcedirs}{\c sourcedirs} variable, QDoc will only read + the files with the fileextensions specified in the \c + sources.fileextensions variable. In this way QDoc avoid + spending time reading irrelevant files. + + The default extensions are *.c++, *.cc, *.cpp and *.cxx. + + The extensions are given as standard wildcard expressions. + You can add a file extension to the filter using '+='. For + example: + + \code + sources.fileextensions += *.CC + \endcode + + \warning The above assignment may not work as described. + + See also \l sourcedirs and \l sources. + + \row + \o \bold spurious \target spurious + \o \bold {The \c spurious variable excludes specified + QDoc warnings from the output.} + + The warnings are specified using standard wildcard + expressions. For example: + + \code + spurious = "Cannot find .*" \ + "Missing .*" + \endcode + + makes sure that warnings matching either of these + expressions, will not be part of the output when running + QDoc. For example would the following warning be omitted + from the output: + + \code + qt-4.0/src/opengl/qgl_mac.cpp:156: Missing parameter name + \endcode + + \row + \o \bold tabsize \target tabsize + \o \bold {The \c tabsize variable defines the size of a tab + character.} + + For example: + + \code + tabsize = 4 + \endcode + + will give the tab character the size of 4 spaces. + + The default value of the variable is 8, and doesn't need to + be specified. + + \row + \o \bold tagfile \target tagfile + \o \bold{The \c tagfile variable specifies the Doxygen tag file to be written + when HTML is generated.} + \row + \o \bold version \target version + \o \bold {The \c version variable specifies the version number of the + documented software.} + + For example: + + \code + version = 4.0.1 + \endcode + + When a version number is specified (using the \tt{\l + version} or \tt {\l versionsym} variables in a \c .qdocconf + file), it is accessible through the corresponding \\version + command for use in the documentation. + + \warning The \\version command's functionality is not + fully implemented; currently it only works within raw HTML + code. + + See also \l versionsym. + + \row + \o \bold versionsym \target versionsym + \o \bold {The \c versionsym variable specifies a C++ + preprocessor symbol that defines the version number + of the documented software.} + + For example in \l qt.qdocconf: + + \code + versionsym = QT_VERSION_STR + \endcode + + QT_VERSION_STR is defined in qglobal.h as follows + + \code + #define QT_VERSION_STR "4.0.1" + \endcode + + When a version number is specified (using the \tt{\l + version} or \tt {\l versionsym} variables in a \c .qdocconf + file), it is accessible through the corresponding \\version + command for use in the documentation. + + \warning The \\version command's functionality is not fully + implemented; currently it only works within raw HTML code. + + See also \l {version}{\\version}. + + \endtable +*/ + +/*! + \page 22-creating-help-project-files.html + \previouspage General Variables + \contentspage QDoc Manual - Table of Contents + \nextpage C++ Specific Variables + + \title Creating Help Project Files + + \section1 Overview + + Starting with Qt 4.4, Qt Assistant uses a different system for managing + Qt documentation that requires QDoc to generate inventories of files in a + format that is similar to the old style DCF format, but with additional + features. + + Instead of hard-coding information about the documentation sets for Qt, + QDoc allows configuration variables to be used to specify which pages are + to be used in each documentation set it generates. These are specified as + subvariables of the \c qch variable with each set declared using a unique + identifier as a subvariable. + + For example, the configuration file for the Qt documentation defines a + \c Qt documentation set by specifying information about the set as + subvariables with the \c{qhp.Qt} prefix: + + \code + qhp.Qt.file = qt.qhp + qhp.Qt.namespace = com.trolltech.qt.440 + qhp.Qt.virtualFolder = qdoc + qhp.Qt.indexTitle = Qt Reference Documentation + qhp.Qt.indexRoot = + qhp.Qt.extraFiles = classic.css images/qt-logo.png + qhp.Qt.filterAttributes = qt 4.4.0 qtrefdoc + qhp.Qt.customFilters.Qt.name = Qt 4.4.0 + qhp.Qt.customFilters.Qt.filterAttributes = qt 4.4.0 + qhp.Qt.subprojects = classes overviews examples + qhp.Qt.subprojects.classes.title = Classes + qhp.Qt.subprojects.classes.indexTitle = Qt's Classes + qhp.Qt.subprojects.classes.selectors = class + qhp.Qt.subprojects.overviews.title = Overviews + qhp.Qt.subprojects.overviews.indexTitle = All Overviews and HOWTOs + qhp.Qt.subprojects.overviews.selectors = fake:page,group,module + qhp.Qt.subprojects.examples.title = Tutorials and Examples + qhp.Qt.subprojects.examples.indexTitle = Qt Examples + qhp.Qt.subprojects.examples.selectors = fake:example + \endcode +*/ + +/*! + \page 23-qdoc-configuration-cppvariables.html + \previouspage Creating Help Project Files + \contentspage QDoc Manual - Table of Contents + \nextpage HTML Specific Variables + + \title C++ Specific Variables + + The C++ specific configuration variables are provided to avoid + erroneous documentation due to non-standard C++ constructs. + + \section1 Alphabetical List + + \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoredirectives} + {Cpp.ignoredirectives}, + \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoretoken} + {Cpp.ignoretokens} + + \section1 Variable Descriptions + + \table + + \header + \o Variable + \o Description + + \row + \o \bold Cpp.ignoredirectives \target Cpp.ignoredirectives + \o \bold {The \c Cpp.ignoredirectives variable makes QDoc ignore + the specified non-standard constructs, within C++ source code.} + + If not specified by the \tt {\l Cpp.ignoretokens} or \tt + {\l Cpp.ignoredirectives} variables, non-standard + constructs (typically macros) can result in erroneous + documentation. + + In \l qt.qdocconf: + + \code + Cpp.ignoredirectives = Q_DECLARE_INTERFACE \ + Q_DECLARE_OPERATORS_FOR_FLAGS \ + Q_DECLARE_PRIVATE \ + Q_DECLARE_PUBLIC \ + Q_DISABLE_COPY \ + Q_DUMMY_COMPARISON_OPERATOR \ + Q_ENUMS \ + Q_FLAGS \ + Q_INTERFACES \ + __attribute__ + \endcode + + makes sure that when processing the code below, for + example, QDoc will simply ignore the 'Q_ENUMS' and + 'Q_FLAGS' expressions: + + \code + class Q_CORE_EXPORT Qt { + Q_OBJECT + Q_ENUMS(Orientation TextFormat BackgroundMode + DateFormat ScrollBarPolicy FocusPolicy + ContextMenuPolicy CaseSensitivity + LayoutDirection ArrowType) + Q_ENUMS(ToolButtonStyle) + Q_FLAGS(Alignment) + Q_FLAGS(Orientations) + Q_FLAGS(DockWidgetAreas) + + public: + ... + }; + \endcode + + The Q_OBJECT macro, however, is an exception: QDoc + recognizes this particular non-standard construct, so there + is no need specifying it using the \tt {\l + Cpp.ignoredirectives} variable. + + Regarding the Q_CORE_EXPORT macro; see the documentation of + the \tt {\l Cpp.ignoretokens} variable. + + See also \l Cpp.ignoretokens. + + \row + \o \bold Cpp.ignoretokens \target Cpp.ignoretokens + \o \bold {The \c Cpp.ignoretokens variable makes QDoc ignore + the specified non-standard constructs, within C++ source code.} + + If not specified by the \tt {\l Cpp.ignoretokens} or \tt + {\l Cpp.ignoredirectives} variables, non-standard + constructs (typically macros) can result in erroneous + documentation. + + In \l qt.qdocconf: + + \code + Cpp.ignoretokens = QAXFACTORY_EXPORT \ + QM_EXPORT_CANVAS \ + ... + Q_COMPAT_EXPORT \ + Q_CORE_EXPORT \ + Q_EXPLICIT \ + Q_EXPORT \ + ... + Q_TYPENAME \ + Q_XML_EXPORT + \endcode + + makes sure that when processing the code below, for + example, QDoc will simply ignore the 'Q_CORE_EXPORT' + expression: + + \code + class Q_CORE_EXPORT Qt { + Q_OBJECT + Q_ENUMS(Orientation TextFormat BackgroundMode + DateFormat ScrollBarPolicy FocusPolicy + ContextMenuPolicy CaseSensitivity + LayoutDirection ArrowType) + Q_ENUMS(ToolButtonStyle) + Q_FLAGS(Alignment) + Q_FLAGS(Orientations) + Q_FLAGS(DockWidgetAreas) + + public: + ... + }; + \endcode + + Regarding the Q_OBJECT, Q_ENUMS and Q_FLAGS macros; see the + documentation of the \tt {\l Cpp.ignoredirectives} + variable. + + See also \l Cpp.ignoredirectives. + + \endtable +*/ + + +/*! + \page 24-qdoc-configuration-htmlvariables.html + \previouspage C++ Specific Variables + \contentspage QDoc Manual - Table of Contents + \nextpage Supporting Derived Projects + + \title HTML Specific Variables + + The HTML specific configuration variables define the generated + documentation's style, or define the contents of the + documentation's footer or postheader. The format of the variable + values are raw HTML. + + \section1 Alphabetical List + + \l {24-qdoc-configuration-htmlvariables.html#HTML.footer}{HTML.footer}, + \l {24-qdoc-configuration-htmlvariables.html#HTML.postheader} + {HTML.postheader}, + \l {24-qdoc-configuration-htmlvariables.html#HTML.style}{HTML.style}, + \l {24-qdoc-configuration-htmlvariables.html#HTML.stylesheets}{HTML.stylesheets} + + + \section1 Variable Descriptions + + \table + + \header + \o Variable + \o Description + + \row + \o \bold HTML.footer \target HTML.footer + \o \bold {The \c HTML.footer variable defines the content + of the generated HTML documentation's footer.} + + The footer is rendered at the bottom of the generated + documentation page. + + The variable's value is given as raw HTML code enclosed by + quotation marks. Note that if the value spans several + lines, each line needs to be enclosed by quotation marks. + + For example in \l qt.qdocconf: + + \code + HTML.footer = "<p /><address><hr /><div align=\"center\">\n" \ + ... + "</tr></table></div></address>" + \endcode + + The complete variable entry in \l qt.qdocconf provides the + standard footer of the \l + {http://qt.nokia.com/doc/4.0/index.html}{Qt Reference + Documentation}. + + \row + \o \bold HTML.postheader \target HTML.postheader + \o \bold {The \c HTML.postheader variable defines the content + of the generated HTML documentation's postheader.} + + The header is rendered at the top of the generated + documentation page. + + The variable's value is given as raw HTML enclosed by + quotation marks. Note that if the value spans several + lines, each line needs to be enclosed by quotation marks. + + For example in \l qt.qdocconf: + + \code + HTML.postheader = "<table border=\"0\"..." \ + ... + "<img src=\"images/trolltech-logo.png\" \ + "align=\"right\" width=\"203\" height=\"32\""\ + "border=\"0\" />" \ + "</td></tr>" \ + "</table>" + \endcode + + The complete variable entry in \l qt.qdocconf provides the + standard header of the \l + {http://qt.nokia.com/doc/4.0/index.html}{Qt Reference + Documentation}. + + \row + \o \bold HTML.style \target HTML.style + \o \bold {The HTML.style variable defines the style for + the generated HTML documentation.} + + The variable's value is given as raw HTML enclosed by + quotation marks. Note that if the value spans several + lines, each line needs to be enclosed by quotation marks. + + For example in \l qt.qdocconf: + + \code + HTML.style = "h3.fn,span.fn" \ + "{ margin-left: 1cm; text-indent: -1cm; }\n" \ + "a:link { color: #004faf; text-decoration: none }\n" \ + "a:visited" \ + "{ color: #672967; text-decoration: none }\n" \ + "td.postheader { font-family: sans-serif }\n" \ + "tr.address { font-family: sans-serif }\n" \ + "body { background: #ffffff; color: black; }" + \endcode + + provides the HTML style for the \l + {http://qt.nokia.com/doc/4.0/index.html}{Qt Reference + Documentation}. + + \row + \o \bold HTML.stylesheets \target HTML.stylesheets + \o \bold {The HTML.stylesheets variable defines a list of stylesheets + to use for the generated HTML documentation.} + + Using separate stylesheets for the documentation makes it easier to + customize and experiment with the style used once the contents has + been generated. Typically, it is only necessary to define a single + stylesheet for any set of documentation; for example: + + \code + HTML.stylesheets = classic.css + \endcode + + QDoc expects to find stylesheets in the directory containing the + \l qt.qdocconf file, and it will copy those specified to the output + directory alongside the HTML pages. + \endtable +*/ + +/*! + \page 25-qdoc-configuration-derivedprojects.html + \previouspage HTML Specific Variables + \contentspage QDoc Manual - Table of Contents + \nextpage QDoc Compatibility + + \title Supporting Derived Projects + + \tableofcontents + + Some particular configuration variables allow you to use QDoc to + support Qt-based projects; i.e to make projects, such as Qt Solutions, + contain references to the online Qt documentation. This + means that QDoc will be able to create links to the class reference + documentation, without any explicit linking command. + + \section1 The Configuration Variables + + \section2 Alphabetical List + + \l{25-qdoc-configuration-derivedprojects.html#description}{description}, + \l{25-qdoc-configuration-derivedprojects.html#indexes}{indexes}, + \l{25-qdoc-configuration-derivedprojects.html#project}{project}, + \l{25-qdoc-configuration-derivedprojects.html#url}{url} + + \section2 Variable Descriptions + + \table + \header + \o Variable + \o Description + \row + \o \bold description \target description + \o \bold {The description variable holds a short description of + the associated project.} + + See also \l project. + + \row + \o \bold indexes \target indexes + \o \bold {The \c indexes variable lists the index files + that will be used to generate references.} + + For example. to make a derived Qt project contain links to + the Qt Reference documentation, you need to specify the + associated index file: + + \code + indexes = $QTDIR/doc/html/qt.index + \endcode + + See also \l project and \l url. + + \row + \o \bold project \target project + \o \bold {The \c project variable provides a name for the project + associated with the \c .qdocconf file.} + + The project's name is used to form a file name for the + associated project's \i index file. For example: + + \code + project = QtMotif + \endcode + + This will cause an index file called \c qtmotif.index to be + created. + + See also \l description and \l indexes. + \row + \o \bold url \target url + \o \bold {The \c url variable holds the base URL for the + reference documentation associated with the current project.} + + The URL is stored in the generated index file for the + project. When we use the index on its own, QDoc will use + this as the base URL when constructing links to classes, + functions, and other things listed in the index. + + For example: + + \code + project = Qt + description = Qt Reference Documentation + url = http://qt.nokia.com/doc/4.0 + + ... + \endcode + + This makes sure that whenever \c qt.index is used to generate + references to for example Qt classes, the base URL is + \c http://qt.nokia.com/doc/4.0. + + See also \l indexes. + + \endtable + + \target howto + \section1 How to Support Derived Projects + + This feature makes use of the comprehensive indexes generated by + QDoc when it creates the Qt reference documentation. + + For example, \l qt.qdocconf (the configuration file for Qt) + contains the following variable definitions: + + \code + project = Qt + description = Qt Reference Documentation + url = http://qt.nokia.com/doc/4.0 + + ... + \endcode + + The \l project variable name is used to form a file name for the + index file; in this case the \c qt.index file is created. The \l + url is stored in the index file. Later, when we use the index on + its own, QDoc will use this as the base URL when constructing + links to classes, functions, and other things listed in the index. + + In a mini-project, you can use an index file by defining an \l + indexes configuration variable in your \c .qdocconf file. + + For example, you can create a \c qtmotif.qdocconf file to help you + check the QtMotif documentation (which is part of Qt Solutions): + + \code + include($QTDIR/tools/qdoc3/test/compat.qdocconf) + + project = QtMotif + description = QtMotif Class Documentation + url = http://www.trolltech.com/products/solutions/catalog/4/Migration/qtmotifextension + + indexes = $QTDIR/doc/html/qt.index + + outputdir = html + + headerdirs = src + sourcedirs = src \ + examples + sources.fileextensions = "*.cpp *.qdoc *.doc" + + exampledirs = examples + \endcode + + The code above requires that you run QDoc from the directory that + contains this file. You need to include the compat.qdocconf + file for compatibility reasons; this is further explained in the + \l {QDoc Compatibility} section. + + \bold {To resolve the actual links to Qt classes, the + mini-project's \c .qdocconf file needs to assign a value to the \l + indexes variable; \c $QTDIR/doc/html/qt.index makes sure that you + always use the updated index file for the Qt documentation.} + + The only disadvantages with this approach are the extra file that + QDoc has to generate and the time it takes to do so. Reading the + index back again later isn't instantaneous either, but it's + quicker than processing all the Qt classes each time you need to + write a new document. +*/ + +/*! + \page 26-qdoc-commands-compatibility.html + \previouspage Supporting Derived Projects + \contentspage QDoc Manual - Table of Contents + \nextpage QDoc Commands - Alphabetical List + + \title QDoc Compatibility + + \tableofcontents + + \section1 General Description + + \target reason + + QDoc is a tool that constantly evolves to suit our needs, for that + reason there are some compatibility issues in the transition + between old and new practices. + + To make the transition as smooth and rapid as possible, the + general idea is to adopt the new commands and usage in new + documentation. While waiting for the occurrences of the old + practices to be eliminated from the old parts of the + documentation, you can map the new commands and usage to the old + ones using a compat.qdocconf file. + + A compat.qdocconf file is a separate \c .qdocconf file which you + can include in your main configuration file. It typically contains + the mapping between old and new commands using the \l alias and \l + {22-qdoc-configuration-generalvariables.html#macro}{macro} + configuration variables. + + \section1 Qt Compatibility + + In Qt's documentation there still exist occurrences of old + commands, and the Qt \l {qt.qdocconf}{configuration file} needs to + include the compat.qdocconf file tailored for Qt. For more + detailed information about the commands creating compatibility + issues, see the \l {Command Comments}{command comments}. + + \section2 Qt's current compat.qdocconf file + + \quotefile files/compat.qdocconf + + \section2 Command Comments + + \table + \header + \o New Command + \o Old Command + \o Description + + \row + \o \\i \target i-versus-e + \o \\e + \o Earlier we + used the \\i command to indicate a list or table item, and + the \\e command for rendering in italic. Now we want the + \\i command to render in italic discarding the + \\e command name. + + \bold {We still need to use the \\e command to render in + italic in new documentation for \l {reason}{compatibility + reasons}}. + + \row + \o \\include \target include-versus-input + \o \\input + \o The \\include command was previously used to quote the + complete contents of a source file, now we want to use the + command to include separate documentation. + That is the functionality of the old \\input command + which name we want to discard. + + \bold {We still need to use the \\input command to include + plain text in new documentation for \l + {reason}{compatibility reasons}}. + + \row + \o \\quotefile \target quotefile-versus-include + \o \\include + \o Earlier, we have used the \\quotefile command to + quote from file, i.e. quote parts from file, and the + \\include command to quote the entire file. Since we now want + \\include to include separate documentation, we change the use of + \\quotefile to quote a complete source file. + + \bold {We still need to use the \\include command to quote + the entire contents of a source file in new documentation + for \l {reason}{compatibility reasons}}. + + \row + \o \\quotefromfile \target quotefromfile-versus-quotefile + \o \\quotefile + \o Earlier, we have used the \\quotefile command to + quote from file, i.e. quote parts from file. Since we now want + that command to quote an entire file, we introduce the new + \\quotefromfile command to quote from file. + + \bold {Use \l {quotefromfile}{\\quotefromfile} to quote + parts from a source file in new documentation}. + + \row + \o \\o \target o-versus-i + \o \\i + \o Earlier we used the \\i command to indicate list items + and table items. Since we now want the \\i command to render + in italic instead, we introduce the new \\o command for + this purpose. + + \bold {Use \l {o}{\\o} to indicate list and table items in + new documentation}. + + \row + \o \\quotation \target quotation-versus-quote + \o \\quote + \o These commands are equivalent, and represent a simple name + change. + + \bold {Use \l {quotation}{\\quotation} in new + documentation}. + + \row + \o \\image \target image-versus-img + \o \\img + \o These commands are equivalent, and represent a simple name + change. + + \bold {Use \l {image}{\\image} in new documentation}. + + \endtable +*/ + +/*! + \page 27-qdoc-commmands-alphabetical.html + \previouspage QDoc Compatibility + \contentspage QDoc Manual - Table of Contents + + \title QDoc Commands - Alphabetical List + + \list + + \o \l {04-qdoc-commands-textformatting.html#a}{\\a} + \o \l {11-qdoc-commands-documentcontents.html#abstract}{\\abstract} + \o \l {06-qdoc-commands-verbatimcode.html#badcode}{\\badcode} + \o \l {04-qdoc-commands-textformatting.html#bold}{\\bold} + \o \l {11-qdoc-commands-documentcontents.html#brief}{\\brief} + \o \l {04-qdoc-commands-textformatting.html#c}{\\c} + \o \l {09-qdoc-commands-graphic.html#caption}{\\caption} + \o \l {05-qdoc-commands-documentstructuring.html#chapter}{\\chapter} + \o \l {13-qdoc-commands-topical.html#class}{\\class} + \o \l {06-qdoc-commands-verbatimcode.html#code}{\\code} + \o \l {07-0-qdoc-commands-quoting.html#codeline}{\\codeline}, + \o \l {16-qdoc-commands-status.html#compat}{\\compat} + \o \l {15-qdoc-commands-navigation.html#contentspage}{\\contentspage} + \o \l {07-0-qdoc-commands-quoting.html#dots}{\\dots} + \o \l {12-0-qdoc-commands-miscellaneous.html#else}{\\else} + \o \l {12-0-qdoc-commands-miscellaneous.html#endif}{\\endif} + \o \l {13-qdoc-commands-topical.html#enum}{\\enum} + \o \l {13-qdoc-commands-topical.html#example-command}{\\example} + \o \l {12-0-qdoc-commands-miscellaneous.html#expire}{\\expire} + \o \l {13-qdoc-commands-topical.html#externalpage}{\\externalpage} + \o \l {13-qdoc-commands-topical.html#fn}{\\fn} + \o \l {11-qdoc-commands-documentcontents.html#footnote}{\\footnote} + \o \l {12-0-qdoc-commands-miscellaneous.html#generatelist}{\\generatelist} + \o \l {13-qdoc-commands-topical.html#group}{\\group} + \o \l {10-qdoc-commands-container.html#header}{\\header} + \o \l {13-qdoc-commands-topical.html#headerfile}{\\headerfile} + \o \l {04-qdoc-commands-textformatting.html#i}{\\i} + \o \l {12-0-qdoc-commands-miscellaneous.html#if}{\\if} + \o \l {09-qdoc-commands-graphic.html#image}{\\image} + \o \l {12-0-qdoc-commands-miscellaneous.html#include}{\\include} + \o \l {15-qdoc-commands-navigation.html#indexpage}{\\indexpage} + \o \l {19-qdoc-commands-grouping.html#ingroup}{\\ingroup} + \o \l {19-qdoc-commands-grouping.html#inmodule}{\\inmodule} + \o \l {09-qdoc-commands-graphic.html#inlineimage}{\\inlineimage} + \o \l {16-qdoc-commands-status.html#internal}{\\internal} + \o \l {08-qdoc-commands-linking.html#keyword}{\\keyword} + \o \l {08-qdoc-commands-linking.html#l}{\\l} + \o \l {11-qdoc-commands-documentcontents.html#legalese}{\\legalese} + \o \l {10-qdoc-commands-container.html#list}{\\list} + \o \l {13-qdoc-commands-topical.html#macro}{\\macro} + \o \l {19-qdoc-commands-grouping.html#mainclass}{\\mainclass} + \o \l {12-0-qdoc-commands-miscellaneous.html#meta}{\\meta} + \o \l {13-qdoc-commands-topical.html#module}{\\module} + \o \l {13-qdoc-commands-topical.html#namespace}{\\namespace} + \o \l {15-qdoc-commands-navigation.html#nextpage}{\\nextpage} + \o \l {06-qdoc-commands-verbatimcode.html#newcode}{\\newcode} + \o \l {17-qdoc-commands-thread.html#nonreentrant}{\\nonreentrant} + \o \l {10-qdoc-commands-container.html#o}{\\o} + \o \l {16-qdoc-commands-status.html#obsolete}{\\obsolete} + \o \l {06-qdoc-commands-verbatimcode.html#oldcode}{\\oldcode} + \o \l {12-0-qdoc-commands-miscellaneous.html#omit}{\\omit} + \o \l {10-qdoc-commands-container.html#omitvalue}{\\omitvalue} + \o \l {18-qdoc-commands-relating.html#overload}{\\overload} + \o \l {13-qdoc-commands-topical.html#page}{\\page} + \o \l {05-qdoc-commands-documentstructuring.html#part}{\\part} + \o \l {16-qdoc-commands-status.html#preliminary}{\\preliminary} + \o \l {15-qdoc-commands-navigation.html#previouspage}{\\previouspage} + \o \l {07-0-qdoc-commands-quoting.html#printline}{\\printline} + \o \l {07-0-qdoc-commands-quoting.html#printto}{\\printto} + \o \l {07-0-qdoc-commands-quoting.html#printuntil}{\\printuntil} + \o \l {13-qdoc-commands-topical.html#property}{\\property} + \o \l {11-qdoc-commands-documentcontents.html#quotation}{\\quotation} + \o \l {07-0-qdoc-commands-quoting.html#quotefile}{\\quotefile} + \o \l {07-0-qdoc-commands-quoting.html#quotefromfile}{\\quotefromfile} + \o \l {12-0-qdoc-commands-miscellaneous.html#raw}{\\raw} + \o \l {17-qdoc-commands-thread.html#reentrant}{\\reentrant} + \o \l {18-qdoc-commands-relating.html#reimp}{\\reimp} + \o \l {18-qdoc-commands-relating.html#relates}{\\relates} + \o \l {10-qdoc-commands-container.html#row}{\\row} + \o \l {08-qdoc-commands-linking.html#sa}{\\sa} + \o \l {05-qdoc-commands-documentstructuring.html#sectionOne}{\\section1} + \o \l {05-qdoc-commands-documentstructuring.html#sectionTwo}{\\section2} + \o \l {05-qdoc-commands-documentstructuring.html#sectionThree}{\\section3} + \o \l {05-qdoc-commands-documentstructuring.html#sectionFour}{\\section4} + \o \l {13-qdoc-commands-topical.html#service}{\\service} + \o \l {16-qdoc-commands-status.html#since}{\\since} + \o \l {07-0-qdoc-commands-quoting.html#skipline}{\\skipline} + \o \l {07-0-qdoc-commands-quoting.html#skipto}{\\skipto} + \o \l {07-0-qdoc-commands-quoting.html#skipuntil}{\\skipuntil} + \o \l {07-0-qdoc-commands-quoting.html#snippet}{\\snippet}, + \o \l {15-qdoc-commands-navigation.html#startpage}{\\startpage} + \o \l {04-qdoc-commands-textformatting.html#sub}{\\sub} + \o \l {20-qdoc-commands-title.html#subtitle}{\\subtitle} + \o \l {04-qdoc-commands-textformatting.html#sup}{\\sup} + \o \l {10-qdoc-commands-container.html#table}{\\table} + \o \l {11-qdoc-commands-documentcontents.html#tableofcontents} + {\\tableofcontents} + \o \l {08-qdoc-commands-linking.html#target}{\\target} + \o \l {17-qdoc-commands-thread.html#threadsafe}{\\threadsafe} + \o \l {20-qdoc-commands-title.html#title}{\\title} + \o \l {04-qdoc-commands-textformatting.html#tt}{\\tt} + \o \l {13-qdoc-commands-topical.html#typedef}{\\typedef} + \o \l {04-qdoc-commands-textformatting.html#underline}{\\underline} + \o \l {13-qdoc-commands-topical.html#variable}{\\variable} + \o \l {10-qdoc-commands-container.html#value}{\\value} + \o \l {11-qdoc-commands-documentcontents.html#warning}{\\warning} + \endlist +*/ + +/*! + \externalpage http://qt.nokia.com/about + \title About Qt +*/ diff --git a/tools/qdoc3/doc/qdoc-manual.qdocconf b/tools/qdoc3/doc/qdoc-manual.qdocconf new file mode 100644 index 0000000..26fd09c --- /dev/null +++ b/tools/qdoc3/doc/qdoc-manual.qdocconf @@ -0,0 +1,49 @@ +project = QDoc +description = QDoc3 Manual + +indexes = $QTDIR/doc/html/qt.index + +outputdir = html + +sources = qdoc-manual.qdoc +sourcedirs = $PWD + +exampledirs += $PWD \ + $QTDIR/examples + +imagedirs += images + +extraimages.HTML = qt-logo + +HTML.stylesheets = classic.css + +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; }" + +HTML.postheader = "<table border=\"0\" cellpadding=\"0\" cellspacing=\"5\" width=\"100%\">\n" \ + "<tr>\n" \ + "<td align=\"left\" valign=\"top\" width=\"32\">" \ + "<a href=\"http://qt.nokia.com/\"><img src=\"images/qt-logo.png\" align=\"left\" border=\"0\" /></a>" \ + "</td>\n" \ + "<td class=\"postheader\" valign=\"center\">" \ + "<a href=\"01-qdoc-manual.html\">" \ + "<font color=\"#004faf\">Home: QDoc Manual</font></a> ·" \ + "<a href=\"http://qt.nokia.com/doc/4.7\">" \ + "<font color=\"#004faf\"> Qt Reference Documentation</font></a>" \ + "</td>\n" \ + "</tr></table>" + +HTML.footer = "<p /><address><hr /><div align=\"center\">\n" \ + "<table width=\"100%\" cellspacing=\"0\" border=\"0\"><tr class=\"address\">\n" \ + "<td width=\"40%\" align=\"left\">Copyright © 2010 Nokia Corporation and/or its subsidiary(-ies)</td>\n" \ + "<td width=\"20%\" align=\"center\"><a href=\"trademarks.html\">Trademarks</a></td>\n" \ + "<td width=\"40%\" align=\"right\"><div align=\"right\">Qt \\version</div></td>\n" \ + "</tr></table></div></address>" + +spurious += "Missing '\\}'" +spurious += "Cannot use .*" +spurious += "Unexpected .*" diff --git a/tools/qdoc3/htmlgenerator.cpp b/tools/qdoc3/htmlgenerator.cpp index 15386f1..e341a03 100644 --- a/tools/qdoc3/htmlgenerator.cpp +++ b/tools/qdoc3/htmlgenerator.cpp @@ -54,10 +54,12 @@ #include <qdebug.h> #include <qlist.h> #include <qiterator.h> +#include <qtextcodec.h> QT_BEGIN_NAMESPACE #define COMMAND_VERSION Doc::alias("version") +int HtmlGenerator::id = 0; QString HtmlGenerator::sinceTitles[] = { @@ -266,6 +268,15 @@ void HtmlGenerator::initializeGenerator(const Config &config) projectUrl = config.getString(CONFIG_URL); + outputEncoding = config.getString(CONFIG_OUTPUTENCODING); + if (outputEncoding.isEmpty()) + outputEncoding = QLatin1String("ISO-8859-1"); + outputCodec = QTextCodec::codecForName(outputEncoding.toLocal8Bit()); + + naturalLanguage = config.getString(CONFIG_NATURALLANGUAGE); + if (naturalLanguage.isEmpty()) + naturalLanguage = QLatin1String("en"); + QSet<QString> editionNames = config.subVars(CONFIG_EDITION); QSet<QString>::ConstIterator edition = editionNames.begin(); while (edition != editionNames.end()) { @@ -389,9 +400,9 @@ void HtmlGenerator::generateTree(const Tree *tree, CodeMarker *marker) "qmake Manual", dcfQmakeRoot); - generateIndex(project.toLower().simplified().replace(" ", "-"), - projectUrl, - projectDescription); + QString fileBase = project.toLower().simplified().replace(" ", "-"); + generateIndex(fileBase, projectUrl, projectDescription); + generatePageIndex(outputDir() + "/" + fileBase + ".pageindex", marker); helpProjectWriter->generate(myTree); } @@ -431,11 +442,11 @@ int HtmlGenerator::generateAtom(const Atom *atom, endLink(); } else { - out() << protect(atom->string()); + out() << protectEnc(atom->string()); } } else { - out() << protect(atom->string()); + out() << protectEnc(atom->string()); } break; case Atom::BaseName: @@ -483,7 +494,7 @@ int HtmlGenerator::generateAtom(const Atom *atom, case Atom::C: out() << formattingLeftMap()[ATOM_FORMATTING_TELETYPE]; if (inLink) { - out() << protect(plainCode(atom->string())); + out() << protectEnc(plainCode(atom->string())); } else { out() << highlightedCode(atom->string(), marker, relative); @@ -516,7 +527,7 @@ int HtmlGenerator::generateAtom(const Atom *atom, // fallthrough case Atom::CodeBad: out() << "<pre><font color=\"#404040\">" - << trimmedTrailing(protect(plainCode(indent(codeIndent,atom->string())))) + << trimmedTrailing(protectEnc(plainCode(indent(codeIndent,atom->string())))) << "</font></pre>\n"; break; case Atom::FootnoteLeft: @@ -768,7 +779,7 @@ int HtmlGenerator::generateAtom(const Atom *atom, out() << "<a name=\"" << Doc::canonicalTitle((*s).name) << "\"></a>\n"; - out() << "<h3>" << protect((*s).name) << "</h3>\n"; + out() << "<h3>" << protectEnc((*s).name) << "</h3>\n"; if (idx == Class) generateCompactList(0, marker, ncmap.value(), QString("Q")); else if (idx == MemberFunction) { @@ -792,7 +803,7 @@ int HtmlGenerator::generateAtom(const Atom *atom, << linkForNode(pmap.key(), 0) << "\">"; QStringList pieces = fullName(pmap.key(), 0, marker).split("::"); - out() << protect(pieces.last()); + out() << protectEnc(pieces.last()); out() << "</a>" << ":</p>\n"; generateSection(nlist, 0, marker, CodeMarker::Summary); @@ -820,12 +831,12 @@ int HtmlGenerator::generateAtom(const Atom *atom, out() << "<p align=\"center\">"; if (fileName.isEmpty()) { out() << "<font color=\"red\">[Missing image " - << protect(atom->string()) << "]</font>"; + << protectEnc(atom->string()) << "]</font>"; } else { - out() << "<img src=\"" << protect(fileName) << "\""; + out() << "<img src=\"" << protectEnc(fileName) << "\""; if (!text.isEmpty()) - out() << " alt=\"" << protect(text) << "\""; + out() << " alt=\"" << protectEnc(text) << "\""; out() << " />"; helpProjectWriter->addExtraFile(fileName); } @@ -923,7 +934,7 @@ int HtmlGenerator::generateAtom(const Atom *atom, // ### Trenton out() << "<tr><td valign=\"top\"><tt>" - << protect(plainCode(marker->markedUpEnumValue(atom->next()->string(), + << protectEnc(plainCode(marker->markedUpEnumValue(atom->next()->string(), relative))) << "</tt></td><td align=\"center\" valign=\"top\">"; @@ -936,7 +947,7 @@ int HtmlGenerator::generateAtom(const Atom *atom, if (itemValue.isEmpty()) out() << "?"; else - out() << "<tt>" << protect(itemValue) << "</tt>"; + out() << "<tt>" << protectEnc(itemValue) << "</tt>"; skipAhead = 1; } @@ -1052,7 +1063,7 @@ int HtmlGenerator::generateAtom(const Atom *atom, generateLink(atom, relative, marker); } else { - out() << protect(atom->string()); + out() << protectEnc(atom->string()); } break; case Atom::TableLeft: @@ -1166,7 +1177,7 @@ int HtmlGenerator::generateAtom(const Atom *atom, out() << "<font color=\"red\"><b><Missing HTML></b></font>"; break; case Atom::UnknownCommand: - out() << "<font color=\"red\"><b><code>\\" << protect(atom->string()) + out() << "<font color=\"red\"><b><code>\\" << protectEnc(atom->string()) << "</code></b></font>"; break; #ifdef QDOC_QML @@ -1295,7 +1306,7 @@ void HtmlGenerator::generateClassLikeNode(const InnerNode *inner, out() << "<a name=\"" << registerRef((*s).name.toLower()) << "\"></a>\n"; - out() << "<h2>" << protect((*s).name) << "</h2>\n"; + out() << "<h2>" << protectEnc((*s).name) << "</h2>\n"; generateSection(s->members, inner, marker, CodeMarker::Summary); } if (!s->reimpMembers.isEmpty()) { @@ -1304,7 +1315,7 @@ void HtmlGenerator::generateClassLikeNode(const InnerNode *inner, out() << "<a name=\"" << registerRef(name.toLower()) << "\"></a>\n"; - out() << "<h2>" << protect(name) << "</h2>\n"; + out() << "<h2>" << protectEnc(name) << "</h2>\n"; generateSection(s->reimpMembers, inner, marker, CodeMarker::Summary); } @@ -1343,7 +1354,7 @@ void HtmlGenerator::generateClassLikeNode(const InnerNode *inner, s = sections.begin(); while (s != sections.end()) { out() << "<hr />\n"; - out() << "<h2>" << protect((*s).name) << "</h2>\n"; + out() << "<h2>" << protectEnc((*s).name) << "</h2>\n"; NodeList::ConstIterator m = (*s).members.begin(); while (m != (*s).members.end()) { @@ -1518,7 +1529,7 @@ void HtmlGenerator::generateFakeNode(const FakeNode *fake, CodeMarker *marker) s = sections.begin(); while (s != sections.end()) { out() << "<a name=\"" << registerRef((*s).name) << "\"></a>\n"; - out() << "<h2>" << protect((*s).name) << "</h2>\n"; + out() << "<h2>" << protectEnc((*s).name) << "</h2>\n"; generateQmlSummary(*s,fake,marker); ++s; } @@ -1534,7 +1545,7 @@ void HtmlGenerator::generateFakeNode(const FakeNode *fake, CodeMarker *marker) sections = marker->qmlSections(qml_cn,CodeMarker::Detailed); s = sections.begin(); while (s != sections.end()) { - out() << "<h2>" << protect((*s).name) << "</h2>\n"; + out() << "<h2>" << protectEnc((*s).name) << "</h2>\n"; NodeList::ConstIterator m = (*s).members.begin(); while (m != (*s).members.end()) { generateDetailedQmlMember(*m, fake, marker); @@ -1554,7 +1565,7 @@ void HtmlGenerator::generateFakeNode(const FakeNode *fake, CodeMarker *marker) s = sections.begin(); while (s != sections.end()) { out() << "<a name=\"" << registerRef((*s).name) << "\"></a>\n"; - out() << "<h2>" << protect((*s).name) << "</h2>\n"; + out() << "<h2>" << protectEnc((*s).name) << "</h2>\n"; generateSectionList(*s, fake, marker, CodeMarker::Summary); ++s; } @@ -1583,7 +1594,7 @@ void HtmlGenerator::generateFakeNode(const FakeNode *fake, CodeMarker *marker) s = sections.begin(); while (s != sections.end()) { out() << "<hr />\n"; - out() << "<h2>" << protect((*s).name) << "</h2>\n"; + out() << "<h2>" << protectEnc((*s).name) << "</h2>\n"; NodeList::ConstIterator m = (*s).members.begin(); while (m != (*s).members.end()) { @@ -1619,7 +1630,7 @@ void HtmlGenerator::generateFakeNode(const FakeNode *fake, CodeMarker *marker) } } -QString HtmlGenerator::fileExtension(const Node * /* node */) +QString HtmlGenerator::fileExtension(const Node * /* node */) const { return "html"; } @@ -1629,11 +1640,11 @@ void HtmlGenerator::generateHeader(const QString& title, CodeMarker *marker, bool mainPage) { - out() << "<?xml version=\"1.0\" encoding=\"iso-8859-1\"?>\n"; + out() << QString("<?xml version=\"1.0\" encoding=\"%1\"?>\n").arg(outputEncoding); out() << "<!DOCTYPE html\n" - " PUBLIC \"-//W3C//DTD XHTML 1.0 Strict//EN\" \"DTD/xhtml1-strict.dtd\">\n" - "<html xmlns=\"http://www.w3.org/1999/xhtml\" xml:lang=\"en\" lang=\"en\">\n"; + " PUBLIC \"-//W3C//DTD XHTML 1.0 Strict//EN\" \"DTD/xhtml1-strict.dtd\">\n"; + out() << QString("<html xmlns=\"http://www.w3.org/1999/xhtml\" xml:lang=\"%1\" lang=\"%1\">\n").arg(naturalLanguage); QString shortVersion; if ((project != "Qtopia") && (project != "Qt Extended")) { @@ -1653,7 +1664,9 @@ void HtmlGenerator::generateHeader(const QString& title, } out() << "<head>\n" - " <title>" << shortVersion << protect(title) << "</title>\n"; + " <title>" << shortVersion << protectEnc(title) << "</title>\n"; + out() << QString("<meta http-equiv=\"Content-type\" content=\"text/html; charset=%1\" />").arg(outputEncoding); + if (!style.isEmpty()) out() << " <style type=\"text/css\">" << style << "</style>\n"; @@ -1662,8 +1675,8 @@ void HtmlGenerator::generateHeader(const QString& title, QMapIterator<QString, QString> i(metaMap); while (i.hasNext()) { i.next(); - out() << " <meta name=\"" << protect(i.key()) << "\" contents=\"" - << protect(i.value()) << "\" />\n"; + out() << " <meta name=\"" << protectEnc(i.key()) << "\" contents=\"" + << protectEnc(i.value()) << "\" />\n"; } } @@ -1687,9 +1700,9 @@ void HtmlGenerator::generateHeader(const QString& title, navigationLinks += "[Previous: <a href=\"" + anchorPair.first + "\">"; if (linkPair.first == linkPair.second && !anchorPair.second.isEmpty()) - navigationLinks += protect(anchorPair.second); + navigationLinks += protectEnc(anchorPair.second); else - navigationLinks += protect(linkPair.second); + navigationLinks += protectEnc(linkPair.second); navigationLinks += "</a>]\n"; } if (node->links().contains(Node::ContentsLink)) { @@ -1705,9 +1718,9 @@ void HtmlGenerator::generateHeader(const QString& title, navigationLinks += "[<a href=\"" + anchorPair.first + "\">"; if (linkPair.first == linkPair.second && !anchorPair.second.isEmpty()) - navigationLinks += protect(anchorPair.second); + navigationLinks += protectEnc(anchorPair.second); else - navigationLinks += protect(linkPair.second); + navigationLinks += protectEnc(linkPair.second); navigationLinks += "</a>]\n"; } if (node->links().contains(Node::NextLink)) { @@ -1723,9 +1736,9 @@ void HtmlGenerator::generateHeader(const QString& title, navigationLinks += "[Next: <a href=\"" + anchorPair.first + "\">"; if (linkPair.first == linkPair.second && !anchorPair.second.isEmpty()) - navigationLinks += protect(anchorPair.second); + navigationLinks += protectEnc(anchorPair.second); else - navigationLinks += protect(linkPair.second); + navigationLinks += protectEnc(linkPair.second); navigationLinks += "</a>]\n"; } if (node->links().contains(Node::IndexLink)) { @@ -1776,7 +1789,7 @@ void HtmlGenerator::generateTitle(const QString& title, const Node *relative, CodeMarker *marker) { - out() << "<h1 class=\"title\">" << protect(title); + out() << "<h1 class=\"title\">" << protectEnc(title); if (!subTitle.isEmpty()) { out() << "<br />"; if (subTitleSize == SmallSubTitle) @@ -2014,18 +2027,18 @@ QString HtmlGenerator::generateLowStatusMemberFile(const InnerNode *inner, out() << "<p><ul><li><a href=\"" << linkForNode(inner, 0) << "\">" - << protect(inner->name()) + << protectEnc(inner->name()) << " class reference</a></li></ul></p>\n"; for (i = 0; i < sections.size(); ++i) { - out() << "<h2>" << protect(sections.at(i).name) << "</h2>\n"; + out() << "<h2>" << protectEnc(sections.at(i).name) << "</h2>\n"; generateSectionList(sections.at(i), inner, marker, CodeMarker::Summary); } sections = marker->sections(inner, CodeMarker::Detailed, status); for (i = 0; i < sections.size(); ++i) { out() << "<hr />\n"; - out() << "<h2>" << protect(sections.at(i).name) << "</h2>\n"; + out() << "<h2>" << protectEnc(sections.at(i).name) << "</h2>\n"; NodeList::ConstIterator m = sections.at(i).members.begin(); while (m != sections.at(i).members.end()) { @@ -2118,7 +2131,7 @@ void HtmlGenerator::generateAnnotatedList(const Node *relative, } else { out() << "<td>"; - out() << protect(node->doc().briefText().toString()); + out() << protectEnc(node->doc().briefText().toString()); out() << "</td>"; } out() << "</tr>\n"; @@ -2320,7 +2333,7 @@ void HtmlGenerator::generateCompactList(const Node *relative, << linkForNode(it.value(), relative) << "\">"; QStringList pieces = fullName(it.value(), relative, marker).split("::"); - out() << protect(pieces.last()); + out() << protectEnc(pieces.last()); out() << "</a>"; if (pieces.size() > 1) { out() << " ("; @@ -2362,7 +2375,7 @@ void HtmlGenerator::generateFunctionIndex(const Node *relative, #else out() << "<p>"; #endif - out() << protect(f.key()) << ":"; + out() << protectEnc(f.key()) << ":"; currentLetter = f.key()[0].unicode(); while (islower(currentLetter) && currentLetter >= nextLetter) { @@ -2416,7 +2429,7 @@ void HtmlGenerator::generateLegaleseList(const Node *relative, QString marked = marker->markedUpSynopsis(node, relative, style); QRegExp templateTag("(<[^@>]*>)"); if (marked.indexOf(templateTag) != -1) { - QString contents = protect(marked.mid(templateTag.pos(1), + QString contents = protectEnc(marked.mid(templateTag.pos(1), templateTag.cap(1).length())); marked.replace(templateTag.pos(1), templateTag.cap(1).length(), contents); @@ -2455,7 +2468,7 @@ void HtmlGenerator::generateQmlItem(const Node *node, QString marked = marker->markedUpQmlItem(node,summary); QRegExp templateTag("(<[^@>]*>)"); if (marked.indexOf(templateTag) != -1) { - QString contents = protect(marked.mid(templateTag.pos(1), + QString contents = protectEnc(marked.mid(templateTag.pos(1), templateTag.cap(1).length())); marked.replace(templateTag.pos(1), templateTag.cap(1).length(), contents); @@ -2561,7 +2574,7 @@ void HtmlGenerator::generateOverviewList(const Node *relative, CodeMarker * /* m const FakeNode *groupNode = groupTitlesMap[groupTitle]; out() << QString("<h3><a href=\"%1\">%2</a></h3>\n").arg( linkForNode(groupNode, relative)).arg( - protect(groupNode->fullTitle())); + protectEnc(groupNode->fullTitle())); if (fakeNodeMap[groupNode].count() == 0) continue; @@ -2573,7 +2586,7 @@ void HtmlGenerator::generateOverviewList(const Node *relative, CodeMarker * /* m if (title.startsWith("The ")) title.remove(0, 4); out() << "<li><a href=\"" << linkForNode(fakeNode, relative) << "\">" - << protect(title) << "</a></li>\n"; + << protectEnc(title) << "</a></li>\n"; } out() << "</ul>\n"; } @@ -2587,7 +2600,7 @@ void HtmlGenerator::generateOverviewList(const Node *relative, CodeMarker * /* m if (title.startsWith("The ")) title.remove(0, 4); out() << "<li><a href=\"" << linkForNode(fakeNode, relative) << "\">" - << protect(title) << "</a></li>\n"; + << protectEnc(title) << "</a></li>\n"; } out() << "</ul>\n"; } @@ -2750,7 +2763,7 @@ void HtmlGenerator::generateSectionInheritedList(const Section& section, } out() << " inherited from <a href=\"" << fileName((*p).first) << "#" << HtmlGenerator::cleanRef(section.name.toLower()) << "\">" - << protect(marker->plainFullName((*p).first, relative)) + << protectEnc(marker->plainFullName((*p).first, relative)) << "</a></li>\n"; ++p; } @@ -2765,7 +2778,7 @@ void HtmlGenerator::generateSynopsis(const Node *node, QString marked = marker->markedUpSynopsis(node, relative, style); QRegExp templateTag("(<[^@>]*>)"); if (marked.indexOf(templateTag) != -1) { - QString contents = protect(marked.mid(templateTag.pos(1), + QString contents = protectEnc(marked.mid(templateTag.pos(1), templateTag.cap(1).length())); marked.replace(templateTag.pos(1), templateTag.cap(1).length(), contents); @@ -3034,7 +3047,7 @@ void HtmlGenerator::generateSectionInheritedList(const Section& section, } out() << " inherited from <a href=\"" << fileName((*p).first) << "#" << HtmlGenerator::cleanRef(section.name.toLower()) << "\">" - << protect(marker->plainFullName((*p).first, relative)) + << protectEnc(marker->plainFullName((*p).first, relative)) << "</a></li>\n"; ++p; } @@ -3048,7 +3061,7 @@ void HtmlGenerator::generateSynopsis(const Node *node, QString marked = marker->markedUpSynopsis(node, relative, style); QRegExp templateTag("(<[^@>]*>)"); if (marked.indexOf(templateTag) != -1) { - QString contents = protect(marked.mid(templateTag.pos(1), + QString contents = protectEnc(marked.mid(templateTag.pos(1), templateTag.cap(1).length())); marked.replace(templateTag.pos(1), templateTag.cap(1).length(), contents); @@ -3246,7 +3259,7 @@ void HtmlGenerator::generateLink(const Atom* atom, if (funcLeftParen.indexIn(atom->string()) != -1 && marker->recognizeLanguage("Cpp")) { // hack for C++: move () outside of link int k = funcLeftParen.pos(1); - out() << protect(atom->string().left(k)); + out() << protectEnc(atom->string().left(k)); if (link.isEmpty()) { if (showBrokenLinks) out() << "</i>"; @@ -3254,7 +3267,7 @@ void HtmlGenerator::generateLink(const Atom* atom, out() << "</a>"; } inLink = false; - out() << protect(atom->string().mid(k)); + out() << protectEnc(atom->string().mid(k)); } else if (marker->recognizeLanguage("Java")) { // hack for Java: remove () and use <tt> when appropriate bool func = atom->string().endsWith("()"); @@ -3262,13 +3275,13 @@ void HtmlGenerator::generateLink(const Atom* atom, if (tt) out() << "<tt>"; if (func) { - out() << protect(atom->string().left(atom->string().length() - 2)); + out() << protectEnc(atom->string().left(atom->string().length() - 2)); } else { - out() << protect(atom->string()); + out() << protectEnc(atom->string()); } out() << "</tt>"; } else { - out() << protect(atom->string()); + out() << protectEnc(atom->string()); } } @@ -3342,7 +3355,12 @@ QString HtmlGenerator::registerRef(const QString& ref) return clean; } -QString HtmlGenerator::protect(const QString& string) +QString HtmlGenerator::protectEnc(const QString &string) +{ + return protect(string, outputEncoding); +} + +QString HtmlGenerator::protect(const QString &string, const QString &outputEncoding) { #define APPEND(x) \ if (html.isEmpty()) { \ @@ -3365,7 +3383,7 @@ QString HtmlGenerator::protect(const QString& string) APPEND(">"); } else if (ch == QLatin1Char('"')) { APPEND("""); - } else if (ch.unicode() > 0x007F + } else if ((outputEncoding == "ISO-8859-1" && ch.unicode() > 0x007F) || (ch == QLatin1Char('*') && i + 1 < n && string.at(i) == QLatin1Char('/')) || (ch == QLatin1Char('.') && i > 2 && string.at(i - 2) == QLatin1Char('.'))) { // we escape '*/' and the last dot in 'e.g.' and 'i.e.' for the Javadoc generator @@ -3495,7 +3513,7 @@ QString HtmlGenerator::refForNode(const Node *node) ref = node->name() + "-var"; break; case Node::Target: - return protect(node->name()); + return protectEnc(node->name()); } return registerRef(ref); } @@ -3569,7 +3587,7 @@ void HtmlGenerator::generateFullName(const Node *apparentNode, } } out() << "\">"; - out() << protect(fullName(apparentNode, relative, marker)); + out() << protectEnc(fullName(apparentNode, relative, marker)); out() << "</a>"; } @@ -3630,12 +3648,12 @@ void HtmlGenerator::generateDetailedMember(const Node *node, else if (node->type() == Node::Enum) { const EnumNode *enume = static_cast<const EnumNode *>(node); if (enume->flagsType()) { - out() << "<p>The " << protect(enume->flagsType()->name()) + out() << "<p>The " << protectEnc(enume->flagsType()->name()) << " type is a typedef for " << "<a href=\"qflags.html\">QFlags</a><" - << protect(enume->name()) + << protectEnc(enume->name()) << ">. It stores an OR combination of " - << protect(enume->name()) + << protectEnc(enume->name()) << " values.</p>\n"; } } @@ -4352,4 +4370,128 @@ void HtmlGenerator::generateInstantiatedBy(const ClassNode* cn, } } +/*! + Generate the <page> element for the given \a node using the \a writer. + Return true if a <page> element was written; otherwise return false. + */ +bool HtmlGenerator::generatePageElement(QXmlStreamWriter& writer, + const Node* node, + CodeMarker* marker) const +{ + if (node->pageType() == Node::NoPageType) + return false; + if (node->name().isEmpty()) + return true; + if (node->access() == Node::Private) + return false; + if (!node->isInnerNode()) + return false; + + QString title; + QString rawTitle; + QString fullTitle; + const InnerNode* inner = static_cast<const InnerNode*>(node); + + writer.writeStartElement("page"); + QXmlStreamAttributes attributes; + QString t; + t.setNum(id++); + switch (node->type()) { + case Node::Fake: + { + const FakeNode* fake = static_cast<const FakeNode*>(node); + title = fake->fullTitle(); + break; + } + case Node::Class: + { + title = node->name() + " Class Reference"; + break; + } + case Node::Namespace: + { + rawTitle = marker->plainName(inner); + fullTitle = marker->plainFullName(inner); + title = rawTitle + " Namespace Reference"; + break; + } + default: + title = node->name(); + break; + } + writer.writeAttribute("id",t); + writer.writeStartElement("pageWords"); + writer.writeCharacters(title); + if (!inner->pageKeywords().isEmpty()) { + const QStringList& w = inner->pageKeywords(); + for (int i = 0; i < w.size(); ++i) { + writer.writeCharacters(" "); + writer.writeCharacters(w.at(i).toLocal8Bit().constData()); + } + } + writer.writeEndElement(); + writer.writeStartElement("pageTitle"); + writer.writeCharacters(title); + writer.writeEndElement(); + writer.writeStartElement("pageUrl"); + writer.writeCharacters(PageGenerator::fileName(node)); + writer.writeEndElement(); + writer.writeStartElement("pageType"); + switch (node->pageType()) { + case Node::ApiPage: + writer.writeCharacters("APIPage"); + break; + case Node::ArticlePage: + writer.writeCharacters("Article"); + break; + case Node::ExamplePage: + writer.writeCharacters("Example"); + break; + default: + break; + } + writer.writeEndElement(); + writer.writeEndElement(); + return true; +} + +/*! + Traverse the tree recursively and generate the <keyword> + elements. + */ +void HtmlGenerator::generatePageElements(QXmlStreamWriter& writer, const Node* node, CodeMarker* marker) const +{ + if (generatePageElement(writer, node, marker)) { + + if (node->isInnerNode()) { + const InnerNode *inner = static_cast<const InnerNode *>(node); + + // Recurse to write an element for this child node and all its children. + foreach (const Node *child, inner->childNodes()) + generatePageElements(writer, child, marker); + } + } +} + +/*! + Outputs the file containing the index used for searching the html docs. + */ +void HtmlGenerator::generatePageIndex(const QString& fileName, CodeMarker* marker) const +{ + QFile file(fileName); + if (!file.open(QFile::WriteOnly | QFile::Text)) + return ; + + QXmlStreamWriter writer(&file); + writer.setAutoFormatting(true); + writer.writeStartDocument(); + writer.writeStartElement("qtPageIndex"); + + generatePageElements(writer, myTree->root(), marker); + + writer.writeEndElement(); // qtPageIndex + writer.writeEndDocument(); + file.close(); +} + #endif diff --git a/tools/qdoc3/htmlgenerator.h b/tools/qdoc3/htmlgenerator.h index 19a7c78..369d6c3 100644 --- a/tools/qdoc3/htmlgenerator.h +++ b/tools/qdoc3/htmlgenerator.h @@ -50,6 +50,7 @@ #include <qmap.h> #include <qregexp.h> +#include <QXmlStreamWriter> #include "codemarker.h" #include "config.h" @@ -104,7 +105,8 @@ class HtmlGenerator : public PageGenerator virtual QString format(); virtual void generateTree(const Tree *tree, CodeMarker *marker); - static QString protect(const QString& string); + QString protectEnc(const QString &string); + static QString protect(const QString &string, const QString &encoding = "ISO-8859-1"); static QString cleanRef(const QString& ref); static QString sinceTitle(int i) { return sinceTitles[i]; } @@ -115,7 +117,7 @@ class HtmlGenerator : public PageGenerator CodeMarker *marker); virtual void generateClassLikeNode(const InnerNode *inner, CodeMarker *marker); virtual void generateFakeNode(const FakeNode *fake, CodeMarker *marker); - virtual QString fileExtension(const Node *node); + virtual QString fileExtension(const Node *node) const; virtual QString refForNode(const Node *node); virtual QString linkForNode(const Node *node, const Node *relative); virtual QString refForAtom(Atom *atom, const Node *node); @@ -261,6 +263,14 @@ class HtmlGenerator : public PageGenerator const Node *relative, CodeMarker *marker); void endLink(); + bool generatePageElement(QXmlStreamWriter& writer, + const Node* node, + CodeMarker* marker) const; + void generatePageElements(QXmlStreamWriter& writer, + const Node* node, + CodeMarker* marker) const; + void generatePageIndex(const QString& fileName, + CodeMarker* marker) const; #if 0 NavigationBar currentNavigationBar; @@ -315,6 +325,7 @@ class HtmlGenerator : public PageGenerator NewSinceMaps newSinceMaps; static QString sinceTitles[]; NewClassMaps newClassMaps; + static int id; }; #define HTMLGENERATOR_ADDRESS "address" diff --git a/tools/qdoc3/javadocgenerator.cpp b/tools/qdoc3/javadocgenerator.cpp index 001bd27..eb9c1c9 100644 --- a/tools/qdoc3/javadocgenerator.cpp +++ b/tools/qdoc3/javadocgenerator.cpp @@ -145,7 +145,7 @@ void JavadocGenerator::generateTree(const Tree *tree, CodeMarker *marker) HtmlGenerator::generateTree(tree, marker); } -QString JavadocGenerator::fileExtension(const Node *node) +QString JavadocGenerator::fileExtension(const Node *node) const { if (node->type() == Node::Fake) { return "html"; diff --git a/tools/qdoc3/javadocgenerator.h b/tools/qdoc3/javadocgenerator.h index 73452cf..b485502 100644 --- a/tools/qdoc3/javadocgenerator.h +++ b/tools/qdoc3/javadocgenerator.h @@ -61,7 +61,7 @@ public: QString imageFileName(const Node *relative, const QString &fileBase); protected: - QString fileExtension(const Node *node); + QString fileExtension(const Node *node) const; void startText( const Node *relative, CodeMarker *marker ); void endText( const Node *relative, CodeMarker *marker ); int generateAtom( const Atom *atom, const Node *relative, CodeMarker *marker ); diff --git a/tools/qdoc3/linguistgenerator.cpp b/tools/qdoc3/linguistgenerator.cpp index d1bd22d..702f0fb 100644 --- a/tools/qdoc3/linguistgenerator.cpp +++ b/tools/qdoc3/linguistgenerator.cpp @@ -82,14 +82,14 @@ QString LinguistGenerator::format() return "Linguist"; } -QString LinguistGenerator::fileExtension(const Node * /* node */) +QString LinguistGenerator::fileExtension(const Node * /* node */) const { return "ts"; } void LinguistGenerator::generateClassLikeNode(const InnerNode *inner, CodeMarker *marker) { - out().setCodec("utf-8"); + out().setCodec("UTF-8"); QDomDocument document("TS"); QDomElement documentElement = document.createElement("TS"); @@ -100,7 +100,7 @@ void LinguistGenerator::generateClassLikeNode(const InnerNode *inner, CodeMarker documentElement.appendChild(element); QDomProcessingInstruction process = document.createProcessingInstruction( - "xml", QString("version=\"1.0\" encoding=\"%1\"").arg("utf-8")); + "xml", QString("version=\"1.0\" encoding=\"%1\"").arg("UTF-8")); document.appendChild(process); document.appendChild(documentElement); diff --git a/tools/qdoc3/linguistgenerator.h b/tools/qdoc3/linguistgenerator.h index f7f0606..979db02 100644 --- a/tools/qdoc3/linguistgenerator.h +++ b/tools/qdoc3/linguistgenerator.h @@ -70,7 +70,7 @@ protected: virtual void generateClassLikeNode(const InnerNode *inner, CodeMarker *marker); virtual void generateFakeNode( const FakeNode *fake, CodeMarker *marker ); - virtual QString fileExtension(const Node *node); + virtual QString fileExtension(const Node *node) const; QList<QDomElement> generateIndexSections(QDomDocument &document, const Node *node, CodeMarker *marker); diff --git a/tools/qdoc3/main.cpp b/tools/qdoc3/main.cpp index 3d0106d..57823fb 100644 --- a/tools/qdoc3/main.cpp +++ b/tools/qdoc3/main.cpp @@ -337,8 +337,9 @@ static void processQdocconfFile(const QString &fileName) Generate the XML tag file, if it was requested. */ QString tagFile = config.getString(CONFIG_TAGFILE); - if (!tagFile.isEmpty()) + if (!tagFile.isEmpty()) { tree->generateTagFile(tagFile); + } tree->setVersion(""); Generator::terminate(); diff --git a/tools/qdoc3/mangenerator.cpp b/tools/qdoc3/mangenerator.cpp index c3b7780..1e85b73 100644 --- a/tools/qdoc3/mangenerator.cpp +++ b/tools/qdoc3/mangenerator.cpp @@ -187,7 +187,7 @@ void ManGenerator::generateFakeNode( const FakeNode *fake, CodeMarker *marker ) generateFooter(); } -QString ManGenerator::fileExtension(const Node * /* node */) +QString ManGenerator::fileExtension(const Node * /* node */) const { return "3qt"; } diff --git a/tools/qdoc3/mangenerator.h b/tools/qdoc3/mangenerator.h index 284517e..0fca342 100644 --- a/tools/qdoc3/mangenerator.h +++ b/tools/qdoc3/mangenerator.h @@ -63,7 +63,7 @@ protected: CodeMarker *marker ); virtual void generateClassLikeNode(const InnerNode *node, CodeMarker *marker); virtual void generateFakeNode( const FakeNode *fake, CodeMarker *marker ); - virtual QString fileExtension(const Node *node); + virtual QString fileExtension(const Node *node) const; private: void generateHeader( const QString& name ); diff --git a/tools/qdoc3/node.cpp b/tools/qdoc3/node.cpp index 9357671..ec574f8 100644 --- a/tools/qdoc3/node.cpp +++ b/tools/qdoc3/node.cpp @@ -92,8 +92,9 @@ void Node::setDoc(const Doc& doc, bool replace) Node::Node(Type type, InnerNode *parent, const QString& name) : typ(type), acc(Public), - sta(Commendable), saf(UnspecifiedSafeness), + pageTyp(NoPageType), + sta(Commendable), par(parent), rel(0), nam(name) @@ -103,6 +104,7 @@ Node::Node(Type type, InnerNode *parent, const QString& name) } /*! + Returns the node's URL. */ QString Node::url() const { @@ -110,13 +112,25 @@ QString Node::url() const } /*! + Sets the node's URL to \a url */ void Node::setUrl(const QString &url) { u = url; } +void Node::setPageType(const QString& t) +{ + if ((t == "API") || (t == "api")) + pageTyp = ApiPage; + else if (t == "article") + pageTyp = ArticlePage; + else if (t == "example") + pageTyp = ExamplePage; +} + /*! + Sets the pointer to the node that this node relates to. */ void Node::setRelates(InnerNode *pseudoParent) { @@ -401,7 +415,7 @@ void InnerNode::deleteChildren() } /*! - Returns true. + Returns true because this is an inner node. */ bool InnerNode::isInnerNode() const { @@ -455,6 +469,9 @@ const EnumNode *InnerNode::findEnumNodeForValue(const QString &enumValue) const } /*! + Returnds the sequence number of the function node \a func + in the list of overloaded functions for a class, such that + all the functions have the same name as the \a func. */ int InnerNode::overloadNumber(const FunctionNode *func) const { @@ -468,6 +485,8 @@ int InnerNode::overloadNumber(const FunctionNode *func) const } /*! + Returns the number of member functions of a class such that + the functions are all named \a funcName. */ int InnerNode::numOverloads(const QString& funcName) const { @@ -480,6 +499,8 @@ int InnerNode::numOverloads(const QString& funcName) const } /*! + Returns a node list containing all the member functions of + some class such that the functions overload the name \a funcName. */ NodeList InnerNode::overloads(const QString &funcName) const { @@ -499,6 +520,8 @@ NodeList InnerNode::overloads(const QString &funcName) const InnerNode::InnerNode(Type type, InnerNode *parent, const QString& name) : Node(type, parent, name) { + if (type == Class) + setPageType(ApiPage); } /*! @@ -682,6 +705,8 @@ bool LeafNode::isInnerNode() const } /*! + Constructs a leaf node named \a name of the specified + \a type. The new leaf node becomes a child of \a parent. */ LeafNode::LeafNode(Type type, InnerNode *parent, const QString& name) : Node(type, parent, name) @@ -693,10 +718,12 @@ LeafNode::LeafNode(Type type, InnerNode *parent, const QString& name) */ /*! + Constructs a namespace node. */ NamespaceNode::NamespaceNode(InnerNode *parent, const QString& name) : InnerNode(Namespace, parent, name) { + setPageType(ApiPage); } /*! @@ -704,11 +731,13 @@ NamespaceNode::NamespaceNode(InnerNode *parent, const QString& name) */ /*! + Constructs a class node. A class node will generate an API page. */ ClassNode::ClassNode(InnerNode *parent, const QString& name) : InnerNode(Class, parent, name) { hidden = false; + setPageType(ApiPage); } /*! @@ -765,11 +794,28 @@ void ClassNode::fixBaseClasses() /*! The type of a FakeNode is Fake, and it has a \a subtype, - which specifies the type of FakeNode. + which specifies the type of FakeNode. The page type for + the page index is set here. */ FakeNode::FakeNode(InnerNode *parent, const QString& name, SubType subtype) : InnerNode(Fake, parent, name), sub(subtype) { + switch (subtype) { + case Module: + case Page: + case Group: + setPageType(ArticlePage); + break; + case QmlClass: + case QmlBasicType: + setPageType(ApiPage); + break; + case Example: + setPageType(ExamplePage); + break; + default: + break; + } } /*! diff --git a/tools/qdoc3/node.h b/tools/qdoc3/node.h index 077aeb8..021a052 100644 --- a/tools/qdoc3/node.h +++ b/tools/qdoc3/node.h @@ -137,6 +137,13 @@ class Node AppendixLink */ }; + enum PageType { + NoPageType, + ApiPage, + ArticlePage, + ExamplePage + }; + virtual ~Node(); void setAccess(Access access) { acc = access; } @@ -150,6 +157,8 @@ class Node void setLink(LinkType linkType, const QString &link, const QString &desc); void setUrl(const QString &url); void setTemplateStuff(const QString &templateStuff) { tpl = templateStuff; } + void setPageType(PageType t) { pageTyp = t; } + void setPageType(const QString& t); virtual bool isInnerNode() const = 0; virtual bool isReimp() const { return false; } @@ -173,6 +182,8 @@ class Node ThreadSafeness inheritedThreadSafeness() const; QString since() const { return sinc; } QString templateStuff() const { return tpl; } + PageType pageType() const { return pageTyp; } + virtual void addPageKeywords(const QString& ) { } void clearRelated() { rel = 0; } @@ -186,13 +197,15 @@ class Node #ifdef Q_WS_WIN Type typ; Access acc; - Status sta; ThreadSafeness saf; + PageType pageTyp; + Status sta; #else Type typ : 4; Access acc : 2; - Status sta : 3; ThreadSafeness saf : 2; + PageType pageTyp : 4; + Status sta : 3; #endif InnerNode *par; InnerNode *rel; @@ -244,6 +257,8 @@ class InnerNode : public Node QStringList primaryKeys(); QStringList secondaryKeys(); + const QStringList& pageKeywords() const { return pageKeywds; } + virtual void addPageKeywords(const QString& t) { pageKeywds << t; } protected: InnerNode(Type type, InnerNode *parent, const QString& name); @@ -256,6 +271,7 @@ class InnerNode : public Node void removeChild(Node *child); void removeRelated(Node *pseudoChild); + QStringList pageKeywds; QStringList inc; NodeList children; NodeList enumChildren; diff --git a/tools/qdoc3/pagegenerator.cpp b/tools/qdoc3/pagegenerator.cpp index 07edcc4..2cad9ed 100644 --- a/tools/qdoc3/pagegenerator.cpp +++ b/tools/qdoc3/pagegenerator.cpp @@ -77,7 +77,7 @@ void PageGenerator::generateTree(const Tree *tree, CodeMarker *marker) generateInnerNode(tree->root(), marker); } -QString PageGenerator::fileBase(const Node *node) +QString PageGenerator::fileBase(const Node *node) const { if (node->relates()) node = node->relates(); @@ -153,7 +153,7 @@ QString PageGenerator::fileBase(const Node *node) return res; } -QString PageGenerator::fileName(const Node *node) +QString PageGenerator::fileName(const Node *node) const { if (!node->url().isEmpty()) return node->url(); @@ -177,7 +177,7 @@ void PageGenerator::beginSubPage(const Location& location, location.fatal(tr("Cannot open output file '%1'") .arg(outFile->fileName())); QTextStream *out = new QTextStream(outFile); - out->setCodec("ISO-8859-1"); + out->setCodec(outputCodec); outStreamStack.push(out); } diff --git a/tools/qdoc3/pagegenerator.h b/tools/qdoc3/pagegenerator.h index db24edd..7ab7e5e 100644 --- a/tools/qdoc3/pagegenerator.h +++ b/tools/qdoc3/pagegenerator.h @@ -54,6 +54,8 @@ QT_BEGIN_NAMESPACE +class QTextCodec; + class ClassNode; class InnerNode; class NamespaceNode; @@ -67,15 +69,19 @@ class PageGenerator : public Generator virtual void generateTree(const Tree *tree, CodeMarker *marker); protected: - virtual QString fileBase(const Node *node); - virtual QString fileExtension(const Node *node) = 0; - QString fileName(const Node *node); + virtual QString fileBase(const Node *node) const; + virtual QString fileExtension(const Node *node) const = 0; + QString fileName(const Node *node) const; QString outFileName(); void beginSubPage(const Location& location, const QString& fileName); void endSubPage(); virtual void generateInnerNode(const InnerNode *node, CodeMarker *marker); QTextStream& out(); + QString naturalLanguage; + QString outputEncoding; + QTextCodec *outputCodec; + private: QStack<QTextStream *> outStreamStack; }; diff --git a/tools/qdoc3/qdoc3.pro b/tools/qdoc3/qdoc3.pro index 441bf39..7705692 100644 --- a/tools/qdoc3/qdoc3.pro +++ b/tools/qdoc3/qdoc3.pro @@ -105,5 +105,26 @@ SOURCES += apigenerator.cpp \ webxmlgenerator.cpp \ yyindent.cpp +### Documentation for qdoc3 ### + +win32:!win32-g++ { + unixstyle = false +} else :win32-g++:isEmpty(QMAKE_SH) { + unixstyle = false +} else { + unixstyle = true +} + +$$unixstyle { + QDOC = cd $$PWD/doc && $$[QT_INSTALL_BINS]/qdoc3 +} else { + QDOC = cd $$PWD/doc && $$[QT_INSTALL_BINS]/qdoc3.exe + QDOC = $$replace(QDOC, "/", "\\") +} + +docs.commands = $$QDOC qdoc-manual.qdocconf + +QMAKE_EXTRA_TARGETS += docs + target.path = $$[QT_INSTALL_BINS] INSTALLS += target diff --git a/tools/qdoc3/qsakernelparser.cpp b/tools/qdoc3/qsakernelparser.cpp index 9320a17..8f12eda 100644 --- a/tools/qdoc3/qsakernelparser.cpp +++ b/tools/qdoc3/qsakernelparser.cpp @@ -70,8 +70,8 @@ void QsaKernelParser::parseSourceFile( const Location& location, const QString& filePath, Tree * /* tree */ ) { - FILE *in = fopen( QFile::encodeName(filePath), "r" ); - if ( in == 0 ) { + QFile in(filePath); + if (!in.open(QIODevice::ReadOnly)) { location.error( tr("Cannot open QSA kernel file '%1'").arg(filePath) ); return; } @@ -171,7 +171,7 @@ void QsaKernelParser::parseSourceFile( const Location& location, readToken(); } } - fclose( in ); + in.close(); } void QsaKernelParser::doneParsingSourceFiles( Tree * /* tree */ ) diff --git a/tools/qdoc3/qscodeparser.cpp b/tools/qdoc3/qscodeparser.cpp index 8b3bc98..3b8bc1a 100644 --- a/tools/qdoc3/qscodeparser.cpp +++ b/tools/qdoc3/qscodeparser.cpp @@ -151,8 +151,8 @@ void QsCodeParser::parseHeaderFile(const Location& location, { qsTre = tree; - FILE *in = fopen(QFile::encodeName(filePath), "r"); - if (in == 0) { + QFile in(filePath); + if (!in.open(QIODevice::ReadOnly)) { location.error(tr("Cannot open Qt Script class list '%1'") .arg(filePath)); return; @@ -175,7 +175,7 @@ void QsCodeParser::parseHeaderFile(const Location& location, } tok = fileTokenizer.getToken(); } - fclose(in); + in.close(); } void QsCodeParser::parseSourceFile(const Location& location, diff --git a/tools/qdoc3/test/qt-api-only_zh_CN.qdocconf b/tools/qdoc3/test/qt-api-only_zh_CN.qdocconf new file mode 100644 index 0000000..c722ee8 --- /dev/null +++ b/tools/qdoc3/test/qt-api-only_zh_CN.qdocconf @@ -0,0 +1,30 @@ +include(qt-build-docs_zh_CN.qdocconf) + +# Ensures that the generated index contains a URL that can be used by the +# tools documentation (assistant.qdocconf, designer.qdocconf, linguist.qdocconf, +# qmake.qdocconf). + +url = ./ + +# Ensures that the documentation for the tools is not included in the generated +# .qhp file. + +qhp.Qt.excluded += $QT_SOURCE_TREE/doc/src/development/assistant-manual.qdoc \ + $QT_SOURCE_TREE/doc/src/examples/simpletextviewer.qdoc \ + $QT_SOURCE_TREE/doc/src/development/designer-manual.qdoc \ + $QT_SOURCE_TREE/doc/src/examples/calculatorbuilder.qdoc \ + $QT_SOURCE_TREE/doc/src/examples/calculatorform.qdoc \ + $QT_SOURCE_TREE/doc/src/examples/customwidgetplugin.qdoc \ + $QT_SOURCE_TREE/doc/src/examples/taskmenuextension.qdoc \ + $QT_SOURCE_TREE/doc/src/examples/containerextension.qdoc \ + $QT_SOURCE_TREE/doc/src/examples/worldtimeclockbuilder.qdoc \ + $QT_SOURCE_TREE/doc/src/examples/worldtimeclockplugin.qdoc \ + $QT_SOURCE_TREE/doc/src/internationalization/linguist-manual.qdoc \ + $QT_SOURCE_TREE/doc/src/examples/hellotr.qdoc \ + $QT_SOURCE_TREE/doc/src/examples/arrowpad.qdoc \ + $QT_SOURCE_TREE/doc/src/examples/trollprint.qdoc \ + $QT_SOURCE_TREE/doc/src/development/qmake-manual.qdoc + +outputdir = $QT_BUILD_TREE/doc-build/html-qt_zh_CN +tagfile = $QT_BUILD_TREE/doc-build/html-qt_zh_CN/qt.tags +base = file:$QT_BUILD_TREE/doc-build/html-qt_zh_CN diff --git a/tools/qdoc3/test/qt-build-docs.qdocconf b/tools/qdoc3/test/qt-build-docs.qdocconf index 6cc27b6..555e826 100644 --- a/tools/qdoc3/test/qt-build-docs.qdocconf +++ b/tools/qdoc3/test/qt-build-docs.qdocconf @@ -8,9 +8,13 @@ project = Qt description = Qt Reference Documentation url = http://qt.nokia.com/doc/4.7 -edition.Desktop.modules = QtCore QtDBus QtGui QtNetwork QtOpenGL QtScript QtScriptTools QtSql QtSvg \ - QtWebKit QtXml QtXmlPatterns Qt3Support QtHelp \ - QtDesigner QtAssistant QAxContainer Phonon \ +sourceencoding = UTF-8 +outputencoding = UTF-8 +naturallanguage = en_US + +edition.Desktop.modules = QtCore QtDBus QtGui QtNetwork QtOpenGL QtScript \ + QtScriptTools QtSql QtSvg QtWebKit QtXml QtXmlPatterns \ + Qt3Support QtHelp QtDesigner QtAssistant QAxContainer Phonon \ QAxServer QtUiTools QtTest QtDBus edition.DesktopLight.modules = QtCore QtDBus QtGui Qt3SupportLight QtTest @@ -90,11 +94,13 @@ excludedirs = $QT_SOURCE_TREE/src/3rdparty/clucene \ $QT_SOURCE_TREE/src/3rdparty/webkit/WebCore \ $QT_SOURCE_TREE/src/3rdparty/wintab \ $QT_SOURCE_TREE/src/3rdparty/zlib \ - $QT_SOURCE_TREE/doc/src/snippets \ $QT_SOURCE_TREE/src/3rdparty/phonon/gstreamer \ $QT_SOURCE_TREE/src/3rdparty/phonon/ds9 \ $QT_SOURCE_TREE/src/3rdparty/phonon/qt7 \ - $QT_SOURCE_TREE/src/3rdparty/phonon/waveout + $QT_SOURCE_TREE/src/3rdparty/phonon/mmf \ + $QT_SOURCE_TREE/src/3rdparty/phonon/waveout \ + $QT_SOURCE_TREE/doc/src/snippets \ + $QT_SOURCE_TREE/doc/src/zh_CN sources.fileextensions = "*.cpp *.qdoc *.mm" examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml" diff --git a/tools/qdoc3/test/qt-build-docs_zh_CN.qdocconf b/tools/qdoc3/test/qt-build-docs_zh_CN.qdocconf new file mode 100644 index 0000000..18b72a1 --- /dev/null +++ b/tools/qdoc3/test/qt-build-docs_zh_CN.qdocconf @@ -0,0 +1,92 @@ +include(compat.qdocconf) +include(macros.qdocconf) +include(qt-cpp-ignore.qdocconf) +include(qt-html-templates_zh_CN.qdocconf) +include(qt-defines.qdocconf) + +project = Qt +description = Qt Reference Documentation +url = http://qt.nokia.com/doc/zh_CN/4.7 + +sourceencoding = UTF-8 +outputencoding = UTF-8 +naturallanguage = zh-Hans + +indexes = $QT_BUILD_TREE/doc-build/html-qt/qt.index + +edition.Desktop.modules = QtCore QtDBus QtGui QtNetwork QtOpenGL QtScript \ + QtScriptTools QtSql QtSvg QtWebKit QtXml QtXmlPatterns \ + Qt3Support QtHelp QtDesigner QtAssistant QAxContainer Phonon \ + QAxServer QtUiTools QtTest QtDBus + +edition.DesktopLight.modules = QtCore QtDBus QtGui Qt3SupportLight QtTest +edition.DesktopLight.groups = -graphicsview-api + +qhp.projects = Qt + +qhp.Qt.file = qt.qhp +qhp.Qt.namespace = com.trolltech.qt.470 +qhp.Qt.virtualFolder = qdoc +qhp.Qt.title = 教程 +qhp.Qt.indexTitle = 教程 +qhp.Qt.selectors = fake:example + +qhp.Qt.filterAttributes = qt 4.7.0 qtrefdoc zh_CN +qhp.Qt.customFilters.Qt.name = Qt 4.7.0 +qhp.Qt.customFilters.Qt.filterAttributes = qt 4.7.0 + +# Files not referenced in any qdoc file (last four are needed by qtdemo) +# See also extraimages.HTML +qhp.Qt.extraFiles = classic.css \ + images/qt-logo.png \ + images/taskmenuextension-example.png \ + images/coloreditorfactoryimage.png \ + images/dynamiclayouts-example.png \ + images/stylesheet-coffee-plastique.png + +language = Cpp + +sourcedirs = $QT_SOURCE_TREE/doc/src/zh_CN + +excludedirs = $QT_SOURCE_TREE/src/3rdparty/clucene \ + $QT_SOURCE_TREE/src/3rdparty/des \ + $QT_SOURCE_TREE/src/3rdparty/freetype \ + $QT_SOURCE_TREE/src/3rdparty/harfbuzz \ + $QT_SOURCE_TREE/src/3rdparty/kdebase \ + $QT_SOURCE_TREE/src/3rdparty/libjpeg \ + $QT_SOURCE_TREE/src/3rdparty/libmng \ + $QT_SOURCE_TREE/src/3rdparty/libpng \ + $QT_SOURCE_TREE/src/3rdparty/libtiff \ + $QT_SOURCE_TREE/src/3rdparty/md4 \ + $QT_SOURCE_TREE/src/3rdparty/md5 \ + $QT_SOURCE_TREE/src/3rdparty/patches \ + $QT_SOURCE_TREE/src/3rdparty/sha1 \ + $QT_SOURCE_TREE/src/3rdparty/sqlite \ + $QT_SOURCE_TREE/src/3rdparty/webkit/JavaScriptCore \ + $QT_SOURCE_TREE/src/3rdparty/webkit/WebCore \ + $QT_SOURCE_TREE/src/3rdparty/wintab \ + $QT_SOURCE_TREE/src/3rdparty/zlib \ + $QT_SOURCE_TREE/doc/src/snippets \ + $QT_SOURCE_TREE/src/3rdparty/phonon/gstreamer \ + $QT_SOURCE_TREE/src/3rdparty/phonon/ds9 \ + $QT_SOURCE_TREE/src/3rdparty/phonon/qt7 \ + $QT_SOURCE_TREE/src/3rdparty/phonon/mmf \ + $QT_SOURCE_TREE/src/3rdparty/phonon/waveout + +sources.fileextensions = "*.cpp *.qdoc *.mm" +examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp" +examples.imageextensions = "*.png" + +exampledirs = $QT_SOURCE_TREE/doc/src \ + $QT_SOURCE_TREE/examples \ + $QT_SOURCE_TREE/examples/tutorials \ + $QT_SOURCE_TREE \ + $QT_SOURCE_TREE/qmake/examples \ + $QT_SOURCE_TREE/src/3rdparty/webkit/WebKit/qt/docs +imagedirs = $QT_SOURCE_TREE/doc/src/images \ + $QT_SOURCE_TREE/examples +outputdir = $QT_BUILD_TREE/doc/html_zh_CN +tagfile = $QT_BUILD_TREE/doc/html_zh_CN/qt.tags +base = file:$QT_BUILD_TREE/doc/html_zh_CN + +HTML.generatemacrefs = "true" diff --git a/tools/qdoc3/test/qt-html-templates_zh_CN.qdocconf b/tools/qdoc3/test/qt-html-templates_zh_CN.qdocconf new file mode 100644 index 0000000..5fb68cf --- /dev/null +++ b/tools/qdoc3/test/qt-html-templates_zh_CN.qdocconf @@ -0,0 +1,25 @@ +HTML.stylesheets = classic.css +HTML.postheader = "<table border=\"0\" cellpadding=\"0\" cellspacing=\"0\" width=\"100%\">\n" \ + "<tr>\n" \ + "<td align=\"left\" valign=\"top\" width=\"32\">" \ + "<a href=\"http://qt.nokia.com/\"><img src=\"images/qt-logo.png\" align=\"left\" border=\"0\" /></a>" \ + "</td>\n" \ + "<td width=\"1\"> </td>" \ + "<td class=\"postheader\" valign=\"center\">" \ + "<a href=\"http://qt.nokia.com/doc/4.7/index.html\">" \ + "<font color=\"#004faf\">主页</font></a> ·" \ + " <a href=\"http://qt.nokia.com/doc/4.7/classes.html\">" \ + "<font color=\"#004faf\">所有类</font></a> ·" \ + " <a href=\"http://qt.nokia.com/doc/4.7/functions.html\">" \ + "<font color=\"#004faf\">所有函数</font></a> ·" \ + " <a href=\"http://qt.nokia.com/doc/4.7/overviews.html\">" \ + "<font color=\"#004faf\">简介</font></a>" \ + "</td>" \ + "</tr></table>" + +HTML.footer = "<p /><address><hr /><div align=\"center\">\n" \ + "<table width=\"100%\" cellspacing=\"0\" border=\"0\"><tr class=\"address\">\n" \ + "<td width=\"40%\" align=\"left\">版权所有 © 2010 诺基亚公司和/或其子公司</td>\n" \ + "<td width=\"20%\" align=\"center\"><a href=\"trademarks.html\">商标</a></td>\n" \ + "<td width=\"40%\" align=\"right\"><div align=\"right\">Qt \\version</div></td>\n" \ + "</tr></table></div></address>" diff --git a/tools/qdoc3/test/qt.qdocconf b/tools/qdoc3/test/qt.qdocconf index b65ac56..f7757fb 100644 --- a/tools/qdoc3/test/qt.qdocconf +++ b/tools/qdoc3/test/qt.qdocconf @@ -10,9 +10,13 @@ version = %VERSION% description = Qt Reference Documentation url = http://qt.nokia.com/doc/4.7 +sourceencoding = UTF-8 +outputencoding = UTF-8 +naturallanguage = en_US + edition.Desktop.modules = QtCore QtDBus QtGui QtNetwork QtOpenGL QtScript \ QtScriptTools QtSql QtSvg QtWebKit QtXml QtXmlPatterns \ - Qt3Support QtHelp QtDesigner QAxContainer Phonon \ + Qt3Support QtHelp QtDesigner QtAssistant QAxContainer Phonon \ QAxServer QtUiTools QtTest QtDBus edition.DesktopLight.modules = QtCore QtDBus QtGui Qt3SupportLight QtTest edition.DesktopLight.groups = -graphicsview-api @@ -91,12 +95,13 @@ excludedirs = $QTDIR/src/3rdparty/clucene \ $QTDIR/src/3rdparty/webkit/WebCore \ $QTDIR/src/3rdparty/wintab \ $QTDIR/src/3rdparty/zlib \ - $QTDIR/doc/src/snippets \ $QTDIR/src/3rdparty/phonon/gstreamer \ $QTDIR/src/3rdparty/phonon/ds9 \ $QTDIR/src/3rdparty/phonon/qt7 \ $QTDIR/src/3rdparty/phonon/mmf \ - $QTDIR/src/3rdparty/phonon/waveout + $QTDIR/src/3rdparty/phonon/waveout \ + $QTDIR/doc/src/snippets \ + $QTDIR/doc/src/zh_CN sources.fileextensions = "*.cpp *.qdoc *.mm" examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml" diff --git a/tools/qdoc3/tokenizer.cpp b/tools/qdoc3/tokenizer.cpp index b391759..7c10de6 100644 --- a/tools/qdoc3/tokenizer.cpp +++ b/tools/qdoc3/tokenizer.cpp @@ -47,6 +47,7 @@ #include <qhash.h> #include <qregexp.h> #include <qstring.h> +#include <qtextcodec.h> #include <ctype.h> #include <string.h> @@ -97,6 +98,8 @@ static QRegExp *definedX = 0; static QRegExp *defines = 0; static QRegExp *falsehoods = 0; +static QTextCodec *sourceCodec = 0; + /* This function is a perfect hash function for the 37 keywords of C99 (with a hash table size of 512). It should perform well on our @@ -118,13 +121,10 @@ static void insertKwordIntoHash(const char *s, int number) kwordHashTable[k] = number; } -Tokenizer::Tokenizer(const Location& loc, FILE *in) +Tokenizer::Tokenizer(const Location& loc, QFile &in) { init(); - QFile file; - file.open(in, QIODevice::ReadOnly); - yyIn = file.readAll(); - file.close(); + yyIn = in.readAll(); yyPos = 0; start(loc); } @@ -483,6 +483,11 @@ void Tokenizer::initialize(const Config &config) { QString versionSym = config.getString(CONFIG_VERSIONSYM); + QString sourceEncoding = config.getString(CONFIG_SOURCEENCODING); + if (sourceEncoding.isEmpty()) + sourceEncoding = QLatin1String("ISO-8859-1"); + sourceCodec = QTextCodec::codecForName(sourceEncoding.toLocal8Bit()); + comment = new QRegExp("/(?:\\*.*\\*/|/.*\n|/[^\n]*$)"); comment->setMinimal(true); versionX = new QRegExp("$cannot possibly match^"); @@ -750,4 +755,14 @@ bool Tokenizer::isTrue(const QString &condition) return !falsehoods->exactMatch(t); } +QString Tokenizer::lexeme() const +{ + return sourceCodec->toUnicode(yyLex); +} + +QString Tokenizer::previousLexeme() const +{ + return sourceCodec->toUnicode(yyPrevLex); +} + QT_END_NAMESPACE diff --git a/tools/qdoc3/tokenizer.h b/tools/qdoc3/tokenizer.h index 519cffb..f55d2ef 100644 --- a/tools/qdoc3/tokenizer.h +++ b/tools/qdoc3/tokenizer.h @@ -46,11 +46,10 @@ #ifndef TOKENIZER_H #define TOKENIZER_H +#include <qfile.h> #include <qstack.h> #include <qstring.h> -#include <stdio.h> - #include "location.h" QT_BEGIN_NAMESPACE @@ -99,7 +98,7 @@ class Tokenizer { public: Tokenizer(const Location& loc, const QByteArray &in); - Tokenizer(const Location& loc, FILE *in); + Tokenizer(const Location& loc, QFile &file); ~Tokenizer(); @@ -108,8 +107,8 @@ class Tokenizer bool parsingFnOrMacro() const { return parsingMacro; } const Location &location() const { return yyTokLoc; } - QString previousLexeme() const { return QString(yyPrevLex); } - QString lexeme() const { return QString(yyLex); } + QString previousLexeme() const; + QString lexeme() const; QString version() const { return yyVersion; } int braceDepth() const { return yyBraceDepth; } int parenDepth() const { return yyParenDepth; } diff --git a/tools/qdoc3/webxmlgenerator.cpp b/tools/qdoc3/webxmlgenerator.cpp index a3c92ce..205bc8c 100644 --- a/tools/qdoc3/webxmlgenerator.cpp +++ b/tools/qdoc3/webxmlgenerator.cpp @@ -90,7 +90,7 @@ QString WebXMLGenerator::format() return "WebXML"; } -QString WebXMLGenerator::fileExtension(const Node * /* node */) +QString WebXMLGenerator::fileExtension(const Node * /* node */) const { return "xml"; } diff --git a/tools/qdoc3/webxmlgenerator.h b/tools/qdoc3/webxmlgenerator.h index 3145d50..cadf176 100644 --- a/tools/qdoc3/webxmlgenerator.h +++ b/tools/qdoc3/webxmlgenerator.h @@ -69,7 +69,7 @@ protected: const Node *relative, CodeMarker *marker ); virtual void generateClassLikeNode(const InnerNode *inner, CodeMarker *marker); virtual void generateFakeNode(const FakeNode *fake, CodeMarker *marker); - virtual QString fileExtension(const Node *node); + virtual QString fileExtension(const Node *node) const; virtual const Atom *addAtomElements(QXmlStreamWriter &writer, const Atom *atom, const Node *relative, CodeMarker *marker); |
