Qt イベント処理の基礎：QCheckBox stateChanged() を中心に解説（日本語）

QCheckBox::stateChanged(int state) は、QCheckBox （チェックボックス）の状態が変化したときに送出（emit）されるシグナルです。

各部分の意味

• (int state): これは、このシグナルが送出される際に、引数として整数型の値 state を伴うことを示しています。この state の値は、チェックボックスの新しい状態を表します。

• stateChanged: これはシグナルの名前です。直訳すると「状態が変化した」となり、チェックボックスの状態が変更されたことを意味します。

• QCheckBox
  : これは、このシグナルが QCheckBox クラスに属していることを示しています。

• void: これは、このシグナルが値を返さないことを意味します。シグナルは、何らかの処理の結果を伝えるのではなく、何かが起こったという通知を行う役割を持つため、通常は void 型です。

state 引数の値と意味

state 引数は、以下のいずれかの値を取ります。

• Qt::Checked (値: 2): チェックボックスがチェックされている状態です。
• Qt::PartiallyChecked (値: 1): チェックボックスが部分的にチェックされている状態です。これは、通常、複数の子アイテムを持つような場合に用いられます。（例えば、ツリービューの中で一部のアイテムがチェックされている親ノードなど）
• Qt::Unchecked (値: 0): チェックボックスがチェックされていない状態です。

このシグナルの役割

stateChanged シグナルは、チェックボックスの状態がユーザーの操作（クリックなど）によって変化したときに自動的に送出されます。プログラマーは、このシグナルにスロットと呼ばれる関数を接続することで、チェックボックスの状態変化に応じて特定のアクションを実行することができます。

例

例えば、チェックボックスの状態が変化したときに、テキストラベルの内容を更新したい場合、以下のような手順になります。

1. チェックボックスの stateChanged シグナルに、テキストラベルを更新する独自の関数（スロット）を接続します。
2. ユーザーがチェックボックスの状態を変更すると、stateChanged シグナルが送出されます。
3. 接続されたスロット関数が自動的に呼び出され、引数として新しい状態 (state) が渡されます。
4. スロット関数の中で、渡された state の値に応じてテキストラベルの内容を更新する処理を記述します。

---

シグナルとスロットが接続されていない

• トラブルシューティング
  
  • connect() 関数の呼び出しがコード内に存在するか確認してください。
  • connect() 関数の引数が正しいか確認してください。
    • 送信元のオブジェクト（QCheckBox のインスタンス）
    • 送信元のシグナル (SIGNAL(stateChanged(int)))
    • 受信先のオブジェクト
    • 受信先のスロット (SLOT(あなたのスロット関数名(int)))
  • シグナルとスロットの引数の型が一致しているか確認してください (stateChanged は int 型の引数を持ちます)。
  • connect() 関数が正しいタイミングで呼び出されているか確認してください（通常はチェックボックスのインスタンスが作成された後）。
• 原因
  QObject::connect() 関数を使って、stateChanged シグナルと目的のスロット関数が正しく接続されていない。
• エラー
  チェックボックスの状態を変更しても、期待される処理（スロット関数）が実行されない。

スロット関数の引数の不一致

• トラブルシューティング
  
  • スロット関数の定義を確認し、int 型の引数を一つ受け取るように修正してください。
  • スロット関数内で引数を使用しない場合でも、定義上は int 型の引数が必要です。
• 原因
  stateChanged シグナルは int 型の引数を渡しますが、接続されたスロット関数が異なる型の引数を受け取ろうとしている、または引数がない。
• エラー
  シグナルが送出されるが、接続されたスロット関数が呼び出されない、またはプログラムがクラッシュする。

スロット関数内でのエラー

• トラブルシューティング
  
  • スロット関数の中のコードを注意深く見直し、論理的な誤りがないか確認してください。
  • 例外処理 (try-catch ブロック) を適切に実装し、エラー発生時にプログラムが停止しないようにしてください。
  • デバッガを使用して、スロット関数内の処理をステップ実行し、エラー箇所を特定してください。
• 原因
  接続されたスロット関数の中に論理的なエラーや例外が発生するコードが含まれている。
• エラー
  チェックボックスの状態変化に応じてスロット関数は呼び出されるが、期待される動作が起こらない、またはプログラムがクラッシュする。

シグナルが意図しないタイミングで複数回送出される

• トラブルシューティング
  
  • チェックボックスの状態をプログラム的に変更している箇所を特定し、本当に必要な変更かどうか、またそのタイミングが適切かどうかを確認してください。
  • 必要であれば、状態変更の処理を一時的に無効化したり、フラグを使って複数回の処理を防ぐなどの対策を検討してください。
  • blockSignals(true) と blockSignals(false) を使用して、特定の期間シグナルの送出を一時的にブロックすることも有効です。
