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