プロパティシステム¶

プロパティは、ノードの状態、見た目、動作を指定したり調べたりする手段となります。例えば、プロパティは色を定義したり、ボタンが押されているかどうかを示したり、アイテムの配置を指定したりすることができます。

Kanzi Studio でプロパティ値を設定し、プロパティシステムの仕組みを理解せずにコード内でそれらにアクセスすることで、プロパティを操作できます。しかし、Kanzi プロパティシステムの機能を最大限に活用するには、プロパティシステムの仕組みを理解する必要があります。

プロパティは、Kanzi ノードのデータにアクセスするための統一された方法を提供し、多くの Kanzi サブシステムがデータを操作できるようにします。これにより、たとえば、プロパティ値をアニメーション化したり、プロパティ値間のバインディングを提供したり、プロパティ値の変化を監視したりすることができます。

任意のプロパティ値は、複数の入力ソースによって影響を受ける可能性があります。プロパティシステムは、すべての入力からプロパティ値を解決するためのルールを定義し、現在の値を解決します。例えば、プロパティの値を直接設定することができ、プロパティにはデフォルト値が設定されている場合があり、スタイルがプロパティ値に影響を与えることができ、アニメーションやステートマネージャーがプロパティ値を変更することができます。自動的に適用されるルールを提供することにより、プロパティシステムは手動で値を変更しなければならない場所の数を最小限に抑えます。

プロパティデータタイプ¶

各プロパティはプロパティタイプによって記述されます。プロパティタイプは、プロパティが使用される場所とプロパティの名前を一意に記述します。データ型は、プロパティが保持できる値のタイプを定義します。

例えば、ノードの可視性を制御する Node::VisibleProperty プロパティタイプは、Node クラスおよび派生クラスで使用されます。実行時にプロパティタイプを見つけるために、その名前（Node::VisibleProperty）を使用できます。プロパティのデータタイプはブール値であるため、true または false の値を受け入れます。

Kanzi Studio では、より専門的なプロパティタイプを持つことができますが、それらの表現は利用可能なデータタイプからのみ得られます。プロパティタイプの作成を参照してください。

たとえばenum値の場合、値の範囲はenumで定義された範囲に限定されますが、enum値はinteger値として表現されます。

プロパティの使用¶

ほとんどの Kanzi プロパティは、それを使用するクラスで定義されています。このようなプロパティを使用して、プロパティを設定するオブジェクトの外観、状態、または動作を設定できます。

例：

Text Block ノードでは、Text プロパティがノードに表示されるテキストを定義します。
Visible プロパティは、ノードおよびそのすべての子孫ノードの可視性を制御します。

しかし、一部の Kanzi プロパティは、他のオブジェクトの外観、動作、または状態を構成します。

例：

マテリアルは、Diffuse Color プロパティを定義することができ、そのマテリアルを使用するノードに割り当てることができます。
Grid Layout は Row および Column プロパティを定義しますが、これらはグリッドレイアウト (Grid Layout) ノードではなく、グリッドレイアウト (Grid Layout) ノードの子ノードで設定します。

Kanzi では、これらのプロパティはアタッチプロパティと呼ばれます。

デフォルトのプロパティ値¶

各プロパティタイプは、そのプロパティのデフォルト値を定義します。クエリされた場合、Kanzi は、スタイルや継承などを通じてプロパティ値を直接または間接的に設定しない限り、デフォルト値を返します。デフォルト値を使用することで、アプリケーション開発の時間を節約できます。

例えば、Visible (Node::VisibleProperty) プロパティのデフォルト値は true です。デフォルトで、すべてのノードは表示されます。

一部のプロパティタイプでは、プロパティ値を持たないことが前提となります。

例えば、Layout Width (Node::WidthProperty) および Layout Height (Node::HeightProperty) プロパティを使用すると、ノードのサイズを設定できます。

これらのプロパティを100ピクセルに設定することで、ノードのサイズを100×100ピクセルに強制します。
これらのプロパティを設定しないことにより、ノードが自身のサイズを決定するようにします。

例えば、Image ノードは表示する画像に基づいてそのサイズを決定することができ、または Stack Layout ノードはそのすべてのアイテムのサイズにすることができます。

継承可能なプロパティタイプ¶

各プロパティタイプは、そのプロパティの値が継承可能かどうかを定義します。ノードは、継承可能なプロパティタイプの値をその祖先ノードから継承します。

例えば、Node::FontFamilyProperty は継承可能なプロパティタイプです。すべてのテキストを表示できるコントロールに同じフォントファミリーを使用したい場合は、ノードツリーの最上位レベルでのみ Font Family プロパティを設定します。Kanzi はすべての子孫ノードに同じフォントを適用します。子孫ノードの一つで異なるフォントを使用したい場合は、そのノードに Font Family プロパティを追加し、使用したいフォントファミリーに設定します。

プロパティの優先順位¶

