プロパティウィンドウをカスタマイズする

[アーティクル]
06/19/2023

Visual Studio のドメイン固有言語 (DSL) で、プロパティウィンドウの外観と動作をカスタマイズすることができます。 DSL 定義で、各ドメインクラスのドメインプロパティを定義します。既定では、ダイアグラムまたはモデルエクスプローラーでクラスのインスタンスを選択すると、すべてのドメインプロパティがプロパティウィンドウに一覧表示されます。これにより、ダイアグラムのシェイプのフィールドにマップされていない場合でも、ドメインプロパティの値を表示および編集できます。

名前、説明、カテゴリ

名前と表示名。ドメインプロパティの定義で、プロパティの表示名は、実行時にプロパティウィンドウに表示される名前です。これに対し、名前は、プロパティを更新するプログラムコードを記述するときに使用します。名前は CLR の正しい英数字名にする必要がありますが、表示名はスペースが含まれていてもかまいません。

DSL 定義でプロパティの名前を設定すると、その表示名に名前のコピーが自動的に設定されます。 "FuelGauge" のようなパスカルケースの名前を記述した場合、表示名には自動的にスペースが挿入されて "Fuel Gauge" のようになります。ただし、表示名を明示的に別の値に設定することもできます。

説明。ドメインプロパティの説明は、次の 2 つの場所に表示されます。

ユーザーがプロパティを選択したときに、プロパティウィンドウの下部。それを使用して、プロパティが表す内容をユーザーに説明することができます。
生成されるプログラムコード内。ドキュメント機能を使用して API ドキュメントを抽出すると、API のこのプロパティの説明として表示されます。

カテゴリ。カテゴリは、プロパティウィンドウの見出しです。

スタイル機能を公開する

グラフィカル要素の動的機能の一部は、ドメインプロパティとして表したり "公開" したりすることができます。この方法で公開された機能は、手動で更新することができ、プログラムコードを使用するとさらに簡単に更新できます。

DSL 定義でシェイプクラスを右クリックし、 [公開済みの項目を追加] をポイントして、機能を選択します。

シェイプでは、FillColor、OutlineColor、TextColor、OutlineDashStyle、OutlineThickness、FillGradientMode の各プロパティを公開できます。コネクタでは、Color,TextColor、DashStyle、Thickness の各プロパティを公開できます。ダイアグラムでは、FillColor と textcolor プロパティを公開できます。

DSL のユーザーがモデル内の要素を選択すると、その要素のプロパティがプロパティウィンドウに表示されます。ただし、指定された関連要素のプロパティを表示することもできます。これは、連携して動作する要素のグループを定義している場合に便利です。たとえば、メイン要素とオプションのプラグイン要素を定義することがあります。メイン要素はシェイプにマップされていて、他はそうでない場合、すべてのプロパティを 1 つの要素上にあるかのように表示すると便利です。

この効果は "プロパティ転送" と呼ばれ、いくつかのケースで自動的に行われます。それ以外の場合は、ドメイン型記述子を定義することで、プロパティ転送を実現できます。

既定のプロパティ転送の場合

ユーザーがシェイプまたはコネクタを選択するか、エクスプローラーで要素を選択すると、次のプロパティがプロパティウィンドウに表示されます。

モデル要素のドメインクラスで定義されているドメインプロパティ。基底クラスで定義されているものも含まれます。例外は、Is Browsable が False に設定されているドメインプロパティです。
カーディナリティが 0..1 のリレーションシップによってリンクされている要素の名前。これにより、リレーションシップのコネクタマッピングが定義されていない場合でも、必要に応じてリンクされる要素を表示する便利な方法が提供されます。
その要素をターゲットとする埋め込みリレーションシップのドメインプロパティ。通常、埋め込みリレーションシップは明示的に表示されないため、これによりユーザーはプロパティを見ることができます。
選択されたシェイプまたはコネクタで定義されているドメインプロパティ。

プロパティ転送を追加する