• 原因
  
  • コード内でチェックボックスの状態をプログラム的に変更している箇所があり、そのたびに stateChanged シグナルが送出されている。
  • 不適切なロジックにより、意図せず状態変更が繰り返されている。
• エラー
  チェックボックスの状態を一度変更しただけなのに、接続されたスロット関数が複数回呼び出される。

スロット関数での無限ループ

• トラブルシューティング
  
  • スロット関数内でチェックボックスの状態を変更する処理がある場合、その条件やロジックを見直し、無限ループが発生しないように修正してください。
  • blockSignals() を使用して、スロット関数内での状態変更によるシグナル送出を一時的に防ぐことを検討してください。
• 原因
  スロット関数の中で、再びチェックボックスの状態を変更する処理を行っており、それが連鎖的に繰り返されて無限ループに陥っている。
• エラー
  チェックボックスの状態を変更すると、プログラムがフリーズしたり、CPU使用率が異常に高くなる。

• トラブルシューティング
  
  • GUIオブジェクトへのアクセスは、常にGUIスレッドから行うようにしてください。
  • 別のスレッドからGUIを操作する必要がある場合は、Qt::QueuedConnection を使用してシグナルとスロットを接続し、GUIスレッドで処理が実行されるようにしてください。
• 原因
  QtのGUIオブジェクトは、原則としてGUIスレッドからのみアクセスする必要があります。
• エラー
  GUIスレッドとは異なるスレッドからチェックボックスの状態を変更しようとして、予期しない動作やクラッシュが発生する。

---

基本的な例：チェックボックスの状態に応じてテキストラベルを更新する

この例では、チェックボックスの状態が変化したときに、その状態をテキストラベルに表示します。

#include <QApplication>
#include <QWidget>
#include <QCheckBox>
#include <QLabel>
#include <QVBoxLayout>

class MyWidget : public QWidget {
public:
    MyWidget(QWidget *parent = nullptr) : QWidget(parent) {
        // チェックボックスの作成
        checkBox = new QCheckBox("チェックしてください", this);

        // テキストラベルの作成
        label = new QLabel("初期状態：未チェック", this);

        // レイアウトの作成
        QVBoxLayout *layout = new QVBoxLayout(this);
        layout->addWidget(checkBox);
        layout->addWidget(label);

        // シグナルとスロットの接続
        connect(checkBox, &QCheckBox::stateChanged, this, &MyWidget::updateLabel);
    }

private slots:
    void updateLabel(int state) {
        QString stateText;
        if (state == Qt::Unchecked) {
            stateText = "未チェック";
        } else if (state == Qt::PartiallyChecked) {
            stateText = "部分的にチェック";
        } else if (state == Qt::Checked) {
            stateText = "チェック済み";
        }
        label->setText(QString("現在の状態：%1").arg(stateText));
    }

private:
    QCheckBox *checkBox;
    QLabel *label;
};

int main(int argc, char *argv[]) {
    QApplication a(argc, argv);
    MyWidget w;
    w.show();
    return a.exec();
}

解説

1. ヘッダーファイルのインクルード
   必要なQtのクラス (QApplication, QWidget, QCheckBox, QLabel, QVBoxLayout) のヘッダーファイルをインクルードします。
2. MyWidget クラスの定義
   
   • QCheckBox のインスタンス checkBox と QLabel のインスタンス label をメンバ変数として宣言します。
   • コンストラクタで、これらのウィジェットを作成し、初期テキストを設定します。
   • QVBoxLayout を使用して、チェックボックスとラベルを縦に配置します。
   • connect(checkBox, &QCheckBox::stateChanged, this, &MyWidget::updateLabel);: ここが重要です。
     • 最初の引数 checkBox は、シグナルを送信するオブジェクトです。
     • 2番目の引数 &QCheckBox::stateChanged は、送信されるシグナルのアドレスです。stateChanged シグナルは int 型の引数を持つため、&QCheckBox::stateChanged と記述します。
     • 3番目の引数 this は、シグナルを受信するオブジェクト（この MyWidget のインスタンス）です。
     • 4番目の引数 &MyWidget::updateLabel は、シグナルが送出されたときに呼び出されるスロット関数のアドレスです。この関数は int 型の引数を受け取る必要があります。
3. updateLabel スロット関数
   
   • この関数は private slots: セクションで宣言されています。Qtのシグナルとスロットの仕組みでは、スロット関数は slots キーワードの下に宣言する必要があります。
   • 引数として state（チェックボックスの新しい状態）を受け取ります。
   • state の値に応じて、テキストラベルに表示する文字列を決定します。
   • label->setText() を使って、ラベルのテキストを更新します。
