QMLのコントロール - GridとGridLayout

概要

GridおよびGridLayoutは、見やすいレイアウトを表示するために用意されている。

Grid

専用プロパティ

• layoutDirection

  値 : enumeration型 (既定値 : Qt.LeftToRight)

  このプロパティは、レイアウトの方向を設定する。

  
  

  Qt.LeftToRightは、アイテムは上から下、左から右へと配置される。フローの方向は、Grid.flowプロパティに依存する。

  Qt.RightToLeftは、アイテムは上から下、右から左へと配置される。フローの方向は、Grid.flowプロパティに依存する。

  
  

  Row.layoutDirectionプロパティやFlow.layoutDirectionプロパティも参照すること。

  
  

• effectiveLayoutDirection

  値 : enumeration型

  グリッドの効果的なレイアウト方向を設定する。

  ロケールレイアウトに対してLayoutMirroring.enabledプロパティを使用する場合、グリッドの位置の視覚的なレイアウト方向がミラーリングされる。

  ただし、layoutDirectionプロパティは変更されない。

  
  

  Grid.layoutDirectionプロパティおよびLayoutMirroringプロパティも参照すること。

  
  

• flow

  値 : enumeration型 (既定値 : Grid.LeftToRight)

  レイアウトのフローを設定する。

  
  

  Grid.LeftToRightは、アイテムをlayoutDirectionで隣り合って配置されて、次の行に折り返される。

  Grid.TopToBottomは、アイテムを上から下に向かって隣り合って配置されて、次の列に折り返される。

  
  

• spacing

  値 : qreal型 (既定値 : 0)

  隣り合うアイテムの間を空けるピクセル数を設定する。

  Grid.spacingプロパティも参照すること。

  
  

• rowSpacing

  値 : qreal型 (既定値 : なし)

  行間のピクセル単位の間隔を設定する。

  このプロパティが設定されていない場合、行の間隔には、spacingプロパティが使用される。

  
  

  このプロパティは、Qt 5.0で導入された。

  
  

• columnSpacing

  値 : qreal型 (既定値 : なし)

  列間のピクセル単位の間隔を設定する。

  このプロパティが設定されていない場合、列の間隔には、spacingプロパティが使用される。

  
  

  このプロパティは、Qt 5.0で導入された。

  rowSpacingプロパティも参照すること。

  
  

• padding
• topPadding
• bottomPadding
• leftPadding
• rightPadding

  値 : real型

  コンテンツの周りのパディングを設定する。

  このプロパティは、Qt 5.6で導入された。

  
  

• add

  値 : Transition型

  Grid内のアイテムに対して実行されるトランジションを設定する。

  Positionerアイテムの場合、以下のアイテムが該当する。

  • ポジショナーが作成された後に、ポジショナーの子として作成または再配置されたアイテム
  • 子アイテムのvisibleプロパティの値がfalseからtrueに変更されて、可視状態になったアイテム

  
  

  トランジションは、ViewTransitionを使用して、追加されるアイテムの詳細にアクセスできる。

  これらのトランジションの使用に関する詳細と例については、ViewTransitionのドキュメントを参照すること。

  
  

  ※注意

  addプロパティは、作成時に既にポジショナーの一部となっているアイテムには適用されない。

  この場合は、代わりにpopulateプロパティが適用される。

  
  

  populateやViewTransitionも参照すること。

  
  

• move

  値 : Transition型

  Grid内で移動したアイテムに対して実行するトランジションを設定する。

  
  

  Positionerアイテムの場合、以下のアイテムが該当する。

  • ポジショナー内の他のアイテムの追加、削除、再配置により、位置がずれた子アイテムの移動
  • ポジショナー内の他のアイテムのサイズ変更により再配置された子アイテム

  
  

  トランジションでは、ViewTransitionを使用して、移動されるアイテムの詳細にアクセスすることができる。

  
  

  ※注意

  ただし、moveプロパティでは、ViewTransition.targetIndexesプロパティとViewTransition.targetItemsプロパティは、

  ポジショナーに他のアイテムが追加されて、moveプロパティがトリガーされた場合にのみ設定される。

  それ以外の場合は、これらのリストは空になる。

  
  

  これらのトランジションの詳細や使用例については、ViewTransitionのドキュメントを参照すること。

  また、addプロパティ、populateプロパティ、ViewTransitionプロパティも参照すること。

  
  

