| /**************************************************************************** |
| ** |
| ** Copyright (C) 2020 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** Commercial License Usage |
| ** Licensees holding valid commercial Qt licenses may use this file in |
| ** accordance with the commercial license agreement provided with the |
| ** Software or, alternatively, in accordance with the terms contained in |
| ** a written agreement between you and The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Free Documentation License Usage |
| ** Alternatively, this file may be used under the terms of the GNU Free |
| ** Documentation License version 1.3 as published by the Free Software |
| ** Foundation and appearing in the file included in the packaging of |
| ** this file. Please review the following information to ensure |
| ** the GNU Free Documentation License version 1.3 requirements |
| ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \page 03-qdoc-commands-markup.html |
| \previouspage Naming Things |
| \nextpage Text Markup |
| |
| \title Markup Commands |
| |
| The markup commands indicate the generated documentation's visual |
| appearance and logical structure. |
| |
| \list |
| \li \l {a-command} {\\a} |
| \li \l {annotatedlist-command} {\\annotatedlist} |
| \li \l {b-command} {\\b} |
| \li \l {badcode-command} {\\badcode} |
| \li \l {b-command} {\\bold} (deprecated, use \\b) |
| \li \l {brief-command} {\\brief} |
| \li \l {c-command} {\\c} |
| \li \l {caption-command} {\\caption} |
| \li \l {code-command} {\\code} |
| \li \l {codeline-command} {\\codeline} |
| \li \l {div-command} {\\div} |
| \li \l {dots-command} {\\dots} |
| \li \l {e-command} {\\e} |
| \li \l {else-command} {\\else} |
| \li \l {endif-command} {\\endif} |
| \li \l {footnote-command} {\\footnote} |
| \li \l {generatelist-command} {\\generatelist} |
| \li \l {header-command} {\\header} |
| \li \l {e-command} {\\i} (deprecated, use \\e) |
| \li \l {if-command} {\\if} |
| \li \l {image-command} {\\image} |
| \li \l {include-command} {\\include} |
| \li \l {include-command} {\\input} |
| \li \l {inlineimage-command} {\\inlineimage} |
| \li \l {keyword-command} {\\keyword} |
| \li \l {l-command} {\\l} |
| \li \l {legalese-command} {\\legalese} |
| \li \l {li-command} {\\li} |
| \li \l {list-command} {\\list} |
| \li \l {meta-command} {\\meta} |
| \li \l {noautolist-command} {\\noautolist} |
| \li \l {newcode-command} {\\newcode} |
| \li \l {li-command} {\\o} (deprecated, use \\li) |
| \li \l {note-command} {\\note} |
| \li \l {oldcode-command} {\\oldcode} |
| \li \l {omit-command} {\\omit} |
| \li \l {printline-command} {\\printline} |
| \li \l {printto-command} {\\printto} |
| \li \l {printuntil-command} {\\printuntil} |
| \li \l {qml-command}{\\qml} |
| \li \l {quotation-command} {\\quotation} |
| \li \l {quotefile-command} {\\quotefile} |
| \li \l {quotefromfile-command} {\\quotefromfile} |
| \li \l {raw-command} {\\raw} |
| \li \l {row-command} {\\row} |
| \li \l {sa-command} {\\sa} |
| \li \l {sectionOne-command} {\\section1} |
| \li \l {sectionTwo-command} {\\section2} |
| \li \l {sectionThree-command} {\\section3} |
| \li \l {sectionFour-command} {\\section4} |
| \li \l {skipline-command} {\\skipline} |
| \li \l {skipto-command} {\\skipto} |
| \li \l {skipuntil-command} {\\skipuntil} |
| \li \l {snippet-command} {\\snippet} |
| \li \l {span-command} {\\span} |
| \li \l {sub-command} {\\sub} |
| \li \l {sup-command} {\\sup} |
| \li \l {table-command} {\\table} |
| \li \l {tableofcontents-command} {\\tableofcontents} |
| \li \l {target-command} {\\target} |
| \li \l {tt-command} {\\tt} |
| \li \l {uicontrol-command} {\\uicontrol} |
| \li \l {underline-command} {\\underline} |
| \li \l {raw-command} {\\unicode} |
| \li \l {warning-command} {\\warning} |
| \li \l {backslash-command} {\\\\} |
| \endlist |
| */ |
| |
| |
| /*! |
| \page 04-qdoc-commands-textmarkup.html |
| \previouspage Markup Commands |
| \nextpage Document Structure |
| |
| \title Text Markup |
| |
| The text formatting commands indicate how text is to be rendered. |
| |
| \target a-command |
| \section1 \\a (parameter marker) |
| |
| The \\a command tells QDoc the next word is a formal parameter name. |
| |
| A warning is emitted when a formal parameter is not documented or |
| is misspelled, so when you document a function you should mention |
| each formal parameter by name in the function description, |
| preceded by the \\a command. The parameter name is then rendered |
| in italics. |
| |
| \code |
| / *! |
| Constructs a line edit containing the text |
| \a contents. The \a parent parameter is sent |
| to the QWidget constructor. |
| * / |
| |
| QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent) |
| { |
| ... |
| } |
| |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| \b {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 formal parameter name may be enclosed between curly brackets, |
| but that isn't required. |
| |
| \target c-command |
| \section1 \\c (code font) |
| |
| The \\c command is used for rendering variable names, user-defined |
| class names, and C++ keywords (for example, \c int and \c for) in the code |
| font. |
| |
| The command renders its argument using a monospace font. For |
| example: |
| |
| \code |
| / *! |
| The \c AnalogClock class provides a clock widget with hour |
| and minute hands that is automatically updated every |
| few seconds. |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| The \c AnalogClock class provides a clock widget with hour |
| and minute hands, which are automatically updated every |
| few seconds. |
| \endquotation |
| |
| If the text to be rendered in the code font contains spaces, enclose the |
| entire text in curly brackets. |
| |
| \code |
| \c {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)} |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| \c {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)} |
| \endquotation |
| |
| The \\c command accepts the special character \c \ within its |
| argument, which renders it as a normal character. So if you want |
| to use nested commands, you must use the \l {tt-command} {teletype |
| (\\tt)} command instead. |
| |
| See also \l {tt-command} {\\tt} and \l {code-command} {\\code}. |
| |
| \target div-command |
| \section1 \\div |
| |
| The \\div and \\enddiv commands delimit a large or small block of |
| text (which may include other QDoc commands) to which special |
| formatting attributes should be applied. |
| |
| An argument must be provided in curly braces, as in the QDoc |
| comment shown below. The argument is not interpreted but is used |
| as attribute(s) of the tag that is output by QDoc. |
| |
| For example, we might want to render an inline image so that it |
| floats to the right of the current block of text: |
| |
| \code |
| / *! |
| \div {class="float-right"} |
| \inlineimage qml-column.png |
| \enddiv |
| |
| * / |
| \endcode |
| |
| If QDoc is generating HTML, it will translate these commands to: |
| |
| \code |
| <div class="float-right"><p><img src="images/qml-column.png" /></p></div> |
| \endcode |
| |
| For HTML, the attribute value \e {float-right} then will refer to |
| a clause in the style.css file, which in this case could be: |
| |
| \code |
| div.float-right |
| { |
| float: right; margin-left: 2em |
| } |
| \endcode |
| |
| \note Note that the \b {\\div} command can be nested. |
| |
| Below you can find an example taken from the index.qdoc file used to |
| generate index.html for Qt 4.7: |
| |
| \code |
| \div {class="indexbox guide"} |
| \div {class="heading"} |
| Qt Developer Guide |
| \enddiv |
| \div {class="indexboxcont indexboxbar"} |
| \div {class="section indexIcon"} \emptyspan |
| \enddiv |
| \div {class="section"} |
| Qt is a cross-platform application and UI |
| framework. Using Qt, you can write web-enabled |
| applications once and deploy them across desktop, |
| mobile and embedded operating systems without |
| rewriting the source code. |
| \enddiv |
| \div {class="section sectionlist"} |
| \list |
| \li \l{Getting Started} |
| \li \l{Installation} {Installation} |
| \li \l{how-to-learn-qt.html} {How to learn Qt} |
| \li \l{tutorials.html} {Tutorials} |
| \li \l{Qt Examples} {Examples} |
| \li \l{qt4-7-intro.html} {What's new in Qt 4.7} |
| \endlist |
| \enddiv |
| \enddiv |
| \enddiv |
| \endcode |
| |
| When all the class attribute values are defined as they are in the |
| style.css file that is used for rendering the Qt documentation, |
| the above example is rendered as: |
| |
| \div {class="indexbox guide"} |
| \div {class="heading"} |
| Qt Developer Guide |
| \enddiv |
| \div {class="indexboxcont indexboxbar"} |
| \div {class="section indexIcon"} \emptyspan |
| \enddiv |
| \div {class="section"} |
| Qt is a cross-platform application and UI |
| framework. Using Qt, you can write web-enabled |
| applications once and deploy them across desktop, |
| mobile and embedded operating systems without |
| rewriting the source code. |
| \enddiv |
| \div {class="section sectionlist"} |
| \list |
| \li Getting Started |
| \li Installation |
| \li How to learn Qt |
| \li Tutorials |
| \li Examples |
| \li What's new in Qt 4.7 |
| \endlist |
| \enddiv |
| \enddiv |
| \enddiv |
| |
| See also \l {span-command} {\\span}. |
| |
| \target span-command |
| \section1 \\span |
| |
| The \\span command applies special formatting to a small block of text. |
| |
| Two arguments must be provided, each argument in curly braces, as |
| shown in the QDoc comment below. The first argument is not |
| interpreted, but specifies the formatting attribute(s) of the tag |
| output by QDoc. The second argument is the text to be rendered with |
| the special formatting attributes. |
| |
| For example, we might want to render the first word of each |
| element in a numeric list in blue. |
| |
| \code |
| / *! |
| Global variables with complex types: |
| \list 1 |
| \li \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14 |
| \li \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15 |
| \li \span {class="variableName"} {constComplex1} in globals.cpp at line 16 |
| \li \span {class="variableName"} {constComplex2} in globals.cpp at line 17 |
| \endlist |
| * / |
| \endcode |
| |
| Class \e {variableName} refers to a clause in your style.css. |
| |
| \code |
| .variableName |
| { |
| font-family: courier; |
| color: blue |
| } |
| \endcode |
| |
| Using the \e {variableName} clause shown above, the example is rendered as: |
| |
| Global variables with complex types: |
| \list 1 |
| \li \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14 |
| \li \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15 |
| \li \span {class="variableName"} {constComplex1} in globals.cpp at line 16 |
| \li \span {class="variableName"} {constComplex2} in globals.cpp at line 17 |
| \endlist |
| |
| \note The \b span command does not cause a new paragraph to be |
| started. |
| |
| See also \l {div-command} {\\div}. |
| |
| \target tt-command |
| \section1 \\tt (teletype font) |
| |
| The \\tt command renders its argument in a monospace font. This |
| command behaves just like the \l {c-command} {\\c} command, except |
| that \\tt allows you to nest QDoc commands within the argument |
| (e.g. \l {e-command} {\\e}, \l {b-command} {\\b} and \l |
| {underline-command} {\\underline}). |
| |
| \code |
| / *! |
| After having populated the main container with |
| child widgets, \c setupUi() scans the main container's list of |
| slots for names with the form |
| \tt{on_\e{objectName}_\e{signalName}().} |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| After having populated the main container with |
| child widgets, \c setupUi() scans the main container's list of |
| slots for names with the form |
| \tt{on_\e{objectName}_\e{signalName}().} |
| \endquotation |
| |
| If the text to be rendered in the code font contains spaces, enclose the |
| entire text in curly brackets. |
| |
| \code |
| \tt {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)} |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| \tt {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)} |
| \endquotation |
| |
| See also \l {c-command} {\\c}. |
| |
| \target b-command |
| \section1 \\b |
| |
| The \\b command renders its argument in bold font. This command used |
| to be called \\bold. |
| |
| \code |
| / *! |
| This is regular text; \b {this text is |
| rendered using the \\b command}. |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| This is regular text; \b {this text is rendered using |
| the \\b command}. |
| \endquotation |
| |
| \target e-command |
| \section1 \\e (emphasis, italics) |
| |
| The \\e command renders its argument in a special font, normally italics. This |
| command used to be called \\i, which is now deprecated. |
| |
| If the argument contains spaces or other punctuation, enclose the |
| argument in curly brackets. |
| |
| \code |
| / *! |
| Here, we render \e {a few words} in italics. |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| Here, we render \e {a few words} in italics. |
| \endquotation |
| |
| If you want to use other QDoc commands within an argument that |
| contains spaces, you always need to enclose the argument in |
| 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: \e QPushButton(tr("A Brand New Button")) |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| An argument can sometimes contain whitespaces, |
| for example: \e QPushButton(tr("A Brand New Button")) |
| \endquotation |
| |
| Finally, trailing punctuation is not included in an argument [4], |
| nor is "'s" [5] |
| |
| \raw HTML |
| <table align="center" cellpadding="2" |
| cellspacing="1" border="0"> |
| <tr valign="top" bgcolor="#a2c511"> |
| <th></th> |
| <th>QDoc Syntax</th> |
| <th>Generated Documentation</th> |
| </tr> |
| |
| <tr valign="top" bgcolor="#d0d0d0"> |
| <td>1</td> |
| <td>A variation of a command button is a \e menu |
| button.</td> |
| <td>A variation of a command button is a <i>menu</i> |
| button.</td> |
| </tr> |
| |
| <tr valign="top" bgcolor="#c0c0c0"> |
| <td>2</td> |
| <td>The QPushButton widget provides a |
| \e {command button}.</td> |
| <td>The QPushButton widget provides a |
| <i>command button</i>.</td> |
| </tr> |
| |
| <tr valign="top" bgcolor="#d0d0d0"> |
| <td>3</td> |
| <td>Another class of buttons are option buttons |
| \e (see QRadioButton).</td> |
| <td>Another class of buttons are option buttons |
| <i> (see QRadioButton)</i>.</td> |
| </tr> |
| |
| <tr valign="top" bgcolor="#c0c0c0"> |
| <td>4</td> |
| <td>A push button emits the signal \e clicked().</td> |
| <td>A push button emits the signal <i>clicked</i>().</td> |
| </tr> |
| |
| <tr valign="top" bgcolor="#d0d0d0"> |
| <td>5</td> |
| <td>The \e QPushButton's checked property is |
| false by default.</td> |
| <td>The <i>QPushButton</i>'s checked property is |
| false by default.</td> |
| </tr> |
| |
| </table> |
| \endraw |
| |
| \target sub-command |
| \section1 \\sub |
| |
| The \\sub command renders its argument lower than the baseline of |
| the regular text, using a smaller font. |
| |
| \code |
| / *! |
| Definition (Range): Consider the sequence |
| {x\sub n}\sub {n > 1} . The set |
| |
| {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...} |
| |
| is called the range of the sequence. |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| Definition (Range): Consider the sequence |
| {x\sub n}\sub {n > 1} . The set |
| |
| {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...} |
| |
| is called the range of the sequence. |
| \endquotation |
| |
| If the argument contains spaces or other punctuation, enclose the |
| argument in curly brackets. |
| |
| \target sup-command |
| \section1 \\sup |
| |
| The \\sup command renders its argument higher than |
| the baseline of the regular text, using a smaller font. |
| |
| \code |
| / *! |
| The series |
| |
| 1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ... |
| |
| is called the \i {geometric series}. |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| The series |
| |
| 1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ... |
| |
| is called the \e {geometric series}. |
| \endquotation |
| |
| If the argument contains spaces or other punctuation, enclose the |
| argument in curly brackets. |
| |
| \target uicontrol-command |
| \section1 \\uicontrol |
| |
| The \\uicontrol command is used to mark content as being used for UI |
| control elements. When using HTML, the output is rendered in bold. |
| |
| \sa \\b |
| |
| \target underline-command |
| \section1 \\underline |
| |
| The \\underline command renders its argument underlined. |
| |
| \code |
| / *! |
| The \underline {F}ile menu gives the users the possibility |
| to edit an existing file, or save a new or modified |
| file, and exit the application. |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| The \underline {F}ile menu gives the users the possibility |
| to edit an existing file, or save a new or modified |
| file, and exit the application. |
| \endquotation |
| |
| If the argument contains spaces or other punctuation, enclose the |
| argument in curly brackets. |
| |
| \target backslash-command |
| \section1 \\\\ (double backslash) |
| |
| The \\\\ command expands to a double backslash. |
| |
| QDoc commands always start with a single backslash. To display a |
| single backslash in the text you need to type two backslashes. If |
| you want to display two backslashes, you need to type four. |
| |
| \code |
| / *! |
| The \\\\ command is useful if you want a |
| backslash to appear verbatim, for example, |
| writing C:\\windows\\home\\. |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| The \\\\ command is useful if you want a |
| backslash to appear verbatim, for example, |
| writing C:\\windows\\home\\. |
| \endquotation |
| |
| However, if you want your text to appear in a monospace font as |
| well, you can use the \l {c-command} {\\c} command instead, which |
| accepts and renders the backslash as any other character. For |
| example: |
| |
| \code |
| / *! |
| The \\c command is useful if you want a |
| backslash to appear verbatim, and the word |
| that contains it written in a monospace font, |
| like this: \c {C:\windows\home\}. |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| The \\c command is useful if you want a |
| backslash to appear verbatim, and the word |
| that contains it written in a monospace font, |
| like this: \c {C:\windows\home\}. |
| \endquotation |
| |
| */ |
| |
| |
| /*! |
| \page 05-qdoc-commands-documentstructure.html |
| \previouspage Text Markup |
| \nextpage Including Code Inline |
| |
| \title Document Structure |
| |
| The document structuring commands are for dividing your document |
| into sections. QDoc supports four levels of section: \c \section1, |
| \c \section2, \c \section3, and \c \section4. The section commands |
| correspond to the traditional section, subsection, etc used in |
| outlining. |
| |
| \target section-commands |
| \section1 Section commands |
| |
| 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 four levels for sections in QDoc: \c \section1, |
| \c \section2, \c \section3 and \c \section4. These correspond to the |
| traditional section, subsection, subsubsection and subsubsubsection. |
| |
| There is a strict ordering of the section units: |
| |
| \code |
| section1 |
| | |
| section2 |
| | |
| section3 |
| | |
| section4 |
| \endcode |
| |
| When sections are used, the first section command should be \c section1. |
| |
| |
| \code |
| / *! |
| \section1 Basic Qt |
| |
| This is the first section. |
| |
| |
| \section2 Getting Started |
| |
| This is the first subsection. |
| |
| |
| \section3 Hello Qt |
| |
| This is the first subsubsection. |
| |
| |
| \section3 Making Connections |
| |
| This is the second subsubsection. |
| |
| |
| \section3 Using the Reference Documentation |
| |
| This is the third subsubsection. |
| |
| |
| \section2 Creating Dialogs |
| |
| This is the second subsection. |
| |
| |
| \section3 Subclassing QDialog |
| |
| This is the first subsubsection. |
| |
| ... |
| |
| |
| \section1 Intermediate Qt |
| |
| This is the second section. |
| |
| |
| \section2 Layout Management |
| |
| This is the second section's first subsection. |
| |
| |
| \section3 Basic Layouts |
| |
| This is the first subsubsection. |
| |
| ... |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| \raw HTML |
| <a name="Basic Qt"> |
| <h1>Basic Qt</h1> |
| </a> |
| <p>This is the first section.</p> |
| |
| <a name="Getting started"> |
| <h2>Getting Started</h2> |
| </a> |
| This is the first subsection.</p> |
| |
| <a name="Hello Qt"> |
| <h3>Hello Qt</h3> |
| </a> |
| <p>This is the first subsubsection.</p> |
| |
| <a name="Making Connections"> |
| <h3>Making Connections</h3> |
| </a> |
| <p>This is the second subsubsection.</p> |
| |
| <a name="Using the Reference Documentation"> |
| <h3>Using the Reference Documentation</h3> |
| </a> |
| <p>This is the third subsubsection.</p> |
| |
| <a name="Creating Dialogs"> |
| <h2>Creating Dialogs</h2> |
| </a> |
| <p>This is the second subsection.</p> |
| |
| <a name="Subclassing QDialog"> |
| <h3>Subclassing QDialog</h3> |
| </a> |
| <p>This is the first subsubsection.</p> |
| |
| ... |
| |
| <a name="Intermediate Qt"> |
| <h1>Intermediate Qt</h1> |
| </a> |
| <p>This is the second section.</p> |
| |
| <a name="Layout Management"> |
| <h2>Layout Management</h2> |
| </a> |
| <p>This is the second section's first subsection.</p> |
| |
| <a name="Basic Layouts"> |
| <h3>Basic Layouts</h3> |
| </a> |
| <p>This is the first subsubsection.</p> |
| |
| ... |
| |
| \endraw |
| \endquotation |
| |
| Each section is a logical unit in the document. The section |
| heading appears in the automatically generated table of contents |
| that normally appears in the upper right-hand corner of the page. |
| |
| \target sectionOne-command |
| \section1 \\section1 |
| |
| The \\section1 command starts a new section. |
| |
| See \l{section-commands} {Section commands} for an explanation of the various |
| section units, command argument, and rendering. |
| |
| \target sectionTwo-command |
| \section1 \\section2 |
| |
| The \\section2 command starts a new section. |
| |
| See \l{section-commands} {Section commands} for an explanation of the various |
| section units, command argument, and rendering. |
| |
| \target sectionThree-command |
| \section1 \\section3 |
| |
| The \\section3 command starts a new section. |
| |
| See \l{section-commands} {Section commands} for an explanation of the various |
| section units, command argument, and rendering. |
| |
| \target sectionFour-command |
| \section1 \\section4 |
| |
| The \\section4 command starts a new section. |
| |
| See \l{section-commands} {Section commands} for an explanation of the various |
| section units, command argument, and rendering. |
| |
| */ |
| |
| |
| /*! |
| \page 06-qdoc-commands-includecodeinline.html |
| \previouspage Document Structure |
| \nextpage Including External Code |
| |
| \title Including Code Inline |
| |
| The following commands are used to render source code without |
| formatting. The source code begins on a new line, rendered in the |
| code. |
| |
| \note Although most of these commands are for rendering C++ |
| code, the |
| \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command} |
| {\\snippet} and |
| \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command} |
| {\\codeline} commands are preferred over the others. These |
| commands allow equivalent code snippets for other Qt language |
| bindings to be substituted for the C++ snippets in the |
| documentation. |
| |
| \target code-command |
| \section1 \\code |
| |
| The \\code and \\endcode commands enclose a snippet of source code. |
| |
| \note The \l {c-command} {\\c} command can be used for short code |
| fragments within a sentence. The \\code command is for longer code |
| snippets. It renders the code verbatim in a separate paragraph in |
| a html <pre> element, and parses the enclosed snippet, creating links |
| to any known types in the code. |
| |
| For documenting command-line instructions, shell scripts, or any |
| content that is not in a Qt language recognized by QDoc, use |
| \l {badcode-command}{\\badcode} instead. |
| |
| When processing any of the \\code, \l {newcode-command} {\\newcode} or \l |
| {oldcode-command} {\\oldcode} commands, QDoc removes all |
| indentation that is common for the verbatim code blocks within a |
| \c{/}\c{*!} ... \c{*}\c{/} comment before it adds the standard |
| indentation. |
| |
| \note This doesn't apply to externally quoted code using the \l |
| {quotefromfile-command} {\\quotefromfile} or \l |
| {quotefile-command} {\\quotefile} command. |
| |
| \code |
| / *! |
| \code |
| #include <QApplication> |
| #include <QPushButton> |
| |
| int main(int argc, char *argv[]) |
| { |
| ... |
| } |
| \ endcode |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \code |
| #include <QApplication> |
| #include <QPushButton> |
| |
| int main(int argc, char *argv[]) |
| { |
| ... |
| } |
| \endcode |
| |
| Other QDoc commands are disabled within \\code... \\endcode, and |
| the special character '\\' is accepted and rendered like the rest |
| of the code, unless it is followed by a digit and parameters were |
| passed to \\code. |
| |
| \section2 Code snippet parameters |
| |
| Since QDoc version 5.12, \\code command accepts also optional |
| parameters. Parameters are useful for injecting simple |
| strings into the code snippet. To inject a string to a specific |
| location in the snippet, add a backslash followed by a digit (1..8). |
| The digits correspond with the order of the argument list, where |
| arguments are separated by spaces. |
| |
| For example: |
| |
| \code |
| / *! |
| \code * hello |
| /\1 \2 \1/ |
| \ endcode |
| * / |
| \endcode |
| |
| For the above snippet, QDoc renders the word \e hello enclosed in |
| a C-style comment. |
| |
| \section2 Including code from external files |
| |
| To include code snippets from an external file, use the |
| \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command} |
| {\\snippet} and |
| \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command} |
| {\\codeline} commands. |
| |
| See also \l {c-command} {\\c}, \l {badcode-command} {\\badcode}, \l |
| {07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command} |
| {\\quotefromfile}, \l{newcode-command} {\\newcode}, and \l {oldcode-command} |
| {\\oldcode}. |
| |
| \target badcode-command |
| \section1 \\badcode |
| |
| Similar to \l {code-command}{\\code}, \\badcode and \\endcode commands |
| enclose content that is rendered verbatim in a separate paragraph, but no |
| parsing or automatic link creation is performed. Instead, the content is |
| treated as plain text. |
| |
| Substitute \\code with this command when documenting command-line |
| instructions, shell scripts or any other content that is not in a Qt |
| language, but should still be styled similarly to a \\code paragraph. |
| |
| Like \\code, \\badcode accepts also optional parameters. |
| |
| \target newcode-command |
| \section1 \\newcode |
| |
| The \\newcode, \\oldcode, and \\endcode commands enable you to |
| show how to port a snippet of code to a new version of an API. |
| |
| The \\newcode command and its companion the \\oldcode command are |
| a convenience combination of the \l {code-command} {\\code} commands: |
| this combination provides a text relating the two code snippets to each |
| other. |
| |
| The \\newcode command requires a preceding \\oldcode statement. |
| |
| Like the \l{code-command}{\\code} command, the \\newcode command renders its |
| code on a new line in the documentation using a monospace font and the |
| standard indentation. |
| |
| \code |
| / *! |
| \oldcode |
| if (printer->setup(parent)) |
| ... |
| \newcode |
| QPrintDialog dialog(printer, parent); |
| if (dialog.exec()) |
| ... |
| \ endcode |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| \oldcode |
| if (printer->setup(parent)) |
| ... |
| \newcode |
| QPrintDialog dialog(printer, parent); |
| if (dialog.exec()) |
| ... |
| \endcode |
| \endquotation |
| |
| Other QDoc commands are disabled within \\oldcode ... \\endcode, |
| and the '\\' character doesn't need to be escaped. |
| |
| \target oldcode-command |
| \section1 \\oldcode |
| |
| The \\oldcode command requires a corresponding |
| \\newcode statement; otherwise QDoc fails to parse the command |
| and emits a warning. |
| |
| See also \l {newcode-command} {\\newcode}. |
| |
| \target qml-command |
| \section1 \\qml |
| |
| The \\qml and \\endqml commands enclose a snippet of QML source |
| code. |
| |
| \code |
| / *! |
| \qml |
| import QtQuick 2.0 |
| |
| Row { |
| Rectangle { |
| width: 100; height: 100 |
| color: "blue" |
| transform: Translate { y: 20 } |
| } |
| Rectangle { |
| width: 100; height: 100 |
| color: "red" |
| transform: Translate { y: -20 } |
| } |
| } |
| \endqml |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \qml |
| import QtQuick 2.0 |
| |
| Row { |
| Rectangle { |
| width: 100; height: 100 |
| color: "blue" |
| transform: Translate { y: 20 } |
| } |
| Rectangle { |
| width: 100; height: 100 |
| color: "red" |
| transform: Translate { y: -20 } |
| } |
| } |
| \endqml |
| |
| Like the \l{code-command}{\\code} command, \\qml accepts optional |
| parameters. |
| */ |
| |
| |
| /*! |
| \page 07-0-qdoc-commands-includingexternalcode.html |
| \previouspage Including Code Inline |
| \nextpage Creating Links |
| |
| \title Including External Code |
| |
| The following commands enable you to include code snippets from |
| external files. You can make QDoc include the complete contents of |
| a file, or you can quote specific parts of the file and skip |
| others. The typical use of the latter is to quote a file chunk by |
| chunk. |
| |
| \note Although all these commands can be used for rendering C++ |
| code, the |
| \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command} |
| {\\snippet} and |
| \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command} |
| {\\codeline} commands are preferred over the others. These |
| commands allow equivalent code snippets for other Qt language |
| bindings to be substituted for the C++ snippets in the |
| documentation. |
| |
| \target quotefile-command |
| \section1 \\quotefile |
| |
| The \\quotefile command expands to the complete contents of the |
| file given as argument. |
| |
| The command considers the rest of the line as part of its |
| argument, make sure to follow the file name with a line break. |
| |
| The file's contents is rendered in a separate paragraph, using a |
| monospace font and the standard indentation. The code is shown |
| verbatim. |
| |
| \code |
| / *! |
| This is a simple "Hello world" example: |
| |
| \quotefile examples/main.cpp |
| |
| It contains only the bare minimum you need |
| to get a Qt application up and running. |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| This is a simple "Hello world" example: |
| |
| \quotefile examples/main.cpp |
| |
| It contains only the bare minimum you need to get a Qt |
| application up and running. |
| \endquotation |
| |
| See also \l {quotefromfile-command} {\\quotefromfile} and |
| \l {code-command} {\\code}. |
| |
| |
| \target quotefromfile-command |
| \section1 \\quotefromfile |
| |
| The \\quotefromfile command opens the file given as argument for |
| quoting. |
| |
| The command considers the rest of the line as part of its |
| argument, make sure to follow the file name with a line break. |
| |
| The command is intended for use when quoting parts from file with |
| the walkthrough commands: \l {printline-command} {\\printline}, \l |
| {printto-command} {\\printto}, \l {printuntil-command} |
| {\\printuntil}, \l {skipline-command} {\\skipline}, \l |
| {skipto-command} {\\skipto}, \l {skipuntil-command} |
| {\\skipuntil}. This enables you to quote specific portions of a |
| file. |
| |
| \code |
| / *! |
| The whole application is contained within |
| the \c main() function: |
| |
| \quotefromfile examples/main.cpp |
| |
| \skipto main |
| \printuntil app(argc, argv) |
| |
| First we create a QApplication object using |
| the \c argc and \c argv parameters. |
| |
| \skipto QPushButton |
| \printuntil resize |
| |
| Then we create a QPushButton, and give it a reasonable |
| size using the QWidget::resize() function. |
| |
| ... |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| The whole application is contained within |
| the \c main() function: |
| |
| \quotefromfile examples/main.cpp |
| |
| \skipto main |
| \printuntil app(argc, argv) |
| |
| First we create a QApplication object using the \c argc |
| and \c argv parameters. |
| |
| \skipto QPushButton |
| \printuntil resize |
| |
| Then we create a QPushButton, and give it a reasonable |
| size using the QWidget::resize() function. |
| |
| ... |
| \endquotation |
| |
| QDoc remembers which file it is quoting from, and the current |
| position in that file (see \l {file} {\\printline} for more |
| information). There is no need to "close" the file. |
| |
| See also \l {quotefile-command} {\\quotefile}, \l {code-command} |
| {\\code} and \l {dots} {\\dots}. |
| |
| \target printline-command |
| \section1 \\printline |
| |
| The \\printline command expands to the line from the current |
| position to the next non-blank line of the current source file. |
| |
| To ensure that the documentation remains synchronized with the |
| source file, a substring of the line must be specified as an |
| argument to the command. Note that the command considers the rest |
| of the line as part of its argument, make sure to follow the |
| substring with a line break. |
| |
| The line from the source file is rendered as a separate paragraph, |
| using a monospace font and the standard indentation. The code is |
| shown verbatim. |
| |
| \code |
| / *! |
| There has to be exactly one QApplication object |
| in every GUI application that uses Qt. |
| |
| \quotefromfile examples/main.cpp |
| |
| \printline QApplication |
| |
| This line includes the QApplication class |
| definition. QApplication manages various |
| application-wide resources, such as the |
| default font and cursor. |
| |
| \printline QPushButton |
| |
| This line includes the QPushButton class |
| definition. The QPushButton widget provides a command |
| button. |
| |
| \printline main |
| |
| The main function... |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| There has to be exactly one QApplication object |
| in every GUI application that uses Qt. |
| |
| \quotefromfile examples/main.cpp |
| |
| \skipto QApplication |
| \printline QApplication |
| |
| This line includes the QApplication class |
| definition. QApplication manages various |
| application-wide resources, such as the |
| default font and cursor. |
| |
| \printline QPushButton |
| |
| This line includes the QPushButton class |
| definition. The QPushButton widget provides a command |
| button. |
| |
| \printline main |
| |
| The main function... |
| \endquotation |
| |
| \target file |
| |
| QDoc reads the file sequentially. To move the current position |
| forward you can use either of the \l {skipline-command} |
| {\\skip...} commands. To move the current position backward, you |
| can use the \l {quotefromfile-command} {\\quotefromfile} command |
| again. |
| |
| \target substring |
| |
| If the substring argument is surrounded by slashes it is |
| interpreted as a \l {QRegExp}{regular expression}. |
| |
| \code |
| / *! |
| \quotefromfile examples/mainwindow.cpp |
| |
| \skipto closeEvent |
| \printuntil /^\}/ |
| |
| Close events are sent to widgets that the users want to |
| close, usually by clicking \c File|Exit or by clicking |
| the \c X title bar button. By reimplementing the event |
| handler, we can intercept attempts to close the |
| application. |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| \quotefromfile examples/mainwindow.cpp |
| |
| \skipto closeEvent |
| \printuntil /^\}/ |
| |
| Close events are sent to widgets that the users want to |
| close, usually by clicking \c File|Exit or by clicking |
| the \c X title bar button. By reimplementing the event |
| handler, we can intercept attempts to close the |
| application. |
| \endquotation |
| |
| (\l {widgets/scribble} {The complete example file...}) |
| |
| The regular expression \c /^\}/ makes QDoc print until the first |
| '}' character occurring at the beginning of the line without |
| indentation. /.../ encloses the regular expression, and '^' means |
| the beginning of the line. The '}' character must be escaped since |
| it is a special character in regular expressions. |
| |
| QDoc will emit a warning if the specified substring or regular |
| expression cannot be located, i.e. if the source code has changed. |
| |
| See also \l {printto-command} {\\printto} and \l |
| {printuntil-command} {\\printuntil}. |
| |
| \target printto-command |
| \section1 \\printto |
| |
| The \\printto command expands to all the lines from the current |
| position up to and \e excluding the next line containing a given |
| substring. |
| |
| The command considers the rest of the line as part of its |
| argument, make sure to follow the substring with a line break. The |
| command also follows the same conventions for \l {file} |
| {positioning} and \l {substring} {argument} as the \l |
| {printline-command} {\\printline} command. |
| |
| The lines from the source file are rendered in a separate |
| paragraph, using a monospace font and the standard |
| indentation. The code is shown verbatim. |
| |
| \code |
| / *! |
| The whole application is contained within the |
| \c main() function: |
| |
| \quotefromfile examples/main.cpp |
| \printto hello |
| |
| First we create a QApplication object using the \c argc and |
| \c argv parameters... |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| The whole application is contained within the |
| \c main() function: |
| |
| \quotefromfile examples/main.cpp |
| \skipto main |
| \printto hello |
| |
| First we create a QApplication object using the \c argc |
| and \c argv parameters... |
| \endquotation |
| |
| See also \l {printline-command} {\\printline} and \l |
| {printuntil-command} {\\printuntil}. |
| |
| \target printuntil-command |
| \section1 \\printuntil |
| |
| The \\printuntil command expands to all the lines from the current |
| position up to and \e including the next line containing a given |
| substring. |
| |
| The command considers the rest of the line as part of its |
| argument, make sure to follow the substring with a line break. The |
| command also follows the same conventions for \l {file} |
| {positioning} and \l {substring} {argument} as the \l |
| {printline-command} {\\printline} command. |
| |
| If \\printuntil is used without an argument, it expands to all the |
| lines from the current position to the end of the quoted file. |
| |
| The lines from the source file are rendered in a separate |
| paragraph, using a monospace font and the standard |
| indentation. The code is shown verbatim. |
| |
| \code |
| / *! |
| The whole application is contained within the |
| \c main() function: |
| |
| \quotefromfile examples/main.cpp |
| \skipto main |
| \printuntil hello |
| |
| First we create a QApplication object using the |
| \c argc and \c argv parameters, then we create |
| a QPushButton. |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| The whole application is contained within the |
| \c main() function: |
| |
| \quotefromfile examples/main.cpp |
| \skipto main |
| \printuntil hello |
| |
| First we create a \l |
| {http://doc.qt.io/qt-5/qapplication.html} {QApplication} |
| object using the \c argc and \c argv parameters, then we |
| create a \l |
| {http://doc.qt.io/qt-5/qpushbutton.html} {QPushButton}. |
| \endquotation |
| |
| See also \l {printline-command} {\\printline} and \l |
| {printto-command} {\\printto}. |
| |
| \target skipline-command |
| \section1 \\skipline |
| |
| The \\skipline command ignores the next non-blank line in the |
| current source file. |
| |
| Doc reads the file sequentially, and the \\skipline command is |
| used to move the current position (omitting a line of the source |
| file). See the remark about \l {file} {file positioning} above. |
| |
| The command considers the rest of the line as part of its |
| argument, make sure to follow the substring with a line break. The |
| command also follows the same conventions for \l {substring} |
| {argument} as the \l {printline-command} {\\printline} command, |
| and it is used in conjunction with the \l {quotefromfile-command} |
| {\\quotefromfile} command. |
| |
| \code |
| / *! |
| QPushButton is a GUI push button that the user |
| can press and release. |
| |
| \quotefromfile examples/main.cpp |
| \skipline QApplication |
| \printline QPushButton |
| |
| This line includes the QPushButton class |
| definition. For each class that is part of the |
| public Qt API, there exists a header file of |
| the same name that contains its definition. |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| \l |
| QPushButton is a GUI push button that the user |
| can press and release. |
| |
| \quotefromfile examples/main.cpp |
| \skipto QApplication |
| \skipline QApplication |
| \printline QPushButton |
| |
| This line includes the QPushButton class |
| definition. For each class that is part of the public |
| Qt API, there exists a header file of the same name |
| that contains its definition. |
| \endquotation |
| |
| See also \l {skipto-command} {\\skipto}, \l {skipuntil-command} |
| {\\skipuntil} and \l {dots} {\\dots}. |
| |
| \target skipto-command |
| \section1 \\skipto |
| |
| The \\skipto command ignores all the lines from the current |
| position up to and \e excluding the next line containing a given |
| substring. |
| |
| QDoc reads the file sequentially, and the \\skipto command is used |
| to move the current position (omitting one or several lines of the |
| source file). See the remark about \l {file} {file positioning} |
| above. |
| |
| The command considers the rest of the line as part of its |
| argument, make sure to follow the substring with a line break. |
| |
| The command also follows the same conventions for \l {substring} |
| {argument} as the \l {printline-command} {\\printline} command, |
| and it is used in conjunction with the \l {quotefromfile-command} |
| {\\quotefromfile} command. |
| |
| \code |
| / *! |
| The whole application is contained within |
| the \c main() function: |
| |
| \quotefromfile examples/main.cpp |
| \skipto main |
| \printuntil } |
| |
| First we create a QApplication object. There |
| has to be exactly one such object in |
| every GUI application that uses Qt. Then |
| we create a QPushButton, resize it to a reasonable |
| size... |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| The whole application is contained within |
| the \c main() function: |
| |
| \quotefromfile examples/main.cpp |
| \skipto main |
| \printuntil } |
| |
| First we create a QApplication object. There has to be |
| exactly one such object in every GUI application that |
| uses Qt. Then we create a QPushButton, resize it to a |
| reasonable size ... |
| \endquotation |
| |
| See also \l {skipline-command} {\\skipline}, \l |
| {skipuntil-command} {\\skipuntil} and \l {dots} {\\dots}. |
| |
| \target skipuntil-command |
| \section1 \\skipuntil |
| |
| The \\skipuntil command ignores all the lines from the current |
| position up to and \e including the next line containing a given |
| substring. |
| |
| QDoc reads the file sequentially, and the \\skipuntil command is |
| used to move the current position (omitting one or several lines |
| of the source file). See the remark about \l {file} {file |
| positioning} above. |
| |
| The command considers the rest of the line as part of its |
| argument, make sure to follow the substring with a line break. |
| |
| The command also follows the same conventions for \l {substring} |
| {argument} as the \l {printline-command} {\\printline} command, |
| and it is used in conjunction with the \l {quotefromfile-command} |
| {\\quotefromfile} command. |
| |
| \code |
| / *! |
| The first thing we did in the \c main() function |
| was to create a QApplication object \c app. |
| |
| \quotefromfile examples/main.cpp |
| \skipuntil show |
| \dots |
| \printuntil } |
| |
| In the end we must remember to make \c main() pass the |
| control to Qt. QCoreApplication::exec() will return when |
| the application exits... |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| The first thing we did in the \c main() function was to |
| create a QApplication object \c app. |
| |
| \quotefromfile examples/main.cpp |
| \skipuntil show |
| \dots |
| \printuntil } |
| |
| In the end we must remember to make \c main() pass the |
| control to Qt. QCoreApplication::exec() |
| will return when the application exits... |
| \endquotation |
| |
| See also \l {skipline-command} {\\skipline}, \l {skipto-command} |
| {\\skipto} and \l {dots} {\\dots}. |
| |
| \target dots-command |
| \section1 \\dots |
| |
| The \\dots command indicates that parts of the source file have |
| been omitted when quoting a file. |
| |
| The command is used in conjunction with the \l |
| {quotefromfile-command} {\\quotefromfile} command, and should be |
| stated on its own line. The dots are rendered on a new line, using |
| a monospace font. |
| |
| \code |
| / *! |
| \quotefromfile examples/main.cpp |
| \skipto main |
| \printuntil { |
| \dots |
| \skipuntil exec |
| \printline } |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotefromfile examples/main.cpp |
| \skipto main |
| \printuntil { |
| \dots |
| \skipuntil exec |
| \printline } |
| |
| The default indentation is 4 spaces, but this can be adjusted |
| using the command's optional argument. |
| |
| \code |
| / *! |
| \dots 0 |
| \dots |
| \dots 8 |
| \dots 12 |
| \dots 16 |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \dots 0 |
| \dots |
| \dots 8 |
| \dots 12 |
| \dots 16 |
| |
| See also \l {skipline-command} {\\skipline}, \l {skipto-command} |
| {\\skipto} and \l {skipuntil-command} {\\skipuntil}. |
| |
| \target snippet-command |
| \section1 \\snippet |
| |
| The \\snippet command causes a code snippet to be included |
| verbatim as preformatted text, which may be syntax highlighted. |
| |
| Each code snippet is 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 (for example, \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: |
| |
| \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 |
| |
| By default, QDoc looks for \c{//!} as a code snippet marker. |
| For \c{.pro}, \c{.py}, \c{.cmake}, and \c{CMakeLists.txt} |
| files, \c {#!} is detected. Finally, \c{<!--} is accepted in |
| \c{.html}, \c{.qrc}, \c{.ui}, \c{.xml}, \c{.dita}, and \c{.xq} files. |
| |
| \target codeline-command |
| \section1 \\codeline |
| |
| The \\codeline command inserts a blank line of preformatted |
| text. It is used to insert gaps between snippets without closing |
| the current preformatted text area and opening a new one. |
| |
| */ |
| |
| |
| /*! |
| \page 08-qdoc-commands-creatinglinks.html |
| \previouspage Including External Code |
| \nextpage Including Images |
| |
| \title Creating Links |
| |
| These commands are for creating hyperlinks to classes, functions, |
| examples, and other targets. |
| |
| \target l-command |
| \section1 \\l (link) |
| |
| The \\l link command is used to create a hyperlink to many |
| different kinds of targets. The command's general syntax is: |
| |
| \code |
| \l [ link criteria ] { link target } { link text } |
| \endcode |
| |
| ...where the \c {link criteria} in square brackets are optional |
| but may be required when the \c {link target} is ambiguous. See |
| \l {Fixing Ambiguous Links} below. |
| |
| Here is an example using the \\l command to link to an external page: |
| |
| \code |
| / *! |
| Read the \l {http://doc.qt.io/qt-5/} |
| {Qt 5.0 Documentation} carefully. |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| Read the \l {http://doc.qt.io/qt-5/} |
| {Qt 5.0 Documentation} carefully. |
| \endquotation |
| |
| If the link target is equivalent to the link text, the second |
| argument can be omitted. |
| |
| For example, if you have documentation like: |
| |
| \code |
| / *! |
| \target assertions |
| |
| Assertions make some statement about the text at the |
| point where they occur in the regexp, but they do not |
| match any characters. |
| |
| ... |
| |
| Regexps are built up from expressions, quantifiers, and |
| \l {assertions} {assertions}. |
| * / |
| \endcode |
| |
| You can simplify this as follows: |
| |
| \code |
| / *! |
| \target assertions |
| |
| Assertions make some statement about the text at the |
| point where they occur in the regexp, but they do not |
| match any characters. |
| |
| ... |
| |
| Regexps are built up from expressions, quantifiers, and |
| \l assertions. |
| * / |
| \endcode |
| |
| For the one-parameter version, the braces can often be omitted. |
| The \\l command supports several ways of linking: |
| |
| \list |
| |
| \li \c {\l QWidget} - The name of a class documented with the \l |
| {class-command} {\\class} command. |
| |
| \li \c {\l QWidget::sizeHint()} - The signature of a function without |
| parameters. If a matching function without parameters can't be found, |
| the link is satisfied with the first matching function found. |
| |
| \li \c {\l QWidget::removeAction(QAction* action)} - The signature |
| of a function with parameters. If an exact match is not found, the |
| link is not satisfied and QDoc reports a \e {Can't link to...} error. |
| |
| \li \c {\l <QtGlobal>} - The subject of a \l {headerfile-command} |
| {\\headerfile} command. |
| |
| \li \c {\l widgets/wiggly} - The relative path used in an \l |
| {example-command} {\\example} command. |
| |
| \li \c {\l {QWidget Class Reference}} - The title used in a |
| \l {title-command} {\\title} command. |
| |
| \li \c {\l {Introduction to QDoc}}- The text from one of the |
| \l{section-commands} {Section commands}. |
| |
| \li \c {\l fontmatching} - The argument of a \l {target-command} |
| {\\target} command. |
| |
| \li \c {\l {Shared Classes}} - A keyword named in a \l |
| {keyword-command} {\\keyword} command. |
| |
| \li \c {\l http://qt-project.org/} - A URL. |
| |
| \endlist |
| |
| QDoc also tries to make a link out of any word that doesn't |
| resemble a normal English word, 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 |
| \li \c {\l {QWidget::} {sizeHint()}} |
| \endlist |
| |
| QDoc renders this as: |
| |
| \quotation |
| \l {QWidget::} {sizeHint()} |
| \endquotation |
| |
| \section2 Fixing Ambiguous Links |
| |
| Because of the modularization of Qt beginning with Qt 5.0, The |
| possibility that QDoc will have to deal with ambiguous links has |
| increased. An ambiguous link is one that has a matching target in |
| more than one Qt module, e.g. the same section title can appear in |
| more than one Qt module, or the name of a C++ class in one module |
| can also be the name of a QML type in another module. A real |
| example in Qt5 is the name Qt itself. Qt is the name of both a C++ |
| namespace in QtCore and a QML type in QtQml. |
| |
| Suppose we want to link to the \l {Qt} {Qt C++ namespace}. At the |
| time QDoc generated this HTML page, that link was correct. Does |
| it still go to the C++ namespace? Qdoc generated that link from |
| this link command: |
| |
| \list |
| \li \c {\l {Qt} {Qt C++ namespace}} |
| \endlist |
| |
| Now suppose we want to link to the \l [QML] {Qt} {Qt QML type}. |
| At the time QDoc generated this HTML page, that link was also |
| correct, but we had to use this link command: |
| |
| \list |
| \li \c {\l [QML] {Qt} {Qt QML type}} |
| \endlist |
| |
| The \e {QML} in \e {square brackets} tells QDoc to accept a |
| matching target only if the traget is on a QML page. Qdoc actually |
| finds the C++ namespace target first, but since that target is on |
| a C++ page, QDoc ignores it and keeps looking until it finds the |
| same target on a QML page. |
| |
| Without the guidance in the \e{\\l command} in the optional \e |
| {square bracket} argument, QDoc links to the first matching target |
| it finds. QDoc can't warn that the link was ambiguous in such |
| cases because it doesn't know that another matching target exists. |
| |
| \section2 What arguments can appear in square brackets? |
| |
| A link command with square bracket argument has the following syntax: |
| \list |
| \c {\l [QML|CPP|DOC|QtModuleName] {link target} {link text}} |
| \endlist |
| |
| The \e {square bracket} argument is only allowed in the \c {\l |
| (link)} command. The example above shows how \c QML is used as the |
| \e {square brackets} argument to force QDoc to match a QML target. |
| Most often, this will be a QML type, but it can also be a QML |
| member function of property. |
| |
| In the example, QDoc didn't need a \e {square bracket} argument to |
| find the Qt C++ namespace page, because that one was the first |
| matching target QDoc found anyway. However, to force QDoc to find |
| a C++ target when a matching QML target gets in the way, \c CPP |
| can be used as the \e {square bracket} argument. For example: |
| |
| \list |
| \li \c {\l [CPP] {Qt} {Qt C++ namespace}} |
| \endlist |
| |
| ...will force QDoc to ignore the Qt QML type and continue |
| searching until it matches the Qt C++ namespace. |
| |
| If the link target is neither a C++ nor a QML entity, \c {DOC} can |
| be used as the \e {square bracket} argument to prevent QDoc from |
| matching either of those. At this writing, there were no cases of |
| ambiguous links where using \c {DOC} was required. |
| |
| Often, the documentor knows which Qt module the link target is |
| in. When the module name is known, use the module name as the \e |
| {square bracket} argument. In the example above, if we know that |
| the QML type named Qt is located in the QtQml module, we can write |
| the link command like this: |
| |
| \list |
| \li \c {\l [QtQml] {Qt} {Qt QML type}} |
| \endlist |
| |
| When a module name is used as the \e {square bracket} argument, |
| QDoc will search for link the target in that module only. This |
| makes searching for link targets more efficient. |
| |
| Finally, the module name and entity type arguments can be |
| combined, separated by a blank, so something like this is also |
| allowed: |
| |
| \list |
| \li \c {\l [CPP QtQml] {Window} {C++ class Window}} |
| \endlist |
| |
| As of this writing, there were no cases where combining the two |
| was required. |
| |
| See also \l {sa-command} {\\sa}, \l {target-command} {\\target}, |
| and \l {keyword-command} {\\keyword}. |
| |
| |
| \target sa-command |
| \section1 \\sa (see also) |
| |
| The \\sa command defines a list of links that will be rendered in |
| a separate "See also" section at the bottom of the documentation |
| unit. |
| |
| The command takes a comma-separated list of links as its |
| argument. If the line ends with a comma, you can continue |
| the list on the next line. The general syntax is: |
| |
| \code |
| \sa {the first link}, {the second link}, |
| {the third link}, ... |
| \endcode |
| |
| QDoc will automatically try to generate "See also" links |
| interconnecting a property's various functions. For example, a |
| setVisible() function will automatically get a link to visible() |
| and vice versa. |
| |
| In general, QDoc will generate "See also" links that interconnect |
| the functions that access the same property. It recognizes four |
| different syntax versions: |
| |
| \list |
| \li \c property() |
| \li \c setProperty() |
| \li \c isProperty() |
| \li \c hasProperty() |
| \endlist |
| |
| The \\sa command supports the same kind of links as the \l |
| {l-command} {\\l} command. |
| |
| \code |
| / *! |
| Appends the actions \a actions to this widget's |
| list of actions. |
| |
| \sa removeAction(), QMenu, addAction() |
| * / |
| void QWidget::addActions(QList<QAction *> actions) |
| { |
| ... |
| } |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| \b {void QWidget::addActions ( QList<QAction*> |
| \e actions )} |
| |
| Appends the actions \e actions to this widget's list of |
| actions. |
| |
| See also \l {QWidget::removeAction()} {removeAction()}, |
| \l QMenu, and \l {QWidget::addAction()} {addAction()}. |
| \endquotation |
| |
| See also \l {l-command} {\\l}, \l {target-command} {\\target} and |
| \l {keyword-command} {\\keyword}. |
| |
| |
| \target target-command |
| \section1 \\target |
| |
| The \\target command names a place in the documentation that you |
| can link to using the \l {l-command} {\\l (link)} and \l |
| {sa-command} {\\sa (see also)} commands. |
| |
| The text up to the line break becomes the target name. Be sure to |
| follow the target name with a line break. Curly brackets are not |
| required around the target name, but they may be required when the |
| target name is used in a link command. See below. |
| |
| \code |
| / *! |
| \target capturing parentheses |
| \section1 Capturing Text |
| |
| Parentheses allow us to group elements together so that |
| we can quantify and capture them. |
| |
| ... |
| * / |
| \endcode |
| |
| The target name \e{capturing parentheses} can be linked from |
| within the same document containing the target in the following way: |
| |
| \list |
| \li \c {\l {capturing parentheses}} (from within the same QDoc comment) |
| \endlist |
| |
| \note The brackets in the link example are required because the |
| target name contains spaces. |
| |
| See also \l {l-command} {\\l}, \l {sa-command} {\\sa} and \l |
| {keyword-command} {\\keyword}. |
| |
| \target keyword-command |
| \section1 \\keyword |
| |
| The \\keyword command names a place in the documentation that you |
| can link to using the \l {l-command} {\\l (link)} and \l |
| {sa-command} {\\sa (see also)} commands. |
| |
| The \\keyword command is like the \l {target-command} {\\target} |
| command, except when linking to keyword the link goes to the top of |
| the QDoc comment where the \\keyword appears in. If you want to |
| create a link target to a \c section unit within a \\page, use |
| \\target instead. A keyword can be linked from anywhere using a |
| simple syntax. |
| |
| Keywords must be unique over all the documents processed during |
| the QDoc run. The command uses the rest of the line as its |
| argument. Be sure to follow the keyword with a line break. |
| |
| |
| \code |
| / *! |
| \class QRegExp |
| \reentrant |
| \brief The QRegExp class provides pattern |
| matching using regular expressions. |
| \ingroup tools |
| \ingroup misc |
| \ingroup shared |
| |
| \keyword regular expression |
| |
| Regular expressions, or "regexps", provide a way to |
| find patterns within text. |
| |
| ... |
| * / |
| \endcode |
| |
| The location marked with the keyword can be linked to with: |
| |
| \code |
| / *! |
| When a string is surrounded by slashes, it is |
| interpreted as a \l {QRegExp}{regular expression}. |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| When a string is surrounded by slashes, it is |
| interpreted as a \l {regular expression}. |
| \endquotation |
| |
| If the keyword text contains spaces, the brackets are required. |
| |
| See also \l {l-command} {\\l (link)}, \l {sa-command} {\\sa (see |
| also)} and \l {target-command} {\\target}. |
| |
| */ |
| |
| |
| /*! |
| \page 09-qdoc-commands-includingimages.html |
| \previouspage Creating Links |
| \nextpage Tables and Lists |
| |
| \title Including Images |
| |
| The graphic commands makes it possible to include images in the |
| documentation. The images can be rendered as separate paragraphs, |
| or within running text. |
| |
| \target image-command |
| \section1 \\image |
| |
| The \\image command expands to the image specified by its first |
| argument, and renders it centered as a separate paragraph. |
| |
| The command takes two arguments. The first argument is the name of |
| the image file. The second argument is optional and is a simple |
| description of the image, equivalent to the HTML alt="" in an image |
| tag. The description is used for tooltips and for browsers that don't |
| support images, like the Lynx text browser. |
| |
| The remaining text \e{after} the file name is the optional, |
| description argument. Be sure to follow the file name or the |
| description with a line break. Curly brackets are required if the |
| description argument spans multiple lines. |
| |
| \code |
| / *! |
| Qt is a C++ toolkit for cross-platform GUI application development. |
| |
| \image happyguy.jpg "Happy guy" |
| |
| Qt provides single-source portability across Microsoft |
| Windows, macOS, Linux, and all major commercial Unix |
| variants. It is also available for embedded devices. |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| Qt is a C++ toolkit for cross-platform GUI application development. |
| |
| \image happyguy.jpg image "Happy guy" |
| |
| Qt provides single-source portability across Microsoft |
| Windows, macOS, Linux, and all major commercial Unix |
| variants. It is also available for embedded devices. |
| \endquotation |
| |
| See also \l {inlineimage-command} {\\inlineimage} and \l |
| {caption-command} {\\caption}. |
| |
| \target inlineimage-command |
| \section1 \\inlineimage |
| |
| The \\inlineimage command expands to the image specified by its |
| argument. The image is rendered inline with the rest of the text. |
| |
| The command takes two arguments. The first argument is the name of |
| the image file. The second argument is optional and is a simple |
| description of the image, equivalent to the HTML alt="" in an image |
| tag. The description is used for tooltips, and for when a browser |
| doesn't support images, like the Lynx text browser. |
| |
| The most common use of the \\inlineimage command is in lists and |
| tables. Here is an example of including inline images in a list: |
| |
| \code |
| / *! |
| \list 1 |
| \li \inlineimage happy.gif Oh so happy! |
| \li \inlineimage happy.gif Oh so happy! |
| \li \inlineimage happy.gif Oh so happy! |
| \endlist |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \list 1 |
| \li \inlineimage happy.gif Oh so happy! |
| \li \inlineimage happy.gif Oh so happy! |
| \li \inlineimage happy.gif Oh so happy! |
| \endlist |
| |
| Here is an example of including inline images in a table: |
| |
| \code |
| / *! |
| \table |
| \header |
| \li Qt |
| \li Qt Creator |
| \row |
| \li \inlineimage happy.gif Oh so happy! |
| \li \inlineimage happy.gif Oh so happy! |
| \row |
| \li \inlineimage happy.gif Oh so happy! |
| \li \inlineimage happy.gif Oh so happy! |
| \endtable |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \raw HTML |
| <table align="center" cellpadding="2" |
| cellspacing="1" border="0"> |
| <tr valign="top" bgcolor="#a2c511"> |
| <th>Qt</th> |
| <th>Qt Creator</th> |
| </tr> |
| <tr valign="top" bgcolor="#f0f0f0"> |
| <td><img src="images/happy.gif" alt="Oh so happy!" /> |
| </td> |
| <td><img src="images/happy.gif" alt="Oh so happy!" /> |
| </td> |
| </tr> |
| <tr valign="top" bgcolor="#f0f0f0"> |
| <td><img src="images/happy.gif" alt="Oh so happy!"/> |
| </td> |
| <td><img src="images/happy.gif" alt="Oh so happy!" /> |
| </td> |
| </tr> |
| </table> |
| \endraw |
| |
| The command can also be used to insert an image inline with the |
| text. |
| |
| \code |
| / *! |
| \inlineimage training.jpg Qt Training |
| The Qt Programming course is offered as a |
| five day Open Enrollment Course. The classes |
| are open to the public. Although the course is open |
| to anyone who wants to learn, attendees should |
| have significant experience in C++ development |
| to derive maximum benefit from the course. |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| \inlineimage training.jpg Qt Training |
| The Qt Programming course is offered as a |
| five day Open Enrollment Course. The classes |
| are open to the public. Although the course is open |
| to anyone who wants to learn, attendees should |
| have significant experience in C++ development |
| to derive maximum benefit from the course. |
| \endquotation |
| |
| See also \l {image-command} {\\image} and \l {caption-command} {\\caption}. |
| |
| \target caption-command |
| \section1 \\caption |
| |
| The \\caption command provides a caption for an image. |
| |
| The command takes all the text up to the end of the paragraph to |
| be the caption. Experiment until you get the effect you want. |
| |
| \code |
| / *! |
| \table 100% |
| \row |
| \li \image windowsvista-pushbutton.png |
| \caption The QPushButton widget provides a command button. |
| \li \image windowsvista-toolbutton.png |
| \caption The QToolButton class provides a quick-access button to commands |
| or options, usually used inside a QToolBar. |
| \endtable |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \table 100% |
| \row |
| \li \image windowsvista-pushbutton.png |
| \caption The QPushButton widget provides a command button. |
| \li \image windowsvista-toolbutton.png |
| \caption The QToolButton class provides a quick-access button to commands |
| or options, usually used inside a QToolBar. |
| \endtable |
| |
| See also \l {image-command} {\\image} and \l {inlineimage-command} |
| {\\inlineimage} |
| */ |
| |
| |
| /*! |
| \page 10-qdoc-commands-tablesandlists.html |
| \previouspage Including Images |
| \nextpage Special Content |
| |
| \title Tables and Lists |
| |
| These commands enable creating lists and tables. A list is |
| rendered left aligned as a separate paragraph. A table is rendered |
| centered as a separate paragraph. The table width depends on the |
| width of its contents. |
| |
| \target table-command |
| \section1 \\table |
| |
| The \\table and \\endtable commands delimit the contents of a |
| table. |
| |
| The command accepts a single argument specifying the table's width |
| as a percentage of the page width: |
| |
| \code |
| / *! |
| \table 100 % |
| |
| ... |
| |
| \endtable |
| * / |
| \endcode |
| |
| The code above ensures that the table will fill all available |
| space. If the table's width is smaller than 100 %, the table will |
| be centered in the generated documentation. |
| |
| A table can contain headers, rows and columns. A row starts with a |
| \l {row-command} {\\row} command and consists of cells, each of which |
| starts with an \l {li-command} {\\li} command. There is also a \l |
| {header-command} {\\header} command which is a special kind of row |
| that has a special format. |
| |
| \code |
| / *! |
| \table |
| \header |
| \li Qt Core Feature |
| \li Brief Description |
| \row |
| \li \l {Signal and Slots} |
| \li Signals and slots are used for communication |
| between objects. |
| \row |
| \li \l {Layout Management} |
| \li The Qt layout system provides a simple |
| and powerful way of specifying the layout |
| of child widgets. |
| \row |
| \li \l {Drag and Drop} |
| \li Drag and drop provides a simple visual |
| mechanism which users can use to transfer |
| information between and within applications. |
| \endtable |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \raw HTML |
| <table align="center" cellpadding="2" |
| cellspacing="1" border="0"> |
| <tr valign="top" bgcolor="#a2c511"> |
| <th>Qt Core Feature</th> |
| <th>Brief Description</th> |
| </tr> |
| |
| <tr valign="top" bgcolor="#d0d0d0"> |
| <td> |
| <a href="http://doc.qt.io/qt-5/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://doc.qt.io/qt-5/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://doc.qt.io/qt-5/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 |
| \li {3,1} This header cell spans three columns, |
| but only one row. |
| \row |
| \li {2, 1} This table cell spans two columns, |
| but only one row |
| \li {1, 2} This table cell spans only one column, |
| but two rows. |
| \row |
| \li A regular table cell |
| \li A regular table cell |
| \endtable |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \raw HTML |
| <table align="center" cellpadding="2" cellspacing="1" |
| border="0"> |
| |
| <tr valign="top" bgcolor="#a2c511"> |
| <th colspan="3" rowspan=" 1"> |
| This header cell spans three columns, but only one row. |
| </th> |
| </tr> |
| |
| <tr valign="top" bgcolor="#d0d0d0"> |
| <td colspan="2" rowspan=" 1"> |
| This table cell spans two columns, but only one row. |
| </td> |
| <td rowspan=" 2"> |
| This table cell spans only one column, but two rows. |
| </td> |
| </tr> |
| |
| <tr valign="top" bgcolor="#c0c0c0"> |
| <td>A regular table cell</td> |
| <td>A regular table cell</td> |
| </tr> |
| |
| </table> |
| \endraw |
| |
| See also \l {header-command} {\\header}, \l {row-command} {\\row} and \l {li-command} {\\li}. |
| |
| \target header-command |
| \section1 \\header |
| |
| The \\header command indicates that the following table cells are |
| the current table's column headers. |
| |
| The command can only be used within the \l{table-command} |
| {\\table...\\endtable} commands. A header can contain several |
| cells. A cell is created with the \l {li-command} {\\li} command. |
| |
| A header cell's text is centered within the table cell and |
| rendered using a bold font. |
| |
| \code |
| / *! |
| \table |
| \header |
| \li Qt Core Feature |
| \li Brief Description |
| \row |
| \li \l {Signal and Slots} |
| \li Signals and slots are used for communication |
| between objects. |
| \endtable |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \raw HTML |
| <table align="center" cellpadding="2" |
| cellspacing="1" border="0"> |
| <tr valign="top" bgcolor="#a2c511"> |
| <th>Qt Core Feature</th> |
| <th>Brief Description</th> |
| </tr> |
| |
| <tr valign="top" bgcolor="#d0d0d0"> |
| <td> |
| <a href="http://doc.qt.io/qt-5/signalsandslots.html"> |
| Signals and Slots</a> |
| </td> |
| <td>Signals and slots are used for communication |
| between objects.</td> |
| </tr> |
| </table> |
| \endraw |
| |
| See also \l {table-command} {\\table}, \l {row-command} {\\row} and \l {li-command} {\\li}. |
| |
| \target row-command |
| \section1 \\row |
| |
| The \\row command begins a new row in a table. The \l {li-command} |
| {\\li items} that belong in the new row will immediately follow the |
| \\row. |
| |
| The command can only be used within the \l{table-command} |
| {\\table...\\endtable} commands. A row can contain several |
| cells. A cell is created with the \l {li-command} {\\li} command. |
| |
| The background cell color of each row alternates between two |
| shades of grey, making it easier to distinguish the rows from each |
| other. The cells' contents is left aligned. |
| |
| \code |
| / *! |
| \table |
| \header |
| \li Qt Core Feature |
| \li Brief Description |
| \row |
| \li \l {Signal and Slots} |
| \li Signals and slots are used for communication |
| between objects. |
| \row |
| \li \l {Layout Management} |
| \li The Qt layout system provides a simple |
| and powerful way of specifying the layout |
| of child widgets. |
| \row |
| \li \l {Drag and Drop} |
| \li Drag and drop provides a simple visual |
| mechanism which users can use to transfer |
| information between and within applications. |
| \endtable |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \raw HTML |
| <table align="center" cellpadding="2" |
| cellspacing="1" border="0"> |
| <tr valign="top" bgcolor="#a2c511"> |
| <th>Qt Core Feature</th> |
| <th>Brief Description</th> |
| </tr> |
| |
| <tr valign="top" bgcolor="#d0d0d0"> |
| <td> |
| <a href="http://doc.qt.io/qt-5/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://doc.qt.io/qt-5/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://doc.qt.io/qt-5/dnd.html"> |
| Drag and Drop</a></td> |
| <td>Drag and drop provides a simple visual |
| mechanism which users can use to transfer |
| information between and within applications.</td> |
| </tr> |
| |
| </table> |
| \endraw |
| |
| See also \l {table-command} {\\table}, \l {header-command} |
| {\\header}, and \l {li-command} {\\li}. |
| |
| \target value-command |
| \section1 \\value |
| |
| The \\value command starts the documentation of a C++ enum item. |
| |
| The command's first argument is the value name. The value name may |
| be preceded by an optional \e since clause enclosed in square |
| brackets. The value description follows the value name. The description |
| ends at the next blank line or \\value. The arguments are rendered in a |
| table. |
| |
| Without a \e since clause, a \\value command could look like this: |
| |
| \code |
| \value QtInfoMsg A message generated by the qInfo() function. |
| \endcode |
| |
| The same command with a \e since clause would look like this: |
| |
| \code |
| \value [since 5.5] QtInfoMsg A message generated by the qInfo() function. |
| \endcode |
| |
| The documentation will be located in the associated class, header |
| file or namespace documentation. See the \l {enum-command} |
| {\\enum} documentation for an example. |
| |
| \note Since Qt 5.4, \\value command can also be used outside the |
| \l {enum-command} {\\enum} topic. In this case, QDoc renders a |
| two-column table listing the constant name (taken as-is from the |
| first argument) and its description. This can be used, for |
| example, in \l {qmlproperty-command}{\\qmlproperty} topic for |
| documenting acceptable values for a QML enumeration property. |
| |
| See also \l {enum-command} {\\enum} and \l {omitvalue-command} {\\omitvalue}. |
| |
| \target omitvalue-command |
| \section1 \\omitvalue |
| |
| The \\omitvalue command excludes a C++ enum item from the |
| documentation. |
| |
| The command's only argument is the name of the enum item that will |
| be omitted. See the \l {enum-command} {\\enum} documentation for |
| an example. |
| |
| See also \l {enum-command} {\\enum} and \l {value-command} |
| {\\value} \l {since-command}{\\since} |
| |
| \target list-command |
| \section1 \\list |
| |
| The \\list and \\endlist commands delimit a list of items. |
| |
| Create each list item with the \l {li-command} {\\li} command. A |
| list always contains one or more items. Lists can be nested. For |
| example: |
| |
| \code |
| / *! |
| \list |
| \li Qt Reference Documentation: Getting Started |
| \list |
| \li How to Learn Qt |
| \li Installation |
| \list |
| \li Qt/X11 |
| \li Qt/Windows |
| \li Qt/Mac |
| \li Qt/Embedded |
| \endlist |
| \li Tutorial and Examples |
| \endlist |
| \endlist |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \list |
| \li Qt Reference Documentation: Getting Started |
| \list |
| \li How to Learn Qt |
| \li Installation |
| \list |
| \li Qt/X11 |
| \li Qt/Windows |
| \li Qt/Mac |
| \li Qt/Embedded |
| \endlist |
| \li Tutorial and Examples |
| \endlist |
| \endlist |
| |
| The \\list command takes an optional argument providing |
| alternative appearances for the list items. |
| |
| \code |
| / *! |
| \list |
| \li How to Learn Qt |
| \li Installation |
| \li Tutorial and Examples |
| \endlist |
| * / |
| \endcode |
| |
| QDoc renders the list items with bullets (the default): |
| |
| \list |
| \li How to Learn Qt |
| \li Installation |
| \li Tutorial and Examples |
| \endlist |
| |
| If you provide 'A' as an argument to the \\list command, the |
| bullets are replaced with characters in alphabetical order: |
| |
| \list A |
| \li How to Learn Qt |
| \li Installation |
| \li Tutorial and Examples |
| \endlist |
| |
| If you replace 'A' with '1', the list items are numbered in |
| ascending order: |
| |
| \list 1 |
| \li How to Learn Qt |
| \li Installation |
| \li Tutorial and Examples |
| |
| \endlist |
| |
| If you provide 'i' as the argument, the bullets are replaced with |
| roman numerals: |
| |
| \list i |
| \li How to Learn Qt |
| \li Installation |
| \li Tutorial and Examples |
| \endlist |
| |
| Finally, you can make the list items appear with roman numbers |
| following in ascending order if you provide 'I' as the optional |
| argument: |
| |
| \list I |
| \li How to Learn Qt |
| \li Installation |
| \li 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 |
| \li How to Learn Qt |
| \li Installation |
| \li Tutorial and Examples |
| \endlist |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \list G |
| \li How to Learn Qt |
| \li Installation |
| \li Tutorial and Examples |
| \endlist |
| |
| See also \l {li-command} {\\li}. |
| |
| \target li-command |
| \section1 \\li (table cell, list item) |
| |
| The \\li command marks a table cell or a list item. This command |
| is only used in \l{table-command} {tables} and \l{list-command} |
| {lists}. |
| |
| It considers everything as its argument until the next \\li command, until the |
| next \l {table-command} {\\endtable}, or \l {list-command} {\\endlist} |
| command. See \l {table-command} {\\table} and \l {list-command} {\\list} |
| for examples. |
| |
| If the command is used within a table, you can also specify |
| how many rows or columns the item should span. |
| |
| \code |
| / *! |
| \table |
| \header |
| \li {3,1} This header cell spans three columns |
| but only one row. |
| \row |
| \li {2, 1} This table item spans two columns |
| but only one row |
| \li {1, 2} This table item spans only one column, |
| but two rows. |
| \row |
| \li A regular table item |
| \li A regular table item |
| \endtable |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \raw HTML |
| <table align="center" cellpadding="2" cellspacing="1" |
| border="0"> |
| |
| <tr valign="top" bgcolor="#a2c511"> |
| <th colspan="3" rowspan=" 1"> |
| This header cell spans three columns, but only one row. |
| </th> |
| </tr> |
| |
| <tr valign="top" bgcolor="#d0d0d0"> |
| <td colspan="2" rowspan=" 1"> |
| This table item spans two columns, but only one row. |
| </td> |
| <td rowspan=" 2"> |
| This table item spans only one column, but two rows. |
| </td> |
| </tr> |
| |
| <tr valign="top" bgcolor="#c0c0c0"> |
| <td>A regular table item</td> |
| <td>A regular table item</td> |
| </tr> |
| |
| </table> |
| \endraw |
| |
| If not specified, the item will span one column and one row. |
| |
| See also \l {table-command} {\\table}, \l {header-command} |
| {\\header}, and \l {list-command} {\\list}. |
| |
| */ |
| |
| |
| /*! |
| \page 11-qdoc-commands-specialcontent.html |
| \previouspage Tables and Lists |
| \nextpage Miscellaneous |
| |
| \title Special Content |
| |
| The document contents commands identify parts of the documentation, |
| parts with a special rendering, conceptual meaning or |
| function. |
| |
| \target quotation-command |
| \section1 \\quotation |
| |
| The \\quotation and \\endquotation commands delimit a long quotation. |
| |
| The text in the delimited block is surrounded by |
| \b{<blockquote>} and \b{</blockquote>} in the html output, |
| e.g.: |
| |
| \code |
| / *! |
| Although the prospect of a significantly broader market is |
| good news for Firstlogic, the notion also posed some |
| challenges. Dave Dobson, director of technology for the La |
| Crosse, Wisconsin-based company, said: |
| |
| \quotation |
| As our solutions were being adopted into new |
| environments, we saw an escalating need for easier |
| integration with a wider range of enterprise |
| applications. |
| \endquotation |
| * / |
| \endcode |
| |
| The text in the \b{\\quotation} block will appear in the generated HTML as: |
| |
| \code |
| <blockquote> |
| <p>As our solutions were being adopted into new environments, |
| we saw an escalating need for easier integration with a wider |
| range of enterprise applications.</p> |
| </blockquote> |
| \endcode |
| |
| The built-in style sheet for most browsers will render the |
| contents of the <blockquote> tag with left and right |
| indentations. The example above would be rendered as: |
| |
| \quotation |
| As our solutions were being adopted into new |
| environments, we saw an escalating need for easier |
| integration with a wider range of enterprise |
| applications. |
| \endquotation |
| |
| But you can redefine the \b{<blockquote>} tag in your style.css file. |
| |
| \target footnote-command |
| \section1 \\footnote |
| |
| The \\footnote and \\endfootnote commands delimit a footnote. |
| |
| The footnote is rendered at the bottom of the page. |
| |
| \warning The \b{\\footnote} and \b{\\endfootnote} commands |
| have not been implemented. The footnote is rendered as a regular |
| HTML paragraph. |
| |
| \target note-command |
| \section1 \\note |
| |
| The \\note command defines a new paragraph preceded by "Note:" |
| in bold. |
| |
| \target tableofcontents-command |
| \section1 \\tableofcontents |
| |
| The \\tableofcontents command has been disabled because QDoc |
| now generates a table of contents automatically. |
| |
| The automatically generated table of contents appears in the upper |
| righthand corner of the page. |
| |
| \target brief-command |
| \section1 \\brief |
| |
| The \\brief command introduces a one-sentence description of a |
| class, namespace, header file, property, or variable. |
| |
| The brief text is used to introduce the documentation of the |
| associated object, and in lists generated using the \l |
| {generatelist-command} {\\generatelist} command and the \l |
| {annotatedlist-command} {\\annotatedlist} command. |
| |
| The \\brief command can be used in two significant different ways: |
| \l {brief class} {One for classes, namespaces and header files}, |
| and \l {brief-property} {one for properties and variables}. |
| |
| \target brief-property |
| |
| When the \\brief command is used to describe a property or a |
| variable, the brief text must be a sentence fragment starting with |
| "whether" (for a boolean property or variable) or starting with |
| "the" (for any other property or variable). |
| |
| For example the boolean QWidget::isWindow property: |
| |
| \code |
| / *! |
| \property QWidget::isActiveWindow |
| \brief Whether this widget's window is the active window. |
| |
| The active window is the window that contains the widget that |
| has keyboard focus. |
| |
| When popup windows are visible, this property is \c true |
| for both the active window \e and the popup. |
| |
| \sa activateWindow(), QApplication::activeWindow() |
| * / |
| \endcode |
| |
| and the QWidget::geometry property |
| |
| \code |
| / *! |
| \property QWidget::geometry |
| \brief The geometry of the widget relative to its parent and |
| excluding the window frame. |
| |
| When changing the geometry, the widget, if visible, |
| receives a move event (moveEvent()) and/or a resize |
| event (resizeEvent()) immediately. |
| |
| ... |
| |
| \sa frameGeometry(), rect(), ... |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| \raw HTML |
| <h3>geometry : |
| <a href="http://doc.qt.io/qt-5/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 |
| \li \b {const QRect & geometry () const} |
| \li \b {void setGeometry ( int x, int y, int w, int h )} |
| \li \b {void setGeometry ( const QRect & )} |
| \endlist |
| |
| See also \l |
| {QWidget::frameGeometry()} {frameGeometry()}, \l |
| {QWidget::rect()} {rect()}, ... |
| \endquotation |
| |
| \target brief class |
| |
| When the \\brief command is used to describe a class, we recommend |
| using a complete sentence like this: |
| |
| \code |
| The <classname> class is|provides|contains|specifies... |
| \endcode |
| |
| \warning Do not repeat your detailed description with the same sentence as |
| the brief statement will be the first paragraph of the detailed |
| description. |
| |
| \code |
| / *! |
| \class PreviewWindow |
| \brief The PreviewWindow class is a custom widget |
| displaying the names of its currently set |
| window flags in a read-only text editor. |
| |
| The PreviewWindow class inherits QWidget. The widget |
| displays the names of its window flags set with the |
| setWindowFlags() function. It is also provided with a |
| QPushButton that closes the window. |
| |
| ... |
| |
| \sa QWidget |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| \raw HTML |
| <h1>PreviewWindow Class Reference</h1> |
| \endraw |
| |
| The PreviewWindow class is a custom widget displaying |
| the names of its currently set window flags in a |
| read-only text editor. \l {preview window} {More...} |
| |
| \raw HTML |
| <h3>Properties</h3> |
| \endraw |
| |
| \list |
| \li 52 properties inherited from QWidget |
| \li 1 property inherited from QObject |
| \endlist |
| |
| \raw HTML |
| <h3>Public Functions</h3> |
| \endraw |
| |
| \list |
| \li \l {constructor} {PreviewWindow}(QWidget *parent = 0) |
| \li void \l {function} {setWindowFlags}(Qt::WindowFlags flags) |
| \endlist |
| |
| \list |
| \li 183 public functions inherited from QWidget |
| \li 28 public functions inherited from QObject |
| \endlist |
| |
| \raw HTML |
| <h3>Public Slots</h3> |
| \endraw |
| |
| \list |
| \li 17 public slots inherited from QWidget |
| \li 1 public slot inherited from QObject |
| \endlist |
| |
| \raw HTML |
| <h3>Additional Inherited Members</h3> |
| \endraw |
| |
| \list |
| \li 1 signal inherited from QWidget |
| \li 1 signal inherited from QObject |
| \li 4 static public members inherited from QWidget |
| \li 4 static public members inherited from QObject |
| \li 39 protected functions inherited from QWidget |
| \li 7 protected functions inherited from QObject |
| \endlist |
| |
| \target preview window |
| |
| \raw HTML |
| <hr /> |
| <h2>Detailed Description</h2> |
| \endraw |
| |
| The PreviewWindow class is a custom widget displaying |
| the names of its currently set window flags in a |
| read-only text editor. |
| |
| The PreviewWindow class inherits QWidget. The widget |
| displays the names of its window flags set with the \l |
| {function} {setWindowFlags()} function. It is also |
| provided with a QPushButton that closes the window. |
| |
| ... |
| |
| See also QWidget. |
| |
| \raw HTML |
| <hr /> |
| <h2>Member Function Documentation</h2> |
| \endraw |
| |
| \target constructor |
| \raw HTML |
| <h3>PreviewWindow(QWidget *parent = 0)</h3> |
| \endraw |
| |
| Constructs a preview window widget with \e parent. |
| |
| \target function |
| \raw HTML |
| <h3>setWindowFlags(Qt::WindowFlags flags)</h3> |
| \endraw |
| |
| Sets the widgets flags using the |
| QWidget::setWindowFlags() function. |
| |
| Then runs through the available window flags, |
| creating a text that contains the names of the flags |
| that matches the flags parameter, displaying |
| the text in the widgets text editor. |
| \endquotation |
| |
| Using \\brief in a \l{namespace-command}{\\namespace}: |
| |
| \code |
| / *! |
| \namespace Qt |
| |
| \brief The Qt namespace contains miscellaneous identifiers |
| used throughout the Qt library. |
| * / |
| \endcode |
| |
| Using \\brief in a \l{headerfile-command}{\\headerfile}: |
| |
| \code |
| / *! |
| \headerfile <QtGlobal> |
| \title Global Qt Declarations |
| |
| \brief The <QtGlobal> header file provides basic |
| declarations and is included by all other Qt headers. |
| |
| \sa <QtAlgorithms> |
| * / |
| \endcode |
| |
| See also \l{property-command} {\\property}, \l{class-command} |
| {\\class}, \l{namespace-command} {\\namespace} and |
| \l{headerfile-command} {\\headerfile}. |
| |
| \target legalese-command |
| \section1 \\legalese |
| |
| The \\legalese and \\endlegalese commands delimit a license agreement. |
| |
| In the generated HTML, the delimited text is surrounded by a \b |
| {<div class="LegaleseLeft">} and \b {</div>} tags. |
| |
| An example of a license agreement enclosed in \\legalese |
| and \\endlegalese: |
| |
| \code |
| / *! |
| \legalese |
| Copyright 1996 Daniel Dardailler. |
| |
| Permission to use, copy, modify, distribute, and sell this |
| software for any purpose is hereby granted without fee, |
| provided that the above copyright notice appear in all |
| copies and that both that copyright notice and this |
| permission notice appear in supporting documentation, and |
| that the name of Daniel Dardailler not be used in |
| advertising or publicity pertaining to distribution of the |
| software without specific, written prior permission. Daniel |
| Dardailler makes no representations about the suitability of |
| this software for any purpose. It is provided "as is" |
| without express or implied warranty. |
| |
| Modifications Copyright 1999 Matt Koss, under the same |
| license as above. |
| \endlegalese |
| * / |
| \endcode |
| |
| It will appear in the generated HTML as: |
| |
| \code |
| <div class="LegaleseLeft"> |
| <p>Copyright 1996 Daniel Dardailler.</p> |
| <p>Permission to use, copy, modify, distribute, and sell |
| this software for any purpose is hereby granted without fee, |
| provided that the above copyright notice appear in all |
| copies and that both that copyright notice and this |
| permission notice appear in supporting documentation, and |
| that the name of Daniel Dardailler not be used in |
| advertising or publicity pertaining to distribution of the |
| software without specific, written prior permission. Daniel |
| Dardailler makes no representations about the suitability of |
| this software for any purpose. It is provided "as is" |
| without express or implied warranty.</p> |
| |
| <p>Modifications Copyright 1999 Matt Koss, under the same |
| license as above.</p> |
| </div> |
| \endcode |
| |
| If the \\endlegalese command is omitted, QDoc will process the |
| \\legalese command but considers the rest of the documentation |
| page as the license agreement. |
| |
| Ideally, the license text is located with the licensed code. |
| |
| Elsewhere, the documentation identified as \e{\\legalese} command |
| can be accumulated using \l {generatelist-command} {\\generatelist} |
| with \c {legalese} as the argument. This is useful for generating |
| an overview of the license agreements associated with the source |
| code. |
| |
| \note The output of the \c {\generatelist legalese} command includes |
| the \\legalese texts in the current documentation project only. If |
| the current documentation project depends on other modules, their |
| license texts will not be listed. |
| |
| \target warning-command |
| \section1 \\warning |
| |
| The \\warning command prepends "Warning:" to the command's |
| argument, in bold font. |
| |
| \code |
| / *! |
| Qt::HANDLE is a platform-specific handle type |
| for system objects. This is equivalent to |
| \c{void *} on Windows and macOS, and to |
| \c{unsigned long} on X11. |
| |
| \warning Using this type is not portable. |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| Qt::HANDLE is a platform-specific handle type |
| for system objects. This is equivalent to |
| \c{void *} on Windows and macOS, and to |
| \c{unsigned long} on X11. |
| |
| \warning Using this type is not portable. |
| \endquotation |
| |
| */ |
| |
| |
| /*! |
| \page 12-0-qdoc-commands-miscellaneous.html |
| \previouspage Special Content |
| \nextpage The QDoc Configuration File |
| |
| \title Miscellaneous |
| |
| These commands provide miscellaneous functions connected to the |
| visual appearance of the documentation, and to the process of |
| generating the documentation. |
| |
| \target annotatedlist-command |
| \section1 \\annotatedlist |
| |
| The \\annotatedlist command expands to a list of the members of a |
| group, each member listed with its \e {brief} text. Below is an |
| example from the Qt Reference Documentation: |
| |
| \code |
| / *! |
| ... |
| \section1 Drag and Drop Classes |
| |
| These classes deal with drag and drop and the necessary mime type |
| encoding and decoding. |
| |
| \annotatedlist draganddrop |
| |
| * / |
| \endcode |
| |
| This generates a list of all the C++ classes and/or QML types in |
| the \e{draganddrop} group. A C++ class or QML type in the |
| \e{draganddrop} group will have \e{\\ingroup draganddrop} in its |
| \e{\\class} or \e{\\qmltype} comment. |
| |
| |
| \target generatelist-command |
| \section1 \\generatelist |
| |
| The \\generatelist command expands to a list of links to the |
| documentation entities in a group. Below is an example from the Qt |
| Reference Documentation: |
| |
| \code |
| / *! |
| \page classes.html |
| \title All Classes |
| |
| For a shorter list that only includes the most |
| frequently used classes, see \l{Qt's Main Classes}. |
| |
| \generatelist classes Q |
| * / |
| \endcode |
| |
| This generates the \e {All Classes} page. The command accepts the |
| following arguments: |
| |
| \target table example |
| \section2 \c annotatedclasses |
| |
| The \c annotatedclasses argument provides a table containing the |
| names of all the classes, and a description of each class. Each |
| class name is a link to the class's reference documentation. For |
| example: |
| |
| \table |
| \row |
| \li QDial |
| \li Rounded range control (like a speedometer or potentiometer) |
| \row |
| \li QDialog |
| \li The base class of dialog windows |
| \row |
| \li QDir |
| \li Access to directory structures and their contents |
| \endtable |
| |
| A C++ class is documented with the \l {class-command} {\\class} |
| command. The annotation for the class is taken from the argument |
| of the class comment's \l {brief-command} {\\brief} command. |
| |
| \section2 \c annotatedexamples |
| |
| The \c annotatedexamples argument provides a complete list of all |
| examples as a set of tables containing the titles of all the |
| examples, and a description of each example. Each title is a |
| link to the example's documentation. |
| |
| A separate table for each module (that has documented examples) |
| is generated, provided that the module has defined a |
| navigation.landingpage configuration variable. The \e landingpage |
| variable is used as a title for a header that precedes each table. |
| |
| \section2 \c annotatedattributions |
| |
| The \c annotatedattributions argument provides a complete list of all |
| attributions as a set of tables containing the titles of all the |
| attributions, and a description of each attribution. Each title is a |
| link to the attribution's page. |
| |
| A separate table for each module (that has attributions) |
| is generated, provided that the module has defined a |
| navigation.landingpage configuration variable. The \e landingpage |
| variable is used as a title for a header that precedes each table. |
| |
| \target list example |
| \section2 \c {classes <prefix>} |
| |
| The \c classes argument provides a complete alphabetical list of |
| the classes. The second argument, \c{<prefix>}, is the common |
| prefix for the class names. The class names will be sorted on the |
| character that follows the common prefix. e.g. The common prefix |
| for the Qt classes is \c Q. The common prefix argument is |
| optional. If no common prefix is provided, the class names will |
| be sorted on their first character. |
| |
| Each class name becomes a link to the class's reference |
| documentation. This command is used to generate the |
| \e {All Classes} page this way: |
| |
| \code |
| / *! |
| \page classes.html |
| \title All Classes |
| \ingroup classlists |
| |
| \brief Alphabetical list of classes. |
| |
| This is a list of all Qt classes. For classes that |
| have been deprecated, see the \l{Obsolete Classes} |
| list. |
| |
| \generatelist classes Q |
| * / |
| \endcode |
| |
| A C++ class is documented with the \l {class-command} {\\class} |
| command. |
| |
| \section2 \c classesbymodule |
| |
| When this argument is used, a second argument is required, which |
| specifies the module whose classes are to be listed. QDoc |
| generates a table containing those classes. Each class is listed |
| with the text of its \l{brief-command} {\\brief} command. |
| |
| For example, this command can be used on a module page as follows: |
| |
| \code |
| / *! |
| \page phonon-module.html |
| \module Phonon |
| \title Phonon Module |
| \ingroup modules |
| |
| \brief Contains namespaces and classes for multimedia functionality. |
| |
| \generatelist{classesbymodule Phonon} |
| |
| ... |
| |
| * / |
| \endcode |
| |
| Each class that is a member of the specified module must be marked |
| with the \l {inmodule-command} {\\inmodule} command in its \\class |
| comment. |
| |
| \section2 \c qmltypesbymodule |
| |
| Similar to \c classesbymodule argument, but used for listing the |
| QML types from the QML module specified with the second argument. |
| |
| \note Support for this argument was introduced in QDoc 5.6. |
| |
| \section2 \c jstypesbymodule |
| |
| Similar to \c classesbymodule argument, but used for listing the |
| JavaScript types from the module specified with the second argument. |
| |
| \note Support for this argument was introduced in QDoc 5.6. |
| |
| \section2 \c {examplefiles [regular_expression]} |
| |
| The \c examplefiles argument lists the files that are part of |
| an example project. The optional second argument is a regular |
| expression; if provided, only the files whose path matches with |
| the regular expression are listed. |
| |
| The \c examplefiles argument can be only used within example |
| documentation (see \l {example-command}{\\example}), and is |
| typically used together with the \l {noautolist-command}{\\noautolist} |
| command. |
| |
| \section2 \c {exampleimages [regular_expression]} |
| |
| The \c exampleimages argument lists the images that are part of |
| an example project. The optional second argument is a regular |
| expression; if provided, only the image files whose path matches |
| with the regular expression are listed. |
| |
| The \c exampleimages argument can be only used within example |
| documentation (see \l {example-command}{\\example}), and is |
| typically used together with the \l {noautolist-command}{\\noautolist} |
| command. |
| |
| \section2 \c functionindex |
| |
| The \c functionindex argument provides a complete alphabetical |
| list of all the documented member functions. It is normally used |
| only to generate the \e {Qt function index} page |
| this way: |
| |
| \code |
| / *! |
| \page functions.html |
| \title All Functions |
| \ingroup funclists |
| |
| \brief All documented Qt functions listed alphabetically with a |
| link to where each one is declared. |
| |
| This is the list of all documented member functions and global |
| functions in the Qt API. Each function has a link to the |
| class or header file where it is declared and documented. |
| |
| \generatelist functionindex |
| * / |
| \endcode |
| |
| \section2 \c legalese |
| |
| The \c legalese argument tells QDoc to generate a list of licenses in |
| the current documentation project. Each license is identified using |
| the \l {legalese-command} {\\legalese} command. |
| |
| \section2 \c overviews |
| |
| The \c overviews argument is used to tell QDoc to generate a list |
| by concatenating the contents of all the \l {group-command} |
| {\\group} pages. Qt uses it to generate the \e {overviews} page |
| this way: |
| |
| \code |
| / *! |
| \page overviews.html |
| |
| \title All Overviews and HOWTOs |
| |
| \generatelist overviews |
| * / |
| \endcode |
| |
| \section2 \c attributions |
| |
| The \c attributions argument is used to tell QDoc to generate a list |
| of attributions in the documentation. |
| |
| \section2 \c related |
| |
| The \c related argument is used in combination with the \l |
| {group-command} {\\group} and \l {ingroup-command} {\\ingroup} |
| commands to list all the overviews related to a specified |
| group. For example, the page for the \e {Programming with Qt} |
| page is generated this way: |
| |
| \code |
| / *! |
| \group qt-basic-concepts |
| \title Programming with Qt |
| |
| \brief The basic architecture of the Qt cross-platform application and UI framework. |
| |
| Qt is a cross-platform application and UI framework for |
| writing web-enabled applications for desktop, mobile, and |
| embedded operating systems. This page contains links to |
| articles and overviews explaining key components and |
| techniuqes used in Qt development. |
| |
| \generatelist {related} |
| * / |
| \endcode |
| |
| Each page listed on this group page contains the command: |
| |
| \code |
| \ingroup qt-basic-concepts |
| \endcode |
| |
| \target if-command |
| \section1 \\if |
| |
| The \\if command and the corresponding \\endif command |
| enclose parts of a QDoc comment that only will be included if |
| the condition specified by the command's argument is true. |
| |
| The command reads the rest of the line and parses it as an C++ #if |
| statement. |
| |
| \code |
| / *! |
| \if defined(opensourceedition) |
| |
| \note This edition is for the development of |
| \l{Qt Open Source Edition} {Free and Open Source} |
| software only; see \l{Qt Commercial Editions}. |
| |
| \endif |
| * / |
| \endcode |
| |
| This QDoc comment will only be rendered if the \c |
| opensourceedition preprocessor symbol is defined, and specified in |
| the \l {defines-variable} {defines} variable in the configuration |
| file to make QDoc process the code within #ifdef and #endif: |
| |
| \code |
| defines = opensourceedition |
| \endcode |
| |
| You can also define the preprocessor symbol manually on the |
| command line. For more information see the documentation of the \l |
| {defines-variable} {defines} variable. |
| |
| See also \l{endif-command} {\\endif}, \l{else-command} {\\else}, |
| \l {defines-variable} {defines} and \l {falsehoods-variable} |
| {falsehoods}. |
| |
| \target endif-command |
| \section1 \\endif |
| |
| The \\endif command and the corresponding \\if command |
| enclose parts of a QDoc comment that will be included if |
| the condition specified by the \l {if-command} {\\if} command's |
| argument is true. |
| |
| For more information, see the documentation of the \l {if-command} |
| {\\if} command. |
| |
| See also \l{if-command} {\\if}, \l{else-command} {\\else}, \l |
| {defines-variable} {defines} and \l {falsehoods-variable} |
| {falsehoods}. |
| |
| \target else-command |
| \section1 \\else |
| |
| The \\else command specifies an alternative if the |
| condition in the \l {if-command} {\\if} command is false. |
| |
| The \\else command can only be used within \l {if-command} |
| {\\if...\\endif} commands, but is useful when there is only two |
| alternatives. |
| |
| \target include-command |
| \section1 \\include |
| |
| The \\include command sends all or part of the file specified by |
| its first argument to the QDoc input stream to be processed as a |
| QDoc comment snippet. |
| |
| The command is useful when some snippet of commands or text is to |
| be used in multiple places in the documentation. Use the \\include |
| command wherever you want to insert a snippet into the documentation. |
| The file containing the snippet to include, must be located under the |
| path(s) listed in the \l{sourcedirs-variable}{sourcedirs} or |
| \l{exampledirs-variable}{exampledirs} QDoc configuration variable. |
| It can be either any source file parsed by QDoc (or even the same one |
| where \\include command is used), or any other text file. To store |
| snippets in a separate file that is not meant to be parsed by QDoc, |
| use a file extension that is not listed in |
| \l{sources.fileextensions-variable}{sources.fileextensions}; |
| for example, \c .qdocinc. |
| |
| The command can have either one or two arguments. The first |
| argument is always a file name. The contents of the file must be |
| QDoc input, in other words, a sequence of QDoc commands and text, but |
| without the enclosing QDoc comment \c{/}\c{*!} ... \c{*}\c{/} delimiters. |
| If you want to include the entire named file, don't use the second |
| argument. If you want to include only part of the file, see the |
| \l{2-argument-form}{two argument form} below. Here is an example |
| of the one argument form: |
| |
| \code |
| / *! |
| \page corefeatures.html |
| \title Core Features |
| |
| \include examples/signalandslots.qdocinc |
| \include examples/objectmodel.qdocinc |
| \include examples/layoutmanagement.qdocinc |
| * / |
| \endcode |
| |
| QDoc renders this page \l{corefeatures.html} {as shown here}. |
| |
| \target 2-argument-form |
| \section2 \\include filename snippet-identifier |
| |
| It is a waste of time to make a separate \c .qdocinc file for every |
| QDoc include snippet you want to use in multiple places in the |
| documentation, especially given that you probably have to put the |
| copyright/license notice in every one of these files. So if you |
| have a large number of snippets to be included, you can put them all in a |
| single file if you want, and surround each one with: |
| \code |
| //! [snippet-id1] |
| |
| QDoc commands and text... |
| |
| //! [snippet-id1] |
| |
| //! [snippet-id2] |
| |
| More QDoc commands and text... |
| |
| //! [snippet-id2] |
| \endcode |
| |
| Then you can use the two-argument form of the command: |
| |
| \code |
| \input examples/signalandslots.qdocinc snippet-id2 |
| \input examples/objectmodel.qdocinc another-snippet-id |
| \endcode |
| |
| It works as expected. The sequence of QDoc commands and text found |
| between the two tags with the same name as the second argument is |
| sent to the QDoc input stream. You can even have nested snippets. |
| |
| \note Snippet identifiers work also within documentation comment |
| (\beginqdoc .. \endqdoc) blocks, so it's not necessary to use a |
| separate \c .qdocinc file. When processing a comment block, QDoc |
| removes any \c {//!} comment lines from the generated output. |
| |
| \target meta-command |
| \section1 \\meta |
| |
| The \\meta command is used for adding metadata to example documentation, |
| and when generating HTML output for specifying the \e maintainer(s) of a |
| C++ class. |
| |
| The command has two arguments: the first argument is the name of the |
| metadata attribute, and the second argument is the |
| value for the attribute. Each argument should be enclosed in curly |
| brackets, as shown in this example: |
| |
| \code |
| / *! |
| \class QWidget |
| \brief The QWidget class is the base class of all user interface objects. |
| |
| \ingroup basicwidgets |
| |
| \meta {technology} {User Interface} |
| \meta {platform} {macOS 10.6} |
| \meta {platform} {MeeGo} |
| \meta {audience} {user} |
| \meta {audience} {programmer} |
| \meta {audience} {designer} |
| * / |
| \endcode |
| |
| When running QDoc to generate HTML, the example above will have no |
| effect on the generated output. |
| |
| \b {Example Metadata} |
| |
| Another use for \\meta command is to include metadata (tags) in |
| \l {example-command}{\\example} documentation. By default, QDoc |
| generates example tags based on the example's \l {title-command}{\\title} |
| and module name. These tags are displayed in Qt Creator's Welcome mode, |
| helping users navigate the list of examples. |
| |
| Additional tags can be created with \c {\\meta {tag} {tag1,[tag2,...]}}. |
| For example: |
| \badcode |
| / *! |
| \example helloworld |
| \title Hello World Example |
| \meta {tag} {tutorial,basic} |
| * / |
| \endcode |
| |
| This would result in the following tags: \e {tutorial,basic,hello,world}. |
| Common words such as \e example are ignored. |
| |
| \b {Example Install Paths} |
| |
| The \\meta command combined with an argument \c installpath specifies the |
| location of an installed example. This value overrides the one that is set |
| using the \c examplesinstallpath configuration variable. |
| |
| \badcode |
| / *! |
| \example helloworld |
| \title Hello World Example |
| \meta {installpath} {tutorials} |
| * / |
| \endcode |
| |
| See also \l {examplesinstallpath}. |
| |
| \target noautolist-command |
| \section1 \\noautolist |
| |
| The \\noautolist command indicates that the annotated list of C++ |
| classes or QML types, which is automatically generated at the |
| bottom of the C++ or QML module page should be omitted, because |
| the classes or types have been listed manually. This command can |
| also be used with the \l {group-command}{\\group} command to omit |
| the list of group members, when they are listed manually. |
| |
| The command must stand on its own line. See \l {Qt Sensors QML Types} for |
| an example. The page is generated from \c {qtsensors5.qdoc}. There you will |
| find a QDoc comment containing the \c{\qmlmodule} command for the QtSensors |
| module. The same QDoc comment contains two \c {\annotated-list} commands to |
| list the QML types in two separate groups. The QML types have been divided |
| into these two groups because it makes more sense to list them this way than |
| it does to list them in a single alphabetical list. At the bottom of the |
| comment, \c {\noautolist} has been used to tell QDoc not to generate the |
| automatic annotated list. |
| |
| This command was introduced in QDoc 5.6. |
| |
| Since Qt 5.10, this command can be applied also to \l{example-command} |
| {\\example} documentation, where it causes the automatically generated |
| list of files and images belonging to an example project to be omitted. |
| |
| \target omit-command |
| \section1 \\omit |
| |
| The \\omit command and the corresponding \\endomit command |
| delimit parts of the documentation that you want QDoc to skip. For |
| example: |
| |
| \code |
| / *! |
| \table |
| \row |
| \li Basic Widgets |
| \li Basic GUI widgets such as buttons, comboboxes |
| and scrollbars. |
| |
| \omit |
| \row |
| \li Component Model |
| \li Interfaces and helper classes for the Qt |
| Component Model. |
| \endomit |
| |
| \row |
| \li Database Classes |
| \li Database related classes, e.g. for SQL databases. |
| \endtable |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \raw HTML |
| <table align="center" cellpadding="2" |
| cellspacing="1" border="0"> |
| |
| <tr valign="top" bgcolor="#d0d0d0"> |
| <td>Basic Widgets</td> |
| <td>Basic GUI widgets such as buttons, comboboxes |
| and scrollbars.</td> |
| </tr> |
| |
| <tr valign="top" bgcolor="#c0c0c0"> |
| <td>Database Classes</td> |
| <td>Database related classes, e.g. for SQL databases.</td> |
| </tr> |
| </table> |
| \endraw |
| |
| \target raw-command |
| \section1 \\raw (avoid) |
| |
| The \\raw command and the corresponding |
| \\endraw command delimit a block of raw mark-up language code. |
| |
| \note Avoid using this command if possible. If you are trying to generate |
| special table or list behavior, try to get the behavior you want |
| using the \l {span-command} {\\span} and \l {div-command} {\\div} |
| commands in your \l {table-command} {\\table} or \l {list-command} |
| {\\list}. |
| |
| The command takes an argument specifying the code's format. |
| Currently, the only supported format is HTML. |
| |
| The \\raw command is useful if you want some special HTML effects |
| in your documentation. |
| |
| \code |
| / *! |
| Qt has some predefined QColor objects. |
| |
| \raw HTML |
| <style type="text/css" id="colorstyles"> |
| #color-blue { background-color: #0000ff; color: #ffffff } |
| #color-darkBlue { background-color: #000080; color: #ffffff } |
| #color-cyan { background-color: #00ffff; color: #000000 } |
| </style> |
| |
| <p> |
| <tt id="color-blue">Blue(#0000ff)</tt>, |
| <tt id="color-darkBlue">dark blue(#000080)</tt> and |
| <tt id="color-cyan">cyan(#00ffff)</tt>. |
| </p> |
| \endraw |
| * / |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| Qt has some predefined QColor objects. |
| |
| \raw HTML |
| <style type="text/css" id="colorstyles"> |
| #color-blue { background-color: #0000ff; color: #ffffff } |
| #color-darkBlue { background-color: #000080; color: #ffffff } |
| #color-cyan { background-color: #00ffff; color: #000000 } |
| </style> |
| |
| <p> |
| <tt id="color-blue">Blue(#0000ff)</tt>, |
| <tt id="color-darkBlue">dark blue(#000080)</tt> and |
| <tt id="color-cyan">cyan(#00ffff)</tt>. |
| </p> |
| \endraw |
| \endquotation |
| |
| \note But you can achieve the exact same thing using QDoc |
| commands. In this case, all you have to do is include the color |
| styles in your style.css file. Then you can write: |
| |
| \code |
| \tt {\span {id="color-blue"} {Blue(#0000ff)}}, |
| \tt {\span {id="color-darkBlue"} {dark blue(#000080)}} and |
| \tt {\span {id="color-cyan"} {cyan(#00ffff)}}. |
| \endcode |
| |
| ...which is rendered as: |
| |
| \tt {\span {id="color-blue"} {Blue(#0000ff)}}, |
| \tt {\span {id="color-darkBlue"} {dark blue(#000080)}} and |
| \tt {\span {id="color-cyan"} {cyan(#00ffff)}}. |
| |
| \target unicode-command |
| \section1 \\unicode |
| |
| The \\unicode command allows you to insert an arbitrary Unicode |
| character in the document. |
| |
| The command takes an argument specifying the character as an |
| integer. By default, base 10 is assumed, unless a '0x' or '0' |
| prefix is specified (for base 16 and 8, respectively). For |
| example: |
| |
| \code |
| O G\unicode{0xEA}nio e as Rosas |
| |
| \unicode 0xC0 table en famille avec 15 \unicode 0x20AC par jour |
| |
| \unicode 0x3A3 \e{a}\sub{\e{i}} |
| \endcode |
| |
| QDoc renders this as: |
| |
| \quotation |
| O G\unicode{0xEA}nio e as Rosas |
| |
| \unicode 0xC0 table en famille avec 15 \unicode 0x20AC par jour |
| |
| \unicode 0x3A3 \e{a}\sub{\e{i}} |
| \endquotation |
| */ |
| |