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?

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.
Max	Girilebilecek en büyük sayı. Üstüne çıkılamaz.
Precision	Ondalık basamak sayısı. Ör. 2 ise iki haneye yuvarlanır.
Step	Yukarı / aşağı oklarıyla değerin kaçar kaçar değişeceği.
OnlyNumber	Yalnızca tam sayı girişine izin verir; ondalık engellenir.
UseThousandSeparator	Binlik ayırıcı gösterir (ör. 1.250.000).
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ı.
Text Align	Sayının hizası (genelde sağa yaslanır).
Title	Fareyle üzerine gelince çıkan ipucu yazısı.
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. NumberBox'ın 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; geçersiz girişi burada engelleyebilirsiniz.

İ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 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:

// Oku
decimal? tutar = Document1.Controls["NumberBox1"].Value;

// 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);
    }
}

İpuçları

• Min ve Max özelliklerini ayarlayarak değer aralığını kod yazmadan sınırlayabilirsiniz.
• 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.
• Değer null olabilir; sunucuda hesaba katmadan önce ?? 0 ile boş durumu güvene alın.

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, Max, Precision, Step, OnlyNumber, UseThousandSeparator, ReadOnly, Required, Tab Index

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

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

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