QGraphicsTextItem::hoverMoveEvent()の徹底解説

QGraphicsTextItem::hoverMoveEvent()は、Qt WidgetsライブラリにおけるQGraphicsTextItemクラスの仮想関数であり、マウスカーソルがテキストアイテムの上を移動した際に発生するイベントを処理します。この関数は、テキストアイテムとのインタラクションや、視覚的なフィードバックを提供するのに役立ちます。

機能

hoverMoveEvent()は、QGraphicsSceneHoverEventオブジェクトを引数として渡されます。このイベントオブジェクトには、マウスカーソルの位置、ボタンの状態、修飾キーなどの情報が含まれています。

この関数は、以下の処理を行うために使用できます。

マウスカーソルがテキストアイテムの上を移動した際に、カスタムイベントを発生させる
マウスカーソルがテキストアイテムの上を移動した際に、ツールチップを表示する
マウスカーソルがテキストアイテムの上を移動した際に、テキストの色やフォントを変更する

例

以下の例では、マウスカーソルがテキストアイテムの上を移動した際に、テキストの色を赤に変更します。

void QGraphicsTextItem::hoverMoveEvent(QGraphicsSceneHoverEvent *event)
{
    if (event->hovering()) {
        setDefaultTextColor(Qt::red);
    } else {
        setDefaultTextColor(Qt::black);
    }
}

テキストアイテムとのインタラクションの詳細については、Qt Widgetsのドキュメントを参照してください。
この関数は、QGraphicsItem::hoverEnterEvent()およびQGraphicsItem::hoverLeaveEvent()関数と組み合わせて使用できます。
hoverMoveEvent()関数は、テキストアイテムが可視状態かつマウスカーソルとのインタラクションが有効な場合にのみ発生します。

具体的な使用方法については、ご自身のアプリケーションの要件に合わせて調整する必要があります。
上記以外にも、QGraphicsTextItem::hoverMoveEvent()関数は様々な目的に使用できます。

#include <QGraphicsScene>
#include <QGraphicsTextItem>

class MyTextItem : public QGraphicsTextItem
{
public:
    MyTextItem(const QString &text, QGraphicsItem *parent = nullptr);

protected:
    void hoverMoveEvent(QGraphicsSceneHoverEvent *event) override;
    void hoverLeaveEvent(QGraphicsSceneHoverEvent *event) override;
};

MyTextItem::MyTextItem(const QString &text, QGraphicsItem *parent)
    : QGraphicsTextItem(text, parent)
{
    setDefaultTextColor(Qt::black);
}

void MyTextItem::hoverMoveEvent(QGraphicsSceneHoverEvent *event)
{
    if (event->hovering()) {
        setDefaultTextColor(Qt::red);
    } else {
        setDefaultTextColor(Qt::black);
    }
}

void MyTextItem::hoverLeaveEvent(QGraphicsSceneHoverEvent *event)
{
    setDefaultTextColor(Qt::black);
}

このコードをどのように使用するかを説明します。

MyTextItemクラスを宣言します。このクラスは、QGraphicsTextItemクラスを継承し、hoverMoveEvent()およびhoverLeaveEvent()関数をオーバーライドします。
MyTextItemクラスのコンストラクタを宣言します。このコンストラクタは、テキストと親アイテムを受け取り、QGraphicsTextItemのコンストラクタを呼び出して、テキストアイテムを作成します。
hoverMoveEvent()関数をオーバーライドします。この関数は、マウスカーソルがテキストアイテムの上を移動した際に発生します。この関数では、setDefaultTextColor()関数を使用してテキストの色を赤に変更します。
hoverLeaveEvent()関数をオーバーライドします。この関数は、マウスカーソルがテキストアイテムから離れた際に発生します。この関数では、setDefaultTextColor()関数を使用してテキストの色を黒に戻します。
MyTextItemオブジェクトを作成し、シーンに追加します。

代替方法

QGraphicsItem::stateChanged(): このシグナルは、テキストアイテムの状態が変更された際に発生します。hoverEnterおよびhoverLeave状態を監視することで、マウスカーソルの移動を検知できます。

void MyTextItem::stateChanged(QGraphicsItem::State state)
{
    if (state & QGraphicsItem::HoverEnter) {
        setDefaultTextColor(Qt::red);
    } else if (state & QGraphicsItem::HoverLeave) {
        setDefaultTextColor(Qt::black);
    }
}

QGraphicsItem::installEventFilter(): この関数を用いて、イベントフィルタをインストールし、hoverMoveEvent()以外のイベントを処理することができます。

class MyEventFilter : public QObject
{
public:
    bool eventFilter(QObject *watched, QEvent *event) override
    {
        if (event->type() == QEvent::GraphicsSceneHoverMove) {
            QGraphicsSceneHoverEvent *hoverEvent = static_cast<QGraphicsSceneHoverEvent *>(event);
            MyTextItem *textItem = static_cast<MyTextItem *>(watched);

            if (hoverEvent->hovering()) {
                textItem->setDefaultTextColor(Qt::red);
            } else {
                textItem->setDefaultTextColor(Qt::black);
            }

            return true;
        }

        return QObject::eventFilter(watched, event);
    }
};

void MyTextItem::setup()
{
    MyEventFilter *filter = new MyEventFilter;
    installEventFilter(filter);
}

QGraphicsProxyItem: このクラスは、別のグラフィックスアイテムを代理するアイテムです。QGraphicsProxyItemを使用して、テキストアイテムをラップし、マウスカーソルの移動イベントを処理することができます。

class MyProxyItem : public QGraphicsProxyItem
{
public:
    MyProxyItem(MyTextItem *textItem)
        : QGraphicsProxyItem(textItem)
    {
        connect(this, &QGraphicsProxyItem::hoverMoveEvent, textItem, &MyTextItem::hoverMoveEvent);
    }
};

選択

上記で紹介した代替方法はそれぞれ長所と短所があります。

QGraphicsProxyItem: コードが簡潔で、テキストアイテム以外のアイテムにも適用できますが、パフォーマンスが低下する可能性があります。
QGraphicsItem::installEventFilter(): 柔軟性が高く、hoverMoveEvent()以外のイベントも処理できますが、コードが複雑になります。
QGraphicsItem::stateChanged(): シンプルでわかりやすいですが、hoverEnterおよびhoverLeave状態のみを検知できます。

状況に応じて、最適な代替方法を選択する必要があります。

具体的な方法は、ご自身のアプリケーションの要件に合わせて検討する必要があります。
上記以外にも、QGraphicsTextItem::hoverMoveEvent()の代替方法は存在します。

既存のコードでQGraphicsTextItem::hoverMoveEvent()関数を使用している場合は、代替方法を使用する前に、コードを書き換える必要があります。
上記の代替方法を使用する場合は、QGraphicsTextItem::hoverMoveEvent()関数は呼び出されないことに注意してください。