QListWidget::visualItemRect()の落とし穴：よくあるエラーと解決策

QListWidget::visualItemRect(const QListWidgetItem *item) const は、QtのQListWidgetクラスが提供するメンバ関数です。この関数は、指定されたQListWidgetItem（リスト内の個々の項目）がビューポート（表示領域）内で占める長方形の領域をQRectオブジェクトとして返します。

具体的な意味と用途

1. 表示されている領域の取得: QListWidgetは、多くの項目を持つ場合、スクロール可能になります。visualItemRect()は、指定した項目が現在画面上のどこに表示されているか（または、表示されるはずの領域がどこか）を知るために使用されます。

   • たとえ項目が部分的にしか表示されていなくても、その項目全体が占める矩形領域が返されます。
   • 項目が完全にビューポートの外にあって表示されていない場合でも、その項目が表示されると仮定した場合のビューポート内での仮想的な位置とサイズが返されます。

2. 座標系の理解: 返されるQRectの座標は、QListWidgetのビューポートを基準とした相対座標です。つまり、QListWidget自体の左上隅からのピクセルオフセットで示されます。

3. イベント処理や視覚的な操作:

   • ドラッグ＆ドロップ: ユーザーがリストアイテムをドラッグしている際に、他のアイテムの上にカーソルが来ているかなどを判定するために、visualItemRect()でアイテムの領域を取得し、カーソル位置と比較することができます。
   • カスタムペイント: QListWidgetの表示をカスタムで描画する場合（例えば、特定のアイテムにハイライトや追加情報を表示する場合など）、visualItemRect()を使ってそのアイテムの描画領域を正確に把握することができます。
   • ツールチップやコンテキストメニュー: アイテムがクリックされたり、マウスがホバーされたりした際に、そのアイテムの表示位置に基づいてツールチップを表示したり、コンテキストメニューを開いたりする際に役立ちます。
   • 特定のアイテムへのスクロール: scrollToItem()などを使って特定のアイテムにスクロールした後、そのアイテムが実際にどこに表示されているかを確認するためにも使えます。

戻り値

QRectオブジェクトを返します。このQRectは、以下の情報を含みます。

• width(), height(): 項目の幅と高さ
• x(), y(): 項目の左上隅のX, Y座標（ビューポート基準）

使用例 (PyQt/PySide の例ですが、C++でも考え方は同じです)

from PySide2.QtWidgets import QApplication, QListWidget, QListWidgetItem, QMainWindow
from PySide2.QtCore import Qt, QRect

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QListWidget visualItemRect Example")
        self.setGeometry(100, 100, 400, 300)

        self.list_widget = QListWidget(self)
        self.setCentralWidget(self.list_widget)

        for i in range(20):
            item = QListWidgetItem(f"Item {i}")
            self.list_widget.addItem(item)

        # 例として、5番目のアイテムの表示領域を取得して出力する
        # このコードは、ウィンドウが表示され、リストウィジェットがレイアウトされた後に実行する必要があります
        # そのため、通常はイベントハンドラ内やタイマーイベントなどで呼び出されます。
        # ここでは便宜上、初期化時に呼び出していますが、実際には表示後に意味を持ちます。

        # アイテムがクリックされたときにその表示領域をコンソールに出力する例
        self.list_widget.itemClicked.connect(self.on_item_clicked)

    def on_item_clicked(self, item: QListWidgetItem):
        rect = self.list_widget.visualItemRect(item)
        print(f"Clicked item: {item.text()}")
        print(f"Visual Rect (x, y, width, height): {rect.x()}, {rect.y()}, {rect.width()}, {rect.height()}")
        print(f"Global position of rect top-left: {self.list_widget.mapToGlobal(rect.topLeft())}")


if __name__ == "__main__":
    app = QApplication([])
    window = MainWindow()
    window.show()
    app.exec_()

---

QListWidget::visualItemRect()は非常に便利な関数ですが、誤った使い方をすると予期せぬ結果やエラーにつながることがあります。

項目がビューポートに表示されていない場合の座標

問題: 項目がスクロールによってビューポート（表示領域）の外にある場合でもvisualItemRect()を呼び出すと、無効な矩形（例: 幅や高さが0、または負の座標）が返されると誤解することがあります。

