VectorMap

Form üzerinde vektörel (SVG tabanlı) bir harita gösteren nesnedir. Ülke, bölge ya da il bazında veri gösterimi, katmanlama, lejant ve harita üzerine işaretleme (annotation) için kullanılır.

Değer tipi: string

Ne zaman kullanılır?

Coğrafi dağılımı görsel olarak göstermek istediğinizde uygundur: bölgelere göre satış, illere göre talep sayısı, seçili bölgenin formda saklanması gibi. Harita üzerinde seçilen bölgenin kodu nesnenin değeri olarak string biçiminde tutulur. Sadece sayısal grafik gerekiyorsa Chart nesneleri, konum işaretlemesi gerekiyorsa Map nesnesi daha uygundur.

Tasarımcı özellikleri

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

General

Özellik	Açıklama
Name	Nesnenin koddaki adı (ör. VectorMap1). Koddan bu adla erişirsiniz.
Field Name	Değerin veritabanında saklandığı alanın adı.

Behavior

Özellik	Açıklama
Layer	Haritanın katmanları. Her katman ayrı bir bölge kümesi veya veri grubu gösterir.
Legend	Harita üzerindeki lejant (açıklama kutusu) tanımları. Renk/değer karşılıklarını gösterir.
Annotations	Harita üzerine eklenen işaretlemeler (etiket, ok, alan vurgusu).
Bounds	Haritanın gösterilecek sınır alanı (görünüm çerçevesi).
ControlBar	Yakınlaştırma/uzaklaştırma gibi harita kontrol çubuğunu gösterir veya gizler.
TitleMap	Harita başlığı ayarları.
ExportMap	Haritanın dışa aktarım (resim olarak indirme) ayarları.
ReadOnly	Haritayı salt okunur yapar; kullanıcı seçim yapamaz.
Required	Bir bölge 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üğü (sunucu / istemci tarafında).
Enabled / Client Enabled	Nesnenin aktif olup olmadığı.
Title	Nesnenin üstünde görünen başlık metni (çok dilli olabilir).
Placeholder	Değer boşken görünen ipucu metni (çok dilli olabilir).
Text	Nesnenin metin değeri.
Text Align	Metnin yatay hizası.

Olaylar

Bir nesne açılırken olaylar belirli bir sırayla tetiklenir; kullanıcı harita üzerinde bir bölge seçince ayrı olaylar çalışır. Doğru kodu doğru olaya yazmak işinizi kolaylaştırır.

Açılış sırası: OnInit → OnLoad → OnDataLoad → OnPreRender → 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ğeri değişmeden hemen önce.
OnTextChanged	Metin değeri değiştikten hemen sonra.
OnValueChanging	Seçilen bölge değeri değişmeden hemen önce (iptal edilebilir).
OnValueChanged	Kullanıcı bir bölge seçip değer kesinleştiğinde. En sık kullanılan olaydır.
OnValidating	Form kaydedilirken değer doğrulanırken.

İ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	Haritaya 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 VectorMap'e üç yerden erişebilirsiniz. Değeri seçilen bölgeyi temsil eden bir string'tir. Sunucu örnekleri turuncu, istemci örnekleri kırmızı çerçevelidir.

Form kodu (C#, sunucu)

Form kodunda nesneye doğrudan adıyla erişirsiniz:

// Oku (seçili bölge kodu)
string bolge = VectorMap1.Value.ToString();

// Yaz (haritada bir bölgeyi seçili getir)
VectorMap1.Value = "TR-06";

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

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

// Oku
string bolge = Document1.Controls["VectorMap1"].Value.ToString();

// Yaz
Document1.Controls["VectorMap1"].Value = "TR-06";

İ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 bolge = this.VectorMap1.value;

// Yaz
this.VectorMap1.value = "TR-06";

Değer neyi tutar?

VectorMap'in .Value değeri, kullanıcının seçtiği bölgenin kodunu (string) saklar. Katman ve lejant yapılandırmasını tasarımcıdaki Layer ve Legend özelliklerinden yönetir, kod tarafında ise yalnızca seçili bölgeyi okur/yazarsınız.

Örnek: seçilen bölgeyi doğrulama (OnValueChanging)

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

İstemci (TypeScript):

async VectorMap1_OnValueChanging(args: Controls.EventArgs.IPropertyChangingEventArgs<string>) {
    if (args.newValue == "") {
        args.cancel = true;                                  // Seçimi iptal eder
        this.showMessage("Uyarı", "Lütfen bir bölge seçin.", "Validation");
    }
}

Sunucu (C#):

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

İpuçları

• Bölge seçimini zorunlu kılmak için kodla kontrol yazmak yerine Required özelliğini kullanın.
• Katmanları (Layer) ve lejantı (Legend) tasarımcıdan yapılandırın; bunları kod tarafında değil tasarım tarafında yönetmek daha temiz olur.
• Haritayı sadece görüntüleme amaçlı kullanacaksanız ReadOnly özelliğini açın; böylece kullanıcı yanlışlıkla seçim yapamaz.

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

General: Name, Field Name

Behavior: Annotations, Bounds, ControlBar, ExportMap, Layer, Legend, ReadOnly, Required, TabIndex, TitleMap

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

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

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