フレームワーク プロパティ メタデータ (WPF .NET)

  • [アーティクル]

依存関係プロパティのフレームワーク プロパティ メタデータ オプションは、Windows Presentation Foundation (WPF) フレームワーク レベルで設定できます。 WPF フレームワーク レベルの指定は、WPF プレゼンテーション API と実行可能ファイルがレンダリングとデータ バインディングを処理する場合に適用されます。 プレゼンテーション API と実行可能ファイルは、依存関係プロパティの FrameworkPropertyMetadata に対してクエリを実行します。

重要

.NET 7 と .NET 6 用のデスクトップ ガイド ドキュメントは作成中です。

必須コンポーネント

この記事では、依存関係プロパティの基本的な知識と、依存関係プロパティの概要に関する記事を参照済みであることを前提としています。 この記事の例について理解するには、Extensible Application Markup Language (XAML) を使い慣れていて、WPF アプリケーションの記述方法を理解していると役に立ちます。

フレームワーク プロパティ メタデータ カテゴリ

FrameworkPropertyMetadata は、次のカテゴリに分類されます。

  • 要素のレイアウトに影響を与えるメタデータ。具体的には、AffectsArrange、AffectsMeasure、AffectsRender メタデータ フラグです。 依存関係プロパティの実装が視覚的な側面に影響し、クラス内で MeasureOverride または ArrangeOverride を実装している場合は、これらのフラグを設定できます。 MeasureOverride メソッドと ArrangeOverride メソッドは、実装固有の動作とレンダリング情報をレイアウト システムに提供します。 依存関係プロパティのメタデータで AffectsArrange、AffectsMeasure、または AffectsRender が true に設定されている場合、有効な値が変更されると、WPF プロパティ システムでは、要素のビジュアルを無効にして再描画をトリガーする要求が開始されます。

  • 要素の親要素のレイアウトに影響を与えるメタデータ。具体的には、AffectsParentArrange および AffectsParentMeasure メタデータ フラグです。 これらのフラグを設定する WPF 依存関係プロパティの例は、FixedPage.Left と Paragraph.KeepWithNext です。

  • プロパティ値の継承メタデータ。具体的には、Inherits および OverridesInheritanceBehavior メタデータ フラグです。 既定では、依存関係プロパティは値を継承しません。 OverridesInheritanceBehavior を使用すると、継承のパスがビジュアル ツリー内を通ることもできるようになります。コントロールを複合する一部のシナリオでは、このような必要が生じることがあります。 詳細については、「プロパティ値の継承」を参照してください。

    注意

    プロパティ値のコンテキストでの "継承" という用語は依存関係プロパティに固有であり、派生型を介したマネージド コードの型とメンバーの継承とは直接関係しません。 依存関係プロパティのコンテキストでは、子要素が親要素から依存関係プロパティ値を継承できることを意味します。

  • データ バインディング メタデータ。具体的には、BindsTwoWayByDefault および IsNotDataBindable メタデータ フラグです。 既定では、WPF フレームワークの依存関係プロパティは一方向のバインドをサポートします。 IsSelected などのように、状態を報告し、"なおかつ" ユーザー アクションによって変更可能なプロパティの既定値として両方向のバインドを設定することを検討してください。 また、TextBox.Text などのように、コントロールのユーザーがプロパティで実装されることを想定している場合は、既定値として両方向のバインドを設定することを検討してください。 BindsTwoWayByDefault は、既定のバインディング モードにのみ影響します。 バインドのデータ フローの方向を編集するには、Binding.Mode を設定します。 使用例がない場合は、IsNotDataBindable を使用してデータ バインディングを無効にすることができます。 データ バインディングの詳細については、「データ バインディングの概要」を参照してください。

  • ジャーナリング メタデータ。具体的には、Journal メタデータ フラグです。 Journal フラグの既定値は、SelectedIndex などの一部の依存関係プロパティに対してのみ true です。 ユーザー入力コントロールでは、格納する必要があるユーザー選択を保持する値を持つプロパティに対して Journal フラグを設定する必要があります。 Journal フラグは、WPF ジャーナリング サービスを含めて、ジャーナリングをサポートするアプリケーションまたはサービスによって読み取られます。 ナビゲーション手順の格納については、「ナビゲーションの概要」を参照してください。

FrameworkPropertyMetadata は UIPropertyMetadata から直接派生し、ここで説明するフラグを実装します。 特に設定されていない限り、FrameworkPropertyMetadata フラグの既定値は false です。

FrameworkPropertyMetadata の読み取り