現実: visualItemRect()は、たとえ項目が現在表示されていなくても、その項目がビューポート内にあった場合に占めるであろう仮想的な矩形を返します。つまり、QListWidgetのスクロール位置を考慮した上での、項目全体の論理的な表示領域を返します。したがって、幅や高さが0になることは稀で、負の座標が返されることも通常はありません。

トラブルシューティング:

• もし、実際に画面に表示されている領域のみに関心がある場合は、返されたQRectとQListWidgetのviewport()->rect()（またはcontentsRect()）との積集合（intersected()）を取ることで、実際に表示されている部分の矩形を得ることができます。
• 項目がビューポートの外にある場合でも、その矩形はスクロールバーを動かせば表示される位置を示していることを理解する。
• 返されたQRectのisValid()メソッドを使って、矩形が有効かどうかを確認する。（ただし、通常は常に有効な矩形が返されます。）

ウィジェットとして設定されたアイテムの表示に関する問題

問題: QListWidgetItemにQWidget（例えばQLabelやQPushButton）をsetItemWidget()で設定している場合、visualItemRect()が返す矩形が、実際に表示されているウィジェットのサイズや位置と微妙に異なるように見えることがあります。これは、Qtの内部的なレイアウトやスタイリングが影響している可能性があります。

トラブルシューティング:

• カスタムペイントを行う場合、visualItemRect()で得られた矩形を基準に描画しますが、ウィジェットがどのように配置されるかを考慮する必要があります。
• QListWidgetのアイテムのサイズヒント（QListWidgetItem::sizeHint()）が適切に設定されているか確認します。setItemWidget()を使用している場合、Qtは通常、設定されたウィジェットのサイズヒントを尊重しますが、手動で調整が必要な場合もあります。
• setItemWidget()を使用している場合、ウィジェット自体のgeometry()やrect()メソッドを呼び出して、そのウィジェットの正確な位置とサイズを取得することも検討してください。

QListWidgetがまだレイアウトされていない、または表示されていない場合の呼び出し

問題: QListWidgetがまだ親ウィジェットに追加されておらず、またはshow()が呼び出される前など、UIが完全に構築・レイアウトされる前にvisualItemRect()を呼び出すと、正しい（意味のある）値が得られないことがあります。この場合、返されるQRectは全てゼロであったり、予期せぬ値になる可能性があります。

トラブルシューティング:

• 最も確実なのは、QListWidgetのサイズ変更イベント（resizeEvent）後や、ユーザー操作（例: クリックイベント）のハンドラ内で呼び出すことです。
• 例えば、showEvent()をオーバーライドしたり、QApplication::processEvents()を呼び出してイベントループを処理させたり、QTimer::singleShot()で少し遅延させてから呼び出すといった方法が考えられます。
• visualItemRect()を呼び出すタイミングを、QListWidgetが完全に表示され、レイアウトが計算された後に限定します。

無効なQListWidgetItemポインタを渡す

問題: QListWidgetに存在しない、またはすでに削除されたQListWidgetItemのポインタをvisualItemRect()に渡すと、クラッシュしたり、未定義の動作を引き起こしたりする可能性があります。

トラブルシューティング:

• アイテムを削除した後は、そのアイテムのポインタを再利用しないように注意します。
• QListWidgetItemポインタが有効であることを常に確認してから関数を呼び出します。例えば、QListWidget::item()やQListWidget::currentItem()などで取得したポインタを使用する場合は、それがnullptrでないことを確認します。

スクロールポリシーやビューモードの変更

問題: QListWidgetのスクロールポリシー（setScrollArea()など）やビューモード（setViewMode()）を変更した場合、アイテムの配置やvisualItemRect()が返す結果に影響を与える可能性があります。

トラブルシューティング:

• 特にQListWidget::setFlow(QListView::LeftToRight)やQListWidget::setGridSize()など、グリッド表示やフロー表示を設定した場合、アイテムの配置ロジックが変わるため、visualItemRect()が返す座標系の理解がより重要になります。
• これらの設定を変更した場合は、visualItemRect()の挙動が期待通りであることをテストで確認してください。

パフォーマンスに関する考慮事項

問題: 多数のアイテムを持つQListWidgetで、頻繁に多くのアイテムに対してvisualItemRect()を呼び出すと、パフォーマンスに影響を与える可能性があります。

トラブルシューティング:

