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: DateTimeOffset? (Nullable). Saat bilgisi bir DateTimeOffset üzerinde taşınır; seçilen saat o değerin gün içindeki zaman kısmıdır.

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 (List<Int32>, ör. mesai dışı saatler).
Use12Hours	12 saatlik (AM / PM) gösterimi açar. Kapalıyken 24 saatlik gösterim kullanılır.
ReadOnly / DefaultReadOnly	Alanı salt okunur yapar; DefaultReadOnly tasarım anındaki varsayılan salt-okunur durumudur.
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ığı.
Default Enabled / Default Client Enabled	Tasarım anındaki varsayılan aktiflik durumu (çalışma anındaki Enabled'dan ayrıdır).
Placeholder	Alan boşken görünen soluk ipucu yazısı (çok dilli MultiLanguageText).
Text Align	Yazının hizası (sol / orta / sağ).
Title	Üzerine gelince çıkan ipucu (tooltip) yazısı (çok dilli MultiLanguageText).
Size Type	Genişlik davranışı (sabit / esnek).
Custom Class Name	Nesneye eklenecek özel CSS sınıfı.
Style / Container Style	Nesnenin ve sarmalayan hücrenin stil ayarları.
Context Menu Key / Context Menu Target	Nesneye bir ContextMenu bağlar; hedef Container / None olabilir.

Olaylar

TimePicker yalnızca değer ve metin değişikliği olayları ile doğrulama olayını sunar. Açılış / yaşam döngüsü (OnInit, OnLoad, OnRender vb.) olayları bu nesnenin kendi olay yüzeyinde yer almaz.

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

Sunucu olayları (Server)

Olay	Ne zaman çalışır
OnTextChanging	Görünen saat metni değişmeden hemen önce.
OnTextChanged	Saat 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. ValidatingEventArgs üzerinden e.Cancel = true ile değer reddedilir.

İstemci olayları (Client)

Aynı değer / metin olayları istemci tarafında da çalışır:

Olay	Ne zaman çalışır
OnValueChanging / OnValueChanged	Saat değeri değişmeden önce / sonra.
OnTextChanging / OnTextChanged	Saat metni değişmeden ö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 (OnValueChanging için DateTimeOffset?)
• 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 DateTimeOffset? olduğu için boş (null) olabileceğini unutmayın. Saat bilgisi DateTimeOffset üzerinde taşındığından gün içindeki zaman kısmını .TimeOfDay / .Hour / .Minute ile okursunuz:

// Oku
DateTimeOffset? saat = TimePicker1.Value;

if (saat.HasValue)
{
    int s  = saat.Value.Hour;        // Saat
    int dk = saat.Value.Minute;      // Dakika
    TimeSpan zaman = saat.Value.TimeOfDay;  // Gün içi zaman
}

// Yaz (DateTime de DateTimeOffset?'e atanabilir)
TimePicker1.Value = DateTime.Today.AddHours(9).AddMinutes(30);  // 09:30

// Temizle (AllowClear ile aynı etki)
TimePicker1.Value = null;

not

.Text salt okunurdur

Bu nesnede Text özelliği yalnızca okunabilir (get); sunucu tarafında TimePicker1.Text = "..." yazamazsınız. Görünen metin değeri biçimlendiren Format özelliğinden türetilir. Değeri değiştirmek için Value'yu set edin.

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

Akış kodunda nesneye Document1.Controls üzerinden erişirsiniz. Okurken null güvenli kalıbı kullanın:

// Oku (null güvenli)
string metin = Document1.Controls["TimePicker1"].Value?.ToString();

// Tipli okuma
var deger = Document1.Controls["TimePicker1"].Value;
if (deger != null)
{
    DateTimeOffset saat = Convert.ToDateTime(deger);  // DateTimeOffset olarak çözümlenir
}

// 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):

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

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

Değeri okuma

.Value saklanan saat değeridir (DateTimeOffset?). Hesaplama yaparken .Value ile çalışın; gün içi zamana saat.Value.TimeOfDay üzerinden erişirsiniz. Sunucu tarafında .Text salt okunur olduğundan görünen metni biçimlendirmek için Format özelliğini kullanın.

Ö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<DateTimeOffset?> 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);
    }
}

Yöntemler

Tipli TimePicker nesnesi üzerinde kullanılabilen başlıca yöntemler:

• GetData() — değeri ve FormControlGroupTypes etiketini taşıyan FormControlDataWithType döndürür.
• ClearDefaultValue() — tasarım anındaki varsayılan değeri kaldırır.
• GetDifferences(otherObj) — başka bir nesneyle değişen özelliklerin sözlüğünü döndürür.
• IsValid() — DataBoundControl'den gelir; alanın kendi doğrulama kurallarından geçip geçmediğini döndürür.

İ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).
• Değeri koddan temizlemek için TimePicker1.Value = null; atayın; tasarımda AllowClear ile kullanıcıya da temizleme düğmesi sunabilirsiniz.
• 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, DefaultReadOnly, Required, TabIndex, Indexable

Appearance: Visible, Client Visible, Enabled, Client Enabled, Default Enabled, Default Client Enabled, Placeholder, Text Align, Title, Size Type, CustomClassName, Style, ContainerStyle, ContextMenuKey, ContextMenuColumnKey, ContextMenuTarget, ControlId, EntityPath, Loading

Değer: Value (DateTimeOffset?), Text (salt okunur)

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

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

Yöntemler: GetData, ClearDefaultValue, GetDifferences, LoadData, IsValid