4. main 関数
   
   • QApplication のインスタンスを作成します。
   • MyWidget のインスタンスを作成し、show() メソッドで表示します。
   • a.exec() でQtのイベントループを開始します。

複数のチェックボックスの状態を監視する例

この例では、複数のチェックボックスを作成し、それぞれの状態が変化したときに共通のスロット関数で処理します。

#include <QApplication>
#include <QWidget>
#include <QCheckBox>
#include <QLabel>
#include <QVBoxLayout>
#include <QStringList>

class MyWidget : public QWidget {
public:
    MyWidget(QWidget *parent = nullptr) : QWidget(parent) {
        QVBoxLayout *layout = new QVBoxLayout(this);
        QStringList labels = {"オプションA", "オプションB", "オプションC"};

        for (const QString &labelStr : labels) {
            QCheckBox *cb = new QCheckBox(labelStr, this);
            checkBoxes.append(cb);
            layout->addWidget(cb);
            connect(cb, &QCheckBox::stateChanged, this, &MyWidget::checkBoxStateChanged);
        }

        infoLabel = new QLabel("いずれかのチェックボックスの状態が変化しました", this);
        layout->addWidget(infoLabel);
        setLayout(layout);
    }

private slots:
    void checkBoxStateChanged(int state) {
        // どのチェックボックスの状態が変化したかは、シグナルを送信したオブジェクトから知ることができます。
        QCheckBox *senderCheckBox = qobject_cast<QCheckBox*>(sender());
        if (senderCheckBox) {
            QString stateText;
            if (state == Qt::Checked) {
                stateText = "チェック";
            } else {
                stateText = "未チェック";
            }
            infoLabel->setText(QString("%1 が %2 になりました").arg(senderCheckBox->text()).arg(stateText));
        }
    }

private:
    QList<QCheckBox*> checkBoxes;
    QLabel *infoLabel;
};

int main(int argc, char *argv[]) {
    QApplication a(argc, argv);
    MyWidget w;
    w.show();
    return a.exec();
}

1. 複数の QCheckBox を QList に格納します。
2. ループ内でチェックボックスを作成し、レイアウトに追加すると同時に、それぞれの stateChanged シグナルを同じスロット関数 checkBoxStateChanged に接続します。
3. sender() スロット
   checkBoxStateChanged スロット関数内では、sender() 関数を使用して、どのオブジェクトがシグナルを送信したか（どのチェックボックスの状態が変化したか）を取得できます。
4. qobject_cast
   sender() は QObject* 型を返すため、それを QCheckBox* 型に安全にキャストするために qobject_cast を使用します。キャストに失敗した場合は nullptr が返ります。
5. 変化したチェックボックスのテキストと新しい状態に応じて、infoLabel のテキストを更新します。

---

clicked(bool checked) シグナルの利用

QCheckBox は clicked(bool checked) という別のシグナルも提供しています。このシグナルは、チェックボックスがクリックされたときに送出され、引数としてクリック後のチェック状態（true がチェック済み、false が未チェック）を受け取ります。

• 欠点
  stateChanged シグナルとは異なり、プログラム的に状態を変更した場合（例えば setChecked() メソッドを呼び出した場合）には送出されません。ユーザーのクリック操作によってのみ発生します。
• 利点
  チェックボックスがクリックされた瞬間の状態を直接知ることができます。状態が PartiallyChecked になるケースを区別する必要がない場合に便利です。

例

#include <QApplication>
#include <QWidget>
#include <QCheckBox>
#include <QLabel>
#include <QVBoxLayout>

class MyWidget : public QWidget {
public:
    MyWidget(QWidget *parent = nullptr) : QWidget(parent) {
        checkBox = new QCheckBox("クリックしてください", this);
        label = new QLabel("初期状態：未チェック", this);

        QVBoxLayout *layout = new QVBoxLayout(this);
        layout->addWidget(checkBox);
        layout->addWidget(label);
        setLayout(layout);

        connect(checkBox, &QCheckBox::clicked, this, &MyWidget::updateLabelOnClicked);
    }

private slots:
    void updateLabelOnClicked(bool checked) {
        label->setText(QString("クリック後の状態：%1").arg(checked ? "チェック済み" : "未チェック"));
    }

private:
    QCheckBox *checkBox;
    QLabel *label;
};

int main(int argc, char *argv[]) {
    QApplication a(argc, argv);
    MyWidget w;
    w.show();
    return a.exec();
}

toggled(bool checked) シグナルの利用

