ComboBox

Kullanıcının hazır bir listeden tek bir değer seçtiği açılır liste nesnesidir. Şehir, departman, durum ya da kategori gibi belli seçeneklerden birini seçtirmek için kullanılır.

Ne zaman kullanılır?

Seçeneklerin sayısı belli ve sınırlıysa idealdir: il, durum, öncelik, kategori. Seçenekleri elle yazmak yerine listeden seçtirir, böylece yazım hatalarını önler. Çok sayıda seçenek için arama özelliğini (ShowSearch) açabilirsiniz. Serbest metin girişi gerektiğinde TextBox, birden çok seçim gerektiğinde çoklu seçim nesnelerini tercih edin.

Değer tipi: object

Tasarımcı özellikleri

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

General

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

ComboBox'ı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. Her satırın bir metni ve bir değeri 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 (metin/değer çiftleri).
Selected Item Values	Seçili öğelerin değerleri.
Selected Values	Seçili değerler listesi.
Text Separator	Birden çok değer 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.
ShowSearch	Açılır listenin üstüne arama kutusu ekler. Uzun listelerde işe yarar.
AllowClear	Seçimi temizleyen küçük bir (x) düğmesi gösterir.
SelectedItem	O an seçili olan öğe.
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ı.
IconExpr	Öğelerin yanında gösterilecek ikonu belirleyen ifade.
IconMatchers	Hangi değere hangi ikonun geleceğini eşleştirir.
HideForceRefreshButton	Listeyi yenileyen düğmeyi gizler.
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	Seçim yapılmadan önce görünen soluk ipucu yazısı.
Text	Seçili öğenin ekranda görünen metni.
Title	Üzerine gelince çıkan başlık (tooltip).
Size Type	Genişlik davranışı (sabit / esnek).

Olaylar

Bir nesne açılırken olaylar belirli bir sırayla tetiklenir; kullanıcı seçim yapınca 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ı seçim yaparken: OnValueChanging → OnValueChanged

Olaylar iki tarafta çalışabilir: sunucu olayları C# kodunda, istemci olayları tarayıcıdaki TypeScript kodunda. ComboBox'ı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.
OnValueChanging	Seçim değişmeden hemen önce (iptal edilebilir).
OnValueChanged	Kullanıcı yeni bir öğe seçtiğinde. En sık kullanılan olaydır.
OnTextChanging	Görünen metin değişmeden hemen önce.
OnTextChanged	Görünen metin değiştikten hemen sonra.
OnValidating	Değer doğrulanırken (geçerli mi diye kontrol edilirken).

İstemci olayları (Client)

Sunucudaki olaylara ek olarak tarayıcı tarafında şunlar da vardır:

Olay	Ne zaman çalışır
OnDataLoad	Nesnenin seçenek 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 — 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 ComboBox'a üç yerden erişebilirsiniz. Sunucu örnekleri turuncu, istemci örnekleri kırmızı çerçevelidir. ComboBox'ın değeri seçili öğenin değeridir; tipi object olduğu için okurken .ToString() ile metne çevirmek pratiktir.

Form kodu (C#, sunucu)

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

// Oku (seçili değer)
var secilen = ComboBox1.Value;
string secilenMetin = ComboBox1.Value?.ToString();

// Görünen metni oku
string gorunen = ComboBox1.Text;

// Yaz (listedeki bir değeri seç)
ComboBox1.Value = "ANK";

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

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

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

// Yaz
Document1.Controls["ComboBox1"].Value = "ANK";

İ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.ComboBox1.value;
const gorunen = this.ComboBox1.text;

// Yaz
this.ComboBox1.value = "ANK";

.Value mi .Text mi?

.Value saklanan değerdir (ör. "ANK"), .Text ekranda görünen metindir (ör. "Ankara"). Listeye bir değer yazdığınızda görünen metin otomatik olarak eşleşen öğeden gelir; siz değeri set etmeye odaklanın.

Örnek: seçime göre işlem yapma (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 ComboBox1_OnValueChanging(args: Controls.EventArgs.IPropertyChangingEventArgs<object>) {
    if (args.newValue == "PASIF") {
        args.cancel = true;                                  // Seçimi iptal eder
        this.showMessage("Uyarı", "Pasif durum seçilemez.", "Validation");
    }
}

Sunucu (C#):

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

İpuçları

• Çok sayıda seçeneğiniz varsa ShowSearch özelliğini açın; kullanıcı listede yazarak arar.
• Seçimin temizlenebilmesi için AllowClear özelliğini açın; alan zorunluysa kapalı tutmak daha güvenlidir.
• Seçenekleri elle (Items) yerine bir veri kaynağına (Data Source) bağlarsanız listeyi tek yerden güncellersiniz.
• Değer tipi object olduğundan okurken ?.ToString() kullanmak null hatasını önler.

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: AllowClear, DateValueFormat, DecimalValuePrecision, HideForceRefreshButton, IconExpr, IconMatchers, ReadOnly, Required, SelectedItem, ShowSearch, TabIndex, ValueType

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

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