ListBox

Kullanıcının açık bir şekilde görünen listeden bir ya da birden çok değer seçtiği nesnedir. Seçenekler açılır kutuda gizlenmez, hepsi ekranda görünür. Rol, yetki, departman ya da etiket gibi aynı anda birden çok seçim yapılabilen alanlar için uygundur.

Ne zaman kullanılır?

Seçeneklerin görünür kalması ve kullanıcının birden çok değeri kolayca işaretlemesi gerektiğinde idealdir: yetkiler, ilgili birimler, etiketler. Tek seçim ve az yer kaplaması gerektiğinde ComboBox, evet/hayır tipi tekil işaretlemelerde CheckBox daha uygundur.

Değer tipi: object

Değerin yapısı

ListBox çoklu seçime izin verdiği için Value özelliği tek bir metin değil, seçili değerlerin listesini taşır. Koddan okurken SelectedValues (List<object>, salt okunur) ya da SelectedItems (List<ListItem>, salt okunur) ile ilerlemek; yazarken ise SelectedItemValues (List<object>, set edilebilir) özelliğine bir liste atamak doğru yoldur. Value'ya tek bir metin atamak çoklu seçim mantığına ters düşer.

Tasarımcı özellikleri

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

General

Özellik	Açıklama
Name	Nesnenin koddaki adı (ör. ListBox1). 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.

Data Source

ListBox'ın seçeneklerini bu sekmeden beslersiniz. Seçenekleri elle girebilir ya da bir veri kaynağına bağlayabilirsiniz.

Özellik	Açıklama
Items	Elle girilen seçenek listesi (ListItemCollection). Her öğenin bir metni (Text) ve bir değeri (Value) olur.
Data Source	Seçenekleri besleyen veri kaynağı (sorgu / liste).
Data Source Type	Veri kaynağının türü.
Data	Koda gelen ham seçenek verisi (List<Dictionary<string, object>>).
Selected Item Values	Seçili öğelerin değerleri (List<object>). Koddan seçim yazarken kullanacağınız özelliktir.
Selected Values	Seçili değerler listesi (List<object>, salt okunur). Koddan seçimi okumak için kullanılır.
Text Separator	Birden çok seçim gösterilirken metinleri ayıran karakter.
Value Separator	Birden çok değer saklanırken değerleri ayıran karakter.

Behavior

Özellik	Açıklama
ReadOnly	Alanı salt okunur yapar; seçim değiştirilemez.
Required	Alanı zorunlu yapar; seçim yapılmazsa form kaydedilmez.
AllowSelectAll	Listenin tümünü tek seferde seçmeyi sağlayan bir seçenek ekler.
ShowSearch	Listenin üstüne arama kutusu ekler. Uzun listelerde işe yarar.
SelectedItems	O an seçili olan öğeler (List<ListItem>, salt okunur).
Direction	Öğelerin diziliş yönü: Vertical (dikey) veya Horizontal (yatay).
ValueType	Saklanan değerin türü (metin, sayı, tarih vb.).
DateValueFormat	Değer tarih olduğunda kullanılan biçim.
DecimalValuePrecision	Değer ondalıklı sayı olduğunda basamak sayısı.
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ığı.
Text	Seçili öğelerin ekranda görünen metni (Text Separator ile ayrılır).
Title	Üzerine gelince çıkan başlık (tooltip, çok dilli).
Value	Nesnenin saklanan değeri (seçili öğelerin değer listesi).

Olaylar

ListBox bir seçim nesnesidir; gerçek olayları seçimle ve doğrulamayla ilgilidir. Sunucu olayları C# kodunda, istemci olayları tarayıcıdaki TypeScript kodunda çalışır.

Yalnızca gerçek olaylar

