Qt TextInput カーソル移動・選択範囲操作 `moveCursorSelection()` 徹底解説【QML プログラミング】

2025-03-21

TextInput.moveCursorSelection() の説明

TextInput.moveCursorSelection() は、Qt Quick (QML) の TextInput 要素で使用できるメソッドの一つです。このメソッドは、テキスト入力フィールド内のカーソル位置と選択範囲をプログラム的に移動させるために使用されます。

主な機能

選択範囲の変更
カーソルを移動させる際に、既存の選択範囲を拡張または縮小したり、新しい選択範囲を作成したりすることができます。
カーソル移動
指定された位置にテキストカーソルを移動させることができます。

メソッドのシグネチャ

void moveCursorSelection(int position, int anchor)

anchor (int)
選択範囲のアンカーとなる位置を指定します。
- position と anchor が同じ値の場合、選択範囲は作成されず、カーソルだけが移動します。
- position と anchor が異なる値の場合、anchor から position までの範囲が選択されます。anchor が position より小さい場合は左から右へ、大きい場合は右から左への選択となります。
position (int)
カーソルを移動させる新しい位置を指定します。この位置は、テキストの先頭からの文字数（インデックス）で表されます。0 は最初の文字の前、テキストの長さは最後の文字の後を意味します。

具体的な動作の例

最後の3文字を選択
```
var length = textInput.text.length;
textInput.moveCursorSelection(length - 3, length);
```
この例では、アンカーが末尾 (length) で、位置が末尾から3文字前 (length - 3) なので、最後の3文字が選択されます。
最初の3文字を選択
```
textInput.moveCursorSelection(3, 0);
```
この例では、アンカーが 0 (先頭) で、位置が 3 なので、インデックス 0, 1, 2 の文字が選択されます。

カーソルを末尾に移動

textInput.moveCursorSelection(textInput.text.length, textInput.text.length);

```
textInput.moveCursorSelection(0, 0);
```

利用場面

ユーザー操作によらず、特定のテキスト範囲を強調表示したい場合。
入力補完やオートサジェスト機能と連携して、候補を自動的に選択したい場合。
プログラム的にテキストの一部を選択状態にしたい場合。
特定の条件に基づいてカーソル位置を調整したい場合。

moveCursorSelection() は、ユーザーがテキストを入力したり、カーソルを操作したりするのと同じように、テキスト入力フィールドの状態を変更します。
TextInput 要素には、現在のカーソル位置や選択範囲に関するプロパティ (cursorPosition, selectionStart, selectionEnd) も用意されています。これらのプロパティを読み取ることで、現在の状態を確認できます。

TextInput.moveCursorSelection() の一般的なエラーとトラブルシューティング

position または anchor が無効な値の場合

トラブルシューティング
- position と anchor に指定する値が、常に 0 以上 textInput.text.length 以下であることを確認してください。
- テキストの長さを取得するには、textInput.text.length プロパティを使用します。
- 動的にテキストが変化する場合は、textChanged シグナルなどでテキスト長を再評価し、moveCursorSelection() に渡す値を更新する必要があります。
エラー
position または anchor に、テキストの長さの範囲外の値（負の数やテキスト長を超える数）を指定すると、予期しないカーソル位置や選択範囲になる可能性があります。場合によっては、プログラムがクラッシュする可能性も否定できません（ただし、Qt Quick の場合は比較的安全に処理されることが多いです）。

意図しない選択範囲になる場合

トラブルシューティング
- 選択範囲を作成したくない場合は、position と anchor に同じ値を指定してください。
- 選択範囲の開始位置と終了位置を正しく理解し、anchor を選択範囲の固定点、position を移動させる点として考えると分かりやすいです。
- デバッガや console.log() などを使用して、position と anchor の値が期待通りになっているか確認してください。
エラー
position と anchor の値を誤って設定すると、意図しない範囲が選択されたり、何も選択されなかったりすることがあります。

moveCursorSelection() の呼び出しタイミングの問題

