DateRangePicker

Kullanıcının takvimden bir başlangıç ve bir bitiş tarihi seçerek bir tarih aralığı belirlemesini sağlayan nesnedir. İzin tarihleri, proje başlangıç-bitişi, rezervasyon dönemi gibi iki uçlu tarih alanları için kullanılır.

Ne zaman kullanılır?

İki uçlu (başlangıç ve bitiş) tarih seçimi gereken her yerde idealdir: izin dönemi, sözleşme süresi, raporlama aralığı. Tek bir tarih için DatePicker, saat içeren tek bir an için DateTimePicker daha uygundur.

Değer tipi: DateTime?

Değer boş (null) olabilir; kullanıcı henüz seçim yapmadıysa değer atanmamıştır. Başlangıç ve bitiş tarihleri nesnenin StartDate / EndDate ayarlarıyla yönetilir.

Tasarımcı özellikleri

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

General

Özellik	Açıklama
Name	Nesnenin koddaki adı (ör. DateRangePicker1). 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
StartDate	Başlangıç tarihi ucunun ayarları (varsayılan değer, sınırlar).
EndDate	Bitiş tarihi ucunun ayarları (varsayılan değer, sınırlar).
Mode	Takvimin seçim kipi (gün, ay, yıl gibi).
Format	Tarihin ekranda gösterileceği biçim (ör. dd.MM.yyyy).
ShowTime	Tarihle birlikte saat seçimini de açar.
ShowToday	Takvimde "Bugün" düğmesini gösterir.
ActiveDateType	Takvim açıldığında hangi tarihin etkin geleceğini belirler.
DateLimitType	Seçilebilir tarih aralığına getirilen sınırın türü.
DisabledDateType	Hangi tür tarihlerin kapatılacağını belirler (ör. geçmiş / gelecek).
DisabledDateRange	Bugüne göre kaç günlük bir aralığın kapatılacağını belirler.
DisabledDates	Tek tek seçilemez yapılan tarihlerin listesi.
AllowClear	Seçimi temizleme (x) düğmesini gösterir.
ReadOnly	Alanı salt okunur yapar.
Required	Alanı zorunlu yapar; 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ığı.
Placeholder	Alan boşken görünen soluk ipucu yazısı.
Text Align	Yazının hizası.
Title	Fare ile üzerine gelince çıkan başlık (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ı seçim yaparken: OnTextChanging → OnTextChanged, tarih kesinleşince OnValueChanging → OnValueChanged

Olaylar iki tarafta çalışabilir: sunucu olayları C# kodunda, istemci olayları tarayıcıdaki TypeScript kodunda. DateRangePicker'ı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 metin değişmeden hemen önce.
OnTextChanged	Görünen metin değiştikten hemen sonra.
OnValueChanging	Tarih değişmeden hemen önce (iptal edilebilir).
OnValueChanged	Kullanıcı tarihi seçip değer kesinleştiğinde. En sık kullanılan olaydır.
OnValidating	Alan doğrulanırken çalışır; geçersiz seçim burada engellenebilir.

İ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 / OnTextChanging olayları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 DateRangePicker'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? olduğu için boş olabilir; okumadan önce kontrol edin:

// Oku
DateTime? baslangic = DateRangePicker1.Value;
if (baslangic.HasValue)
{
    DateTime tarih = baslangic.Value;
}

// Yaz
DateRangePicker1.Value = DateTime.Today;

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

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

// Oku
DateTime? baslangic = Document1.Controls["DateRangePicker1"].Value;

// Yaz
Document1.Controls["DateRangePicker1"].Value = DateTime.Today;

İstemci kodu (TypeScript, tarayıcı)

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

this.DateRangePicker1.value = null;
this.DateRangePicker1.text  = "";

Boş değere dikkat

DateRangePicker'ın değeri DateTime? olduğu için kullanıcı seçim yapmadığında null olur. C# tarafında okumadan önce HasValue ile kontrol edin, yoksa hata alırsınız.

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

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

İstemci (TypeScript):

async DateRangePicker1_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 DateRangePicker1_OnValueChanging(object sender, PropertyChangingEventArgs<DateTime?> e)
{
    if (e.NewValue.HasValue && e.NewValue.Value < DateTime.Today)
    {
        e.Cancel = true;
        ShowMessage("Uyarı", "Geçmiş bir tarih seçemezsiniz.",
            Bimser.CSP.FormControls.RuleManager.AlertType.Validation);
    }
}

İpuçları

• Seçilemeyecek tarihleri kod ile kontrol etmek yerine DisabledDates, DisabledDateType ve DisabledDateRange ayarlarını kullanın; tasarımda belirlemek daha temizdir.
• Nesnenin Required özelliğini kullanarak kod ile boş/dolu kontrolü yapmanıza gerek kalmaz.
• Saat de seçtirmeniz gerekiyorsa ShowTime özelliğini açın.
• Ekrandaki tarih biçimini Format ile (ör. dd.MM.yyyy) belirleyebilirsiniz.

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: ActiveDateType, AllowClear, DateLimitType, DisabledDateRange, DisabledDates, DisabledDateType, EndDate, Format, Mode, ReadOnly, Required, ShowTime, ShowToday, StartDate, TabIndex

Appearance: ClientEnabled, ClientVisible, Enabled, Placeholder, SizeType, Text, TextAlign, Title, Value, Visible

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