外部コードの埋め込み

以下のコマンドを使用すると、外部ファイルからのコードスニペットを組み込むことができます。QDocにファイルの内容全体を組み込ませることも、ファイルの特定の部分を引用して他の部分をスキップさせることも可能です。後者の典型的な用途は、ファイルをブロックごとに引用することです。

\quotefile

\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.
*/

バージョン 6.11 以降、\quotefile コマンドと同じ行に、大文字小文字を区別しないオプション引数として言語を指定できるようになりました。これは、 \code コマンドと同様の方法で、引用されたテキストに影響を与えます。

例：

\quotefile [text] examples/main.cpp

これは、QDocがマークアップできないソースコードを含むファイルから引用を行う際に役立ちます。

関連項目 \quotefromfile および \codeを参照してください。

\quotefromfile

\quotefromfile コマンドは、引数として指定されたファイルを開き、クォーティングを行います。

このコマンドは、行の残りの部分を引数の一部とみなすため、ファイル名の後に必ず改行を入れてください。

このコマンドは、以下のウォークスルーコマンドを使用してファイルの一部を引用する場合に利用することを想定しています： \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 を参照）。ファイルを「閉じる」必要はありません。

バージョン6.11以降、\quotefromfile コマンドと同じ行に、オプションの大文字小文字を区別しない引数として言語を指定できるようになりました。これは、 \code コマンドと同様に、引用されるテキストに影響を与えます。

例：

\quotefromfile [text] examples/main.cpp
\skipto main
\printuntil app(argc, argv)

QDocは、どのプログラミング言語のコードを引用しているかも記憶しているため、次のようなコマンドも利用できます。 \printline、 \printto や \printuntil 現在のファイルから引用し、新しいファイルが読み込まれるまで一貫したマークアップスタイルを適用します。

関連項目 \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 コマンドを再度使用します。

substring引数がスラッシュで囲まれている場合、それは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 コマンドと同じ規則に従います。

\printuntil を引数なしで使用した場合、現在の位置から引用されたファイルの末尾までのすべての行に展開されます。

ソースファイルの行は、等幅フォントと標準のインデントを使用して、別の段落として表示されます。コードはそのままの形で表示されます。

/*!
   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。

\skipline

\skipline コマンドは、現在のソースファイル内の次の空白行以外の行を無視します。

Docはファイルを順次読み込み、\skipline コマンドは現在の位置を移動させる（ソースファイルの1行をスキップする）ために使用されます。ファイルの位置指定に関する上記の注記を参照してください。

このコマンドは、その行の残りの部分を引数の一部として扱うため、部分文字列の後に必ず改行を入れるようにしてください。また、このコマンドは \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.
*/

関連項目 \skipto、 \skipuntil および \dots。

\skipto

\skipto コマンドは、現在の位置から、指定された部分文字列を含む次の行（その行自体は除く）までのすべての行を無視します。

QDocはファイルを順次読み込みますが、\skipto コマンドを使用すると、ソースファイルの1行または複数行をスキップして、現在の位置を移動させることができます。ファイルの位置指定に関する上記の注記を参照してください。

このコマンドは、行の残りの部分を引数の一部として扱います。部分文字列の後に必ず改行を入れるようにしてください。

また、このコマンドは \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 ...
*/

関連項目 \skipline、 \skipuntil および \dots。

\skipuntil

\skipuntil コマンドは、現在の位置から、指定された部分文字列を含む次の行まで（その行を含む）のすべての行を無視します。

QDocはファイルを順次読み込みますが、\skipuntil コマンドを使用すると、ソースファイルの1行または複数行をスキップして、現在の位置を移動させることができます。ファイルの位置指定に関する上記の注記を参照してください。

このコマンドは、その行の残りの部分を引数の一部として扱うため、部分文字列の後に必ず改行を入れてください。

また、このコマンドは \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...
*/

関連項目 \skipline、 \skipto および \dots。

\dots

\dots コマンドは、ファイルを引用する際にソースファイルの一部が省略されたことを示します。

このコマンドは \quotefromfile コマンドと組み合わせて使用され、単独の行に記述する必要があります。ドットは、等幅フォントを使用して新しい行に表示されます。

/*!
   \quotefromfile examples/main.cpp
   \skipto main
   \printuntil {
   \dots
   \skipuntil exec
   \printline }
*/

デフォルトのインデントは4スペースですが、このコマンドのオプション引数を使用して調整することができます。

/*!
    \dots 0
    \dots
    \dots 8
    \dots 12
    \dots 16
*/

関連項目 \skipline、 \skipto および \skipuntil。

\snippet

\snippet コマンドを使用すると、コードスニペットがそのままの形式で、事前フォーマットされたテキストとして挿入され、構文強調表示される場合があります。

各コードスニペットは、それを格納しているファイルと、そのファイルの一意の識別子によって参照されます。スニペットファイルは通常、ドキュメントディレクトリ内のsnippets ディレクトリに保存されます（例：$QTDIR/doc/src/snippets ）。

QDocは、最初に見つかった一致するファイルを使用します。同じ相対パスが複数の検索ディレクトリに存在する場合、QDocは辞書順でディレクトリを参照するため、あるファイルが別のファイルを上書きしてしまう可能性があります。

たとえば、以下のドキュメントは、ドキュメントディレクトリのサブディレクトリにあるファイル内のスニペットを参照しています:

\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 」ファイルでは、「<!-- 」が受け入れられます。

QDoc は、スニペットマーカーのスペースによるインデントを、スニペットのコンテンツの最小インデントと比較することで、スニペットのインデントを正規化します（Qt マクロ、空白行、および行全体にわたるコメントは無視されます）。 その後、スニペット本文のインデントを、その2つのうち小さい方に自動的に調整し、マーカーの位置にかかわらず、生成されたコードが常に自然な構造を保つようにします。インデントが浅すぎるマーカーについては、変更を加えません。

バージョン 6.11 以降、\snippet コマンドと同じ行に、大文字小文字を区別しないオプション引数として言語を指定できるようになりました。これは、 \code コマンドと同様に、引用されたテキストに影響を与えます。

このコマンドの使用例では、デフォルトの C++ マークアップスタイルを上書きし、代わりにプレーンテキストを出力します：

\snippet [text] code.cpp

これは、QDocがマークアップできない言語を引用する場合や、通常とは異なるファイル名を持つファイルから引用する必要がある場合に役立ちます。

\codeline

\codeline コマンドは、プレフォーマットされたテキストの空白行を挿入します。これは、現在のプレフォーマットされたテキスト領域を閉じたり、新しい領域を開いたりすることなく、スニペットの間に空白を挿入するために使用されます。