Flickable QML Type

「フリック」操作が可能な表面を提供します。詳細...

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

プロパティ

• acceptedButtons : flags (since 6.9)
• atXBeginning : bool
• atXEnd : bool
• atYBeginning : bool
• atYEnd : bool
• bottomMargin : real
• boundsBehavior : enumeration
• boundsMovement : enumeration
• contentHeight : real
• contentItem : Item
• contentWidth : real
• contentX : real
• contentY : real
• dragging : bool
• draggingHorizontally : bool
• draggingVertically : bool
• flickDeceleration : real
• flickableDirection : enumeration
• flicking : bool
• flickingHorizontally : bool
• flickingVertically : bool
• horizontalOvershoot : real
• horizontalVelocity : real
• interactive : bool
• leftMargin : real
• maximumFlickVelocity : real
• moving : bool
• movingHorizontally : bool
• movingVertically : bool
• originX : real
• originY : real
• pixelAligned : bool
• pressDelay : int
• rebound : Transition
• rightMargin : real
• synchronousDrag : bool
• topMargin : real
• verticalOvershoot : real
• verticalVelocity : real
• visibleArea
  • visibleArea.heightRatio : real
  • visibleArea.widthRatio : real
  • visibleArea.xPosition : real
  • visibleArea.yPosition : real

信号

• dragEnded()
• dragStarted()
• flickEnded()
• flickStarted()
• movementEnded()
• movementStarted()

方法

• void cancelFlick()
• void flick(qreal xVelocity, qreal yVelocity)
• void flickTo(point position) (since 6.11)
• void flickToChild(QQuickItem *child, PositionMode mode, point offset) (since 6.11)
• void positionViewAtChild(QQuickItem *child, PositionMode mode, point offset) (since 6.11)
• void resizeContent(real width, real height, point center)
• void returnToBounds()

詳細な説明

Flickable アイテムは、その子要素をドラッグやフリック操作が可能な面に配置し、子要素の表示をスクロールさせます。この動作は、ListView やGridView など、多数の子要素を表示するように設計されたアイテムの基礎となっています。

従来のユーザーインターフェースでは、スクロールバーや矢印ボタンなどの標準的なコントロールを使用してビューをスクロールできます。状況によっては、マウスボタンを押したままカーソルを動かすことで、ビューを直接ドラッグすることも可能です。 タッチベースのユーザーインターフェースでは、このドラッグ操作にフリック操作が組み合わされることが多く、ユーザーがビューへのタッチを停止した後もスクロールが継続します。

Flickableは、そのコンテンツを自動的にクリップしません。フルスクリーンアイテムとして使用しない場合は、clip プロパティをtrueに設定することを検討してください。

使用例

次の例は、大きな画像の一部を表示する小さなビューを示しています。ユーザーは、画像をドラッグまたはフリックして、画像のさまざまな部分を表示することができます。

import QtQuick

Flickable {
    width: 200; height: 200
    contentWidth: image.width; contentHeight: image.height

    Image { id: image; source: "bigImage.png" }
}

Flickableの子として宣言されたアイテムは、自動的にそのFlickableのcontentItem に親付けされます。Flickableの子に対して操作を行う際は、この点を考慮する必要があります。通常、関連するのはcontentItem の子です。例えば、Flickableに追加されたアイテムの境界は、次のようにして取得できます。contentItem.childrenRect

contentX および contentY の例

以下の画像は、Flickableがさまざまな方向にフリックされた際の様子と、その結果得られるcontentX およびcontentY の値を示しています。青い四角形はFlickableのコンテンツを表し、黒い枠はFlickableの境界を表しています。

制限事項

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

acceptedButtons : flags [since 6.9]

この「Flickable」をドラッグしてスクロールするために使用できるマウスボタンです。

デフォルトでは、このプロパティはQt.LeftButton に設定されており、以前のQtバージョンと同じ動作となります。しかし、ほとんどのユーザーインターフェースにおいて、この動作は予想外のものとなります。ユーザーは、フリック操作はタッチスクリーン上でのみ行い、マウスやタッチパッドでのスクロールにはマウスホイール、タッチパッドのジェスチャ、またはスクロールバーを使用することを期待しています。ドラッグを無効にするには、Qt.NoButton に設定してください。

このプロパティには、マウスボタンの「OR」組み合わせを設定することができ、他のボタンからのイベントは無視されます。

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

フリック可能なビューが、それぞれ先頭または末尾に配置されている場合、これらのプロパティはtrueとなります。

