HoverHandler QML Type

マウスおよびタブレットのホバー処理。詳細...

• 継承されたメンバーを含む、すべてのメンバーの一覧

プロパティ

• acceptedDevices : flags
• acceptedModifiers : flags
• acceptedPointerTypes : flags
• active : bool
• blocking : bool (since 6.3)
• cursorShape : Qt::CursorShape
• enabled : bool
• grabPermissions : flags
• hovered : bool
• margin : real
• parent : Item
• point : handlerPoint
• target : Item

信号

• canceled(eventPoint point)
• grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

詳細な説明

HoverHandlerは、マウスやタブレットのスタイラスのカーソルがホバー状態になったことを検出します。

hovered プロパティへのバインディングは、カーソルがparent アイテムに進入または離脱した際に反応する最も簡単な方法です。point プロパティは、カーソルの位置など、より詳細な情報を提供します。acceptedDevices 、acceptedPointerTypes 、およびacceptedModifiers プロパティを使用することで、特定の種類のデバイスでのホバーや、修飾キーを押下中のホバーを検出するように動作を絞り込むことができます。

cursorShape プロパティを使用すると、hovered がtrue に変わった際にカーソルを変更できます。

「 MouseArea 」、「PointHandler 」、および「Qt Quick 」の「例 - ポインタハンドラ」も参照してください 。

プロパティのドキュメント

acceptedDevices : flags

ポインタハンドラを起動できるポインティングデバイスの種類。

デフォルトでは、このプロパティはPointerDevice.AllDevices に設定されています。デバイスタイプの「OR」組み合わせに設定した場合、一致しないデバイスからのポインタイベントは無視されます。

たとえば、2つのハンドラを使用して、アイテムがマウスのホバーにはある方法で、スタイラスのホバーには別の方法で反応するように設定できます。

import QtQuick

Rectangle {
    width: 150; height: 50; radius: 3
    color: mouse.hovered ? "goldenrod" : stylus.hovered ? "tomato" : "wheat"

    HoverHandler {
        id: stylus
        acceptedDevices: PointerDevice.Stylus
        cursorShape: Qt.CrossCursor
    }

    HoverHandler {
        id: mouse
        acceptedDevices: PointerDevice.Mouse | PointerDevice.TouchPad
        cursorShape: Qt.PointingHandCursor
    }
}

利用可能なデバイスタイプは以下の通りです:

「QInputDevice::DeviceType」も参照してください 。

acceptedModifiers : flags

このプロパティが設定されている場合、指定されたキーボード修飾キーが押されているときにのみ、ホバーイベントが処理されます。修飾キーが押されていない場合は、イベントは無視されます。

このプロパティはデフォルトで `Qt.KeyboardModifierMask ` に設定されており、これにより修飾キーの有無にかかわらずホバーイベントが処理されます。

たとえば、Item には同じタイプのハンドラが2つ設定されており、そのうち1つは必要なキーボード修飾キーが押された場合にのみ有効になります。

import QtQuick

Rectangle {
    width: 150; height: 50; radius: 3
    color: control.hovered ? "goldenrod" : shift.hovered ? "wheat" : "beige"

    HoverHandler {
        id: control
        acceptedModifiers: Qt.ControlModifier
        cursorShape: Qt.PointingHandCursor
    }

    HoverHandler {
        id: shift
        acceptedModifiers: Qt.ShiftModifier
        cursorShape: Qt.CrossCursor
    }
}

使用可能な修飾キーは以下の通りです：

Qt::KeyboardModifierも参照してください 。

acceptedPointerTypes : flags

ポインタハンドラを起動できるポインティングデバイスの種類（汎用、スタイラス、消しゴムなど）。

デフォルトでは、このプロパティはPointerDevice.AllPointerTypes に設定されています。デバイスタイプの「OR」組み合わせに設定した場合、条件に一致しないイベントは無視されます。

たとえば、グラフィックスタブレット上でスタイラスと消しゴムのどちらがホバーしているかによってカーソルを変更し、フィードバックを提供することができます。

import QtQuick

Rectangle {
    id: rect
    width: 150; height: 150

    HoverHandler {
        id: stylus
        acceptedPointerTypes: PointerDevice.Pen
        cursorShape: Qt.CrossCursor
    }

    HoverHandler {
        id: eraser
        acceptedPointerTypes: PointerDevice.Eraser
        cursorShape: Qt.BlankCursor
        target: Image {
            parent: rect
            source: "images/cursor-eraser.png"
            visible: eraser.hovered
            x: eraser.point.position.x
            y: eraser.point.position.y - 32
        }
    }
}

使用可能なポインタの種類は次のとおりです：

QPointingDevice::PointerTypeも参照してください 。

active : bool [read-only]

この変数には、この入力ハンドラが1つ以上のeventPoints を排他的に取得することに成功し、それらの処理を単独で担当している間、true が格納されます。つまり、この入力ハンドラは、それらのeventPointsの動きに応じて自身のプロパティを最新の状態に保ち、target （存在する場合）を能動的に操作していることを意味します。

blocking : bool [since 6.3]

