Signature

Kullanıcının fare, kalem ya da dokunmatik ekranla el yazısı imza atabileceği nesnedir. Çizilen imza bir görüntü olarak saklanır ve forma kaydedilir.

Ne zaman kullanılır?

Onay, teslim alma, muvafakat gibi kullanıcının el imzasını gerektiren adımlarda kullanılır. Teslim formları, izin onayları ve sözleşme ekranları tipik örnektir. İmza yerine ad/soyad metni yeterliyse TextBox daha uygundur.

Değer tipi: string

İmzanın kendisi nesnenin Value özelliğinde metin (Base64 görüntü verisi) olarak tutulur. Yani değeri okuyup yazarken string olarak işlersiniz. Signature bir metin nesnesi değildir; MaxLength ya da Field Size gibi sınırlamalar görüntü verisinin boyutunu etkilemez.

Tasarımcı özellikleri

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

General

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

Behavior

Özellik	Açıklama
Width	İmza alanının genişliği (piksel). Int32.
Height	İmza alanının yüksekliği (piksel). Int32.
PenColor	Kalem rengi. Onaltılık renk değeri taşıyan bir string'dir (ör. #000000).
MinPenSize	Kalem ucunun en ince genişliği. Double.
MaxPenSize	Kalem ucunun en kalın genişliği. Double.
DotSize	Tek noktaya dokununca oluşan iz büyüklüğü. Int32.
ShowBorder	İmza alanının çevresine çerçeve çizer.
ShowLegalWarning	İmza alanının altında yasal uyarı metni gösterir.
ReadOnly	Alanı salt okunur yapar; yeni imza atılamaz.
Required	Alanı zorunlu yapar; imza boşsa form kaydedilmez.
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	Fareyle üzerine gelince çıkan ipucu başlığı (çok dilli, MultiLanguageText).

Metin nesnelerinden farkı

Signature bir görüntü/tuval nesnesidir. Metin kutularındaki Placeholder, Text Align ve Text gibi özellikler bu nesnede anlamlı değildir ve çalışan bir görünüm seçeneği olarak sunulmaz. Görünür kalem/çizim ayarları yukarıdaki Behavior sekmesindeki Width, Height, PenColor, MinPenSize, MaxPenSize ve DotSize değerleridir.

Olaylar

Olaylar iki tarafta çalışabilir: sunucu olayları C# kodunda, istemci olayları tarayıcıdaki TypeScript kodunda. Signature bir görüntü nesnesi olduğu için metin olayları (OnTextChanging / OnTextChanged) yoktur; nesne yalnızca değer ve doğrulama olaylarını sunar.

Sunucu olayları (Server)

Olay	Ne zaman çalışır
OnValueChanging	İmza değişmeden hemen önce (iptal edilebilir).
OnValueChanged	Kullanıcı imza atıp değer kesinleştiğinde. En sık kullanılan olaydır.
OnValidating	Form kaydedilirken / doğrulanırken çalışır. İmza zorunluluğunu kayıt anında dayatmak için en doğru yerdir.

İstemci olayları (Client)

Tarayıcı tarafında değer olayları kullanılabilir:

Olay	Ne zaman çalışır
OnValueChanging	İmza değişmeden hemen önce (iptal edilebilir).
OnValueChanged	Kullanıcı imza atıp değer kesinleştiğinde.

Olay parametreleri

