ColorPicker

Kullanıcının görsel bir paletten renk seçmesini sağlayan nesnedir. Seçilen renk, metin değer olarak (ör. #FF0000) saklanır.

Değer tipi: string

Ne zaman kullanılır?

Kullanıcının bir renk belirlemesi gereken her yerde uygundur: kategori rengi, etiket rengi, tema seçimi, durum göstergesi. Renk paletini elle yazdırmak yerine, kullanıcıya tıklayarak seçebileceği bir alan sunar. Kullanıcıya sınırlı bir renk seti sunmak istiyorsanız hazır renkleri PresetColors ile tanımlayabilirsiniz.

Tasarımcı özellikleri

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

General

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

Behavior

Özellik	Açıklama
AllowClear	Seçili rengi temizleyip boş bırakmaya izin verir. Açıkken Value boş/null olabilir.
DisableAlpha	Saydamlık (alfa) ayarını kapatır; sadece tam renk seçilir.
Disabled	Nesneyi pasif yapar; kullanıcı renk seçemez.
Format	Renk değerinin biçimi (ColorFormat: hex / rgb / hsb).
PresetColors	Palette önceden sabitlenmiş hazır renkler (List<String>).
ReadOnly	Alanı salt okunur yapar.
Required	Alanı zorunlu yapar; boşsa form kaydedilmez.
ShowText	Seçili rengin metin değerini (ör. #FF0000) yanında gösterir.
Size	Nesnenin boyutu.
Tab Index	Tab tuşuyla geçiş sırasını belirler.
Trigger	Renk paletinin nasıl açılacağını belirler (TriggerType: hover / click).

Appearance

Özellik	Açıklama
Visible / Client Visible	Nesnenin görünürlüğü.
Enabled / Client Enabled	Nesnenin aktif olup olmadığı.
Caption	Nesnenin yanındaki etiket (ControlCaption).
Title	Nesnenin başlığı (MultiLanguageText, çok dilli olabilir).
Loading	Yükleme göstergesini açar/kapatır.
Size Type	Genişlik davranışı (sabit / esnek).

Bu nesnenin metin alanı yoktur

ColorPicker InputControl1[String]tabanlıdır; tek değer üyesiValue(string) 'tir. Metin kutularındakiText, Placeholder, Text Aligngibi özellikler veTextChanging/TextChangedolayları bu nesnede **yoktur**. Tüm okuma/yazmaValue` üzerinden yapılır.

Olaylar

Kullanıcı renk seçince ve palet açılıp kapanınca olaylar tetiklenir. ColorPicker'ın olay yüzeyi metin kutularından farklıdır: değer değişim olayları ile palet aç/kapa olayları vardır.

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

Sunucu olayları (Server)

Olay	Ne zaman çalışır
Open	Renk paleti açıldığında (OnOpen giriş noktası). Parametre: ColorPickerOpenEventArgs.
Close	Renk paleti kapandığında (OnClose giriş noktası). Parametre: ColorPickerCloseEventArgs (Color alanını taşır).
ValidatingEvent	Değer doğrulanırken (OnValidating giriş noktası, salt okunur olay).
ValueChanging	Renk değişmeden hemen önce (iptal edilebilir).
ValueChanged	Kullanıcı rengi seçip değer kesinleştiğinde. En sık kullanılan olaydır.

İstemci olayları (Client)

Aynı olaylar tarayıcı tarafında da (OnValueChanging, OnValueChanged, Open, Close) ele alınabilir. İstemci tarafında özellik adları küçük harfle yazılır (value).

Olay parametreleri

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

• newValue / NewValue — seçilmek istenen yeni renk
• oldValue / OldValue — önceki renk
• cancel / Cancel — true yapılırsa değişiklik iptal edilir (yalnızca Changing olaylarında)

ValueChanged olayında cancel yoktur (değişiklik artık gerçekleşmiştir). ColorPickerCloseEventArgs ise palet kapanırken seçilen rengi Color alanında taşır.

Kod örnekleri

Bir ColorPicker'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 (AllowClear acikken Value null olabilir, null-guvenli okuyun)
string renk = ColorPicker1.Value?.ToString();

// Yaz
ColorPicker1.Value = "#FF0000";

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

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

// Oku (null-guvenli)
string renk = Document1.Controls["ColorPicker1"].Value?.ToString();

// Yaz
Document1.Controls["ColorPicker1"].Value = "#FF0000";

İstemci kodu (TypeScript, tarayıcı)

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

this.ColorPicker1.value = "#FF0000";

AllowClear açıkken null kontrolü

AllowClear açıksa kullanıcı seçimi temizleyebilir ve Value boş/null olur. Bu yüzden okurken her zaman Value?.ToString() kullanın; doğrudan Value.ToString() çağrısı temizlenmiş bir seçicide hata (NullReferenceException) üretir.

Örnek: hazır renk paleti tanımlama (PresetColors)

Kullanıcıya serbest seçim yerine sabit bir palet sunmak için PresetColors listesini koddan doldurabilirsiniz:

ColorPicker1.PresetColors = new List<string> { "#FF0000", "#00FF00", "#0000FF", "#FFC107" };
ColorPicker1.Format = Bimser.CSP.FormControls.Enums.ColorFormat.hex;

Örnek: rengi doğrulama (OnValueChanging)

OnValueChanging renk değişmeden hemen önce çalışır; istemediğiniz bir rengi burada iptal edebilirsiniz. Aşağıdaki örnekte beyaz (#FFFFFF) seçilmesi engellenir.

İstemci (TypeScript):

async ColorPicker1_OnValueChanging(args: Controls.EventArgs.IPropertyChangingEventArgs<string>) {
    if (args.newValue == "#FFFFFF") {
        args.cancel = true;                                  // Renk değişimini iptal eder
        this.showMessage("Uyarı", "Beyaz renk seçilemez.", "Validation");
    }
}

Sunucu (C#):

void ColorPicker1_OnValueChanging(object sender, PropertyChangingEventArgs<string> e)
{
    if (e.NewValue == "#FFFFFF")
    {
        e.Cancel = true;
        ShowMessage("Uyarı", "Beyaz renk seçilemez.",
            Bimser.CSP.FormControls.RuleManager.AlertType.Validation);
    }
}

Örnek: palet kapanınca seçilen rengi okuma (OnClose)

Palet kapandığında ColorPickerCloseEventArgs seçilen rengi Color alanında taşır:

void ColorPicker1_OnClose(object sender, ColorPickerCloseEventArgs e)
{
    string secilen = e.Color;                                // Palet kapanirken secili renk
    // secilen rengi baska bir alanda kullanabilirsiniz
}

İpuçları

• Kullanıcıya sınırlı bir renk seti sunmak istiyorsanız PresetColors ile hazır renkleri tanımlayın; böylece serbest seçim yerine sabit paletten seçim yapılır.
• Saydamlığa ihtiyacınız yoksa DisableAlpha özelliğini açın; bu, alfa ayarını gizleyip seçimi sadeleştirir.
• Seçilen rengin kodunu kullanıcıya da göstermek için ShowText özelliğini açın.
• Format özelliğiyle saklanan değerin biçimini (hex / rgb / hsb) belirleyebilirsiniz.
• AllowClear açıkken Value boş olabileceğinden okumalarda her zaman Value?.ToString() kullanın.

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

General: Name, Field Name

Behavior: AllowClear, DisableAlpha, Disabled, Format, PresetColors, ReadOnly, Required, ShowText, Size, Tab Index, Trigger

Appearance: Visible, Client Visible, Enabled, Client Enabled, Caption, Title, Loading, Size Type

Olaylar (Server): Open, Close, ValidatingEvent, ValueChanging, ValueChanged

Olaylar (Client): Open, Close, ValueChanging, ValueChanged