DateTimePicker

Kullanıcının takvimden tarih seçmesini sağlayan nesnedir. İstenirse saat de seçtirebilir. Başlangıç tarihi, teslim tarihi, doğum tarihi gibi alanlar için kullanılır.

Değer tipi: DateTime?

Ne zaman kullanılır?

Tarih ya da tarih + saat girişi gereken her yerde kullanın: talep tarihi, termin, randevu saati. Kullanıcı serbest metin yazmaz, takvimden seçer; böylece hatalı biçimde tarih girilmesinin önüne geçilir. Saat de istiyorsanız ShowTime özelliğini açın.

Tasarımcı özellikleri

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

General

Özellik	Açıklama
Name	Nesnenin koddaki adı (ör. DateTimePicker1). Koddan bu adla erişirsiniz.
Field Name	Veritabanındaki alanı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.

Behavior

Özellik	Açıklama
AllowClear	Seçilen tarihi temizlemek için kutuda bir (×) düğmesi gösterir.
DisableBefore	Bu tarihten öncesini seçilemez yapar (alt sınır).
DisableAfter	Bu tarihten sonrasını seçilemez yapar (üst sınır).
Format	Tarihin gösterim biçimi (ör. dd.MM.yyyy veya dd.MM.yyyy HH:mm).
ReadOnly	Alanı salt okunur yapar.
Required	Alanı zorunlu yapar; boşsa form kaydedilmez.
SetTodayAsDefault	Form açıldığında bugünün tarihini varsayılan olarak yazar.
ShowTime	Tarihin yanında saat seçimini de açar.
ShowToday	Takvimde "Bugün" düğmesini gösterir.
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ığı.
Placeholder	Alan boşken görünen soluk ipucu yazısı.
Text Align	Yazının hizası.
Title	Fareyle üzerine gelince çıkan ipucu (tooltip).
Size Type	Genişlik davranışı (sabit / esnek).

Olaylar

Bir nesne açılırken olaylar belirli bir sırayla tetiklenir; kullanıcı tarih seçince de ayrı olaylar çalışır. Doğru kodu doğru olaya yazmak için bu sırayı bilmek işinizi kolaylaştırır.

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

Kullanıcı tarih seçince: OnValueChanging → OnValueChanged

Olaylar iki tarafta çalışabilir: sunucu olayları C# kodunda, istemci olayları tarayıcıdaki TypeScript kodunda. DateTimePicker'ın 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.
OnTextChanging	Görünen tarih metni değişmeden hemen önce.
OnTextChanged	Görünen tarih metni değiştikten hemen sonra.
OnValueChanging	Tarih değeri değişmeden hemen önce (iptal edilebilir).
OnValueChanged	Kullanıcı tarih seçip değer kesinleştiğinde. En sık kullanılan olaydır.
OnValidating	Form kaydedilmeden önce değerin geçerliliği kontrol edilirken.

İ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 tarih
• oldValue / OldValue — önceki tarih
• 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 DateTimePicker'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. Değer DateTime? tipindedir (boş olabilir):

// Oku
DateTime? tarih = DateTimePicker1.Value;

// Yaz
DateTimePicker1.Value = DateTime.Now;

// Boş mu kontrol et
if (DateTimePicker1.Value == null)
{
    ShowMessage("Uyarı", "Lütfen bir tarih seçin.",
        Bimser.CSP.FormControls.RuleManager.AlertType.Validation);
}

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

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

// Oku
DateTime? tarih = Document1.Controls["DateTimePicker1"].Value;

// Yaz
Document1.Controls["DateTimePicker1"].Value = DateTime.Now;

İ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 tarih = this.DateTimePicker1.value;

// Yaz
this.DateTimePicker1.value = new Date();

Boş tarihe dikkat

DateTime? tipi boş (null) olabilir. Kullanıcı hiç tarih seçmediyse değer null gelir. Tarihle işlem yapmadan önce mutlaka boş olup olmadığını kontrol edin; aksi halde kod hata verir. Zorunlu tutmak istiyorsanız Required özelliğini açmanız en pratik yoldur.

Örnek: geçmiş tarihi engelleme (OnValueChanging)

OnValueChanging değer değişmeden hemen önce çalışır; istemediğiniz bir tarihi burada iptal edebilirsiniz. Aşağıdaki örnekte bugünden önceki bir tarihin seçilmesi engellenir.

İstemci (TypeScript):

async DateTimePicker1_OnValueChanging(args: Controls.EventArgs.IPropertyChangingEventArgs<Date>) {
    if (args.newValue && args.newValue < new Date()) {
        args.cancel = true;                                  // Tarih değişimini iptal eder
        this.showMessage("Uyarı", "Geçmiş bir tarih seçemezsiniz.", "Validation");
    }
}

Sunucu (C#):

void DateTimePicker1_OnValueChanging(object sender, PropertyChangingEventArgs<DateTime?> e)
{
    if (e.NewValue != null && e.NewValue < DateTime.Now)
    {
        e.Cancel = true;
        ShowMessage("Uyarı", "Geçmiş bir tarih seçemezsiniz.",
            Bimser.CSP.FormControls.RuleManager.AlertType.Validation);
    }
}

İpuçları

• Sadece tarih yetiyorsa ShowTime özelliğini kapalı bırakın; saat de gerekiyorsa açın.
• Geçmiş ya da gelecek tarihleri sınırlamak için kod yazmak yerine DisableBefore ve DisableAfter özelliklerini kullanın; tasarımcıdan ayarlamak daha pratiktir.
• Form açılır açılmaz bugünün tarihinin dolu gelmesini istiyorsanız SetTodayAsDefault özelliğini açın.
• Zorunlu tarih alanlarında kod ile boş kontrolü yapmak yerine Required özelliğini kullanın.

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

Behavior: AllowClear, DisableBefore, DisableAfter, Format, ReadOnly, Required, SetTodayAsDefault, ShowTime, ShowToday, TabIndex

Appearance: Visible, Client Visible, Enabled, Client Enabled, Placeholder, Text Align, Title, Text, Size Type, Value

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

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