トラブルシューティング
- Component.onCompleted ハンドラや、関連するデータのロードが完了したことを示すシグナルなど、適切なタイミングで moveCursorSelection() を呼び出すようにしてください。
- 必要であれば、タイマー (Qt.createTimer()) を使用して、わずかな遅延後に moveCursorSelection() を実行してみるのも有効な場合があります。
エラー
TextInput のテキストがまだ完全にロードされていない状態や、他の処理が完了していないタイミングで moveCursorSelection() を呼び出すと、期待通りの動作にならないことがあります。

フォーカスがない状態で moveCursorSelection() を呼び出す場合

トラブルシューティング
- 視覚的なフィードバックが必要な場合は、moveCursorSelection() を呼び出す前に textInput.forceActiveFocus() などを使用して、TextInput にフォーカスを当てることを検討してください。
動作
TextInput にフォーカスがない状態でも moveCursorSelection() を呼び出すことは可能ですが、画面上でのカーソルの移動や選択範囲のハイライトは、フォーカスが当たっていないと視覚的に確認できない場合があります。

他のカーソル操作との競合

トラブルシューティング
- ユーザーの操作とプログラムによるカーソル操作が頻繁に競合する場合は、どちらの操作を優先するか、または両方の操作を適切に連携させるためのロジックを検討する必要があります。例えば、ユーザーが操作を開始したらプログラムによる操作を一時的に停止するなど。
エラー
ユーザーが手動でカーソルを操作している最中に、プログラムから moveCursorSelection() を呼び出すと、予期しない挙動を引き起こす可能性があります。

QML バインディングの問題

トラブルシューティング
- バインディングが期待通りに評価されているか確認してください。
- 必要であれば、JavaScript 関数内で明示的に値を計算し、その結果を moveCursorSelection() に渡すようにすることで、バインディングの評価タイミングによる問題を回避できる場合があります。
エラー
position や anchor の値が QML のバインディングによって動的に変化する場合、バインディングの評価タイミングによっては意図しない値が moveCursorSelection() に渡されることがあります。

簡単なテストケースの作成
問題を再現する最小限のコードを作成し、そこで動作を確認することで、問題を切り分けやすくなります。
ステップ実行
Qt Creator のデバッガを使用して、コードをステップ実行し、moveCursorSelection() が呼び出される際の変数の状態を確認します。
console.log() の活用
position や anchor に渡している値、および textInput.text.length などの関連するプロパティの値をコンソールに出力して確認することで、問題の原因を特定しやすくなります。

基本的なカーソル移動

import QtQuick 2.15
import QtQuick.Controls 2.15

ApplicationWindow {
    visible: true
    width: 400
    height: 200
    title: "TextInput カーソル操作例"

    TextInput {
        id: inputField
        anchors.fill: parent
        text: "これはサンプルテキストです。"
    }

    Column {
        anchors.horizontalCenter: parent.horizontalCenter
        spacing: 10

        Button {
            text: "先頭に移動"
            onClicked: inputField.moveCursorSelection(0, 0)
        }

        Button {
            text: "末尾に移動"
            onClicked: inputField.moveCursorSelection(inputField.text.length, inputField.text.length)
        }
    }
}

説明

「末尾に移動」ボタンをクリックすると、inputField.moveCursorSelection(inputField.text.length, inputField.text.length) が実行され、カーソルがテキストの末尾に移動します。ここでも anchor が同じ値なので、選択範囲は作成されません。
「先頭に移動」ボタンをクリックすると、inputField.moveCursorSelection(0, 0) が実行され、カーソルがテキストの先頭（インデックス 0）に移動します。anchor も 0 なので、選択範囲は作成されません。
この例では、TextInput と二つの Button を配置しています。

テキストの一部を選択

import QtQuick 2.15
import QtQuick.Controls 2.15

