Lookup

Bir veri kaynağındaki kayıtları arama penceresinde açıp kullanıcıya seçtiren nesnedir. Seçilen kaydın bir ya da birden çok kolonunu forma getirebilirsiniz. Personel, firma, ürün, masraf kodu gibi tanımlı bir listeden kayıt seçmek için kullanılır.

Değer tipi: object

Ne zaman kullanılır?

Kullanıcının elle yazması yerine hazır bir listeden kayıt seçmesi gerektiğinde idealdir: cari seçimi, personel seçimi, ürün/stok seçimi, proje kodu. Listeyi açılır kutu içine sığdırmak yeterliyse ComboBox daha hafiftir; Lookup ise çok kolonlu, aranabilir ve büyük veri kaynakları için uygundur.

Tasarımcı özellikleri

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

General

Özellik	Açıklama
Name	Nesnenin koddaki adı (ör. Lookup1). Koddan bu adla erişirsiniz.
Field Name	Seçilen değerin yazılacağı veritabanı alanını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

Lookup'ın hangi kayıtları göstereceğini bu sekme belirler. Veri kaynağı olmadan nesne boş açılır.

Özellik	Açıklama
DataSource	Kayıtların geldiği veri kaynağı (genellikle bir SQL veri kaynağı). Arama penceresinde listelenecek satırlar buradan gelir.
Items	Veri kaynağı yerine elle sabit bir liste vermek için kullanılır. Kısa, değişmeyen listelerde pratiktir.

Behavior

Özellik	Açıklama
AllowClear	Kullanıcının seçimi temizlemesine izin verir (yanındaki temizleme düğmesi).
GridOptions	Arama penceresindeki tablonun ayarları (kolonlar, sayfalama, arama).
ReadOnly	Nesneyi salt okunur yapar; seçim değiştirilemez.
Required	Seçimi zorunlu yapar; boşsa form kaydedilmez.
Rows	Seçilen satır(lar)ın kolon değerlerine erişilen koleksiyon.
SelectedItems	O an seçili olan kayıt veya kayıtlar.
ShowOn	Arama penceresinin nasıl açılacağını belirler.
TabIndex	Tab tuşuyla geçiş sırasını belirler.
ValueType	Seçilen değerin saklanacağı veri türü (metin, sayı vb.).

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çilen kaydın ekranda görünen metni.
Text Align	Yazının hizası.
Title	Nesnenin başlığı (çok dilli olabilir).
Value	Seçilen kayıt(lar)ın değeri (List<Object>).
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şinizi kolaylaştırır.

Açılış sırası: OnInit → OnLoad → OnDataLoad → OnPreRender → OnRender

Kullanıcı seçim yapınca: arama düğmesine basınca LookupButtonClick, seçim kesinleşmeden önce ValueChanging, kesinleşince 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
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.
LookupButtonClick	Kullanıcı arama düğmesine basıp pencereyi açtığında.
ValidatingEvent	Seçim doğrulanırken; geçersiz seçimi burada engelleyebilirsiniz.
ValueChanging	Seçim değişmeden hemen önce (iptal edilebilir).
ValueChanged	Seçim kesinleştiğinde. En sık kullanılan olaydır.
TextChanging / TextChanged	Görünen metin değişmeden önce / sonra.

İstemci olayları (Client)

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

Olay	Ne zaman çalışır
OnDataLoad	Nesnenin 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

ValueChanging 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 seçim iptal edilir (yalnızca Changing olaylarında)

ValueChanged olayında cancel yoktur (seçim artık gerçekleşmiştir).

Kod örnekleri

Bir Lookup'a üç yerden erişebilirsiniz. Sunucu örnekleri turuncu, istemci örnekleri kırmızı çerçevelidir. Lookup'ın değeri bir nesne (List<Object>) olduğundan, çoğu zaman seçilen değeri doğrudan değil, satırın kolonları üzerinden okursunuz.

Form kodu (C#, sunucu)

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

// Seçilen değeri oku
var secilen = Lookup1.Value;

// Seçilen satırın bir kolonunu oku
string firmaAdi = Lookup1.Rows[0]["FIRMA_ADI"].ToString();

// Görünen metni oku
string metin = Lookup1.Text;

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

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

// Seçilen değeri oku
var secilen = Document1.Controls["Lookup1"].Value;

// Görünen metni oku
string metin = Document1.Controls["Lookup1"].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):

// Seçilen değeri oku
const secilen = this.Lookup1.value;

// Görünen metni oku
const metin = this.Lookup1.text;

// Seçimi temizle
this.Lookup1.value = null;

.Value mi Rows mı?

.Value seçilen kaydın saklanan değeridir, .Text ise ekranda görünen metindir. Seçilen kaydın diğer kolonlarına (firma adı, vergi no gibi) ulaşmak için .Rows koleksiyonunu kullanın. Forma birden çok alan getirecekseniz değeri ValueChanged içinde okuyup ilgili nesnelere yazmak en temiz yoldur.

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

ValueChanging seçim kesinleşmeden hemen önce çalışır; istemediğiniz bir seçimi burada iptal edebilirsiniz.

İstemci (TypeScript):

async Lookup1_OnValueChanging(args: Controls.EventArgs.IPropertyChangingEventArgs<any>) {
    if (args.newValue == null) {
        args.cancel = true;                                  // Boş seçimi iptal eder
        this.showMessage("Uyarı", "Lütfen bir kayıt seçin.", "Validation");
    }
}

Sunucu (C#):

void Lookup1_OnValueChanging(object sender, PropertyChangingEventArgs<object> e)
{
    if (e.NewValue == null)
    {
        e.Cancel = true;
        ShowMessage("Uyarı", "Lütfen bir kayıt seçin.",
            Bimser.CSP.FormControls.RuleManager.AlertType.Validation);
    }
}

İpuçları

• Seçilen kayıttan birden çok alan getireceğinizde değeri ValueChanged olayında okuyup ilgili TextBox'lara yazın; her alan için ayrı Lookup koymayın.
• AllowClear açıkken kullanıcı seçimi temizleyebilir; bu durumda Value boş gelebileceği için kodunuzda boş kontrolü yapın.
• Kısa ve değişmeyen listelerde DataSource yerine Items ile sabit liste vermek daha pratiktir.
• Tek bir değer açılır kutuya sığıyorsa ComboBox daha hafif bir seçenektir.

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: DataSource, Items

Behavior: AllowClear, GridOptions, ReadOnly, Required, Rows, SelectedItems, ShowOn, TabIndex, ValueType

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

Olaylar (Server): OnInit, OnLoad, OnRender, LookupButtonClick, ValidatingEvent, ValueChanging, ValueChanged, TextChanging, TextChanged

Olaylar (Client): OnInit, OnLoad, OnPreRender, OnRender, OnDataLoad, OnClick, OnDoubleClick, OnPropertyChanging, OnPropertyChanged, LookupButtonClick, ValidatingEvent, ValueChanging, ValueChanged, TextChanging, TextChanged