MaskInput

Kullanıcının girişini belirli bir biçime (maskeye) zorlayan nesnedir. Telefon, TC kimlik, IBAN ya da posta kodu gibi sabit kalıbı olan alanlarda kullanıcının yanlış biçimde veri girmesini engeller.

Değer tipi: string

Ne zaman kullanılır?

Girişin belli bir kalıba uyması gerektiğinde kullanın: telefon numarası, TC kimlik numarası, IBAN, plaka, posta kodu. Serbest metin için TextBox, uzun metinler için TextArea daha uygundur. Maske yalnızca biçimi denetler; alanın gerçekten dolu olup olmadığını Required ile zorlarsınız.

Tasarımcı özellikleri

Bir MaskInput seçildiğinde Özellik Görüntüleyici sekmelere ayrılır.

General

Özellik	Açıklama
Name	Nesnenin koddaki adı (ör. MaskInput1). Koddan bu adla erişirsiniz.
Field Name	Veritabanındaki alanın adı.
Size	Alanın veritabanındaki uzunluğu.

Label

Nesnenin yanındaki etiketi yönetir.

Özellik	Açıklama
Caption / Text	Etiketin yazısı (çok dilli olabilir).
Position	Etiketin yeri: solda (Left) veya üstte (Top).
Width / Height	Etiketin boyutu.
Font	Yazı tipi, kalın / italik / altı çizili.
Show Colon	Etiketin sonuna iki nokta (:) ekler.
Horizontal Align / Vertical Align	Etiketin hizası.
Visible	Etiketi gösterir veya gizler.

Behavior

Özellik	Açıklama
Mask	Girişin uyacağı biçim kalıbı. Maske karakterleriyle yazılır (ör. (999) 999 99 99). En önemli özelliktir.
FormatChars	Maskede kullanılacak özel karakterlerin (joker karakterlerin) tanımı. Hangi karakterin rakam, harf ya da alfanumerik anlamına geleceğini belirler.
MaxLength	En fazla kaç karakter girilebileceğini sınırlar.
ReadOnly	Alanı salt okunur yapar.
Required	Alanı zorunlu yapar; boşsa form kaydedilmez.
Tab Index	Tab tuşuyla geçiş sırasını belirler.

Appearance

Özellik	Açıklama
Visible / Client Visible	Nesnenin görünürlüğü.
Enabled / Client Enabled	Nesnenin aktif olup olmadığı.
Placeholder	Alan boşken görünen soluk ipucu yazısı (çok dilli olabilir).
Text Align	Yazının hizası.
Title	Üzerine gelince çıkan ipucu yazısı (çok dilli olabilir).
Size Type	Genişlik davranışı (sabit / esnek).

Olaylar

Bir nesne açılırken olaylar belirli bir sırayla tetiklenir; kullanıcı alana dokununca da ayrı olaylar çalışır. Doğru kodu doğru olaya yazmak için bu sırayı bilmek işinizi kolaylaştırır.

Açılış sırası: OnInit → OnLoad → OnDataLoad → OnPreRender → OnRender

Kullanıcı yazarken: OnTextChanging → OnTextChanged, alandan çıkınca OnValueChanging → OnValueChanged

Olaylar iki tarafta çalışabilir: sunucu olayları C# kodunda, istemci olayları tarayıcıdaki TypeScript kodunda. MaskInput'un iki tarafta sunduğu olaylar farklıdır.

Sunucu olayları (Server)

Olay	Ne zaman çalışır
OnInit	Form açılırken nesne oluşturulduğunda, en başta.
OnLoad	OnInit'in hemen ardından, nesne yüklenince.
OnRender	Nesne ekrana çizilirken.
OnTextChanging	Kullanıcı yazarken, metin değişmeden hemen önce.
OnTextChanged	Metin değiştikten hemen sonra.
OnValueChanging	Değer değişmeden hemen önce (iptal edilebilir).
OnValueChanged	Kullanıcı alandan çıkıp değer kesinleştiğinde. En sık kullanılan olaydır.
OnValidating	Değer doğrulanırken; maskeye uygunluk denetimi sırasında çalışır.

İstemci olayları (Client)

Sunucudaki olaylara ek olarak tarayıcı tarafında şunlar da vardır:

Olay	Ne zaman çalışır
OnDataLoad	Nesnenin verisi yüklendiğinde.
OnPreRender	Nesne ekrana çizilmeden hemen önce.
OnClick / OnDoubleClick	Nesneye tıklanınca / çift tıklanınca.
OnPropertyChanging / OnPropertyChanged	Bir özellik kodla değiştirilmeden önce / sonra.