• populate

  値 : Transition型

  ポジショナーの作成時に、このポジショナーの一部であるアイテムに対して実行されるトランジションを設定する。

  populateプロパティは、ポジショナーが最初に作成された時に実行される。

  
  

  populateプロパティは、ViewTransitionを使用して追加されるアイテムの詳細情報にアクセスできる。

  
  

  これらのトランジションの詳細や使用例については、ViewTransitionのドキュメントを参照すること。

  また、addプロパティも参照すること。

  
  

• effectiveHorizontalItemAlignment
• horizontalItemAlignment
• verticalItemAlignment

  値 : enumeration型

  Grid内のアイテムの水平方向および垂直方向の配置を設定する。

  既定値では、アイテムは垂直方向に上に並んでいる。

  水平方向のアラインメントは、layoutDirectionに従う。

  
  

  例えば、layoutDirectionがLeftToRightの場合、アイテムは左に配置される。

  
  

  horizontalItemAlignmentの有効な値は、Grid.AlignLeft、Grid.AlignRight、Grid.AlignHCenterである。

  VerticalItemAlignmentの有効な値は、Grid.AlignTop、Grid.AlignBottom、Grid.AlignVCenterである。

  
  

  LayoutMirroring.enabledプロパティやlayoutDirectionプロパティの設定してレイアウトをミラーリングする時、アイテムの水平方向もミラーリングされる。

  ただし、horizontalItemAlignmentプロパティは変更されない。

  アイテムの効果的な水平方向の配置を確認するには、読み取り専用であるefficHorizontalItemAlignmentプロパティを使用する。

  
  

  これらのプロパティは、Qt 5.1で導入された。

  Grid.layoutDirectionプロパティおよびLayoutMirroringも参照すること。

  
  

  下表は、アイテムを整列させるための3つの例を示している。

Horizontal alignment	AlignLeft	AlignHCenter	AlignHCenter
Vertical alignment	AlignTop	AlignTop	AlignVCenter

シグナル

• positioningComplete()

  このシグナルは、位置決めが完了した時に発行する。

  
  

  ※注意

  対応するハンドラは onPositioningComplete()である。

  
  

  このシグナルは、Qt 5.9で導入された。

メソッド

• forceLayout()

  Gridは、通常、フレームごとに1度だけ子アイテムを配置する。

  
  

  スクリプト内では、下層の子アイテムが変更されても、Gridがまだ更新されていない可能性がある。

  そのため、forceLayoutメソッドは、Gridが子アイテムの変更に即座に対応することを強制する。

  
  

  ※注意

  一般的に、forceLayoutメソッドは、コンポーネントが完了してから呼び出すべきである。

  
  

  このメソッドは、Qt 5.9で導入された。

GridLayout

専用プロパティ

• layoutDirection

  値 : enumeration (既定値 : Qt.LeftToRight)

  このプロパティは、アイテムを左から右にレイアウト、または、右から左にレイアウトするかどうかを制御する。(QtQuick.Layouts 1.1で導入された)

  
  

  既定値のQt.LeftToRightは、アイテムを左から右に配置する。

  値にQt.RightToLeftを指定する場合、アイテムを右から左に向かって配置する。

  また、Qt.RightToLeftが指定されている場合、左揃えのアイテムは右揃えになり、右揃えのアイテムは左揃えになる。
  

  
  

  RowLayout、ColumnLayout、GridLayoutには、layoutDirectionプロパティが存在する。
  

  
  

