1/**************************************************************************** 2** 3** Copyright (C) 2016 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 13-qdoc-commands-topics.html 30 \previouspage Command Index 31 \nextpage Context Commands 32 33 \title Topic Commands 34 35 A topic command tells QDoc which source code element is being 36 documented. Some topic commands allow you to create documentation 37 pages that aren't tied to any underlying source code element. 38 39 When QDoc processes a QDoc comment, it tries to connect the 40 comment to an element in the source code by first looking for a 41 topic command that names the source code element. If there is no 42 topic command, QDoc tries to connect the comment to the source 43 code element that immediately follows the comment. If it can't do 44 either of these and if there is no topic command that indicates 45 the comment does not have an underlying source code element (e.g. 46 \l{page-command} {\\page}), then the comment is discarded. 47 48 \target topic argument 49 50 The name of the entity being documented is usually the only 51 argument for a topic command. Use the complete name. Sometimes 52 there can be a second parameter in the argument. See e.g. \l 53 {page-command} {\\page}. 54 55 \code 56 \enum QComboBox::InsertPolicy 57 \endcode 58 59 The \l {fn-command} {\\fn} command is a special case. For the \l 60 {fn-command} {\\fn} command, use the function's signature 61 including the class qualifier. 62 63 \code 64 \fn void QGraphicsWidget::setWindowFlags(Qt::WindowFlags wFlags) 65 \endcode 66 67 A topic command can appear anywhere in a comment but must stand 68 alone on its own line. It is good practice is to let the topic command 69 be the first line of the comment. If the argument spans several 70 lines, make sure that each line (except the last one) is ended 71 with a backslash. Moreover, QDoc counts parentheses, which means 72 that if it encounters a '(' it considers everything until the 73 closing ')' as its argument. 74 75 If a topic command is repeated with different arguments, the 76 same documentation will appear for both the units. 77 78 \code 79 / *! 80 \fn void PreviewWindow::setWindowFlags() 81 \fn void ControllerWindow::setWindowFlags() 82 83 Sets the widgets flags using the QWidget::setWindowFlags() 84 function. 85 86 Then runs through the available window flags, creating a text 87 that contains the names of the flags that matches the flags 88 parameter, displaying the text in the widgets text editor. 89 * / 90 \endcode 91 92 The \c PreviewWindow::setWindowFlags() and \c 93 ControllerWindow::setWindowFlags() functions will get the same 94 documentation. 95 96 \target class-command 97 \section1 \\class 98 99 The \\class command is for documenting a C++ class. The argument 100 is the complete name of the class. The command tells QDoc that a 101 class is part of the public API, and lets you enter a detailed 102 description. 103 104 \code 105 / *! 106 \class QMap::iterator 107 108 \brief The QMap::iterator class provides an STL-style 109 non-const iterator for QMap and QMultiMap. 110 111 QMap features both \l{STL-style iterators} and 112 \l{Java-style iterators}. The STL-style iterators ... 113 * / 114 \endcode 115 116 The HTML documentation for the named class is written to a 117 \c{.html} file named from the class name, in lower case, and with 118 the double colon qualifier(s) replaced with '-'. For example, the 119 documentation for the \c QMap::Iterator class is written to \c 120 qmap-iterator.html. 121 122 \target framework 123 124 The file contains the class description from the \\class comment, 125 plus the documentation generated from QDoc comments for all the 126 class members: a list of the class's types, properties, 127 functions, signals, and slots. 128 129 In addition to the detailed description of the class, the \\class 130 comment typically contains a \l {brief-command} {\\brief} command 131 and one or more \l{Markup Commands}. See the \\class command for 132 any of the Qt class for examples. Here is a very simple example: 133 134 \code 135 / *! 136 \class PreviewWindow 137 \brief The PreviewWindow class is a custom widget. 138 displaying the names of its currently set 139 window flags in a read-only text editor. 140 141 \ingroup miscellaneous 142 143 The PreviewWindow class inherits QWidget. The widget 144 displays the names of its window flags set with the \l 145 {function} {setWindowFlags()} function. It is also 146 provided with a QPushButton that closes the window. 147 148 ... 149 150 \sa QWidget 151 * / 152 \endcode 153 154 The way QDoc renders this \\class will depend a lot on your \c 155 {style.css} file, but the general outline of the class reference 156 page will look like this: 157 158 \quotation 159 \raw HTML 160 <h1>PreviewWindow Class Reference</h1> 161 \endraw 162 163 The PreviewWindow class is a custom widget displaying 164 the names of its currently set window flags in a 165 read-only text editor. \l {preview window} {More...} 166 167 \raw HTML 168 <h3>Properties</h3> 169 \endraw 170 171 \list 172 \li 52 properties inherited from QWidget 173 \li 1 property inherited from QObject 174 \endlist 175 176 \raw HTML 177 <h3>Public Functions</h3> 178 \endraw 179 180 \list 181 \li \l {constructor} {PreviewWindow}(QWidget *parent = 0) 182 \li void \l {function} {setWindowFlags}(Qt::WindowFlags flags) 183 \endlist 184 185 \list 186 \li 183 public functions inherited from QWidget 187 \li 28 public functions inherited from QObject 188 \endlist 189 190 \raw HTML 191 <h3>Public Slots</h3> 192 \endraw 193 194 \list 195 \li 17 public slots inherited from QWidget 196 \li 1 public slot inherited from QObject 197 \endlist 198 199 \raw HTML 200 <h3>Additional Inherited Members</h3> 201 \endraw 202 203 \list 204 \li 1 signal inherited from QWidget 205 \li 1 signal inherited from QObject 206 \li 4 static public members inherited from QWidget 207 \li 4 static public members inherited from QObject 208 \li 39 protected functions inherited from QWidget 209 \li 7 protected functions inherited from QObject 210 \endlist 211 212 \target preview window 213 214 \raw HTML 215 <hr /> 216 <h2>Detailed Description</h2> 217 \endraw 218 219 The PreviewWindow class is a custom widget displaying 220 the names of its currently set window flags in a 221 read-only text editor. 222 223 The PreviewWindow class inherits QWidget. The widget 224 displays the names of its window flags set with the \l 225 {function} {setWindowFlags()} function. It is also 226 provided with a QPushButton that closes the window. 227 228 ... 229 230 See also QWidget. 231 232 \raw HTML 233 <hr /> 234 <h2>Member Function Documentation</h2> 235 \endraw 236 237 \target constructor 238 \raw HTML 239 <h3>PreviewWindow(QWidget *parent = 0)</h3> 240 \endraw 241 242 Constructs a preview window widget with \e parent. 243 244 \target function 245 \raw HTML 246 <h3>setWindowFlags(Qt::WindowFlags flags)</h3> 247 \endraw 248 249 Sets the widgets flags using the 250 QWidget::setWindowFlags() function. 251 252 Then runs through the available window flags, 253 creating a text that contains the names of the flags 254 that matches the flags parameter, displaying 255 the text in the widgets text editor. 256 \endquotation 257 258 \target enum-command 259 \section1 \\enum 260 261 The \\enum command is for documenting a C++ enum type. The 262 argument is the full name of the enum type. 263 264 The enum values are documented in the \\enum comment using the \l 265 {value-command} {\\value} command. If an enum value is not 266 documented with \\value, QDoc emits a warning. These warnings can 267 be avoided using the \l {omitvalue-command} {\\omitvalue} command 268 to tell QDoc that an enum value should not be documented. The enum 269 documentation will be included on the class reference page, header 270 file page, or namespace page where the enum type is defined. For 271 example, consider the enum type \c {Corner} in the Qt namespace: 272 273 \code 274 enum Corner { 275 TopLeftCorner = 0x00000, 276 TopRightCorner = 0x00001, 277 BottomLeftCorner = 0x00002, 278 BottomRightCorner = 0x00003 279 #if defined(QT3_SUPPORT) && !defined(Q_MOC_RUN) 280 ,TopLeft = TopLeftCorner, 281 TopRight = TopRightCorner, 282 BottomLeft = BottomLeftCorner, 283 BottomRight = BottomRightCorner 284 #endif 285 }; 286 \endcode 287 288 This enum can be cocumented this way: 289 290 \code 291 / *! 292 \enum Qt::Corner 293 294 This enum type specifies a corner in a rectangle: 295 296 \value TopLeftCorner 297 The top-left corner of the rectangle. 298 \value TopRightCorner 299 The top-right corner of the rectangle. 300 \value BottomLeftCorner 301 The bottom-left corner of the rectangle. 302 \value BottomRightCorner 303 The bottom-right corner of the rectangle. 304 305 \omitvalue TopLeft 306 \omitvalue TopRight 307 \omitvalue BottomLeft 308 \omitvalue BottomRight 309 * / 310 \endcode 311 312 Note the inclusion of the namespace qualifier. QDoc will render 313 this enum type in \c {qt.html} like this: 314 315 \quotation 316 \raw HTML 317 <h3 class="fn"><a name="Corner-enum"></a>enum Qt::Corner</h3> 318 319 <p>This enum type specifies a corner in a rectangle:</p> 320 321 <table border="1" cellpadding="2" cellspacing="1" width="100%"> 322 <tr> 323 <th width="25%">Constant</th> 324 <th width="15%">Value</th> 325 <th width="60%">Description</th> 326 </tr> 327 328 <tr> 329 <td valign="top"><tt>Qt::TopLeftCorner</tt></td> 330 <td align="center" valign="top"><tt>0x00000</tt></td> 331 <td valign="top">The top-left corner of the rectangle.</td> 332 </tr> 333 334 <tr> 335 <td valign="top"><tt>Qt::TopRightCorner</tt></td> 336 <td align="center" valign="top"><tt>0x00001</tt></td> 337 <td valign="top">The top-right corner of the rectangle.</td> 338 </tr> 339 340 <tr> 341 <td valign="top"><tt>Qt::BottomLeftCorner</tt></td> 342 <td align="center" valign="top"><tt>0x00002</tt></td> 343 <td valign="top">The bottom-left corner of the rectangle.</td> 344 </tr> 345 346 <tr> 347 <td valign="top"><tt>Qt::BottomRightCorner</tt></td> 348 <td align="center" valign="top"><tt>0x00003</tt></td> 349 <td valign="top">The bottom-right corner of the rectangle.</td> 350 </tr> 351 352 </table> 353 \endraw 354 \endquotation 355 356 See also \l {value-command} {\\value} and \l {omitvalue-command} {\\omitvalue}. 357 358 \target example-command 359 \section1 \\example 360 361 The \\example command is for documenting an example. The argument 362 is the example's path relative to one of the paths listed in the 363 \l {exampledirs-variable} {exampledirs} variable in the QDoc 364 configuration file. 365 366 The documentation page will be output to \c {modulename-path-to-example}.html. 367 QDoc will add a list of all the example's source and images files at the end 368 of the page, unless \l {noautolist-command}{\\noautolist} command is used or 369 the configuration variable \l {url.examples-variable}{url.examples} is defined 370 for the project. 371 372 For example, if \l {exampledirs-variable} {exampledirs} contains 373 \c $QTDIR/examples/widgets/imageviewer, then 374 375 \code 376 / *! 377 \example widgets/imageviewer 378 \title ImageViewer Example 379 \subtitle 380 381 The example shows how to combine QLabel and QScrollArea 382 to display an image. 383 384 ... 385 * / 386 \endcode 387 388 QDoc renders this example in widgets-imageviewer.html: 389 390 \quotation 391 \raw HTML 392 <center><h1>Image Viewer Example</h1></center> 393 \endraw 394 395 The example shows how to combine QLabel and QScrollArea 396 to display an image. 397 398 Files: 399 \list 400 \li \l{http://doc.qt.io/qt-5/qtwidgets-widgets-imageviewer-imageviewer-cpp.html} 401 {widgets/imageviewer/imageviewer.cpp} 402 \li \l{http://doc.qt.io/qt-5/qtwidgets-widgets-imageviewer-imageviewer-h.html} 403 {widgets/imageviewer/imageviewer.h} 404 \li \l{http://doc.qt.io/qt-5/qtwidgets-widgets-imageviewer-main-cpp.html} 405 {widgets/imageviewer/main.cpp} 406 \endlist 407 408 409 ... 410 \endquotation 411 412 \b {See also:} \l {generatelist-command}{\\generatelist examplefiles}, 413 \l {noautolist-command}{\\noautolist}, 414 \l {url.examples-variable}{url.examples}, 415 \l {meta-command}{\\meta} 416 417 \target externalpage-command 418 \section1 \\externalpage 419 420 The \\externalpage command assigns a title to an external URL. 421 422 \code 423 / *! 424 \externalpage http://doc.qt.io/ 425 \title Qt Documentation Site 426 * / 427 \endcode 428 429 This allows you to include a link to the external page in your 430 documentation this way: 431 432 \code 433 / *! 434 At the \l {Qt Documentation Site} you can find the latest 435 documentation for Qt, Qt Creator, the Qt SDK and much more. 436 * / 437 \endcode 438 439 QDoc renders this as: 440 441 \quotation 442 At the \l {http://doc.qt.io/}{Qt Documentation Site} 443 you can find the latest documentation for Qt, Qt Creator, the Qt SDK 444 and much more. 445 \endquotation 446 447 To achieve the same result without using the \\externalpage 448 command, you would have to hard-code the address into your 449 documentation: 450 451 \code 452 / *! 453 At the \l {http://doc.qt.io/}{Qt Documentation Site} 454 you can find the latest documentation for Qt, Qt Creator, the Qt SDK 455 and much more. 456 * / 457 \endcode 458 459 The \\externalpage command makes it easier to maintain the 460 documentation. If the address changes, you only need to change the 461 argument of the \\externalpage command. 462 463 \target fn-command 464 \section1 \\fn (function) 465 466 The \\fn command is for documenting a function. The argument is 467 the function's signature, including its return type, const-ness, 468 and list of formal arguments with types. If the named function 469 doesn't exist, QDoc emits a warning. 470 471 \note The \\fn command is QDoc's default command: when no 472 topic command can be found in a QDoc comment, QDoc tries to tie 473 the documentation to the following code as if it is the 474 documentation for a function. Hence, it is normally not necessary 475 to include this command when documenting a function, if the 476 function's QDoc comment is written immediately above the function 477 implementation in the \c .cpp file. But it must be present when 478 documenting an inline function in the \c .cpp file that is 479 implemented in the \c .h file. 480 481 \code 482 / *! 483 \fn bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const 484 485 Returns \c true if this toolbar is dockable in the given 486 \a area; otherwise returns \c false. 487 * / 488 \endcode 489 490 QDoc renders this as: 491 492 \quotation 493 \raw HTML 494 <h3>bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const 495 </h3> 496 \endraw 497 498 Returns \c true if this toolbar is dockable in the given 499 \a area; otherwise returns \c false. 500 \endquotation 501 502 See also \l {overload-command} {\\overload}. 503 504 \target group-command 505 \section1 \\group 506 507 The \\group command creates a separate page that lists the classes 508 belonging to the group. The argument is the group name. 509 510 A class is included in a group by using the \l {ingroup-command} 511 {\\ingroup} command. Overview pages can also be related to a group 512 using the same command, but the list of overview pages must be 513 requested explicitly using the \l {generatelist-command} 514 {\\generatelist} command (see example below). 515 516 The \\group command is typically followed by a \l {title-command} 517 {\\title} command and a short introduction to the group. The 518 HTML page for the group is written to a \c {.html} file put in 519 <lower-case>\e{group}.html. 520 521 Each class name is listed as a link to the class reference page 522 followed by the text from the class's \l {brief-command} {\\brief} 523 texts. 524 525 \code 526 / *! 527 \group io 528 529 \title Input/Output and Networking 530 531 These classes are used to handle input and output to 532 and from external devices, processes, files etc., as 533 well as manipulating files and directories. 534 * / 535 \endcode 536 537 QDoc generates a group page in \c{io.html} that will look 538 like this: 539 540 \quotation 541 \raw HTML 542 543 <h1>Input/Output and Networking</h1> 544 545 <p>These classes are used to handle input and output 546 to and from external devices, processes, files etc., as 547 well as manipulating files and directories.</p> 548 549 <p> 550 <table width="100%"> 551 <tr valign="top" bgcolor="#e0e0e0"> 552 <td><b> 553 <a href="http://doc.qt.io/qt-5/qabstractsocket.html">QAbstractSocket</a> 554 </b></td> 555 <td> 556 The base functionality common to all socket types 557 </td></tr> 558 559 <tr valign="top" bgcolor="#e0e0e0"> 560 <td><b> 561 <a href="http://doc.qt.io/qt-5/qbuffer.html">QBuffer</a> 562 </b></td> 563 <td> 564 QIODevice interface for a QByteArray 565 </td></tr> 566 567 <tr valign="top" bgcolor="#e0e0e0"> 568 <td><b> 569 <a href="http://doc.qt.io/qt-5/qclipboard.html">QClipboard</a> 570 </b></td> 571 <td> 572 Access to the window system clipboard 573 </td></tr> 574 </table> 575 \endraw 576 \endquotation 577 578 Note that overview pages related to the group, must be listed 579 explicitly using the \l {generatelist-command} {\\generatelist} 580 command with the \c related argument. 581 582 \code 583 / *! 584 \group architecture 585 586 \title Architecture 587 588 These documents describe aspects of Qt's architecture 589 and design, including overviews of core Qt features and 590 technologies. 591 592 \generatelist{related} 593 * / 594 \endcode 595 596 See also \l {ingroup-command} {\\ingroup} and \l 597 {generatelist-command} {\\generatelist}. 598 599 \target headerfile-command 600 \section1 \\headerfile 601 602 The \\headerfile command is for documenting the global functions, 603 types and macros that are declared in a header file, but not in a 604 namespace. The argument is the name of the header file. The HTML 605 page is written to a \c {.html} file constructed from the header 606 file argument. 607 608 The documentation for a function, type, or macro that is declared 609 in the header file being documented, is included in the header file 610 page using the \l {relates-command} {\\relates} command. 611 612 If the argument doesn't exist as a header file, the \\headerfile 613 command creates a documentation page for the header file anyway. 614 615 \code 616 / *! 617 \headerfile <QtAlgorithms> 618 619 \title Generic Algorithms 620 621 \brief The <QtAlgorithms> header file provides 622 generic template-based algorithms. 623 624 Qt provides a number of global template functions in \c 625 <QtAlgorithms> that work on containers and perform 626 well-know algorithms. 627 * / 628 \endcode 629 630 QDoc generates a header file page \c{qtalgorithms.html} that looks 631 like this: 632 633 \quotation 634 \raw HTML 635 <center><h1><QtAlgorithms> - 636 Generic Algorithms</h1></center> 637 <p>The <QtAlgorithms> header file provides generic 638 template-based algorithms. 639 <a href="13-qdoc-commands-topics.html#header-command">More...</a> 640 </p> 641 642 <h3>Functions</h3> 643 <ul> 644 <li>RandomAccessIterator 645 <a href="http://doc.qt.io/qt-5/qtalgorithms-obsolete.html#qBinaryFind">qBinaryFind</a></b> 646 (RandomAccessIterator begin, RandomAccessIterator end, 647 const T & value)</li> 648 <li>...</li></ul> 649 <hr /> 650 \endraw 651 652 \target header 653 654 \raw HTML 655 <h2>Detailed Description</h2> 656 <p>The <QtAlgorithms> header file provides generic 657 template-based algorithms. </p> 658 \endraw 659 660 Qt provides a number of global template functions in \c 661 <QtAlgorithms> that work on containers and perform 662 well-know algorithms. 663 664 ... 665 \endquotation 666 667 See also \l {inheaderfile-command}{\\inheaderfile}. 668 669 \target macro-command 670 \section1 \\macro 671 672 The \\macro command is for documenting a C++ macro. The argument 673 is the macro in one of three styles: function-like macros like 674 Q_ASSERT(), declaration-style macros like Q_PROPERTY(), and macros 675 without parentheses like Q_OBJECT. 676 677 The \\macro comment must contain a \l {relates-command} 678 {\\relates} command that attaches the macro comment to a class, 679 header file, or namespace. Otherwise, the documentation will be 680 lost. Here are three example macro comments followed by what they 681 might look like in \c {qtglobal.html} or \c {qobject.html}: 682 683 \code 684 / *! 685 \macro void Q_ASSERT(bool test) 686 \relates <QtGlobal> 687 688 Prints a warning message containing the source code 689 file name and line number if \a test is false. 690 691 ... 692 693 \sa Q_ASSERT_X(), qFatal(), {Debugging Techniques} 694 * / 695 \endcode 696 697 \quotation 698 \raw HTML 699 <h3>void Q_ASSERT ( bool <i>test</i> )</h3> 700 \endraw 701 702 Prints a warning message containing the source code 703 file name and line number if \a test is false. 704 705 ... 706 707 See also Q_ASSERT_X(), qFatal() and \l {Debugging Techniques}. 708 709 \endquotation 710 711 \code 712 / *! 713 \macro Q_PROPERTY(...) 714 \relates QObject 715 716 This macro declares a QObject property. The syntax is: 717 718 ... 719 720 \sa {Qt's Property System} 721 * / 722 \endcode 723 724 \quotation 725 \raw HTML 726 <h3>Q_PROPERTY ( ... )</h3> 727 \endraw 728 729 This macro declares a QObject property. The syntax is: 730 731 ... 732 733 See also \l {Qt's Property System}. 734 \endquotation 735 736 \code 737 / *! 738 \macro Q_OBJECT 739 \relates QObject 740 741 The Q_OBJECT macro must appear in the private section 742 of a class definition that declares its own signals and 743 slots, or that uses other services provided by Qt's 744 meta-object system. 745 746 ... 747 748 \sa {Meta-Object System}, {Signals and Slots}, {Qt's 749 Property System} 750 * / 751 \endcode 752 753 \quotation 754 \raw HTML 755 <h3>Q_OBJECT</h3> 756 \endraw 757 758 The Q_OBJECT macro must appear in the private section 759 of a class definition that declares its own signals and 760 slots or that uses other services provided by Qt's 761 meta-object system. 762 763 ... 764 765 See also \l {Meta-Object System}, \l {Signals & 766 Slots} and \l {Qt's Property System}. 767 \endquotation 768 769 \target module-command 770 \section1 \\module 771 772 The \\module creates a page that lists the classes belonging to 773 the module specified by the command's argument. A class included 774 in the module by including the \l {inmodule-command} {\\inmodule} 775 command in the \\class comment. 776 777 The \\module command is typically followed by a \l {title-command} 778 {\\title} and a \l {brief-command} {\\brief} command. Each class 779 is listed as a link to the class reference page followed by the 780 text from the class's \l {brief-command} {\\brief} command. For 781 example: 782 783 \code 784 / *! 785 \module QtNetwork 786 787 \title Qt Network Module 788 789 \brief Contains classes for writing TCP/IP clients and servers. 790 791 The network module provides classes to make network 792 programming easier and portable. It offers both 793 high-level classes such as QNetworkAccessManager that 794 implements application-level protocols, and 795 lower-level classes such as QTcpSocket, QTcpServer, and 796 QUdpSocket. 797 * / 798 \endcode 799 800 QDoc renders this in \c {qtnetwork.html} like this: 801 802 \quotation 803 \raw HTML 804 <h1><center>Qt Network Module</center></h1> 805 \endraw 806 807 The Qt Network module offers classes that allow you to 808 write TCP/IP clients and servers.\l {module 809 details} {More...} 810 811 \raw HTML 812 <p> 813 <table width="100%"> 814 <tr valign="top" bgcolor="#d0d0d0"> 815 <td><b> 816 <a href="https://doc.qt.io/qt-5/qabstractsocket.html">QAbstractSocket</a> 817 </b></td> 818 <td> 819 The base functionality common to all socket types 820 </td></tr> 821 822 <tr valign="top" bgcolor="#d0d0d0"> 823 <td>...</td> 824 <td>...</td> 825 </tr> 826 </table> 827 828 <p><hr /></p> 829 \endraw 830 831 \target module details 832 833 \raw HTML 834 <h2>Detailed Description</h2> 835 836 <p> 837 The Qt Network module offers classes that allow you to 838 write TCP/IP clients and servers. 839 </p> 840 841 <p> 842 The network module provides classes to make network 843 programming easier and portable. It offers both 844 high-level classes such as QNetworkAccessManager that 845 implements application-level protocols, and 846 lower-level classes such as QTcpSocket, QTcpServer, and 847 QUdpSocket. 848 </p> 849 \endraw 850 851 ... 852 853 \endquotation 854 855 The \l {noautolist-command} {\\noautolist} command can be used here 856 to omit the automatically generated list of classes at the end. 857 858 See also \l {inmodule-command} {\\inmodule} 859 860 \target namespace-command 861 \section1 \\namespace 862 863 The \\namespace command is for documenting the contents of the C++ 864 namespace named as its argument. The reference page QDoc generates 865 for a namespace is similar to the reference page it generates for a 866 C++ class. 867 868 \code 869 / *! 870 \namespace Qt 871 872 \brief Contains miscellaneous identifiers used throughout the Qt library. 873 * / 874 \endcode 875 876 QDoc renders this in \c{qt.html} like this: 877 878 \quotation 879 \raw HTML 880 <center><h1>Qt Namespace</h1></center> 881 <p>The Qt namespace contains miscellaneous 882 identifiers used throughout the Qt library. 883 <a href="13-qdoc-commands-topics.html#name">More...</a> 884 </p> 885 886 <pre>#include <Qt></pre> 887 <ul> 888 <li> 889 <a href="https://doc.qt.io/qt-5/qt-obsolete.html"> 890 Obsolete members</a></li> 891 </ul> 892 893 894 <h3>Types</h3> 895 <ul> 896 <li>flags 897 <a href="https://doc.qt.io/qt-5/qt.html#AlignmentFlag-enum">Alignment</a></b></li> 898 <li>...</li></ul> 899 <hr /> 900 \endraw 901 902 \target name 903 904 \raw HTML 905 <h2>Detailed Description</h2> 906 <p>Contains miscellaneous identifiers 907 used throughout the Qt library.</p> 908 \endraw 909 910 ... 911 \endquotation 912 913 Note that in C++, a particular namespace can be used in more 914 than one module, but when C++ elements from different modules 915 are declared in the same namespace, the namespace itself must 916 be documented in one module only. For example, namespace Qt in 917 the example above contains types and functions from both QtCore 918 and QtGui, but it is documented with the \\namespace command 919 only in QtCore. 920 921 \target page-command 922 \section1 \\page 923 924 The \\page command is for creating a stand-alone documentation 925 page. The argument can consist of two parts separated by a 926 space. The first part is the name of the file where QDoc should 927 store the page. The second part, if present, is a word that 928 specifies the page type. Currently, the second part can be one of 929 the following list of words: 930 931 \list 932 933 \li api - This is the type of page used for C++ class references and 934 QML type references. You should never use this one for the pages 935 you write, because this one is reserved for QDoc. 936 937 \li attribution - A page describing (code) attributions. 938 939 \li example - A page that describes a working example. 940 941 \li faq - A frequently asked question. 942 943 \li howto - A user guide on how to use some components of the 944 software. 945 946 \li overview - For text pages that provide an overview of some 947 important subject. 948 949 \li tutorial - For text pages that are part of a tutorial. 950 951 \endlist 952 953 The page title is set using the \l {title-command} {\\title} 954 command. 955 956 \code 957 / *! 958 \page aboutqt.html 959 960 \title About Qt 961 962 Qt is a C++ toolkit for cross-platform GUI 963 application development. Qt provides single-source 964 portability across Microsoft Windows, macOS, Linux, 965 and all major commercial Unix variants. 966 967 Qt provides application developers with all the 968 functionality needed to build applications with 969 state-of-the-art graphical user interfaces. Qt is fully 970 object-oriented, easily extensible, and allows true 971 component programming. 972 973 ... 974 * / 975 \endcode 976 977 QDoc renders this page in \c {aboutqt.html}. 978 979 \target property-command 980 \section1 \\property 981 982 The \\property command is for documenting a Qt property. The 983 argument is the full property name. 984 985 A property is defined using the Q_PROPERTY() macro. The macro 986 takes as arguments the property's name and its set, reset and get 987 functions. 988 989 \code 990 Q_PROPERTY(QString state READ state WRITE setState) 991 \endcode 992 993 The set, reset and get functions don't need to be documented, 994 documenting the property is sufficient. QDoc will generate a list 995 of the access function that will appear in the property 996 documentation which in turn will be located in the documentation 997 of the class that defines the property. 998 999 The \\property command comment typically includes a \l 1000 {brief-command} {\\brief} command. For properties the \l 1001 {brief-command} {\\brief} command's argument is a sentence 1002 fragment that will be included in a one line description of the 1003 property. The command follows the same rules for the \l 1004 {brief-property} {description} as the \l {variable-command} 1005 {\\variable} command. 1006 1007 \code 1008 / *! 1009 \property QPushButton::flat 1010 \brief Whether the border is disabled. 1011 1012 This property's default is false. 1013 * / 1014 \endcode 1015 1016 QDoc includes this in \c {qpushbutton.html} like this: 1017 1018 \quotation 1019 \raw HTML 1020 <h3>flat : bool</h3> 1021 \endraw 1022 1023 This property holds whether the border is disabled. 1024 1025 This property's default is false. 1026 1027 Access functions: 1028 1029 \list 1030 \li \b { bool isFlat () const} 1031 \li \b { void setFlat ( bool )} 1032 \endlist 1033 1034 \endquotation 1035 1036 \code 1037 / *! 1038 \property QWidget::width 1039 \brief The width of the widget excluding any window frame. 1040 1041 See the \l {Window Geometry} documentation for an 1042 overview of window geometry. 1043 1044 \sa geometry, height, size 1045 * / 1046 \endcode 1047 1048 QDoc includes this in \c {qwidget.html} like this: 1049 1050 \quotation 1051 \raw HTML 1052 <h3>width : const int</h3> 1053 \endraw 1054 1055 This property holds the width of the widget excluding 1056 any window frame. 1057 1058 See the \l {Window Geometry} documentation for an 1059 overview of window geometry. 1060 1061 Access functions: 1062 1063 \list 1064 \li \b { int width () const} 1065 \endlist 1066 1067 See also \l{QWidget::geometry} {geometry}, 1068 \l{QWidget::height} {height}, and \l{QWidget::size} {size}. 1069 \endquotation 1070 1071 \target qmlattachedproperty-command 1072 \section1 \\qmlattachedproperty 1073 1074 The \\qmlattachedproperty command is for documenting a QML 1075 property that will be attached to some QML type. See 1076 \l{http://doc.qt.io/qt-5/qtqml-syntax-objectattributes.html#attached-properties-and-attached-signal-handlers} 1077 {Attached Properties}. The argument is the rest of the line. The 1078 argument text should be the property type, followed by the QML 1079 element name where the property is being declared, the \c{::} 1080 qualifier, and finally the property name. If we have a QML 1081 attached property named \c isCurrentItem in QML \c ListView, 1082 and the property has type \c {bool}, the \\qmlattachedproperty for 1083 it would look like this: 1084 1085 \code 1086 / *! 1087 \qmlattachedproperty bool ListView::isCurrentItem 1088 This attached property is \c true if this delegate is the current 1089 item; otherwise false. 1090 1091 It is attached to each instance of the delegate. 1092 1093 This property may be used to adjust the appearance of the current 1094 item, for example: 1095 1096 \snippet doc/src/snippets/declarative/listview/listview.qml isCurrentItem 1097 * / 1098 \endcode 1099 1100 QDoc includes this attached property on the QML reference page for the 1101 \l{http://doc.qt.io/qt-5/qml-qtquick-listview.html#isCurrentItem-attached-prop} 1102 {ListView} element. 1103 1104 \target qmlattachedsignal-command 1105 \section1 \\qmlattachedsignal 1106 1107 The \\qmlattachedsignal command is for documenting an attachable 1108 \l{Signal and Handler Event System}{signal}. The \\qmlattachedsignal 1109 command is used just like the \l{qmlsignal-command} {\\qmlsignal} command. 1110 1111 The argument is the rest of the line. It should be the name of the 1112 QML type where the signal is declared, the \c{::} 1113 qualifier, and finally the signal name. For example, a QML 1114 attached signal named \c add() in the \c GridView 1115 element is documented like this: 1116 1117 \code 1118 / *! 1119 \qmlattachedsignal GridView::add() 1120 This attached signal is emitted immediately after an item is added to the view. 1121 * / 1122 \endcode 1123 1124 QDoc includes this documentation on the QML reference page for the 1125 \l GridView element. 1126 1127 \target qmlbasictype-command 1128 \section1 \\qmlbasictype 1129 1130 The \\qmlbasictype command is for documenting a basic type for QML. 1131 The argument is the type name. The type must be included in the 1132 QML basic types group using the \l{ingroup-command}{\\ingroup} 1133 command as shown below. This will cause QDoc to include the 1134 documentation for the type on the 1135 \l{http://doc.qt.io/qt-5/qtqml-typesystem-basictypes.html} 1136 {QML Basic Types} page. The \l{brief-command} {\\brief} command 1137 is also required, because it appears on the 1138 \l{http://doc.qt.io/qt-5/qtqml-typesystem-basictypes.html} 1139 {QML Basic Types} page as well. 1140 1141 \code 1142 / *! 1143 \qmlbasictype int 1144 \ingroup qmlbasictypes 1145 1146 \brief An integer is a whole number, for example 0, 10, or -20. 1147 1148 An integer is a whole number, e.g. 0, 10, or -20. The possible 1149 \c int values range from around -2000000000 to around 1150 2000000000, although most elements will only accept a reduced 1151 range (which they mention in their documentation). 1152 1153 Example: 1154 \qml 1155 Item { width: 100; height: 200 } 1156 \endqml 1157 1158 \sa {QML Basic Types} 1159 * / 1160 \endcode 1161 1162 QDoc outputs this as \l{http://doc.qt.io/qt-5/qml-int.html} 1163 {qml-int.html}. 1164 1165 \target qmlclass-command 1166 \section1 \\qmlclass 1167 1168 This command is deprecated. Use \l{qmltype-command} {\\qmltype} 1169 instead. 1170 1171 The \\qmlclass command is for documenting a QML type that is 1172 instantiated by a C++ class. The command has two arguments. The 1173 first argument is the name of the QML type. The second argument 1174 is the name of the C++ class that instantiates the QML type. 1175 1176 \code 1177 / *! 1178 \qmlclass Transform QGraphicsTransform 1179 \ingroup qml-transform-elements 1180 \since 4.7 1181 \brief Provides a way of building advanced transformations on Items. 1182 1183 The Transform element is a base type which cannot be 1184 instantiated directly. The following concrete Transform types 1185 are available: 1186 1187 \list 1188 \li \l Rotation 1189 \li \l Scale 1190 \li \l Translate 1191 \endlist 1192 1193 The Transform elements let you create and control advanced 1194 transformations that can be configured independently using 1195 specialized properties. 1196 1197 You can assign any number of Transform elements to an \l 1198 Item. Each Transform is applied in order, one at a time. 1199 1200 * / 1201 \endcode 1202 1203 This example generates the 1204 \l {https://doc.qt.io/qt-5/qml-qtquick-transform.html} {QML Transform} 1205 page. The \\qmlclass comment should include the \l 1206 {since-command} {\\since} command, because all QML types are 1207 new. It should also include the \l{brief-command} {\\brief} 1208 command. If a type is a member of a group of QML 1209 types, it should also include one or more \l{ingroup-command} 1210 {\\ingroup} commands. 1211 1212 \target qmlmethod-command 1213 \section1 \\qmlmethod 1214 1215 The \\qmlmethod command is for documenting a QML method. The 1216 argument is the complete method signature, including return 1217 type and parameter names and types. 1218 1219 \code 1220 / *! 1221 \qmlmethod void TextInput::select(int start, int end) 1222 1223 Causes the text from \a start to \a end to be selected. 1224 1225 If either start or end is out of range, the selection is not changed. 1226 1227 After having called this, selectionStart will become the lesser, and 1228 selectionEnd the greater (regardless of the order passed to this method). 1229 1230 \sa selectionStart, selectionEnd 1231 * / 1232 \endcode 1233 1234 QDoc includes this documentation on the element reference page for the 1235 \l{http://doc.qt.io/qt-5/qml-qtquick-textinput.html#select-method} 1236 {TextInput} element. 1237 1238 \target qmltype-command 1239 \section1 \\qmltype 1240 1241 The \\qmltype command is for documenting a QML type. The command 1242 has one argument, which is the name of the QML type. 1243 1244 If the QML type is instantiated by a C++ class, that class must be 1245 specified using the \l{instantiates-command} {\\instantiates} 1246 context command. 1247 1248 \code 1249 / *! 1250 \qmltype Transform 1251 \instantiates QGraphicsTransform 1252 \ingroup qml-transform-elements 1253 \since 4.7 1254 \brief The Transform elements provide a way to build 1255 advanced transformations on Items. 1256 1257 The Transform element is a base type which cannot be 1258 instantiated directly. The concrete Transform types are: 1259 1260 \list 1261 \li \l Rotation 1262 \li \l Scale 1263 \li \l Translate 1264 \endlist 1265 1266 The Transform elements let you create and control advanced 1267 transformations that can be configured independently using 1268 specialized properties. 1269 1270 You can assign any number of Transform elements to an \l 1271 Item. Each Transform is applied in order, one at a time. 1272 1273 * / 1274 \endcode 1275 1276 The example generates the \l 1277 {https://doc.qt.io/qt-5/qml-qtquick-transform.html} {QML Transform} 1278 page. The \e{\\qmltype} comment includes \l{instantiates-command} 1279 {\\instantiates} to specify that a Transform is instantiated by 1280 the C++ class QGraphicsTransform. A \\qmltype comment should 1281 always include a \l {since-command} {\\since} command, because all 1282 QML types are new. It should also include a \l{brief-command} 1283 {\\brief} description. If a QML type is a member of a QML type group, 1284 the \\qmltype comment should include one or more \l{ingroup-command} 1285 {\\ingroup} commands. 1286 1287 1288 \target qmlproperty-command 1289 \section1 \\qmlproperty 1290 1291 The \\qmlproperty command is for documenting a QML property. The 1292 argument is the rest of the line. The argument text should be the 1293 property type, followed by the QML type name, the \c{::} 1294 qualifier, and finally the property name. If we have a QML 1295 property named \c x in QML type \c Translate, and the property 1296 has type \c {real}, the \\qmlproperty for it would look like this: 1297 1298 \code 1299 / *! 1300 \qmlproperty real Translate::x 1301 1302 The translation along the X axis. 1303 * / 1304 \endcode 1305 1306 QDoc includes this QML property on the QML reference page for the 1307 \l {http://doc.qt.io/qt-5/qml-qtquick-translate.html} {Translate} 1308 element. 1309 1310 If the QML property is of enumeration type, or it holds a bit-wise 1311 combination of flags, the \l{value-command}{\\value} command can 1312 be used to document the acceptable values. 1313 1314 \target qmlsignal-command 1315 \section1 \\qmlsignal 1316 1317 The \\qmlsignal command is for documenting a QML signal. 1318 The argument is the rest of the line. The arguments should be: the QML type 1319 where the signal is declared, the \c{::} qualifier, and finally the signal 1320 name. If we have a QML signal named \c clicked(), the documentation for it 1321 would look like this: 1322 1323 \code 1324 / *! 1325 \qmlsignal QtQuick::MouseArea::clicked(MouseEvent mouse) 1326 This signal is emitted when there is a click. A click is defined as a 1327 press followed by a release, both inside the MouseArea. 1328 * / 1329 \endcode 1330 1331 QDoc includes this documentation on the QML reference page for the 1332 \l{http://doc.qt.io/qt-5/qml-qtquick-mousearea.html#clicked-signal} 1333 {MouseArea} element. 1334 1335 \target qmlmodule-command 1336 \section1 \\qmlmodule 1337 1338 Insert the \c{\\qmlmodule} command to create a \c QML module page. A QML 1339 module is a collection of QML types or any related material. This 1340 command is similar to the \l{group-command}. 1341 1342 A QML class may belong to a module by inserting the 1343 \l{inqmlmodule-command}{\\inqmlmodule} command as a topic command. 1344 Every member of a group must be linked to using the module name and two 1345 colons (\c{::}). 1346 1347 \code 1348 \beginqdoc 1349 A link to the TabWidget of the UI Component is \l {UIComponent::TabWidget}. 1350 \endqdoc 1351 \endcode 1352 1353 QDoc will generate a page for the module with a listing of the members 1354 of the module. 1355 1356 \code 1357 \qmlmodule ClickableComponents 1358 1359 This is a list of the Clickable Components set. A Clickable component 1360 responds to a \c clicked() event. 1361 \endcode 1362 1363 \target inqmlmodule-command 1364 \section1 \\inqmlmodule 1365 1366 A QML class may belong to a \l{qmlmodule-command}{QML module} by inserting 1367 the \l{inqmlmodule-command}{\\inqmlmodule} command as a topic command, with 1368 the module name (without a version number) as the only argument. Every 1369 member of a group must be linked to using the module name and two colons 1370 (\c{::}). 1371 1372 \code 1373 \qmltype ClickableButton 1374 \inqmlmodule ClickableComponents 1375 1376 A clickable button that responds to the \c click() event. 1377 \endcode 1378 1379 To link to the \c ClickableButton, use the 1380 \c{\l ClickableComponents::ClickableButton} format. 1381 1382 The \l {noautolist-command} {\\noautolist} command can be used here 1383 to omit the automatically generated list of types at the end. 1384 1385 \target instantiates-command 1386 \section1 \\instantiates 1387 1388 The \\instantiates command is used in the \l{qmltype-command} {QML 1389 type} comment of an elemental QML type to specify the name of the 1390 C++ class that instantiates the QML type. 1391 1392 If the QML type is not instantiated by a C++ class, this command 1393 is not used. 1394 1395 \code 1396 / *! 1397 \qmltype Transform 1398 \instantiates QGraphicsTransform 1399 \ingroup qml-transform-elements 1400 \since 4.7 1401 \brief Provides elements provide a way to build 1402 advanced transformations on Items. 1403 1404 The Transform element is a base type which cannot be 1405 instantiated directly. 1406 * / 1407 \endcode 1408 1409 The example generates the \l 1410 {https://doc.qt.io/qt-5/qml-qtquick-transform.html} {QML Transform} 1411 page. The \e{\\qmltype} comment includes \l{instantiates-command} 1412 {\\instantiates} to specify that a Transform is instantiated by 1413 the C++ class QGraphicsTransform. A \\qmltype comment should 1414 1415 \target typealias-command 1416 \section1 \\typealias 1417 1418 The \\typealias command is similar to \l {typedef-command}{\\typedef}, 1419 but specific to documenting a C++ type alias: 1420 1421 \code 1422 class Foo 1423 { 1424 public: 1425 using ptr = void*; 1426 // ... 1427 } 1428 \endcode 1429 1430 This can be documented as 1431 1432 \badcode * 1433 /\1! 1434 \typealias Foo::ptr 1435 \1/ 1436 \endcode 1437 1438 QDoc will automatically generate a sentence in the documentation describing 1439 the alias: 1440 1441 \quotation 1442 This is a type alias for \c {void*}. 1443 \endquotation 1444 1445 The \\typealias command was introduced in QDoc 5.15. 1446 1447 See also \l {typedef-command}{\\typedef}. 1448 1449 \target typedef-command 1450 \section1 \\typedef 1451 1452 The \\typedef command is for documenting a C++ typedef. The 1453 argument is the name of the typedef. The documentation for 1454 the typedef will be included in the reference documentation 1455 for the class, namespace, or header file in which the typedef 1456 is declared. To relate the \\typedef to a class, namespace, or 1457 header file, the \\typedef comment must contain a 1458 \l {relates-command} {\\relates} command. 1459 1460 \code 1461 / *! 1462 \typedef QObjectList 1463 \relates QObject 1464 1465 Synonym for QList<QObject>. 1466 * / 1467 \endcode 1468 1469 QDoc includes this in \c {qobject.html} as: 1470 1471 \quotation 1472 \raw HTML 1473 <h3>typedef QObjectList</h3> 1474 \endraw 1475 1476 Synonym for QList<QObject>. 1477 \endquotation 1478 1479 Another, although more rare, example: 1480 1481 \code 1482 / *! 1483 \typedef QMsgHandler 1484 \relates QtGlobal 1485 1486 This is a typedef for a pointer to a function with the 1487 following signature: 1488 1489 \code 1490 void myMsgHandler(QtMsgType, const char *); 1491 \ endcode 1492 1493 \sa QtMsgType, qInstallMessageHandler() 1494 * / 1495 \endcode 1496 1497 QDoc includes this in \c {qtglobal.html} as: 1498 1499 \quotation 1500 \raw HTML 1501 <h3>typedef QtMsgHandler</h3> 1502 \endraw 1503 1504 This is a typedef for a pointer to a function with the 1505 following signature: 1506 1507 \raw HTML 1508 <tt> 1509 <pre> void myMsgHandler(QtMsgType, const char *);</pre> 1510 </tt> 1511 \endraw 1512 1513 See also QtMsgType and qInstallMessageHandler(). 1514 \endquotation 1515 1516 Other typedefs are located on the reference page for the class 1517 that defines them. 1518 1519 \code 1520 / *! 1521 \typedef QLinkedList::Iterator 1522 1523 Qt-style synonym for QList::iterator. 1524 * / 1525 \endcode 1526 1527 QDoc includes this one on the reference page for class QLinkedList as: 1528 1529 \quotation 1530 \raw HTML 1531 <h3>typedef QLinkedList::Iterator</h3> 1532 \endraw 1533 1534 Qt-style synonym for QList::iterator. 1535 \endquotation 1536 1537 See also \l {typealias-command}{\\typealias}. 1538 1539 \target variable-command 1540 \section1 \\variable 1541 1542 The \\variable command is for documenting a class member variable 1543 or a constant. The argument is the variable or constant name. The 1544 \\variable command comment includes a \l {brief-command} {\\brief} 1545 command. QDoc generates the documentation based on the text from 1546 \\brief command. 1547 1548 The documentation will be located in the in the associated class, 1549 header file, or namespace documentation. 1550 1551 In case of a member variable: 1552 1553 \code 1554 / *! 1555 \variable QStyleOption::palette 1556 \brief The palette that should be used when painting 1557 the control 1558 * / 1559 \endcode 1560 1561 QDoc includes this in qstyleoption.html as: 1562 1563 \quotation 1564 \raw HTML 1565 <h3> 1566 <a href="http://doc.qt.io/qt-5/qpalette.html"> 1567 QPalette 1568 </a> 1569 QStyleOption::palette 1570 </h3> 1571 \endraw 1572 1573 This variable holds the palette that should be used 1574 when painting the control. 1575 \endquotation 1576 1577 You can also document constants with the \\variable command. For 1578 example, suppose you have the \c Type and \c UserType constants in 1579 the QTreeWidgetItem class: 1580 1581 \code 1582 enum { Type = 0, UserType = 1000 }; 1583 \endcode 1584 1585 For these, the \\variable command can be used this way: 1586 1587 \code 1588 / *! 1589 \variable QTreeWidgetItem::Type 1590 1591 The default type for tree widget items. 1592 1593 \sa UserType, type() 1594 * / 1595 \endcode 1596 \code 1597 / *! 1598 \variable QTreeWidgetItem::UserType 1599 1600 The minimum value for custom types. Values below 1601 UserType are reserved by Qt. 1602 1603 \sa Type, type() 1604 * / 1605 \endcode 1606 1607 QDoc includes these in qtreewidget.html as: 1608 1609 \quotation 1610 \raw HTML 1611 <h3> 1612 const int QTreeWidgetItem::Type 1613 </h3> 1614 \endraw 1615 1616 The default type for tree widget items. 1617 1618 See also \l {QTreeWidgetItem::UserType} {UserType} and \l 1619 {QTreeWidgetItem::type()} {type()}. 1620 1621 \raw HTML 1622 <h3> 1623 const int QTreeWidgetItem::UserType 1624 </h3> 1625 \endraw 1626 1627 The minimum value for custom types. Values below 1628 UserType are reserved by Qt. 1629 1630 See also \l {QTreeWidgetItem::Type} {Type} and 1631 \l{QTreeWidgetItem::type()} {type()}. 1632 1633 \endquotation 1634*/ 1635