• もし大量のアイテムの情報を頻繁に取得する必要がある場合は、QtのModel/Viewアーキテクチャ（QListViewとカスタムモデル/デリゲート）の使用を検討してください。これはより柔軟でパフォーマンスの高い描画とデータ管理を可能にします。
• 必要な場合にのみvisualItemRect()を呼び出すように最適化します。例えば、すべてのアイテムの領域をループで取得するのではなく、特定のイベントが発生したアイテムのみ取得するようにします。

---

QListWidget::visualItemRect()関数は、QListWidget内の特定の項目が、リストウィジェットのビューポート（表示領域）内でどのような矩形領域を占めているかを取得するために使用されます。この情報を利用することで、さまざまな視覚的な操作やイベント処理が可能になります。

以下に、いくつかの一般的な使用シナリオにおけるC++のコード例を示します。

クリックされたアイテムの表示領域をデバッグ出力する

最も基本的な使用例です。ユーザーがリストの項目をクリックしたときに、その項目の位置とサイズをコンソールに出力します。

#include <QApplication>
#include <QMainWindow>
#include <QListWidget>
#include <QListWidgetItem>
#include <QRect>
#include <QDebug> // デバッグ出力用

class MainWindow : public QMainWindow
{
    Q_OBJECT // シグナル/スロットを使用するために必要

public:
    MainWindow(QWidget *parent = nullptr) : QMainWindow(parent)
    {
        setWindowTitle("visualItemRect Example");
        setGeometry(100, 100, 400, 300);

        QListWidget *listWidget = new QListWidget(this);
        setCentralWidget(listWidget);

        for (int i = 0; i < 20; ++i) {
            listWidget->addItem(QString("Item %1").arg(i));
        }

        // itemClicked シグナルをスロットに接続
        connect(listWidget, &QListWidget::itemClicked, this, &MainWindow::onItemClicked);
    }

private slots:
    void onItemClicked(QListWidgetItem *item)
    {
        QListWidget *listWidget = qobject_cast<QListWidget*>(sender());
        if (!listWidget || !item) {
            return;
        }

        // 指定されたアイテムの視覚的な矩形を取得
        QRect itemRect = listWidget->visualItemRect(item);

        qDebug() << "Clicked Item:" << item->text();
        qDebug() << "Visual Rect (x, y, width, height):"
                 << itemRect.x() << "," << itemRect.y() << ","
                 << itemRect.width() << "," << itemRect.height();

        // リストウィジェット全体のグローバル座標に変換
        QPoint globalPos = listWidget->mapToGlobal(itemRect.topLeft());
        qDebug() << "Global Position of Rect Top-Left:" << globalPos.x() << "," << globalPos.y();
    }
};

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    MainWindow window;
    window.show();
    return app.exec();
}

#include "main.moc" // シグナル/スロットのMOC処理に必要

説明:

• mapToGlobal()を使って、ビューポート内の相対座標をスクリーン上の絶対座標に変換する例も示しています。
• QDebugを使って、その矩形の位置とサイズを出力しています。
• listWidget->visualItemRect(item)を呼び出すことで、そのアイテムがQListWidgetのビューポート内で占めるQRectが取得されます。
• 項目がクリックされると、onItemClickedが呼び出され、クリックされたQListWidgetItemへのポインタが渡されます。
• onItemClickedスロットがQListWidget::itemClickedシグナルに接続されています。

マウスのホバー時にツールチップを表示する（カスタムウィジェット使用）

QListWidgetItemにカスタムウィジェット（例: QLabelなど）を設定し、そのウィジェット上でマウスがホバーされたときに、visualItemRect()を使って正確な位置にツールチップを表示する例です。

この例は少し複雑になりますが、QListWidgetのイベントをオーバーライドして、マウスの位置がどのアイテムの領域内にあるかを判断する必要があります。

#include <QApplication>
#include <QMainWindow>
#include <QListWidget>
#include <QListWidgetItem>
#include <QLabel>
#include <QToolTip>
#include <QMouseEvent>
#include <QVBoxLayout>
#include <QDebug>