プロパティを転送するには、ドメイン型記述子を定義します。 2 つのドメインクラスの間にドメインリレーションシップがある場合は、ドメイン型記述子を使用して、最初のクラスのドメインプロパティに、2 番目のドメインクラスのドメインプロパティの値を設定できます。たとえば、Book ドメインクラスと Author ドメインクラスの間にリレーションシップがある場合、ドメイン型記述子を使用して、ユーザーが Book を選択したときに、Book の Author の Name プロパティをプロパティウィンドウに表示させることができます。

注意

プロパティ転送がプロパティウィンドウに影響を与えるのは、ユーザーがモデルを編集している場合のみです。受け取り側のクラスではドメインプロパティは定義されません。 DSL 定義の他の部分またはプログラムコードで転送されたドメインプロパティにアクセスするには、転送側の要素にアクセスする必要があります。

次の手順では、DSL を作成してあるものとします。最初の数ステップに、前提条件をまとめてあります。

別の要素からプロパティを転送する

少なくとも 2 つのクラスが含まれるドメイン固有言語ツールソリューションを作成します。この例では、Book および Author という名前です。 Book と Author の間に、いずれかの種類のリレーションシップが存在する必要があります。

各 Book に 1 つの Author があるように、ソースロール (Book 側のロール) のカーディナリティは 0..1 または 1..1 である必要があります。
DSL エクスプローラーで、Book ドメインクラスを右クリックし、 [新しい DomainTypeDescriptor の追加] をクリックします。

[カスタムプロパティ記述子のパス] という名前のノードが、 [カスタムの型記述子] ノードの下に表示されます。
[カスタムの型記述子] ノードを右クリックし、 [新しい PropertyPath の追加] をクリックします。

新しいプロパティパスが、 [カスタムプロパティ記述子のパス] ノードの下に表示されます。
新しいプロパティパスを選択し、 [プロパティ] ウィンドウで、 [プロパティへのパス] を適切なモデル要素のパスに設定します。

ツリービューでこのプロパティの右側にある下矢印をクリックすることで、パスを編集できます。ドメインパスの詳細については、「ドメインパス構文」を参照してください。編集が済むと、パスは BookReferencesAuthor.Author/!Author のようになります。
[Property] を Author の [Name] ドメインプロパティに設定します。
[Display Name] を Author Name に設定します。
すべてのテンプレートを変換し、DSL をビルドして実行します。
モデルダイアグラムで、書籍と著者を作成し、参照リレーションシップを使用してそれらをリンクします。書籍要素を選択すると、プロパティウィンドウに書籍のプロパティに加えて Author Name が表示されるはずです。リンクされた著者の名前を変更するか、別の著者に書籍をリンクして、書籍の著者名が変化することを確認します。

カスタムプロパティエディター

プロパティウィンドウには、各ドメインプロパティの型に対する適切な既定の編集エクスペリエンスが用意されています。たとえば、列挙型の場合はユーザーにドロップダウンリストが表示され、数値プロパティの場合はユーザーは数字を入力できます。これは、組み込み型の場合にのみ当てはまります。外部型を指定した場合、ユーザーはプロパティの値を表示できますが、編集することはできません。

ただし、次のエディターと型を指定できます。

標準型で使用される別のエディター。たとえば、文字列プロパティに対してファイルパスエディターを指定できます。
ドメインプロパティの外部型と、その型のエディター。
ファイルパスエディターなどの .NET エディター、または独自のカスタムプロパティエディターを作成することができます。

外部タイプと、デフォルトのエディターを持つ文字列などのタイプ間の変換。

DSL では、"外部型" は、単純型 (ブール値や Int32 など) または String ではない任意の型です。

外部型を持つドメインプロパティを定義する

ソリューションエクスプローラーで、Dsl プロジェクトに外部型を含むアセンブリ (DLL) への参照を追加します。

アセンブリは、.NET アセンブリでも、ユーザー指定のアセンブリでもかまいません。
[ドメイン型] の一覧に型を追加します (まだ行っていない場合)。
1. DslDefinition.dsl を開き、DSL エクスプローラーでルートノードを右クリックして、 [新しい外部型の追加] をクリックします。
  
  [ドメイン型] ノードの下に新しいエントリが表示されます。
  
  警告
  
  メニュー項目は、 [ドメイン型] ノードではなく、DSL のルートノードにあります。
