FmgLib.MauiMarkup Dokümantasyonu

FmgLib.MauiMarkup, .NET MAUI için akıcı (fluent) bir C# markup kütüphanesidir. Tüm kullanıcı arayüzünüzü — XAML'e hiç ihtiyaç duymadan — saf C# ile geliştirmenizi sağlar. Her MAUI kontrolünün her bindable özelliği ve olayı (event) için otomatik üretilmiş, okunabilir ve zincirlenebilir genişletme metotları sunar.

new Label()
    .Text("Merhaba, FmgLib!")
    .FontSize(30)
    .TextColor(Colors.Green)
    .Center()

Bu dokümantasyon, kütüphane için eksiksiz ve kendi kendine yeten bir rehberdir. Proje README'sindeki her başlık burada çok daha derinlemesine ele alınmış; ayrıca kütüphanenin kaynak kodundan çıkarılan, README'de yer almayan kullanım kalıpları da eklenmiştir.

🇬🇧 English version of this documentation lives in the parent docs/ folder.

İçindekiler#

1. Temeller#

Doküman	Öğrenecekleriniz
Başlarken	Kurulum, proje şablonları, ilk uygulama, proje yapısı
XAML'den C#'a	XAML kavramlarının FmgLib.MauiMarkup karşılıkları, yan yana dönüşümler
Fluent Özellikler	Dört overload kalıbı; tema/platform/idiom bazlı değerler, dinamik kaynaklar
Nesne Referansları (Assign)	`Assign`, `InvokeOnElement`, `RegisterName`; alan tanımlamadan kontrole erişim

2. Veri Bağlama (Data Binding)#

Doküman	Öğrenecekleriniz
Özellik Bağlama	`Path`, `Source`, `BindingMode`, `StringFormat`, fallback değerleri, düşük seviye `Bind()` API'si
Binding Converter'ları	Satır içi `Convert`/`ConvertBack`, `IValueConverter`, func tabanlı converter'lar
MultiBinding	Birden çok binding'i tek özellikte birleştirme, `IMultiValueConverter`
Derlenmiş Binding'ler	`Getter`/`Setter` expression binding'leri, `Binding.Create`, performans

3. Yerleşim (Layout)#

Doküman	Öğrenecekleriniz
Yerleşim Seçenekleri	Hizalama ve doldurma yardımcıları (`Center`, `AlignTopLeft`, `FillHorizontal`, …)
Grid	Satır/sütun tanım builder'ları (`Star`, `Auto`, `Absolute`), çocukları konumlandırma
Metin Hizalama	`ITextAlignment` yardımcıları (`TextCenter`, `TextTopLeft`, …)
Attached Property'ler	Grid, Shell, Semantic, Automation… için tam eşleme tablosu ve örnekler

4. Etkileşim#

Doküman	Öğrenecekleriniz
Olay İşleyiciler	`On<EventName>` metotları, method group ve satır içi lambda kullanımı
Jest Tanıyıcılar	Tap, pan, pointer, swipe, pinch, sürükle & bırak
Behavior'lar	Yeniden kullanılabilir behavior ekleme, özel behavior yazma
Trigger'lar	Property, data, event, multi ve state trigger'ları
Menüler	Bağlam menüleri (`MenuFlyout`), menü çubukları, klavye kısayolları
SwipeView	Kaydırmalı aksiyon satırları, `SwipeItem`, özel swipe içerikleri

5. Görünüm#

Doküman	Öğrenecekleriniz
Stiller	`Style<T>`, resource dictionary'ler, `BasedOn`, türetilmiş tipler, uygulama geneli temalar
Visual State'ler	`VisualState<T>`, yerleşik state adları, state'e bağlı animasyonlar
Gradyanlar ve Fırçalar	Doğrusal/dairesel gradyanlar, düz fırçalar, gölgeler
Şekiller ve Geometriler	Çizgiler, dikdörtgenler, elipsler, poligonlar, `Path` geometrileri, kırpma
Biçimli Metin	`FormattedString`/`Span`, karışık stiller, tıklanabilir satır içi bağlantılar
Animasyonlar	Üretilen `Animate…To` yardımcıları, MAUI animasyonlarıyla birlikte kullanım