Bu nesnenin sınıfında (Bimser.CSP.FormControls.Controls.ListBox) tanımlı EventHandler üyeleri şunlardır: ValueChanging / ValueChanged (PropertyChangingEventArgs<object> / PropertyChangedEventArgs<object>), TextChanging / TextChanged (...<string>) ve salt okunur ValidatingEvent (EventHandler<ValidatingEventArgs>). Genel yaşam döngüsü olayları (OnInit, OnLoad, OnDataLoad, OnPreRender, OnRender, OnPropertyChanging/Changed, OnClick, OnDoubleClick) bu nesnenin gerçek üyeleri değildir.

Sunucu olayları (Server)

Olay	Argüman tipi	Ne zaman çalışır
OnValueChanging	PropertyChangingEventArgs<object>	Seçim değişmeden hemen önce (iptal edilebilir: e.Cancel = true).
OnValueChanged	PropertyChangedEventArgs<object>	Kullanıcı seçimi değiştirdiğinde. En sık kullanılan olaydır.
OnTextChanging	PropertyChangingEventArgs<string>	Görünen metin değişmeden hemen önce.
OnTextChanged	PropertyChangedEventArgs<string>	Görünen metin değiştikten hemen sonra.
OnValidating	ValidatingEventArgs	Değer doğrulanırken (geçerli mi diye kontrol edilirken).

Seçili öğeler değişince

Temel ListBoxBase sınıfı ayrıca OnSelectedItemsChanged / OnSelectedItemsChanging giriş noktalarını sunar (argüman tipi PropertyChangedEventArgs<List<ListItem>> / PropertyChangingEventArgs<List<ListItem>>). Bunlar seçili ListItem kümesi değiştiğinde tetiklenir; bütün seçili öğe listesine erişmek istediğinizde ValueChanged yerine bunları kullanabilirsiniz.

İstemci olayları (Client)

Olay	Ne zaman çalışır
OnValueChanging / OnValueChanged	Seçim değişmeden önce / sonra (tarayıcı tarafında).
OnTextChanging / OnTextChanged	Görünen metin değişmeden önce / sonra.

Olay parametreleri

OnValueChanging / OnTextChanging olayları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). OnValidating olayının parametresi ise ValidatingEventArgs'tır; Property*ChangingEventArgs değildir.

Kod örnekleri

Bir ListBox'a üç yerden erişebilirsiniz. Sunucu örnekleri turuncu, istemci örnekleri kırmızı çerçevelidir. ListBox çoklu seçime izin verdiği için değeri bir öğe listesidir; bu yüzden okuma SelectedValues / SelectedItems, yazma ise SelectedItemValues üzerinden yapılır.

