Grandma3 Plugin 15 Apr 2026 0 okunma

GrandMA3 Plugin ile UI Widget Kullanımı

GrandMA3 plugin geliştirmede UI widget'larını Lua ile nasıl oluşturacağınızı ve yöneteceğinizi öğrenin.

GrandMA3 Plugin Geliştirmede UI Widget Nedir?

GrandMA3, plugin geliştiricilerine kendi arayüz bileşenlerini oluşturma imkânı tanır. UI widget'lar; düğmeler, metin kutuları, kaydırıcılar ve listeler gibi ekrana yerleştirilen etkileşimli öğelerdir. Lua tabanlı plugin sistemi sayesinde bu bileşenleri programatik olarak oluşturabilir, özelleştirebilir ve kullanıcı etkileşimlerine yanıt verecek şekilde programlayabilirsiniz.

Plugin İçin Temel Yapı

Bir UI widget plugin'i yazmadan önce doğru dosya yapısını ve giriş noktasını tanımlamanız gerekir. GrandMA3, plugin dosyalarını .xml manifest ve .lua betik çifti olarak okur.

Bir plugin betiğinin temel iskeleti şu şekildedir:

local function Init(display_handle) -- widget'lar burada oluşturulur end local function CleanUp() -- kaynaklar serbest bırakılır end return Init, CleanUp
Önemli Not: Her plugin mutlaka bir CleanUp fonksiyonu döndürmelidir. Aksi takdirde plugin kapatıldığında bellek sızıntısı yaşanabilir.

Widget Oluşturma Adımları

  1. Display handle almak: Plugin başlatılırken sistem size bir display_handle iletir; tüm widget'lar bu handle üzerine inşa edilir.
  2. Widget tipini seçmek: GrandMA3 API'si farklı widget türleri sunar. En yaygın kullanılanlar şunlardır:
    • StaticText — salt okunur metin gösterimi
    • PushButton — tıklanabilir düğme
    • TextEdit — kullanıcı girişi için metin alanı
    • Slider — sayısal değer seçimi için kaydırıcı
  3. Widget'ı konumlandırmak: Her widget için konum ve boyut parametreleri piksel cinsinden belirtilir.
  4. Callback bağlamak: Kullanıcı etkileşimleri için olay dinleyicisi tanımlanır.

Düğme Widget'ı Örneği

Aşağıdaki örnek, ekrana bir PushButton ekler ve tıklandığında konsola mesaj yazar:

local button = display_handle:CreateWidget("PushButton", {x=10, y=10, width=120, height=40}) button:SetLabel("Sahneyi Başlat") button:SetPressedFunction(function() Printf("Buton tıklandı!") end)

Burada SetPressedFunction, düğmeye bir callback bağlar. Bu callback içinde fixture kontrolü, cue tetiklemesi veya harici API çağrısı gibi her türlü Lua kodu çalıştırılabilir.

Slider ile Değer Okuma

Bir sahne elemanının yoğunluğunu dinamik olarak kontrol etmek için kaydırıcı kullanabilirsiniz:

local slider = display_handle:CreateWidget("Slider", {x=10, y=70, width=200, height=30}) slider:SetMinMax(0, 100) slider:SetValue(50) slider:SetChangedFunction(function(val) Printf("Yeni değer: " .. tostring(val)) end)
İpucu: SetChangedFunction her değer değişiminde tetiklenir. Performans açısından bu callback içinde ağır işlemler yapmaktan kaçının; mümkünse değeri bir değişkende saklayıp ayrı bir döngüde işleyin.

Widget Stilini Özelleştirme

GrandMA3 widget'ları temel stil seçenekleri sunar. Renk, font boyutu ve görünürlük gibi özellikler aşağıdaki metodlarla ayarlanır:

  • SetBackColor(r, g, b) — arka plan rengini ayarlar
  • SetTextColor(r, g, b) — metin rengini ayarlar
  • SetVisible(true/false) — widget'ı gösterir veya gizler
  • SetEnable(true/false) — widget'ı etkin veya pasif yapar

Bu yöntemlerle kullanıcı arayüzünüzü konsolun genel tasarım diline uygun hale getirebilir, farklı durumlara göre (örneğin bağlantı kesildiğinde) widget'ları dinamik olarak devre dışı bırakabilirsiniz.

Yaygın Hatalar ve Çözümleri

  • Widget görünmüyor: display_handle'ın geçerli bir referans olduğundan emin olun; nil kontrolü yapın.
  • Callback çalışmıyor: Fonksiyonu atadıktan sonra widget'ın hâlâ var olduğunu doğrulayın; erken temizleme sık karşılaşılan bir sorundur.
  • Konum kayması: Farklı ekran çözünürlüklerinde görünüm bozulabilir; koordinatları sabit kodlamak yerine ekran boyutunu sorgulayarak hesaplayın.