このハンドラが、その背後にある他のアイテムやハンドラへの同時ホバーを妨げるかどうかを示します。このプロパティのデフォルト値はfalse です。

このプロパティは Qt 6.3 で導入されました。

cursorShape : Qt::CursorShape

このプロパティは、hovered がtrue に設定されており、かつ他のハンドラによって上書きされていない場合に表示されるカーソルの形状を保持します。

利用可能なカーソル形状は以下の通りです：

• Qt.ArrowCursor
• Qt.UpArrowCursor
• Qt.CrossCursor
• Qt.WaitCursor
• Qt.IBeamCursor
• Qt.SizeVerCursor
• Qt.SizeHorCursor
• Qt.SizeBDiagCursor
• Qt.SizeFDiagCursor
• Qt.SizeAllCursor
• Qt.BlankCursor
• Qt.SplitVカーソル
• Qt.SplitHCursor
• Qt.指差しカーソル
• Qt.ForbiddenCursor
• Qt.WhatIsThisカーソル
• Qt.BusyCursor
• Qt.開いた手のカーソル
• Qt.閉じた手のカーソル
• Qt.ドラッグコピーカーソル
• Qt.DragMoveCursor
• Qt.DragLinkCursor

このプロパティのデフォルト値は設定されておらず、これにより、同じ親アイテム上でアクティブなハンドラがカーソルの形状を決定できるようになります。このプロパティは、undefined に設定することで初期状態にリセットできます。

cursorShape が定義されているハンドラのうち、いずれかがactive である場合、そのカーソルが表示されます。それ以外の場合、HoverHandler にcursorShape が定義されている場合は、そのカーソルが表示されます。それ以外の場合は、親アイテムのcursor が表示されます。

「 Qt::CursorShape 」および「QQuickItem::cursor()」も参照してください 。

enabled : bool

HoverHandler が無効になっている場合、すべてのイベントが拒否され、シグナルは一切発信されません。

HoverHandler のparent がdisabled に設定されている場合、HoverHandler はデフォルトでホバーイベントに引き続き反応します。これは、コントロールが無効化されている場合でも、ホバー時のフィードバック効果やツールチップが有用である可能性があるためです。親要素が無効化されている場合にHoverHandler を無効化したい場合は、バインディングを追加することができます：

Item {
    HoverHandler {
        enabled: parent.enabled
    }
}

grabPermissions : flags

このプロパティは、このハンドラのロジックが排他的なグラブを引き継ぐことを決定した場合、または別のハンドラからグラブの引き継ぎや取り消しの承認を求められた場合の権限を指定します。

デフォルトは `PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything ` であり、ほとんどの引き継ぎシナリオを許可しますが、例えば 2 つの `PinchHandler` が同じタッチポイントを奪い合うような事態は回避します。

hovered : bool [read-only]

ポインティングデバイス（マウスやタブレット）のカーソルが、parent アイテムの範囲内（margin によって拡張されている場合はその範囲を含む）にあるときは常にこの動作が適用されます。

margin : real

parent 項目の境界線の外側にある余白で、eventPoint がこのハンドラーを起動できる範囲です。たとえば、target がparent でもあるPinchHandler の場合、この値を一般的なユーザーの指の幅の少なくとも半分以上の距離に設定しておくと便利です。そうすることで、parent が非常に小さなサイズに縮小されていても、ピンチジェスチャーが可能になります。 あるいは、TapHandler ベースのボタンを画面の端近くに配置する場合、フィッツの法則に準拠するためにこれを利用できます。つまり、ボタンが視覚的には画面の端から数ピクセル離れているように見えても、画面の端でのマウスクリックに反応するようにするのです。

デフォルト値は 0 です。

parent : Item

Item は、ハンドラの適用範囲であり、宣言されたItemを指します。ハンドラはこのItemに代わってイベントを処理します。つまり、ポインタイベントは、そのeventPoints のうち少なくとも1つがItemの内部で発生する場合にのみ関連付けられます。初期状態ではtarget() は同一ですが、再割り当てが可能です。

target およびQObject::parent()も参照してください 。

point : handlerPoint [read-only]

現在処理中のeventPoint 。現在処理中のポイントが存在しない場合、このオブジェクトはデフォルト値（すべての座標が0）にリセットされます。

target : Item

このハンドラが操作対象とするアイテム。

デフォルトでは、これはparent 、つまりハンドラが宣言されているItemと同じです。ただし、あるアイテム内のイベントを処理しつつ別のアイテムを操作する場合や、null としてデフォルトの動作を無効にし、代わりに別の処理を行う場合など、ターゲットを別のItemに設定すると便利な場合があります。

シグナルのドキュメント

canceled(eventPoint point)

このハンドラーがすでに指定されたpoint を取得している場合、別のポインタハンドラーまたはアイテムによってその取得が奪われたときに、このシグナルが発信されます。

grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

このシグナルは、グラブにこのハンドラに関連する何らかの変化が生じた際に発せられます。

transition （動詞）は、何が起こったかを示します。point （目的語）は、グラブされた、またはグラブが解除されたポイントです。

transition の有効な値は以下の通りです：