• rowSpacing

  値 : real型 (既定値 : 5)

  各行の間隔を設定する。

  
  

• columnSpacing

  値 : real型 (既定値 : 5)

  各カラムの間隔を設定する。

  
  

• rows

  値 : int型 (既定値 : 制限なし)

  Layout.flowプロパティがGridLayout.TopToBottomの場合、配置されるアイテムの行数制限を設定する。

  
  

• columns

  値 : int型 (既定値 : 制限なし)

  Layout.flowプロパティがGridLayout.LeftToRightの場合、配置されるアイテムの列数制限を設定する。

  
  

• flow

  値 : enumeration型 (既定値 : GridLayout.LeftToRight)

  セルの位置が明示的に設定されていないアイテムのフロー方向を設定する。

  このプロパティは、rowsプロパティやcolumnsと一緒に使用され、それぞれ、次の行または列にフローがリセットされるタイミングを指定する。

  
  

  設定可能な値は、以下の通りである。

  • GridLayout.LeftToRight （既定値）

    アイテムが隣り合って配置されて、次の行に折り返される。

  • GridLayout.TopToBottom

    アイテムは上から下に向かって隣り合って配置されて、次の列に折り返される。

  
  

  rowsプロパティとcolumnsプロパティも参照すること。

  
  

• Layout.row

  値 : int型 (既定値 : 0)

  GridLayout内のアイテムの行の位置を設定する。

  Layout.rowプロパティおよびLayout.columnプロパティの両方が設定されていない場合、アイテムにセルを割り当てるかどうかは、レイアウトに委ねられる。

  Layout.columnおよびLayout.rowSpanも参照すること。

  
  

• Layout.rowSpan

  値 : int型 (既定値 : 1)

  GridLayout内のアイテムの行のスパンを設定する。

  Layout.rowおよびLayout.columnSpanも参照すること。

  
  

• Layout.column

  値 : int型 (既定値 : 0)

  GridLayout内のアイテムのカラムの位置を設定する。

  Layout.columnプロパティおよびLayout.rowプロパティの両方が設定されていない場合、アイテムにセルを割り当てるかどうかは、レイアウトに委ねられる。

  Layout.rowおよびLayout.columnSpanも参照すること。

  
  

• Layout.columnSpan

  値 : int型 (既定値 : 1)

  GridLayout内のアイテムのカラムのスパンを設定する。

  Layout.columnおよびLayout.rowSpanも参照すること。

プロパティ

GridLayoutは、以下のプロパティもサポートしている。

• Layout.minimumWidth

  値 : real型 (既定値 : アイテムの暗黙の最小幅)

  レイアウト内のアイテムの最小幅を設定する。

  アイテムがレイアウトである場合、暗黙の最小幅は、どの項目もその最小幅よりも縮小することなくレイアウトが持つことができる最小幅になる。

  (その他のアイテムにおける暗黙の最小幅は0である)

  この値を-1に設定する場合、暗黙的な最小幅にリセットされる。

  preferredWidthプロパティおよびmaximumWidthプロパティも参照すること。

  
  

• Layout.minimumHeight

  値 : real型 (既定値 : アイテムの暗黙の最小の高さ)

  レイアウト内のアイテムの最小の高さを設定する。

  アイテムがレイアウトである場合、暗黙の最小の高さは、どのアイテムもその最小高さよりも縮小することなく、レイアウトが持つことのできる最小の高さになる。

  (その他のアイテムの暗黙の最小の高さは0である)

  この値を-1に設定する場合、高さが暗黙の最小値にリセットされる。

  preferredHeightプロパティとmaximumHeightプロパティも参照すること。

  
  

• Layout.preferredWidth

  値 : real型 (既定値 : -1)

  レイアウト内のアイテムの優先幅を設定する。

  値が-1の場合、preferredWidthプロパティは無視されて、implicitWidthプロパティを使用する。

  minimumWidthプロパティとmaximumWidthプロパティも参照すること。

  
  

