RadioList

Kullanıcının önceden tanımlı seçenekler arasından tek bir tanesini işaretlediği nesnedir. Tüm seçenekler ekranda radyo düğmesi olarak yan yana ya da alt alta görünür; kullanıcı birini seçtiğinde diğeri otomatik olarak boşalır.

Değer tipi: object (seçili öğenin değeri; ValueType ile temel tipi belirlenir)

RadioList, ComboBoxBase üzerinden ListControl'ten türer; yani Items, DataSource ve Data ile seçenek besleme davranışı ComboBox ile birebir aynıdır. Aradaki fark yalnızca görünümdür: ComboBox açılır liste, RadioList ise hepsi görünen radyo düğmeleri sunar.

Ne zaman kullanılır?

Seçenek sayısı az (genelde 2-5) ve hepsinin aynı anda görünmesi istendiğinde idealdir: cinsiyet, evet/hayır, öncelik (Düşük / Orta / Yüksek) gibi alanlar. Seçenek çok ya da yerden tasarruf gerekiyorsa ComboBox, birden fazla seçim gerekiyorsa CheckBoxList daha uygundur.

Tasarımcı özellikleri

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

General

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

Data Source

Seçeneklerin nereden geldiğini belirleyen sekmedir. Sabit liste girebilir ya da bir veri kaynağına bağlayabilirsiniz.

Özellik	Açıklama
Items	Seçenek listesi (ListItemCollection). Tasarımcıdan elle girilebilir ya da koddan doldurulabilir.
Data Source	Seçeneklerin geleceği veri kaynağı (ör. .mssqlds sorgusu).
Data Source Type	Veri kaynağının türü (statik liste, veri kaynağı vb.).
Data	Seçenekleri koddan vermek için kullanılan satır listesi (List<Dictionary<string,object>>).
Selected Values	(Salt okunur) Seçili değerlerin listesi (List<object>). Yalnızca okunur, atanamaz.
Selected Item Values	Seçili öğelerin ham değerleri (List<object>). Okunabilir ve yazılabilir.
Text Separator	Birden çok metin gösterilirken araya konan ayraç.
Value Separator	Birden çok değer birleştirilirken araya konan ayraç.

Behavior

Özellik	Açıklama
Required	Alanı zorunlu yapar; seçim yapılmazsa form kaydedilmez.
ReadOnly	Alanı salt okunur yapar; kullanıcı seçimi değiştiremez.
AllowClear	Yapılan seçimin temizlenebilmesine (boşa alınmasına) izin verir.
ButtonType	Radyo düğmelerinin görünüm tipi. Değerler: Radio (klasik radyo düğmesi) / Button (buton kümesi).
Direction	Seçeneklerin diziliş yönü. Değerler: Horizontal (yatay) / Vertical (dikey).
ShowSearch	Seçenekler arasında arama kutusu gösterir.
SelectedItem	(Salt okunur) O an seçili olan öğe (ListItem). Atanamaz; seçimi değiştirmek için .Value kullanın.
ValueType	Saklanan değerin temel tipi (PrimitiveType: metin, sayı, tarih).
DateValueFormat	Değer tarih ise kullanılacak tarih biçimi.
DecimalValuePrecision	Değer ondalık ise basamak hassasiyeti.
TabIndex	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	Seçim yapılmadan önce görünen ipucu yazısı (MultiLanguageText).
Title	Nesnenin başlığı (MultiLanguageText, çok dilli olabilir).
Caption	Etiket ayarları (ControlCaption).
Style / Container Style / Custom Class Name	Görsel stil ve CSS sınıfı.

Olaylar

RadioList'in sınıf üyesi olarak sunduğu olaylar sınırlıdır; kullanıcı seçim yaptığında değer ve metin olayları tetiklenir. OnInit / OnLoad / OnDataLoad / OnPreRender / OnRender gibi yaşam döngüsü olayları RadioList'in kendi üyesi değildir; bunlar tüm nesnelerde geçerli çerçeve (framework) olaylarıdır ve istemci tarafında editörden bağlanabilir.

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

Sunucu olayları (Server)