2. プロパティウィンドウで、新しい型の名前と名前空間を設定します。
通常の方法でドメインクラスにドメインプロパティを追加します。

プロパティウィンドウで、 [型] フィールドのドロップダウンリストから外部型を選択します。

この段階では、ユーザーはプロパティの値を表示できますが、編集することはできません。表示される値は、ToString() 関数から取得されます。コマンドやルールなどで、プロパティの値を設定するプログラムコードを記述できます。

プロパティエディターを設定する

次の形式で、CLR 属性をドメインプロパティに追加します。

[System.ComponentModel.Editor (
   typeof(AnEditor),
   typeof(System.Drawing.Design.UITypeEditor))]

プロパティウィンドウの [カスタム属性] エントリを使用することで、プロパティに属性を設定できます。

AnEditor の型は、2 番目のパラメーターで指定された型から派生する必要があります。 2 番目のパラメーターは、UITypeEditor または ComponentEditor である必要があります。詳細については、「EditorAttribute」を参照してください。

独自のエディターまたは .NET エディター (FileNameEditor や ImageEditor など) を指定できます。たとえば、ユーザーがファイル名を入力できるプロパティを設定するには、次の手順のようにします。

ファイル名ドメインプロパティを定義する

DSL 定義でドメインクラスにドメインプロパティを追加します。
新しいプロパティを選択します。プロパティウィンドウの [カスタム属性] フィールドに、次の属性を入力します。この属性を入力するには、省略記号 [...] をクリックし、属性名とパラメーターを個別に入力します。
```
[System.ComponentModel.Editor (
   typeof(System.Windows.Forms.Design.FileNameEditor)
   , typeof(System.Drawing.Design.UITypeEditor))]
```
ドメインプロパティの Type は、既定の String の設定のままにします。
エディターをテストするには、ユーザーがファイル名エディターを開いてドメインプロパティを編集できることを確認します。
1. Ctrl + F5 キーまたは F5 キーを押します。デバッグソリューションで、テストファイルを開きます。ドメインクラスの要素を作成して、それを選択します。
2. プロパティウィンドウで、ドメインプロパティを選択します。値フィールドに、省略記号 [...] が表示されます。
3. 省略記号をクリックします。ファイルダイアログボックスが表示されます。ファイルを選択して、ダイアログボックスを閉じます。これで、ファイルパスがドメインプロパティの値になりました。

独自のプロパティエディターを定義する

独自のエディターを定義できます。これは、開発者が定義した型をユーザーが編集したり、標準の型を特別な方法で編集したりできるようにするために行います。たとえば、数式を表す文字列をユーザーが入力できるようにすることができます。

エディターを定義するには、UITypeEditor の派生クラスを記述します。そのクラスで以下をオーバーライドする必要があります。

EditValue は、ユーザーと対話し、プロパティの値を更新します。
GetEditStyle は、エディターでダイアログボックスを開くか、ドロップダウンメニューを表示するかを指定します。

プロパティグリッドに表示されるプロパティの値のグラフィカル表現を提供することもできます。これを行うには、GetPaintValueSupported と PaintValue をオーバーライドします。詳細については、「UITypeEditor」を参照してください。

注意

Dsl プロジェクトの別のコードファイルにコードを追加します。

次に例を示します。

internal class TextFileNameEditor : System.Windows.Forms.Design.FileNameEditor
{
  protected override void InitializeDialog(System.Windows.Forms.OpenFileDialog openFileDialog)
  {
    base.InitializeDialog(openFileDialog);
    openFileDialog.Filter = "Text files(*.txt)|*.txt|All files (*.*)|*.*";
    openFileDialog.Title = "Select a text file";
  }
}

このエディターを使用するには、ドメインプロパティの [カスタム属性] を次のように設定します。

[System.ComponentModel.Editor (
   typeof(MyNamespace.TextFileNameEditor)
   , typeof(System.Drawing.Design.UITypeEditor))]

詳細については、「UITypeEditor」を参照してください。

値のドロップダウンリストを提供する

ユーザーが選択するための値の一覧を指定できます。

注意

この手法では、実行時に変更できる値の一覧を提供します。変更されない一覧を提供する場合は、代わりに、ドメインプロパティの型として列挙型を使用することを検討します。