これらのプロパティは、コンテンツの周囲の余白を指定します。このスペースは、contentWidth およびcontentHeight に加えて確保されます。

boundsBehavior : enumeration

このプロパティは、サーフェスが Flickable の境界の外までドラッグできるか、またはフリック操作時に Flickable の境界を越えてしまうかどうかを指定します。

boundsMovement がFlickable.FollowBoundsBehavior に設定されている場合、Flickable.StopAtBounds 以外の値を設定すると、ビューの端が物理的な境界線というよりは、ソフトな境界であるかのような感覚が生まれます。

boundsBehavior には、以下のいずれかを指定できます。

• Flickable.StopAtBounds - コンテンツはフリック可能な領域の境界を越えてドラッグできず、フリック操作も境界を越えて進みません。
• Flickable.DragOverBounds - コンテンツは Flickable の境界を越えてドラッグできますが、フリック操作は境界を越えて進みません。
• Flickable.OvershootBounds - フリック操作時にコンテンツが境界を越えても構いませんが、Flickableの境界の外へコンテンツをドラッグすることはできません。（QtQuick 2.5 のため）
• Flickable.DragAndOvershootBounds（デフォルト） - コンテンツは Flickable の境界の外までドラッグでき、フリック操作時に境界を越えることができます。

horizontalOvershoot 、verticalOvershoot 、およびboundsMovementも参照してください 。

boundsMovement : enumeration

このプロパティは、フリック可能な要素が、ビューの端を物理的な明確な境界ではなく、柔らかな境界であるかのように感じさせるかどうかを指定します。

boundsMovement には、以下のいずれかを指定できます。

• Flickable.StopAtBounds - これにより、フリッカブルの境界を越えたドラッグやフリックに対してコンテンツが追従しない、カスタムなエッジ効果を実装できます。horizontalOvershoot およびverticalOvershoot の値を活用することで、カスタムなエッジ効果を実装できます。
• Flickable.FollowBoundsBehavior（デフォルト） - コンテンツがフリッカブルの境界を越えてドラッグやフリックに追従するかどうかは、boundsBehavior によって決定されます。

次の例では、コンテンツを境界内に保持し、水平方向の境界を越えてフリックした際にフリップ効果を適用しています：

Flickable {
    id: flickable
    boundsMovement: Flickable.StopAtBounds
    boundsBehavior: Flickable.DragAndOvershootBounds
    transform: Rotation {
        axis { x: 0; y: 1; z: 0 }
        origin.x: flickable.width / 2
        origin.y: flickable.height / 2
        angle: Math.min(30, Math.max(-30, flickable.horizontalOvershoot))
    }
}

次の例では、コンテンツを境界内に保持し、代わりに垂直方向の境界を越えてドラッグされた際に不透明度変更効果を適用しています：

Flickable {
    boundsMovement: Flickable.StopAtBounds
    boundsBehavior: Flickable.DragOverBounds
    opacity: Math.max(0.5, 1.0 - Math.abs(verticalOvershoot) / height)
}

boundsBehavior 、verticalOvershoot 、およびhorizontalOvershootも参照してください 。

コンテンツ（Flickableによって制御される領域）の寸法。通常、これはFlickable内に配置されたアイテムの合計サイズに設定する必要があります。

以下のコードスニペットは、Flickableのアイテム自体よりも大きな画像を表示するために、これらのプロパティがどのように使用されるかを示しています：

import QtQuick

Flickable {
    width: 200; height: 200
    contentWidth: image.width; contentHeight: image.height

    Image { id: image; source: "bigImage.png" }
}

場合によっては、contentItem のchildrenRect.width およびchildrenRect.height プロパティに基づいて、コンテンツの寸法を自動的に設定できます。たとえば、前のスニペットは次のように書き換えることができます：

contentWidth: contentItem.childrenRect.width; contentHeight: contentItem.childrenRect.height

ただし、これは childrenRect の原点が (0, 0) であることを前提としています。

contentItem : Item [read-only]

Flickable内で移動対象となるアイテムを格納する内部アイテム。

Flickableの子として宣言されたアイテムは、自動的にそのFlickableのcontentItemの子として設定されます。

動的に作成されたアイテムは、明示的にcontentItem の子として設定する必要があります：

Flickable {
    id: myFlickable
    function addItem(file) {
        var component = Qt.createComponent(file)
        component.createObject(myFlickable.contentItem);
    }
}

