書式の設定

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

書式設定の概要

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

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

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

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

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

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

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

非表示フィールドのデフォルト値

入力書式を変更して非表示のフィールドが存在する場合、Valueプロパティがnull 参照 (Visual Basic では Nothing)になると、その後値が入力されたときに非表示のフィールドの値にはRecommendedValue プロパティの値が設定されます。RecommendedValue プロパティの値がnull 参照 (Visual Basic では Nothing)のときには、直前の「値がクリアされた時間」が設定されます。

以下のサンプルコードでは、時分だけの入力を許可してRecommendedValue プロパティにデフォルト値を設定しています。この場合、時分の入力が行われると、非表示になっている秒の部分には、RecommendedValue プロパティに設定された秒の値が設定されます。

Visual Basic
C#

    ' キーワードから書式を設定します。 
    GcTime1.Fields.AddRange("HH:mm")
    ' RecommendedValueプロパティに非表示フィールドのデフォルト値を設定します。
    GcTime1.RecommendedValue = New TimeSpan(23, 59, 59)
    ' ValueプロパティにNothingを設定します。
    GcTime1.Value = Nothing

    // キーワードから書式を設定します。 
    gcTime1.Fields.AddRange("yyyy/MM");
    // RecommendedValueプロパティに非表示フィールドのデフォルト値を設定します。
    gcTime1.RecommendedValue = new TimeSpan(23, 59, 59);
    // Valueプロパティにnullを設定します。
    gcTime1.Value = null;

自由書式入力

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

Visual Basic
C#

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

' 検証アイテムを作成
Dim GcTimeInvalidValue1 As New GrapeCity.Win.Editors.GcTimeValidator.InvalidValue()
GcTimeValidator1.GetValidateItems(GcTime1).Add(GcTimeInvalidValue1)
' 検証アクション（値をクリア）を作成
Dim ValueProcess1 As New GrapeCity.Win.Editors.ValueProcess()
ValueProcess1.ValueProcessOption = GrapeCity.Win.Editors.ValueProcessOption.Clear
GcTimeValidator1.GetValidateActions(GcTime1).Add(ValueProcess1)

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

// 検証アイテムを作成
GrapeCity.Win.Editors.GcTimeValidator.InvalidValue gcTimeInvalidValue1 = new GrapeCity.Win.Editors.GcTimeValidator.InvalidValue();
gcTimeValidator1.GetValidateItems(gcTime1).Add(gcTimeInvalidValue1);
// 検証アクション（値をクリア）を作成
GrapeCity.Win.Editors.ValueProcess valueProcess1 = new GrapeCity.Win.Editors.ValueProcess();
valueProcess1.ValueProcessOption = GrapeCity.Win.Editors.ValueProcessOption.Clear;
gcTimeValidator1.GetValidateActions(gcTime1).Add(valueProcess1);

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

フィールド操作

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

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

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

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

Visual Basic
C#

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

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

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

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

Visual Basic
C#

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

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

イベントの利用

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

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

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

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