SearchBox

İçinde arama ikonu bulunan, tek satırlık bir metin nesnesidir. Kullanıcının bir arama ifadesi yazıp listeleri ya da kayıtları filtrelemesi gereken yerlerde kullanılır. Davranış olarak TextBox ile aynıdır; tek farkı arama amacına uygun görünümüdür.

Değer tipi: string

SearchBox, sade bir TextControl'dür

SearchBox TextControl tabanlıdır; TextBox'ın sahip olduğu MultiLanguageText / EnableMultiLanguageText ve ShowCharacterCounter özellikleri SearchBox'ta yoktur. Yani değeri her zaman düz bir string'tir, çok dilli metin tutmaz. Placeholder ve Title gibi etiket benzeri özellikleri ise çok dilli (MultiLanguageText) olabilir.

Ne zaman kullanılır?

Kullanıcının bir şey araması gereken alanlarda kullanın: kayıt listesinde filtreleme, ad/kod ile arama, hızlı bulma kutusu. Girilen metni ValueChanged olayında okuyup kendi arama/filtre kodunuzu çalıştırırsınız. Sıradan metin girişi için TextBox, belirli bir biçim gereken alanlarda MaskInput daha uygundur.

Tasarımcı özellikleri

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

General

Özellik	Açıklama
Name	Nesnenin koddaki adı (ör. SearchBox1). Koddan bu adla erişirsiniz.
Field Name	Veritabanındaki alanın adı.
Size	Alanın veritabanındaki uzunluğu.

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.

Behavior

Özellik	Açıklama
ReadOnly	Alanı salt okunur yapar.
Required	Alanı zorunlu yapar; boşsa form kaydedilmez.
MaxLength	En fazla kaç karakter girilebileceğini sınırlar.
Tab Index	Tab tuşuyla geçiş sırasını belirler.
Is Secret Data	Değeri hassas veri sayar; loglarda gizlenir.

Appearance

Özellik	Tip	Açıklama
Visible / Client Visible	bool	Nesnenin görünürlüğü.
Enabled / Client Enabled	bool	Nesnenin aktif olup olmadığı.
Placeholder	MultiLanguageText	Alan boşken görünen soluk ipucu yazısı (ör. "Ara..."). Çok dilli olabilir.
Text Align	HorizontalAlign	Yazının hizası. Serbest metin değil, Left / Center / Right gibi enum değerleri alır.
Size Type	SizeType?	Genişlik davranışı (sabit / esnek).
Title	MultiLanguageText	Fareyle üzerine gelince çıkan ipucu (tooltip) yazısı. Çok dilli olabilir.
Text	string	Nesnede görünen metin.

Olaylar

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

Bu nesnenin gerçek olayları

SearchBox sınıfının (Bimser.CSP.FormControls.Controls.SearchBox) kendine ait olay üyeleri yalnızca şunlardır: TextChanging / TextChanged, ValueChanging / ValueChanged ve ValidatingEvent. Tasarımcıda görebileceğiniz OnInit, OnLoad, OnRender, OnDataLoad, OnPreRender, OnClick, OnDoubleClick, OnPropertyChanging / OnPropertyChanged gibi olaylar SearchBox'a özgü değildir; tüm nesnelerde ortak olan genel yaşam döngüsü / istemci kancalarıdır.

Sunucu olayları (Server)

Olay	Arg tipi	Ne zaman çalışır
TextChanging	PropertyChangingEventArgs<string>	Kullanıcı yazarken, metin değişmeden hemen önce (iptal edilebilir).
TextChanged	PropertyChangedEventArgs<string>	Metin değiştikten hemen sonra.
ValueChanging	PropertyChangingEventArgs<string>	Değer değişmeden hemen önce (iptal edilebilir).
ValueChanged	PropertyChangedEventArgs<string>	Kullanıcı alandan çıkıp arama metni kesinleştiğinde. En sık kullanılan olaydır.
ValidatingEvent	ValidatingEventArgs	Form kaydedilirken alanın değeri doğrulanırken.

İstemci olayları (Client)

İstemci tarafında aynı değişim olaylarına OnValueChanged, OnValueChanging, OnTextChanged, OnTextChanging adlarıyla erişirsiniz. Bunlara ek olarak tüm nesnelerde ortak olan OnClick / OnDoubleClick ve özellik değişim kancaları (OnPropertyChanging / OnPropertyChanged) da kullanılabilir; bunlar SearchBox'a özgü değildir.

Olay parametreleri