Bunlar sınıf üyesi olarak gerçekten var olan olaylardır:

Olay	Üye adı	Ne zaman çalışır
OnValueChanging	ValueChanging	Seçim değişmeden hemen önce (iptal edilebilir). Parametre tipi PropertyChangingEventArgs<object>.
OnValueChanged	ValueChanged	Kullanıcı seçim yapıp değer kesinleştiğinde. En sık kullanılan olaydır. Parametre tipi PropertyChangedEventArgs<object>.
OnTextChanging	TextChanging	Görünen metin değişmeden hemen önce. Parametre tipi PropertyChangingEventArgs<string>.
OnTextChanged	TextChanged	Görünen metin değiştikten hemen sonra. Parametre tipi PropertyChangedEventArgs<string>.
OnValidating	ValidatingEvent	Alan doğrulanırken. Üyenin gerçek adı ValidatingEvent'tir (salt okunur); editörde OnValidating etiketiyle görünür. Parametre tipi ValidatingEventArgs.

İstemci olayları (Client)

Yukarıdaki olaylara ek olarak, tarayıcı tarafında her nesnede ortak olan çerçeve olayları da editörden bağlanabilir:

Olay	Ne zaman çalışır
OnInit / OnLoad	Nesne oluşturulup yüklendiğinde (çerçeve olayı).
OnDataLoad	Seçeneklerin verisi yüklendiğinde (çerçeve olayı).
OnPreRender / OnRender	Nesne ekrana çizilmeden önce / çizilirken (çerçeve olayı).
OnClick / OnDoubleClick	Nesneye tıklanınca / çift tıklanınca (çerçeve olayı).
OnPropertyChanging / OnPropertyChanged	Bir özellik kodla değiştirilmeden önce / sonra (çerçeve olayı).

Olay parametreleri

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

• newValue / NewValue — seçilmek 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 RadioList'e üç yerden erişebilirsiniz. Sunucu örnekleri turuncu, istemci örnekleri kırmızı çerçevelidir.

