外部コードのインクルード
以下のコマンドを使用すると、外部ファイルのコード・スニペットをインクルードできます。QDocにファイルの全内容をインクルードさせることもできますし、ファイルの特定の部分を引用して他をスキップすることもできます。後者の典型的な使い方は、ファイルを塊ごとに引用することです。
注意: これらのコマンドはすべて C++ コードのレンダリングに使用できますが、他のコマンドよりも ˶´﹀`˵ コマンドと˶´﹀`˵コマンドをお勧めします。これらのコマンドを使用すると、他のQt言語バインディング用の同等のコード・スニペットを、ドキュメンテーションのC++スニペットに置き換えることができます。
\quoteファイル
quotefileコマンドは、引数として与えられたファイルの完全な内容まで展開します。
コマンドは行の残りを引数の一部と見なすので、ファイル名の後に改行を入れるようにしてください。
ファイルの内容は、等幅フォントと標準的なインデントを使用して、独立した段落で表示される。コードはそのまま表示される。
/*! This is a simple "Hello world" example: \quotefile examples/main.cpp It contains only the bare minimum you need to get a Qt application up and running. */
を参照してください。
\を参照してください。
quotefromfileコマンドは、引数として与えられたファイルを引用のために開きます。
コマンドは行の残りを引数の一部と見なしますので、ファイル名の後に改行を入れるようにしてください。
このコマンドはwalkthroughコマンドでファイルの一部を引用するときに使用することを意図しています:\printline、printto、printuntil、skipline、skipto、skipuntil。これにより、ファイルの特定の部分を引用することができます。
/*! The whole application is contained within the \c main() function: \quotefromfile examples/main.cpp \skipto main \printuntil app(argc, argv) First we create a QApplication object using the \c argc and \c argv parameters. \skipto QPushButton \printuntil resize Then we create a QPushButton, and give it a reasonable size using the QWidget::resize() function. ... */
QDocは、どのファイルから引用しているかと、そのファイル内の現在の位置を記憶します(詳し くは「printline」を参照してください)。ファイルを "閉じる "必要はありません。
また、"quotefile"、"code"、"dots "も参照してください。
\printlineを参照してください。
printlineコマンドは、現在のソースファイルの現在の位置から次の空白でない行まで展開します。
ドキュメントがソース・ファイルと同期したままであることを保証するために、行の部分文字列をコマンドの引数として指定する必要があります。コマンドは行の残りの部分を引数の一部と見なすので、部分文字列の後には必ず改行を入れてください。
ソース・ファイルからの行は、等幅フォントと標準的なインデントを使用して、独立した段落として表示されます。コードはそのまま表示される。
/*! There has to be exactly one QApplication object in every GUI application that uses Qt. \quotefromfile examples/main.cpp \printline QApplication This line includes the QApplication class definition. QApplication manages various application-wide resources, such as the default font and cursor. \printline QPushButton This line includes the QPushButton class definition. The QPushButton widget provides a command button. \printline main The main function... */
QDocはファイルを順次読み込みます。現在の位置を前方に移動するには、"skip... "コマンドのいずれかを使用できます。現在の位置を後方に移動するには、再度 "quotefromfile "コマンドを使用します。
部分文字列引数がスラッシュで囲まれている場合は、regular expression として解釈されます。
/*! \quotefromfile examples/mainwindow.cpp \skipto closeEvent \printuntil /^\}/ Close events are sent to widgets that the users want to close, usually by clicking \c File|Exit or by clicking the \c X title bar button. By reimplementing the event handler, we can intercept attempts to close the application. */
/^\
}/という正規表現は、QDocに行頭の最初の'}'文字までインデントなしで印刷させます。/.../は正規表現を囲み、'^'は行頭を意味します。'}'文字は正規表現の特殊文字なのでエスケープする必要があります。
QDocは指定された部分文字列や正規表現が見つからない場合、つまりソースコードが変更された場合に警告を発します。
printtoと printuntilも参照してください。
\Printto
printtoコマンドは、現在の位置から、指定された部分文字列を含む次の行を除いたすべての行に展開します。
コマンドは残りの行を引数の一部と見なしますので、必ず部分文字列の後に改行を入れてください。このコマンドは、位置と 引数に関しても、printlineコマンドと同じ規則に従います。
ソース・ファイルからの行は、等幅フォントと標準インデントを使用して、別の段落に表示されます。コードはそのまま表示されます。
/*! The whole application is contained within the \c main() function: \quotefromfile examples/main.cpp \printto hello First we create a QApplication object using the \c argc and \c argv parameters... */
printlineと printuntilも参照してください。
\Printuntil
printuntilコマンドは、現在の位置から、指定された部分文字列を含む次の行までのすべての行に展開します。
コマンドはその行の残りを引数の一部と見なしますので、必ず部分文字列の後に改行を入れてください。このコマンドは、位置と 引数に関しても、printlineコマンドと同じ規則に従います。
引数なしで使用された場合、現在の位置から引用ファイルの終わりまでのすべての行に展開されます。
ソースファイルからの行は、等幅フォントと標準インデントを使用して、別の段落にレンダリングされます。コードはそのまま表示されます。
/*! The whole application is contained within the \c main() function: \quotefromfile examples/main.cpp \skipto main \printuntil hello First we create a QApplication object using the \c argc and \c argv parameters, then we create a QPushButton. */
printlineと printtoも参照してください。
\スキップライン
を参照してください。
Docはファイルを順次読み、(ソースファイルの1行を省略して)現在の位置を移動するために˶skiplineコマンドを使用します。上記のファイル位置に関する記述を参照。
このコマンドは行の残りを引数の一部と見なしますので、必ず部分文字列の後に改行を入れてください。また、このコマンドは、引数に関する規約は、"printline "コマンドと同じで、"quotefromfile "コマンドと一緒に使用されます。
/*! QPushButton is a GUI push button that the user can press and release. \quotefromfile examples/main.cpp \skipline QApplication \printline QPushButton This line includes the QPushButton class definition. For each class that is part of the public Qt API, there exists a header file of the same name that contains its definition. */
(printline)コマンドと引数の規約は同じで、quotefromfile(quotefromfile)コマンドと併用します。
\を参照してください。
を参照してください。"sukipto "コマンドは、現在の位置から、指定された部分文字列を含む次の行を除 くまでのすべての行を無視します。
QDocはファイルを順番に読み、(ソースファイルの1行または数行を省略して)現在の位置を移動するために、˶skiptoコマンドを使用します。上記のファイルの位置に関する記述を参照してください。
コマンドは行の残りを引数の一部と見なしますので、必ず部分文字列の後に改行を入れてください。
また、このコマンドは、引数に関する規則も、˶‾printline‾コマンドと同じで、˶‾quotefromfile‾コマンドと一緒に使用されます。
/*! The whole application is contained within the \c main() function: \quotefromfile examples/main.cpp \skipto main \printuntil } First we create a QApplication object. There has to be exactly one such object in every GUI application that uses Qt. Then we create a QPushButton, resize it to a reasonable size ... */
(注)このコマンドは、"printline"コマンドと同じ引数の規約に従っ ており、"quotefromfile "コマンドと組み合わせて使用します。
\を参照してください。
を参照してください。"sukipuntil "コマンドは、現在の位置から、指定された部分文字列を含む次の行までのすべての行を無視します。
QDocはファイルを順次読み、(ソースファイルの1行または数行を省略して)現在の位置を移動するために、˶skipuntilコマンドを使用します。上記のファイルの位置に関する記述を参照してください。
コマンドは行の残りを引数の一部と見なしますので、部分文字列の後には必ず改行を入れてください。
また、このコマンドは、引数に関する規則も、˶‾printline‾コマンドと同じで、˶‾quotefromfile‾コマンドと一緒に使用されます。
/*! The first thing we did in the \c main() function was to create a QApplication object \c app. \quotefromfile examples/main.cpp \skipuntil show \dots \printuntil } In the end we must remember to make \c main() pass the control to Qt. QCoreApplication::exec() will return when the application exits... */
( 注)このコマンドは、"printline"コマンドと同じ引数の規則に従います。
\dots
ファイルを引用するとき、ソースファイルの一部が省略されていることを示す。
このコマンドは "quotefromfile "コマンドと一緒に使用され、独立した行に記述する必要があります。ドットは改行され、等幅フォントを使用します。
/*! \quotefromfile examples/main.cpp \skipto main \printuntil { \dots \skipuntil exec \printline } */
デフォルトのインデントは4スペースですが、コマンドのオプション引数で調整できます。
/*! \dots 0 \dots \dots 8 \dots 12 \dots 16 */
を参照してください。
\スニペット
を使うと、コード・スニペットが整形済みテキストとして逐語的に含まれ、構 文がハイライトされることがあります。
各コード・スニペットは、それを保持するファイルと、そのファイルの一意な識別子によって参照されます。スニペット・ファイルは通常、ドキュメント・ディレクトリ内のsnippets
ディレクトリに保存されます(例:$QTDIR/doc/src/snippets
)。
例えば、以下のドキュメントでは、ドキュメント・ディレクトリのサブディレクトリにあるファイルのスニペットを参照しています:
\snippet snippets/textdocument-resources/main.cpp Adding a resource
ファイル名に続くテキストは、スニペットの一意識別子です。これは、上記の\snippet
コマンドに対応する次の例のように、関連するスニペット・ファイルの引用コードを区切るために使用されます:
... QImage image(64, 64, QImage::Format_RGB32); image.fill(qRgb(255, 160, 128)); //! [Adding a resource] document->addResource(QTextDocument::ImageResource, QUrl("mydata://image.png"), QVariant(image)); //! [Adding a resource] ...
デフォルトでは、QDocは//!
をコード・スニペット・マーカーとして探します。.pro
、.py
、.cmake
、CMakeLists.txt
のファイルでは、#!
が検出されます。最後に、.html
、.qrc
、.ui
、.xml
、.xq
ファイルでは、<!--
が検出されます。
\コードライン
Ȃ「codeline」コマンドは、整形済みテキストの空白行を挿入します。このコマンドは、現在の整形済みテキスト・エリアを閉じて新しいエリアを開くことなく、スニペット間のギャップを挿入するために使用されます。
本ドキュメントに含まれる文書の著作権は、それぞれの所有者に帰属します。 本書で提供されるドキュメントは、Free Software Foundation が発行したGNU Free Documentation License version 1.3に基づいてライセンスされています。 Qtおよびそれぞれのロゴは、フィンランドおよびその他の国におけるThe Qt Company Ltd.の 商標です。その他すべての商標は、それぞれの所有者に帰属します。