ValueChanging / TextChanging olaylarının parametresi PropertyChangingEventArgs<string> (C# e, TS args) tipindedir ve şunları taşır:

• NewValue / newValue — girilmek 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ının parametresi PropertyChangedEventArgs<string> tipindedir; Cancel alanı yoktur (değişiklik artık gerçekleşmiştir).

Kod örnekleri

Bir SearchBox'a üç 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:

// Oku (boş alanda NullReferenceException atmaması için null-güvenli okuyun)
string aramaMetni = SearchBox1.Value?.ToString();

// Yaz
SearchBox1.Value = "fatura";
SearchBox1.Text  = "fatura";

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

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

// Oku
string aramaMetni = Document1.Controls["SearchBox1"].Value?.ToString();

// Yaz
Document1.Controls["SearchBox1"].Value = "fatura";
Document1.Controls["SearchBox1"].Text  = "fatura";

İstemci kodu (TypeScript, tarayıcı)

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

this.SearchBox1.value = "";
this.SearchBox1.text  = "";

.Value mi .Text mi?

.Value saklanan değerdir, .Text ekranda görünen metindir. SearchBox için ikisi de string'tir; yazarken ikisini de aynı yazıyla set etmeye özen gösterin. Okurken, alan boş olabileceği için ?.ToString() ile null-güvenli okuyun.

Örnek: arama metnini yakalama (OnValueChanged)

Kullanıcı arama metnini yazıp alandan çıktığında ValueChanged çalışır. Bu olayda arama ifadesini okuyup filtre/arama kodunuzu tetikleyebilirsiniz.

İstemci (TypeScript):

async SearchBox1_OnValueChanged(args: Controls.EventArgs.IPropertyChangedEventArgs<string>) {
    const aranan = this.SearchBox1.value;                    // Yazılan arama metni
    if (!aranan) {
        return;                                              // Boşsa arama yapma
    }
    // TODO: aranan ifadeye göre kendi filtre/arama kodunuzu çalıştırın
    this.showMessage("Arama", "Aranıyor: " + aranan, "Info");
}

Sunucu (C#):

void SearchBox1_OnValueChanged(object sender, PropertyChangedEventArgs<string> e)
{
    string aranan = e.NewValue;                              // Kesinleşen arama metni
    if (string.IsNullOrEmpty(aranan))
    {
        return;                                              // Boşsa arama yapma
    }
    // TODO: aranan ifadeye göre kendi filtre/arama kodunuzu çalıştırın
}

İpuçları

• Arama metnini her tuş vuruşunda değil, kullanıcı alandan çıkınca işlemek için ValueChanged olayını kullanın; her harfte tetiklemek isterseniz TextChanged'i tercih edin.
• Placeholder özelliğine "Ara..." gibi bir ipucu yazarak alanın amacını netleştirin.
• Yalnızca veri girişi gereken, arama amacı taşımayan alanlarda SearchBox yerine TextBox kullanın. Çok dilli metin ya da karakter sayacı gerekiyorsa da TextBox kullanın; SearchBox bunları desteklemez.

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

General: Name, Field Name, Size

Label: Caption, Text, Position, Left, Width, Height, Font (Bold / Italic / Underline), Ellipsis, Visible, Show Colon, Horizontal Align, Vertical Align, Mark Char, Mark Position

Behavior: IsSecretData, MaxLength, ReadOnly, Required, TabIndex

Appearance: ClientEnabled, ClientVisible, Enabled, Placeholder (MultiLanguageText), SizeType, Text (string), TextAlign (HorizontalAlign), Title (MultiLanguageText), Value (string), Visible

Diğer üyeler: Caption (ControlCaption), ContainerStyle / Style (Style), CustomClassName, ContextMenuKey / ContextMenuColumnKey / ContextMenuTarget, ControlId, EntityPath, Indexable, Loading, DefaultEnabled / DefaultClientEnabled / DefaultReadOnly

Olaylar (SearchBox'a özgü, gerçek üyeler): TextChanging (PropertyChangingEventArgs<string>), TextChanged (PropertyChangedEventArgs<string>), ValueChanging (PropertyChangingEventArgs<string>), ValueChanged (PropertyChangedEventArgs<string>), ValidatingEvent (ValidatingEventArgs)

Genel kancalar (tüm nesnelerde ortak, SearchBox'a özgü değil): OnInit, OnLoad, OnPreRender, OnRender, OnDataLoad, OnClick, OnDoubleClick, OnPropertyChanging, OnPropertyChanged