BorderImage QML Type

画像に基づいて枠線を描画します。詳細...

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

プロパティ

• asynchronous : bool
• border
  • border.bottom : int
  • border.left : int
  • border.right : int
  • border.top : int
• cache : bool
• currentFrame : int
• frameCount : int
• horizontalTileMode : enumeration
• mirror : bool
• progress : real
• retainWhileLoading : bool (since 6.8)
• smooth : bool
• source : url
• sourceSize : size
• status : enumeration
• verticalTileMode : enumeration

詳細な説明

BorderImage 型は、各画像の一部を拡大縮小またはタイル状に配置することで、画像から枠線を作成するために使用されます。

BorderImage は、source プロパティで指定されたソース画像を、以下に示すように 9 つの領域に分割します。

画像が拡大・縮小される際、ソース画像の各領域は、次のように拡大・縮小またはタイル状に配置され、表示されるボーダー画像が生成されます：

• 隅の部分（領域 1、3、7、9）は、まったくスケーリングされません。
• 領域 2 および 8 は、horizontalTileMode に基づいて拡大縮小されます。
• 領域 4 および 6 は、verticalTileMode に基づいてスケーリングされます。
• 中央（領域 5）は、horizontalTileMode およびverticalTileMode の両方に従ってスケーリングされます。

画像の各領域は、border プロパティグループを使用して定義されます。このプロパティグループは、ソース画像の各エッジから、境界線として使用する距離を指定します。

使用例

以下の例は、さまざまなモードが画像に与える影響を示しています。前述のように、画像のさまざまな領域を示すために、ガイドラインが画像上に重ねられています。

比較のために、単純な Image アイテムを使用して、拡大・縮小されていない画像も表示しています。ここでは、BorderImage を使用して画像をどのように分割したいかを示すために、線を重ねて表示しています。

Image {
    source: "pics/borderframe.png"
    anchors.centerIn: parent
}

しかし、BorderImage を使用して画像を表示する場合、border プロパティによって、拡大・縮小されていない隅の部分の内側に収まる画像の領域と、水平および垂直方向に引き伸ばされる領域が決定されます。 これにより、元の画像よりも大きなサイズを設定することが可能です。horizontalTileMode プロパティがBorderImage.Stretch に設定されているため、領域2および8の画像部分は水平方向に伸縮します。また、verticalTileMode プロパティがBorderImage.Stretch に設定されているため、領域4および6の画像部分は垂直方向に伸縮します：

BorderImage {
    anchors { fill: parent; margins: 1 }
    border { left: 30; top: 30; right: 30; bottom: 30 }
    horizontalTileMode: BorderImage.Stretch
    verticalTileMode: BorderImage.Stretch
    source: "pics/borderframe.png"
}

ここでも、画像を表示するために大きなBorderImageが使用されています。horizontalTileMode プロパティがBorderImage.Repeat に設定されているため、領域2および8にある画像の部分は、アイテムの上部と下部のスペースを埋めるようにタイル状に配置されます。 同様に、verticalTileMode プロパティをBorderImage.Repeat に設定すると、領域4および6の画像部分がタイル状に並べられ、アイテムの左右のスペースを埋めるようになります：

BorderImage {
    anchors { fill: parent; margins: 1 }
    border { left: 30; top: 30; right: 30; bottom: 30 }
    horizontalTileMode: BorderImage.Repeat
    verticalTileMode: BorderImage.Repeat
    source: "pics/borderframe.png"
}

状況によっては、領域 2 および 8 の幅が、ソース画像の対応する領域の幅の正確な倍数ではない場合があります。同様に、領域 4 および 6 の高さが、対応する領域の高さの正確な倍数ではない場合もあります。BorderImage.Round モードを使用すると、整数個のタイルが選択され、サイズに合わせて縮小されます:

BorderImage {
    anchors { fill: parent; margins: 6 }
    border { left: 30; top: 30; right: 30; bottom: 30 }
    horizontalTileMode: BorderImage.Round
    verticalTileMode: BorderImage.Round
    source: "pics/borderframe.png"
}

『Qt Quick Examples - Image Elements』の「Border Image」の例では、BorderImage を使用して長方形のアイテムに影の効果をシミュレートする方法を示しています。

画像の読み込み

元の保存場所によっては、ソース画像が即座に読み込まれない場合があります。読み込みの進捗状況は、progress プロパティで確認できます。

「 Image 」および「AnimatedImage 」も参照してください 。

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

asynchronous : bool