ApplicationWindow {
    visible: true
    width: 400
    height: 200
    title: "TextInput 選択範囲操作例"

    TextInput {
        id: inputField
        anchors.fill: parent
        text: "これはサンプルテキストです。"
    }

    Column {
        anchors.horizontalCenter: parent.horizontalCenter
        spacing: 10

        Button {
            text: "最初の5文字を選択"
            onClicked: inputField.moveCursorSelection(5, 0)
        }

        Button {
            text: "「サンプル」を選択"
            onClicked: {
                var startIndex = inputField.text.indexOf("サンプル");
                if (startIndex !== -1) {
                    inputField.moveCursorSelection(startIndex + "サンプル".length, startIndex);
                }
            }
        }
    }
}

説明

「「サンプル」を選択」ボタンをクリックすると、まず indexOf() メソッドでテキスト内に "サンプル" という文字列が存在するかどうかを検索します。存在する場合、その開始インデックス (startIndex) を取得し、moveCursorSelection() を呼び出します。anchor に開始インデックス、position に開始インデックスに "サンプル" の長さを加えた値を指定することで、「サンプル」という文字列が選択されます。
「最初の5文字を選択」ボタンをクリックすると、inputField.moveCursorSelection(5, 0) が実行されます。anchor が 0 (先頭) で、position が 5 なので、インデックス 0 から 4 までの最初の5文字が選択されます。

カーソル位置を動的に変更

import QtQuick 2.15
import QtQuick.Controls 2.15

ApplicationWindow {
    visible: true
    width: 400
    height: 200
    title: "TextInput 動的なカーソル操作例"

    TextInput {
        id: inputField
        anchors.top: parent.top
        anchors.left: parent.left
        anchors.right: parent.right
        text: "初期テキスト"
    }

    Slider {
        id: positionSlider
        anchors.top: inputField.bottom
        anchors.left: parent.left
        anchors.right: parent.right
        minimumValue: 0
        maximumValue: inputField.text.length
        value: 0
        onValueChanged: inputField.moveCursorSelection(value, value)
    }

    Text {
        anchors.top: positionSlider.bottom
        anchors.horizontalCenter: parent.horizontalCenter
        text: "カーソル位置: " + positionSlider.value
    }

    Component.onCompleted: {
        positionSlider.maximumValue = inputField.text.length;
        inputField.textChanged.connect(function() {
            positionSlider.maximumValue = inputField.text.length;
            // テキストが変更されたら、スライダーの値が範囲内になるように調整
            if (positionSlider.value > inputField.text.length) {
                positionSlider.value = inputField.text.length;
            }
        });
    }
}

説明

Component.onCompleted と textChanged シグナルハンドラ内で、Slider の maximumValue を TextInput のテキスト長に合わせて更新することで、常に有効な範囲でスライダーを操作できるようにしています。
Slider の値が変更されると、その値が inputField.moveCursorSelection(value, value) の position と anchor に渡され、カーソル位置がスライダーの値に対応して移動します。選択範囲は作成されません。
この例では、TextInput の下に Slider と Text を配置しています。

入力時に特定のパターンを強調表示

import QtQuick 2.15
import QtQuick.Controls 2.15

ApplicationWindow {
    visible: true
    width: 400
    height: 200
    title: "TextInput パターン強調表示例"

    TextInput {
        id: inputField
        anchors.fill: parent
        text: ""
        onTextChanged: {
            var keyword = "強調";
            var startIndex = text.indexOf(keyword);
            if (startIndex !== -1) {
                moveCursorSelection(startIndex + keyword.length, startIndex);
            } else {
                // キーワードが見つからない場合は選択を解除
                moveCursorSelection(cursorPosition, cursorPosition);
            }
        }
    }
}

キーワードが見つからない場合は、現在のカーソル位置に position と anchor を設定することで、選択を解除します。
キーワードが見つかった場合、moveCursorSelection() を使用してそのキーワードを選択状態にします。
この例では、TextInput の onTextChanged シグナルハンドラ内で、入力されたテキストに特定のキーワード ("強調") が含まれているかどうかをチェックしています。

cursorPosition プロパティと selectionStart/selectionEnd プロパティの直接操作

TextInput は、現在のカーソル位置を表す cursorPosition プロパティと、選択範囲の開始位置 (selectionStart) および終了位置 (selectionEnd) を表すプロパティを持っています。これらのプロパティに直接値を代入することで、カーソル位置や選択範囲を変更できます。

