Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
qdoc-manual-topiccmds.qdoc
Go to the documentation of this file.
1
// Copyright (C) 2016 The Qt Company Ltd.
2
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4
/*!
5
\page 13-qdoc-commands-topics.html
6
\previouspage Command Index
7
\nextpage Context Commands
8
9
\title Topic Commands
10
11
A topic command tells QDoc which source code element is being
12
documented. Some topic commands allow you to create documentation
13
pages that aren't tied to any underlying source code element.
14
15
When QDoc processes a QDoc comment, it tries to connect the
16
comment to an element in the source code by first looking for a
17
topic command that names the source code element. If there is no
18
topic command, QDoc tries to connect the comment to the source
19
code element that immediately follows the comment. If it can't do
20
either of these and if there is no topic command that indicates
21
the comment does not have an underlying source code element (e.g.
22
\l{page-command} {\\page}), then the comment is discarded.
23
24
\target topic argument
25
26
The name of the entity being documented is usually the only
27
argument for a topic command. Use the complete name. Sometimes
28
there can be a second parameter in the argument. See e.g. \l
29
{page-command} {\\page}.
30
31
\code
32
\enum QComboBox::InsertPolicy
33
\endcode
34
35
The \l {fn-command} {\\fn} command is a special case. For the \l
36
{fn-command} {\\fn} command, use the function's signature
37
including the class qualifier.
38
39
\code
40
\fn void QGraphicsWidget::setWindowFlags(Qt::WindowFlags wFlags)
41
\endcode
42
43
A topic command can appear anywhere in a comment but must stand
44
alone on its own line. It is good practice is to let the topic command
45
be the first line of the comment. If the argument spans several
46
lines, make sure that each line (except the last one) is ended
47
with a backslash. Moreover, QDoc counts parentheses, which means
48
that if it encounters a '(' it considers everything until the
49
closing ')' as its argument.
50
51
If a topic command is repeated with different arguments, the
52
same documentation will appear for both the units.
53
54
\badcode *
55
/\1!
56
\fn void PreviewWindow::setWindowFlags()
57
\fn void ControllerWindow::setWindowFlags()
58
59
Sets the widgets flags using the QWidget::setWindowFlags()
60
function.
61
62
Then runs through the available window flags, creating a text
63
that contains the names of the flags that matches the flags
64
parameter, displaying the text in the widgets text editor.
65
\1/
66
\endcode
67
68
The \c PreviewWindow::setWindowFlags() and \c
69
ControllerWindow::setWindowFlags() functions will get the same
70
documentation.
71
72
\section2 Nomenclature for files generated by topic commands
73
74
For many topic commands, such as \l {page-command}{\\page}, QDoc
75
generates a file when processing the documentation.
76
77
QDoc normalizes the name of each file before writing it to disk.
78
The following operations are performed:
79
80
\list
81
\li All sequences of non alphanumeric characters are replaced with a hyphen, '-'.
82
\li All uppercase letters are replaced with their lowercase equivalent.
83
\li All trailing hyphens are removed.
84
\endlist
85
86
For example, the following command generates a file named
87
\c{this-generates-a-file-and-writes-it-to-disk.html}:
88
89
\badcode
90
\page this_generates_a_file_(and_writes_it_to_DISK)-.html
91
\endcode
92
93
As the example shows, the name that is given to the file in the
94
command might differ from the name of the actual file that is
95
written to disk.
96
97
\section3 Prefixes and Suffixes for generated files
98
99
When QDoc generates a file, it may add a prefix, a suffix, or both,
100
depending on the element that the file will document.
101
102
The table below shows what those prefixes and suffixes are for
103
various elements.
104
105
\table
106
\header
107
\li Element
108
\li Prefix
109
\li Suffix
110
\li Command
111
\row
112
\li QML Modules
113
\li None
114
\li "-qmlmodule"
115
\li \l {qmlmodule-command}{\\qmlmodule}
116
\row
117
\li Modules
118
\li None
119
\li "-module"
120
\li \l {module-command}{\\module}
121
\row
122
\li Examples
123
\li The project name, as given by the \l
124
{project-variable}{project configuration variable},
125
followed by a hyphen.
126
\li "-example"
127
\li \l {example-command}{\\example}
128
\row
129
\li QML Types
130
\li The output prefix for QML, as given by the \l
131
{outputprefixes-variable}{outputprefixes configuration
132
variable}.
133
134
If the module that contains this type is known to QDoc,
135
the module name is added as a prefix, followed by the QML
136
output suffix, as defined by the \l
137
{outputsuffixes-variable}{outputsuffixes configuration
138
variable} and a hyphen.
139
\li None
140
\li \l {qmltype-command}{\\qmltype}
141
\endtable
142
143
\target class-command
144
\section1 \\class
145
146
The \\class command is for documenting a C++ \e class, a C/C++
147
\e struct, or a \e union. The argument is the complete, qualified
148
name of the class. The command tells QDoc that a class is part of
149
the public API, and lets you enter a detailed description.
150
151
\badcode *
152
/\1!
153
\class QMap::iterator
154
\inmodule QtCore
155
156
\brief The QMap::iterator class provides an STL-style
157
non-const iterator for QMap and QMultiMap.
158
159
QMap features both \l{STL-style iterators} and
160
\l{Java-style iterators}. The STL-style iterators ...
161
\1/
162
\endcode
163
164
The HTML documentation for the named class is written to a
165
\c{.html} file named from the class name, in lower case, and with
166
the double colon qualifiers replaced with '-'. For example, the
167
documentation for the \c QMap::iterator class is written to \c
168
qmap-iterator.html.
169
170
The file contains the class description from the \\class comment,
171
plus the documentation generated from QDoc comments for all the
172
class members: a list of the class's types, properties,
173
functions, signals, and slots.
174
175
In addition to the detailed description of the class, the \\class
176
comment typically contains an \l {inmodule-command} {\\inmodule}
177
command, as well as a \l {brief-command} {\\brief} description.
178
Here is a very simple example:
179
180
\badcode *
181
/\1!
182
\class PreviewWindow
183
\inmodule CustomWidgets
184
\brief The PreviewWindow class is a custom widget.
185
displaying the names of its currently set
186
window flags in a read-only text editor.
187
188
\ingroup miscellaneous
189
190
The PreviewWindow class inherits QWidget. The widget
191
displays the names of its window flags set with the \l
192
{function} {setWindowFlags()} function. It is also
193
provided with a QPushButton that closes the window.
194
195
...
196
197
\sa QWidget
198
\1/
199
\endcode
200
201
The way QDoc renders this \\class depends on your \c {style.css}
202
file.
203
204
\target enum-command
205
\section1 \\enum
206
207
The \\enum command is for documenting a C++ enum type. The
208
argument is the full name of the enum type.
209
210
The enum values are documented in the \\enum comment using the \l
211
{value-command} {\\value} command. If an enum value is not
212
documented with \\value, QDoc emits a warning. These warnings can
213
be avoided using the \l {omitvalue-command} {\\omitvalue} command
214
to tell QDoc that an enum value should not be documented. The enum
215
documentation will be included on the class reference page, header
216
file page, or namespace page where the enum type is defined. For
217
example, consider the enum type \c {Corner} in the Qt namespace:
218
219
\code
220
enum Corner {
221
TopLeftCorner = 0x00000,
222
TopRightCorner = 0x00001,
223
BottomLeftCorner = 0x00002,
224
BottomRightCorner = 0x00003
225
#if defined(QT3_SUPPORT) && !defined(Q_MOC_RUN)
226
,TopLeft = TopLeftCorner,
227
TopRight = TopRightCorner,
228
BottomLeft = BottomLeftCorner,
229
BottomRight = BottomRightCorner
230
#endif
231
};
232
\endcode
233
234
This enum can be cocumented this way:
235
236
\badcode *
237
/\1!
238
\enum Qt::Corner
239
240
This enum type specifies a corner in a rectangle:
241
242
\value TopLeftCorner
243
The top-left corner of the rectangle.
244
\value TopRightCorner
245
The top-right corner of the rectangle.
246
\value BottomLeftCorner
247
The bottom-left corner of the rectangle.
248
\value BottomRightCorner
249
The bottom-right corner of the rectangle.
250
251
\omitvalue TopLeft
252
\omitvalue TopRight
253
\omitvalue BottomLeft
254
\omitvalue BottomRight
255
Bottom-right (omitted; not documented).
256
\1/
257
\endcode
258
259
Note the inclusion of the namespace qualifier.
260
261
See also \l {value-command} {\\value} and \l {omitvalue-command} {\\omitvalue}.
262
263
\target example-command
264
\section1 \\example
265
266
The \\example command is for documenting an example. The argument
267
is the example's path relative to one of the paths listed in the
268
\l {exampledirs-variable} {exampledirs} variable in the QDoc
269
configuration file.
270
271
The documentation page will be output to \c {modulename-path-to-example}.html.
272
QDoc will add a list of all the example's source and images files at the end
273
of the page, unless \l {noautolist-command}{\\noautolist} command is used or
274
the configuration variable \l {url.examples-variable}{url.examples} is defined
275
for the project.
276
277
For example, if \l {exampledirs-variable} {exampledirs} contains
278
\c $QTDIR/examples/widgets/imageviewer, then
279
280
\badcode *
281
/\1!
282
\example widgets/imageviewer
283
\title ImageViewer Example
284
\subtitle
285
286
The example shows how to combine QLabel and QScrollArea
287
to display an image.
288
289
...
290
\1/
291
\endcode
292
293
\b {See also:} \l {noautolist-command}{\\noautolist},
294
\l {url.examples-variable}{url.examples},
295
\l {meta-command}{\\meta}
296
297
\target externalpage-command
298
\section1 \\externalpage
299
300
The \\externalpage command assigns a title to an external URL.
301
302
\badcode *
303
/\1!
304
\externalpage http://doc.qt.io/
305
\title Qt Documentation Site
306
\1/
307
\endcode
308
309
This allows you to include a link to the external page in your
310
documentation this way:
311
312
\badcode *
313
/\1!
314
At the \l {Qt Documentation Site} you can find the latest
315
documentation for Qt, Qt Creator, the Qt SDK and much more.
316
\1/
317
\endcode
318
319
To achieve the same result without using the \\externalpage
320
command, you would have to hard-code the address into your
321
documentation:
322
323
\badcode *
324
/\1!
325
At the \l {http://doc.qt.io/}{Qt Documentation Site}
326
you can find the latest documentation for Qt, Qt Creator, the Qt SDK
327
and much more.
328
\1/
329
\endcode
330
331
The \\externalpage command makes it easier to maintain the
332
documentation. If the address changes, you only need to change the
333
argument of the \\externalpage command.
334
335
\target fn-command
336
\section1 \\fn (function)
337
338
The \\fn command is for documenting a function. The argument is
339
the function's signature, including its template parameters (if
340
any), return type, const-ness, and list of formal arguments with
341
types. If the named function doesn't exist, QDoc emits a warning.
342
343
The command accepts \c auto as the type of a function, even though
344
the full type can be deduced by QDoc. In certain situations, it may
345
be preferable to use \e auto instead of the actual type of a
346
function. Using \c auto as the return type in the
347
\\fn-command lets the author to do this explicitly, also for types
348
that are defined without the \e auto keyword.
349
350
Since QDoc version 6.0, the \\fn command can be used for documenting
351
class members that are not explicitly declared in the header,
352
but are implicitly generated by the compiler; default constructor
353
and destructor, copy constructor and move-copy constructor,
354
assignment operator, and move-assignment operator.
355
356
When documenting an hidden friend, it is required to prepend the
357
enclosing class name to the function name.
358
For example, for:
359
360
\code
361
class Foo {
362
...
363
friend bool operator==(const Foo&, const Foo&) { ... }
364
...
365
}
366
\endcode
367
368
The command should be written as \c{"\fn Foo::operator==(const
369
Foo&, const Foo&)"} and not as the free function \c{"\fn
370
operator==(const Foo&, const Foo&)"}.
371
372
Failure to do so will have QDoc complaining about being unable to
373
resolve the function.
374
375
\note The \\fn command is QDoc's default command: when no
376
topic command can be found in a QDoc comment, QDoc tries to tie
377
the documentation to the following code as if it is the
378
documentation for a function. Hence, it is normally not necessary
379
to include this command when documenting a function, if the
380
function's QDoc comment is written immediately above the function
381
implementation in the \c .cpp file. But it must be present when
382
documenting an inline function in the \c .cpp file that is
383
implemented in the \c .h file.
384
385
\badcode *
386
/\1!
387
\fn bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const
388
389
Returns \c true if this toolbar is dockable in the given
390
\a area; otherwise returns \c false.
391
\1/
392
\endcode
393
394
\note Running in debug mode (pass the \c {-debug} command line option
395
or set the \c QDOC_DEBUG environment variable before invoking QDoc)
396
can help troubleshoot \\fn commands that QDoc fails to parse. In
397
debug mode, additional diagnostic information is available.
398
399
See also \l {overload-command} {\\overload}.
400
401
\target group-command
402
\section1 \\group
403
404
The \\group command creates a separate page that lists the classes,
405
pages, or other entities belonging to a named group. The argument
406
is the group name.
407
408
A class is included in a group by using the \l {ingroup-command}
409
{\\ingroup} command. Overview pages can also be related to a group
410
using the same command, but the list of overview pages must be
411
requested explicitly using the \l {generatelist-command}
412
{\\generatelist} command (see example below).
413
414
The \\group command is typically followed by a \l {title-command}
415
{\\title} command and a short introduction to the group. The
416
HTML page for the group is written to an \c {.html} file named
417
<lower-case-group-name>.html.
418
419
Each entity in the group is listed as a link (using page title
420
or class name), followed by a decription from the \l {brief-command}
421
{\\brief} command in the entity's documentation.
422
423
\badcode *
424
/\1!
425
\group io
426
\title Input/Output and Networking
427
\1/
428
\endcode
429
430
QDoc generates a group page \c{io.html}.
431
432
Note that overview pages related to the group must be listed
433
explicitly using the \l {generatelist-command} {\\generatelist}
434
command with the \c related argument.
435
436
\badcode *
437
/\1!
438
\group architecture
439
440
\title Architecture
441
442
These documents describe aspects of Qt's architecture
443
and design, including overviews of core Qt features and
444
technologies.
445
446
\generatelist{related}
447
\1/
448
\endcode
449
450
See also \l {ingroup-command} {\\ingroup}, \l {annotatedlist-command}
451
{\\annotatedlist}, \l {generatelist-command} {\\generatelist}, and
452
\l {noautolist-command}{\\noautolist}.
453
454
\target headerfile-command
455
\section1 \\headerfile
456
457
The \\headerfile command is for documenting the global functions,
458
types and macros that are declared in a header file, but not in a
459
namespace. The argument is the name of the header file. The HTML
460
page is written to a \c {.html} file constructed from the header
461
file argument.
462
463
The documentation for a function, type, or macro that is declared
464
in the header file being documented, is included in the header file
465
page using the \l {relates-command} {\\relates} command.
466
467
If the argument doesn't exist as a header file, the \\headerfile
468
command creates a documentation page for the header file anyway.
469
470
\badcode *
471
/\1!
472
\headerfile <QtAlgorithms>
473
474
\title Generic Algorithms
475
476
\brief The <QtAlgorithms> header file provides
477
generic template-based algorithms.
478
479
Qt provides a number of global template functions in \c
480
<QtAlgorithms> that work on containers and perform
481
well-know algorithms.
482
\1/
483
\endcode
484
485
QDoc generates a header file page, \c{qtalgorithms.html}.
486
487
See also \l {inheaderfile-command}{\\inheaderfile}.
488
489
\target macro-command
490
\section1 \\macro
491
492
The \\macro command is for documenting a C++ macro. The argument
493
is the macro in one of three styles: function-like macros like
494
Q_ASSERT(), declaration-style macros like Q_PROPERTY(), and macros
495
without parentheses like Q_OBJECT.
496
497
The \\macro comment must contain a \l {relates-command}
498
{\\relates} command that attaches the macro comment to a class,
499
header file, or namespace. Otherwise, the documentation will be
500
lost.
501
502
\target module-command
503
\section1 \\module
504
505
The \\module creates a page that lists the classes belonging to
506
the module specified by the command's argument. A class included
507
in the module by including the \l {inmodule-command} {\\inmodule}
508
command in the \\class comment.
509
510
The \\module command is typically followed by a \l {title-command}
511
{\\title} and a \l {brief-command} {\\brief} command. Each class
512
is listed as a link to the class reference page followed by the
513
text from the class's \l {brief-command} {\\brief} command. For
514
example:
515
516
\badcode *
517
/\1!
518
\module QtNetwork
519
520
\title Qt Network Module
521
522
\brief Contains classes for writing TCP/IP clients and servers.
523
524
The network module provides classes to make network
525
programming easier and portable. It offers both
526
high-level classes such as QNetworkAccessManager that
527
implements application-level protocols, and
528
lower-level classes such as QTcpSocket, QTcpServer, and
529
QUdpSocket.
530
\1/
531
\endcode
532
533
The \l {noautolist-command} {\\noautolist} command can be used here
534
to omit the automatically generated list of classes at the end.
535
536
See also \l {inmodule-command} {\\inmodule}
537
538
\target namespace-command
539
\section1 \\namespace
540
541
The \\namespace command is for documenting the contents of the C++
542
namespace named as its argument. The reference page QDoc generates
543
for a namespace is similar to the reference page it generates for a
544
C++ class.
545
546
\badcode *
547
/\1!
548
\namespace Qt
549
550
\brief Contains miscellaneous identifiers used throughout the Qt library.
551
\1/
552
\endcode
553
554
Note that in C++, a particular namespace can be used in more
555
than one module, but when C++ elements from different modules
556
are declared in the same namespace, the namespace itself must
557
be documented in one module only. For example, namespace Qt in
558
the example above contains types and functions from both QtCore
559
and QtGui, but it is documented with the \\namespace command
560
only in QtCore.
561
562
\target page-command
563
\section1 \\page
564
565
The \\page command is for creating a stand-alone documentation
566
page.
567
568
The \\page command expects a single argument that represents the
569
name of the file where QDoc should store the page.
570
571
The page title is set using the \l {title-command} {\\title}
572
command.
573
574
\badcode *
575
/\1!
576
\page aboutqt.html
577
578
\title About Qt
579
580
Qt is a C++ toolkit for cross-platform GUI
581
application development. Qt provides single-source
582
portability across Microsoft Windows, macOS, Linux,
583
and all major commercial Unix variants.
584
585
Qt provides application developers with all the
586
functionality needed to build applications with
587
state-of-the-art graphical user interfaces. Qt is fully
588
object-oriented, easily extensible, and allows true
589
component programming.
590
591
...
592
\1/
593
\endcode
594
595
QDoc renders this page in \c {aboutqt.html}.
596
597
\target property-command
598
\section1 \\property
599
600
The \\property command is for documenting a Qt property. The
601
argument is the full property name.
602
603
A property is defined using the Q_PROPERTY() macro. The macro
604
takes as arguments the property's name and its set, reset and get
605
functions.
606
607
\badcode
608
Q_PROPERTY(QString state READ state WRITE setState)
609
\endcode
610
611
The set, reset and get functions don't need to be documented,
612
documenting the property is sufficient. QDoc will generate a list
613
of the access function that will appear in the property
614
documentation which in turn will be located in the documentation
615
of the class that defines the property.
616
617
The \\property command comment typically includes a \l
618
{brief-command} {\\brief} command. For properties the \l
619
{brief-command} {\\brief} command's argument is a sentence
620
fragment that will be included in a one line description of the
621
property. The command follows the same rules for the
622
description as the \l {variable-command} {\\variable} command.
623
624
\badcode *
625
/\1!
626
\property QPushButton::flat
627
\brief Whether the border is disabled.
628
629
This property's default is false.
630
\1/
631
\endcode
632
633
\target qmlattachedproperty-command
634
\section1 \\qmlattachedproperty
635
636
The \\qmlattachedproperty command is for documenting a QML
637
property that will be attached to some QML type. See
638
\l{Attached Properties and Attached Signal Handlers}
639
{Attached Properties}. The argument is the rest of the line.
640
It must start with the property type, followed by the QML
641
type name where the property is declared, the \c{::}
642
qualifier, and finally the property name.
643
644
For example, to document a boolean QML attached property named
645
\c isCurrentItem for the \c ListView type:
646
647
\badcode *
648
/\1!
649
\qmlattachedproperty bool ListView::isCurrentItem
650
651
This attached property is \c true if this delegate is the current
652
item; otherwise false.
653
654
It is attached to each instance of the delegate.
655
656
This property may be used to adjust the appearance of the current
657
item, for example:
658
659
\snippet doc/src/snippets/declarative/listview/listview.qml isCurrentItem
660
\1/
661
\endcode
662
663
QDoc includes this attached property on the QML reference page for the
664
\l [QML] {ListView} type.
665
666
\note Like \l{qmlproperty-command}{\\qmlproperty}, \\qmlattachedproperty
667
accepts a QML module identifier as part of its argument.
668
669
\target qmlattachedsignal-command
670
\section1 \\qmlattachedsignal
671
672
The \\qmlattachedsignal command is for documenting an attachable
673
\l{Signal and Handler Event System}{signal}. The \\qmlattachedsignal
674
command is used just like the \l{qmlsignal-command} {\\qmlsignal} command.
675
676
The argument is the rest of the line. It should be the name of the
677
QML type where the signal is declared, the \c{::}
678
qualifier, and finally the signal name. For example, a QML
679
attached signal named \c add() in the \c GridView
680
element is documented like this:
681
682
\badcode *
683
/\1!
684
\qmlattachedsignal GridView::add()
685
This attached signal is emitted immediately after an item is added to the view.
686
\1/
687
\endcode
688
689
QDoc includes this documentation on the QML reference page for the
690
\l GridView element.
691
692
\note Like \l{qmlproperty-command}{\\qmlproperty}, \\qmlattachedsignal accepts
693
a QML module identifier as part of its argument.
694
695
\target qmlvaluetype-command
696
\section1 \\qmlvaluetype
697
698
The \\qmlvaluetype command is for documenting a \l [QtQml]
699
{QML Value Types}{value type} for QML. The command takes
700
a type name as its only argument.
701
702
\\qmlvaluetype is functionally identical to the
703
\l {qmltype-command}{\\qmltype} command. The only difference
704
is that the type will be titled (and grouped) as a
705
\e {QML value type}.
706
707
\target qmlclass-command
708
\section1 \\qmlclass
709
710
This command is deprecated. Use \l{qmltype-command} {\\qmltype}
711
instead.
712
713
\target qmlmethod-command
714
\section1 \\qmlmethod
715
716
The \\qmlmethod command is for documenting a QML method. The
717
argument is the complete method signature, including return
718
type and parameter names and types.
719
720
\badcode *
721
/\1!
722
\qmlmethod void TextInput::select(int start, int end)
723
724
Causes the text from \a start to \a end to be selected.
725
726
If either start or end is out of range, the selection is not changed.
727
728
After having called this, selectionStart will become the lesser, and
729
selectionEnd the greater (regardless of the order passed to this method).
730
731
\sa selectionStart, selectionEnd
732
\1/
733
\endcode
734
735
QDoc includes this documentation on the element reference page for the
736
\l{http://doc.qt.io/qt-5/qml-qtquick-textinput.html#select-method}
737
{TextInput} element.
738
739
\target qmltype-command
740
\section1 \\qmltype
741
742
The \\qmltype command is for documenting a QML type. The command
743
has one argument, which is the name of the QML type.
744
745
If the QML type has an equivalent C++ class, you can specify that class
746
with the \qdoccmd nativetype context command.
747
748
The \l {inqmlmodule-command}{\\inqmlmodule} command documents the
749
QML module the type belongs to. The argument passed to this command
750
must match with a documented \l {qmlmodule-command}{\\qmlmodule}
751
page.
752
753
\badcode *
754
/\1!
755
\qmltype Transform
756
\nativetype QGraphicsTransform
757
\inqmlmodule QtQuick
758
759
\brief Provides a way to build advanced transformations on Items.
760
761
The Transform element is a base type which cannot be
762
instantiated directly.
763
\1/
764
\endcode
765
766
Here, the \e{\\qmltype} comment includes \qdoccmd nativetype
767
to specify that a Transform is the QML counterpart to the
768
C++ class QGraphicsTransform. A \\qmltype comment should
769
always include a \l {since-command} {\\since} command, because all
770
QML types are new. It should also include a \l{brief-command}
771
{\\brief} description. If a QML type is a member of a QML type group,
772
the \\qmltype comment should include one or more \l{ingroup-command}
773
{\\ingroup} commands.
774
775
\target qmlproperty-command
776
\section1 \\qmlproperty
777
778
The \\qmlproperty command is for documenting a QML property. The
779
argument is the rest of the line. The argument text should be the
780
property type, followed by the QML type name, the \c{::}
781
qualifier, and finally the property name. If we have a QML
782
property named \c x in QML type \c Translate, and the property
783
has type \c {real}, the \\qmlproperty for it would look like this:
784
785
\badcode *
786
/\1!
787
\qmlproperty real Translate::x
788
789
The translation along the X axis.
790
\1/
791
\endcode
792
793
QDoc includes this QML property on the QML reference page for the
794
\l [QML] {Translate} type.
795
796
If the QML property is of enumeration type, or it holds a bit-wise
797
combination of flags, the \l{value-command}{\\value} command can
798
be used to document the acceptable values.
799
800
QDoc accepts also a fully qualified property name, including the
801
QML module identifier:
802
803
\badcode
804
\qmlproperty bool QtQuick.Controls::Button::highlighted
805
\endcode
806
807
If specified, the module identifier (above, \c {QtQuick.Controls})
808
must match with value passed to \l {inqmlmodule-command}{\\inqmlmodule}
809
command in the associated \\qmltype documentation. If the name of
810
the QML type the property belongs to is unique across all types in
811
the documentation project, the module identifier can be omitted.
812
813
\target qmlsignal-command
814
\section1 \\qmlsignal
815
816
The \\qmlsignal command is for documenting a QML signal.
817
The argument is the rest of the line. The arguments should be: the QML type
818
where the signal is declared, the \c{::} qualifier, and finally the signal
819
name. If we have a QML signal named \c clicked(), the documentation for it
820
would look like this:
821
822
\badcode *
823
/\1!
824
\qmlsignal MouseArea::clicked(MouseEvent mouse)
825
826
This signal is emitted when there is a click. A click is defined as a
827
press followed by a release, both inside the MouseArea.
828
\1/
829
\endcode
830
831
QDoc includes this documentation on the QML reference page for the
832
\l [QML] {MouseArea} type.
833
834
\note Like \l{qmlproperty-command}{\\qmlproperty}, \\qmlsignal
835
accepts a QML module identifier as part of its argument.
836
837
\target qmlmodule-command
838
\section1 \\qmlmodule
839
840
Use the \c{\qmlmodule} command to create a \c QML module page. A QML
841
module page is a collection of QML types or any related material. The
842
command takes an optional \c <VERSION> number argument, and is similar
843
to the \l{group-command}.
844
845
A QML type is associated with a module by adding the
846
\l{inqmlmodule-command}{\\inqmlmodule} command to the comment-block that
847
documents the type. You can link to any member of a QML module using the
848
module name and two colons (\c{::}) prefix.
849
850
\badcode *
851
/\1!
852
A link to the TabWidget of the UI Component is \l {UIComponent::TabWidget}.
853
\1/
854
\endcode
855
856
QDoc generates a page for the module that lists all the members of the
857
module.
858
859
\badcode *
860
/\1!
861
\qmlmodule ClickableComponents
862
863
This is a list of the Clickable Components set. A Clickable component
864
responds to a \c clicked() event.
865
\1/
866
\endcode
867
868
\target inqmlmodule-command
869
\section1 \\inqmlmodule
870
871
A QML type is marked as being available under a specific QML module
872
import by inserting the \\inqmlmodule command in a
873
\l {qmltype-command}{\\qmltype} topic. The command takes the module
874
(import) name, without a version number, as the only argument.
875
876
The QML module name must match with a QML module documented with
877
the (\l{qmlmodule-command}{\\qmlmodule} command).
878
879
\badcode *
880
/\1!
881
\qmltype ClickableButton
882
\inqmlmodule ClickableComponents
883
884
A clickable button that responds to the \c click() event.
885
\1/
886
\endcode
887
888
QDoc outputs a row \e {Import statement: import <qmlmodule>}
889
in a table at the top of the QML type reference page.
890
891
When linking to QML types, the QML module identifier may appear in
892
the link target. For example:
893
894
\badcode
895
\l {ClickableComponents::}{ClickableButton}
896
\endcode
897
898
Links to the type reference page, with \e ClickableButton as the
899
link text.
900
901
\target instantiates-command
902
\section1 \\instantiates
903
904
The \\instantiates command is deprecated since Qt 6.8.
905
Use \qdoccmd nativetype instead.
906
907
908
\target nativetype-command
909
\section1 \\nativetype
910
911
The \\nativetype-command must be used in conjunction with the
912
\qdoccmd qmltype topic command. The command takes a C++ class as its
913
argument. If QDoc cannot find the C++ class, it issues a warning. This
914
command was introduced with Qt 6.8.
915
916
Use the \\nativetype-command to specify what the type is called in C++.
917
This ensures that the requisites block generated in the documentation for
918
the QML type contains an "In C++" entry. The C++ class will have a
919
corresponding "In QML" entry.
920
921
Any one QML type can only have one native type. QDoc issues a warning if
922
redefinition occurs. However, multiple QML types can have the same C++
923
class as their native type. The C++ class documentation will contain a list
924
of all corresponding types in QML.
925
926
\badcode *
927
/\1!
928
\qmltype Transform
929
\nativetype QGraphicsTransform
930
\inqmlmodule QtQuick
931
932
\brief Provides a way to build advanced transformations on Items.
933
934
The Transform element is a base type which cannot be
935
instantiated directly.
936
\1/
937
\endcode
938
939
Here, the \e{\\qmltype} topic includes \e{\\nativetype} to specify that a
940
Transform is called QGraphicsTransform in C++.
941
942
943
\target typealias-command
944
\section1 \\typealias
945
946
The \\typealias command is similar to \l {typedef-command}{\\typedef},
947
but specific to documenting a C++ type alias:
948
949
\code
950
class Foo
951
{
952
public:
953
using ptr = void*;
954
// ...
955
}
956
\endcode
957
958
This can be documented as
959
960
\badcode *
961
/\1!
962
\typealias Foo::ptr
963
\1/
964
\endcode
965
966
The \\typealias command was introduced in QDoc 5.15.
967
968
See also \l {typedef-command}{\\typedef}.
969
970
\target typedef-command
971
\section1 \\typedef
972
973
The \\typedef command is for documenting a C++ typedef. The
974
argument is the name of the typedef. The documentation for
975
the typedef will be included in the reference documentation
976
for the class, namespace, or header file in which the typedef
977
is declared. To relate the \\typedef to a class, namespace, or
978
header file, the \\typedef comment must contain a
979
\l {relates-command} {\\relates} command.
980
981
\badcode *
982
/\1!
983
\typedef QObjectList
984
\relates QObject
985
986
Synonym for QList<QObject>.
987
\1/
988
\endcode
989
990
Other typedefs are located on the reference page for the class
991
that defines them.
992
993
\badcode *
994
/\1!
995
\typedef QList::Iterator
996
997
Qt-style synonym for QList::iterator.
998
\1/
999
\endcode
1000
1001
See also \l {typealias-command}{\\typealias}.
1002
1003
\target variable-command
1004
\section1 \\variable
1005
1006
The \\variable command is for documenting a class member variable
1007
or a constant. The argument is the variable or constant name. The
1008
\\variable command comment includes a \l {brief-command} {\\brief}
1009
command. QDoc generates the documentation based on the text from
1010
\\brief command.
1011
1012
The documentation will be located in the in the associated class,
1013
header file, or namespace documentation.
1014
1015
In case of a member variable:
1016
1017
\badcode *
1018
/\1!
1019
\variable QStyleOption::palette
1020
\brief The palette that should be used when painting
1021
the control
1022
\1/
1023
\endcode
1024
1025
You can also document constants with the \\variable command. For
1026
example, suppose you have the \c Type and \c UserType constants in
1027
the QTreeWidgetItem class:
1028
1029
\code
1030
enum { Type = 0, UserType = 1000 };
1031
\endcode
1032
1033
For these, the \\variable command can be used this way:
1034
1035
\badcode *
1036
/\1!
1037
\variable QTreeWidgetItem::Type
1038
1039
The default type for tree widget items.
1040
1041
\sa UserType, type()
1042
\1/
1043
\endcode
1044
1045
\badcode *
1046
/\1!
1047
\variable QTreeWidgetItem::UserType
1048
1049
The minimum value for custom types. Values below
1050
UserType are reserved by Qt.
1051
1052
\sa Type, type()
1053
\1/
1054
\endcode
1055
1056
*/
qttools
src
qdoc
qdoc
doc
qdoc-manual-topiccmds.qdoc
Generated on Sat Sep 21 2024 01:06:19 for Qt by
1.12.0