Olay parametreleri

OnValueChanging / OnTextChanging olaylarının parametresi (args TS, e C#) şunları taşır:

• newValue / NewValue — girilmek istenen yeni değer
• oldValue / OldValue — önceki değer
• cancel / Cancel — true yapılırsa değişiklik iptal edilir (yalnızca Changing olaylarında)

Changed olaylarında cancel yoktur (değişiklik artık gerçekleşmiştir).

Kod örnekleri

Bir MaskInput'a üç yerden erişebilirsiniz. Sunucu örnekleri turuncu, istemci örnekleri kırmızı çerçevelidir. MaskInput'un değeri her zaman string'tir.

Form kodu (C#, sunucu)

Form kodunda nesneye doğrudan adıyla erişirsiniz:

// Oku
string telefon = MaskInput1.Value.ToString();

// Yaz
MaskInput1.Value = "(532) 123 45 67";
MaskInput1.Text  = "(532) 123 45 67";

Akış (Flow) kodu (C#, sunucu)

Akış kodunda nesneye Document1.Controls üzerinden erişirsiniz:

// Oku
string telefon = Document1.Controls["MaskInput1"].Value.ToString();

// Yaz
Document1.Controls["MaskInput1"].Value = "(532) 123 45 67";
Document1.Controls["MaskInput1"].Text  = "(532) 123 45 67";

İstemci kodu (TypeScript, tarayıcı)

İstemci tarafında nesnelere this. ile erişilir ve özellik adları küçük harfle yazılır (value, text):

this.MaskInput1.value = "";
this.MaskInput1.text  = "";

.Value mi .Text mi?

.Value saklanan değerdir, .Text ekranda görünen metindir. MaskInput'ta .Text maske karakterleriyle birlikte (ör. parantez ve boşluklar) görünen metni taşır. Kayıtta hangi biçimde tutmak istediğinize göre ikisini de bilinçli set edin.

Örnek: değeri doğrulama (OnValueChanging)

OnValueChanging değer değişmeden hemen önce çalışır; istemediğiniz bir değeri burada iptal edebilirsiniz. Aşağıdaki örnekte boş bir numara girilmesi engellenir.

İstemci (TypeScript):

async MaskInput1_OnValueChanging(args: Controls.EventArgs.IPropertyChangingEventArgs<string>) {
    if (args.newValue == "") {
        args.cancel = true;                                  // Değer değişimini iptal eder
        this.showMessage("Uyarı", "Telefon numarası boş bırakılamaz.", "Validation");
    }
}

Sunucu (C#):

void MaskInput1_OnValueChanging(object sender, PropertyChangingEventArgs<string> e)
{
    if (string.IsNullOrEmpty(e.NewValue))
    {
        e.Cancel = true;
        ShowMessage("Uyarı", "Telefon numarası boş bırakılamaz.",
            Bimser.CSP.FormControls.RuleManager.AlertType.Validation);
    }
}

İpuçları

• Maske yalnızca girişin biçimini denetler; alanın zorunlu olmasını istiyorsanız ayrıca Required özelliğini açın.
• Mask içinde rakam için genellikle 9, harf için a, alfanumerik için * joker karakterleri kullanılır. Hangi karakterin ne anlama geleceğini FormatChars ile özelleştirebilirsiniz.
• Kayıtta numarayı maske karakterleri olmadan (sadece rakam) saklamak istiyorsanız, .Value üzerinden gelen metni kodda temizleyin.
• Biçim zorunluluğu olmayan serbest alanlarda MaskInput yerine TextBox kullanın.

Tüm tasarımcı özellikleri (tam liste)

General: Name, Field Name, Size

Label: Caption, Text, Position, Left, Width, Height, Font (Bold / Italic / Underline), Visible, Show Colon, Horizontal Align, Vertical Align

Behavior: Mask, FormatChars, MaxLength, ReadOnly, Required, Tab Index

Appearance: Visible, Client Visible, Enabled, Client Enabled, Placeholder, Text Align, Title, Text, Value, Size Type

Olaylar (Client): OnInit, OnLoad, OnPreRender, OnRender, OnDataLoad, OnPropertyChanging, OnPropertyChanged, OnClick, OnDoubleClick, OnValueChanging, OnValueChanged, OnTextChanging, OnTextChanged, OnValidating

Olaylar (Server): OnInit, OnLoad, OnRender, OnValueChanging, OnValueChanged, OnTextChanging, OnTextChanged, OnValidating