Map

Form üzerinde gömülü bir harita gösteren nesnedir. Üzerine işaretçi (marker) koyabilir, iki nokta arasında rota çizebilir ve kullanıcının seçtiği konumu saklayabilirsiniz.

Değer tipi: string

Seçilen konum, harita nesnesinin Value alanında metin olarak (koordinat) tutulur.

Ne zaman kullanılır?

Adres, teslimat noktası, şube konumu, arıza yeri gibi coğrafi bilgileri form üzerinde göstermek ve seçtirmek için kullanılır. Sadece düz adres metni isteyeceğiniz durumlarda bir TextBox yeterlidir; konumu harita üzerinde görsel olarak göstermek veya seçtirmek istediğinizde Map nesnesini tercih edin.

Tasarımcı özellikleri

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

General

Özellik	Açıklama
Name	Nesnenin koddaki adı (ör. Map1). Koddan bu adla erişirsiniz.
Field Name	Konum değerinin veritabanında saklanacağı alanın adı.

Behavior

Özellik	Açıklama
Provider	Harita sağlayıcısı (ör. Google). Hangi harita servisinin kullanılacağını belirler.
ApiKey	Harita sağlayıcısının istediği API anahtarı. Haritanın yüklenebilmesi için gereklidir.
Type	Harita türü (yol, uydu vb. görünüm).
Center	Haritanın açılışta ortalanacağı koordinat (enlem/boylam).
Zoom	Açılıştaki yakınlaştırma seviyesi. Büyük değer daha yakın görünümdür.
AutoAdjust	İşaretçiler varsa haritayı otomatik olarak hepsini kapsayacak şekilde ayarlar.
Controls	Harita üzerindeki zoom / tür gibi kontrollerin görünürlüğü.
Markers	Harita üzerine yerleştirilecek işaretçilerin listesi.
MarkerIconSrc	İşaretçiler için kullanılacak özel simgenin yolu.
Routes	Harita üzerinde çizilecek rotaların listesi.
RouteMode	Rota modu; noktalar arası yol çiziminin nasıl yapılacağını belirler.
ReadOnly	Haritayı salt okunur yapar; kullanıcı konum seçemez.
Required	Konum seçimini zorunlu yapar; boşsa form kaydedilmez.
TabIndex	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ığı.
Title	Nesnenin başlığı (çok dilli olabilir).
Placeholder	Değer boşken görünen ipucu yazısı.
Text	Nesnenin metin değeri.
Text Align	Yazının yatay hizası.

Olaylar

Bir nesne açılırken olaylar belirli bir sırayla tetiklenir; kullanıcı konum seçtiğinde de ayrı olaylar çalışır. Doğru kodu doğru olaya yazmak işinizi kolaylaştırır.

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

Kullanıcı seçim yaparken: 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	Metin değişmeden hemen önce.
OnTextChanged	Metin değiştikten hemen sonra.
OnValueChanging	Seçilen konum değişmeden hemen önce (iptal edilebilir).
OnValueChanged	Kullanıcı konumu kesinleştirdiğinde. En sık kullanılan olaydır.
OnValidating	Form doğrulanırken nesne değeri 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 / OnTextChanging olaylarının parametresi (args TS, e C#) şunları taşır:

• newValue / NewValue — girilmek 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 Map nesnesine üç 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. Seçili konum Value içinde metin olarak tutulur:

// Oku
string konum = Map1.Value.ToString();

// Yaz (koordinatı metin olarak set edin)
Map1.Value = "39.925533,32.866287";

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

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

// Oku
string konum = Document1.Controls["Map1"].Value.ToString();

// Yaz
Document1.Controls["Map1"].Value = "39.925533,32.866287";

İ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.Map1.value = "39.925533,32.866287";
this.Map1.text  = "Ankara";

Konum nasıl saklanır?

Map nesnesinin değeri bir string'tir; genellikle "enlem,boylam" biçiminde koordinat tutar. Bu değeri başka bir alana yazarak adres çözümlemesinde veya raporda kullanabilirsiniz.

Örnek: konum seçimini doğrulama (OnValueChanging)

OnValueChanging seçilen konum kesinleşmeden hemen önce çalışır; istemediğiniz bir değeri burada iptal edebilirsiniz. Aşağıdaki örnekte boş konum seçimi engellenir.

İstemci (TypeScript):

async Map1_OnValueChanging(args: Controls.EventArgs.IPropertyChangingEventArgs<string>) {
    if (args.newValue == "") {
        args.cancel = true;                              // Boş konumu iptal eder
        this.showMessage("Uyarı", "Lütfen harita üzerinden bir konum seçin.", "Validation");
    }
}

Sunucu (C#):

void Map1_OnValueChanging(object sender, PropertyChangingEventArgs<string> e)
{
    if (string.IsNullOrEmpty(e.NewValue))
    {
        e.Cancel = true;
        ShowMessage("Uyarı", "Lütfen harita üzerinden bir konum seçin.",
            Bimser.CSP.FormControls.RuleManager.AlertType.Validation);
    }
}

İpuçları

• Haritanın yüklenebilmesi için Provider ve geçerli bir ApiKey ayarlanmış olmalıdır; anahtar yoksa harita boş görünür.
• Birden çok işaretçi gösterdiğinizde AutoAdjust özelliğini açın; harita hepsini kapsayacak şekilde otomatik ölçeklenir.
• Sadece konumu göstermek, kullanıcının değiştirmesini istemiyorsanız ReadOnly özelliğini açın.

Tüm tasarımcı özellikleri (tam liste)

General: Name, Field Name

Behavior: Provider, ApiKey, Type, Center, Zoom, AutoAdjust, Controls, Markers, MarkerIconSrc, Routes, RouteMode, ReadOnly, Required, TabIndex

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

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

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