QMLのコントロール - Positionerアイテムのソースを表示

== 概要 ==
Positionerアイテムとは、宣言型UIのアイテムの位置を管理するコンテナアイテムである。<br>
多くのアイテムを通常のレイアウトに配置する必要がある場合に、容易に設計することができる。<br>
<br>
Qtの標準的なウィジェットで使用されているレイアウトマネージャと同じように動作するが、それ自体がコンテナであることが異なる。<br>
<br>
PositionerアイテムはQt Quick Layoutsに含まれており、UI上のアイテムの位置とサイズの両方を管理しており、サイズ変更可能なデザインに使用する。<br>
<br><br>

== Positionerアイテムの種類 ==
下表に、標準的なPositionerアイテムを示す。<br>
<center>
{| class="wikitable" | style="background-color:#fefefe;"
|-
! style="background-color:#66CCFF;" | Positionerアイテム名 
! style="background-color:#66CCFF;" | 説明
|-
| [[QMLのコントロール - RowとRowLayout|Row]] || 行の中の子を一列に配置する。
|-
| [[QMLのコントロール - ColumnとColumnLayout|Column]] || 列の中に子を配置する。
|-
| [[QMLのコントロール - GridとGridLayout|Grid]] || グリッドの中の子を配置する。
|-
| [[QMLのコントロール - Flow|Flow]] || 必要に応じて折り返しながら、子を横に並べて配置する。
|-
| [[QMLのコントロール - Positionerアイテム#LayoutMirroringプロパティ|LayoutMirroring]] || レイアウトの動作をミラーリングするためのプロパティ。
|-
| [[QMLのコントロール - Positioner|Positioner]] || Positionerアイテム内の子アイテムがどこに存在するかの詳細を含むプロパティ。
|}
</center>
<br><br>

== Row ==
<code>Row</code>は、アイテムを水平方向に並べるために使用する。<br>
<br>
以下の例では、行アイテムを使用して、3つの丸みを帯びた<code>Rectangle</code>を、外側の<code>Rectangle</code>で定義された領域に配置している。<br>
<code>spacing</code>プロパティは、<code>Rectangle</code>の間にわずかなスペースを空けるように設定している。<br>
<br>
親アイテムの<code>Rectangle</code>が十分な大きさであることを確認して、水平方向に中央に配置された<code>Row</code>の端にスペースを空けている。<br>
[[ファイル:QML Positioner Item 1.png|フレームなし|中央]]
 <syntaxhighlight lang="qml">
 import QtQuick 2.0
 
 Rectangle {
    width: 320
    height: 110
    color: "#c0c0c0"
 
    Row {
       anchors.horizontalCenter: parent.horizontalCenter
       anchors.verticalCenter: parent.verticalCenter

       spacing: 5

       Rectangle {
          width: 100
          height: 100
          radius: 20.0
          color: "#024c1c"
       }
 
       Rectangle {
          width: 100
          height: 100
          radius: 20.0
          color: "#42a51c"
       }
 
       Rectangle {
          width: 100
          height: 100
          radius: 20.0
          color: "white"
       }
    }
 }
 </syntaxhighlight>
<br><br>

== Column ==
<code>Column</code>は、アイテムを垂直に並べるために使用する。<br>
<br>
以下の例では、Columnを使用して、外側のアイテムで定義された領域に3つのRectangleを配置している。<br>
spacingプロパティは、四角形の間にわずかなスペースを含むように設定している。<br>
<br>
なお、<code>Column</code>は<code>Item</code>を継承しているため、背景色が必要な場合は、親の<code>Rectangle</code>にプロパティを追加する必要がある。<br>
[[ファイル:QML Positioner Item 2.png|フレームなし|中央]]
 <syntaxhighlight lang="qml">
 import QtQuick 2.0
 
 Item {
    width: 310; height: 170
 
    Column {
       anchors.horizontalCenter: parent.horizontalCenter
       anchors.verticalCenter: parent.verticalCenter
 
       spacing: 5
 
       Rectangle {
          color: "lightblue"
          radius: 10.0
          width: 300
          height: 50
 
          Text {
             anchors.centerIn: parent
             font.pointSize: 24
             text: "Books"
          }
       }
 
       Rectangle {
          color: "gold"
          radius: 10.0
          width: 300
          height: 50
 
          Text {
             anchors.centerIn: parent
             font.pointSize: 24
             text: "Music"
          }
       }
 
       Rectangle {
          color: "lightgreen"
          radius: 10.0
          width: 300
          height: 50
 
          Text {
             anchors.centerIn: parent
             font.pointSize: 24
             text: "Movies"
          }
       }
    }
 }
 </syntaxhighlight>
<br><br>

== Grid ==
<code>Grid</code>は、子アイテムを格子状またはテーブル状に配置する。<br>
<br>
以下の例では、<code>Grid</code>を使用して、4つの<code>Rectangle</code>を2×2の格子状に配置している。<br>
他の<code>Positioner</code>アイテムと同様、アイテム間の間隔は、<code>spacing</code>プロパティを使用して設定できる。<br>
アイテム間に挿入される水平方向の間隔と垂直方向の間隔には違いが無いため、追加のスペースは子アイテム自体の中に追加する必要がある。<br>
<br>
格子状内の空のセルは、<code>Grid</code>内の適切な場所にプレースホルダアイテムを定義して作成する必要がある。<br>
[[ファイル:QML Positioner Item 3.png|フレームなし|中央]]
 <syntaxhighlight lang="qml">
 import QtQuick 2.0
 
 Rectangle {
    width: 112
    height: 112
    color: "#303030"
 
    Grid {
       anchors.horizontalCenter: parent.horizontalCenter
       anchors.verticalCenter: parent.verticalCenter
       columns: 2
       spacing: 6
 
       Rectangle {
          color: "#aa6666"
          width: 50
          height: 50
       }
 
       Rectangle {
          color: "#aaaa66"
          width: 50
          height: 50
       }
 
       Rectangle {
          color: "#9999aa"
          width: 50
          height: 50
       }
 
       Rectangle {
          color: "#6666aa"
          width: 50
          height: 50
       }
    }
 }
 </syntaxhighlight>
<br><br>

== Flow ==
<code>Flow</code>は、ページ上に単語のようなアイテムを、重ならないように行や列で配置する。<br>
<br>
これは、<code>Grid</code>のように、1つの軸（短軸）に沿ってアイテムを並べて、もう1つの軸（長軸）に沿ってアイテムを隣り合わせに並べる。<br>
並べる方向とアイテム間の間隔は、<code>flow</code>と<code>spacing</code>プロパティで制御される。<br>
また、<code>Grid</code>と同様に、アイテム間やアイテムの行間の間隔を独立して制御することはできない。<br>
<br>
以下に、<code>Flow</code>と<code>Grid</code>の主な違いを示す。<br>
* <code>Flow</code>内のアイテムは短軸のスペースが無くなると折り返される。
* アイテムのサイズが均一でない場合、1行のアイテムが他の行のアイテムと揃わないことがある。
<br>
以下の例では、<code>Flow</code>内に<code>Text</code>の子アイテムがいくつか作成している。<br>
これらは、下図で示したものと同様の方法で配置されている。<br>
[[ファイル:QML Positioner Item 4.png|フレームなし|中央]]
 <syntaxhighlight lang="qml">
 import QtQuick 2.0
 
 Rectangle {
    color: "lightblue"
    width: 300
    height: 200
 
    Flow {
       anchors.fill: parent
       anchors.margins: 4
       spacing: 10
 
       Text {
          text: "Text"
          font.pixelSize: 40
       }
 
       Text {
          text: "items"
          font.pixelSize: 40
       }
 
       Text {
          text: "flowing"
          font.pixelSize: 40
       }
 
       Text {
          text: "inside"
          font.pixelSize: 40
       }
 
       Text {
          text: "a"
          font.pixelSize: 40
       }
 
       Text {
          text: "Flow"
          font.pixelSize: 40
       }
 
       Text {
          text: "item"
          font.pixelSize: 40
       }
    }
 }
 </syntaxhighlight>
<br><br>

== LayoutMirroringプロパティ ==
LayoutMirroringとは、レイアウトの動作をミラーリングするためのプロパティである。<br>
<br>
==== 専用プロパティ ====
ミラーリングは視覚的な変化である。<br>
<br>
<code>LayoutMirroring</code>プロパティは、アイテムのアンカー、<code>Row</code>や<code>Grid</code>等のPositionerや<code>GridView</code>や<code>ListView</code>等のViewを水平方向にミラーリング(反転)する。<br>
(左のアンカーが右のアンカーになる等)<br>
<br>
ミラーリングは、<code>enabled</code>プロパティを<code>true</code>に設定することにより、アイテムに対して有効になる。<br>
<br>
既定値では、ミラーリングはアイテム自身にのみ影響する。<br>
<code>childrenInherit</code>プロパティを<code>true</code>に設定することにより、ミラーリングの動作が全ての子アイテムにも継承される。<br>
<br>
<u>※注意</u><br>
<u>Qt 5.8以降、<code>LayoutMirroring</code>は<code>Window</code>に対しても使用できるようになった。</u><br>
<u><code>LayoutMirroring</code>プロパティを、<code>Window</code>の<code>contentItem</code>にアタッチするのと同様に使用できる。</u><br>
<br>
* childrenInherit
*: 値 : bool (既定値 : false)
*: アイテムの<code>LayoutMirroring.enabled</code>の値が、その子アイテムたちに継承されるかどうかを設定する。
*: <br>
* enabled
*: 値 : bool (既定値 : false)
*: アイテムのレイアウトが水平方向にミラーリングされるかどうかを設定する。
*: 水平方向にtrueを設定する場合、左のアンカーが右に、右のアンカーが左になるようにアンカーの設定が反転する。
*: <code>Row</code>や<code>Grid</code>等のPositionerや<code>GridView</code>や<code>ListView</code>等のViewでは、アイテムの水平方向もミラーリングされる。
<br>
==== サンプルコード ====
以下の例では、ミラーリングの動作を示しており、<code>Row</code>は親の左に固定されるように指定している。<br>
ただし、ミラーリングが有効になっているため、アンカーは水平方向に反転して、右に固定されている。<br>
<br>
また、既定値では<code>Row</code>内のアイテムは左から右に配置されるが、アイテムの番号や不透明度から分かるように、右から左に配置されている。<br>
[[ファイル:QML Positioner Item 5.png|フレームなし|中央]]
 <syntaxhighlight lang="qml">
 import QtQuick 2.0
 
 Rectangle {
    LayoutMirroring.enabled: true
    LayoutMirroring.childrenInherit: true
 
    width: 300
    height: 50
    color: "yellow"
    border.width: 1
 
    Row {
       anchors {
          left: parent.left
          margins: 5
       }
       y: 5
       spacing: 5
 
       Repeater {
          model: 5
 
          Rectangle {
             color: "red"
             opacity: (5 - index) / 5
             width: 40; height: 40
 
             Text {
                text: index + 1
                anchors.centerIn: parent
             }
          }
       }
    }
 }
 </syntaxhighlight>
<br>
<code>LayoutMirroring</code>は、異なる言語圏をターゲットとするソフトウェアにおいて、左から右へのレイアウトと右から左へのレイアウトの両方をサポートする必要がある場合に便利である。<br>
<br>
<code>childrenInherit</code>プロパティを使用する場合、ソフトウェア内の全てのアイテムに対してレイアウト設定を手動で行うことなく、<code>LayoutMirroring</code>を適用することができる。<br>
<br>
ただし、ミラーリングは、アイテムのx座標の値で定義される位置関係には影響しないため、<br>
ミラーリングを有効にしても、希望のレイアウト方向に対応するためには、レイアウトの修正が必要になることに注意する。<br>
<br>
また、ミラーリングが望ましい動作ではない場合や既に子アイテムが他の方法でミラーリングを行っている場合は、<br>
個々の子アイテムのミラーリングを無効（各アイテムに対して、<code>LayoutMirroring.enabled</code>を<code>false</code>)に設定する必要があるかもしれない。<br>
<br>
ソフトウェアの既定のレイアウト方向に基づいて変更するには、以下を使用する。<br>
 <syntaxhighlight lang="qml">
 LayoutMirroring.enabled: Qt.application.layoutDirection === Qt.RightToLeft
 </syntaxhighlight>
<br>
レイアウト方向の変更において、<code>LayoutMirroring</code>やその他の関連機能の詳細は、[[QMLのコントロール - レイアウト方向の変更]]を参照すること。<br>
<br><br>

__FORCETOC__
[[カテゴリ:Qt]]