【初心者向け】Qt Widgetsでスプリッターハンドルの操作をマスターしよう！QSplitter::handle()の使い方

QSplitter::handle() 関数は、Qt Widgets ライブラリにおける QSplitter ウィジェットのハンドルを取得するために使用されます。QSplitter ウィジェットは、複数のウィジェットを垂直方向または水平方向に分割して配置するためのものです。ハンドルは、ユーザーがウィジェット間の境界をドラッグしてサイズを変更できるようにするグラフィカル要素です。

関数詳細

QSplitter::handle() 関数は、以下の引数と戻り値を持ちます。

戻り値: 指定されたインデックスのハンドルへのポインタ。ハンドルが存在しない場合は nullptr が返されます。
index: 取得したいハンドルのインデックス。インデックス 0 は常に非表示のハンドルを表します。

例

以下のコード例は、QSplitter ウィジェットの 2 番目のハンドルの位置を取得する方法を示しています。

QSplitter *splitter = new QSplitter(Qt::Horizontal);
splitter->addWidget(new QWidget);
splitter->addWidget(new QWidget);

QSplitterHandle *handle = splitter->handle(1);
int position = handle->pos();

ハンドルの動作は、QSplitter クラスの様々なシグナルとスロットを使用して制御できます。
ハンドルの外観は、QSplitterHandle クラスの様々なプロパティを使用してカスタマイズできます。
QSplitter ウィジェットには、複数のハンドルが存在する可能性があります。ハンドルの数は、QSplitter::count() 関数を使用して取得できます。

#include <QApplication>
#include <QSplitter>
#include <QWidget>

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

  // スプリッターを作成
  QSplitter splitter(Qt::Horizontal);

  // ウィジェットを追加
  QWidget *widget1 = new QWidget;
  widget1->setStyleSheet("background-color: red");
  splitter.addWidget(widget1);

  QWidget *widget2 = new QWidget;
  widget2->setStyleSheet("background-color: blue");
  splitter.addWidget(widget2);

  // 2 番目のハンドルの位置を取得
  QSplitterHandle *handle = splitter.handle(1);
  int position = handle->pos();
  std::cout << "2 番目のハンドルの位置: " << position << std::endl;

  // 2 番目のハンドルのサイズを変更
  handle->setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Fixed);

  // ウィジェットを表示
  splitter.show();

  return app.exec();
}

QApplication オブジェクトを作成します。
QSplitter ウィジェットを作成し、水平方向に分割するように設定します。
赤と青の背景色を持つ 2 つのウィジェットを作成し、スプリッターに追加します。
QSplitter::handle() 関数を使用して、2 番目のハンドルの位置を取得します。
QSplitterHandle::setSizePolicy() メソッドを使用して、2 番目のハンドルのサイズを変更します。
スプリッターを表示します。

スタイルシートを使用する

QSplitter ウィジェットのハンドルは、スタイルシートを使用して外観と動作をカスタマイズできます。ハンドルの位置やサイズを変更するには、以下のプロパティを使用できます。

handle-margin: ハンドルのマージンをピクセル単位で指定します。
handle-width: ハンドルの幅をピクセル単位で指定します。
handle-position: ハンドルの位置をピクセル単位で指定します。

以下のコード例は、スタイルシートを使用して、QSplitter ウィジェットのすべてのハンドルの位置を 10 ピクセル下に移動する方法を示しています。

QSplitter::handle {
  handle-position: bottom + 10px;
}

QSplitterHandle クラスをサブクラス化する

より高度なカスタマイズが必要な場合は、QSplitterHandle クラスをサブクラス化することができます。サブクラス化することで、ハンドルの外観、動作、イベントハンドリングなどを独自に実装することができます。

以下のコード例は、QSplitterHandle クラスをサブクラス化して、ハンドルの背景色を青色に変更する方法を示しています。

class MySplitterHandle : public QSplitterHandle {
public:
  MySplitterHandle(Qt::Orientation orientation, QWidget *parent)
      : QSplitterHandle(orientation, parent) {
  }

protected:
  void paintEvent(QPaintEvent *event) override {
    QPainter painter(this);
    painter.setBrush(QColor(Qt::blue));
    painter.drawRect(event->rect());
  }
};

カスタムウィジェットを使用する

ハンドルの完全な制御が必要な場合は、カスタムウィジェットを作成することができます。カスタムウィジェットを作成することで、ハンドルの外観、動作、イベントハンドリングなどを完全に独自に実装することができます。

以下のコード例は、カスタムウィジェットを使用して、QSplitter ウィジェットのハンドルをボタンに置き換える方法を示しています。

class MyButtonHandle : public QWidget {
public:
  MyButtonHandle(Qt::Orientation orientation, QWidget *parent)
      : QWidget(parent) {
    setLayout(new QVBoxLayout);
    QPushButton *button = new QPushButton("Resize");
    layout()->addWidget(button);
    connect(button, &QPushButton::clicked, this, &MyButtonHandle::resize);
  }

signals:
  void resize();

private:
  Qt::Orientation orientation;

public slots:
  void resize() {
    emit resize();
  }
};

ハンドルのイベントを直接処理する

ハンドルのイベントを直接処理する場合は、QSplitter::handleMoved() シグナルと QSplitter::handleResized() シグナルを使用できます。これらのシグナルは、ハンドルの位置またはサイズが変更されたときに発行されます。

以下のコード例は、QSplitter::handleMoved() シグナルを使用して、ハンドルの位置が変更されたときにログメッセージを出力する方法を示しています。

QSplitter splitter(Qt::Horizontal);
splitter.handleMoved.connect([](int index, const QPoint &pos) {
  std::cout << "ハンドル " << index << " が位置 (" << pos.x() << ", " << pos.y() << ") に移動しました。" << std::endl;
});

方法	長所	短所
スタイルシート	シンプルで使いやすい	高度なカスタマイズが難しい
QSplitterHandle クラスをサブクラス化する	高度なカスタマイズが可能	複雑でコード量が多い
カスタムウィジェットを使用する	完全な制御が可能	最も複雑でコード量が多い
ハンドルのイベントを直接処理する	特定のイベントのみを処理するのに適している	イベントハンドリングのロジックを自分で実装する必要がある