基本的な使い方 |
このトピックでは、マスクコントロールの基本的な使用方法について解説します。
マスクコントロールでは正規表現による書式設定が可能です。書式の設定は FieldSet プロパティで参照される MaskFieldSet オブジェクトによって行われ、フィールドとよばれる入力領域を構成する要素によって定義されます。フィールドについては、「書式を設定する」で詳しく解説します。
Visual Studio のデザインページ上で書式を設定するには、次の2通りのデザイン機能のいずれかを実行します。
マスクコントロールで設定可能な3種類のフィールドを組み合わせて書式を設定する方法です。プロパティウィンドウの Fields プロパティから開かれる[フィールドコレクションエディタ]を使用して設定することができます。
正規表現のキーワード(メタ文字)を設定することで書式を設定します。郵便番号のような一般的な定型書式が予めビルトイン書式として用意されているため、これらのリストから書式を選択するだけで簡単に書式を定義することが可能です。
キーワードから書式を設定するには、プロパティウィンドウの FieldSet プロパティを参照し、ドロップダウンリストから使用するキーワードを選択するか、をクリックして表示される[書式の設定]ダイアログを使用して書式を編集します。
キーワードを使って設定した書式は、フィールドオブジェクトのコレクションに変換されます。フィールドオブジェクトに変換された後はフィールドコレクションエディタで編集できるようになります。
各フィールドのフォントや色といったスタイルを設定することができます。
各フィールドオブジェクトには、デザイン機能で設定可能なプロパティのほかに、フィールド間のフォーカスの移動によって発生するイベントやメソッドも備えています。
ShowLiterals プロパティを使えば、入力中にリテラル文字列を表示するかどうかを指定できます。リテラル文字とは、MaskLiteralField (リテラルフィールド)で定義された文字列をそのまま表示する文字列をいいます。
また、入力パターンフィールドには、プロンプト文字を設定することができます。プロンプト文字は PromptChar プロパティを使用します。プロンプト文字を使用することで、入力フィールドを明示的に表示したり入力文字数を視覚的に表すことができます。
Value プロパティを使えば、リテラル文字列とプロンプト文字列を除いたコントロール内の文字列を取得または設定できます。たとえば、Text プロパティに「郵便番号:981-3205」が設定されているときには、Value プロパティの値は「9813205」となります。
Value プロパティが変更されると、その変更は DisplayText プロパティと Text プロパティにも適用されます。また、IsFull プロパティによって、すべてのフィールドに値が入力されているかどうかを確認することが可能です。
クリップボードにリテラル文字を含まない値を渡すには、ClipContent プロパティと SelectedText プロパティを使用します。ClipContent プロパティで制御できるのは、SelectedText プロパティの値のみなので、以下のプロパティの値をクリップボードに設定した場合は、ClipContent プロパティの設定は無効になります。なお、プロンプト文字列は、ClipContent プロパティの設定に関わらず常にクリップボードに渡されます。
以下のサンプルコードは、ClipContent プロパティを使って、リテラル文字列を省いた文字列をクリップボードにコピーする方法を示します。ボタンをクリックすると、クリップボードにコピーされた内容を表示します。
private void Button_Click(object sender, RoutedEventArgs e) { // コントロールに値を設定して、クリップボードにコピーします。 GcMask1.Value = "9813205"; GcMask1.ClipContent = GrapeCity.Windows.InputMan.ClipContent.ExcludeLiterals; GcMask1.SelectionStart = 0; GcMask1.SelectionLength = GcMask1.Text.Length; Clipboard.SetText(GcMask1.SelectedText); // クリップボードのデータを取得して確認します。 TextBlock1.Text = Clipboard.GetText(); }
WatermarkNull プロパティおよび WatermarkDisplayNull プロパティを使用すれば、コントロールが未入力のときに代わりに透かし表示するテキストを文字列として設定することができます。
コントロールにフォーカスがあるときの透かし表示テキストを設定するには WatermarkNull プロパティを、コントロールにフォーカスがないときの透かし表示テキストを設定するには WatermarkDisplayNull プロパティを使用します。
なお、WatermarkNullForeground プロパティおよび WatermarkDisplayNullForeground プロパティを使用することにより、それぞれのテキストを表示する際の前景色を指定することができます。
AutoConvert プロパティを True に設定すると、MaskFieldSetFields プロパティのパターンフィールド(MaskPatternField)で設定された書式に基づいて、変換可能な文字はすべて自動的に変換されます。たとえば、書式が" \A{8} "のように設定されていると、小文字を入力しても自動的に大文字に変換されます。また、全角文字だけが許可されている場合は、入力された半角文字は全角文字に変換されます。
コントロール内部で行われる自動変換の手順を以下に示します。
半角カタカナ、全角カタカナ、およびひらがなは、次のように変換されます。
EditMode プロパティを使って、コントロールがフォーカスを受け取ったときのデフォルトの編集モードを定義できます。EditMode プロパティを EditMode.Insert にすると挿入モード、EditMode.Overwrite にすると上書きモードになります。また、EditMode.FixedInsert と EditMode.FixedOverwrite では、編集モードが固定されるので、実行中に[Ins]キーが押されても編集モードは切り替わりません。
EditMode プロパティが EditMode.Insert または EditMode.Overwrite に設定されているときに[Ins]キーを押したり、EditMode プロパティの値を変更したりすることで、編集モードが切り替わった場合には、EditStatusChanged イベントが発生します。また、フォーカス取得時の編集モードは、IsOverwrite プロパティを使って調べることができます。
以下のサンプルコードは、IsOverwrite プロパティを使用して編集モードを常に監視します
private void GcMask1_EditStatusChanged(object sender, RoutedEventArgs e) { // 編集モードが切り替えられた場合に呼び出されます CheckEditMode(); } private void GcMask1_GotFocus(object sender, RoutedEventArgs e) { CheckEditMode(); } private void CheckEditMode() { // 編集モードをチェックします if (GcMask1.IsOverwrite == true) TextBlock1.Text = "上書き"; else TextBlock1.Text = "挿入"; }
ShowRecommendedValue プロパティを使用すると、マスクコントロールで値が未入力のとき、入力候補となる値をグレー表示することができます。入力候補として表示されたマスクの値は、表示された候補値のまま適用するか、その一部もしくは全ての値を変更して入力値として適用することができます。入力候補として表示される値は、RecommendedValue プロパティで設定します。
候補として表示された値を確定するには、ApplyRecommendedValueCommand ショートカットコマンドとして定義されているキー(既定では [Ctrl]+[Enter]キー)を押下します。MaskPatternField.ApplyRecommendedValue メソッドあるいは MaskEnumerationField.ApplyRecommendedValue メソッドを使って入力値として適用することもできます。
HighlightText プロパティを使用すると、フォーカスを受け取ったときのテキストの選択状態を設定することができます。HighlightText.All の場合は、コントロールのすべてのテキストが選択状態になります。HighlightText.Field の場合は、コントロール内のフィールドの1つを選択状態にすることができます。
HighlightText の値 | キャレットまたはフィールドの状態 |
---|---|
None | キャレットは、DefaultActiveFieldIndex プロパティで指定したフィールドの先頭に位置します。DefaultActiveFieldIndex プロパティが -1 のとき、キャレットの位置は SelectionStart プロパティと SelectionLength プロパティの設定で決まります。 |
Field | DefaultActiveFieldIndex プロパティで指定したフィールドが選択状態になります。DefaultActiveFieldIndex プロパティが -1 のときは、SelectionStart プロパティで設定された文字以降の最初のフィールドが選択状態になります。SelectionStart 以降がすべてリテラル文字の場合は、前のフィールドが選択状態になります。 |
All | DefaultActiveFieldIndex プロパティの設定に関わらず、コントロール内のすべての内容が選択状態になります。 |
コントロールからフォーカスが移動した後もコントロールのハイライト表示を保持するには、HideSelection プロパティを使用します。
コントロールの一部分のみ選択状態にするには、SelectionStart プロパティと SelectionLength プロパティを組み合わせて使用します。
以下のサンプルコードは、コントロールがフォーカスを受け取った時にコントロール内の最初の文字列から3文字を選択します。
private void GcMask1_GotFocus(object sender, RoutedEventArgs e) { GcMask1.SelectionStart = 0; GcMask1.SelectionLength = 3; }
注意 |
---|
GotFocus イベント内にて SelectionStart と SelectionLength の各プロパティを使って選択範囲を指定した場合は、これらのプロパティの設定が HighlightText プロパティの設定よりも優先されます。 |
コントロールに文字列を入力すると、TextChanged イベントの前(入力された文字列が Text プロパティに渡される前)に TextChanging イベントが発生します。このイベント内で入力文字列をチェックすることにより、Text プロパティの値に影響を与えることなく、入力を制御できます。