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に追加されたItemsの境界は、次のようになります。contentItem.childrenRect

contentXとcontentYの例

次の画像は、フリッカブルをさまざまな方向にフリックし、contentX とcontentY の値を表示した例です。青い四角はフリッカブルのコンテンツを表し、黒い境界線はフリッカブルの境界線を表しています。

制限事項

プロパティ・ドキュメンテーション

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の境界を越えてドラッグできず、フリックはオーバーシュートしません。
• Flickable.DragOverBounds - コンテンツは Flickable の境界を超えてドラッグできますが、フリックはオーバーシュートしません。
• Flickable.OvershootBounds - フリックしたときにコンテンツが境界をオーバーシュートすることができますが、コンテンツはフリッカブルの境界を超えてドラッグすることはできません。(QtQuick 2.5 以降 )
• Flickable.DragAndOvershootBounds (default) - Flickableの境界を超えてコンテンツをドラッグすることができ、フリックしたときに境界をオーバーシュートすることができます。

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

boundsMovement : enumeration

このプロパティは、flickableが、ビューのエッジが物理的な硬い境界線ではなく、ソフトであるという感覚を与えるかどうかを保持する。

boundsMovement ：

• Flickable.StopAtBounds - これは、コンテンツがflickableの境界を超えてドラッグまたはフリックに追従しないカスタムエッジエフェクトを実装することができます。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 内で移動する Items を含む内部アイテム。

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 のwidthと等しくない場合、水平方向のフリックを許可します。
• Flickable.AutoFlickIfNeeded -contentHeightが Flickable のheightより大きい場合、垂直方向のフリックを許可します。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 マップをフリーズしたい場合などです。

maximumFlickVelocity : real

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

デフォルト値はプラットフォーム依存です。

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

これらのプロパティは、コンテンツの原点を保持する。この値は、レイアウト方向に関係なく、常にコンテンツの左上位置を指す。

これは通常(0,0)ですが、ListView とGridView は、デリゲートサイズのばらつきや、可視領域外でのアイテムの挿入/削除により、任意の原点を持つ可能性があります。

contentX とcontentYも参照してください 。

pixelAligned : bool

このプロパティは、contentX とcontentY のアライメントをピクセル (true) またはサブピクセル (false) に設定します。

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

デフォルトはfalse 。

pressDelay : int

このプロパティは、Flickableの子プロパティへの押下を配信する遅延時間(ms)を保持する。これは、フリック操作の前にプレスに反応することが望ましくない効果をもたらす場合に便利です。

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

ネストされたFlickableでpressDelayが設定されている場合、外側のFlickableのpressDelayは内側のFlickableによってオーバーライドされることに注意してください。ドラッグがプラットフォームのドラッグしきい値を超えた場合、このプロパティに関係なくプレスイベントが配信されます。

QStyleHintsも参照してください 。

rebound : Transition

これは、コンテンツビューがflickableの境界にスナップバックしたときに適用されるトランジションを保持します。トランジションは、ビューがコンテンツ領域の端を越えてフリックまたはドラッグされたとき、または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]

このプロパティは、垂直方向のオーバーシュート、つまり、コンテンツがflickableの境界を越えてドラッグまたはフリックされた垂直方向の距離を保持する。この値は、コンテンツが始点を超えてドラッグまたはフリックされた場合は負、終点を超えた場合は正となり、それ以外の場合は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"
    }
}

シグナル・ドキュメント

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)

mode で指定された位置にchild アイテム（子である場合）が来るように、フリッカブルをフリックする。mode は、以下の or-ed の組み合わせである：

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

オプションで、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-ed の組み合わせとすることができる：

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

オプションで、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 xheight 約center に変更します。

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

コンテンツのサイズを変更すると、コンテンツが Flickable の境界外に配置される場合があります。returnToBounds() を呼び出すと、コンテンツは法的な境界内に戻ります。

void returnToBounds()

コンテンツが法的範囲内にあることを確認する。

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