1/**************************************************************************** 2** 3** Copyright (C) 2020 The Qt Company Ltd. 4** Contact: https://www.qt.io/licensing/ 5** 6** This file is part of the documentation of the Qt Toolkit. 7** 8** $QT_BEGIN_LICENSE:FDL$ 9** Commercial License Usage 10** Licensees holding valid commercial Qt licenses may use this file in 11** accordance with the commercial license agreement provided with the 12** Software or, alternatively, in accordance with the terms contained in 13** a written agreement between you and The Qt Company. For licensing terms 14** and conditions see https://www.qt.io/terms-conditions. For further 15** information use the contact form at https://www.qt.io/contact-us. 16** 17** GNU Free Documentation License Usage 18** Alternatively, this file may be used under the terms of the GNU Free 19** Documentation License version 1.3 as published by the Free Software 20** Foundation and appearing in the file included in the packaging of 21** this file. Please review the following information to ensure 22** the GNU Free Documentation License version 1.3 requirements 23** will be met: https://www.gnu.org/licenses/fdl-1.3.html. 24** $QT_END_LICENSE$ 25** 26****************************************************************************/ 27 28/*! 29 \page 03-qdoc-commands-markup.html 30 \previouspage Naming Things 31 \nextpage Text Markup 32 33 \title Markup Commands 34 35 The markup commands indicate the generated documentation's visual 36 appearance and logical structure. 37 38 \list 39 \li \l {a-command} {\\a} 40 \li \l {annotatedlist-command} {\\annotatedlist} 41 \li \l {b-command} {\\b} 42 \li \l {badcode-command} {\\badcode} 43 \li \l {b-command} {\\bold} (deprecated, use \\b) 44 \li \l {brief-command} {\\brief} 45 \li \l {c-command} {\\c} 46 \li \l {caption-command} {\\caption} 47 \li \l {code-command} {\\code} 48 \li \l {codeline-command} {\\codeline} 49 \li \l {div-command} {\\div} 50 \li \l {dots-command} {\\dots} 51 \li \l {e-command} {\\e} 52 \li \l {else-command} {\\else} 53 \li \l {endif-command} {\\endif} 54 \li \l {footnote-command} {\\footnote} 55 \li \l {generatelist-command} {\\generatelist} 56 \li \l {header-command} {\\header} 57 \li \l {e-command} {\\i} (deprecated, use \\e) 58 \li \l {if-command} {\\if} 59 \li \l {image-command} {\\image} 60 \li \l {include-command} {\\include} 61 \li \l {include-command} {\\input} 62 \li \l {inlineimage-command} {\\inlineimage} 63 \li \l {keyword-command} {\\keyword} 64 \li \l {l-command} {\\l} 65 \li \l {legalese-command} {\\legalese} 66 \li \l {li-command} {\\li} 67 \li \l {list-command} {\\list} 68 \li \l {meta-command} {\\meta} 69 \li \l {noautolist-command} {\\noautolist} 70 \li \l {newcode-command} {\\newcode} 71 \li \l {li-command} {\\o} (deprecated, use \\li) 72 \li \l {note-command} {\\note} 73 \li \l {oldcode-command} {\\oldcode} 74 \li \l {omit-command} {\\omit} 75 \li \l {printline-command} {\\printline} 76 \li \l {printto-command} {\\printto} 77 \li \l {printuntil-command} {\\printuntil} 78 \li \l {qml-command}{\\qml} 79 \li \l {quotation-command} {\\quotation} 80 \li \l {quotefile-command} {\\quotefile} 81 \li \l {quotefromfile-command} {\\quotefromfile} 82 \li \l {raw-command} {\\raw} 83 \li \l {row-command} {\\row} 84 \li \l {sa-command} {\\sa} 85 \li \l {sectionOne-command} {\\section1} 86 \li \l {sectionTwo-command} {\\section2} 87 \li \l {sectionThree-command} {\\section3} 88 \li \l {sectionFour-command} {\\section4} 89 \li \l {skipline-command} {\\skipline} 90 \li \l {skipto-command} {\\skipto} 91 \li \l {skipuntil-command} {\\skipuntil} 92 \li \l {snippet-command} {\\snippet} 93 \li \l {span-command} {\\span} 94 \li \l {sub-command} {\\sub} 95 \li \l {sup-command} {\\sup} 96 \li \l {table-command} {\\table} 97 \li \l {tableofcontents-command} {\\tableofcontents} 98 \li \l {target-command} {\\target} 99 \li \l {tt-command} {\\tt} 100 \li \l {uicontrol-command} {\\uicontrol} 101 \li \l {underline-command} {\\underline} 102 \li \l {raw-command} {\\unicode} 103 \li \l {warning-command} {\\warning} 104 \li \l {backslash-command} {\\\\} 105 \endlist 106*/ 107 108 109/*! 110 \page 04-qdoc-commands-textmarkup.html 111 \previouspage Markup Commands 112 \nextpage Document Structure 113 114 \title Text Markup 115 116 The text formatting commands indicate how text is to be rendered. 117 118 \target a-command 119 \section1 \\a (parameter marker) 120 121 The \\a command tells QDoc the next word is a formal parameter name. 122 123 A warning is emitted when a formal parameter is not documented or 124 is misspelled, so when you document a function you should mention 125 each formal parameter by name in the function description, 126 preceded by the \\a command. The parameter name is then rendered 127 in italics. 128 129 \code 130 / *! 131 Constructs a line edit containing the text 132 \a contents. The \a parent parameter is sent 133 to the QWidget constructor. 134 * / 135 136 QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent) 137 { 138 ... 139 } 140 141 \endcode 142 143 QDoc renders this as: 144 145 \quotation 146 \b {QLineEdit::QLineEdit ( const QString & 147 contents, QWidget *parent )} 148 149 Constructs a line edit containing the text \a contents. 150 The \a parent parameter is sent to the QWidget constructor. 151 \endquotation 152 153 The formal parameter name may be enclosed between curly brackets, 154 but that isn't required. 155 156 \target c-command 157 \section1 \\c (code font) 158 159 The \\c command is used for rendering variable names, user-defined 160 class names, and C++ keywords (for example, \c int and \c for) in the code 161 font. 162 163 The command renders its argument using a monospace font. For 164 example: 165 166 \code 167 / *! 168 The \c AnalogClock class provides a clock widget with hour 169 and minute hands that is automatically updated every 170 few seconds. 171 * / 172 \endcode 173 174 QDoc renders this as: 175 176 \quotation 177 The \c AnalogClock class provides a clock widget with hour 178 and minute hands, which are automatically updated every 179 few seconds. 180 \endquotation 181 182 If the text to be rendered in the code font contains spaces, enclose the 183 entire text in curly brackets. 184 185 \code 186 \c {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)} 187 \endcode 188 189 QDoc renders this as: 190 191 \quotation 192 \c {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)} 193 \endquotation 194 195 The \\c command accepts the special character \c \ within its 196 argument, which renders it as a normal character. So if you want 197 to use nested commands, you must use the \l {tt-command} {teletype 198 (\\tt)} command instead. 199 200 See also \l {tt-command} {\\tt} and \l {code-command} {\\code}. 201 202 \target div-command 203 \section1 \\div 204 205 The \\div and \\enddiv commands delimit a large or small block of 206 text (which may include other QDoc commands) to which special 207 formatting attributes should be applied. 208 209 An argument must be provided in curly braces, as in the QDoc 210 comment shown below. The argument is not interpreted but is used 211 as attribute(s) of the tag that is output by QDoc. 212 213 For example, we might want to render an inline image so that it 214 floats to the right of the current block of text: 215 216 \code 217 / *! 218 \div {class="float-right"} 219 \inlineimage qml-column.png 220 \enddiv 221 222 * / 223 \endcode 224 225 If QDoc is generating HTML, it will translate these commands to: 226 227 \code 228 <div class="float-right"><p><img src="images/qml-column.png" /></p></div> 229 \endcode 230 231 For HTML, the attribute value \e {float-right} then will refer to 232 a clause in the style.css file, which in this case could be: 233 234 \code 235 div.float-right 236 { 237 float: right; margin-left: 2em 238 } 239 \endcode 240 241 \note Note that the \b {\\div} command can be nested. 242 243 Below you can find an example taken from the index.qdoc file used to 244 generate index.html for Qt 4.7: 245 246 \code 247 \div {class="indexbox guide"} 248 \div {class="heading"} 249 Qt Developer Guide 250 \enddiv 251 \div {class="indexboxcont indexboxbar"} 252 \div {class="section indexIcon"} \emptyspan 253 \enddiv 254 \div {class="section"} 255 Qt is a cross-platform application and UI 256 framework. Using Qt, you can write web-enabled 257 applications once and deploy them across desktop, 258 mobile and embedded operating systems without 259 rewriting the source code. 260 \enddiv 261 \div {class="section sectionlist"} 262 \list 263 \li \l{Getting Started} 264 \li \l{Installation} {Installation} 265 \li \l{how-to-learn-qt.html} {How to learn Qt} 266 \li \l{tutorials.html} {Tutorials} 267 \li \l{Qt Examples} {Examples} 268 \li \l{qt4-7-intro.html} {What's new in Qt 4.7} 269 \endlist 270 \enddiv 271 \enddiv 272 \enddiv 273 \endcode 274 275 When all the class attribute values are defined as they are in the 276 style.css file that is used for rendering the Qt documentation, 277 the above example is rendered as: 278 279 \div {class="indexbox guide"} 280 \div {class="heading"} 281 Qt Developer Guide 282 \enddiv 283 \div {class="indexboxcont indexboxbar"} 284 \div {class="section indexIcon"} \emptyspan 285 \enddiv 286 \div {class="section"} 287 Qt is a cross-platform application and UI 288 framework. Using Qt, you can write web-enabled 289 applications once and deploy them across desktop, 290 mobile and embedded operating systems without 291 rewriting the source code. 292 \enddiv 293 \div {class="section sectionlist"} 294 \list 295 \li Getting Started 296 \li Installation 297 \li How to learn Qt 298 \li Tutorials 299 \li Examples 300 \li What's new in Qt 4.7 301 \endlist 302 \enddiv 303 \enddiv 304 \enddiv 305 306 See also \l {span-command} {\\span}. 307 308 \target span-command 309 \section1 \\span 310 311 The \\span command applies special formatting to a small block of text. 312 313 Two arguments must be provided, each argument in curly braces, as 314 shown in the QDoc comment below. The first argument is not 315 interpreted, but specifies the formatting attribute(s) of the tag 316 output by QDoc. The second argument is the text to be rendered with 317 the special formatting attributes. 318 319 For example, we might want to render the first word of each 320 element in a numeric list in blue. 321 322 \code 323 / *! 324 Global variables with complex types: 325 \list 1 326 \li \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14 327 \li \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15 328 \li \span {class="variableName"} {constComplex1} in globals.cpp at line 16 329 \li \span {class="variableName"} {constComplex2} in globals.cpp at line 17 330 \endlist 331 * / 332 \endcode 333 334 Class \e {variableName} refers to a clause in your style.css. 335 336 \code 337 .variableName 338 { 339 font-family: courier; 340 color: blue 341 } 342 \endcode 343 344 Using the \e {variableName} clause shown above, the example is rendered as: 345 346 Global variables with complex types: 347 \list 1 348 \li \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14 349 \li \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15 350 \li \span {class="variableName"} {constComplex1} in globals.cpp at line 16 351 \li \span {class="variableName"} {constComplex2} in globals.cpp at line 17 352 \endlist 353 354 \note The \b span command does not cause a new paragraph to be 355 started. 356 357 See also \l {div-command} {\\div}. 358 359 \target tt-command 360 \section1 \\tt (teletype font) 361 362 The \\tt command renders its argument in a monospace font. This 363 command behaves just like the \l {c-command} {\\c} command, except 364 that \\tt allows you to nest QDoc commands within the argument 365 (e.g. \l {e-command} {\\e}, \l {b-command} {\\b} and \l 366 {underline-command} {\\underline}). 367 368 \code 369 / *! 370 After having populated the main container with 371 child widgets, \c setupUi() scans the main container's list of 372 slots for names with the form 373 \tt{on_\e{objectName}_\e{signalName}().} 374 * / 375 \endcode 376 377 QDoc renders this as: 378 379 \quotation 380 After having populated the main container with 381 child widgets, \c setupUi() scans the main container's list of 382 slots for names with the form 383 \tt{on_\e{objectName}_\e{signalName}().} 384 \endquotation 385 386 If the text to be rendered in the code font contains spaces, enclose the 387 entire text in curly brackets. 388 389 \code 390 \tt {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)} 391 \endcode 392 393 QDoc renders this as: 394 395 \quotation 396 \tt {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)} 397 \endquotation 398 399 See also \l {c-command} {\\c}. 400 401 \target b-command 402 \section1 \\b 403 404 The \\b command renders its argument in bold font. This command used 405 to be called \\bold. 406 407 \code 408 / *! 409 This is regular text; \b {this text is 410 rendered using the \\b command}. 411 * / 412 \endcode 413 414 QDoc renders this as: 415 416 \quotation 417 This is regular text; \b {this text is rendered using 418 the \\b command}. 419 \endquotation 420 421 \target e-command 422 \section1 \\e (emphasis, italics) 423 424 The \\e command renders its argument in a special font, normally italics. This 425 command used to be called \\i, which is now deprecated. 426 427 If the argument contains spaces or other punctuation, enclose the 428 argument in curly brackets. 429 430 \code 431 / *! 432 Here, we render \e {a few words} in italics. 433 * / 434 \endcode 435 436 QDoc renders this as: 437 438 \quotation 439 Here, we render \e {a few words} in italics. 440 \endquotation 441 442 If you want to use other QDoc commands within an argument that 443 contains spaces, you always need to enclose the argument in 444 braces. But QDoc is smart enough to count parentheses [3], so you 445 don't need braces in cases like this: 446 447 \code 448 / *! 449 An argument can sometimes contain whitespaces, 450 for example: \e QPushButton(tr("A Brand New Button")) 451 * / 452 \endcode 453 454 QDoc renders this as: 455 456 \quotation 457 An argument can sometimes contain whitespaces, 458 for example: \e QPushButton(tr("A Brand New Button")) 459 \endquotation 460 461 Finally, trailing punctuation is not included in an argument [4], 462 nor is "'s" [5] 463 464 \raw HTML 465 <table align="center" cellpadding="2" 466 cellspacing="1" border="0"> 467 <tr valign="top" bgcolor="#a2c511"> 468 <th></th> 469 <th>QDoc Syntax</th> 470 <th>Generated Documentation</th> 471 </tr> 472 473 <tr valign="top" bgcolor="#d0d0d0"> 474 <td>1</td> 475 <td>A variation of a command button is a \e menu 476 button.</td> 477 <td>A variation of a command button is a <i>menu</i> 478 button.</td> 479 </tr> 480 481 <tr valign="top" bgcolor="#c0c0c0"> 482 <td>2</td> 483 <td>The QPushButton widget provides a 484 \e {command button}.</td> 485 <td>The QPushButton widget provides a 486 <i>command button</i>.</td> 487 </tr> 488 489 <tr valign="top" bgcolor="#d0d0d0"> 490 <td>3</td> 491 <td>Another class of buttons are option buttons 492 \e (see QRadioButton).</td> 493 <td>Another class of buttons are option buttons 494 <i> (see QRadioButton)</i>.</td> 495 </tr> 496 497 <tr valign="top" bgcolor="#c0c0c0"> 498 <td>4</td> 499 <td>A push button emits the signal \e clicked().</td> 500 <td>A push button emits the signal <i>clicked</i>().</td> 501 </tr> 502 503 <tr valign="top" bgcolor="#d0d0d0"> 504 <td>5</td> 505 <td>The \e QPushButton's checked property is 506 false by default.</td> 507 <td>The <i>QPushButton</i>'s checked property is 508 false by default.</td> 509 </tr> 510 511 </table> 512 \endraw 513 514 \target sub-command 515 \section1 \\sub 516 517 The \\sub command renders its argument lower than the baseline of 518 the regular text, using a smaller font. 519 520 \code 521 / *! 522 Definition (Range): Consider the sequence 523 {x\sub n}\sub {n > 1} . The set 524 525 {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...} 526 527 is called the range of the sequence. 528 * / 529 \endcode 530 531 QDoc renders this as: 532 533 \quotation 534 Definition (Range): Consider the sequence 535 {x\sub n}\sub {n > 1} . The set 536 537 {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...} 538 539 is called the range of the sequence. 540 \endquotation 541 542 If the argument contains spaces or other punctuation, enclose the 543 argument in curly brackets. 544 545 \target sup-command 546 \section1 \\sup 547 548 The \\sup command renders its argument higher than 549 the baseline of the regular text, using a smaller font. 550 551 \code 552 / *! 553 The series 554 555 1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ... 556 557 is called the \i {geometric series}. 558 * / 559 \endcode 560 561 QDoc renders this as: 562 563 \quotation 564 The series 565 566 1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ... 567 568 is called the \e {geometric series}. 569 \endquotation 570 571 If the argument contains spaces or other punctuation, enclose the 572 argument in curly brackets. 573 574 \target uicontrol-command 575 \section1 \\uicontrol 576 577 The \\uicontrol command is used to mark content as being used for UI 578 control elements. When using HTML, the output is rendered in bold. 579 580 \sa \\b 581 582 \target underline-command 583 \section1 \\underline 584 585 The \\underline command renders its argument underlined. 586 587 \code 588 / *! 589 The \underline {F}ile menu gives the users the possibility 590 to edit an existing file, or save a new or modified 591 file, and exit the application. 592 * / 593 \endcode 594 595 QDoc renders this as: 596 597 \quotation 598 The \underline {F}ile menu gives the users the possibility 599 to edit an existing file, or save a new or modified 600 file, and exit the application. 601 \endquotation 602 603 If the argument contains spaces or other punctuation, enclose the 604 argument in curly brackets. 605 606 \target backslash-command 607 \section1 \\\\ (double backslash) 608 609 The \\\\ command expands to a double backslash. 610 611 QDoc commands always start with a single backslash. To display a 612 single backslash in the text you need to type two backslashes. If 613 you want to display two backslashes, you need to type four. 614 615 \code 616 / *! 617 The \\\\ command is useful if you want a 618 backslash to appear verbatim, for example, 619 writing C:\\windows\\home\\. 620 * / 621 \endcode 622 623 QDoc renders this as: 624 625 \quotation 626 The \\\\ command is useful if you want a 627 backslash to appear verbatim, for example, 628 writing C:\\windows\\home\\. 629 \endquotation 630 631 However, if you want your text to appear in a monospace font as 632 well, you can use the \l {c-command} {\\c} command instead, which 633 accepts and renders the backslash as any other character. For 634 example: 635 636 \code 637 / *! 638 The \\c command is useful if you want a 639 backslash to appear verbatim, and the word 640 that contains it written in a monospace font, 641 like this: \c {C:\windows\home\}. 642 * / 643 \endcode 644 645 QDoc renders this as: 646 647 \quotation 648 The \\c command is useful if you want a 649 backslash to appear verbatim, and the word 650 that contains it written in a monospace font, 651 like this: \c {C:\windows\home\}. 652 \endquotation 653 654*/ 655 656 657/*! 658 \page 05-qdoc-commands-documentstructure.html 659 \previouspage Text Markup 660 \nextpage Including Code Inline 661 662 \title Document Structure 663 664 The document structuring commands are for dividing your document 665 into sections. QDoc supports four levels of section: \c \section1, 666 \c \section2, \c \section3, and \c \section4. The section commands 667 correspond to the traditional section, subsection, etc used in 668 outlining. 669 670 \target section-commands 671 \section1 Section commands 672 673 In general a document structuring command considers everything 674 that follows it until the first line break as its argument. The 675 argument is rendered as the unit's title. If the title needs to be 676 spanned over several lines, make sure that each line (except the 677 last one) is ended with a backslash. 678 679 In total, there are four levels for sections in QDoc: \c \section1, 680 \c \section2, \c \section3 and \c \section4. These correspond to the 681 traditional section, subsection, subsubsection and subsubsubsection. 682 683 There is a strict ordering of the section units: 684 685 \code 686 section1 687 | 688 section2 689 | 690 section3 691 | 692 section4 693 \endcode 694 695 When sections are used, the first section command should be \c section1. 696 697 698 \code 699 / *! 700 \section1 Basic Qt 701 702 This is the first section. 703 704 705 \section2 Getting Started 706 707 This is the first subsection. 708 709 710 \section3 Hello Qt 711 712 This is the first subsubsection. 713 714 715 \section3 Making Connections 716 717 This is the second subsubsection. 718 719 720 \section3 Using the Reference Documentation 721 722 This is the third subsubsection. 723 724 725 \section2 Creating Dialogs 726 727 This is the second subsection. 728 729 730 \section3 Subclassing QDialog 731 732 This is the first subsubsection. 733 734 ... 735 736 737 \section1 Intermediate Qt 738 739 This is the second section. 740 741 742 \section2 Layout Management 743 744 This is the second section's first subsection. 745 746 747 \section3 Basic Layouts 748 749 This is the first subsubsection. 750 751 ... 752 * / 753 \endcode 754 755 QDoc renders this as: 756 757 \quotation 758 \raw HTML 759 <a name="Basic Qt"> 760 <h1>Basic Qt</h1> 761 </a> 762 <p>This is the first section.</p> 763 764 <a name="Getting started"> 765 <h2>Getting Started</h2> 766 </a> 767 This is the first subsection.</p> 768 769 <a name="Hello Qt"> 770 <h3>Hello Qt</h3> 771 </a> 772 <p>This is the first subsubsection.</p> 773 774 <a name="Making Connections"> 775 <h3>Making Connections</h3> 776 </a> 777 <p>This is the second subsubsection.</p> 778 779 <a name="Using the Reference Documentation"> 780 <h3>Using the Reference Documentation</h3> 781 </a> 782 <p>This is the third subsubsection.</p> 783 784 <a name="Creating Dialogs"> 785 <h2>Creating Dialogs</h2> 786 </a> 787 <p>This is the second subsection.</p> 788 789 <a name="Subclassing QDialog"> 790 <h3>Subclassing QDialog</h3> 791 </a> 792 <p>This is the first subsubsection.</p> 793 794 ... 795 796 <a name="Intermediate Qt"> 797 <h1>Intermediate Qt</h1> 798 </a> 799 <p>This is the second section.</p> 800 801 <a name="Layout Management"> 802 <h2>Layout Management</h2> 803 </a> 804 <p>This is the second section's first subsection.</p> 805 806 <a name="Basic Layouts"> 807 <h3>Basic Layouts</h3> 808 </a> 809 <p>This is the first subsubsection.</p> 810 811 ... 812 813 \endraw 814 \endquotation 815 816 Each section is a logical unit in the document. The section 817 heading appears in the automatically generated table of contents 818 that normally appears in the upper right-hand corner of the page. 819 820 \target sectionOne-command 821 \section1 \\section1 822 823 The \\section1 command starts a new section. 824 825 See \l{section-commands} {Section commands} for an explanation of the various 826 section units, command argument, and rendering. 827 828 \target sectionTwo-command 829 \section1 \\section2 830 831 The \\section2 command starts a new section. 832 833 See \l{section-commands} {Section commands} for an explanation of the various 834 section units, command argument, and rendering. 835 836 \target sectionThree-command 837 \section1 \\section3 838 839 The \\section3 command starts a new section. 840 841 See \l{section-commands} {Section commands} for an explanation of the various 842 section units, command argument, and rendering. 843 844 \target sectionFour-command 845 \section1 \\section4 846 847 The \\section4 command starts a new section. 848 849 See \l{section-commands} {Section commands} for an explanation of the various 850 section units, command argument, and rendering. 851 852*/ 853 854 855/*! 856 \page 06-qdoc-commands-includecodeinline.html 857 \previouspage Document Structure 858 \nextpage Including External Code 859 860 \title Including Code Inline 861 862 The following commands are used to render source code without 863 formatting. The source code begins on a new line, rendered in the 864 code. 865 866 \note Although most of these commands are for rendering C++ 867 code, the 868 \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command} 869 {\\snippet} and 870 \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command} 871 {\\codeline} commands are preferred over the others. These 872 commands allow equivalent code snippets for other Qt language 873 bindings to be substituted for the C++ snippets in the 874 documentation. 875 876 \target code-command 877 \section1 \\code 878 879 The \\code and \\endcode commands enclose a snippet of source code. 880 881 \note The \l {c-command} {\\c} command can be used for short code 882 fragments within a sentence. The \\code command is for longer code 883 snippets. It renders the code verbatim in a separate paragraph in 884 a html <pre> element, and parses the enclosed snippet, creating links 885 to any known types in the code. 886 887 For documenting command-line instructions, shell scripts, or any 888 content that is not in a Qt language recognized by QDoc, use 889 \l {badcode-command}{\\badcode} instead. 890 891 When processing any of the \\code, \l {newcode-command} {\\newcode} or \l 892 {oldcode-command} {\\oldcode} commands, QDoc removes all 893 indentation that is common for the verbatim code blocks within a 894 \c{/}\c{*!} ... \c{*}\c{/} comment before it adds the standard 895 indentation. 896 897 \note This doesn't apply to externally quoted code using the \l 898 {quotefromfile-command} {\\quotefromfile} or \l 899 {quotefile-command} {\\quotefile} command. 900 901 \code 902 / *! 903 \code 904 #include <QApplication> 905 #include <QPushButton> 906 907 int main(int argc, char *argv[]) 908 { 909 ... 910 } 911 \ endcode 912 * / 913 \endcode 914 915 QDoc renders this as: 916 917 \code 918 #include <QApplication> 919 #include <QPushButton> 920 921 int main(int argc, char *argv[]) 922 { 923 ... 924 } 925 \endcode 926 927 Other QDoc commands are disabled within \\code... \\endcode, and 928 the special character '\\' is accepted and rendered like the rest 929 of the code, unless it is followed by a digit and parameters were 930 passed to \\code. 931 932 \section2 Code snippet parameters 933 934 Since QDoc version 5.12, \\code command accepts also optional 935 parameters. Parameters are useful for injecting simple 936 strings into the code snippet. To inject a string to a specific 937 location in the snippet, add a backslash followed by a digit (1..8). 938 The digits correspond with the order of the argument list, where 939 arguments are separated by spaces. 940 941 For example: 942 943 \code 944 / *! 945 \code * hello 946 /\1 \2 \1/ 947 \ endcode 948 * / 949 \endcode 950 951 For the above snippet, QDoc renders the word \e hello enclosed in 952 a C-style comment. 953 954 \section2 Including code from external files 955 956 To include code snippets from an external file, use the 957 \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command} 958 {\\snippet} and 959 \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command} 960 {\\codeline} commands. 961 962 See also \l {c-command} {\\c}, \l {badcode-command} {\\badcode}, \l 963 {07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command} 964 {\\quotefromfile}, \l{newcode-command} {\\newcode}, and \l {oldcode-command} 965 {\\oldcode}. 966 967 \target badcode-command 968 \section1 \\badcode 969 970 Similar to \l {code-command}{\\code}, \\badcode and \\endcode commands 971 enclose content that is rendered verbatim in a separate paragraph, but no 972 parsing or automatic link creation is performed. Instead, the content is 973 treated as plain text. 974 975 Substitute \\code with this command when documenting command-line 976 instructions, shell scripts or any other content that is not in a Qt 977 language, but should still be styled similarly to a \\code paragraph. 978 979 Like \\code, \\badcode accepts also optional parameters. 980 981 \target newcode-command 982 \section1 \\newcode 983 984 The \\newcode, \\oldcode, and \\endcode commands enable you to 985 show how to port a snippet of code to a new version of an API. 986 987 The \\newcode command and its companion the \\oldcode command are 988 a convenience combination of the \l {code-command} {\\code} commands: 989 this combination provides a text relating the two code snippets to each 990 other. 991 992 The \\newcode command requires a preceding \\oldcode statement. 993 994 Like the \l{code-command}{\\code} command, the \\newcode command renders its 995 code on a new line in the documentation using a monospace font and the 996 standard indentation. 997 998 \code 999 / *! 1000 \oldcode 1001 if (printer->setup(parent)) 1002 ... 1003 \newcode 1004 QPrintDialog dialog(printer, parent); 1005 if (dialog.exec()) 1006 ... 1007 \ endcode 1008 * / 1009 \endcode 1010 1011 QDoc renders this as: 1012 1013 \quotation 1014 \oldcode 1015 if (printer->setup(parent)) 1016 ... 1017 \newcode 1018 QPrintDialog dialog(printer, parent); 1019 if (dialog.exec()) 1020 ... 1021 \endcode 1022 \endquotation 1023 1024 Other QDoc commands are disabled within \\oldcode ... \\endcode, 1025 and the '\\' character doesn't need to be escaped. 1026 1027 \target oldcode-command 1028 \section1 \\oldcode 1029 1030 The \\oldcode command requires a corresponding 1031 \\newcode statement; otherwise QDoc fails to parse the command 1032 and emits a warning. 1033 1034 See also \l {newcode-command} {\\newcode}. 1035 1036 \target qml-command 1037 \section1 \\qml 1038 1039 The \\qml and \\endqml commands enclose a snippet of QML source 1040 code. 1041 1042 \code 1043 / *! 1044 \qml 1045 import QtQuick 2.0 1046 1047 Row { 1048 Rectangle { 1049 width: 100; height: 100 1050 color: "blue" 1051 transform: Translate { y: 20 } 1052 } 1053 Rectangle { 1054 width: 100; height: 100 1055 color: "red" 1056 transform: Translate { y: -20 } 1057 } 1058 } 1059 \endqml 1060 * / 1061 \endcode 1062 1063 QDoc renders this as: 1064 1065 \qml 1066 import QtQuick 2.0 1067 1068 Row { 1069 Rectangle { 1070 width: 100; height: 100 1071 color: "blue" 1072 transform: Translate { y: 20 } 1073 } 1074 Rectangle { 1075 width: 100; height: 100 1076 color: "red" 1077 transform: Translate { y: -20 } 1078 } 1079 } 1080 \endqml 1081 1082 Like the \l{code-command}{\\code} command, \\qml accepts optional 1083 parameters. 1084*/ 1085 1086 1087/*! 1088 \page 07-0-qdoc-commands-includingexternalcode.html 1089 \previouspage Including Code Inline 1090 \nextpage Creating Links 1091 1092 \title Including External Code 1093 1094 The following commands enable you to include code snippets from 1095 external files. You can make QDoc include the complete contents of 1096 a file, or you can quote specific parts of the file and skip 1097 others. The typical use of the latter is to quote a file chunk by 1098 chunk. 1099 1100 \note Although all these commands can be used for rendering C++ 1101 code, the 1102 \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command} 1103 {\\snippet} and 1104 \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command} 1105 {\\codeline} commands are preferred over the others. These 1106 commands allow equivalent code snippets for other Qt language 1107 bindings to be substituted for the C++ snippets in the 1108 documentation. 1109 1110 \target quotefile-command 1111 \section1 \\quotefile 1112 1113 The \\quotefile command expands to the complete contents of the 1114 file given as argument. 1115 1116 The command considers the rest of the line as part of its 1117 argument, make sure to follow the file name with a line break. 1118 1119 The file's contents is rendered in a separate paragraph, using a 1120 monospace font and the standard indentation. The code is shown 1121 verbatim. 1122 1123 \code 1124 / *! 1125 This is a simple "Hello world" example: 1126 1127 \quotefile examples/main.cpp 1128 1129 It contains only the bare minimum you need 1130 to get a Qt application up and running. 1131 * / 1132 \endcode 1133 1134 QDoc renders this as: 1135 1136 \quotation 1137 This is a simple "Hello world" example: 1138 1139 \quotefile examples/main.cpp 1140 1141 It contains only the bare minimum you need to get a Qt 1142 application up and running. 1143 \endquotation 1144 1145 See also \l {quotefromfile-command} {\\quotefromfile} and 1146 \l {code-command} {\\code}. 1147 1148 1149 \target quotefromfile-command 1150 \section1 \\quotefromfile 1151 1152 The \\quotefromfile command opens the file given as argument for 1153 quoting. 1154 1155 The command considers the rest of the line as part of its 1156 argument, make sure to follow the file name with a line break. 1157 1158 The command is intended for use when quoting parts from file with 1159 the walkthrough commands: \l {printline-command} {\\printline}, \l 1160 {printto-command} {\\printto}, \l {printuntil-command} 1161 {\\printuntil}, \l {skipline-command} {\\skipline}, \l 1162 {skipto-command} {\\skipto}, \l {skipuntil-command} 1163 {\\skipuntil}. This enables you to quote specific portions of a 1164 file. 1165 1166 \code 1167 / *! 1168 The whole application is contained within 1169 the \c main() function: 1170 1171 \quotefromfile examples/main.cpp 1172 1173 \skipto main 1174 \printuntil app(argc, argv) 1175 1176 First we create a QApplication object using 1177 the \c argc and \c argv parameters. 1178 1179 \skipto QPushButton 1180 \printuntil resize 1181 1182 Then we create a QPushButton, and give it a reasonable 1183 size using the QWidget::resize() function. 1184 1185 ... 1186 * / 1187 \endcode 1188 1189 QDoc renders this as: 1190 1191 \quotation 1192 The whole application is contained within 1193 the \c main() function: 1194 1195 \quotefromfile examples/main.cpp 1196 1197 \skipto main 1198 \printuntil app(argc, argv) 1199 1200 First we create a QApplication object using the \c argc 1201 and \c argv parameters. 1202 1203 \skipto QPushButton 1204 \printuntil resize 1205 1206 Then we create a QPushButton, and give it a reasonable 1207 size using the QWidget::resize() function. 1208 1209 ... 1210 \endquotation 1211 1212 QDoc remembers which file it is quoting from, and the current 1213 position in that file (see \l {file} {\\printline} for more 1214 information). There is no need to "close" the file. 1215 1216 See also \l {quotefile-command} {\\quotefile}, \l {code-command} 1217 {\\code} and \l {dots} {\\dots}. 1218 1219 \target printline-command 1220 \section1 \\printline 1221 1222 The \\printline command expands to the line from the current 1223 position to the next non-blank line of the current source file. 1224 1225 To ensure that the documentation remains synchronized with the 1226 source file, a substring of the line must be specified as an 1227 argument to the command. Note that the command considers the rest 1228 of the line as part of its argument, make sure to follow the 1229 substring with a line break. 1230 1231 The line from the source file is rendered as a separate paragraph, 1232 using a monospace font and the standard indentation. The code is 1233 shown verbatim. 1234 1235 \code 1236 / *! 1237 There has to be exactly one QApplication object 1238 in every GUI application that uses Qt. 1239 1240 \quotefromfile examples/main.cpp 1241 1242 \printline QApplication 1243 1244 This line includes the QApplication class 1245 definition. QApplication manages various 1246 application-wide resources, such as the 1247 default font and cursor. 1248 1249 \printline QPushButton 1250 1251 This line includes the QPushButton class 1252 definition. The QPushButton widget provides a command 1253 button. 1254 1255 \printline main 1256 1257 The main function... 1258 * / 1259 \endcode 1260 1261 QDoc renders this as: 1262 1263 \quotation 1264 There has to be exactly one QApplication object 1265 in every GUI application that uses Qt. 1266 1267 \quotefromfile examples/main.cpp 1268 1269 \skipto QApplication 1270 \printline QApplication 1271 1272 This line includes the QApplication class 1273 definition. QApplication manages various 1274 application-wide resources, such as the 1275 default font and cursor. 1276 1277 \printline QPushButton 1278 1279 This line includes the QPushButton class 1280 definition. The QPushButton widget provides a command 1281 button. 1282 1283 \printline main 1284 1285 The main function... 1286 \endquotation 1287 1288 \target file 1289 1290 QDoc reads the file sequentially. To move the current position 1291 forward you can use either of the \l {skipline-command} 1292 {\\skip...} commands. To move the current position backward, you 1293 can use the \l {quotefromfile-command} {\\quotefromfile} command 1294 again. 1295 1296 \target substring 1297 1298 If the substring argument is surrounded by slashes it is 1299 interpreted as a \l {QRegExp}{regular expression}. 1300 1301 \code 1302 / *! 1303 \quotefromfile examples/mainwindow.cpp 1304 1305 \skipto closeEvent 1306 \printuntil /^\}/ 1307 1308 Close events are sent to widgets that the users want to 1309 close, usually by clicking \c File|Exit or by clicking 1310 the \c X title bar button. By reimplementing the event 1311 handler, we can intercept attempts to close the 1312 application. 1313 * / 1314 \endcode 1315 1316 QDoc renders this as: 1317 1318 \quotation 1319 \quotefromfile examples/mainwindow.cpp 1320 1321 \skipto closeEvent 1322 \printuntil /^\}/ 1323 1324 Close events are sent to widgets that the users want to 1325 close, usually by clicking \c File|Exit or by clicking 1326 the \c X title bar button. By reimplementing the event 1327 handler, we can intercept attempts to close the 1328 application. 1329 \endquotation 1330 1331 (\l {widgets/scribble} {The complete example file...}) 1332 1333 The regular expression \c /^\}/ makes QDoc print until the first 1334 '}' character occurring at the beginning of the line without 1335 indentation. /.../ encloses the regular expression, and '^' means 1336 the beginning of the line. The '}' character must be escaped since 1337 it is a special character in regular expressions. 1338 1339 QDoc will emit a warning if the specified substring or regular 1340 expression cannot be located, i.e. if the source code has changed. 1341 1342 See also \l {printto-command} {\\printto} and \l 1343 {printuntil-command} {\\printuntil}. 1344 1345 \target printto-command 1346 \section1 \\printto 1347 1348 The \\printto command expands to all the lines from the current 1349 position up to and \e excluding the next line containing a given 1350 substring. 1351 1352 The command considers the rest of the line as part of its 1353 argument, make sure to follow the substring with a line break. The 1354 command also follows the same conventions for \l {file} 1355 {positioning} and \l {substring} {argument} as the \l 1356 {printline-command} {\\printline} command. 1357 1358 The lines from the source file are rendered in a separate 1359 paragraph, using a monospace font and the standard 1360 indentation. The code is shown verbatim. 1361 1362 \code 1363 / *! 1364 The whole application is contained within the 1365 \c main() function: 1366 1367 \quotefromfile examples/main.cpp 1368 \printto hello 1369 1370 First we create a QApplication object using the \c argc and 1371 \c argv parameters... 1372 * / 1373 \endcode 1374 1375 QDoc renders this as: 1376 1377 \quotation 1378 The whole application is contained within the 1379 \c main() function: 1380 1381 \quotefromfile examples/main.cpp 1382 \skipto main 1383 \printto hello 1384 1385 First we create a QApplication object using the \c argc 1386 and \c argv parameters... 1387 \endquotation 1388 1389 See also \l {printline-command} {\\printline} and \l 1390 {printuntil-command} {\\printuntil}. 1391 1392 \target printuntil-command 1393 \section1 \\printuntil 1394 1395 The \\printuntil command expands to all the lines from the current 1396 position up to and \e including the next line containing a given 1397 substring. 1398 1399 The command considers the rest of the line as part of its 1400 argument, make sure to follow the substring with a line break. The 1401 command also follows the same conventions for \l {file} 1402 {positioning} and \l {substring} {argument} as the \l 1403 {printline-command} {\\printline} command. 1404 1405 If \\printuntil is used without an argument, it expands to all the 1406 lines from the current position to the end of the quoted file. 1407 1408 The lines from the source file are rendered in a separate 1409 paragraph, using a monospace font and the standard 1410 indentation. The code is shown verbatim. 1411 1412 \code 1413 / *! 1414 The whole application is contained within the 1415 \c main() function: 1416 1417 \quotefromfile examples/main.cpp 1418 \skipto main 1419 \printuntil hello 1420 1421 First we create a QApplication object using the 1422 \c argc and \c argv parameters, then we create 1423 a QPushButton. 1424 * / 1425 \endcode 1426 1427 QDoc renders this as: 1428 1429 \quotation 1430 The whole application is contained within the 1431 \c main() function: 1432 1433 \quotefromfile examples/main.cpp 1434 \skipto main 1435 \printuntil hello 1436 1437 First we create a \l 1438 {http://doc.qt.io/qt-5/qapplication.html} {QApplication} 1439 object using the \c argc and \c argv parameters, then we 1440 create a \l 1441 {http://doc.qt.io/qt-5/qpushbutton.html} {QPushButton}. 1442 \endquotation 1443 1444 See also \l {printline-command} {\\printline} and \l 1445 {printto-command} {\\printto}. 1446 1447 \target skipline-command 1448 \section1 \\skipline 1449 1450 The \\skipline command ignores the next non-blank line in the 1451 current source file. 1452 1453 Doc reads the file sequentially, and the \\skipline command is 1454 used to move the current position (omitting a line of the source 1455 file). See the remark about \l {file} {file positioning} above. 1456 1457 The command considers the rest of the line as part of its 1458 argument, make sure to follow the substring with a line break. The 1459 command also follows the same conventions for \l {substring} 1460 {argument} as the \l {printline-command} {\\printline} command, 1461 and it is used in conjunction with the \l {quotefromfile-command} 1462 {\\quotefromfile} command. 1463 1464 \code 1465 / *! 1466 QPushButton is a GUI push button that the user 1467 can press and release. 1468 1469 \quotefromfile examples/main.cpp 1470 \skipline QApplication 1471 \printline QPushButton 1472 1473 This line includes the QPushButton class 1474 definition. For each class that is part of the 1475 public Qt API, there exists a header file of 1476 the same name that contains its definition. 1477 * / 1478 \endcode 1479 1480 QDoc renders this as: 1481 1482 \quotation 1483 \l 1484 QPushButton is a GUI push button that the user 1485 can press and release. 1486 1487 \quotefromfile examples/main.cpp 1488 \skipto QApplication 1489 \skipline QApplication 1490 \printline QPushButton 1491 1492 This line includes the QPushButton class 1493 definition. For each class that is part of the public 1494 Qt API, there exists a header file of the same name 1495 that contains its definition. 1496 \endquotation 1497 1498 See also \l {skipto-command} {\\skipto}, \l {skipuntil-command} 1499 {\\skipuntil} and \l {dots} {\\dots}. 1500 1501 \target skipto-command 1502 \section1 \\skipto 1503 1504 The \\skipto command ignores all the lines from the current 1505 position up to and \e excluding the next line containing a given 1506 substring. 1507 1508 QDoc reads the file sequentially, and the \\skipto command is used 1509 to move the current position (omitting one or several lines of the 1510 source file). See the remark about \l {file} {file positioning} 1511 above. 1512 1513 The command considers the rest of the line as part of its 1514 argument, make sure to follow the substring with a line break. 1515 1516 The command also follows the same conventions for \l {substring} 1517 {argument} as the \l {printline-command} {\\printline} command, 1518 and it is used in conjunction with the \l {quotefromfile-command} 1519 {\\quotefromfile} command. 1520 1521 \code 1522 / *! 1523 The whole application is contained within 1524 the \c main() function: 1525 1526 \quotefromfile examples/main.cpp 1527 \skipto main 1528 \printuntil } 1529 1530 First we create a QApplication object. There 1531 has to be exactly one such object in 1532 every GUI application that uses Qt. Then 1533 we create a QPushButton, resize it to a reasonable 1534 size... 1535 * / 1536 \endcode 1537 1538 QDoc renders this as: 1539 1540 \quotation 1541 The whole application is contained within 1542 the \c main() function: 1543 1544 \quotefromfile examples/main.cpp 1545 \skipto main 1546 \printuntil } 1547 1548 First we create a QApplication object. There has to be 1549 exactly one such object in every GUI application that 1550 uses Qt. Then we create a QPushButton, resize it to a 1551 reasonable size ... 1552 \endquotation 1553 1554 See also \l {skipline-command} {\\skipline}, \l 1555 {skipuntil-command} {\\skipuntil} and \l {dots} {\\dots}. 1556 1557 \target skipuntil-command 1558 \section1 \\skipuntil 1559 1560 The \\skipuntil command ignores all the lines from the current 1561 position up to and \e including the next line containing a given 1562 substring. 1563 1564 QDoc reads the file sequentially, and the \\skipuntil command is 1565 used to move the current position (omitting one or several lines 1566 of the source file). See the remark about \l {file} {file 1567 positioning} above. 1568 1569 The command considers the rest of the line as part of its 1570 argument, make sure to follow the substring with a line break. 1571 1572 The command also follows the same conventions for \l {substring} 1573 {argument} as the \l {printline-command} {\\printline} command, 1574 and it is used in conjunction with the \l {quotefromfile-command} 1575 {\\quotefromfile} command. 1576 1577 \code 1578 / *! 1579 The first thing we did in the \c main() function 1580 was to create a QApplication object \c app. 1581 1582 \quotefromfile examples/main.cpp 1583 \skipuntil show 1584 \dots 1585 \printuntil } 1586 1587 In the end we must remember to make \c main() pass the 1588 control to Qt. QCoreApplication::exec() will return when 1589 the application exits... 1590 * / 1591 \endcode 1592 1593 QDoc renders this as: 1594 1595 \quotation 1596 The first thing we did in the \c main() function was to 1597 create a QApplication object \c app. 1598 1599 \quotefromfile examples/main.cpp 1600 \skipuntil show 1601 \dots 1602 \printuntil } 1603 1604 In the end we must remember to make \c main() pass the 1605 control to Qt. QCoreApplication::exec() 1606 will return when the application exits... 1607 \endquotation 1608 1609 See also \l {skipline-command} {\\skipline}, \l {skipto-command} 1610 {\\skipto} and \l {dots} {\\dots}. 1611 1612 \target dots-command 1613 \section1 \\dots 1614 1615 The \\dots command indicates that parts of the source file have 1616 been omitted when quoting a file. 1617 1618 The command is used in conjunction with the \l 1619 {quotefromfile-command} {\\quotefromfile} command, and should be 1620 stated on its own line. The dots are rendered on a new line, using 1621 a monospace font. 1622 1623 \code 1624 / *! 1625 \quotefromfile examples/main.cpp 1626 \skipto main 1627 \printuntil { 1628 \dots 1629 \skipuntil exec 1630 \printline } 1631 * / 1632 \endcode 1633 1634 QDoc renders this as: 1635 1636 \quotefromfile examples/main.cpp 1637 \skipto main 1638 \printuntil { 1639 \dots 1640 \skipuntil exec 1641 \printline } 1642 1643 The default indentation is 4 spaces, but this can be adjusted 1644 using the command's optional argument. 1645 1646 \code 1647 / *! 1648 \dots 0 1649 \dots 1650 \dots 8 1651 \dots 12 1652 \dots 16 1653 * / 1654 \endcode 1655 1656 QDoc renders this as: 1657 1658 \dots 0 1659 \dots 1660 \dots 8 1661 \dots 12 1662 \dots 16 1663 1664 See also \l {skipline-command} {\\skipline}, \l {skipto-command} 1665 {\\skipto} and \l {skipuntil-command} {\\skipuntil}. 1666 1667 \target snippet-command 1668 \section1 \\snippet 1669 1670 The \\snippet command causes a code snippet to be included 1671 verbatim as preformatted text, which may be syntax highlighted. 1672 1673 Each code snippet is referenced by the file that holds it and by 1674 a unique identifier for that file. Snippet files are typically 1675 stored in a \c{snippets} directory inside the documentation 1676 directory (for example, \c{$QTDIR/doc/src/snippets}). 1677 1678 For example, the following documentation references a snippet in a 1679 file residing in a subdirectory of the documentation directory: 1680 1681 \code 1682 \snippet snippets/textdocument-resources/main.cpp Adding a resource 1683 \endcode 1684 1685 The text following the file name is the unique identifier for the 1686 snippet. This is used to delimit the quoted code in the relevant 1687 snippet file, as shown in the following example that corresponds to 1688 the above \c{\snippet} command: 1689 1690 \code 1691 ... 1692 QImage image(64, 64, QImage::Format_RGB32); 1693 image.fill(qRgb(255, 160, 128)); 1694 1695//! [Adding a resource] 1696 document->addResource(QTextDocument::ImageResource, 1697 QUrl("mydata://image.png"), QVariant(image)); 1698//! [Adding a resource] 1699 ... 1700 \endcode 1701 1702 By default, QDoc looks for \c{//!} as a code snippet marker. 1703 For \c{.pro}, \c{.py}, \c{.cmake}, and \c{CMakeLists.txt} 1704 files, \c {#!} is detected. Finally, \c{<!--} is accepted in 1705 \c{.html}, \c{.qrc}, \c{.ui}, \c{.xml}, \c{.dita}, and \c{.xq} files. 1706 1707 \target codeline-command 1708 \section1 \\codeline 1709 1710 The \\codeline command inserts a blank line of preformatted 1711 text. It is used to insert gaps between snippets without closing 1712 the current preformatted text area and opening a new one. 1713 1714*/ 1715 1716 1717/*! 1718 \page 08-qdoc-commands-creatinglinks.html 1719 \previouspage Including External Code 1720 \nextpage Including Images 1721 1722 \title Creating Links 1723 1724 These commands are for creating hyperlinks to classes, functions, 1725 examples, and other targets. 1726 1727 \target l-command 1728 \section1 \\l (link) 1729 1730 The \\l link command is used to create a hyperlink to many 1731 different kinds of targets. The command's general syntax is: 1732 1733 \code 1734 \l [ link criteria ] { link target } { link text } 1735 \endcode 1736 1737 ...where the \c {link criteria} in square brackets are optional 1738 but may be required when the \c {link target} is ambiguous. See 1739 \l {Fixing Ambiguous Links} below. 1740 1741 Here is an example using the \\l command to link to an external page: 1742 1743 \code 1744 / *! 1745 Read the \l {http://doc.qt.io/qt-5/} 1746 {Qt 5.0 Documentation} carefully. 1747 * / 1748 \endcode 1749 1750 QDoc renders this as: 1751 1752 \quotation 1753 Read the \l {http://doc.qt.io/qt-5/} 1754 {Qt 5.0 Documentation} carefully. 1755 \endquotation 1756 1757 If the link target is equivalent to the link text, the second 1758 argument can be omitted. 1759 1760 For example, if you have documentation like: 1761 1762 \code 1763 / *! 1764 \target assertions 1765 1766 Assertions make some statement about the text at the 1767 point where they occur in the regexp, but they do not 1768 match any characters. 1769 1770 ... 1771 1772 Regexps are built up from expressions, quantifiers, and 1773 \l {assertions} {assertions}. 1774 * / 1775 \endcode 1776 1777 You can simplify this as follows: 1778 1779 \code 1780 / *! 1781 \target assertions 1782 1783 Assertions make some statement about the text at the 1784 point where they occur in the regexp, but they do not 1785 match any characters. 1786 1787 ... 1788 1789 Regexps are built up from expressions, quantifiers, and 1790 \l assertions. 1791 * / 1792 \endcode 1793 1794 For the one-parameter version, the braces can often be omitted. 1795 The \\l command supports several ways of linking: 1796 1797 \list 1798 1799 \li \c {\l QWidget} - The name of a class documented with the \l 1800 {class-command} {\\class} command. 1801 1802 \li \c {\l QWidget::sizeHint()} - The signature of a function without 1803 parameters. If a matching function without parameters can't be found, 1804 the link is satisfied with the first matching function found. 1805 1806 \li \c {\l QWidget::removeAction(QAction* action)} - The signature 1807 of a function with parameters. If an exact match is not found, the 1808 link is not satisfied and QDoc reports a \e {Can't link to...} error. 1809 1810 \li \c {\l <QtGlobal>} - The subject of a \l {headerfile-command} 1811 {\\headerfile} command. 1812 1813 \li \c {\l widgets/wiggly} - The relative path used in an \l 1814 {example-command} {\\example} command. 1815 1816 \li \c {\l {QWidget Class Reference}} - The title used in a 1817 \l {title-command} {\\title} command. 1818 1819 \li \c {\l {Introduction to QDoc}}- The text from one of the 1820 \l{section-commands} {Section commands}. 1821 1822 \li \c {\l fontmatching} - The argument of a \l {target-command} 1823 {\\target} command. 1824 1825 \li \c {\l {Shared Classes}} - A keyword named in a \l 1826 {keyword-command} {\\keyword} command. 1827 1828 \li \c {\l http://qt-project.org/} - A URL. 1829 1830 \endlist 1831 1832 QDoc also tries to make a link out of any word that doesn't 1833 resemble a normal English word, for example, Qt class names or 1834 functions, like QWidget or QWidget::sizeHint(). In these cases, 1835 the \\l command can actually be omitted, but by using the command, 1836 you ensure that QDoc will emit a warning if it cannot find the 1837 link target. In addition, if you only want the function name to 1838 appear in the link, you can use the following syntax: 1839 1840 \list 1841 \li \c {\l {QWidget::} {sizeHint()}} 1842 \endlist 1843 1844 QDoc renders this as: 1845 1846 \quotation 1847 \l {QWidget::} {sizeHint()} 1848 \endquotation 1849 1850 \section2 Fixing Ambiguous Links 1851 1852 Because of the modularization of Qt beginning with Qt 5.0, The 1853 possibility that QDoc will have to deal with ambiguous links has 1854 increased. An ambiguous link is one that has a matching target in 1855 more than one Qt module, e.g. the same section title can appear in 1856 more than one Qt module, or the name of a C++ class in one module 1857 can also be the name of a QML type in another module. A real 1858 example in Qt5 is the name Qt itself. Qt is the name of both a C++ 1859 namespace in QtCore and a QML type in QtQml. 1860 1861 Suppose we want to link to the \l {Qt} {Qt C++ namespace}. At the 1862 time QDoc generated this HTML page, that link was correct. Does 1863 it still go to the C++ namespace? Qdoc generated that link from 1864 this link command: 1865 1866 \list 1867 \li \c {\l {Qt} {Qt C++ namespace}} 1868 \endlist 1869 1870 Now suppose we want to link to the \l [QML] {Qt} {Qt QML type}. 1871 At the time QDoc generated this HTML page, that link was also 1872 correct, but we had to use this link command: 1873 1874 \list 1875 \li \c {\l [QML] {Qt} {Qt QML type}} 1876 \endlist 1877 1878 The \e {QML} in \e {square brackets} tells QDoc to accept a 1879 matching target only if the traget is on a QML page. Qdoc actually 1880 finds the C++ namespace target first, but since that target is on 1881 a C++ page, QDoc ignores it and keeps looking until it finds the 1882 same target on a QML page. 1883 1884 Without the guidance in the \e{\\l command} in the optional \e 1885 {square bracket} argument, QDoc links to the first matching target 1886 it finds. QDoc can't warn that the link was ambiguous in such 1887 cases because it doesn't know that another matching target exists. 1888 1889 \section2 What arguments can appear in square brackets? 1890 1891 A link command with square bracket argument has the following syntax: 1892 \list 1893 \c {\l [QML|CPP|DOC|QtModuleName] {link target} {link text}} 1894 \endlist 1895 1896 The \e {square bracket} argument is only allowed in the \c {\l 1897 (link)} command. The example above shows how \c QML is used as the 1898 \e {square brackets} argument to force QDoc to match a QML target. 1899 Most often, this will be a QML type, but it can also be a QML 1900 member function of property. 1901 1902 In the example, QDoc didn't need a \e {square bracket} argument to 1903 find the Qt C++ namespace page, because that one was the first 1904 matching target QDoc found anyway. However, to force QDoc to find 1905 a C++ target when a matching QML target gets in the way, \c CPP 1906 can be used as the \e {square bracket} argument. For example: 1907 1908 \list 1909 \li \c {\l [CPP] {Qt} {Qt C++ namespace}} 1910 \endlist 1911 1912 ...will force QDoc to ignore the Qt QML type and continue 1913 searching until it matches the Qt C++ namespace. 1914 1915 If the link target is neither a C++ nor a QML entity, \c {DOC} can 1916 be used as the \e {square bracket} argument to prevent QDoc from 1917 matching either of those. At this writing, there were no cases of 1918 ambiguous links where using \c {DOC} was required. 1919 1920 Often, the documentor knows which Qt module the link target is 1921 in. When the module name is known, use the module name as the \e 1922 {square bracket} argument. In the example above, if we know that 1923 the QML type named Qt is located in the QtQml module, we can write 1924 the link command like this: 1925 1926 \list 1927 \li \c {\l [QtQml] {Qt} {Qt QML type}} 1928 \endlist 1929 1930 When a module name is used as the \e {square bracket} argument, 1931 QDoc will search for link the target in that module only. This 1932 makes searching for link targets more efficient. 1933 1934 Finally, the module name and entity type arguments can be 1935 combined, separated by a blank, so something like this is also 1936 allowed: 1937 1938 \list 1939 \li \c {\l [CPP QtQml] {Window} {C++ class Window}} 1940 \endlist 1941 1942 As of this writing, there were no cases where combining the two 1943 was required. 1944 1945 See also \l {sa-command} {\\sa}, \l {target-command} {\\target}, 1946 and \l {keyword-command} {\\keyword}. 1947 1948 1949 \target sa-command 1950 \section1 \\sa (see also) 1951 1952 The \\sa command defines a list of links that will be rendered in 1953 a separate "See also" section at the bottom of the documentation 1954 unit. 1955 1956 The command takes a comma-separated list of links as its 1957 argument. If the line ends with a comma, you can continue 1958 the list on the next line. The general syntax is: 1959 1960 \code 1961 \sa {the first link}, {the second link}, 1962 {the third link}, ... 1963 \endcode 1964 1965 QDoc will automatically try to generate "See also" links 1966 interconnecting a property's various functions. For example, a 1967 setVisible() function will automatically get a link to visible() 1968 and vice versa. 1969 1970 In general, QDoc will generate "See also" links that interconnect 1971 the functions that access the same property. It recognizes four 1972 different syntax versions: 1973 1974 \list 1975 \li \c property() 1976 \li \c setProperty() 1977 \li \c isProperty() 1978 \li \c hasProperty() 1979 \endlist 1980 1981 The \\sa command supports the same kind of links as the \l 1982 {l-command} {\\l} command. 1983 1984 \code 1985 / *! 1986 Appends the actions \a actions to this widget's 1987 list of actions. 1988 1989 \sa removeAction(), QMenu, addAction() 1990 * / 1991 void QWidget::addActions(QList<QAction *> actions) 1992 { 1993 ... 1994 } 1995 \endcode 1996 1997 QDoc renders this as: 1998 1999 \quotation 2000 \b {void QWidget::addActions ( QList<QAction*> 2001 \e actions )} 2002 2003 Appends the actions \e actions to this widget's list of 2004 actions. 2005 2006 See also \l {QWidget::removeAction()} {removeAction()}, 2007 \l QMenu, and \l {QWidget::addAction()} {addAction()}. 2008 \endquotation 2009 2010 See also \l {l-command} {\\l}, \l {target-command} {\\target} and 2011 \l {keyword-command} {\\keyword}. 2012 2013 2014 \target target-command 2015 \section1 \\target 2016 2017 The \\target command names a place in the documentation that you 2018 can link to using the \l {l-command} {\\l (link)} and \l 2019 {sa-command} {\\sa (see also)} commands. 2020 2021 The text up to the line break becomes the target name. Be sure to 2022 follow the target name with a line break. Curly brackets are not 2023 required around the target name, but they may be required when the 2024 target name is used in a link command. See below. 2025 2026 \code 2027 / *! 2028 \target capturing parentheses 2029 \section1 Capturing Text 2030 2031 Parentheses allow us to group elements together so that 2032 we can quantify and capture them. 2033 2034 ... 2035 * / 2036 \endcode 2037 2038 The target name \e{capturing parentheses} can be linked from 2039 within the same document containing the target in the following way: 2040 2041 \list 2042 \li \c {\l {capturing parentheses}} (from within the same QDoc comment) 2043 \endlist 2044 2045 \note The brackets in the link example are required because the 2046 target name contains spaces. 2047 2048 See also \l {l-command} {\\l}, \l {sa-command} {\\sa} and \l 2049 {keyword-command} {\\keyword}. 2050 2051 \target keyword-command 2052 \section1 \\keyword 2053 2054 The \\keyword command names a place in the documentation that you 2055 can link to using the \l {l-command} {\\l (link)} and \l 2056 {sa-command} {\\sa (see also)} commands. 2057 2058 The \\keyword command is like the \l {target-command} {\\target} 2059 command, except when linking to keyword the link goes to the top of 2060 the QDoc comment where the \\keyword appears in. If you want to 2061 create a link target to a \c section unit within a \\page, use 2062 \\target instead. A keyword can be linked from anywhere using a 2063 simple syntax. 2064 2065 Keywords must be unique over all the documents processed during 2066 the QDoc run. The command uses the rest of the line as its 2067 argument. Be sure to follow the keyword with a line break. 2068 2069 2070 \code 2071 / *! 2072 \class QRegExp 2073 \reentrant 2074 \brief The QRegExp class provides pattern 2075 matching using regular expressions. 2076 \ingroup tools 2077 \ingroup misc 2078 \ingroup shared 2079 2080 \keyword regular expression 2081 2082 Regular expressions, or "regexps", provide a way to 2083 find patterns within text. 2084 2085 ... 2086 * / 2087 \endcode 2088 2089 The location marked with the keyword can be linked to with: 2090 2091 \code 2092 / *! 2093 When a string is surrounded by slashes, it is 2094 interpreted as a \l {QRegExp}{regular expression}. 2095 * / 2096 \endcode 2097 2098 QDoc renders this as: 2099 2100 \quotation 2101 When a string is surrounded by slashes, it is 2102 interpreted as a \l {regular expression}. 2103 \endquotation 2104 2105 If the keyword text contains spaces, the brackets are required. 2106 2107 See also \l {l-command} {\\l (link)}, \l {sa-command} {\\sa (see 2108 also)} and \l {target-command} {\\target}. 2109 2110*/ 2111 2112 2113/*! 2114 \page 09-qdoc-commands-includingimages.html 2115 \previouspage Creating Links 2116 \nextpage Tables and Lists 2117 2118 \title Including Images 2119 2120 The graphic commands makes it possible to include images in the 2121 documentation. The images can be rendered as separate paragraphs, 2122 or within running text. 2123 2124 \target image-command 2125 \section1 \\image 2126 2127 The \\image command expands to the image specified by its first 2128 argument, and renders it centered as a separate paragraph. 2129 2130 The command takes two arguments. The first argument is the name of 2131 the image file. The second argument is optional and is a simple 2132 description of the image, equivalent to the HTML alt="" in an image 2133 tag. The description is used for tooltips and for browsers that don't 2134 support images, like the Lynx text browser. 2135 2136 The remaining text \e{after} the file name is the optional, 2137 description argument. Be sure to follow the file name or the 2138 description with a line break. Curly brackets are required if the 2139 description argument spans multiple lines. 2140 2141 \code 2142 / *! 2143 Qt is a C++ toolkit for cross-platform GUI application development. 2144 2145 \image happyguy.jpg "Happy guy" 2146 2147 Qt provides single-source portability across Microsoft 2148 Windows, macOS, Linux, and all major commercial Unix 2149 variants. It is also available for embedded devices. 2150 * / 2151 \endcode 2152 2153 QDoc renders this as: 2154 2155 \quotation 2156 Qt is a C++ toolkit for cross-platform GUI application development. 2157 2158 \image happyguy.jpg image "Happy guy" 2159 2160 Qt provides single-source portability across Microsoft 2161 Windows, macOS, Linux, and all major commercial Unix 2162 variants. It is also available for embedded devices. 2163 \endquotation 2164 2165 See also \l {inlineimage-command} {\\inlineimage} and \l 2166 {caption-command} {\\caption}. 2167 2168 \target inlineimage-command 2169 \section1 \\inlineimage 2170 2171 The \\inlineimage command expands to the image specified by its 2172 argument. The image is rendered inline with the rest of the text. 2173 2174 The command takes two arguments. The first argument is the name of 2175 the image file. The second argument is optional and is a simple 2176 description of the image, equivalent to the HTML alt="" in an image 2177 tag. The description is used for tooltips, and for when a browser 2178 doesn't support images, like the Lynx text browser. 2179 2180 The most common use of the \\inlineimage command is in lists and 2181 tables. Here is an example of including inline images in a list: 2182 2183 \code 2184 / *! 2185 \list 1 2186 \li \inlineimage happy.gif Oh so happy! 2187 \li \inlineimage happy.gif Oh so happy! 2188 \li \inlineimage happy.gif Oh so happy! 2189 \endlist 2190 * / 2191 \endcode 2192 2193 QDoc renders this as: 2194 2195 \list 1 2196 \li \inlineimage happy.gif Oh so happy! 2197 \li \inlineimage happy.gif Oh so happy! 2198 \li \inlineimage happy.gif Oh so happy! 2199 \endlist 2200 2201 Here is an example of including inline images in a table: 2202 2203 \code 2204 / *! 2205 \table 2206 \header 2207 \li Qt 2208 \li Qt Creator 2209 \row 2210 \li \inlineimage happy.gif Oh so happy! 2211 \li \inlineimage happy.gif Oh so happy! 2212 \row 2213 \li \inlineimage happy.gif Oh so happy! 2214 \li \inlineimage happy.gif Oh so happy! 2215 \endtable 2216 * / 2217 \endcode 2218 2219 QDoc renders this as: 2220 2221 \raw HTML 2222 <table align="center" cellpadding="2" 2223 cellspacing="1" border="0"> 2224 <tr valign="top" bgcolor="#a2c511"> 2225 <th>Qt</th> 2226 <th>Qt Creator</th> 2227 </tr> 2228 <tr valign="top" bgcolor="#f0f0f0"> 2229 <td><img src="images/happy.gif" alt="Oh so happy!" /> 2230 </td> 2231 <td><img src="images/happy.gif" alt="Oh so happy!" /> 2232 </td> 2233 </tr> 2234 <tr valign="top" bgcolor="#f0f0f0"> 2235 <td><img src="images/happy.gif" alt="Oh so happy!"/> 2236 </td> 2237 <td><img src="images/happy.gif" alt="Oh so happy!" /> 2238 </td> 2239 </tr> 2240 </table> 2241 \endraw 2242 2243 The command can also be used to insert an image inline with the 2244 text. 2245 2246 \code 2247 / *! 2248 \inlineimage training.jpg Qt Training 2249 The Qt Programming course is offered as a 2250 five day Open Enrollment Course. The classes 2251 are open to the public. Although the course is open 2252 to anyone who wants to learn, attendees should 2253 have significant experience in C++ development 2254 to derive maximum benefit from the course. 2255 * / 2256 \endcode 2257 2258 QDoc renders this as: 2259 2260 \quotation 2261 \inlineimage training.jpg Qt Training 2262 The Qt Programming course is offered as a 2263 five day Open Enrollment Course. The classes 2264 are open to the public. Although the course is open 2265 to anyone who wants to learn, attendees should 2266 have significant experience in C++ development 2267 to derive maximum benefit from the course. 2268 \endquotation 2269 2270 See also \l {image-command} {\\image} and \l {caption-command} {\\caption}. 2271 2272 \target caption-command 2273 \section1 \\caption 2274 2275 The \\caption command provides a caption for an image. 2276 2277 The command takes all the text up to the end of the paragraph to 2278 be the caption. Experiment until you get the effect you want. 2279 2280 \code 2281 / *! 2282 \table 100% 2283 \row 2284 \li \image windowsvista-pushbutton.png 2285 \caption The QPushButton widget provides a command button. 2286 \li \image windowsvista-toolbutton.png 2287 \caption The QToolButton class provides a quick-access button to commands 2288 or options, usually used inside a QToolBar. 2289 \endtable 2290 * / 2291 \endcode 2292 2293 QDoc renders this as: 2294 2295 \table 100% 2296 \row 2297 \li \image windowsvista-pushbutton.png 2298 \caption The QPushButton widget provides a command button. 2299 \li \image windowsvista-toolbutton.png 2300 \caption The QToolButton class provides a quick-access button to commands 2301 or options, usually used inside a QToolBar. 2302 \endtable 2303 2304 See also \l {image-command} {\\image} and \l {inlineimage-command} 2305 {\\inlineimage} 2306*/ 2307 2308 2309/*! 2310 \page 10-qdoc-commands-tablesandlists.html 2311 \previouspage Including Images 2312 \nextpage Special Content 2313 2314 \title Tables and Lists 2315 2316 These commands enable creating lists and tables. A list is 2317 rendered left aligned as a separate paragraph. A table is rendered 2318 centered as a separate paragraph. The table width depends on the 2319 width of its contents. 2320 2321 \target table-command 2322 \section1 \\table 2323 2324 The \\table and \\endtable commands delimit the contents of a 2325 table. 2326 2327 The command accepts a single argument specifying the table's width 2328 as a percentage of the page width: 2329 2330 \code 2331 / *! 2332 \table 100 % 2333 2334 ... 2335 2336 \endtable 2337 * / 2338 \endcode 2339 2340 The code above ensures that the table will fill all available 2341 space. If the table's width is smaller than 100 %, the table will 2342 be centered in the generated documentation. 2343 2344 A table can contain headers, rows and columns. A row starts with a 2345 \l {row-command} {\\row} command and consists of cells, each of which 2346 starts with an \l {li-command} {\\li} command. There is also a \l 2347 {header-command} {\\header} command which is a special kind of row 2348 that has a special format. 2349 2350 \code 2351 / *! 2352 \table 2353 \header 2354 \li Qt Core Feature 2355 \li Brief Description 2356 \row 2357 \li \l {Signal and Slots} 2358 \li Signals and slots are used for communication 2359 between objects. 2360 \row 2361 \li \l {Layout Management} 2362 \li The Qt layout system provides a simple 2363 and powerful way of specifying the layout 2364 of child widgets. 2365 \row 2366 \li \l {Drag and Drop} 2367 \li Drag and drop provides a simple visual 2368 mechanism which users can use to transfer 2369 information between and within applications. 2370 \endtable 2371 * / 2372 \endcode 2373 2374 QDoc renders this as: 2375 2376 \raw HTML 2377 <table align="center" cellpadding="2" 2378 cellspacing="1" border="0"> 2379 <tr valign="top" bgcolor="#a2c511"> 2380 <th>Qt Core Feature</th> 2381 <th>Brief Description</th> 2382 </tr> 2383 2384 <tr valign="top" bgcolor="#d0d0d0"> 2385 <td> 2386 <a href="http://doc.qt.io/qt-5/signalsandslots.html"> 2387 Signals and Slots</a> 2388 </td> 2389 <td>Signals and slots are used for communication 2390 between objects.</td> 2391 </tr> 2392 2393 <tr valign="top" bgcolor="#c0c0c0"> 2394 <td> 2395 <a href="http://doc.qt.io/qt-5/layout.html"> 2396 Layout Management</a></td> 2397 <td>The Qt layout system provides a simple 2398 and powerful way of specifying the layout 2399 of child widgets.</td> 2400 </tr> 2401 2402 <tr valign="top" bgcolor="#d0d0d0"> 2403 <td> 2404 <a href="http://doc.qt.io/qt-5/dnd.html"> 2405 Drag and Drop</a></td> 2406 <td>Drag and drop provides a simple visual 2407 mechanism which users can use to transfer 2408 information between and within applications.</td> 2409 </tr> 2410 2411 </table> 2412 \endraw 2413 2414 You can also make cells span several rows and columns. For 2415 example: 2416 2417 \code 2418 / *! 2419 \table 2420 \header 2421 \li {3,1} This header cell spans three columns, 2422 but only one row. 2423 \row 2424 \li {2, 1} This table cell spans two columns, 2425 but only one row 2426 \li {1, 2} This table cell spans only one column, 2427 but two rows. 2428 \row 2429 \li A regular table cell 2430 \li A regular table cell 2431 \endtable 2432 * / 2433 \endcode 2434 2435 QDoc renders this as: 2436 2437 \raw HTML 2438 <table align="center" cellpadding="2" cellspacing="1" 2439 border="0"> 2440 2441 <tr valign="top" bgcolor="#a2c511"> 2442 <th colspan="3" rowspan=" 1"> 2443 This header cell spans three columns, but only one row. 2444 </th> 2445 </tr> 2446 2447 <tr valign="top" bgcolor="#d0d0d0"> 2448 <td colspan="2" rowspan=" 1"> 2449 This table cell spans two columns, but only one row. 2450 </td> 2451 <td rowspan=" 2"> 2452 This table cell spans only one column, but two rows. 2453 </td> 2454 </tr> 2455 2456 <tr valign="top" bgcolor="#c0c0c0"> 2457 <td>A regular table cell</td> 2458 <td>A regular table cell</td> 2459 </tr> 2460 2461 </table> 2462 \endraw 2463 2464 See also \l {header-command} {\\header}, \l {row-command} {\\row} and \l {li-command} {\\li}. 2465 2466 \target header-command 2467 \section1 \\header 2468 2469 The \\header command indicates that the following table cells are 2470 the current table's column headers. 2471 2472 The command can only be used within the \l{table-command} 2473 {\\table...\\endtable} commands. A header can contain several 2474 cells. A cell is created with the \l {li-command} {\\li} command. 2475 2476 A header cell's text is centered within the table cell and 2477 rendered using a bold font. 2478 2479 \code 2480 / *! 2481 \table 2482 \header 2483 \li Qt Core Feature 2484 \li Brief Description 2485 \row 2486 \li \l {Signal and Slots} 2487 \li Signals and slots are used for communication 2488 between objects. 2489 \endtable 2490 * / 2491 \endcode 2492 2493 QDoc renders this as: 2494 2495 \raw HTML 2496 <table align="center" cellpadding="2" 2497 cellspacing="1" border="0"> 2498 <tr valign="top" bgcolor="#a2c511"> 2499 <th>Qt Core Feature</th> 2500 <th>Brief Description</th> 2501 </tr> 2502 2503 <tr valign="top" bgcolor="#d0d0d0"> 2504 <td> 2505 <a href="http://doc.qt.io/qt-5/signalsandslots.html"> 2506 Signals and Slots</a> 2507 </td> 2508 <td>Signals and slots are used for communication 2509 between objects.</td> 2510 </tr> 2511 </table> 2512 \endraw 2513 2514 See also \l {table-command} {\\table}, \l {row-command} {\\row} and \l {li-command} {\\li}. 2515 2516 \target row-command 2517 \section1 \\row 2518 2519 The \\row command begins a new row in a table. The \l {li-command} 2520 {\\li items} that belong in the new row will immediately follow the 2521 \\row. 2522 2523 The command can only be used within the \l{table-command} 2524 {\\table...\\endtable} commands. A row can contain several 2525 cells. A cell is created with the \l {li-command} {\\li} command. 2526 2527 The background cell color of each row alternates between two 2528 shades of grey, making it easier to distinguish the rows from each 2529 other. The cells' contents is left aligned. 2530 2531 \code 2532 / *! 2533 \table 2534 \header 2535 \li Qt Core Feature 2536 \li Brief Description 2537 \row 2538 \li \l {Signal and Slots} 2539 \li Signals and slots are used for communication 2540 between objects. 2541 \row 2542 \li \l {Layout Management} 2543 \li The Qt layout system provides a simple 2544 and powerful way of specifying the layout 2545 of child widgets. 2546 \row 2547 \li \l {Drag and Drop} 2548 \li Drag and drop provides a simple visual 2549 mechanism which users can use to transfer 2550 information between and within applications. 2551 \endtable 2552 * / 2553 \endcode 2554 2555 QDoc renders this as: 2556 2557 \raw HTML 2558 <table align="center" cellpadding="2" 2559 cellspacing="1" border="0"> 2560 <tr valign="top" bgcolor="#a2c511"> 2561 <th>Qt Core Feature</th> 2562 <th>Brief Description</th> 2563 </tr> 2564 2565 <tr valign="top" bgcolor="#d0d0d0"> 2566 <td> 2567 <a href="http://doc.qt.io/qt-5/signalsandslots.html"> 2568 Signals and Slots</a> 2569 </td> 2570 <td>Signals and slots are used for communication 2571 between objects.</td> 2572 </tr> 2573 2574 <tr valign="top" bgcolor="#c0c0c0"> 2575 <td> 2576 <a href="http://doc.qt.io/qt-5/layout.html"> 2577 Layout Management</a></td> 2578 <td>The Qt layout system provides a simple 2579 and powerful way of specifying the layout 2580 of child widgets.</td> 2581 </tr> 2582 2583 <tr valign="top" bgcolor="#d0d0d0"> 2584 <td> 2585 <a href="http://doc.qt.io/qt-5/dnd.html"> 2586 Drag and Drop</a></td> 2587 <td>Drag and drop provides a simple visual 2588 mechanism which users can use to transfer 2589 information between and within applications.</td> 2590 </tr> 2591 2592 </table> 2593 \endraw 2594 2595 See also \l {table-command} {\\table}, \l {header-command} 2596 {\\header}, and \l {li-command} {\\li}. 2597 2598 \target value-command 2599 \section1 \\value 2600 2601 The \\value command starts the documentation of a C++ enum item. 2602 2603 The command's first argument is the value name. The value name may 2604 be preceded by an optional \e since clause enclosed in square 2605 brackets. The value description follows the value name. The description 2606 ends at the next blank line or \\value. The arguments are rendered in a 2607 table. 2608 2609 Without a \e since clause, a \\value command could look like this: 2610 2611 \code 2612 \value QtInfoMsg A message generated by the qInfo() function. 2613 \endcode 2614 2615 The same command with a \e since clause would look like this: 2616 2617 \code 2618 \value [since 5.5] QtInfoMsg A message generated by the qInfo() function. 2619 \endcode 2620 2621 The documentation will be located in the associated class, header 2622 file or namespace documentation. See the \l {enum-command} 2623 {\\enum} documentation for an example. 2624 2625 \note Since Qt 5.4, \\value command can also be used outside the 2626 \l {enum-command} {\\enum} topic. In this case, QDoc renders a 2627 two-column table listing the constant name (taken as-is from the 2628 first argument) and its description. This can be used, for 2629 example, in \l {qmlproperty-command}{\\qmlproperty} topic for 2630 documenting acceptable values for a QML enumeration property. 2631 2632 See also \l {enum-command} {\\enum} and \l {omitvalue-command} {\\omitvalue}. 2633 2634 \target omitvalue-command 2635 \section1 \\omitvalue 2636 2637 The \\omitvalue command excludes a C++ enum item from the 2638 documentation. 2639 2640 The command's only argument is the name of the enum item that will 2641 be omitted. See the \l {enum-command} {\\enum} documentation for 2642 an example. 2643 2644 See also \l {enum-command} {\\enum} and \l {value-command} 2645 {\\value} \l {since-command}{\\since} 2646 2647 \target list-command 2648 \section1 \\list 2649 2650 The \\list and \\endlist commands delimit a list of items. 2651 2652 Create each list item with the \l {li-command} {\\li} command. A 2653 list always contains one or more items. Lists can be nested. For 2654 example: 2655 2656 \code 2657 / *! 2658 \list 2659 \li Qt Reference Documentation: Getting Started 2660 \list 2661 \li How to Learn Qt 2662 \li Installation 2663 \list 2664 \li Qt/X11 2665 \li Qt/Windows 2666 \li Qt/Mac 2667 \li Qt/Embedded 2668 \endlist 2669 \li Tutorial and Examples 2670 \endlist 2671 \endlist 2672 * / 2673 \endcode 2674 2675 QDoc renders this as: 2676 2677 \list 2678 \li Qt Reference Documentation: Getting Started 2679 \list 2680 \li How to Learn Qt 2681 \li Installation 2682 \list 2683 \li Qt/X11 2684 \li Qt/Windows 2685 \li Qt/Mac 2686 \li Qt/Embedded 2687 \endlist 2688 \li Tutorial and Examples 2689 \endlist 2690 \endlist 2691 2692 The \\list command takes an optional argument providing 2693 alternative appearances for the list items. 2694 2695 \code 2696 / *! 2697 \list 2698 \li How to Learn Qt 2699 \li Installation 2700 \li Tutorial and Examples 2701 \endlist 2702 * / 2703 \endcode 2704 2705 QDoc renders the list items with bullets (the default): 2706 2707 \list 2708 \li How to Learn Qt 2709 \li Installation 2710 \li Tutorial and Examples 2711 \endlist 2712 2713 If you provide 'A' as an argument to the \\list command, the 2714 bullets are replaced with characters in alphabetical order: 2715 2716 \list A 2717 \li How to Learn Qt 2718 \li Installation 2719 \li Tutorial and Examples 2720 \endlist 2721 2722 If you replace 'A' with '1', the list items are numbered in 2723 ascending order: 2724 2725 \list 1 2726 \li How to Learn Qt 2727 \li Installation 2728 \li Tutorial and Examples 2729 2730 \endlist 2731 2732 If you provide 'i' as the argument, the bullets are replaced with 2733 roman numerals: 2734 2735 \list i 2736 \li How to Learn Qt 2737 \li Installation 2738 \li Tutorial and Examples 2739 \endlist 2740 2741 Finally, you can make the list items appear with roman numbers 2742 following in ascending order if you provide 'I' as the optional 2743 argument: 2744 2745 \list I 2746 \li How to Learn Qt 2747 \li Installation 2748 \li Tutorial and Examples 2749 \endlist 2750 2751 You can also make the listing start at any character or number by 2752 simply provide the number or character you want to start at. For 2753 example: 2754 2755 \code 2756 / *! 2757 \list G 2758 \li How to Learn Qt 2759 \li Installation 2760 \li Tutorial and Examples 2761 \endlist 2762 * / 2763 \endcode 2764 2765 QDoc renders this as: 2766 2767 \list G 2768 \li How to Learn Qt 2769 \li Installation 2770 \li Tutorial and Examples 2771 \endlist 2772 2773 See also \l {li-command} {\\li}. 2774 2775 \target li-command 2776 \section1 \\li (table cell, list item) 2777 2778 The \\li command marks a table cell or a list item. This command 2779 is only used in \l{table-command} {tables} and \l{list-command} 2780 {lists}. 2781 2782 It considers everything as its argument until the next \\li command, until the 2783 next \l {table-command} {\\endtable}, or \l {list-command} {\\endlist} 2784 command. See \l {table-command} {\\table} and \l {list-command} {\\list} 2785 for examples. 2786 2787 If the command is used within a table, you can also specify 2788 how many rows or columns the item should span. 2789 2790 \code 2791 / *! 2792 \table 2793 \header 2794 \li {3,1} This header cell spans three columns 2795 but only one row. 2796 \row 2797 \li {2, 1} This table item spans two columns 2798 but only one row 2799 \li {1, 2} This table item spans only one column, 2800 but two rows. 2801 \row 2802 \li A regular table item 2803 \li A regular table item 2804 \endtable 2805 * / 2806 \endcode 2807 2808 QDoc renders this as: 2809 2810 \raw HTML 2811 <table align="center" cellpadding="2" cellspacing="1" 2812 border="0"> 2813 2814 <tr valign="top" bgcolor="#a2c511"> 2815 <th colspan="3" rowspan=" 1"> 2816 This header cell spans three columns, but only one row. 2817 </th> 2818 </tr> 2819 2820 <tr valign="top" bgcolor="#d0d0d0"> 2821 <td colspan="2" rowspan=" 1"> 2822 This table item spans two columns, but only one row. 2823 </td> 2824 <td rowspan=" 2"> 2825 This table item spans only one column, but two rows. 2826 </td> 2827 </tr> 2828 2829 <tr valign="top" bgcolor="#c0c0c0"> 2830 <td>A regular table item</td> 2831 <td>A regular table item</td> 2832 </tr> 2833 2834 </table> 2835 \endraw 2836 2837 If not specified, the item will span one column and one row. 2838 2839 See also \l {table-command} {\\table}, \l {header-command} 2840 {\\header}, and \l {list-command} {\\list}. 2841 2842*/ 2843 2844 2845/*! 2846 \page 11-qdoc-commands-specialcontent.html 2847 \previouspage Tables and Lists 2848 \nextpage Miscellaneous 2849 2850 \title Special Content 2851 2852 The document contents commands identify parts of the documentation, 2853 parts with a special rendering, conceptual meaning or 2854 function. 2855 2856 \target quotation-command 2857 \section1 \\quotation 2858 2859 The \\quotation and \\endquotation commands delimit a long quotation. 2860 2861 The text in the delimited block is surrounded by 2862 \b{<blockquote>} and \b{</blockquote>} in the html output, 2863 e.g.: 2864 2865 \code 2866 / *! 2867 Although the prospect of a significantly broader market is 2868 good news for Firstlogic, the notion also posed some 2869 challenges. Dave Dobson, director of technology for the La 2870 Crosse, Wisconsin-based company, said: 2871 2872 \quotation 2873 As our solutions were being adopted into new 2874 environments, we saw an escalating need for easier 2875 integration with a wider range of enterprise 2876 applications. 2877 \endquotation 2878 * / 2879 \endcode 2880 2881 The text in the \b{\\quotation} block will appear in the generated HTML as: 2882 2883 \code 2884 <blockquote> 2885 <p>As our solutions were being adopted into new environments, 2886 we saw an escalating need for easier integration with a wider 2887 range of enterprise applications.</p> 2888 </blockquote> 2889 \endcode 2890 2891 The built-in style sheet for most browsers will render the 2892 contents of the <blockquote> tag with left and right 2893 indentations. The example above would be rendered as: 2894 2895 \quotation 2896 As our solutions were being adopted into new 2897 environments, we saw an escalating need for easier 2898 integration with a wider range of enterprise 2899 applications. 2900 \endquotation 2901 2902 But you can redefine the \b{<blockquote>} tag in your style.css file. 2903 2904 \target footnote-command 2905 \section1 \\footnote 2906 2907 The \\footnote and \\endfootnote commands delimit a footnote. 2908 2909 The footnote is rendered at the bottom of the page. 2910 2911 \warning The \b{\\footnote} and \b{\\endfootnote} commands 2912 have not been implemented. The footnote is rendered as a regular 2913 HTML paragraph. 2914 2915 \target note-command 2916 \section1 \\note 2917 2918 The \\note command defines a new paragraph preceded by "Note:" 2919 in bold. 2920 2921 \target tableofcontents-command 2922 \section1 \\tableofcontents 2923 2924 The \\tableofcontents command has been disabled because QDoc 2925 now generates a table of contents automatically. 2926 2927 The automatically generated table of contents appears in the upper 2928 righthand corner of the page. 2929 2930 \target brief-command 2931 \section1 \\brief 2932 2933 The \\brief command introduces a one-sentence description of a 2934 class, namespace, header file, property, or variable. 2935 2936 The brief text is used to introduce the documentation of the 2937 associated object, and in lists generated using the \l 2938 {generatelist-command} {\\generatelist} command and the \l 2939 {annotatedlist-command} {\\annotatedlist} command. 2940 2941 The \\brief command can be used in two significant different ways: 2942 \l {brief class} {One for classes, namespaces and header files}, 2943 and \l {brief-property} {one for properties and variables}. 2944 2945 \target brief-property 2946 2947 When the \\brief command is used to describe a property or a 2948 variable, the brief text must be a sentence fragment starting with 2949 "whether" (for a boolean property or variable) or starting with 2950 "the" (for any other property or variable). 2951 2952 For example the boolean QWidget::isWindow property: 2953 2954 \code 2955 / *! 2956 \property QWidget::isActiveWindow 2957 \brief Whether this widget's window is the active window. 2958 2959 The active window is the window that contains the widget that 2960 has keyboard focus. 2961 2962 When popup windows are visible, this property is \c true 2963 for both the active window \e and the popup. 2964 2965 \sa activateWindow(), QApplication::activeWindow() 2966 * / 2967 \endcode 2968 2969 and the QWidget::geometry property 2970 2971 \code 2972 / *! 2973 \property QWidget::geometry 2974 \brief The geometry of the widget relative to its parent and 2975 excluding the window frame. 2976 2977 When changing the geometry, the widget, if visible, 2978 receives a move event (moveEvent()) and/or a resize 2979 event (resizeEvent()) immediately. 2980 2981 ... 2982 2983 \sa frameGeometry(), rect(), ... 2984 * / 2985 \endcode 2986 2987 QDoc renders this as: 2988 2989 \quotation 2990 \raw HTML 2991 <h3>geometry : 2992 <a href="http://doc.qt.io/qt-5/qrect.html">QRect</a> 2993 </h3> 2994 \endraw 2995 2996 This property holds the geometry of the widget relative 2997 to its parent and excluding the window frame. 2998 2999 ... 3000 3001 Access functions: 3002 \list 3003 \li \b {const QRect & geometry () const} 3004 \li \b {void setGeometry ( int x, int y, int w, int h )} 3005 \li \b {void setGeometry ( const QRect & )} 3006 \endlist 3007 3008 See also \l 3009 {QWidget::frameGeometry()} {frameGeometry()}, \l 3010 {QWidget::rect()} {rect()}, ... 3011 \endquotation 3012 3013 \target brief class 3014 3015 When the \\brief command is used to describe a class, we recommend 3016 using a complete sentence like this: 3017 3018 \code 3019 The <classname> class is|provides|contains|specifies... 3020 \endcode 3021 3022 \warning Do not repeat your detailed description with the same sentence as 3023 the brief statement will be the first paragraph of the detailed 3024 description. 3025 3026 \code 3027 / *! 3028 \class PreviewWindow 3029 \brief The PreviewWindow class is a custom widget 3030 displaying the names of its currently set 3031 window flags in a read-only text editor. 3032 3033 The PreviewWindow class inherits QWidget. The widget 3034 displays the names of its window flags set with the 3035 setWindowFlags() function. It is also provided with a 3036 QPushButton that closes the window. 3037 3038 ... 3039 3040 \sa QWidget 3041 * / 3042 \endcode 3043 3044 QDoc renders this as: 3045 3046 \quotation 3047 \raw HTML 3048 <h1>PreviewWindow Class Reference</h1> 3049 \endraw 3050 3051 The PreviewWindow class is a custom widget displaying 3052 the names of its currently set window flags in a 3053 read-only text editor. \l {preview window} {More...} 3054 3055 \raw HTML 3056 <h3>Properties</h3> 3057 \endraw 3058 3059 \list 3060 \li 52 properties inherited from QWidget 3061 \li 1 property inherited from QObject 3062 \endlist 3063 3064 \raw HTML 3065 <h3>Public Functions</h3> 3066 \endraw 3067 3068 \list 3069 \li \l {constructor} {PreviewWindow}(QWidget *parent = 0) 3070 \li void \l {function} {setWindowFlags}(Qt::WindowFlags flags) 3071 \endlist 3072 3073 \list 3074 \li 183 public functions inherited from QWidget 3075 \li 28 public functions inherited from QObject 3076 \endlist 3077 3078 \raw HTML 3079 <h3>Public Slots</h3> 3080 \endraw 3081 3082 \list 3083 \li 17 public slots inherited from QWidget 3084 \li 1 public slot inherited from QObject 3085 \endlist 3086 3087 \raw HTML 3088 <h3>Additional Inherited Members</h3> 3089 \endraw 3090 3091 \list 3092 \li 1 signal inherited from QWidget 3093 \li 1 signal inherited from QObject 3094 \li 4 static public members inherited from QWidget 3095 \li 4 static public members inherited from QObject 3096 \li 39 protected functions inherited from QWidget 3097 \li 7 protected functions inherited from QObject 3098 \endlist 3099 3100 \target preview window 3101 3102 \raw HTML 3103 <hr /> 3104 <h2>Detailed Description</h2> 3105 \endraw 3106 3107 The PreviewWindow class is a custom widget displaying 3108 the names of its currently set window flags in a 3109 read-only text editor. 3110 3111 The PreviewWindow class inherits QWidget. The widget 3112 displays the names of its window flags set with the \l 3113 {function} {setWindowFlags()} function. It is also 3114 provided with a QPushButton that closes the window. 3115 3116 ... 3117 3118 See also QWidget. 3119 3120 \raw HTML 3121 <hr /> 3122 <h2>Member Function Documentation</h2> 3123 \endraw 3124 3125 \target constructor 3126 \raw HTML 3127 <h3>PreviewWindow(QWidget *parent = 0)</h3> 3128 \endraw 3129 3130 Constructs a preview window widget with \e parent. 3131 3132 \target function 3133 \raw HTML 3134 <h3>setWindowFlags(Qt::WindowFlags flags)</h3> 3135 \endraw 3136 3137 Sets the widgets flags using the 3138 QWidget::setWindowFlags() function. 3139 3140 Then runs through the available window flags, 3141 creating a text that contains the names of the flags 3142 that matches the flags parameter, displaying 3143 the text in the widgets text editor. 3144 \endquotation 3145 3146 Using \\brief in a \l{namespace-command}{\\namespace}: 3147 3148 \code 3149 / *! 3150 \namespace Qt 3151 3152 \brief The Qt namespace contains miscellaneous identifiers 3153 used throughout the Qt library. 3154 * / 3155 \endcode 3156 3157 Using \\brief in a \l{headerfile-command}{\\headerfile}: 3158 3159 \code 3160 / *! 3161 \headerfile <QtGlobal> 3162 \title Global Qt Declarations 3163 3164 \brief The <QtGlobal> header file provides basic 3165 declarations and is included by all other Qt headers. 3166 3167 \sa <QtAlgorithms> 3168 * / 3169 \endcode 3170 3171 See also \l{property-command} {\\property}, \l{class-command} 3172 {\\class}, \l{namespace-command} {\\namespace} and 3173 \l{headerfile-command} {\\headerfile}. 3174 3175 \target legalese-command 3176 \section1 \\legalese 3177 3178 The \\legalese and \\endlegalese commands delimit a license agreement. 3179 3180 In the generated HTML, the delimited text is surrounded by a \b 3181 {<div class="LegaleseLeft">} and \b {</div>} tags. 3182 3183 An example of a license agreement enclosed in \\legalese 3184 and \\endlegalese: 3185 3186 \code 3187 / *! 3188 \legalese 3189 Copyright 1996 Daniel Dardailler. 3190 3191 Permission to use, copy, modify, distribute, and sell this 3192 software for any purpose is hereby granted without fee, 3193 provided that the above copyright notice appear in all 3194 copies and that both that copyright notice and this 3195 permission notice appear in supporting documentation, and 3196 that the name of Daniel Dardailler not be used in 3197 advertising or publicity pertaining to distribution of the 3198 software without specific, written prior permission. Daniel 3199 Dardailler makes no representations about the suitability of 3200 this software for any purpose. It is provided "as is" 3201 without express or implied warranty. 3202 3203 Modifications Copyright 1999 Matt Koss, under the same 3204 license as above. 3205 \endlegalese 3206 * / 3207 \endcode 3208 3209 It will appear in the generated HTML as: 3210 3211 \code 3212 <div class="LegaleseLeft"> 3213 <p>Copyright 1996 Daniel Dardailler.</p> 3214 <p>Permission to use, copy, modify, distribute, and sell 3215 this software for any purpose is hereby granted without fee, 3216 provided that the above copyright notice appear in all 3217 copies and that both that copyright notice and this 3218 permission notice appear in supporting documentation, and 3219 that the name of Daniel Dardailler not be used in 3220 advertising or publicity pertaining to distribution of the 3221 software without specific, written prior permission. Daniel 3222 Dardailler makes no representations about the suitability of 3223 this software for any purpose. It is provided "as is" 3224 without express or implied warranty.</p> 3225 3226 <p>Modifications Copyright 1999 Matt Koss, under the same 3227 license as above.</p> 3228 </div> 3229 \endcode 3230 3231 If the \\endlegalese command is omitted, QDoc will process the 3232 \\legalese command but considers the rest of the documentation 3233 page as the license agreement. 3234 3235 Ideally, the license text is located with the licensed code. 3236 3237 Elsewhere, the documentation identified as \e{\\legalese} command 3238 can be accumulated using \l {generatelist-command} {\\generatelist} 3239 with \c {legalese} as the argument. This is useful for generating 3240 an overview of the license agreements associated with the source 3241 code. 3242 3243 \note The output of the \c {\generatelist legalese} command includes 3244 the \\legalese texts in the current documentation project only. If 3245 the current documentation project depends on other modules, their 3246 license texts will not be listed. 3247 3248 \target warning-command 3249 \section1 \\warning 3250 3251 The \\warning command prepends "Warning:" to the command's 3252 argument, in bold font. 3253 3254 \code 3255 / *! 3256 Qt::HANDLE is a platform-specific handle type 3257 for system objects. This is equivalent to 3258 \c{void *} on Windows and macOS, and to 3259 \c{unsigned long} on X11. 3260 3261 \warning Using this type is not portable. 3262 * / 3263 \endcode 3264 3265 QDoc renders this as: 3266 3267 \quotation 3268 Qt::HANDLE is a platform-specific handle type 3269 for system objects. This is equivalent to 3270 \c{void *} on Windows and macOS, and to 3271 \c{unsigned long} on X11. 3272 3273 \warning Using this type is not portable. 3274 \endquotation 3275 3276*/ 3277 3278 3279/*! 3280 \page 12-0-qdoc-commands-miscellaneous.html 3281 \previouspage Special Content 3282 \nextpage The QDoc Configuration File 3283 3284 \title Miscellaneous 3285 3286 These commands provide miscellaneous functions connected to the 3287 visual appearance of the documentation, and to the process of 3288 generating the documentation. 3289 3290 \target annotatedlist-command 3291 \section1 \\annotatedlist 3292 3293 The \\annotatedlist command expands to a list of the members of a 3294 group, each member listed with its \e {brief} text. Below is an 3295 example from the Qt Reference Documentation: 3296 3297 \code 3298 / *! 3299 ... 3300 \section1 Drag and Drop Classes 3301 3302 These classes deal with drag and drop and the necessary mime type 3303 encoding and decoding. 3304 3305 \annotatedlist draganddrop 3306 3307 * / 3308 \endcode 3309 3310 This generates a list of all the C++ classes and/or QML types in 3311 the \e{draganddrop} group. A C++ class or QML type in the 3312 \e{draganddrop} group will have \e{\\ingroup draganddrop} in its 3313 \e{\\class} or \e{\\qmltype} comment. 3314 3315 3316 \target generatelist-command 3317 \section1 \\generatelist 3318 3319 The \\generatelist command expands to a list of links to the 3320 documentation entities in a group. Below is an example from the Qt 3321 Reference Documentation: 3322 3323 \code 3324 / *! 3325 \page classes.html 3326 \title All Classes 3327 3328 For a shorter list that only includes the most 3329 frequently used classes, see \l{Qt's Main Classes}. 3330 3331 \generatelist classes Q 3332 * / 3333 \endcode 3334 3335 This generates the \e {All Classes} page. The command accepts the 3336 following arguments: 3337 3338 \target table example 3339 \section2 \c annotatedclasses 3340 3341 The \c annotatedclasses argument provides a table containing the 3342 names of all the classes, and a description of each class. Each 3343 class name is a link to the class's reference documentation. For 3344 example: 3345 3346 \table 3347 \row 3348 \li QDial 3349 \li Rounded range control (like a speedometer or potentiometer) 3350 \row 3351 \li QDialog 3352 \li The base class of dialog windows 3353 \row 3354 \li QDir 3355 \li Access to directory structures and their contents 3356 \endtable 3357 3358 A C++ class is documented with the \l {class-command} {\\class} 3359 command. The annotation for the class is taken from the argument 3360 of the class comment's \l {brief-command} {\\brief} command. 3361 3362 \section2 \c annotatedexamples 3363 3364 The \c annotatedexamples argument provides a complete list of all 3365 examples as a set of tables containing the titles of all the 3366 examples, and a description of each example. Each title is a 3367 link to the example's documentation. 3368 3369 A separate table for each module (that has documented examples) 3370 is generated, provided that the module has defined a 3371 navigation.landingpage configuration variable. The \e landingpage 3372 variable is used as a title for a header that precedes each table. 3373 3374 \section2 \c annotatedattributions 3375 3376 The \c annotatedattributions argument provides a complete list of all 3377 attributions as a set of tables containing the titles of all the 3378 attributions, and a description of each attribution. Each title is a 3379 link to the attribution's page. 3380 3381 A separate table for each module (that has attributions) 3382 is generated, provided that the module has defined a 3383 navigation.landingpage configuration variable. The \e landingpage 3384 variable is used as a title for a header that precedes each table. 3385 3386 \target list example 3387 \section2 \c {classes <prefix>} 3388 3389 The \c classes argument provides a complete alphabetical list of 3390 the classes. The second argument, \c{<prefix>}, is the common 3391 prefix for the class names. The class names will be sorted on the 3392 character that follows the common prefix. e.g. The common prefix 3393 for the Qt classes is \c Q. The common prefix argument is 3394 optional. If no common prefix is provided, the class names will 3395 be sorted on their first character. 3396 3397 Each class name becomes a link to the class's reference 3398 documentation. This command is used to generate the 3399 \e {All Classes} page this way: 3400 3401 \code 3402 / *! 3403 \page classes.html 3404 \title All Classes 3405 \ingroup classlists 3406 3407 \brief Alphabetical list of classes. 3408 3409 This is a list of all Qt classes. For classes that 3410 have been deprecated, see the \l{Obsolete Classes} 3411 list. 3412 3413 \generatelist classes Q 3414 * / 3415 \endcode 3416 3417 A C++ class is documented with the \l {class-command} {\\class} 3418 command. 3419 3420 \section2 \c classesbymodule 3421 3422 When this argument is used, a second argument is required, which 3423 specifies the module whose classes are to be listed. QDoc 3424 generates a table containing those classes. Each class is listed 3425 with the text of its \l{brief-command} {\\brief} command. 3426 3427 For example, this command can be used on a module page as follows: 3428 3429 \code 3430 / *! 3431 \page phonon-module.html 3432 \module Phonon 3433 \title Phonon Module 3434 \ingroup modules 3435 3436 \brief Contains namespaces and classes for multimedia functionality. 3437 3438 \generatelist{classesbymodule Phonon} 3439 3440 ... 3441 3442 * / 3443 \endcode 3444 3445 Each class that is a member of the specified module must be marked 3446 with the \l {inmodule-command} {\\inmodule} command in its \\class 3447 comment. 3448 3449 \section2 \c qmltypesbymodule 3450 3451 Similar to \c classesbymodule argument, but used for listing the 3452 QML types from the QML module specified with the second argument. 3453 3454 \note Support for this argument was introduced in QDoc 5.6. 3455 3456 \section2 \c jstypesbymodule 3457 3458 Similar to \c classesbymodule argument, but used for listing the 3459 JavaScript types from the module specified with the second argument. 3460 3461 \note Support for this argument was introduced in QDoc 5.6. 3462 3463 \section2 \c {examplefiles [regular_expression]} 3464 3465 The \c examplefiles argument lists the files that are part of 3466 an example project. The optional second argument is a regular 3467 expression; if provided, only the files whose path matches with 3468 the regular expression are listed. 3469 3470 The \c examplefiles argument can be only used within example 3471 documentation (see \l {example-command}{\\example}), and is 3472 typically used together with the \l {noautolist-command}{\\noautolist} 3473 command. 3474 3475 \section2 \c {exampleimages [regular_expression]} 3476 3477 The \c exampleimages argument lists the images that are part of 3478 an example project. The optional second argument is a regular 3479 expression; if provided, only the image files whose path matches 3480 with the regular expression are listed. 3481 3482 The \c exampleimages argument can be only used within example 3483 documentation (see \l {example-command}{\\example}), and is 3484 typically used together with the \l {noautolist-command}{\\noautolist} 3485 command. 3486 3487 \section2 \c functionindex 3488 3489 The \c functionindex argument provides a complete alphabetical 3490 list of all the documented member functions. It is normally used 3491 only to generate the \e {Qt function index} page 3492 this way: 3493 3494 \code 3495 / *! 3496 \page functions.html 3497 \title All Functions 3498 \ingroup funclists 3499 3500 \brief All documented Qt functions listed alphabetically with a 3501 link to where each one is declared. 3502 3503 This is the list of all documented member functions and global 3504 functions in the Qt API. Each function has a link to the 3505 class or header file where it is declared and documented. 3506 3507 \generatelist functionindex 3508 * / 3509 \endcode 3510 3511 \section2 \c legalese 3512 3513 The \c legalese argument tells QDoc to generate a list of licenses in 3514 the current documentation project. Each license is identified using 3515 the \l {legalese-command} {\\legalese} command. 3516 3517 \section2 \c overviews 3518 3519 The \c overviews argument is used to tell QDoc to generate a list 3520 by concatenating the contents of all the \l {group-command} 3521 {\\group} pages. Qt uses it to generate the \e {overviews} page 3522 this way: 3523 3524 \code 3525 / *! 3526 \page overviews.html 3527 3528 \title All Overviews and HOWTOs 3529 3530 \generatelist overviews 3531 * / 3532 \endcode 3533 3534 \section2 \c attributions 3535 3536 The \c attributions argument is used to tell QDoc to generate a list 3537 of attributions in the documentation. 3538 3539 \section2 \c related 3540 3541 The \c related argument is used in combination with the \l 3542 {group-command} {\\group} and \l {ingroup-command} {\\ingroup} 3543 commands to list all the overviews related to a specified 3544 group. For example, the page for the \e {Programming with Qt} 3545 page is generated this way: 3546 3547 \code 3548 / *! 3549 \group qt-basic-concepts 3550 \title Programming with Qt 3551 3552 \brief The basic architecture of the Qt cross-platform application and UI framework. 3553 3554 Qt is a cross-platform application and UI framework for 3555 writing web-enabled applications for desktop, mobile, and 3556 embedded operating systems. This page contains links to 3557 articles and overviews explaining key components and 3558 techniuqes used in Qt development. 3559 3560 \generatelist {related} 3561 * / 3562 \endcode 3563 3564 Each page listed on this group page contains the command: 3565 3566 \code 3567 \ingroup qt-basic-concepts 3568 \endcode 3569 3570 \target if-command 3571 \section1 \\if 3572 3573 The \\if command and the corresponding \\endif command 3574 enclose parts of a QDoc comment that only will be included if 3575 the condition specified by the command's argument is true. 3576 3577 The command reads the rest of the line and parses it as an C++ #if 3578 statement. 3579 3580 \code 3581 / *! 3582 \if defined(opensourceedition) 3583 3584 \note This edition is for the development of 3585 \l{Qt Open Source Edition} {Free and Open Source} 3586 software only; see \l{Qt Commercial Editions}. 3587 3588 \endif 3589 * / 3590 \endcode 3591 3592 This QDoc comment will only be rendered if the \c 3593 opensourceedition preprocessor symbol is defined, and specified in 3594 the \l {defines-variable} {defines} variable in the configuration 3595 file to make QDoc process the code within #ifdef and #endif: 3596 3597 \code 3598 defines = opensourceedition 3599 \endcode 3600 3601 You can also define the preprocessor symbol manually on the 3602 command line. For more information see the documentation of the \l 3603 {defines-variable} {defines} variable. 3604 3605 See also \l{endif-command} {\\endif}, \l{else-command} {\\else}, 3606 \l {defines-variable} {defines} and \l {falsehoods-variable} 3607 {falsehoods}. 3608 3609 \target endif-command 3610 \section1 \\endif 3611 3612 The \\endif command and the corresponding \\if command 3613 enclose parts of a QDoc comment that will be included if 3614 the condition specified by the \l {if-command} {\\if} command's 3615 argument is true. 3616 3617 For more information, see the documentation of the \l {if-command} 3618 {\\if} command. 3619 3620 See also \l{if-command} {\\if}, \l{else-command} {\\else}, \l 3621 {defines-variable} {defines} and \l {falsehoods-variable} 3622 {falsehoods}. 3623 3624 \target else-command 3625 \section1 \\else 3626 3627 The \\else command specifies an alternative if the 3628 condition in the \l {if-command} {\\if} command is false. 3629 3630 The \\else command can only be used within \l {if-command} 3631 {\\if...\\endif} commands, but is useful when there is only two 3632 alternatives. 3633 3634 \target include-command 3635 \section1 \\include 3636 3637 The \\include command sends all or part of the file specified by 3638 its first argument to the QDoc input stream to be processed as a 3639 QDoc comment snippet. 3640 3641 The command is useful when some snippet of commands or text is to 3642 be used in multiple places in the documentation. Use the \\include 3643 command wherever you want to insert a snippet into the documentation. 3644 The file containing the snippet to include, must be located under the 3645 path(s) listed in the \l{sourcedirs-variable}{sourcedirs} or 3646 \l{exampledirs-variable}{exampledirs} QDoc configuration variable. 3647 It can be either any source file parsed by QDoc (or even the same one 3648 where \\include command is used), or any other text file. To store 3649 snippets in a separate file that is not meant to be parsed by QDoc, 3650 use a file extension that is not listed in 3651 \l{sources.fileextensions-variable}{sources.fileextensions}; 3652 for example, \c .qdocinc. 3653 3654 The command can have either one or two arguments. The first 3655 argument is always a file name. The contents of the file must be 3656 QDoc input, in other words, a sequence of QDoc commands and text, but 3657 without the enclosing QDoc comment \c{/}\c{*!} ... \c{*}\c{/} delimiters. 3658 If you want to include the entire named file, don't use the second 3659 argument. If you want to include only part of the file, see the 3660 \l{2-argument-form}{two argument form} below. Here is an example 3661 of the one argument form: 3662 3663 \code 3664 / *! 3665 \page corefeatures.html 3666 \title Core Features 3667 3668 \include examples/signalandslots.qdocinc 3669 \include examples/objectmodel.qdocinc 3670 \include examples/layoutmanagement.qdocinc 3671 * / 3672 \endcode 3673 3674 QDoc renders this page \l{corefeatures.html} {as shown here}. 3675 3676 \target 2-argument-form 3677 \section2 \\include filename snippet-identifier 3678 3679 It is a waste of time to make a separate \c .qdocinc file for every 3680 QDoc include snippet you want to use in multiple places in the 3681 documentation, especially given that you probably have to put the 3682 copyright/license notice in every one of these files. So if you 3683 have a large number of snippets to be included, you can put them all in a 3684 single file if you want, and surround each one with: 3685 \code 3686 //! [snippet-id1] 3687 3688 QDoc commands and text... 3689 3690 //! [snippet-id1] 3691 3692 //! [snippet-id2] 3693 3694 More QDoc commands and text... 3695 3696 //! [snippet-id2] 3697 \endcode 3698 3699 Then you can use the two-argument form of the command: 3700 3701 \code 3702 \input examples/signalandslots.qdocinc snippet-id2 3703 \input examples/objectmodel.qdocinc another-snippet-id 3704 \endcode 3705 3706 It works as expected. The sequence of QDoc commands and text found 3707 between the two tags with the same name as the second argument is 3708 sent to the QDoc input stream. You can even have nested snippets. 3709 3710 \note Snippet identifiers work also within documentation comment 3711 (\beginqdoc .. \endqdoc) blocks, so it's not necessary to use a 3712 separate \c .qdocinc file. When processing a comment block, QDoc 3713 removes any \c {//!} comment lines from the generated output. 3714 3715 \target meta-command 3716 \section1 \\meta 3717 3718 The \\meta command is used for adding metadata to example documentation, 3719 and when generating HTML output for specifying the \e maintainer(s) of a 3720 C++ class. 3721 3722 The command has two arguments: the first argument is the name of the 3723 metadata attribute, and the second argument is the 3724 value for the attribute. Each argument should be enclosed in curly 3725 brackets, as shown in this example: 3726 3727 \code 3728 / *! 3729 \class QWidget 3730 \brief The QWidget class is the base class of all user interface objects. 3731 3732 \ingroup basicwidgets 3733 3734 \meta {technology} {User Interface} 3735 \meta {platform} {macOS 10.6} 3736 \meta {platform} {MeeGo} 3737 \meta {audience} {user} 3738 \meta {audience} {programmer} 3739 \meta {audience} {designer} 3740 * / 3741 \endcode 3742 3743 When running QDoc to generate HTML, the example above will have no 3744 effect on the generated output. 3745 3746 \b {Example Metadata} 3747 3748 Another use for \\meta command is to include metadata (tags) in 3749 \l {example-command}{\\example} documentation. By default, QDoc 3750 generates example tags based on the example's \l {title-command}{\\title} 3751 and module name. These tags are displayed in Qt Creator's Welcome mode, 3752 helping users navigate the list of examples. 3753 3754 Additional tags can be created with \c {\\meta {tag} {tag1,[tag2,...]}}. 3755 For example: 3756 \badcode 3757 / *! 3758 \example helloworld 3759 \title Hello World Example 3760 \meta {tag} {tutorial,basic} 3761 * / 3762 \endcode 3763 3764 This would result in the following tags: \e {tutorial,basic,hello,world}. 3765 Common words such as \e example are ignored. 3766 3767 \b {Example Install Paths} 3768 3769 The \\meta command combined with an argument \c installpath specifies the 3770 location of an installed example. This value overrides the one that is set 3771 using the \c examplesinstallpath configuration variable. 3772 3773 \badcode 3774 / *! 3775 \example helloworld 3776 \title Hello World Example 3777 \meta {installpath} {tutorials} 3778 * / 3779 \endcode 3780 3781 See also \l {examplesinstallpath}. 3782 3783 \target noautolist-command 3784 \section1 \\noautolist 3785 3786 The \\noautolist command indicates that the annotated list of C++ 3787 classes or QML types, which is automatically generated at the 3788 bottom of the C++ or QML module page should be omitted, because 3789 the classes or types have been listed manually. This command can 3790 also be used with the \l {group-command}{\\group} command to omit 3791 the list of group members, when they are listed manually. 3792 3793 The command must stand on its own line. See \l {Qt Sensors QML Types} for 3794 an example. The page is generated from \c {qtsensors5.qdoc}. There you will 3795 find a QDoc comment containing the \c{\qmlmodule} command for the QtSensors 3796 module. The same QDoc comment contains two \c {\annotated-list} commands to 3797 list the QML types in two separate groups. The QML types have been divided 3798 into these two groups because it makes more sense to list them this way than 3799 it does to list them in a single alphabetical list. At the bottom of the 3800 comment, \c {\noautolist} has been used to tell QDoc not to generate the 3801 automatic annotated list. 3802 3803 This command was introduced in QDoc 5.6. 3804 3805 Since Qt 5.10, this command can be applied also to \l{example-command} 3806 {\\example} documentation, where it causes the automatically generated 3807 list of files and images belonging to an example project to be omitted. 3808 3809 \target omit-command 3810 \section1 \\omit 3811 3812 The \\omit command and the corresponding \\endomit command 3813 delimit parts of the documentation that you want QDoc to skip. For 3814 example: 3815 3816 \code 3817 / *! 3818 \table 3819 \row 3820 \li Basic Widgets 3821 \li Basic GUI widgets such as buttons, comboboxes 3822 and scrollbars. 3823 3824 \omit 3825 \row 3826 \li Component Model 3827 \li Interfaces and helper classes for the Qt 3828 Component Model. 3829 \endomit 3830 3831 \row 3832 \li Database Classes 3833 \li Database related classes, e.g. for SQL databases. 3834 \endtable 3835 * / 3836 \endcode 3837 3838 QDoc renders this as: 3839 3840 \raw HTML 3841 <table align="center" cellpadding="2" 3842 cellspacing="1" border="0"> 3843 3844 <tr valign="top" bgcolor="#d0d0d0"> 3845 <td>Basic Widgets</td> 3846 <td>Basic GUI widgets such as buttons, comboboxes 3847 and scrollbars.</td> 3848 </tr> 3849 3850 <tr valign="top" bgcolor="#c0c0c0"> 3851 <td>Database Classes</td> 3852 <td>Database related classes, e.g. for SQL databases.</td> 3853 </tr> 3854 </table> 3855 \endraw 3856 3857 \target raw-command 3858 \section1 \\raw (avoid) 3859 3860 The \\raw command and the corresponding 3861 \\endraw command delimit a block of raw mark-up language code. 3862 3863 \note Avoid using this command if possible. If you are trying to generate 3864 special table or list behavior, try to get the behavior you want 3865 using the \l {span-command} {\\span} and \l {div-command} {\\div} 3866 commands in your \l {table-command} {\\table} or \l {list-command} 3867 {\\list}. 3868 3869 The command takes an argument specifying the code's format. 3870 Currently, the only supported format is HTML. 3871 3872 The \\raw command is useful if you want some special HTML effects 3873 in your documentation. 3874 3875 \code 3876 / *! 3877 Qt has some predefined QColor objects. 3878 3879 \raw HTML 3880 <style type="text/css" id="colorstyles"> 3881 #color-blue { background-color: #0000ff; color: #ffffff } 3882 #color-darkBlue { background-color: #000080; color: #ffffff } 3883 #color-cyan { background-color: #00ffff; color: #000000 } 3884 </style> 3885 3886 <p> 3887 <tt id="color-blue">Blue(#0000ff)</tt>, 3888 <tt id="color-darkBlue">dark blue(#000080)</tt> and 3889 <tt id="color-cyan">cyan(#00ffff)</tt>. 3890 </p> 3891 \endraw 3892 * / 3893 \endcode 3894 3895 QDoc renders this as: 3896 3897 \quotation 3898 Qt has some predefined QColor objects. 3899 3900 \raw HTML 3901 <style type="text/css" id="colorstyles"> 3902 #color-blue { background-color: #0000ff; color: #ffffff } 3903 #color-darkBlue { background-color: #000080; color: #ffffff } 3904 #color-cyan { background-color: #00ffff; color: #000000 } 3905 </style> 3906 3907 <p> 3908 <tt id="color-blue">Blue(#0000ff)</tt>, 3909 <tt id="color-darkBlue">dark blue(#000080)</tt> and 3910 <tt id="color-cyan">cyan(#00ffff)</tt>. 3911 </p> 3912 \endraw 3913 \endquotation 3914 3915 \note But you can achieve the exact same thing using QDoc 3916 commands. In this case, all you have to do is include the color 3917 styles in your style.css file. Then you can write: 3918 3919 \code 3920 \tt {\span {id="color-blue"} {Blue(#0000ff)}}, 3921 \tt {\span {id="color-darkBlue"} {dark blue(#000080)}} and 3922 \tt {\span {id="color-cyan"} {cyan(#00ffff)}}. 3923 \endcode 3924 3925 ...which is rendered as: 3926 3927 \tt {\span {id="color-blue"} {Blue(#0000ff)}}, 3928 \tt {\span {id="color-darkBlue"} {dark blue(#000080)}} and 3929 \tt {\span {id="color-cyan"} {cyan(#00ffff)}}. 3930 3931 \target unicode-command 3932 \section1 \\unicode 3933 3934 The \\unicode command allows you to insert an arbitrary Unicode 3935 character in the document. 3936 3937 The command takes an argument specifying the character as an 3938 integer. By default, base 10 is assumed, unless a '0x' or '0' 3939 prefix is specified (for base 16 and 8, respectively). For 3940 example: 3941 3942 \code 3943 O G\unicode{0xEA}nio e as Rosas 3944 3945 \unicode 0xC0 table en famille avec 15 \unicode 0x20AC par jour 3946 3947 \unicode 0x3A3 \e{a}\sub{\e{i}} 3948 \endcode 3949 3950 QDoc renders this as: 3951 3952 \quotation 3953 O G\unicode{0xEA}nio e as Rosas 3954 3955 \unicode 0xC0 table en famille avec 15 \unicode 0x20AC par jour 3956 3957 \unicode 0x3A3 \e{a}\sub{\e{i}} 3958 \endquotation 3959*/ 3960 3961