PieChart

Verileri daire şeklinde dilimlere bölerek gösteren grafik nesnesidir. Her dilim bir kategoriyi, dilimin büyüklüğü o kategorinin toplam içindeki payını temsil eder. Chart nesnesinden türer ve seri tipini PieSeries olarak ön ayarlar; kendine ait ek bir özellik getirmez, tüm yüzeyini Chart tabanından alır.

Değer tipi: Bu nesnenin tek bir skaler değeri yoktur. PieChart görsel bir nesnedir; grafiği Data (bağlanan satırlar) ve Charts (seri tanımları) özelliklerinden çizer. Veriyi koddan değiştirdikten sonra ekrana yansıması için Reload() çağrılmalıdır.

Ne zaman kullanılır?

Bir bütünün parçalara nasıl dağıldığını göstermek istediğinizde idealdir: departmanlara göre bütçe dağılımı, durumlara göre talep sayısı, bölgelere göre satış oranı. Az sayıda kategori (genelde 2 ile 6 arası) olduğunda en okunaklı sonucu verir. Zaman içindeki değişimi ya da çok sayıda kategoriyi karşılaştıracaksanız çubuk grafik daha uygundur.

Tasarımcı özellikleri

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

General

Özellik	Açıklama
Name	Nesnenin koddaki adı (ör. PieChart1). Koddan bu adla erişirsiniz.

Data Source

PieChart'ın çizdiği veriyi bu bölümden bağlarsınız.

Özellik	Açıklama
Data	Grafiğe doğrudan verilen satır kümesidir (tipi Object). Kod ile hazırladığınız listeyi/DataTable'ı buraya atayarak grafiği beslersiniz.
DataSource	Grafiği bir veri kaynağına (datasource) bağlar. Sorgu sonucundaki satırlar dilimlere dönüşür.
Charts	Seri tanımlarının listesidir (List<ChartItem>). Hangi alanın dilim adı (ArgumentField), hangi alanın değer (ValueField) olduğu ve seri tipi (Type) burada belirlenir.

Behavior

Özellik	Tip	Açıklama
Legend	ChartLegend	Grafik açıklamasını (renk-kategori eşleşmesini gösteren kutu) yönetir. Alt özellikleri: Enabled (görünürlük), Position (ChartPosition: Left / Top / Right / Bottom).
Tooltip	ChartTooltip	Bir dilimin üzerine gelindiğinde çıkan bilgi balonu. Enabled ile açılır/kapanır.
Hover	ChartHover	Fare dilim üzerindeyken uygulanan vurgu davranışı. Enabled ile açılır/kapanır.
Selection	ChartSelection	Dilim seçimi davranışı. Enabled ile açılır/kapanır.
Animation	ChartAnimation	Grafik çizilirken oynatılan animasyon. Enabled ile açılır/kapanır.
Rotate	Boolean	Pasta grafiği döndürür (bağımsız bir bayraktır; Legend ile ilgisi yoktur).
ArgumentAxis	ChartArgumentAxis	Argüman (kategori) ekseni. Alt özellikleri: ShowLabels, ShowGrid, ShowLine, ShowTicks, Position, IndentFromAxis, ScaleName.
ValueAxis	ChartValueAxis	Değer ekseni. ArgumentAxis ile aynı alt özelliklere sahiptir.
Stack	ChartStack	Yığılmış seri davranışı. Series (birlikte yığılan seri adları) listesini taşır. Pasta grafikte nadir kullanılır.
ZoomAndPan	ChartZoomAndPan	Yakınlaştırma ve kaydırma. InteractionWithArguments / InteractionWithValues (None / Pan / Zoom / Both), ZoomRegionKey (Shift / Alt / Ctrl).

Appearance

Özellik	Tip	Açıklama
Title	MultiLanguageText	Grafiğin üstünde görünen başlık. Çok dillidir; düz string değil, kültür-metin sözlüğü tutar.
Caption	ControlCaption	Nesnenin etiket bloğu (metin, font).
Visible / Client Visible	Boolean	Nesnenin görünürlüğü (sunucu / istemci).
Enabled / Client Enabled	Boolean	Nesnenin aktif olup olmadığı (sunucu / istemci).
CustomClassName	String	Nesneye eklenen özel CSS sınıfı.
Style / ContainerStyle	Style	Nesnenin ve kapsayıcısının stil bloğu.

