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: DateTimeOffset? (Nullable<DateTimeOffset>)

Nesnenin Value özelliği DateTimeOffset? tipindedir; boş olabilir. Bir DateTime atadığınızda sorunsuz dönüştürülür, ancak değeri okurken Convert.ToDateTime(...) ile DateTime tipine çevirmeniz gerekir. Text özelliği ise ekranda görünen biçimlendirilmiş metnin salt okunur kopyasıdır.

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	Belirli bir tarihten öncesini seçilemez yapar (alt sınır). Tip: DisableDate (bugüne göre Days / Months / Years ofseti, Enabled).
DisableAfter	Belirli bir tarihten sonrasını seçilemez yapar (üst sınır). Tip: DisableDate.
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.

not

DisableBefore / DisableAfter tipi: DisableDate

Bu iki özellik düz bir tarih değil, bugüne göre göreli bir sınır tanımlayan DisableDate nesnesidir. Üyeleri:

• Days / Months / Years — bugünden kaç gün / ay / yıl ofset alınacağı (Nullable<Int32>)
• Enabled — sınırın etkin olup olmadığı (Nullable<Boolean>)

Örneğin geçmiş tarihleri engellemek için DisableBefore'u bugüne (sıfır ofset) eşitlersiniz; gelecek 30 günden sonrasını engellemek için DisableAfter'a Days = 30 verirsiniz. Sabit bir tarih sınırı değil, göreli bir ofsettir.

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ı (çok dilli, MultiLanguageText).
Text Align	Yazının hizası.
Title	Fareyle üzerine gelince çıkan ipucu (tooltip, çok dilli).
Size Type	Genişlik davranışı (sabit / esnek).

Olaylar

DateTimePicker yalnızca birkaç gerçek olay sunar: kullanıcı tarih seçince değer ve metin olayları, kaydetmeden önce ise doğrulama olayı çalışır. Olaylar iki tarafta yazılabilir: sunucu olayları C# kodunda, istemci olayları tarayıcıdaki TypeScript kodunda.

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

Sunucu olayları (Server)

Olay	Ne zaman çalışır
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.
OnTextChanging	Görünen tarih metni değişmeden hemen önce.
OnTextChanged	Görünen tarih metni değiştikten hemen sonra.
OnValidating	Form kaydedilmeden önce değerin geçerliliği kontrol edilirken (ValidatingEvent).

İstemci olayları (Client)

Olay	Ne zaman çalışır
OnValueChanging / OnValueChanged	Tarih değeri değişmeden önce / sonra.
OnTextChanging / OnTextChanged	Görünen metin değişmeden önce / sonra.

Olay parametreleri

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

• newValue / NewValue — seçilmek istenen yeni tarih (DateTimeOffset?)
• oldValue / OldValue — önceki tarih (DateTimeOffset?)
• 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. Value tipi DateTimeOffset? olduğundan okurken Convert.ToDateTime(...) ile çevirin; yazarken hem .Value'ya tarihi hem de .Text'e biçimlendirilmiş metni atayın ki ekranda görünen değer değerle örtüşsün:

// Oku (DateTimeOffset? -> DateTime'a çevirerek)
if (DateTimePicker1.Value != null)
{
    DateTime tarih = Convert.ToDateTime(DateTimePicker1.Value);
}

// Yaz (.Value tarihi + .Text görünen metni birlikte)
DateTime now = DateTime.Now;
DateTimePicker1.Value = now;
DateTimePicker1.Text  = now.ToString("dd MMM yyyy HH:mm");

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

not

.Text salt okunurdur

Text özelliği yalnızca okunabilir (PROP String Text { get }); ekranda görünen biçimlendirilmiş tarihin kopyasıdır. Form kodunda .Text'e atama yapabilseniz de bu yalnızca görünen metni günceller; gerçek değer .Value'dur. Bu yüzden tarih atarken her zaman önce .Value'yu, ardından .Text'i set edin.

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

Akış kodunda nesneye Document1.Controls üzerinden erişirsiniz. Burada da değer DateTimeOffset? döner, Convert.ToDateTime(...) ile çevirin:

// Oku
DateTime tarih = Convert.ToDateTime(Document1.Controls["DateTimePicker1"].Value);

// Yaz (.Value + .Text)
DateTime now = DateTime.Now;
Document1.Controls["DateTimePicker1"].Value = now;
Document1.Controls["DateTimePicker1"].Text  = now.ToString("dd MMM yyyy HH:mm");

İ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

Value tipi boş (null) olabilir. Kullanıcı hiç tarih seçmediyse değer null gelir. Convert.ToDateTime(null) çalışma zamanında hata verir; bu yüzden tarihle işlem yapmadan önce mutlaka boş olup olmadığını kontrol edin. 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. Değer DateTimeOffset? olduğundan karşılaştırmadan önce DateTime'a çevirilir.

İ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<DateTimeOffset?> e)
{
    if (e.NewValue != null && Convert.ToDateTime(e.NewValue) < DateTime.Now)
    {
        e.Cancel = true;
        ShowMessage("Uyarı", "Geçmiş bir tarih seçemezsiniz.",
            Bimser.CSP.FormControls.RuleManager.AlertType.Validation);
    }
}

Örnek: göreli tarih sınırı (DisableDate)

DisableBefore ve DisableAfter, sabit bir tarih değil bugüne göre göreli bir sınır tanımlayan DisableDate nesneleridir. Aşağıda geçmiş tarihler kapatılır ve yalnızca önümüzdeki 30 güne tarih seçilebilir hale getirilir.

// Geçmişi kapat: bugünden öncesi seçilemez
DateTimePicker1.DisableBefore = new Bimser.CSP.FormControls.Controls.DisableDate
{
    Enabled = true,
    Days = 0
};

// Üst sınır: bugünden 30 gün sonrasını kapat
DateTimePicker1.DisableAfter = new Bimser.CSP.FormControls.Controls.DisableDate
{
    Enabled = true,
    Days = 30
};

İ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 DisableBefore ve DisableAfter'ı (DisableDate ofsetleri) kullanın; çoğu durumda tasarımcıdan ayarlamak koddan ayarlamaktan 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.
• Tarih atarken .Value'yu set ettikten sonra .Text'i de biçimlendirilmiş metinle güncelleyin; aksi halde değer ile ekranda görünen metin farklılaşabilir.

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 (DisableDate), DisableAfter (DisableDate), Format, ReadOnly, DefaultReadOnly, Required, SetTodayAsDefault, ShowTime, ShowToday, TabIndex

Appearance: Visible, Client Visible, Enabled, Client Enabled, DefaultEnabled, DefaultClientEnabled, Placeholder (MultiLanguageText), Text Align, Title (MultiLanguageText), Size Type, Caption, Style, Container Style, Custom Class Name, Loading

Diğer (kod tarafı): Value (DateTimeOffset?), Text (salt okunur), EntityPath, Indexable, ControlId, ContextMenuKey, ContextMenuColumnKey, ContextMenuTarget

Metotlar: GetData(), ClearDefaultValue(), GetDifferences(object)

Olaylar (Server): OnValueChanging, OnValueChanged, OnTextChanging, OnTextChanged, OnValidating

Olaylar (Client): OnValueChanging, OnValueChanged, OnTextChanging, OnTextChanged