OnValueChanging olayının parametresi (args TS, e C#) ş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)

OnValueChanged olayında cancel yoktur (değişiklik artık gerçekleşmiştir).

OnValidating olayının parametresi ValidatingEventArgs'tir: Cancel (true yapılırsa doğrulama başarısız sayılır) ve Messages (List<ValidationMessage> — kullanıcıya gösterilecek doğrulama mesajları).

Kod örnekleri

Bir Signature'a üç yerden erişebilirsiniz. Sunucu örnekleri turuncu, istemci örnekleri kırmızı çerçevelidir. İmza, Value içinde string (Base64 görüntü) olarak tutulur. Değer okuma/yazma/temizleme dışında dışarıya açık, belgelenmeye değer bir metot yoktur (GetData / GetValueAsObject gibi üyeler iç kullanımdır).

Form kodu (C#, sunucu)

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

// Oku
string imza = Signature1.Value;

// İmza atılmış mı kontrol et
bool imzaVar = !string.IsNullOrEmpty(Signature1.Value);

// Temizle
Signature1.Value = "";

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

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

// Oku
string imza = Document1.Controls["Signature1"].Value.ToString();

// Temizle
Document1.Controls["Signature1"].Value = "";

İstemci kodu (TypeScript, tarayıcı)

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

// Oku
const imza = this.Signature1.value;

// Temizle
this.Signature1.value = "";

İmza dolu mu?

İmza alanı boşken Value boş string'tir. Zorunluluk için Required özelliğini açın; ek bir kontrol gerekiyorsa Value boş mu diye bakın. Değeri ekranda göstermeye çalışmayın, içinde Base64 görüntü verisi vardır.

Örnek: imza zorunluluğunu kayıtta doğrulama (OnValidating)

İmza zorunluluğunu form kaydedilirken dayatmanın doğru yeri OnValidating olayıdır. e.Cancel = true ile kaydı durdurur, e.Messages listesine bir ValidationMessage ekleyerek kullanıcıyı uyarırsınız.

Sunucu (C#):

void Signature1_OnValidating(object sender, ValidatingEventArgs e)
{
    if (string.IsNullOrEmpty(Signature1.Value))
    {
        e.Cancel = true;
        e.Messages.Add(new Bimser.CSP.FormControls.RuleManager.ValidationMessage
        {
            Message = "Lütfen imzanızı atın.",
            Type = Bimser.CSP.FormControls.RuleManager.AlertType.Validation
        });
    }
}

Örnek: boş imzayı anında engelleme (OnValueChanging)

OnValueChanging imza değişmeden hemen önce çalışır; istemediğiniz bir durumu burada iptal edebilirsiniz. Aşağıdaki örnekte imzanın boşaltılması anında engellenir.

İstemci (TypeScript):

async Signature1_OnValueChanging(args: Controls.EventArgs.IPropertyChangingEventArgs<string>) {
    if (args.newValue == "") {
        args.cancel = true;                                  // Boş imzayı iptal eder
        this.showMessage("Uyarı", "Lütfen imzanızı atın.", "Validation");
    }
}

Sunucu (C#):

void Signature1_OnValueChanging(object sender, PropertyChangingEventArgs<string> e)
{
    if (string.IsNullOrEmpty(e.NewValue))
    {
        e.Cancel = true;
        ShowMessage("Uyarı", "Lütfen imzanızı atın.",
            Bimser.CSP.FormControls.RuleManager.AlertType.Validation);
    }
}

İpuçları

• İmzayı zorunlu yapmak için kod yazmak yerine Required özelliğini açmanız genellikle yeterlidir. Kayıt anında ek koşullu doğrulama gerekiyorsa OnValidating olayını kullanın.
• Dokunmatik ekran ve tablet kullanımı için Width ve Height değerlerini yeterince büyük tutun.
• Kalem kalınlığını ayarlayan MinPenSize ve MaxPenSize değerleri Double'dır; ondalıklı değer verebilirsiniz.
• ShowLegalWarning ile imza alanının altına yasal bir uyarı metni gösterebilir, onay süreçlerini netleştirebilirsiniz.
• İmza tamamlandıktan sonra değişmesini istemiyorsanız ilgili adımda ReadOnly özelliğini açın.

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

General: Name, Field Name, Size

Behavior: DotSize, Height, MaxPenSize, MinPenSize, PenColor, ReadOnly, Required, ShowBorder, ShowLegalWarning, TabIndex, Width

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

Olaylar (Client): OnValueChanging, OnValueChanged

Olaylar (Server): OnValueChanging, OnValueChanged, OnValidating