class CustomListWidget : public QListWidget
{
    Q_OBJECT
public:
    CustomListWidget(QWidget *parent = nullptr) : QListWidget(parent)
    {
        // マウスのトラッキングを有効にする
        setMouseTracking(true);

        for (int i = 0; i < 20; ++i) {
            QListWidgetItem *item = new QListWidgetItem(this);
            QLabel *label = new QLabel(QString("詳細情報: Item %1").arg(i));
            label->setAlignment(Qt::AlignCenter);
            item->setSizeHint(label->sizeHint() + QSize(0, 10)); // スペースを追加
            addItem(item);
            setItemWidget(item, label);
        }
    }

protected:
    void mouseMoveEvent(QMouseEvent *event) override
    {
        // マウスカーソルの位置にあるアイテムを取得
        QListWidgetItem *item = itemAt(event->pos());

        if (item) {
            // アイテムの視覚的な矩形を取得
            QRect itemRect = visualItemRect(item);

            // マウスカーソルがアイテムの矩形内にあるか確認
            if (itemRect.contains(event->pos())) {
                // そのアイテムにカスタムツールチップを表示
                // Qt::ToolTip は通常のツールチップで、ここでは例として使います。
                // より高度なツールチップが必要な場合は、QToolTip::showText() を使って
                // 独自の内容と位置を指定できます。
                QToolTip::showText(event->globalPos(), "ホバー中: " + item->text());
                //qDebug() << "Mouse over item:" << item->text();
            } else {
                QToolTip::hideText(); // 矩形の外に出たらツールチップを隠す
            }
        } else {
            QToolTip::hideText(); // アイテム上にない場合はツールチップを隠す
        }
        QListWidget::mouseMoveEvent(event); // 親クラスのイベント処理を呼び出す
    }

    void leaveEvent(QEvent *event) override
    {
        QToolTip::hideText(); // ウィジェットからマウスが離れたらツールチップを隠す
        QListWidget::leaveEvent(event);
    }
};

class MainWindowWithCustomList : public QMainWindow
{
public:
    MainWindowWithCustomList(QWidget *parent = nullptr) : QMainWindow(parent)
    {
        setWindowTitle("visualItemRect Custom Tooltip Example");
        setGeometry(100, 100, 400, 300);

        CustomListWidget *listWidget = new CustomListWidget(this);
        setCentralWidget(listWidget);
    }
};

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    MainWindowWithCustomList window;
    window.show();
    return app.exec();
}

#include "main.moc"

説明:

• QToolTip::showText()は、指定されたグローバル座標にツールチップを表示します。
• その後、visualItemRect(item)で取得した矩形がマウスカーソルを含んでいるかcontains()で確認し、ツールチップを表示/非表示を切り替えています。
• itemAt(event->pos())を使って、現在のマウスカーソル位置にあるQListWidgetItemを取得します。
• setMouseTracking(true)を呼び出すことで、マウスボタンが押されていない状態でもmouseMoveEventが発生するようにします。
• CustomListWidgetをQListWidgetから継承し、mouseMoveEvent()とleaveEvent()をオーバーライドしています。

選択されたアイテムの中心にスクロールする

特定のアイテムを選択し、そのアイテムがビューポートの中央に来るようにスクロールする例です。これはscrollToItem()と似ていますが、より細かくスクロール位置を制御する場合に役立ちます。

#include <QApplication>
#include <QMainWindow>
#include <QListWidget>
#include <QPushButton>
#include <QVBoxLayout>
#include <QDebug>
#include <QScrollBar>