6. Uygulama Mimarisi#

Doküman	Öğrenecekleriniz
Shell Uygulamaları	C# ile Shell kurma; flyout, sekmeler, şablonlar, navigasyon
Application ve Pencereler	`Application` kurulumu, pencere yaşam döngüsü, `TitleBar`, NavigationPage/TabbedPage/FlyoutPage
Hot Reload	`IFmgLibHotReload`, `FmgLibContentPage`, MVVM sayfa taban sınıfları, IDE destek matrisi
Koleksiyonlar ve Şablonlar	`CollectionView`, `ItemTemplate` overload'ları, `BindableLayout`, `EmptyView`
Yerelleştirme (JSON)	JSON dosyası tabanlı yerelleştirme, çalışma zamanında dil değiştirme
Yerelleştirme (RESX)	`TranslatorResx` ile RESX tabanlı yerelleştirme

7. Genişletme ve Referans#

Doküman	Öğrenecekleriniz
Üçüncü Parti Kontroller	`[MauiMarkup]`, `[MauiMarkupAttachedProp]`, otomatik generator modu
Özel Genişletme Metotları	Her bağlamda çalışan kendi fluent metotlarınızı yazma
Yardımcı Metotlar	`ToColor`, koleksiyon yardımcıları, `AddRangeMarkup`, stil interop
Tam Örnekler	Eksiksiz sayfalar: giriş ekranı, ürün listesi, ayarlar sayfası, MVVM kalıpları
İpuçları ve Sorun Giderme	Sık yapılan hatalar, adlandırma kuralları, SSS

Önerilen Öğrenme Yolu#

Kütüphaneye yeni misiniz? Önce Başlarken, ardından XAML'den C#'a ve Fluent Özellikler. Bu üç doküman günlük kullanımın %80'ini kapsar.
Gerçek sayfalar mı geliştiriyorsunuz? Yerleşim Seçenekleri, Grid, Özellik Bağlama ve Hot Reload ile devam edin.
Uygulamayı cilalıyor musunuz? Stiller, Visual State'ler, Trigger'lar ve Animasyonlar.
Birden çok pazara mı çıkıyorsunuz? Yerelleştirme (JSON) veya Yerelleştirme (RESX).
SkiaSharp, ZXing, UraniumUI, InputKit… mi kullanıyorsunuz? Üçüncü Parti Kontroller.

Paketler#

Paket	Amaç
`FmgLib.MauiMarkup`	Markup kütüphanesinin kendisi + Roslyn source generator
`FmgLib.MauiMarkup.Template`	`dotnet new` proje şablonu (`fmglib-mauimarkup-app`)

30 Saniyede Temel Fikir#

Her MAUI kontrolünün her bindable özelliği, özellikle aynı adı taşıyan bir fluent genişletme metodu alır. Her olay bir On<EventName> metodu alır. Tüm metotlar kontrolün kendisini döndürür; böylece çağrılar doğal biçimde zincirlenir ve C# kodunuzun girintisi görsel ağacı birebir yansıtır — tıpkı XAML gibi, ama tam IntelliSense, yeniden adlandırma desteği, derleme zamanı güvenliği ile ve iki dil arasında gidip gelmeden.

public partial class MainPage : ContentPage, IFmgLibHotReload
{
    int count = 0;

    public MainPage() => this.InitializeHotReload();

    public void Build() =>
        this.Content(
            new VerticalStackLayout()
            .Spacing(25)
            .Padding(30)
            .Center()
            .Children(
                new Image()
                    .Source("dotnet_bot.png")
                    .HeightRequest(200)
                    .CenterHorizontal(),

                new Label()
                    .Text("Merhaba, Dünya!")
                    .FontSize(32)
                    .CenterHorizontal(),

                new Button()
                    .Text("Bana tıkla")
                    .OnClicked(b => b.Text = $"{++count} kez tıklandı")
                    .CenterHorizontal()
            )
        );
}