QCheckBox は toggled(bool checked) シグナルも提供しています。このシグナルは、チェックボックスの状態が変化したときに送出され、引数として新しいチェック状態（true がチェック済み、false が未チェック）を受け取ります。

• 欠点
  Qt::PartiallyChecked の状態を区別することができません。
• 利点
  stateChanged シグナルと同様に、ユーザー操作とプログラムによる状態変更の両方で送出されます。Qt::PartiallyChecked の状態を区別する必要がない場合に、より簡潔にチェック状態 (true / false) を扱えます。

例

#include <QApplication>
#include <QWidget>
#include <QCheckBox>
#include <QLabel>
#include <QVBoxLayout>

class MyWidget : public QWidget {
public:
    MyWidget(QWidget *parent = nullptr) : QWidget(parent) {
        checkBox = new QCheckBox("トグルしてください", this);
        label = new QLabel("初期状態：未チェック", this);

        QVBoxLayout *layout = new QVBoxLayout(this);
        layout->addWidget(checkBox);
        layout->addWidget(label);
        setLayout(layout);

        connect(checkBox, &QCheckBox::toggled, this, &MyWidget::updateLabelOnToggled);
    }

private slots:
    void updateLabelOnToggled(bool checked) {
        label->setText(QString("トグル後の状態：%1").arg(checked ? "チェック済み" : "未チェック"));
    }

private:
    QCheckBox *checkBox;
    QLabel *label;
};

int main(int argc, char *argv[]) {
    QApplication a(argc, argv);
    MyWidget w;
    w.show();
    return a.exec();
}

イベントフィルタの利用

QObject::installEventFilter() を使用して、チェックボックスに送信されるイベントを監視し、その中で状態の変化を検出することも可能です。

• 欠点
  stateChanged シグナルよりも実装が複雑になる可能性があり、チェックボックスの状態変化の検出もより間接的になります。通常は、専用のシグナルが用意されている場合はそちらを使う方が簡潔です。
• 利点
  より低レベルなイベント処理が可能になり、他のイベントと組み合わせて複雑なロジックを実装できます。

例

#include <QApplication>
#include <QWidget>
#include <QCheckBox>
#include <QLabel>
#include <QVBoxLayout>
#include <QEvent>
#include <QMouseEvent>

class MyWidget : public QWidget {
public:
    MyWidget(QWidget *parent = nullptr) : QWidget(parent), currentState(Qt::Unchecked) {
        checkBox = new QCheckBox("イベントを監視", this);
        label = new QLabel("初期状態：未チェック", this);

        QVBoxLayout *layout = new QVBoxLayout(this);
        layout->addWidget(checkBox);
        layout->addWidget(label);
        setLayout(layout);

        checkBox->installEventFilter(this);
    }

protected:
    bool eventFilter(QObject *watched, QEvent *event) override {
        if (watched == checkBox && event->type() == QEvent::MouseButtonRelease) {
            // マウスボタンが離されたときに状態が変化した可能性がある
            Qt::CheckState newState = checkBox->checkState();
            if (newState != currentState) {
                currentState = newState;
                updateLabelFromEvent(currentState);
            }
        }
        return QWidget::eventFilter(watched, event);
    }

private:
    void updateLabelFromEvent(Qt::CheckState state) {
        QString stateText;
        if (state == Qt::Unchecked) {
            stateText = "未チェック";
        } else if (state == Qt::PartiallyChecked) {
            stateText = "部分的にチェック";
        } else if (state == Qt::Checked) {
            stateText = "チェック済み";
        }
        label->setText(QString("イベント検出：現在の状態：%1").arg(stateText));
    }

private:
    QCheckBox *checkBox;
    QLabel *label;
    Qt::CheckState currentState;
};

int main(int argc, char *argv[]) {
    QApplication a(argc, argv);
    MyWidget w;
    w.show();
    return a.exec();
}

解説

1. installEventFilter(this) を使って、MyWidget クラス自身を checkBox のイベントフィルタとして登録します。
2. eventFilter() 関数をオーバーライドし、監視対象のオブジェクト (watched) とイベント (event) を受け取ります。
3. watched が checkBox であり、イベントのタイプが QEvent::MouseButtonRelease（マウスボタンが離された）であることを確認します。これは、クリック操作が完了し、チェックボックスの状態が変化するタイミングである可能性が高いです。
4. 現在のチェック状態 (checkBox->checkState()) を取得し、以前の状態 (currentState) と比較して変化があった場合にのみラベルを更新します。

チェックボックスの状態をポーリングする (非推奨)

タイマーなどを使って定期的にチェックボックスの状態 (checkBox->checkState()) を確認する方法も考えられますが、これは一般的に効率が悪く、推奨されません。イベント駆動型のQtの仕組みを活用する方が適切です。