NumberBox

Kullanıcının yalnızca sayısal değer girebileceği nesnedir. Tutar, miktar, adet, fiyat ya da yüzde gibi rakamsal alanlar için kullanılır.

Değer tipi: decimal? (Nullable<Decimal>)

Ne zaman kullanılır?

Sayı girilmesi gereken her alanda kullanın: adet, tutar, fiyat, yüzde, ölçü. Ondalık basamak, en küçük / en büyük sınır ve binlik ayırıcı gibi sayıya özel ayarları hazır sunar. Harf ya da karışık metin gereken yerlerde TextBox, belirli bir biçim isteyen alanlarda MaskInput daha uygundur.

Tasarımcı özellikleri

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

General

Özellik	Açıklama
Name	Nesnenin koddaki adı (ör. NumberBox1). Koddan bu adla erişirsiniz.
Field Name	Veritabanındaki alanın adı.

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
Min	Girilebilecek en küçük sayı. Altına inilemez. Tipi decimal?, boş bırakılabilir.
Max	Girilebilecek en büyük sayı. Üstüne çıkılamaz. Tipi decimal?, boş bırakılabilir.
Precision	Ondalık basamak sayısı (int?). Ör. 2 ise iki haneye yuvarlanır.
Step	Yukarı / aşağı oklarıyla değerin kaçar kaçar değişeceği. Tipi decimal (boş olmaz, her zaman bir değeri vardır).
OnlyNumber	Yalnızca tam sayı girişine izin verir; ondalık engellenir (bool?).
UseThousandSeparator	Binlik ayırıcı gösterir (ör. 1.250.000). Tipi bool.
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ı (MultiLanguageText, çok dilli).
Text Align	Sayının hizası (genelde sağa yaslanır).
Title	Fareyle üzerine gelince çıkan ipucu yazısı (MultiLanguageText, çok dilli).
Size Type	Genişlik davranışı (sabit / esnek).

Olaylar

NumberBox'ın kendine ait, koda bağlayabileceğiniz olayları sayı veya metin değişimiyle ilgilidir. Bunların yanında her form nesnesinin ortak olarak taşıdığı çerçeve (lifecycle) olayları da vardır; bunlar NumberBox'a özel değildir, tüm nesnelerden miras gelir.

Kullanıcı yazarken: OnTextChanging → OnTextChanged (görünen metin değişir), değer kesinleşince OnValueChanging → OnValueChanged (sayısal değer değişir).

Olaylar iki tarafta çalışabilir: sunucu olayları C# kodunda, istemci olayları tarayıcıdaki TypeScript kodunda.

NumberBox'a özel olaylar

Bunlar gerçekten NumberBox sınıfının üyesidir ve hem sunucuda hem istemcide bağlanabilir.

Olay	Tip	Ne zaman çalışır
OnValueChanging	PropertyChangingEventArgs<decimal?>	Sayısal değer değişmeden hemen önce (iptal edilebilir).
OnValueChanged	PropertyChangedEventArgs<decimal?>	Değer kesinleştiğinde. En sık kullanılan olaydır.
OnTextChanging	PropertyChangingEventArgs<string>	Görünen metin değişmeden hemen önce (iptal edilebilir).
OnTextChanged	PropertyChangedEventArgs<string>	Görünen metin değiştikten hemen sonra.
OnValidating	ValidatingEventArgs	Değer doğrulanırken. e.Cancel = true ve e.Messages'a bir ValidationMessage ekleyerek geçersiz girişi sunucuda reddedebilirsiniz.

not

OnValidating olayı ValidatingEvent üyesidir

Sınıftaki gerçek üye ValidatingEvent (EventHandler<ValidatingEventArgs>) adını taşır; siz bunu ServerEvents üzerinden ada göre OnValidating(object sender, ValidatingEventArgs e) imzasıyla bağlarsınız.

Çerçeve (framework) olayları

Aşağıdakiler NumberBox'a özel değildir; tüm form nesnelerinin ortak yaşam döngüsü ve istemci olaylarıdır (BaseControl / VisualControl / DataBoundControl üzerinden miras gelir). NumberBox bağlamında değer olaylarıyla karıştırmamak için ayrı tutulmuştur.

Olay	Ne zaman çalışır
OnInit / OnLoad	Nesne oluşturulup yüklenirken (yaşam döngüsü başı).
OnPreRender / OnRender	Nesne ekrana çizilmeden önce / çizilirken.
OnDataLoad	Nesnenin verisi yüklendiğinde.
OnClick / OnDoubleClick	Nesneye tıklanınca / çift tıklanınca (istemci).
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).

.Value mi .Text mi?