Form kodu (C#, sunucu)

Form kodunda nesneye doğrudan adıyla erişirsiniz. RadioList'in değeri object tipindedir:

// Oku
var secilen = RadioList1.Value;                 // seçili öğenin değeri (object)
var deger   = RadioList1.Value?.ToString();     // karşılaştırma için string

// Yaz (seçeneğin değeriyle)
RadioList1.Value = "Yuksek";

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

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

// Oku
var secilen = Document1.Controls["RadioList1"].Value?.ToString();

// Yaz
Document1.Controls["RadioList1"].Value = "Yuksek";

İstemci kodu (TypeScript, tarayıcı)

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

// Oku
const secilen = this.RadioList1.value;

// Yaz
this.RadioList1.value = "Yuksek";

Değer mi metin mi?

.Value seçeneğin saklanan değeridir (ör. "Yuksek"), .Text ise kullanıcının gördüğü metindir (ör. "Yüksek Öncelik"). Veritabanı sorgularında ve karşılaştırmalarda her zaman .Value kullanın.

Örnek: seçenekleri koddan doldurma (Items)

Seçenekleri sabit girmek yerine koddan (ör. bir veri kaynağı satırlarından ya da bir liste döngüsünden) doldurmak en sık ihtiyaç duyulan işlemdir. Items özelliği bir ListItemCollection'dır; her seçenek bir ListItem'dır.

ListItem üyeleri: Value (object), Key (string), Text (MultiLanguageText), Icon (string), Selected (bool).

// Seçenekleri sıfırdan kur
RadioList1.Items = new ListItemCollection();

RadioList1.Items.Add(new ListItem {
    Value    = "Dusuk",
    Key      = "Dusuk",
    Selected = false,
    Text     = new MultiLanguageText(new Dictionary<string, string> { { "tr-TR", "Düşük" } })
});
RadioList1.Items.Add(new ListItem {
    Value = "Orta",
    Key   = "Orta",
    Text  = new MultiLanguageText(new Dictionary<string, string> { { "tr-TR", "Orta" } })
});
RadioList1.Items.Add(new ListItem {
    Value    = "Yuksek",
    Key      = "Yuksek",
    Selected = true,                                 // varsayılan seçili öğe
    Text     = new MultiLanguageText(new Dictionary<string, string> { { "tr-TR", "Yüksek" } })
});

// Veri kaynağına bağlıysa (DataSource/Data) listeyi tazelemek için:
// RadioList1.Reload();

Örnek: seçili öğeyi okuma (SelectedItem / SelectedValues)

SelectedItem (salt okunur) seçili ListItem'ın tamamını verir; tek seferde hem değer hem metni okumak için kullanışlıdır. SelectedValues (salt okunur) ise seçili değerlerin listesidir.

var secili = RadioList1.SelectedItem;            // ListItem (atanamaz)
if (secili != null)
{
    var deger = secili.Value;                    // seçeneğin değeri
    var metin = secili.GetText();                // gösterilen metin (ListItem.GetText())
}

// Tüm seçili değerler (RadioList tekli seçimdir; tek elemanlı gelir)
var degerler = RadioList1.SelectedValues;        // List<object> (salt okunur)

Örnek: seçime göre doğrulama (OnValueChanging)

OnValueChanging seçim değişmeden hemen önce çalışır; istemediğiniz bir seçeneği burada iptal edebilirsiniz. Aşağıdaki örnekte "Iptal" seçilmesi engellenir.

İstemci (TypeScript):

async RadioList1_OnValueChanging(args: Controls.EventArgs.IPropertyChangingEventArgs<any>) {
    if (args.newValue == "Iptal") {
        args.cancel = true;                                  // Seçim değişimini iptal eder
        this.showMessage("Uyarı", "Bu seçenek seçilemez.", "Validation");
    }
}

Sunucu (C#):

void RadioList1_OnValueChanging(object sender, PropertyChangingEventArgs<object> e)
{
    if (e.NewValue?.ToString() == "Iptal")
    {
        e.Cancel = true;
        ShowMessage("Uyarı", "Bu seçenek seçilemez.",
            Bimser.CSP.FormControls.RuleManager.AlertType.Validation);
    }
}

İpuçları

• Seçenekleri sabitlemek için Items, dinamik liste için Data Source kullanın; ikisini aynı anda kullanmayın.
• Koddan seçenek doldururken Items = new ListItemCollection() ile başlayıp ListItem ekleyin; veri kaynağına bağlı listeyi tazelemek için Reload() çağırın.
• SelectedItem ve SelectedValues salt okunurdur; seçimi değiştirmek için bunları atayamazsınız, .Value yazın.
• ButtonType ile görünümü Radio (klasik) ya da Button (buton kümesi) yapabilirsiniz; Direction ile dar formlarda Vertical, geniş formlarda Horizontal dizin.
• Seçenek sayısı 5'i aşıyorsa veya yer darsa RadioList yerine ComboBox tercih edin.
• AllowClear açıkken kullanıcı seçimi tümüyle boşa alabilir; zorunlu alanlarda bunu kapalı tutun.

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

General: Name, Field Name

Data Source: Items, Data, Data Source, Data Source Type, Selected Values (salt okunur), Selected Item Values, Text Separator, Value Separator

Behavior: Required, ReadOnly, AllowClear, ButtonType (Radio / Button), Direction (Horizontal / Vertical), ShowSearch, SelectedItem (salt okunur), ValueType, DateValueFormat, DecimalValuePrecision, TabIndex, Indexable, EntityPath, DefaultEnabled, DefaultClientEnabled, DefaultReadOnly

Appearance: Visible, Client Visible, Enabled, Client Enabled, Placeholder, Title, Caption, Value, Text, Style, Container Style, Custom Class Name, Loading, Context Menu Key / Context Menu Column Key / Context Menu Target

Sınıf üyesi olaylar (gerçek üyeler): ValueChanging, ValueChanged, TextChanging, TextChanged, ValidatingEvent (salt okunur; editörde OnValidating)

Çerçeve (lifecycle) olayları — RadioList üyesi değildir, editörden bağlanır: OnInit, OnLoad, OnDataLoad, OnPreRender, OnRender, OnClick, OnDoubleClick, OnPropertyChanging, OnPropertyChanged