標準値の一覧を定義するには、次の形式の CLR 属性をドメインプロパティに追加します。

[System.ComponentModel.TypeConverter
(typeof(MyTypeConverter))]

TypeConverter から派生するクラスを定義します。 Dsl プロジェクトの別のファイルにコードを追加します。次に例を示します。

/// <summary>
/// Type converter that provides a list of values
/// to be displayed in the property grid.
/// </summary>
/// <remarks>This type converter returns a list
/// of the names of all "ExampleElements" in the
/// current store.</remarks>
public class MyTypeConverter : System.ComponentModel.TypeConverter
{
  /// <summary>
  /// Return true to indicate that we return a list of values to choose from
  /// </summary>
  /// <param name="context"></param>
  public override bool GetStandardValuesSupported
    (System.ComponentModel.ITypeDescriptorContext context)
  {
    return true;
  }

  /// <summary>
  /// Returns true to indicate that the user has
  /// to select a value from the list
  /// </summary>
  /// <param name="context"></param>
  /// <returns>If we returned false, the user would
  /// be able to either select a value from
  /// the list or type in a value that is not in the list.</returns>
  public override bool GetStandardValuesExclusive
      (System.ComponentModel.ITypeDescriptorContext context)
  {
    return true;
  }

  /// <summary>
  /// Return a list of the values to display in the grid
  /// </summary>
  /// <param name="context"></param>
  /// <returns>A list of values the user can choose from</returns>
  public override StandardValuesCollection GetStandardValues
      (System.ComponentModel.ITypeDescriptorContext context)
  {
    // Try to get a store from the current context
    // "context.Instance"  returns the element(s) that
    // are currently selected i.e. whose values are being
    // shown in the property grid.
    // Note that the user could have selected multiple objects,
    // in which case context.Instance will be an array.
    Store store = GetStore(context.Instance);

    List<string> values = new List<string>();

    if (store != null)
    {
      values.AddRange(store.ElementDirectory
        .FindElements<ExampleElement>()
        .Select<ExampleElement, string>(e =>
      {
        return e.Name;
      }));
    }
    return new StandardValuesCollection(values);
  }

  /// <summary>
  /// Attempts to get to a store from the currently selected object(s)
  /// in the property grid.
  /// </summary>
  private Store GetStore(object gridSelection)
  {
    // We assume that "instance" will either be a single model element, or
    // an array of model elements (if multiple items are selected).

    ModelElement currentElement = null;

    object[] objects = gridSelection as object[];
    if (objects != null && objects.Length > 0)
    {
      currentElement = objects[0] as ModelElement;
    }
    else
    {
        currentElement = gridSelection as ModelElement;
    }

    return (currentElement == null) ? null : currentElement.Store;
  }

}

プログラムコードにおけるモデル内の移動およびモデルの更新

次の方法で共有

プロパティウィンドウをカスタマイズする

名前、説明、カテゴリ

スタイル機能を公開する

既定のプロパティ転送の場合

プロパティ転送を追加する

別の要素からプロパティを転送する

カスタムプロパティエディター

外部型を持つドメインプロパティを定義する

プロパティエディターを設定する

ファイル名ドメインプロパティを定義する

独自のプロパティエディターを定義する

値のドロップダウンリストを提供する

フィードバック

その他のリソース

次の方法で共有

プロパティ ウィンドウをカスタマイズする

名前、説明、カテゴリ

スタイル機能を公開する

転送: 関連する要素のプロパティを表示する

既定のプロパティ転送の場合

プロパティ転送を追加する

別の要素からプロパティを転送する

カスタム プロパティ エディター

外部型を持つドメイン プロパティを定義する

プロパティ エディターを設定する

ファイル名ドメイン プロパティを定義する

独自のプロパティ エディターを定義する

値のドロップダウン リストを提供する

関連するコンテンツ

フィードバック

その他のリソース

プロパティウィンドウをカスタマイズする

カスタムプロパティエディター

外部型を持つドメインプロパティを定義する

プロパティエディターを設定する

ファイル名ドメインプロパティを定義する

独自のプロパティエディターを定義する

値のドロップダウンリストを提供する