TextInput {
    id: inputField
    text: "サンプルテキスト"

    function moveCursorTo(index) {
        cursorPosition = index;
    }

    function selectRange(start, end) {
        selectionStart = start;
        selectionEnd = end;
    }

    Component.onCompleted: {
        moveCursorTo(5); // カーソルを5番目の文字の後に移動
        selectRange(0, 3); // 最初の3文字を選択
    }
}

利点

単純なカーソル移動や選択範囲の設定には十分。
直感的で分かりやすい。

注意点

プログラムのロジックによっては、cursorPosition、selectionStart、selectionEnd の値を矛盾なく管理する必要がある場合があります。
moveCursorSelection() のように、一つのメソッド呼び出しでカーソル移動とアンカー設定を同時に行えないため、選択範囲の変更には selectionStart と selectionEnd の両方を設定する必要があります。

selectAll() メソッド

テキスト全体を選択したい場合は、selectAll() メソッドを呼び出すだけで済みます。

TextInput {
    id: inputField
    text: "すべてのテキストを選択します"

    Button {
        text: "全選択"
        onClicked: inputField.selectAll()
    }
}

利点

テキスト全体を選択する際のコードが簡潔になる。

deselect() メソッド

現在の選択範囲を解除したい場合は、deselect() メソッドを呼び出します。

TextInput {
    id: inputField
    text: "選択を解除します"
    selectionStart: 0
    selectionEnd: 5 // 初期状態で最初の5文字を選択

    Button {
        text: "選択解除"
        onClicked: inputField.deselect()
    }
}

利点

選択範囲を簡単に解除できる。

テキスト操作と組み合わせた間接的なカーソル/選択制御

テキストの挿入、削除、置換などの操作を行うと、それに伴ってカーソル位置や選択範囲が自動的に調整されることがあります。これらのテキスト操作を利用して、間接的にカーソルや選択範囲を制御することも可能です。

TextInput {
    id: inputField
    text: "元のテキスト"

    Button {
        text: "先頭に挿入"
        onClicked: {
            inputField.text = "追加の " + inputField.text;
            inputField.cursorPosition = "追加の ".length; // 挿入したテキストの直後にカーソルを移動
        }
    }
}

利点

複雑なカーソル移動ロジックを、より高レベルなテキスト操作に置き換えられる場合がある。
テキストの内容を変更しながら、自然なカーソル移動を実現できる。

注意点

テキストの内容変更が不要な場合は、オーバーヘッドになる可能性がある。
単純なカーソル移動や選択範囲の設定に比べて、コードが複雑になる可能性がある。

シグナルとスロットの活用

TextInput は、カーソル位置や選択範囲が変更された際に cursorPositionChanged や selectionChanged などのシグナルを発行します。これらのシグナルを他の要素やロジックに接続することで、カーソルや選択範囲の変化に反応した処理を行うことができます。直接的にカーソルを移動させるわけではありませんが、間接的にアプリケーションの動作を制御できます。

TextInput {
    id: inputField
    text: "テキスト入力"
    onCursorPositionChanged: console.log("カーソル位置が変更されました:", cursorPosition)
    onSelectionChanged: console.log("選択範囲が変更されました:", selectionStart, selectionEnd)
}

利点

アプリケーションの他の部分との連携が容易になる。
カーソルや選択範囲の変化に柔軟に対応できる。

より複雑なカーソル移動や選択範囲の操作が必要な場合は、moveCursorSelection() が最も柔軟性の高い選択肢となります。
カーソルや選択範囲の変化に他の処理を連動させたい場合は、シグナルとスロットを活用します。
テキストの内容を変更しながらカーソルを移動させたい場合は、テキスト操作と cursorPosition の組み合わせが有効です。
選択範囲を解除する場合は、deselect() を使用します。
テキスト全体を選択する場合は、selectAll() が簡潔です。
単純なカーソル移動や選択範囲の設定には、cursorPosition、selectionStart、selectionEnd プロパティの直接操作が適しています。