Transfer

Kullanıcının soldaki kaynak listeden öğeleri seçip sağdaki hedef listeye taşıyarak çoklu seçim yaptığı nesnedir. İki panelli yapısı sayesinde "hangileri seçili" bilgisini görsel olarak net biçimde sunar.

Değer tipi: object (seçilen öğelerin listesi)

Ne zaman kullanılır?

Bir listeden birden fazla öğenin seçilmesi gerektiğinde ve seçilenlerin ayrı bir panelde görünür olması istendiğinde idealdir: bir projeye atanacak kişiler, bir rola verilecek yetkiler, dağıtım listesine eklenecek birimler gibi. Tek bir seçim yeterliyse ComboBox, az sayıda seçenek için CheckBoxList daha uygun olabilir.

Tasarımcı özellikleri

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

General

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

Veri kaynağı (Data Source)

Transfer'in soldaki kaynak listesinde hangi öğelerin görüneceğini bu özellikler belirler.

Özellik	Açıklama
DataSource	Öğelerin çekileceği veri kaynağı (sorgu / liste).
DataSourceType	Veri kaynağının türü (statik liste, sorgu vb.).
Data	Nesneye doğrudan verilen satır listesi (anahtar/değer çiftleri).
Items	Tasarım anında elle eklenen öğeler.
SelectedValues	Seçili (hedefe taşınmış) öğelerin değerleri.
SelectedItemValues	Seçili öğelerin değer listesi.
TextSeparator	Birden çok öğenin metni birleştirilirken kullanılan ayraç.
ValueSeparator	Birden çok öğenin değeri birleştirilirken kullanılan ayraç.

Behavior

Özellik	Açıklama
AllowSelectAll	"Tümünü seç" seçeneğini açar; tüm öğeler tek hamlede taşınabilir.
ShowSearch	Listelerin üstünde arama kutusu gösterir.
ReadOnly	Nesneyi salt okunur yapar; öğeler taşınamaz.
Required	Alanı zorunlu yapar; hedef liste boşsa form kaydedilmez.
SourceTitle	Soldaki kaynak panelin başlığı (çok dilli).
TargetTitle	Sağdaki hedef panelin başlığı (çok dilli).
SelectedItems	Seçili öğelerin listesi (ListItem).
ValueType	Öğe değerlerinin tipi (metin, sayı, tarih).
DateValueFormat	Değer tarih ise kullanılacak tarih biçimi.
DecimalValuePrecision	Değer ondalık ise gösterilecek 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ığı.
Title	Nesnenin başlığı (çok dilli).
Text	Seçili öğelerin birleştirilmiş metni.

Olaylar

Bir nesne açılırken olaylar belirli bir sırayla tetiklenir; kullanıcı öğe taşıyı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ı öğe taşırken: OnValueChanging → OnValueChanged

Olaylar iki tarafta çalışabilir: sunucu olayları C# kodunda, istemci olayları tarayıcıdaki TypeScript kodunda. Transfer'in 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	Hedef listedeki seçim kesinleştiğinde. En sık kullanılan olaydır.
OnTextChanging / OnTextChanged	Seçili öğelerin metni değişmeden önce / sonra.
OnValidating	Alan doğrulanırken çalışır; özel kurallar burada yazılır.

İ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

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 Transfer'e üç yerden erişebilirsiniz. Sunucu örnekleri turuncu, istemci örnekleri kırmızı çerçevelidir. Değer tipi object olduğundan değeri okurken var kullanmak en pratiğidir.

Form kodu (C#, sunucu)

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

// Oku (seçilen öğelerin listesi)
var secilenler = Transfer1.Value;

// Seçili değerler üzerinde dön
foreach (var deger in Transfer1.SelectedValues)
{
    // her bir seçili öğenin değeri
}

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

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

// Oku
var secilenler = Document1.Controls["Transfer1"].Value;

İstemci kodu (TypeScript, tarayıcı)

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

// Seçili değerleri oku
const secilenler = this.Transfer1.value;

Değer bir listedir

Transfer'in değeri tek bir metin değil, seçilen öğelerin listesidir. Bu yüzden .Value.ToString() yerine listeyi doğrudan var ile alıp üzerinde dönmek daha doğrudur. Seçili öğelere ulaşmanın en net yolu SelectedValues özelliğidir.

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

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

İstemci (TypeScript):

async Transfer1_OnValueChanging(args: Controls.EventArgs.IPropertyChangingEventArgs<object>) {
    if (this.Transfer1.value == null) {
        args.cancel = true;                                  // Seçimi iptal eder
        this.showMessage("Uyarı", "En az bir öğe seçmelisiniz.", "Validation");
    }
}

Sunucu (C#):

void Transfer1_OnValueChanging(object sender, PropertyChangingEventArgs<object> e)
{
    if (e.NewValue == null)
    {
        e.Cancel = true;
        ShowMessage("Uyarı", "En az bir öğe seçmelisiniz.",
            Bimser.CSP.FormControls.RuleManager.AlertType.Validation);
    }
}

İpuçları

• Çok sayıda öğe taşınacaksa ShowSearch özelliğini açın; kullanıcı listeyi arayarak hızla bulur.
• Tüm öğelerin tek hamlede taşınması gerekebiliyorsa AllowSelectAll özelliğini açın.
• Kaynak ve hedef panellerin başlıklarını SourceTitle ve TargetTitle ile anlamlı yazın (ör. "Tüm birimler" / "Seçili birimler").
• Hedef listenin boş bırakılmaması gerekiyorsa kod yazmak yerine Required özelliğini kullanın.

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

General: Name, Field Name

Data Source: Data, DataSource, DataSourceType, Items, SelectedItemValues, SelectedValues, TextSeparator, ValueSeparator

Behavior: AllowSelectAll, DateValueFormat, DecimalValuePrecision, ReadOnly, Required, SelectedItems, ShowSearch, SourceTitle, TabIndex, TargetTitle, ValueType

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

Olaylar (Server): OnInit, OnLoad, OnRender, OnValueChanging, OnValueChanged, OnTextChanging, OnTextChanged, OnValidating

Olaylar (Client): OnInit, OnLoad, OnPreRender, OnRender, OnDataLoad, OnPropertyChanging, OnPropertyChanged, OnClick, OnDoubleClick, OnValueChanging, OnValueChanged, OnTextChanging, OnTextChanged