• Layout.preferredHeight

  値 : real型 (既定値 : -1)

  レイアウト内のアイテムの優先する高さを設定する。

  値が-1の場合、preferredWidthプロパティは無視されて、implicitHeightプロパティを使用する。

  minimumHeightプロパティとmaximumHeightプロパティも参照すること。

  
  

• Layout.maximumWidth

  値 : real型 (既定値 : アイテムの暗黙の最大幅)

  レイアウト内のアイテムの最大幅を設定する。

  アイテムがレイアウトの場合、暗黙の最大幅は、レイアウトが最大幅を超えることなくレイアウトが持つことができる最大幅になる。

  この値を-1に設定すると、幅が暗黙の最大幅にリセットされる。

  
  

  レイアウト以外の場合、暗黙の最大幅は、Number.POSITIVE_INFINITYである。

  minimumWidthプロパティおよびpreferredWidthプロパティも参照すること。

  
  

• Layout.maximumHeight

  値 : real型 (既定値 : アイテムの暗黙の最大の高さ)

  レイアウト内のアイテムの最大幅を設定する。

  アイテムがレイアウトの場合、暗黙の最大の高さは、どのアイテムも最大の高さを超えずにレイアウトが持てる最大の高さになる。

  この値を-1に設定する場合、高さは暗黙の最大の高さにリセットされる。

  
  

  レイアウト以外の場合、暗黙の最大の高さは、Number.POSITIVE_INFINITYである。

  minimumHeightプロパティとpreferredHeightプロパティも参照すること。

  
  

• Layout.fillWidth

  値 : bool型 (レイアウトの既定値 : true, レイアウト内のアイテムの既定値 : false)

  このプロパティがtrueの場合、レイアウト内のアイテムは、与えられた制約を尊重しながら可能な限り広くなる。

  このプロパティがfalseの場合、レイアウト内のアイテムは、望ましい幅に設定された固定幅を持つ。

  
  

  レイアウト内のアイテムの既定値はfalseであるが、レイアウト自体の既定値はtrueである。

  fillHeightプロパティも参照すること。

  
  

• Layout.fillHeight

  値 : bool型 (レイアウトの既定値 : true, レイアウト内のアイテムの既定値 : false)

  このプロパティがtrueの場合、レイアウト内のアイテムは、与えられた制約を尊重しながら可能な限り高さが高くなる。

  このプロパティがfalseの場合、レイアウト内のアイテムは、望ましい高さに設定された固定の高さを持つ。

  
  

  レイアウト内のアイテムの既定値はfalseであるが、レイアウト自体の既定値はtrueである。

  fillWidthプロパティも参照すること。

  
  

• Layout.alignment

  値 : Qt.Alignment型 (既定値 : 0 … 0とは、Qt.AlignVCenter | Qt.AlignLeftのこと)

  アイテムが占めるセル内の配置を指定する。

  既定値は、水平フラグまたは垂直フラグのみが指定された場合にも適用される。

  水平フラグのみが指定された場合でも、自動的に垂直フラグがQt.AlignVCenterに設定される。

  垂直フラグのみが指定された場合でも、自動的に水平フラグがQt.AlignLeftに設定される。

  
  

  以下に、使用できるフラグを示す。

  • Qt.AlignLeft
  • Qt.AlignHCenter
  • Qt.AlignRight
  • Qt.AlignTop
  • Qt.AlignVCenter
  • Qt.AlignBottom
  • Qt.AlignBaseline

  
  