これらのプロパティには、Flickableの左上隅にある現在の表面座標が格納されています。たとえば、画像を100ピクセル上にフリックすると、contentY の値が100増加します。

Examples of contentX and contentY 、originX 、およびoriginYも参照してください 。

これらのプロパティは、ユーザーがビューをドラッグしたことにより、ビューが現在、水平方向、垂直方向、あるいはその両方向に動いているかどうかを表します。

flickDeceleration : real

このプロパティは、フリックの減速率を指定します。数値が大きいほど、ユーザーがタッチ操作でフリックを停止した際の減速が速くなります。例えば、0.0001 はほぼ「摩擦がない」状態であり、10000 はかなり「粘り気がある」ように感じられます。

デフォルト値はプラットフォームによって異なります。0 以下の値は指定できません。

flickableDirection : enumeration

このプロパティは、ビューをどの方向にフリックできるかを決定します。

• Flickable.AutoFlickDirection（デフォルト） -contentHeightがFlickableの高さと等しくない場合、垂直方向のフリックを許可します。contentWidthがFlickableの幅と等しくない場合、水平方向のフリックを許可します。
• Flickable.AutoFlickIfNeeded -contentHeightがFlickableの高さより大きい場合、垂直方向のフリックを許可します。contentWidthがFlickableの幅より大きい場合、水平方向のフリックを許可します。（QtQuick 2.7 以降）
• Flickable.HorizontalFlick - 水平方向のフリックを許可します。
• Flickable.VerticalFlick - 垂直方向のフリックを許可します。
• Flickable.HorizontalAndVerticalFlick - 両方向へのフリックを許可します。

これらのプロパティは、ユーザーがビューをフリックしたことにより、ビューが現在、水平方向、垂直方向、あるいはその両方向に動いているかどうかを表します。

horizontalOvershoot : real [read-only]

このプロパティは、水平方向のオーバーシュート、すなわち、コンテンツがフリック可能な領域の境界を越えてドラッグまたはフリックされた水平方向の距離を保持します。値は、コンテンツが先頭を超えてドラッグまたはフリックされた場合は負となり、末尾を超えてドラッグまたはフリックされた場合は正となります。それ以外の場合は、0.0 となります。

ドラッグおよび／またはフリックについてこの値が報告されるかどうかは、boundsBehavior によって決定されます。boundsMovement がFlickable.StopAtBounds に設定されている場合でも、オーバーシュート距離は報告されます。

verticalOvershoot 、boundsBehavior 、およびboundsMovementも参照してください 。

x軸およびy軸に沿った瞬時速度（単位：ピクセル/秒）。

報告される速度は、出力の乱れを防ぐために平滑化されています。

なお、コンテンツサイズが大きいビュー（ビューサイズの10倍以上）の場合、素早く連続してフリック操作を複数回行うと、フリックの速度がタッチの速度を上回る可能性があります。これにより、ユーザーは大きなコンテンツ内をより速くフリックして移動することができます。

interactive : bool

このプロパティは、ユーザーが Flickable と操作できるかどうかを指定します。操作不可の Flickable では、ユーザーはドラッグやフリックを行うことができません。

デフォルトでは、このプロパティは true です。

このプロパティは、フリック操作を一時的に無効にする場合に役立ちます。これにより、Flickableの子要素との特別な操作が可能になります。たとえば、Flickableの子要素であるポップアップダイアログをスクロールしている間、Flickableのマップを固定したい場合などが挙げられます。

maximumFlickVelocity : real

このプロパティは、ユーザーがビューをフリックできる最大速度（ピクセル/秒）を保持します。

デフォルト値はプラットフォームによって異なります。

これらのプロパティは、ユーザーがビューをドラッグまたはフリックしたことにより、ビューが現在、水平方向、垂直方向、あるいはその両方向に動いているかどうかを表します。

これらのプロパティは、コンテンツの原点を保持します。この値は、レイアウトの方向にかかわらず、常にコンテンツの左上隅の位置を指します。

通常は (0,0) ですが、ListView およびGridView では、デリゲートのサイズの変動や、表示領域外での項目の挿入・削除により、原点が任意の位置になる場合があります。

「 contentX 」および「contentY 」も参照してください 。

pixelAligned : bool

このプロパティは、contentX およびcontentY の配置を、ピクセル (true) またはサブピクセル (false) に設定します。

静止コンテンツや、1ピクセル幅の線、テキスト、ベクターグラフィックスなど、エッジのコントラストが高い動的コンテンツを最適化するには、`pixelAligned`を有効にしてください。アニメーションの品質を最適化する場合は、`pixelAligned`を無効にしてください。