ローカルファイルシステム上の画像を、別のスレッドで非同期に読み込むように指定します。デフォルト値は false であり、この場合、画像の読み込み中はユーザーインターフェースのスレッドがブロックされます。asynchronous を true に設定すると、画像を即座に表示させることよりも、ユーザーインターフェースの応答性を維持することが望ましい場合に役立ちます。

なお、このプロパティはローカルファイルシステムから読み込まれる画像に対してのみ有効です。ネットワークリソース（HTTPなど）経由で読み込まれる画像は、常に非同期で読み込まれます。

border group

4本の境界線（横2本、縦2本）により、画像は以下に示すように9つの領域に分割されます。

各境界線（左、右、上、下）は、ソース画像のそれぞれの端からのピクセル単位のオフセットを指定します。デフォルトでは、各境界線の値は0です。

たとえば、次の定義では、下側の境界線を画像の下端から10ピクセル上に設定しています:

BorderImage {
    border.bottom: 10
    // ...
}

境界線は、.sci file を使用して指定することもできます。

cache : bool

画像をキャッシュするかどうかを指定します。デフォルト値は true です。cache を false に設定すると、大きな画像を扱う際に、小さな「UI 要素」の画像を優先してキャッシュされるのを防ぐのに役立ちます。

currentFrame 現在表示されているフレームです。デフォルトは0 です。画像に複数のフレームが含まれている場合、0 からframeCount - 1 までの範囲の数値を設定することで、別のフレームを表示することができます。

frameCount は、画像に含まれるフレームの数です。ほとんどの画像にはフレームが1つしか含まれていません。

このプロパティは、ボーダー画像の中央部分をどのように繰り返すか、または伸縮させるかを指定します。

各プロパティのデフォルトのタイルモードは、BorderImage.Stretch です。

mirror : bool

このプロパティは、画像を水平反転させるかどうか（実質的に鏡像を表示するかどうか）を指定します。

デフォルト値は false です。

progress : real [read-only]

このプロパティは、画像の読み込み進捗状況を、0.0（読み込みなし）から1.0（完了）まで保持します。

statusも参照してください 。

retainWhileLoading : bool [since 6.8]

このプロパティは、source プロパティが変更され、読み込みが非同期で行われる場合の動作を定義します。これは、asynchronous プロパティがtrue に設定されている場合、または画像がローカルファイルシステム上に存在しない場合に該当します。

retainWhileLoading がfalse （デフォルト）に設定されている場合、古い画像は直ちに破棄され、新しい画像の読み込み中はコンポーネントがクリアされます。true に設定されている場合、古い画像は保持され、新しい画像の準備が整うまで表示されたままになります。

このプロパティを有効にすると、新しい画像の読み込みに時間がかかる場合にもちらつきを防ぐことができます。ただし、新しい画像の読み込み中はダブルバッファリングのために余分なメモリが消費されるという代償が伴います。

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

smooth : bool

このプロパティは、画像の拡大縮小や変形時にスムージング処理が行われるかどうかを指定します。スムージング処理を行うと視覚的な品質は向上しますが、一部のハードウェアでは処理速度が低下する場合があります。画像が本来のサイズで表示される場合、このプロパティは視覚的な効果やパフォーマンスに影響を与えません。

デフォルトでは、このプロパティは true に設定されています。

source : url

このプロパティには、元の画像を参照するURLが格納されます。

BorderImage QtがサポートするあらゆるURLスキームから読み込まれた、Qtがサポートするあらゆる画像形式に対応しています。

このプロパティは、.sci ファイル（QML 独自のテキストベースのフォーマットで、境界線の値、ソース画像、およびタイルのルールをファイル内に直接埋め込むもの）を参照することもできます。.sci ファイルを使用する場合、BorderImage はファイル自体から境界線情報を読み取るため、QML で境界線プロパティを指定する必要はありません。

以下の .sci ファイルは、画像picture.png の各辺の境界線を 10 に設定しています：

border.left: 10
border.top: 10
border.bottom: 10
border.right: 10
source: "picture.png"

URLは絶対パスでも、コンポーネントのURLを基準とした相対パスでも構いません。

QQuickImageProviderも参照してください 。

sourceSize : size [read-only]

このプロパティには、読み込まれた画像の実際の幅と高さが格納されます。

BorderImage では、このプロパティは読み取り専用です。

「Image::sourceSize」も参照してください 。

status : enumeration [read-only]

このプロパティは、画像の読み込み状況を表します。以下のいずれかの値をとります。

progressも参照してください 。