Ayrıca Chart tabanından gelen ve çoğunlukla altyapı tarafından kullanılan üyeler: Loading (Boolean, yükleniyor göstergesi), ContextMenuKey / ContextMenuColumnKey / ContextMenuTarget (sağ tık menüsü bağlama), ControlId, DefaultEnabled / DefaultClientEnabled.

ChartItem (seri tanımı)

Charts listesindeki her eleman bir ChartItem'dır. Pasta grafikte tek seri kullanılır ve Type her zaman PieSeries'tir.

Üye	Tip	Açıklama
Type	ChartType	Seri tipi. Değerler: LineSeries, SplineSeries, BarSeries, ScatterSeries, AreaSeries, PieSeries. Pasta için PieSeries.
ArgumentField	String	Dilim adını (kategoriyi) taşıyan alan adı.
ValueField	String	Dilim büyüklüğünü (değeri) taşıyan alan adı.
Name	String	Serinin adı (açıklamada görünür).
Color	String	Serinin/dilimin rengi (ör. "#3366ff").
BarWidth	Nullable<Int32>	Çubuk genişliği (çubuk grafiklerde kullanılır).
ScaleName	String	İlişkili eksen ölçek adı.

Olaylar

PieChart görsel bir nesnedir; değeri olmadığı için TextBox gibi nesnelerdeki OnValueChanged benzeri değer olayları burada yoktur. OnInit / OnLoad / OnPreRender / OnRender gibi genel yaşam döngüsü kancaları ise her nesnede olduğu gibi burada da bulunur (BaseControl'den miras gelir); bunlar nesnenin kendi tasarımcı olayları değildir. OnDataLoad ise yoktur, çünkü PieChart veriye bağlı (DataBoundControl) bir nesne değildir.

Dökümde doğrulanan tek veri kancası, veri kaynağından satır eklenirken çalışan sunucu metodudur:

Sunucu kancası (Server)

Kanca	İmza	Ne zaman çalışır
OnDataSourceAddItem	void OnDataSourceAddItem(object sender, DataSourceAddItemEventArgs e)	Grafik bir DataSource'a bağlıyken her satır eklenirken çalışır. Satırı dilime dönüştürmeden önce araya girip değer/etiket düzenlemek için kullanılır.

TODO: İstemci tarafı tıklama olayları (OnClick / OnDoubleClick) bu nesne için API dökümünde doğrulanamadı; Studio'da olay listesinde görünüyorsa eklenebilir.

Kod örnekleri

PieChart'ın bir skaler değeri olmadığı için .Value set etmezsiniz; bunun yerine Data ve Charts'ı kurar, Reload() çağırır ve görünürlük gibi özellikleri yönetirsiniz. Sunucu örnekleri turuncu, istemci örnekleri kırmızı çerçevelidir.

Grafiği koddan doldurma (C#, sunucu)

Tipik akış: satırları hazırla, Data'ya ata, Charts'ı bir ChartItem ile tanımla (Type = PieSeries), sonra Reload() çağır. Reload() zorunludur; çağrılmazsa veri atanır ama grafik yenilenmez.

// Satırları hazırla (kategori + değer)
var satirlar = new List<Dictionary<string, object>>
{
    new Dictionary<string, object> { { "Kategori", "Donanım" }, { "Tutar", 45000m } },
    new Dictionary<string, object> { { "Kategori", "Yazılım" }, { "Tutar", 32000m } },
    new Dictionary<string, object> { { "Kategori", "Hizmet" },  { "Tutar", 18000m } },
};

// Seriyi tanımla: pasta serisi, hangi alan dilim adı, hangi alan değer
PieChart1.Charts = new List<ChartItem>
{
    new ChartItem
    {
        Type          = ChartType.PieSeries,
        ArgumentField = "Kategori",   // dilim adı
        ValueField    = "Tutar"       // dilim büyüklüğü
    }
};

// Veriyi bağla ve grafiği yenile
PieChart1.Data = satirlar;
PieChart1.Reload();   // TODO: Data/Charts değişiminden sonra ZORUNLU

Sorgu sonucundan doldurma (C#, sunucu)

Bir DataTable döndüren sorgudan beslemek için satırları doğrudan Data'ya atayabilirsiniz; alan adlarını ArgumentField / ValueField ile eşleştirin.

// dt: "Departman" ve "Butce" kolonları olan bir DataTable
PieChart1.Charts = new List<ChartItem>
{
    new ChartItem
    {
        Type          = ChartType.PieSeries,
        ArgumentField = "Departman",
        ValueField    = "Butce"
    }
};
PieChart1.Data = dt;
PieChart1.Reload();

Başlığı ayarlama (C#, sunucu)

Title düz string değil MultiLanguageText'tir. Kültür-metin sözlüğüyle atayın:

PieChart1.Title = new MultiLanguageText(
    new Dictionary<string, string> { { "tr-TR", "Departman Bütçe Dağılımı" } });

Açıklamayı (Legend) konumlandırma (C#, sunucu)

PieChart1.Legend.Enabled  = true;
PieChart1.Legend.Position = ChartPosition.Right;   // Left / Top / Right / Bottom
PieChart1.Reload();

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

Akış kodunda nesneye Document1.Controls üzerinden erişirsiniz. Generic Controls[...] üzerinden çoğunlukla görünürlük gibi temel özellikleri yönetirsiniz; Title yine MultiLanguageText ister.

// Görünürlük
Document1.Controls["PieChart1"].Visible = true;

// Başlık (MultiLanguageText, düz string değil)
Document1.Controls["PieChart1"].Title = new MultiLanguageText(
    new Dictionary<string, string> { { "tr-TR", "Departman Bütçe Dağılımı" } });

İstemci kodu (TypeScript, tarayıcı)

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

// Görünürlük ve durum
this.PieChart1.visible = true;
this.PieChart1.enabled = true;

Değer yerine veri kaynağı + Reload()

PieChart'ta tek bir .Value yoktur. Grafiği beslemek için ya tasarımcıdan DataSource bağlayın ya da koddan Data'ya satır kümesi atayıp Charts'ı tanımlayın. Hangi alanın dilim adı (ArgumentField), hangisinin değer (ValueField) olacağını ChartItem içinde belirtin ve mutlaka Reload() çağırın, aksi halde değişiklik ekrana yansımaz.

İpuçları

• Çok fazla dilim okunabilirliği bozar. Beşten fazla kategori varsa küçük payları "Diğer" başlığı altında toplamayı düşünün.
• Data veya Charts'ı koddan değiştirdiğinizde Reload() çağırmayı unutmayın; çağrılmazsa grafik eski halini korur.
• ArgumentField ve ValueField adlarını veri kümesindeki gerçek alan adlarıyla birebir eşleştirin; aksi halde grafik boş çizilir.
• Başlığı (Title) MultiLanguageText ile birden çok dilde girerek farklı dillerdeki kullanıcılara uygun metni gösterebilirsiniz.

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

General: Name

Data Source: Data, DataSource, Charts

Behavior: Animation, ArgumentAxis, Hover, Legend, Rotate, Selection, Stack, Tooltip, ValueAxis, ZoomAndPan

Appearance: Title (MultiLanguageText), Caption, Visible, Client Visible, Enabled, Client Enabled, CustomClassName, Style, ContainerStyle

Chart tabanından devralınan diğer üyeler: Loading, ContextMenuKey, ContextMenuColumnKey, ContextMenuTarget, ControlId, DefaultEnabled, DefaultClientEnabled, ClientEvents, ServerEvents, ExecutedServerEvents

Metotlar: Reload(), GetProtectedData(bool), GetDifferences(object), OnDataSourceAddItem(object, DataSourceAddItemEventArgs)

Olaylar: API dökümünde EVENT üyesi yok. Tek doğrulanan veri kancası: OnDataSourceAddItem (sunucu).