プロパティ値をクエリすると1つの結果が得られますが、値を決定する際にプロパティシステムはプロパティ値に影響を与える可能性がある複数のソースを評価します。プロパティ値のソースは特定の順序で評価されます。

Kanzi Engine は、次の優先順位ルール（最も高いものが最初）に基づいてランタイム値を解決します。

変更された値

アニメーションとバインディングは値を変更し、ステートは値をオーバーライドします。アニメーション (Animations)、修飾子バインディング、およびステートマネージャー (State Manager) を参照してください。

ヒント

Kanzi Studio の Node Tree ウィンドウでは、ステートマネージャー、バインディング、データソースバインディング、またはアニメーションによってノードの一部のプロパティの値がオーバーライドされている場合、そのノードの横にインジケーターが表示されます。

Kanzi Studio プロジェクト内のオーバーライドのソースに移動するには、オーバーライドインジケーターを右クリックし、コンテキストメニューから移動先のソースを選択します。
ローカル値

ローカル値は、直接設定するプロパティ値です。Kanzi Studio では、ノード内のすべてのプロパティがローカル値によって定義されています。アクション、値ソースバインディング、および Kanzi Engine API を使用してローカル値を設定できます。

Kanzi Engine APIを使用して、ローカルプロパティ値を設定できます:
- PropertyObject::setProperty 関数。
  
  たとえば、Visible プロパティの値を false に設定するには、使用します。
```
node.setProperty(Node::VisibleProperty, false)
```
- ほとんどのクラスが提供するヘルパー関数。
  
  例えば、Node::setVisible 関数で Node::VisibleProperty プロパティを設定できます。
  
  ヘルパー関数については、プロパティを定義しているクラスのリファレンスを参照してください。
値ソースバインディングとトリガー (Triggers) を参照してください。
名前付きスタイル

Kanzi は、Style プロパティの値がそのスタイルを指しているすべてのノードに名前付きスタイルを適用します。

ノードタイプの選択されたインスタンスにスタイルを適用するを参照してください。
Typed スタイル

Kanzi は、スタイルで指定したタイプのすべてのノードに型付きスタイルを適用します。

選択したスコープ内のノードタイプに適用されるスタイルを適用するを参照してください。
継承された値 （プロパティが継承可能な場合）

各プロパティタイプでは、プロパティが継承可能かどうかを指定します。特定の値のみが先祖から継承されることができます。

継承可能なプロパティタイプを参照してください。
デフォルト値とクラスデフォルト値

すべてのプロパティには、そのメタデータで定義されたデフォルト値があります。Kanzi は、他に何も値に影響を与えない場合、デフォルト値を使用します。プロパティタイプを継承する各クラスは、そのデフォルト値をオーバーライドすることができます。

例：
- Horizontal Alignment (Node::HorizontalAlignmentProperty) プロパティのデフォルト値は Center (Node::HorizontalAlignment::HorizontalAlignmentCenter) です。
- Node2D クラスは、Horizontal Alignment プロパティのデフォルト値を Left (Node::HorizontalAlignment::HorizontalAlignmentLeft) にオーバーライドします。
デフォルトのプロパティ値を参照してください。

プロパティタイプ変更フラグ¶

Kanzi では、各プロパティタイプは、そのプロパティの値を変更した際の影響を示す1つ以上の変更フラグを持つことができます。

例：

PropertyTypeChangeFlag::PropertyTypeChangeFlagMeasure フラグは、ノード自身によって報告されるノードのサイズ、または他のノードに対するそのノードのサイズと位置に影響を与えるプロパティタイプによって使用されます。

例えば、Layout Width (Node::WidthProperty) プロパティにはこの変更フラグがあります。ノード内の Layout Width プロパティの値が変更されると、Kanzi:
1. ノードを再測定します。
2. ノードの測定サイズが変更された場合、ノードの親、その親の親、そしてその先も測定します。
3. ノード、その変更された祖先ノード、およびその子孫のレイアウトを再配置します。
4. 変換が変更されたノードに対して、変換を再計算します。
5. すべてのノードを描画します。
PropertyTypeChangeFlag::PropertyTypeChangeFlagRender フラグは、2Dノードのレンダリングパラメータを変更するが、レイアウトには影響を与えないプロパティタイプで使用されます。

例えば、Render Transformation （Node2D::RenderTransformationProperty）プロパティにはこの変更フラグがあります。ノード内の Render Transformation プロパティの値が変更されると、Kanzi:
1. ノードとその子孫の変換を再計算します。
2. すべてのノードを描画します。
PropertyTypeChangeFlag::PropertyTypeChangeFlagDraw フラグは、ノードの描画に影響を与えるプロパティタイプで使用されます。

例えば、ほとんどのマテリアルプロパティはこのフラグを使用します。このようなプロパティの値がノードで変更されると、Kanzi はすべてのノードを描画します。

Kanzi Engine APIリファレンスで、PropertyTypeChangeFlag を参照してください。