class ScrollToCenterWindow : public QMainWindow
{
    Q_OBJECT
public:
    ScrollToCenterWindow(QWidget *parent = nullptr) : QMainWindow(parent)
    {
        setWindowTitle("Scroll to Center Example");
        setGeometry(100, 100, 400, 400);

        QWidget *centralWidget = new QWidget(this);
        QVBoxLayout *layout = new QVBoxLayout(centralWidget);
        setCentralWidget(centralWidget);

        listWidget = new QListWidget(this);
        for (int i = 0; i < 50; ++i) { // 多数のアイテムを追加してスクロール可能にする
            listWidget->addItem(QString("Item %1").arg(i));
        }
        layout->addWidget(listWidget);

        QPushButton *scrollButton = new QPushButton("Scroll Item 25 to Center", this);
        layout->addWidget(scrollButton);

        connect(scrollButton, &QPushButton::clicked, this, &ScrollToCenterWindow::onScrollButtonClicked);
    }

private slots:
    void onScrollButtonClicked()
    {
        // 25番目のアイテム（0-indexedなので24番目）を取得
        if (listWidget->count() <= 24) {
            qDebug() << "Item 25 does not exist.";
            return;
        }

        QListWidgetItem *targetItem = listWidget->item(24); // 25番目のアイテム

        // アイテムの視覚的な矩形を取得
        QRect itemRect = listWidget->visualItemRect(targetItem);
        qDebug() << "Target Item 25 Visual Rect:" << itemRect;

        // リストウィジェットのビューポートの矩形
        QRect viewportRect = listWidget->viewport()->rect();
        qDebug() << "Viewport Rect:" << viewportRect;

        // アイテムの中心Y座標
        int itemCenterY = itemRect.center().y();

        // ビューポートの中心Y座標
        int viewportCenterY = viewportRect.center().y();

        // スクロールバーの現在値
        int currentScrollValue = listWidget->verticalScrollBar()->value();

        // 新しいスクロールバーの値を計算
        // アイテムの中心がビューポートの中心に来るようにする
        int newScrollValue = currentScrollValue + (itemCenterY - viewportCenterY);

        // スクロールバーの値を設定
        listWidget->verticalScrollBar()->setValue(newScrollValue);

        qDebug() << "Scrolled to bring Item 25 to center.";
    }

private:
    QListWidget *listWidget;
};

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    ScrollToCenterWindow window;
    window.show();
    return app.exec();
}

#include "main.moc"

説明:

• verticalScrollBar()->setValue()を使って、スクロール位置をプログラムで設定します。
• アイテムの中心Y座標とビューポートの中心Y座標を計算し、その差分を現在のスクロールバーの値に加算することで、アイテムがビューポートの中央に来るようにスクロールバーの値を調整します。
• QListWidgetのビューポートの矩形も取得します。
• ターゲットとなるアイテム（この例では25番目のアイテム）のvisualItemRect()を取得します。
• スクロールボタンがクリックされると、onScrollButtonClicked()が呼び出されます。

---

QAbstractItemViewのメソッドを利用する

QListWidgetは内部的にQListViewを継承しており、さらにその親クラスであるQAbstractItemViewから多くの機能を受け継いでいます。Model/Viewフレームワークの概念を理解している場合、以下のメソッドが代替として役立ちます。

• QRect QAbstractItemView::visualRect(const QModelIndex &index) const これはvisualItemRect()と非常に似ていますが、QListWidgetItem*の代わりにQModelIndexを引数に取ります。QListWidgetの項目は内部的にQModelIndexとして表現されています。 QListWidgetItemからQModelIndexを取得するには、QListWidget::indexFromItem(const QListWidgetItem *item) constを使用します。

  利点:

  • Model/Viewアーキテクチャのより一般的なインターフェースであり、QTableViewやQTreeViewなど他のビューでも同様の概念で使える。
  • カスタムモデルを使用するQListViewなど、より柔軟なリスト表示を実装する際に役立つ。

  欠点:

  • QListWidgetItemからQModelIndexへの変換が必要になるため、visualItemRect()よりもコードが少し長くなる可能性があります。

  例:

  // QListWidgetItem* item があると仮定
  QModelIndex index = listWidget->indexFromItem(item);
  if (index.isValid()) {
      QRect itemRect = listWidget->visualRect(index);
      qDebug() << "Visual Rect (using QModelIndex):" << itemRect;
  }
  

マウスイベントとitemAt()、indexAt()を組み合わせる

ユーザーのマウス操作に基づいて、特定のアイテムの位置を特定したい場合、visualItemRect()を直接使うのではなく、マウスイベントの座標と以下のメソッドを組み合わせる方法があります。

• QModelIndex QAbstractItemView::indexAt(const QPoint &p) const 指定されたウィジェット座標pにある項目のQModelIndexを返します。項目がない場合は無効なQModelIndexを返します。

• QListWidgetItem *QListWidget::itemAt(const QPoint &p) const 指定されたウィジェット座標pにある項目へのポインタを返します。項目がない場合はnullptrを返します。

利点:

• 例えば、ドラッグ＆ドロップ操作でカーソル下の項目をハイライトする場合などに非常に便利です。
• ユーザーがクリックまたはホバーした位置から、どの項目がその場所にあるかを直接的に特定できます。

欠点: