Flutter & Mobil İle İleri Düzey İpucu Gösterge Paneli Nasıl Yapılır?

Gereksinimler ve Ön Hazırlık

Projeye başlamadan önce geliştirme ortamınızın 2026 yılı güncel Flutter sürümüyle uyumlu olduğundan emin olmalısınız. İpucu paneli mimarisi için flutter_riverpod veya bloc gibi güçlü bir state yönetim kütüphanesi kullanmanızı öneririz. Bu rehberde kod örnekleri, temiz mimari (clean architecture) prensiplerine uygun olarak tasarlanmıştır.

• Flutter SDK 3.24 veya üzeri.
• Dart 3.5 veya üzeri.
• Proje bağımlılıkları: tutorial_coach_mark (gelişmiş ipucu yönetimi için) veya özel OverlayEntry implementasyonu.

Adım 1: İpucu Veri Modelini Oluşturma

İpucu gösterge panelinizin yönetilebilir olması için verileri merkezi bir modelde tutmalısınız. Bu, uygulamanın farklı ekranlarında aynı mantığı kullanmanıza olanak tanır. Aşağıdaki kod bloğu, bir ipucu nesnesinin temel yapısını temsil eder.

class TooltipData {
  final String id;
  final String title;
  final String description;
  final GlobalKey targetKey;
  final AlignmentGeometry alignment;

  TooltipData({
    required this.id,
    required this.title,
    required this.description,
    required this.targetKey,
    this.alignment = Alignment.bottomCenter,
  });
}

Bu model, ipucunun hangi widget üzerine odaklanacağını (targetKey) ve hangi metinleri göstereceğini tanımlar. GlobalKey kullanımı, ipucunun ekran üzerindeki koordinatlarını doğru hesaplamamız için kritiktir.

Adım 2: OverlayEntry ile Dinamik İpucu Katmanı

Flutter'da ipuçlarını ekranın en üst katmanında göstermek için Overlay yapısını kullanırız. Bu yöntem, mevcut widget ağacını bozmadan kullanıcıya rehberlik etmenizi sağlar. Aşağıdaki örnek, bir widget'ın konumunu alarak üzerine bir ipucu baloncuğu yerleştirir.

void showCustomTooltip(BuildContext context, TooltipData data) {
  final renderBox = data.targetKey.currentContext!.findRenderObject() as RenderBox;
  final position = renderBox.localToGlobal(Offset.zero);

  OverlayEntry overlayEntry = OverlayEntry(
    builder: (context) => Positioned(
      top: position.dy + renderBox.size.height + 10,
      left: position.dx,
      child: Material(
        color: Colors.transparent,
        child: Container(
          padding: const EdgeInsets.all(12),
          decoration: BoxDecoration(color: Colors.black87, borderRadius: BorderRadius.circular(8)),
          child: Text(data.description, style: const TextStyle(color: Colors.white)),
        ),
      ),
    ),
  );
  Overlay.of(context).insert(overlayEntry);
}

Bu kod bloğu, hedef widget'ın global koordinatlarını hesaplar ve OverlayEntry aracılığıyla ekranın en üstüne bir Material bileşeni ekler. Material kullanımı, metinlerin ve kutuların doğru şekilde render edilmesi için zorunludur.

Adım 3: İpucu Gösterge Paneli Mimarisi

İleri düzey bir sistemde, ipuçlarını tek tek değil, bir liste halinde yönetmelisiniz. Bir TooltipController sınıfı oluşturarak, kullanıcının hangi ipucunu gördüğünü takip edebilir ve "bir daha gösterme" gibi mantıkları kolayca işleyebilirsiniz.

Adım 4: Kullanıcı Deneyimi ve Animasyonlar

İpuçlarının aniden belirmesi kullanıcıyı rahatsız edebilir. AnimatedOpacity veya FadeTransition kullanarak ipuçlarına yumuşak geçişler eklemelisiniz. Aşağıdaki örnek, ipucunun 300 milisaniyede belirmesini sağlar.

AnimatedOpacity(
  opacity: isVisible ? 1.0 : 0.0,
  duration: const Duration(milliseconds: 300),
  child: TooltipWidget(data: data),
)

Bu animasyon, arayüzün daha profesyonel ve akıcı görünmesini sağlar. isVisible değişkeni, state yönetimi ile tetiklenmelidir.

Adım 5: Güvenlik ve Performans Uyarıları

Kritik Uyarı: İpucu verilerini yerel depolamada (SharedPreferences) tutarken hassas kullanıcı verilerini saklamayın. Ayrıca, OverlayEntry nesnelerini işiniz bittiğinde mutlaka remove() metodu ile bellekten temizleyin; aksi takdirde "memory leak" (bellek sızıntısı) oluşabilir.

Performans için, ipucu hesaplamalarını build metodu içinde değil, addPostFrameCallback içerisinde yapmanız önerilir. Bu, render işleminin tamamlanmasını bekleyerek koordinat hatalarının önüne geçer.

WidgetsBinding.instance.addPostFrameCallback((_) {
  showCustomTooltip(context, myTooltipData);
});

Bu yöntem, widget'lar ekrana çizildikten sonra ipucunun doğru konumda görünmesini garanti eder.

Sıkça Sorulan Sorular

İpucu paneli tüm ekranlarda aynı anda görünebilir mi?

Evet, ancak kullanıcı deneyimi açısından bir seferde tek bir ipucu göstermek (adım adım rehber) en iyi pratiktir.

İpucu tıklandığında ne yapmalıyım?

İpucu widget'ına bir GestureDetector ekleyerek, tıklandığında bir sonraki ipucuna geçişi tetikleyen bir fonksiyon çağırabilirsiniz.

Karanlık mod desteği nasıl eklenir?

Theme.of(context).brightness kontrolü yaparak, ipucu kutusunun arka plan rengini dinamik olarak değiştirebilirsiniz.

İpucu paneli mobil cihazlarda ekran dışına taşarsa ne olur?

Koordinat hesaplamalarında MediaQuery kullanarak ekran genişliğini kontrol etmeli ve ipucunu ekran sınırları içerisinde kalacak şekilde hizalamalısınız.

Performansı düşürür mü?

Doğru yönetilen OverlayEntry kullanımı, render ağacını etkilemediği için performans kaybına yol açmaz.

İleri Düzey İpucu Yönetimi: Etkileşimli Senaryo Tasarımı

İpucu gösterge panelinizi daha işlevsel hale getirmek için, statik metinler yerine kullanıcı davranışına duyarlı bir "İpucu Senaryosu" (Onboarding Flow) oluşturmanız gerekir. Bu sistem, kullanıcının bir butona tıklamasıyla bir sonraki ipucuna geçmesini sağlayan bir StreamController veya ChangeNotifier yapısı ile yönetilmelidir.

Aşağıdaki örnek, bir ipucu dizisinin adım adım nasıl yönetileceğini ve bir sonraki adıma nasıl geçileceğini göstermektedir:

class HintController extends ChangeNotifier {
  int _currentIndex = 0;
  final List _hints = ["Ayarlar menüsü", "Profil düzenleme", "Bildirimler"];

  int get currentIndex => _currentIndex;
  String get currentHint => _hints[_currentIndex];

  void nextHint() {
    if (_currentIndex < _hints.length - 1) {
      _currentIndex++;
      notifyListeners();
    }
  }
}

Hata Ayıklama ve Test Stratejileri

Overlay tabanlı yapılar, widget ağacının dışında çalıştıkları için standart Navigator veya BuildContext yöntemleriyle hata ayıklamak bazen zor olabilir. İpucu panelinizin doğru koordinatlarda konumlandığından emin olmak için RenderBox nesnelerini görselleştirmeniz gerekebilir.

Görsel Hata Ayıklama İpuçları

• Boundary Check: İpucunun ekran sınırlarını aşıp aşmadığını kontrol etmek için MediaQuery.of(context).size değerlerini her tetikleyicide yeniden hesaplayın.
• Z-Index Çakışmaları: Eğer ipucunuz diğer elementlerin altında kalıyorsa, OverlayEntry'nin OverlayState içindeki sırasını kontrol edin.
• Widget Testleri: tester.pumpWidget kullanarak ipucunun varlığını ve koordinatlarını doğrulamak için find.byType(OverlayEntry) yerine, ipucu içeriğindeki spesifik bir Key değerini kullanın.

// İpucu konumunu debug etmek için basit bir kontrol
void debugHintPosition(GlobalKey key) {
  final RenderBox? box = key.currentContext?.findRenderObject() as RenderBox?;
  if (box != null) {
    final position = box.localToGlobal(Offset.zero);
    debugPrint("İpucu Koordinatı: ${position.dx}, ${position.dy}");
  }
}

Not: İpucu panellerini test ederken, cihazın yönelim (landscape/portrait) değişikliklerini simüle etmeyi unutmayın. OrientationBuilder kullanımı, ekran döndüğünde ipucunun kaymasını engellemek için kritik öneme sahiptir.

Performans Optimizasyonu ve Bellek Yönetimi

İpucu panellerinde en sık yapılan hata, OverlayEntry nesnelerinin remove() edilmeden hafızada tutulmasıdır. Bu durum, özellikle karmaşık animasyonlar içeren panellerde bellek sızıntısına (memory leak) neden olur. Her zaman dispose metodunda girişleri temizlediğinizden emin olun.

Sonuç

Flutter & mobil ile ileri düzey bir ipucu gösterge paneli oluşturmak, uygulamanızın profesyonellik seviyesini doğrudan etkiler. Bu rehberde öğrendiğiniz OverlayEntry yönetimi, koordinat hesaplama ve state entegrasyonu sayesinde, kullanıcılarınıza rehberlik eden sürdürülebilir bir sistem kurabilirsiniz. Bir sonraki adım olarak, bu yapıya "kullanıcı etkileşim geçmişi" ekleyerek, ipuçlarının sadece ilk kez uygulamayı açan kullanıcılara gösterilmesini sağlayabilirsiniz.

Kod güvenliği notu: Uygulamanızda kullandığınız tüm harici kütüphanelerin güncel olduğundan ve güvenlik açıklarına karşı düzenli tarandığından emin olun.