基本的な使い方 |
このトピックでは、数値コントロールの基本的な使用方法について解説します。
数値コントロールでは書式設定により、数値の入力および表示書式を自由に設定することができます。入力書式は、コントロールが入力フォーカスを受け取ったときの書式で、表示書式は入力フォーカスのないときの書式です。
入力書式の設定は、FieldSet プロパティで参照される NumberFieldSet オブジェクトによって行われ、フィールドとよばれる入力領域を構成する要素によって定義されます。また、表示書式の設定は DisplayFieldSet プロパティで参照される NumberDisplayFieldSet オブジェクトによって行われ、同様にフィールドによって定義します。フィールドについては、「書式を設定する」で詳しく解説します。
Visual Studio のデザインページ上で書式を設定するには、次の3通りのデザイン機能のいずれかを実行します。
数値コントロールで設定可能なフィールドを組み合わせて書式を設定する方法で、表示書式を設定する場合のみ利用できます。プロパティウィンドウの NumberDisplayFieldSetDisplayFields プロパティから開かれる[フィールドコレクションエディタ]を使用して書式を設定します。
メモ |
---|
プロパティウィンドウの NumberDisplayFieldSetDisplayFields プロパティにアクセスするには、DisplayFieldSet プロパティのをクリックします。 |
この方法は、入力書式を設定する場合のみ利用できます。プロパティウィンドウの FieldSet プロパティを展開した際に表示される、各フィールドのプロパティを使用して書式を設定します。
キーワードを設定することで書式を設定します。個々のフィールドのプロパティは設定できませんが、一般的な数値のフォーマットが予めビルトイン書式として用意されているため、これらのリストから書式を選択するだけで簡単に書式を定義することが可能です。
キーワードから書式を設定するには、プロパティウィンドウの FieldSet プロパティあるいは DisplayFieldSet プロパティを参照し、ドロップダウンリストから使用するキーワードを選択するか、をクリックして表示される[入力書式の設定]ダイアログあるいは[表示書式の設定]ダイアログを使用して書式を編集します。
キーワードを使って設定した書式は、フィールドオブジェクトのコレクションに変換されます。フィールドオブジェクトに変換された後はフィールドコレクションエディタあるいはプロパティウィンドウで編集できるようになります。
各フィールドのフォントや色といったスタイルを設定することができます。
各フィールドオブジェクトには、デザイン機能で設定可能なプロパティのほかに、フィールド間のフォーカスの移動によって発生するイベントやメソッドも備えています。
フィールドを設定する際に NumberSignPrefixField オブジェクトあるいは NumberSignSuffixField オブジェクトの NegativePattern プロパティを使用して、マイナス値が入力された際に表示する接頭辞/接尾辞文字列を指定することが可能です。また、NegativeForeground プロパティを使用して、マイナス値が入力された場合の文字色を設定することができます。
デフォルトでは、[+] キー、および [-] キーは、それぞれ入力値をプラス値/マイナス値に切り替えるスイッチとして動作します。値がプラス値のときに [-] キーを押すとマイナス値に、値がマイナス値のときに [+]キー を押すとプラス値に、それぞれ切り替わります。なお、値がマイナス値のときに [-] キーを押しても、値はプラス値にはならず、マイナス値のままとなります。
また、SwitchSignCommand ショートカットコマンドを使用することで、プラス値/マイナス値を交互に切り替えるトグルボタンの機能を、特定のキーに対して割り当てることができます。
以下のサンプルコードは、[PageUp] キーをクリックするたびに、入力値のプラス値/マイナス値を交互に切り替えます。
using GrapeCity.Windows.InputMan; using GrapeCity.Windows.InputMan.Extension; var collection = new InputBindingCollection(); collection.Add(new KeyBinding(GcNumber.SwitchSignCommand, KeyEx.PageUp, ModifierKeys.None)); GcNumber1.SetValue(InputBindingHelper.InputBindingsProperty, collection);
Value プロパティを使えば、リテラル文字列を除いたコントロール内の数値を Decimal 型で取得または設定できます。たとえば、Text プロパティに「\ 50,000.-」が設定されているときには、Value プロパティの値は「50000」となります。
Value プロパティが変更されると、その変更は DisplayText プロパティと Text プロパティにも適用されます。
クリップボードにリテラル文字を含まない値を渡すには、ClipContent プロパティと SelectedText プロパティを使用します。ClipContent プロパティで制御できるのは、SelectedText プロパティの値のみなので、以下のプロパティの値をクリップボードに設定した場合は、ClipContent プロパティの設定は無効になります。
以下のサンプルコードは、ClipContent プロパティを使って、リテラル文字列を省いた文字列をクリップボードにコピーする方法を示します。ボタンをクリックすると、クリップボードにコピーされた内容を表示します。
using GrapeCity.Windows.InputMan; private void Button1_Click(object sender, RoutedEventArgs e) { // コントロールに値を設定して、クリップボードにコピーします。 GcNumber1.FieldSet.SignPrefix.PositivePattern = "\\"; GcNumber1.FieldSet.SignPrefix.NegativePattern = "\\-"; GcNumber1.Value = 10000; GcNumber1.ClipContent = ClipContent.ExcludeLiterals; GcNumber1.SelectionStart = 0; GcNumber1.SelectionLength = GcNumber1.Text.Length; Clipboard.SetText(GcNumber1.SelectedText); // クリップボードのデータを取得して確認します。 TextBlock1.Text = Clipboard.GetText(); }
数値コントロールで、ゼロを削除し値を Null とすることができるかどうかは、 AllowDeleteToNull プロパティで設定します。
AllowDeleteToNull プロパティを True に設定することで、入力された「0」を [Delete] キーや [BackSpace] キーで削除し、その Value プロパティを Null にすることができます。
WatermarkNull プロパティおよび WatermarkDisplayNull プロパティを使用すれば、コントロールが未入力のときに代わりに表示する透かし表示テキストを文字列として設定することができます。
コントロールにフォーカスがあるときの透かし表示テキストを設定するには WatermarkNull プロパティを、コントロールにフォーカスがないときの透かし表示テキストを設定するには WatermarkDisplayNull プロパティを使用します。
また、値が0のときに表示する透かし表示テキストを設定することもできます。フォーカスがあるときのテキストは WatermarkZero プロパティで、フォーカスがないときの透かし表示テキストは WatermarkDisplayZero プロパティで設定します。
なお、WatermarkNullForeground、WatermarkDisplayNullForeground、WatermarkZeroForeground、および WatermarkDisplayZeroForeground の各プロパティを使用することにより、それぞれのテキストを表示する際の前景色を指定することができます。
EditMode プロパティを使って、コントロールがフォーカスを受け取ったときのデフォルトの編集モードを定義できます。EditMode プロパティを EditMode.Insert にすると挿入モード、EditMode.Overwrite にすると上書きモードになります。また、EditMode.FixedInsert と EditMode.FixedOverwrite では、編集モードが固定されるので、実行中に[Ins]キーが押されても編集モードは切り替わりません。
EditMode プロパティが EditMode.Insert または EditMode.Overwrite に設定されているときに[Ins]キーを押したり、EditMode プロパティの値を変更したりすることで、編集モードが切り替わった場合には、EditStatusChanged イベントが発生します。また、フォーカス取得時の編集モードは、IsOverwrite プロパティを使って調べることができます。
以下のサンプルコードは、IsOverwrite プロパティを使用して編集モードを常に監視します。
private void GcNumber1_EditStatusChanged(object sender, RoutedEventArgs e) { // 編集モードが切り替えられた場合に呼び出されます。 CheckEditMode(); } private void GcNumber1_GotFocus(object sender, RoutedEventArgs e) { CheckEditMode(); } private void CheckEditMode() { // 編集モードをチェックします。 if (GcNumber1.IsOverwrite == true) TextBlock1.Text = "上書き"; else TextBlock1.Text = "挿入"; }
ShowRecommendedValue プロパティを使用すると、数値コントロールで値が未入力のとき、入力候補となる値をグレー表示することができます。入力候補として表示された数値は、表示された候補値のまま適用するか、全ての値を変更して入力値として適用することができます。入力候補として表示される値は、RecommendedValue プロパティで設定します。
候補として表示された値を確定するには、ApplyRecommendedValueCommand ショートカットコマンドとして定義されているキー(既定では [Ctrl]+[Enter]キー)を押下します。
HighlightText プロパティを使用すると、フォーカスを受け取ったときのテキストの選択状態を設定することができます。コントロールからフォーカスが移動した後もコントロールのハイライト表示を保持するには、HideSelection プロパティを使用します。
コントロールの一部分のみ選択状態にするには、SelectionStart プロパティと SelectionLength プロパティを組み合わせて使用します。
以下のサンプルコードは、コントロールがフォーカスを受け取った時にコントロール内の最初の文字列から3文字を選択する例です。
private void GcNumber1_GotFocus(object sender, RoutedEventArgs e) { GcNumber1.SelectionStart = 0; GcNumber1.SelectionLength = 3; }
注意 |
---|
GotFocus イベント内にて SelectionStart プロパティと SelectionStart プロパティを使って選択範囲を指定した場合は、これらのプロパティの設定が HighlightText プロパティの設定よりも優先されます。 |
MaxValue プロパティおよび MinValue プロパティを使用して、入力可能な値の最大値および最小値を指定することができます。
最大値および最小値を指定した場合、スピンボタンによる値の増減は、指定された値範囲内に限定されます。
また、検証機能を使用して、指定した値範囲を超える値を入力した場合のエラーメッセージおよび動作を指定することができます。詳しくは、「入力値の検証」を参照してください。
以下のサンプルコードは、値範囲を 10~150 に設定します。
現在キャレットが置かれているフィールドは、ActiveField プロパティで取得できます。
コントロールに文字列を入力すると、TextChanged イベントの前(入力された文字列が Text プロパティに渡される前)に TextChanging イベントが発生します。このイベント内で入力文字列をチェックすることにより、Text プロパティの値に影響を与えることなく、入力を制御できます。