書式の設定

日付時刻コントロールの主要機能である書式フィールドの設定とその活用方法について解説します。

書式設定の概要

日付時刻コントロールの書式には、入力用と表示用の２つがあり、それぞれ入力フィールドと表示フィールドを使って書式を設定します。
入力フィールドを設定するには、Fields プロパティが参照するDateTimeFieldCollection クラスを使用します。DateTimeFieldCollection は、各入力フィールドを表すDateFieldのコレクションを保持するクラスです。

一方、表示フィールドを設定するには、DisplayFields プロパティが参照するDateTimeDisplayFieldCollection クラスを使用します。DateDisplayFieldCollection は、各表示フィールドを表すDateDisplayFieldのコレクションを保持するクラスです。

日付時刻コントロールの書式を設定するには、それぞれのコレクションのAdd メソッドもしくはAddRange メソッドを使用して直接フィールドオブジェクトを追加する方法と、AddRange メソッドのオーバーライドの１つを使用して、キーワード文字列によりフィールドを自動生成する方法があります。それぞれの方法による書式の設定方法については、以下のトピックを参照してください。

リテラル文字とプロンプト文字

ShowLiterals プロパティを使えば、入力中にリテラル文字列を表示するかどうかを指定できます。
リテラル文字とは、DateLiteralField （リテラルフィールド）で定義された文字列をそのまま表示する文字列をいいます。

また、リテラルフィールド以外のフィールドには、プロンプト文字を設定することができます。プロンプト文字を使用することで、入力フィールドを明示的に表示したり入力文字数を視覚的に表すことができます。プロンプト文字はコントロールのPromptChar プロパティを使用して設定できます。なお、各フィールドのPromptChar プロパティを設定するとフィールドごとに異なるプロンプト文字も設定できます。

（図）プロンプト文字（"_"）

（図）月と分フィールドのみ異なるプロンプト文字（"*")

自由書式入力

入力フィールドのコレクションを全て削除すると自由書式入力が可能になります。自由書式入力では、日付に変換可能なあらゆる値を受けつけますが、無効な文字が入力されてもInvalidInput イベントは発生しません。文字列を日付に変換できなかった場合、値はnull 参照 (Visual Basic では Nothing)になりますが、入力された値は次回フォーカス取得時まで保持されます。変換できない値をクリアしたり入力前の値に戻すためには、日付時刻検証コンポーネントを用いて値を検証します。

Visual Basic
C#

' 自由書式入力を行うために、入力フィールドを削除します。
GcDateTime1.Fields.Clear()

' 検証アイテムを作成します。
Dim GcDateTimeInvalidValue1 As New GrapeCity.Win.Editors.GcDateTimeValidator.InvalidValue()
GcDateTimeValidator1.GetValidateItems(GcDateTime1).Add(GcDateTimeInvalidValue1)
' 検証アクション（値をクリア）を作成します。
Dim ValueProcess1 As New GrapeCity.Win.Editors.ValueProcess()
ValueProcess1.ValueProcessOption = GrapeCity.Win.Editors.ValueProcessOption.Clear
GcDateTimeValidator1.GetValidateActions(GcDateTime1).Add(ValueProcess1)

// 自由書式入力を行うために、入力フィールドを削除します。
gcDateTime1.Fields.Clear();

// 検証アイテムを作成します。
GrapeCity.Win.Editors.GcDateTimeValidator.InvalidValue gcDateTimeInvalidValue1 = new GrapeCity.Win.Editors.GcDateTimeValidator.InvalidValue();
gcDateTimeValidator1.GetValidateItems(gcDateTime1).Add(gcDateTimeInvalidValue1);
// 検証アクション（値をクリア）を作成します。
GrapeCity.Win.Editors.ValueProcess valueProcess1 = new GrapeCity.Win.Editors.ValueProcess();
valueProcess1.ValueProcessOption = GrapeCity.Win.Editors.ValueProcessOption.Clear;
gcDateTimeValidator1.GetValidateActions(gcDateTime1).Add(valueProcess1);

なお、自由書式入力に設定した場合は、次の各プロパティが無効になります。

フィールド操作

DefaultActiveField プロパティを使用すると、コントロールがフォーカスを受け取ったときにキャレットを配置するフィールドを指定できます。現在キャレットが置かれているフィールドは、ActiveField プロパティで取得できます。

フィールドコレクション内の特定のフィールドにアクセスする場合、次のいずれかの方法を使うことができます。

インデックスからフィールドにアクセス
キー（文字列）からフィールドにアクセス

コレクションのインデックスがわかっている場合は、インデックスを使ってフィールドを取得することができます。
次のサンプルはインデックスを使ってフィールドを取得する例です。ここでは日付時刻コントロールの3番目のフィールドを取得する例です。

Visual Basic
C#

Dim MyField As GrapeCity.Win.Editors.Fields.DateField = GcDateTime1.Fields(2)

GrapeCity.Win.Editors.Fields.DateField myField = gcDateTime1.Fields[2];

また、インデックスを使わず、設定したキー（文字列）を使って特定のフィールドにアクセスすることもできます。
キーは、各フィールドのName プロパティにキーとして文字列を設定します。

次のサンプルはキーを使ってフィールドを取得する例です。ここでは日付時刻コントロールの特定のフィールドのName プロパティに予め"Key1"という文字列が設定されていることを前提にしています。

Visual Basic
C#

Dim MyField As GrapeCity.Win.Editors.Fields.DateField = GcDateTime1.Fields("Key1")

GrapeCity.Win.Editors.Fields.DateField myField = gcDateTime1.Fields["Key1"];

イベントの利用

コントロールには、フィールド間のキャレットの移動によって発生する２つのイベントが用意されています。

FieldEnter イベント（コントロール内でフィールドがアクティブになったときに発生します。）
FieldLeave イベント（コントロール内でフィールドがアクティブでなくなったときに発生します。）

これらのイベントを使えば、フィールド毎に入力された値をチェックすることや、その値に応じた独自処理の実装など、フィールドを使った細やかな処理の実装を可能になります。

各フィールドクラスには、コントロールのFieldEnter とFieldLeave と同様の機能を持つEnter とLeave イベントが提供されています。これらのイベントを使うことでも、ユーザーは同様の処理を実装することが可能です。しかし、フィールドクラスのイベントの場合、フィールド毎にイベントを実装する必要があることから、動的なフィールド操作や書式の仕様変更などに対しての処理が煩雑になる可能性があることや、デザインウィンドウ上からイベントハンドラを生成できないことなどのデメリットがあるためフィールドクラスのイベントよりもコントロールのイベントを使うことが推奨されます。