CheckBox

Kullanıcının tek bir koşulu işaretleyip işaretlemediğini belirten onay kutusu nesnesidir. İşaretliyse true, boşsa false değerini tutar.

Ne zaman kullanılır?

Açık/kapalı, evet/hayır, kabul ediyorum/etmiyorum gibi iki durumlu seçimler için idealdir. Örneğin "Şartları okudum ve kabul ediyorum" ya da "KDV dahil" gibi alanlarda kullanılır. Birden çok seçenekten birini seçtirmek istiyorsanız RadioButton, bir listeden seçim için ComboBox daha uygundur.

Değer tipi: bool

Tasarımcı özellikleri

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

General

Özellik	Açıklama
Name	Nesnenin koddaki adı (ör. CheckBox1). 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
ReadOnly	Onay kutusunu salt okunur yapar; kullanıcı işaretini değiştiremez.
Required	Alanı zorunlu yapar; işaretlenmeden 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ığı.
Label	Onay kutusunun yanındaki yazı (çok dilli olabilir).
Title	Fareyle üzerine gelince çıkan ipucu yazısı (çok dilli olabilir).
Value	Kutunun başlangıç durumu: işaretli (true) veya boş (false).

Olaylar

Bir nesne açılırken olaylar belirli bir sırayla tetiklenir; kullanıcı kutuyu işaretleyince de 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ı işaretleyince: OnValueChanging → OnValueChanged

Olaylar iki tarafta çalışabilir: sunucu olayları C# kodunda, istemci olayları tarayıcıdaki TypeScript kodunda. CheckBox'ı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.
OnValidating	Değer doğrulanırken (zorunlu/koşul kontrolü).
OnValueChanging	Değer değişmeden hemen önce (iptal edilebilir).
OnValueChanged	Kullanıcı kutuyu işaretleyip değer kesinleştiğinde. En sık kullanılan olaydı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 olayının parametresi (args TS, e C#) şunları taşır:

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

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

Kod örnekleri

Bir CheckBox'a üç yerden erişebilirsiniz. Sunucu örnekleri turuncu, istemci örnekleri kırmızı çerçevelidir. Değer bool (mantıksal) tipindedir.

Form kodu (C#, sunucu)

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

// Oku
bool onay = CheckBox1.Value;

// Yaz
CheckBox1.Value = true;

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

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

// Oku
bool onay = Document1.Controls["CheckBox1"].Value;

// Yaz
Document1.Controls["CheckBox1"].Value = true;

İstemci kodu (TypeScript, tarayıcı)

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

// Oku
const onay = this.CheckBox1.value;

// Yaz
this.CheckBox1.value = true;

Değer her zaman dolu gelir

CheckBox'ın değeri hiçbir zaman boş (null) olmaz; ya true ya false'tur. Bu yüzden okurken boş kontrolü yapmanıza gerek kalmaz, doğrudan if (onay) yazabilirsiniz.

Örnek: işaretlemeyi engelleme (OnValueChanging)

OnValueChanging değer değişmeden hemen önce çalışır; istemediğiniz bir durumu burada iptal edebilirsiniz. Aşağıdaki örnekte, başka bir koşul sağlanmadan kutunun işaretlenmesi engellenir.

İstemci (TypeScript):

async CheckBox1_OnValueChanging(args: Controls.EventArgs.IPropertyChangingEventArgs<boolean>) {
    if (args.newValue == true) {
        args.cancel = true;                                  // İşaretlemeyi iptal eder
        this.showMessage("Uyarı", "Önce tutarı girmelisiniz.", "Validation");
    }
}

Sunucu (C#):

void CheckBox1_OnValueChanging(object sender, PropertyChangingEventArgs<bool> e)
{
    if (e.NewValue == true)
    {
        e.Cancel = true;
        ShowMessage("Uyarı", "Önce tutarı girmelisiniz.",
            Bimser.CSP.FormControls.RuleManager.AlertType.Validation);
    }
}

İpuçları

• Onay kutusunu zorunlu yapmak için Required özelliğini kullanın; "Şartları kabul ediyorum" gibi alanlarda kutu işaretlenmeden form kaydedilmez.
• Bir CheckBox işaretlendiğinde başka bir nesneyi gösterip gizlemek için OnValueChanged olayında ilgili nesnenin Visible özelliğini ayarlayın.
• Değer her zaman true ya da false olduğu için if (CheckBox1.Value) yazmanız yeterlidir; ayrıca == true eklemenize gerek yoktur.

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: ReadOnly, Required, Tab Index

Appearance: Client Enabled, Client Visible, Enabled, Label, Title, Value, Visible

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

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