Dropdown

Kullanıcının önceden tanımlı bir listeden seçim yapabileceği açılır liste nesnesidir. Şehir, durum, kategori, departman gibi belirli seçenekler arasından tek bir değerin seçildiği alanlar için kullanılır.

Değer tipi: object

Ne zaman kullanılır?

Seçenekler belli ve sınırlıysa Dropdown idealdir: il, departman, öncelik, durum gibi alanlar. Kullanıcının serbest metin yazması gerekiyorsa TextBox, birden çok seçeneği aynı anda işaretlemesi gerekiyorsa CheckBoxList, az sayıda seçenek arasından hızlı seçim için RadioButtonList daha uygundur.

Tasarımcı özellikleri

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

General

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

Listede görünecek seçenekleri belirler. Seçenekleri elle girebilir ya da bir veri kaynağına bağlayabilirsiniz.

Özellik	Açıklama
Items	Elle tanımlanan seçenek listesi. Her satırın bir görünen yazısı (Text) ve bir değeri (Value) vardır.
Data Source	Listeyi besleyen veri kaynağı (örn. bir sorgu sonucu).
Data Source Type	Veri kaynağının türü.
Data	Listeyi koddan doldurmak için kullanılan veri (Text/Value çiftlerinden oluşan liste).
Selected Item	O an seçili olan öğe.
Selected Values / Selected Item Values	Seçili öğelerin değerleri.
Text Separator / Value Separator	Birden çok değer gösterildiğinde yazı ve 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.
AllowClear	Seçimi temizlemek için (×) butonunu gösterir.
ShowSearch	Liste içinde arama kutusu gösterir; uzun listelerde işe yarar.
DisplayMode	Listenin görünüm biçimi.
SelectedItem	O an seçili öğe.
ValueType	Değerin türü (metin, sayı, tarih vb.).
DateValueFormat	Değer tarih ise gösterim biçimi.
DecimalValuePrecision	Değer ondalık sayı ise 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ığı.
Placeholder	Seçim yapılmadan önce görünen soluk ipucu yazısı.
Title	Üzerine gelince çıkan başlık (tooltip).
Text	Seçili öğenin ekranda görünen yazısı.
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 yapınca: OnValueChanging → OnValueChanged

Olaylar iki tarafta çalışabilir: sunucu olayları C# kodunda, istemci olayları tarayıcıdaki TypeScript kodunda. Dropdown'ı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ı seçimi kesinleştirdiğinde. En sık kullanılan olaydır.
OnTextChanging / OnTextChanged	Görünen yazı değişmeden önce / sonra.
OnValidating	Değer doğrulanırken çalışır; geçersizse engelleyebilirsiniz.

İstemci olayları (Client)

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

Olay	Ne zaman çalışır
OnDataLoad	Listenin 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 — 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 Dropdown'a üç yerden erişebilirsiniz. Sunucu örnekleri turuncu, istemci örnekleri kırmızı çerçevelidir. Dropdown'ın değeri object tipindedir; okurken seçtiğiniz değerin türüne göre dönüştürün.

Form kodu (C#, sunucu)

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

// Oku (seçili değer)
var secilen = Dropdown1.Value;
string secilenMetin = Dropdown1.Text;          // ekranda görünen yazı

// Yaz (değeri seç)
Dropdown1.Value = "Ankara";

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

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

// Oku
var secilen = Document1.Controls["Dropdown1"].Value;

// Yaz
Document1.Controls["Dropdown1"].Value = "Ankara";

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

// Yaz
this.Dropdown1.value = "Ankara";

.Value mi .Text mi?

.Value saklanan değerdir (örn. bir kod ya da kimlik), .Text ise listede görünen yazıdır. Çoğu zaman değeri (Value) iş mantığında kullanır, yazıyı (Text) sadece kullanıcıya gösterirsiniz.

Örnek: seçimi doğrulama (OnValueChanging)

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

İstemci (TypeScript):

async Dropdown1_OnValueChanging(args: Controls.EventArgs.IPropertyChangingEventArgs<object>) {
    if (args.newValue == "Pasif") {
        args.cancel = true;                                  // Seçimi iptal eder
        this.showMessage("Uyarı", "Pasif değeri seçilemez.", "Validation");
    }
}

Sunucu (C#):

void Dropdown1_OnValueChanging(object sender, PropertyChangingEventArgs<object> e)
{
    if ((string)e.NewValue == "Pasif")
    {
        e.Cancel = true;
        ShowMessage("Uyarı", "Pasif değeri seçilemez.",
            Bimser.CSP.FormControls.RuleManager.AlertType.Validation);
    }
}

İpuçları

• Listeyi koddan doldurmak için Items koleksiyonunu ya da bir veri kaynağını (Data Source) kullanın; her seçeneğin bir görünen yazısı (Text) ve bir değeri (Value) olur.
• Uzun listelerde ShowSearch özelliğini açın; kullanıcı yazarak hızlıca seçeneğe ulaşır.
• Seçimin temizlenebilmesini istiyorsanız AllowClear özelliğini açın.
• Bir seçim yapıldığında başka alanları doldurmak için OnValueChanged olayını kullanı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

Data Source: Data, Data Source, Data Source Type, Items, Selected Item Values, Selected Values, Text Separator, Value Separator

Behavior: AllowClear, DateValueFormat, DecimalValuePrecision, DisplayMode, ReadOnly, Required, SelectedItem, ShowSearch, Tab Index, ValueType

Appearance: Client Enabled, Client Visible, Enabled, Placeholder, Size Type, 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