TagBox

Kullanıcının bir listeden birden fazla değer seçebildiği nesnedir. Seçilen her değer küçük bir etiket (tag) olarak alanın içinde gösterilir. Tek seçim yapan açılır listenin çoklu seçim yapan halidir.

Değer tipi: object (seçili değerlerin listesini taşır)

Ne zaman kullanılır?

Bir kayda birden çok değer bağlamak istediğinizde uygundur: birden fazla etiket, ilgili kişiler, departmanlar ya da kategoriler. Tek bir değer seçilecekse ComboBox, seçenekleri tek tek işaretletmek istiyorsanız CheckBoxList daha uygundur.

Tasarımcı özellikleri

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

General

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

Data Source (Veri kaynağı)

TagBox'ta gösterilecek seçenekleri buradan tanımlarsınız. Seçenekler elle (Items) ya da bir veri kaynağından (DataSource) gelebilir.

Özellik	Açıklama
DataSourceType	Verinin nereden geleceğini belirler: elle girilen liste mi yoksa bir veri kaynağı mı.
DataSource	Seçenekleri besleyen veri kaynağı (.mssqlds / .restds vb.).
Data	Nesneye doğrudan kod ile verilen satır listesi (List<Dictionary<string, object>>).
Items	Elle tanımlanan seçenek listesi (ListItemCollection: metin ve değer çiftleri).
SelectedValues	Seçili öğelerin değerleri (salt okunur, List<object>).
SelectedItemValues	Seçili öğelere atanan değer listesi (yazılabilir, List<object>).
TextSeparator	Etiketlerin ekrandaki metinlerini ayıran karakter.
ValueSeparator	Seçili değerlerin saklanırken ayrıldığı karakter.

Behavior

Özellik	Açıklama
Required	Alanı zorunlu yapar; hiçbir değer seçilmezse form kaydedilmez.
ReadOnly	Alanı salt okunur yapar; seçim değiştirilemez.
ShowSearch	Liste içinde arama kutusu gösterir.
AllowClear	Seçimi tek tıkla temizleyen butonu gösterir.
HideForceRefreshButton	Listeyi yeniden yükleme butonunu gizler.
ValueType	Seçilen değerin veri tipi (PrimitiveType: metin, sayı, tarih vb.).
DateValueFormat	Değer tarihse uygulanacak tarih biçimi.
DecimalValuePrecision	Değer ondalıksa gösterilecek basamak sayısı.
SelectedItems	Seçili öğelerin listesi (salt okunur, List<ListItem>).
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	Hiçbir değer seçili değilken görünen soluk ipucu yazısı (çok dilli).
Title	Nesnenin başlık / ipucu metni (çok dilli).
Text	Seçili etiketlerin birleşik metni.

Olaylar

Kullanıcı seçim yaptığında ya da alanın metni değiştiğinde olaylar tetiklenir. Doğru kodu doğru olaya yazmak için bu nesnenin hangi olayları sunduğunu bilmek işinizi kolaylaştırır.

Kullanıcı seçim yaparken: ValueChanging → ValueChanged

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

Sunucu olayları (Server)

Olay	Ne zaman çalışır
OnValueChanging	Seçim değişmeden hemen önce (iptal edilebilir).
OnValueChanged	Kullanıcı seçimini değiştirip değer kesinleştiğinde. En sık kullanılan olaydır.
OnTextChanging	Etiketlerin birleşik metni değişmeden hemen önce.
OnTextChanged	Etiketlerin birleşik metni değiştikten hemen sonra.
OnValidating	Alan doğrulanırken; geçerlilik kontrolü buraya yazılır (ValidatingEvent, salt okunur).

İstemci olayları (Client)

Olay	Ne zaman çalışır
OnValueChanging / OnValueChanged	Seçim değişmeden önce / sonra.
OnTextChanging / OnTextChanged	Etiket metni değişmeden önce / sonra.

Olay parametreleri

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

• newValue / NewValue — seçilmek istenen yeni değer (seçili değerlerin listesi)
• 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). Sunucu tarafında olayın argüman tipi PropertyChangingEventArgs<object> / PropertyChangedEventArgs<object>'tir; NewValue bir liste olduğu için IList'e dönüştürerek okuyun.

Kod örnekleri

Bir TagBox'a üç yerden erişebilirsiniz. Sunucu örnekleri turuncu, istemci örnekleri kırmızı çerçevelidir. TagBox'ın değeri çoklu seçim olduğu için object tipinde olup seçili değerlerin listesini taşır.

