Qt GUI：既存のテキストをリストに変換する便利な関数「QTextCursor::createList()」

Qt GUIのQTextCursor::createList()関数は、テキストカーソルの位置にあるブロックの内容を、リストの最初の項目に変換します。これは、既存のテキストをリストに変換したり、新しいリストを作成する際に役立ちます。

構文

QTextList *QTextCursor::createList();

戻り値

この関数は、変換されたリストを表す QTextList ポインタを返します。変換に失敗した場合は、nullptr を返します。

例

QTextCursor cursor(document); // テキストドキュメント内のカーソルを取得
cursor.movePosition(QTextCursor::End, QTextCursor::MoveAnchor); // カーソルをドキュメントの最後に移動
cursor.insertText("リスト化するテキスト"); // リスト化するテキストを挿入
QTextList *list = cursor.createList(); // テキストをリストに変換
if (list) {
    // リストが作成された場合の処理
    list->setFormat(listFormat); // リストのフォーマットを設定
}

リストのフォーマットは、QTextListFormat クラスを使用して設定できます。
リストを作成する前に、QTextCursor::currentList() 関数を使用して、カーソルが現在どのリスト内にあるのかを確認できます。
QTextCursor::createList() 関数は、カーソルの位置にあるブロック全体をリストに変換します。部分的に変換したい場合は、QTextCursor::selectedText() 関数で選択範囲を取得してから、そのテキストをリストに変換する必要があります。

上記以外にも、QTextCursor::insertList() 関数を使用して、新しいリストを作成することもできます。この関数は、空のブロックをドキュメントに挿入し、それをリストの最初の項目にします。

QTextCursor cursor(document); // テキストドキュメント内のカーソルを取得
cursor.movePosition(QTextCursor::End, QTextCursor::MoveAnchor); // カーソルをドキュメントの最後に移動
cursor.insertList(listFormat); // 新しいリストを作成

#include <QApplication>
#include <QTextCursor>
#include <QTextDocument>
#include <QTextEdit>

int main(int argc, char *argv[]) {
    QApplication app(argc, argv);

    QTextDocument document;
    document.setPlainText("リスト化するテキスト\n別の行のテキスト");

    QTextEdit textEdit(&document);
    textEdit.show();

    QTextCursor cursor(&document);
    cursor.movePosition(QTextCursor::Start, QTextCursor::MoveAnchor);
    cursor.movePosition(QTextCursor::NextBlock, QTextCursor::MoveAnchor); // 2行目の先頭にカーソルを移動

    QTextList *list = cursor.createList();
    if (list) {
        QTextListFormat listFormat;
        listFormat.setIndent(2); // リストのインデントを設定
        listFormat.setMargin(10); // リストのマージンを設定
        list->setFormat(listFormat);
    }

    return app.exec();
}

このコードの説明

QApplication オブジェクトを作成し、イベントループを開始します。
QTextDocument オブジェクトを作成し、プレーンテキストを設定します。
QTextEdit ウィジェットを作成し、QTextDocument オブジェクトを設定します。
QTextCursor オブジェクトを作成し、QTextDocument オブジェクトに設定します。
カーソルを2行目の先頭に移動します。
QTextCursor::createList() 関数を使用して、カーソルの位置にあるテキストをリストに変換します。
リストのフォーマットを設定します。
アプリケーションを実行します。

実行結果

このコードを実行すると、以下のようになります。

リストは、設定されたインデントとマージンで表示されます。
ウィジェット内のテキストが2行のリストに変換されます。
QTextEdit ウィジェットが表示されます。

QTextCursor::createList() 関数は、既存のテキストをリストに変換する便利な機能ですが、状況によっては代替方法の方が適している場合があります。以下に、いくつかの代替方法とその利点と欠点をご紹介します。

QTextBlock::insertList()

この関数は、QTextBlock オブジェクトにリストを挿入します。カーソル位置ではなく、ブロック全体をリストに変換したい場合に適しています。

利点

ブロック全体をリストに変換できる。

欠点

カーソル位置にのみ作用する QTextCursor::createList() 関数よりも柔軟性に欠ける。

例

QTextCursor cursor(document); // テキストドキュメント内のカーソルを取得
cursor.movePosition(QTextCursor::Start, QTextCursor::MoveAnchor); // カーソルをドキュメントの先頭に移動
QTextBlock block = cursor.currentBlock();
block.insertList(listFormat); // ブロックにリストを挿入

手動でリストを作成する

この方法は、より細かい制御が必要な場合に適しています。以下の手順で、手動でリストを作成できます。

リストの最初の項目となるテキストを挿入します。
リストのフォーマットを設定します。
リストの次の項目となるテキストを挿入します。
2と3を繰り返します。

利点

リストのフォーマットを完全に制御できる。

欠点

QTextCursor::createList() 関数よりも時間とコード量がかかります。

例

QTextCursor cursor(document); // テキストドキュメント内のカーソルを取得
cursor.movePosition(QTextCursor::Start, QTextCursor::MoveAnchor); // カーソルをドキュメントの先頭に移動
cursor.insertText("リストの最初の項目");
cursor.insertBlockFormat(listFormat); // リストのフォーマットを設定
cursor.insertText("リストの次の項目");
// ...

QTextTable を使用する

利点

行と列を個別にフォーマットできる。
複雑なリストを作成できる。

欠点

QTextCursor::createList() 関数よりも学習曲線が急である。

QTextCursor cursor(document); // テキストドキュメント内のカーソルを取得
cursor.movePosition(QTextCursor::Start, QTextCursor::MoveAnchor); // カーソルをドキュメントの先頭に移動
QTextTable *table = cursor.insertTable(2, 3); // 2行3列のテーブルを挿入
table->cellAt(0, 0).setText("リストの最初の項目");
table->cellAt(1, 0).setText("リストの次の項目");
table->cellAt(0, 1).setText("別のテキスト");
table->cellAt(1, 1).setText("さらに別のテキスト");
// ...