TimePicker

Kullanıcının saat seçmesini sağlayan nesnedir. Bir saat dilimi (saat, dakika, isteğe bağlı saniye) girişi gereken alanlarda kullanılır.

Değer tipi: DateTime?

Ne zaman kullanılır?

Yalnızca saat bilgisi gereken alanlar için idealdir: toplantı saati, mesai başlangıç / bitiş saati, randevu saati. Hem tarih hem saat birlikte gerekiyorsa ya da sadece tarih gerekiyorsa DateTimePicker daha uygundur.

Tasarımcı özellikleri

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

General

Özellik	Açıklama
Name	Nesnenin koddaki adı (ör. TimePicker1). 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	Alanın yanına temizleme (x) düğmesi koyar; kullanıcı seçimi tek tıkla silebilir.
Format	Saatin görünüm biçimi (ör. HH:mm veya HH:mm:ss).
HourStep	Saat seçiminde kaçar kaçar artacağını belirler (ör. 1).
MinuteStep	Dakika seçiminde adım aralığı (ör. 5 ise 0, 5, 10...).
SecondStep	Saniye seçiminde adım aralığı.
DisabledHours	Seçilemeyecek saatlerin listesi (ör. mesai dışı saatler).
Use12Hours	12 saatlik (AM / PM) gösterimi açar. Kapalıyken 24 saatlik gösterim kullanılır.
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ı (sol / orta / sağ).
Title	Üzerine gelince çıkan ipucu (tooltip) yazısı.
Size Type	Genişlik davranışı (sabit / esnek).

Olaylar

Bir nesne açılırken olaylar belirli bir sırayla tetiklenir; kullanıcı saat 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ı saat seçerken: OnTextChanging → OnTextChanged, değer kesinleşince OnValueChanging → OnValueChanged

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

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	Seçim metni değişmeden hemen önce.
OnTextChanged	Seçim metni değiştikten hemen sonra.
OnValueChanging	Saat değeri değişmeden hemen önce (iptal edilebilir).
OnValueChanged	Kullanıcı saati seçip değer kesinleştiğinde. En sık kullanılan olaydır.
OnValidating	Alan doğrulanırken; geçerlilik kontrolü buraya yazılır.

İ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 değer
• oldValue / OldValue — önceki değer
• 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 TimePicker'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 tipi DateTime? olduğu için boş (null) olabileceğini unutmayın:

// Oku
DateTime? saat = TimePicker1.Value;

if (saat.HasValue)
{
    int s = saat.Value.Hour;     // Saat
    int dk = saat.Value.Minute;  // Dakika
}

// Yaz
TimePicker1.Value = DateTime.Today.AddHours(9).AddMinutes(30);  // 09:30

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

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

// Oku
DateTime? saat = Document1.Controls["TimePicker1"].Value;

// Yaz
Document1.Controls["TimePicker1"].Value = DateTime.Today.AddHours(17);  // 17:00

İstemci kodu (TypeScript, tarayıcı)

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

// Oku
const saat = this.TimePicker1.value;

// Yaz
this.TimePicker1.value = new Date();
this.TimePicker1.text  = "09:30";

.Value mi .Text mi?

.Value saklanan saat değeridir (DateTime?), .Text ekranda görünen metindir ("09:30" gibi). Hesaplama yaparken .Value ile çalışın; sadece görünümü değiştirecekseniz .Text yeterlidir.

Örnek: mesai dışı saati engelleme (OnValueChanging)

OnValueChanging değer değişmeden hemen önce çalışır; istemediğiniz bir saati burada iptal edebilirsiniz. Aşağıdaki örnekte 18:00'den sonrası engellenir.

İstemci (TypeScript):

async TimePicker1_OnValueChanging(args: Controls.EventArgs.IPropertyChangingEventArgs<Date>) {
    if (args.newValue && args.newValue.getHours() >= 18) {
        args.cancel = true;                                  // Saat seçimini iptal eder
        this.showMessage("Uyarı", "Mesai saati dışında saat seçilemez.", "Validation");
    }
}

Sunucu (C#):

void TimePicker1_OnValueChanging(object sender, PropertyChangingEventArgs<DateTime?> e)
{
    if (e.NewValue.HasValue && e.NewValue.Value.Hour >= 18)
    {
        e.Cancel = true;
        ShowMessage("Uyarı", "Mesai saati dışında saat seçilemez.",
            Bimser.CSP.FormControls.RuleManager.AlertType.Validation);
    }
}

İpuçları

• Dakikaları beşer beşer ilerletmek için MinuteStep değerini 5 yapın; kullanıcı 0, 5, 10... gibi düzenli değerler seçer.
• Sadece saat ve dakika gösterilecekse Format değerini HH:mm yapın; saniye gereksiz yere ekranı kalabalıklaştırmaz.
• Belirli saatleri kapatmak için DisabledHours listesini kullanın (ör. gece saatleri).
• Hem tarih hem saat gerekiyorsa bu nesne yerine DateTimePicker 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, Format, HourStep, MinuteStep, SecondStep, DisabledHours, Use12Hours, ReadOnly, Required, TabIndex

Appearance: Visible, Client Visible, Enabled, Client Enabled, Placeholder, Text Align, Title, Size Type, Text, 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