デフォルトはfalse です。

pressDelay : int

このプロパティは、Flickableの子要素へのタップイベントの配信を遅延させる時間（ms）を保持します。フリック操作の前にタップイベントが配信されると望ましくない結果が生じる場合に、この設定が役立ちます。

遅延時間が経過する前に Flickable がドラッグまたはフリックされた場合、押下イベントは送信されません。タイムアウト内にボタンが離された場合、押下イベントと離しイベントの両方が送信されます。

なお、pressDelay が設定されているネストされた Flickable の場合、外側の Flickable の pressDelay は、最も内側の Flickable によって上書きされます。ドラッグがプラットフォームのドラッグ閾値を超えた場合、このプロパティの設定にかかわらず、押下イベントが配信されます。

QStyleHintsも参照してください 。

rebound : Transition

これは、コンテンツビューがフリック可能な領域の境界にスナップバックする際に適用されるトランジションを保持します。このトランジションは、ビューがコンテンツ領域の端を越えてフリックまたはドラッグされたとき、あるいはreturnToBounds()が呼び出されたときにトリガーされます。

import QtQuick 2.0

Flickable {
    width: 150; height: 150
    contentWidth: 300; contentHeight: 300

    rebound: Transition {
        NumberAnimation {
            properties: "x,y"
            duration: 1000
            easing.type: Easing.OutBounce
        }
    }

    Rectangle {
        width: 300; height: 300
        gradient: Gradient {
            GradientStop { position: 0.0; color: "lightsteelblue" }
            GradientStop { position: 1.0; color: "blue" }
        }
    }
}

上記のビューが境界を超えてフリックされると、指定されたトランジションを使用して境界内に戻ります。

このプロパティが設定されていない場合は、デフォルトのアニメーションが適用されます。

synchronousDrag : bool

このプロパティが true に設定されている場合、マウスやタッチポイントがコンテンツのドラッグを開始するのに十分な距離まで移動すると、コンテンツがジャンプします。これにより、押下時にカーソルやタッチポイントの下にあったコンテンツのピクセルが、その位置の下に留まるようになります。

デフォルトはfalse です。これにより、ドラッグ開始時にドラッグ距離の一部が「失われる」という代償を払う代わりに、よりスムーズな操作感（ジャンプなし）が得られます。

verticalOvershoot : real [read-only]

このプロパティは、垂直方向のオーバーシュート、つまりコンテンツがフリッカブルの境界を超えてドラッグまたはフリックされた垂直距離を保持します。値は、コンテンツが先頭を超えてドラッグまたはフリックされた場合は負となり、末尾を超えてドラッグまたはフリックされた場合は正となります。それ以外の場合は、0.0 となります。

ドラッグおよび／またはフリックについてこの値が報告されるかどうかは、boundsBehavior によって決定されます。boundsMovement がFlickable.StopAtBounds に設定されている場合でも、オーバーシュート距離は報告されます。

horizontalOvershoot 、boundsBehavior 、およびboundsMovementも参照してください 。

visibleArea group

これらのプロパティは、現在表示されている領域の位置とサイズを表します。サイズは、現在表示されている全画面に対する割合として定義され、0.0～1.0の範囲にスケーリングされます。 ページの位置は通常、0.0（開始位置）から1.0からサイズ比率を引いた値（終了位置）の範囲にあります。つまり、yPosition は0.0から1.0 -heightRatio の範囲にあります。 ただし、コンテンツが通常の範囲外にドラッグされる可能性があり、その結果、ページ位置も通常の範囲外になることがあります。

これらのプロパティは、通常、スクロールバーの描画に使用されます。例：

Rectangle {
    width: 200; height: 200

    Flickable {
        id: flickable
        ...
    }

    Rectangle {
        id: scrollbar
        anchors.right: flickable.right
        y: flickable.visibleArea.yPosition * flickable.height
        width: 10
        height: flickable.visibleArea.heightRatio * flickable.height
        color: "black"
    }
}

Signal ドキュメント

dragEnded()

このシグナルは、ユーザーがビューのドラッグを停止したときに発生します。

タッチまたはマウスボタンが離された時点で、ドラッグの速度が十分であれば、フリックが開始されます。

dragStarted()

このシグナルは、ユーザーの操作によってビューのドラッグが開始されたときに発火します。

flickEnded()

このシグナルは、フリックまたは一連のフリックの後、ビューの動きが止まったときに発火します。