Hangi özelliğe yazılır?

SelectedValues salt okunurdur (yalnızca getter'ı vardır); ona atama yaparsanız kod derlenmez. Seçimi koddan ayarlamak için yazılabilir olan SelectedItemValues ya da Value özelliğini kullanın. SelectedValues ve SelectedItems sadece okuma içindir.

Form kodu (C#, sunucu)

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

// Oku: seçili değerleri liste olarak al (salt okunur)
var degerler = TagBox1.SelectedValues;          // List<object>

// Yaz: seçimi ayarla (yazılabilir özellik SelectedItemValues)
TagBox1.SelectedItemValues = new List<object> { "1", "2", "3" };

// Alternatif yazma: Value da yazılabilir
TagBox1.Value = new List<object> { "1", "2", "3" };

// Tüm etiketleri temizle (kanonik çoklu seçim temizleme deyimi)
TagBox1.Value = new List<object>();
TagBox1.Text  = "";

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

Akış kodunda nesneye Document1.Controls üzerinden erişirsiniz. Bu yol genel Control arayüzünü döndürdüğü için yazma da .Value üzerinden yapılır:

// Oku
var secilenler = Document1.Controls["TagBox1"].Value;   // object (liste)

// Yaz
Document1.Controls["TagBox1"].Value = new List<object> { "1", "2", "3" };

// Tüm etiketleri temizle
Document1.Controls["TagBox1"].Value = new List<object>();
Document1.Controls["TagBox1"].Text  = "";

İ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 secilenler = this.TagBox1.value;

// Yaz
this.TagBox1.value = ["1", "2", "3"];

// Temizle
this.TagBox1.value = [];
this.TagBox1.text = "";

Çoklu değerle çalışmak

TagBox tek bir metin değil bir değer listesi tutar. Okurken SelectedValues (değerler) veya SelectedItems (tam ListItem nesneleri) liste olarak gelir. Yazarken yazılabilir olan SelectedItemValues ya da Value özelliğini kullanın; SelectedValues salt okunurdur. Temizlemek için boş liste atayın: Value = new List<object>().

Örnek 1: Seçili etiketleri tek tek dolaşmak (SelectedItems)

SelectedItems her seçili etiketi bir ListItem olarak verir. ListItem üzerinde Value (saklanan değer), Text (görünen çok dilli metin) ve Key (anahtar) bulunur. Aşağıdaki örnek seçili etiketleri okuyup virgülle birleştirir.

// Seçili etiketleri dolaş ve metinlerini topla
var etiketler = new List<string>();
foreach (var item in TagBox1.SelectedItems)        // List<ListItem>
{
    object deger   = item.Value;                   // saklanan değer
    string gorunen = item.GetText();               // görünen metin (çok dilli)
    etiketler.Add(gorunen);
}

string birlesik = string.Join(", ", etiketler);
TextBox1.Value = birlesik;
TextBox1.Text  = birlesik;

Örnek 2: Seçenekleri koddan elle doldurmak (Items + Reload)

Seçenekleri sabit bir liste olarak koddan kurmak istiyorsanız Items koleksiyonuna ListItem ekleyip ardından Reload() çağırarak değişikliği istemciye gönderirsiniz.

TagBox1.Items = new Bimser.CSP.FormControls.Common.ListItemCollection();

TagBox1.Items.Add(new Bimser.CSP.FormControls.Common.ListItem {
    Key   = "1",
    Value = "1",
    Text  = new MultiLanguageText(new Dictionary<string, string> { { "tr-TR", "Acil" } })
});
TagBox1.Items.Add(new Bimser.CSP.FormControls.Common.ListItem {
    Key   = "2",
    Value = "2",
    Text  = new MultiLanguageText(new Dictionary<string, string> { { "tr-TR", "Normal" } })
});

// Mevcut Items / DataSource değişti; istemciye yansıt
TagBox1.Reload();

// İstenirse varsayılan seçimi de ata
TagBox1.SelectedItemValues = new List<object> { "1" };

Örnek 3: Bir veri kaynağından beslemek (DataSource + ValueType)

Seçenekler bir sorgudan geliyorsa DataSourceType ve DataSource özelliklerini bağlar, değerin tipini ValueType ile belirtirsiniz. Tasarımcıdan bağlamak olağan yoldur; koddan kaynağı yeniledikten sonra Reload() çağırın.

// Değerin tipini bildir (ör. tam sayı anahtarlar)
TagBox1.ValueType = Bimser.CSP.FormControls.Enums.PrimitiveType.Integer;

// Tasarımcıda bağlı veri kaynağını yeniden yükle
TagBox1.Reload();

// Kaynaktan gelen birkaç anahtarı önceden seç
TagBox1.SelectedItemValues = new List<object> { 10, 20 };

Data ile doğrudan satır vermek

Bir sorgu çalıştırıp satırları kendiniz hazırlıyorsanız, Data özelliğine List<Dictionary<string, object>> atayabilirsiniz. Her sözlük bir seçenek satırını temsil eder; hangi alanın değer, hangisinin metin olduğunu veri kaynağı eşlemesi belirler. Atamadan sonra yine Reload() çağırın.

Örnek 4: En az bir seçim zorunlu (OnValueChanging)

OnValueChanging seçim değişmeden hemen önce çalışır; istemediğiniz bir durumu burada iptal edebilirsiniz. Aşağıdaki örnekte tüm etiketlerin kaldırılması engellenir.

İstemci (TypeScript):

async TagBox1_OnValueChanging(args: Controls.EventArgs.IPropertyChangingEventArgs<object>) {
    const yeni = args.newValue as any[];
    if (!yeni || yeni.length == 0) {
        args.cancel = true;                                  // Seçimin tamamen boşalmasını engeller
        this.showMessage("Uyarı", "En az bir etiket seçili kalmalı.", "Validation");
    }
}

Sunucu (C#):

void TagBox1_OnValueChanging(object sender, PropertyChangingEventArgs<object> e)
{
    // NewValue seçili değerlerin listesidir; IList'e dönüştürerek sayısını kontrol et
    var yeni = e.NewValue as System.Collections.IList;
    if (yeni == null || yeni.Count == 0)
    {
        e.Cancel = true;
        ShowMessage("Uyarı", "En az bir etiket seçili kalmalı.",
            Bimser.CSP.FormControls.RuleManager.AlertType.Validation);
    }
}

Örnek 5: Seçim değişince başka alanı güncellemek (OnValueChanged)

OnValueChanged seçim kesinleştikten sonra çalışır; seçim sayısını okuyup başka bir alana yazmak için uygundur.

void TagBox1_OnValueChanged(object sender, PropertyChangedEventArgs<object> e)
{
    int adet = TagBox1.SelectedValues.Count;
    NumberBox1.Value = adet;                                 // seçilen etiket sayısı
    NumberBox1.Text  = adet.ToString();
}

İpuçları

• Koddan seçim atarken yazılabilir olan SelectedItemValues ya da Value kullanın; SelectedValues salt okunurdur ve ona atama yapmak derlenmez.
• Tüm etiketleri temizlemenin kanonik yolu boş liste atamaktır: TagBox1.Value = new List<object>(); ardından TagBox1.Text = "";.
• Seçeneklerin sayısı çoksa ShowSearch özelliğini açın; kullanıcı liste içinde arayarak hızlıca seçim yapar.
• Kullanıcının seçimini hızla temizleyebilmesi için AllowClear özelliğini açık tutun.
• Alanın boş bırakılmamasını istiyorsanız Required özelliğini kullanın; kod ile boş kontrolü yapmanıza gerek kalmaz.
• Items ya da DataSource özelliğini koddan değiştirdikten sonra Reload() çağırmayı unutmayın; aksi halde değişiklik istemciye yansımaz.
• Tek bir değer seçtirecekseniz TagBox yerine ComboBox kullanın.

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

General: Name, Field Name

Data Source: Data, DataSource, DataSourceType, Items, SelectedItemValues (yazılabilir), SelectedValues (salt okunur), TextSeparator, ValueSeparator

Behavior: AllowClear, DateValueFormat, DecimalValuePrecision, HideForceRefreshButton, ReadOnly, Required, SelectedItems (salt okunur), ShowSearch, TabIndex, ValueType

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

Yapısal / inherited: Caption, ContainerStyle, Style, CustomClassName, ControlId, EntityPath, Indexable, Loading, ContextMenuKey, ContextMenuColumnKey, ContextMenuTarget, DefaultEnabled, DefaultClientEnabled, DefaultReadOnly, ClientEvents, ServerEvents, ExecutedServerEvents

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

Olaylar (Client): OnValueChanging, OnValueChanged, OnTextChanging, OnTextChanged

Yöntemler: Reload(), GetValueAsObject(), GetData(), IsValid(), GetDifferences(object)