Form kodu (C#, sunucu)

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

// Oku (seçili değerler) - SelectedValues salt okunur, List<object> döner
foreach (var deger in ListBox1.SelectedValues)
{
    string v = deger?.ToString();
    // ...
}

// Seçili öğeleri tam ListItem olarak oku (metin + değer çiftleri)
foreach (var oge in ListBox1.SelectedItems)
{
    string metin = oge.Text?.ToString();   // görünen metin
    string deger = oge.Value?.ToString();  // saklanan değer
}

// Yaz (çoklu seçim) - SelectedItemValues set edilebilir
ListBox1.SelectedItemValues = new List<object> { "ROL_YONETICI", "ROL_ONAYCI" };

// Seçimi temizle - boş liste ata (çoklu seçim temizleme deseni)
ListBox1.SelectedItemValues = new List<object>();

Doğru yazma özelliği

ListBox1.Value = "ROL_YONETICI" gibi tek bir metin atamak çoklu seçim nesnesinin değer yapısına uymaz. Seçimi koddan ayarlarken her zaman SelectedItemValues özelliğine bir List<object> atayın. SelectedValues salt okunurdur, ona atama yapamazsınız.

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

Akış kodunda nesneye Document1.Controls üzerinden erişirsiniz. Bu yol genel Control arayüzünü döndürür; çoklu seçim listesine ulaşmak için Value değerini bir listeye çevirin (cast edin) ya da tipli nesneye erişin:

// Oku - Value bir listedir; List<object>'e çevirin
var deger = Document1.Controls["ListBox1"].Value as List<object>;
if (deger != null)
{
    foreach (var v in deger)
    {
        string metin = v?.ToString();
    }
}

// Yaz - değer listesini doğrudan ata
Document1.Controls["ListBox1"].Value = new List<object> { "ROL_YONETICI", "ROL_ONAYCI" };

// Temizle (çoklu seçim temizleme deseni)
Document1.Controls["ListBox1"].Value = new List<object>();
Document1.Controls["ListBox1"].Text  = "";

Tipli nesneye erişim

SelectedValues / SelectedItemValues gibi listeye özgü özellikler genel Control arayüzünde yer almaz; bunlara doğrudan ulaşmak isterseniz akış kodunda dökümanı tipli forma açtıktan sonra (ör. Form1) form.Controls["ListBox1"] üzerinden değil, tipli ListBox nesnesi üzerinden ilerlemeniz gerekir. Genel Controls[...] yolunda en pratik yol Value'yu List<object>'e cast etmektir.

İ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 (seçili değer listesi)
const secilenler = this.ListBox1.value;
const gorunen = this.ListBox1.text;

// Yaz (çoklu seçim - değer listesi)
this.ListBox1.value = ["ROL_YONETICI", "ROL_ONAYCI"];

// Temizle
this.ListBox1.value = [];

.Value mi .Text mi?

.Value saklanan değerlerdir (ör. ["ROL_YONETICI", "ROL_ONAYCI"]), .Text ekranda görünen metindir (ör. "Yönetici, Onaycı"). Birden çok seçimde değerler Value Separator, görünen metinler Text Separator ile ayrılır. Seçili öğelerle tek tek çalışmak için sunucuda SelectedValues ya da SelectedItems daha pratiktir.

Örnek: yasak değeri seçtirmeme (OnValueChanging)

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

İstemci (TypeScript):

async ListBox1_OnValueChanging(args: Controls.EventArgs.IPropertyChangingEventArgs<object>) {
    const yeni = args.newValue as any[];
    if (Array.isArray(yeni) && yeni.indexOf("PASIF") > -1) {
        args.cancel = true;                                  // Seçimi iptal eder
        this.showMessage("Uyarı", "Pasif değer seçilemez.", "Validation");
    }
}

Sunucu (C#):

void ListBox1_OnValueChanging(object sender, PropertyChangingEventArgs<object> e)
{
    // NewValue çoklu seçimde bir değer listesidir
    var yeni = e.NewValue as List<object>;
    if (yeni != null && yeni.Any(v => v?.ToString() == "PASIF"))
    {
        e.Cancel = true;
        ShowMessage("Uyarı", "Pasif değer seçilemez.",
            Bimser.CSP.FormControls.RuleManager.AlertType.Validation);
    }
}

Örnek: seçeneklerin tümünü koddan doldurma (Items)

Listeyi tasarımcıdan değil de koddan beslemek isterseniz Items koleksiyonunu (ListItemCollection) ListItem nesneleriyle doldurursunuz. Her ListItem'in bir Value (saklanan değer), Key (anahtar) ve Text (görünen, çok dilli metin) alanı vardır.

ListBox1.Items = new ListItemCollection();

ListBox1.Items.Add(new ListItem
{
    Value = "ROL_YONETICI",
    Key   = "ROL_YONETICI",
    Selected = false,
    Text = new MultiLanguageText(new Dictionary<string, string> { { "tr-TR", "Yönetici" } })
    {
        EnableMultiLanguageText = true
    }
});

ListBox1.Items.Add(new ListItem
{
    Value = "ROL_ONAYCI",
    Key   = "ROL_ONAYCI",
    Selected = true,                                          // önceden seçili gelsin
    Text = new MultiLanguageText(new Dictionary<string, string> { { "tr-TR", "Onaycı" } })
    {
        EnableMultiLanguageText = true
    }
});

Örnek: veri kaynağına bağlı listeyi yenileme (Reload)

Liste bir veri kaynağına (Data Source) bağlıysa ve kaynağın verisi değiştiyse, listeyi koddan tazelemek için Reload() çağırırsınız. Reload(), ListBox'ın temel ListControl sınıfından gelir.

// Önce bir filtre değerine göre veri kaynağı parametresini değiştirin,
// sonra listeyi yeniden yükleyin
ListBox1.Reload();

// Seçimi tekrar uygulamak isterseniz Reload sonrası set edin
ListBox1.SelectedItemValues = new List<object> { "ROL_YONETICI" };

Örnek: yön ve davranış özelliklerini koddan değiştirme

Öğelerin diziliş yönünü, "tümünü seç" seçeneğini ve arama kutusunu koddan açıp kapatabilirsiniz.

// Öğeleri yatay diz (varsayılan dikeydir)
ListBox1.Direction = Bimser.CSP.FormControls.Enums.Direction.Horizontal;

// "Tümünü seç" seçeneğini ekle
ListBox1.AllowSelectAll = true;

// Uzun liste için arama kutusunu aç
ListBox1.ShowSearch = true;

Örnek: kaydetmeden önce seçimi doğrulama (akış kodu)

Akıştaki bir onay adımında ListBox'tan en az bir değer seçilmiş olmasını şart koşabilirsiniz.

var secilenler = Document1.Controls["ListBox1"].Value as List<object>;
if (secilenler == null || secilenler.Count == 0)
{
    // En az bir rol seçilmemiş; akışı durdurun ya da kullanıcıyı uyarın
    throw new Exception("En az bir yetki seçmelisiniz.");
}

İpuçları

• Aynı anda birden çok seçim gerekiyorsa ListBox doğru tercihtir; tek seçim yeterliyse ComboBox daha az yer kaplar.
• Koddan seçim yazarken SelectedItemValues özelliğine bir List<object> atayın; SelectedValues salt okunurdur ve yalnızca okumak içindir.
• Seçimi temizlemek için SelectedItemValues = new List<object>() (boş liste) atayın; akış kodunda Value = new List<object>() ve Text = "" ile temizleyin.
• Uzun listelerde ShowSearch özelliğini açın; kullanıcı listede yazarak arar.
• Tümünü seçtirmek isterseniz AllowSelectAll özelliğini açın.
• Seçenekleri elle (Items) yerine bir veri kaynağına (Data Source) bağlarsanız listeyi tek yerden güncellersiniz; kaynak değişince Reload() ile tazeleyin.
• Seçili öğeleri metin + değer çiftleriyle okumak için SelectedItems (List<ListItem>) üzerinde gezinin; sadece değerler yeterliyse SelectedValues daha hafiftir.

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

Data Source: Data, DataSource, DataSourceType, Items, SelectedItemValues, SelectedValues, TextSeparator, ValueSeparator

Behavior: AllowSelectAll, DateValueFormat, DecimalValuePrecision, Direction, ReadOnly, Required, SelectedItems, ShowSearch, TabIndex, ValueType

Appearance: ClientEnabled, ClientVisible, Enabled, Text, Title, Value, Visible

Diğer (taban sınıflardan): ContainerStyle, Style, CustomClassName, ContextMenuKey, ContextMenuColumnKey, ContextMenuTarget, ControlId, EntityPath, Indexable, Loading, DefaultEnabled, DefaultClientEnabled, DefaultReadOnly

Olaylar (Server / Client): OnValueChanging, OnValueChanged, OnTextChanging, OnTextChanged, OnValidating

Taban sınıf giriş noktaları: OnSelectedItemsChanging, OnSelectedItemsChanged

Yöntemler: Reload(), GetData(), GetValueAsObject(), ClearDefaultValue(), GetDifferences(object), SetPropertyValue(List<string>, object)