flickStarted()

このシグナルは、ビューがフリックされたときに発信されます。フリックは、マウスやタッチが移動中に離された時点から始まります。

movementEnded()

このシグナルは、ユーザーの操作や生成されたflick()によってビューの移動が停止したときに発火します。フリックが有効だった場合、フリックが停止するとこのシグナルが発火します。フリックが有効でなかった場合、ユーザーがドラッグを停止したとき（つまり、マウスやタッチが離されたとき）にこのシグナルが発火します。

movementStarted()

このシグナルは、ユーザーの操作や、生成されたflick() によってビューが移動し始めたときに発火します。

メソッドのドキュメント

void cancelFlick()

現在のフリックアニメーションをキャンセルします。

void flick(qreal xVelocity, qreal yVelocity)

xVelocity のピクセル/秒でコンテンツを水平方向に、yVelocity のピクセル/秒で垂直方向にフリックします。

このメソッドを呼び出すと、実際のタッチスクリーンでのフリック操作と同様に、対応する移動およびフリックに関するプロパティとシグナルが更新されます。

[since 6.11] void flickTo(point position)

フリック可能なオブジェクトをposition にフリックします。

フリック可能なオブジェクトをフリックした際に、その先頭または末尾に空白が表示される場合、その境界でフリックは停止します。

このメソッドは Qt 6.11 で導入されました。

[since 6.11] void flickToChild(QQuickItem *child, PositionMode mode, point offset)

「フリック可能オブジェクト」をフリックし、child のアイテム（子要素である場合）がmode で指定された位置に来るようにします。mode には、以下の項目の論理和（OR）を指定できます：

垂直方向の配置が指定されていない場合、垂直方向のフリックは無視されます。水平方向の配置についても同様です。

オプションで、offset を指定することで、目標の位置からさらに指定したピクセル数だけフリックを延長することができます。

子アイテムでフリック操作を行った結果、フリック可能な領域の先頭または末尾に空白が表示される場合、フリック操作は境界で停止します。

import QtQuick
import QtQuick.Controls
import QtQuick.Window

Flickable {
    id: flickable

    width: 200
    height: 200
    contentWidth: width
    contentHeight: column.height

    // Will flick to the beginning of the activeFocusItem every time it changes
    property Item activeFocusItem: Window.activeFocusItem
    onActiveFocusItemChanged: flickable.flickToChild(activeFocusItem, Flickable.AlignTop)

    Column {
        id: column

        spacing: 10

        Repeater {
            model: 10
            TextArea {}
        }
    }
}

このメソッドは Qt 6.11 で導入されました。

[since 6.11] void positionViewAtChild(QQuickItem *child, PositionMode mode, point offset)

contentX およびcontentY を、child の項目（子要素である場合）がmode で指定された位置に来るように配置します。mode は、以下の項目の論理和（OR）で構成される場合があります：

垂直方向の配置が指定されていない場合、垂直方向の位置指定は無視されます。水平方向の配置についても同様です。

オプションで、offset を指定することで、contentXおよび contentYをターゲットの位置からさらに指定したピクセル数だけ移動させることができます。

子アイテムの位置に合わせてフリッカブルを配置すると、フリッカブルの先頭または末尾に空白が表示される場合、フリッカブルは境界に配置されます。

import QtQuick
import QtQuick.Controls
import QtQuick.Window

Flickable {
    id: flickable

    width: 200
    height: 200
    contentWidth: width
    contentHeight: column.height

    // Will center activeFocusItem in the Flickable every time it changes
    property Item activeFocusItem: Window.activeFocusItem
    onActiveFocusItemChanged: flickable.positionViewAtChild(activeFocusItem, Flickable.AlignCenter)

    Column {
        id: column

        spacing: 10

        Repeater {
            model: 10
            TextArea {}
        }
    }
}

このメソッドは Qt 6.11 で導入されました。

void resizeContent(real width, real height, point center)

コンテンツのサイズをwidth ×height 、約center に調整します。

これは Flickable のコンテンツを拡大縮小するものではなく、contentWidth とcontentHeight のサイズを変更するだけです。

コンテンツのサイズを変更すると、コンテンツがFlickableの境界外に出てしまう可能性があります。returnToBounds()を呼び出すと、コンテンツが許容範囲内に戻ります。

void returnToBounds()

コンテンツが法的な範囲内であることを保証します。

コンテンツを手動で配置した後、そのコンテンツが法的な範囲内にあることを確認するために、この処理が呼び出される場合があります。