依存関係プロパティのメタデータを取得するには、DependencyProperty 識別子で GetMetadata を呼び出します。 GetMetadata 呼び出しは PropertyMetadata オブジェクトを返します。 フレームワーク メタデータ値を照会する必要がある場合は、PropertyMetadata を FrameworkPropertyMetadata にキャストします。

FrameworkPropertyMetadata の指定

依存関係プロパティを登録する場合は、メタデータを作成して割り当てるオプションがあります。 割り当てるメタデータ オブジェクトは、PropertyMetadata またはその派生クラスのいずれか (FrameworkPropertyMetadata など) になります。 レンダリングとデータ バインディングには、WPF プレゼンテーション API と実行可能ファイルに依存する依存関係プロパティの FrameworkPropertyMetadata を選択します。 より高度なオプションは、より多くのフラグを持つカスタム メタデータ レポート クラスを作成するために FrameworkPropertyMetadata から派生することです。 または、UI レンダリングに影響を与えるフレームワーク以外のプロパティに UIPropertyMetadata を使用することもできます。

通常、メタデータ オプションは新しい依存関係プロパティの登録時に設定されますが、OverrideMetadata または AddOwner 呼び出しで再指定できます。 メタデータをオーバーライドする場合は、常にプロパティの登録時に使用されたのと同じメタデータ型でオーバーライドします。

FrameworkPropertyMetadata によって公開されるプロパティ特性は、''フラグ'' と呼ばれる場合があります。 FrameworkPropertyMetadata インスタンスを作成する場合は、フラグ値を設定する方法が 2 つあります。

  1. FrameworkPropertyMetadataOptions 列挙型のインスタンスにフラグを設定します。 FrameworkPropertyMetadataOptions では、メタデータ フラグをビットごとの OR の組み合わせで指定できます。 次に、FrameworkPropertyMetadataOptions パラメーターを持つコンストラクターを使用して FrameworkPropertyMetadata をインスタンス化し、FrameworkPropertyMetadataOptions インスタンスを渡します。 FrameworkPropertyMetadataOptions を FrameworkPropertyMetadata コンストラクターに渡した後でメタデータ フラグを変更するには、新しい FrameworkPropertyMetadata インスタンスの対応するプロパティを変更します。 たとえば、FrameworkPropertyMetadataOptions.NotDataBindable フラグを設定した場合は、FrameworkPropertyMetadata.IsNotDataBindable を false に設定して元に戻すことができます。

  2. FrameworkPropertyMetadataOptions パラメーターを持たないコンストラクターを使用して FrameworkPropertyMetadata をインスタンス化し、FrameworkPropertyMetadata の該当する Boolean フラグを設定します。 FrameworkPropertyMetadata インスタンスを依存関係プロパティに関連付ける前にフラグ値を設定します。それ以外の場合は、InvalidOperationException が発生します。

メタデータのオーバーライド動作

フレームワーク プロパティのメタデータをオーバーライドすると、変更されたメタデータ値は元の値に置き換えられるかマージされます。

  • PropertyChangedCallback の場合、既定のマージ ロジックでは以前の PropertyChangedCallback の値がテーブルに保持され、プロパティの変更時にすべて呼び出されます。 コールバックの順序は、階層内の基底クラスによって登録されたコールバックが最初に実行されるクラスの深さによって決まります。 継承されたコールバックは 1 回だけ実行され、それらをメタデータに追加したクラスによって所有されます。

  • DefaultValue の場合、新しい値によって既存の既定値が置き換えられます。 オーバーライド メタデータで DefaultValue を指定せず、既存の FrameworkPropertyMetadata に Inherits フラグが設定されている場合、既定値はメタデータで DefaultValue が指定された最も近い先祖から取得されます。

  • CoerceValueCallback の場合、新しい値によって既存の CoerceValueCallback の値が置き換えられます。 オーバーライド メタデータで CoerceValueCallback を指定しないと、CoerceValueCallback の値は、継承チェーンでそれを指定した最も近い先祖のものになります。

  • 継承されていない FrameworkPropertyMetadata フラグの場合、既定の false 値を true 値でオーバーライドできます。 ただし、Inherits、Journal、OverridesInheritanceBehavior、SubPropertiesDoNotAffectRender に対しては、true 値を false 値でオーバーライドすることしかできません。

注意

既定のマージ ロジックは、Merge メソッドによって実装されます。 依存関係プロパティを継承する派生クラスでは、そのクラスで Merge をオーバーライドすることで、カスタム マージ ロジックを指定できます。

関連項目