自作コントロールを使い易くする(説明表示系)

.NETで自作コントロールを作成した場合、完成度を高めるためにも説明表示系の対応は、やっておくべきだと思う。

以下の様に、TextBox を継承した CurrencyTextBox クラスを作成したとする。なお、このクラス自体は説明の為だけに作ってあり、全く実用にはならない手抜きコードである事は了承してもらいたい。

---

using System;
using System.Windows.Forms;

namespace Acha_ya.SampleClass
{
    /// <summary>
    /// 金額入力用の TextBox クラスです。
    /// </summary>
    public class CurrencyTextBox : TextBox
    {
        /// <summary>
        /// コンストラクタ
        /// </summary>
        public CurrencyTextBox()
        {
            base.TextAlign = HorizontalAlignment.Right;
        }
        private long currencyValue = 0;
        public long CurrencyValue
        {
            get
            {
                return currencyValue;
            }
            set
            {
                currencyValue = value;
                base.Text = value.ToString();
                if (ValueChanged != null) ValueChanged(this, EventArgs.Empty);
            }
        }
        public event EventHandler ValueChanged;
    }
}

---

これをクラスライブラリとしてコンパイルし、VisualStadioのツールボックスとして登録すれば、フォームへの CurrecyTextBox コントロール貼り付けが可能になる。

実際にそうして、プロパティウィンドウを表示してみた。

追加したCurrencyValueプロパティやValueChangedイベントがプロパティウィンドウに表示され、これらに対する設定が可能になっている。
一方で、これらは「その他」に表示され、プロパティウィンドウ下部にある説明欄も未表示のままである。したがって、これらを改良してみる。詳細な説明は省くが、これらはCategoryAttribute,DescriptionAttribute の属性を設定する事で解決する。実際のコード記述例は以下の様にする。

using System;
using System.Windows.Forms;
using System.ComponentModel;
...
[Category("表示")]
[Description("コントロール内のテキスト内容を数値で返します。")]
[DefaultValue(0L)]
public long CurrencyValue
{
    ...
}
[Category("アクション")]
[Description("コントロール内の金額を変更したときに発生します。")]
public event EventHandler ValueChanged;

CurrencyValue プロパティには、ついでにデフォルト値も設定した。ここでは型がlongなので、0ではなく、0Lと明示的にlong型の定数である事を示す必要がある事には注意が必要だ。

これで再コンパイル後、プロパティウィンドウを見た結果である。

カテゴリーが指示された処にプロパティが表示され、説明も表示される様になった。また、CurrencyValue はデフォルト値の 0 で字体がボールド表示ではなくなった。

これでプロパティウィンドウ関連の対応は終了です。でも、これだけは不十分です。
実際に使用するアプリで、コードを書いてみるとインテリセンスにより、CurrencyValueが表示されます。これを選択した場合、次の様に表示される筈です。

次に、隣の Cursor プロパティを選択してみましょう。

Cursor プロパティでは、「マウス ポインタが～」の説明が表示されています。これは、実際に記述してあるコードにマウスポインタを移動した時にも表示される、ツールチップヘルプです。

ツールチップヘルプに対応する必要がありますが、これはどうすればいいのかと言うと、XMLコメントを作成する事です。従って、再度CurrencyTextBox クラスを修正し、XMLコメントを作成してやる必要があります。ここで以下のように記述したとします。

/// <summary>
/// コントロール内のテキスト内容を数値で取得または設定します。
/// </summary>
[Category("表示")]
[Description("コントロール内のテキスト内容を数値で返します。")]
[DefaultValue(0L)]
public long CurrencyValue
{
    ...
}
/// <summary>
/// CurrencyValue プロパティが変更されたときに発生します。
/// </summary>
[Category("アクション")]
[Description("コントロール内の金額を変更したときに発生します。")]
public event EventHandler ValueChanged;

更に、プロジェクトの設定でXMLドキュメントファイルを出力する様に指示します。この時、出力ファイル名をアセンブリ名と同じ名前＋拡張子の".xml"に指定します。出力先も、dllファイルの出力先に合わせる必要があります。

さて、ここで無事XMLドキュメントファイルが生成されたとします。しかし、キャッシュが効いているのか、そのまま先程のコードでツールチップヘルプを表示しようとしても、表示されない事があります。XMLコメントを修正した場合も、修正前の内容が表示される事からも、こういった確認の際には、一度VisualStudioを終了した後に、再度立ち上げてから確認する手続きをした方がいいようです。最終結果のハードコピーです。

XMLコメントの内容が表示されているのが確認できると思います。これで説明表示系への対応は完了です。
最後にここで使ったサンプルのプロジェクト一式をcab形式に圧縮して置いておく。

「Sample.cab」をダウンロード