.Value saklanan sayısal veridir (decimal?), .Text ise ekranda görünen metindir (string). NumberBox'ta bu ikisi farklı tiptedir: UseThousandSeparator ve Precision ayarları yalnızca .Text görünümünü biçimlendirir; hesap yaparken her zaman .Value üzerinden çalışın. Bu yüzden NumberBox hem ValueChanged (sayı) hem TextChanged (görünen metin) olaylarını ayrı ayrı tetikler.

Kod örnekleri

Bir NumberBox'a üç yerden erişebilirsiniz. Sunucu örnekleri turuncu, istemci örnekleri kırmızı çerçevelidir. Değer decimal? tipindedir, yani boş (null) olabilir.

Form kodu (C#, sunucu)

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

// Oku
decimal? tutar = NumberBox1.Value;

// Yaz
NumberBox1.Value = 1500.75m;

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

Akış kodunda nesneye Document1.Controls üzerinden erişirsiniz. Controls["..."].Value tipi object döndürür; sayıya çevirmek için Convert.ToDecimal kullanın:

// Oku (sayı olarak)
decimal tutar = Convert.ToDecimal(Document1.Controls["NumberBox1"].Value);

// Oku (metin olarak, null güvenli)
string metin = Document1.Controls["NumberBox1"].Value?.ToString();

// Yaz
Document1.Controls["NumberBox1"].Value = 1500.75m;

İstemci kodu (TypeScript, tarayıcı)

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

// Oku
const tutar = this.NumberBox1.value;

// Yaz
this.NumberBox1.value = 1500.75;

Boş değere dikkat edin

NumberBox boş bırakılabilir; bu durumda Value değeri null olur. Sunucuda hesap yapmadan önce boş olup olmadığını kontrol edin: decimal tutar = NumberBox1.Value ?? 0; gibi. Aksi halde boş alan hata verebilir.

Ö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 sıfırdan küçük tutar girilmesi engellenir.

İstemci (TypeScript):

async NumberBox1_OnValueChanging(args: Controls.EventArgs.IPropertyChangingEventArgs<number>) {
    if (args.newValue < 0) {
        args.cancel = true;                                  // Değişikliği iptal eder
        this.showMessage("Uyarı", "Tutar negatif olamaz.", "Validation");
    }
}

Sunucu (C#):

void NumberBox1_OnValueChanging(object sender, PropertyChangingEventArgs<decimal?> e)
{
    if (e.NewValue < 0)
    {
        e.Cancel = true;
        ShowMessage("Uyarı", "Tutar negatif olamaz.",
            Bimser.CSP.FormControls.RuleManager.AlertType.Validation);
    }
}

Örnek: metin değişimini izleme (OnTextChanged)

OnValueChanged sayısal decimal? değerle, OnTextChanged ise ekranda görünen string ile çalışır. Biçimlenmiş gösterimi (binlik ayırıcılı / ondalıklı) izlemeniz gerektiğinde OnTextChanged kullanın:

void NumberBox1_OnTextChanged(object sender, PropertyChangedEventArgs<string> e)
{
    // e.NewValue ekranda görünen biçimlenmiş metindir (ör. "1.500,75")
    // Sayısal değer için NumberBox1.Value kullanın
}

İpuçları

• Min ve Max özelliklerini ayarlayarak değer aralığını kod yazmadan sınırlayabilirsiniz. Her ikisi de boş bırakılabilir (decimal?); ayarlanmazsa sınır uygulanmaz.
• Ondalık istemiyorsanız OnlyNumber özelliğini açın ya da Precision değerini 0 yapın; örneğin adet alanlarında kullanışlıdır.
• Tutar alanlarında UseThousandSeparator özelliğini açarsanız büyük sayılar daha okunaklı görünür. Bu yalnızca .Text görünümünü etkiler; .Value ham sayı olarak kalır.
• Step her zaman bir değere sahiptir (decimal, boş olmaz); Min / Max ise boş bırakılabilir.
• Değer null olabilir; sunucuda hesaba katmadan önce ?? 0 ile boş durumu güvene alın.
• Sunucuda geçersiz girişi reddetmek için OnValidating olayında e.Cancel = true yapıp e.Messages listesine bir ValidationMessage ekleyin.

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

General: Name, Field Name

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

Behavior: Min (decimal?), Max (decimal?), Precision (int?), Step (decimal), OnlyNumber (bool?), UseThousandSeparator (bool), ReadOnly, Required, Tab Index

Appearance: Visible, Client Visible, Enabled, Client Enabled, Placeholder (MultiLanguageText), Text, Text Align, Title (MultiLanguageText), Value (decimal?), Size Type

NumberBox'a özel olaylar: OnValueChanging, OnValueChanged, OnTextChanging, OnTextChanged, OnValidating (ValidatingEvent)

Çerçeve (miras) olayları: OnInit, OnLoad, OnPreRender, OnRender, OnDataLoad, OnClick, OnDoubleClick, OnPropertyChanging, OnPropertyChanged