• Layout.margins

  値 : real型 (既定値 : 0)

  アイテムの外側の余白をすべて同じ値に設定する。

  アイテム自体は自身のマージンを評価しない。マージンを評価するかどうかは、親アイテムが決定する。

  
  

  具体的には、マージンが評価されるのは、ColumnLayout、RowLayout、GridLayout、SplitView等のレイアウトであり、マージンが大きくなるとアイテムの有効セルサイズが大きくなる。

  したがって、マージンを持つアイテムが他のアイテムの子である場合、その位置、サイズ、暗黙のサイズは変更されない。

  
  

  marginsとalignmentを組み合わせる場合、marginsプロパティの値を含めてアイテムの位置を合わせる。

  例えば、上のマージンが1、下のマージンが9の垂直方向に中央に配置されたアイテムの場合、セル内でのアイテムの配置は、中央から4ピクセル上となる。

  
  

  このプロパティは、QtQuick.Layouts 1.2で導入された。

  leftMarginプロパティ、topMarginプロパティ、rightMarginプロパティ、bottomMarginプロパティも参照すること。

  
  

• Layout.topMargin

  値 : real型 (既定値 : Layout.marginsの値)

  アイテムの外側にある上の余白を設定する。

  値が設定されていない場合は、Layout.marginsの値を使用する。

  
  

  このプロパティは、QtQuick.Layouts 1.2で導入された。

  marginsプロパティも参照すること。

  
  

• Layout.bottomMargin

  値 : real型 (既定値 : Layout.marginsの値)

  アイテムの外側にある下の余白を設定する。

  値が設定されていない場合は、Layout.marginsの値を使用する。

  
  

  このプロパティは、QtQuick.Layouts 1.2で導入された。

  marginsプロパティも参照すること。

  
  

• Layout.leftMargin

  値 : real型 (既定値 : Layout.marginsの値)

  アイテムの外側にある左の余白を設定する。

  値が設定されていない場合は、Layout.marginsの値を使用する。

  
  

  このプロパティは、QtQuick.Layouts 1.2で導入された。

  marginsプロパティも参照すること。

  
  

• Layout.rightMargin

  値 : real型 (既定値 : Layout.marginsの値)

  アイテムの外側にある右の余白を設定する。

  値が設定されていない場合は、Layout.marginsの値を使用する。

  
  

  このプロパティは、QtQuick.Layouts 1.2で導入された。

  marginsプロパティも参照すること。

  
  

サンプルコード

GridLayout内の全ての可視アイテムは、レイアウトに属する。

GridLayoutのサイズが変更された場合、レイアウト内の全てのアイテムが再配置される。
これは、ウィジェットベースのQGridLayoutに似ている。

1つの行または1つの列のみを持つレイアウトが必要な場合は、RowLayoutまたはColumnLayoutを使用する。
これらは、より便利なAPIを提供しているため、可読性が向上するからである。

デフォルトの設定では、アイテムはflowプロパティにしたがって配置される。
(flowプロパティの既定値は、GridLayout.LeftToRight)

もし、columnsプロパティを設定している場合、自動配置が次の行の先頭に折り返される前に、レイアウトが持つことのできる列数の最大値として扱われる。
columnsプロパティは、flowプロパティがGridLayout.LeftToRightの場合にのみ使用される。

以下の例は、GridLayoutのサンプルコードである。

 GridLayout {
    id: grid
    columns: 3
 
    Text {
       text: "Three"
       font.bold: true
    }
 
    Text {
       text: "words"
       color: "red"
    }
 
    Text {
       text: "in"
       font.underline: true
    }
 
    Text {
       text: "a"
       font.pixelSize: 20
    }
 
    Text {
       text: "row"
       font.strikeout: true
    }
 }

rowsプロパティも同様に動作するが、アイテムは垂直方向に自動配置される。
また、rowsプロパティは、flowがGridLayout.TopToBottomの場合にのみ使用される。

Layout.rowプロパティとLayout.columnプロパティを設定することにより、アイテムが占めるセルを設定できる。
また、Layout.rowSpanまたはLayout.columnSpanプロパティを設定することにより、行のスパンや列のスパンを設定できる。

GridLayout内のアイテムは、これらの付属プロパティをサポートしている。