KuvixOS SDK Docs

KuvixOS SDK v0.1 Taslak

JSON tabanlı arayüz, C tabanlı uygulama geliştirme

KuvixOS SDK, uygulama mantığını C ile yazarken arayüzü ayrı bir JSON dosyasında tanımlamanı sağlar. Bu yaklaşım; daha temiz kod, daha kolay tema desteği, daha hızlı UI düzenleme ve ileride sürükle-bırak editör geliştirme için güçlü bir temel sunar.

Hızlı Başlangıç UI JSON Şeması

Declarative UI

Arayüz bileşenlerini JSON ile tanımla, yükle, oluştur ve gerektiğinde editör ile üret.

Native C Logic

Event callback, dosya sistemi, pencere yönetimi ve uygulama mantığı doğrudan C tarafında çalışır.

Genişletilebilir Yapı

İleride tema sistemi, kapsayıcı widget'lar, plugin desteği ve UI designer eklemek için hazır temel.

Hızlı Başlangıç

İlk uygulama için iki temel dosya yeterlidir: bir layout JSON dosyası ve bir C giriş dosyası.

hello.json

{
  "window": {
    "title": "Hello App",
    "width": 420,
    "height": 240,
    "backgroundColor": "#121212"
  },
  "widgets": [
    {
      "id": "titleLabel",
      "type": "label",
      "text": "Merhaba KuvixOS",
      "x": 12,
      "y": 12,
      "color": "#ffffff"
    },
    {
      "id": "okButton",
      "type": "button",
      "text": "Tikla",
      "x": 12,
      "y": 40,
      "w": 96,
      "h": 28,
      "color": "#000000",
      "backgroundColor": "#d6d6d6"
    }
  ]
}

main.c

#include <kuvix/ui.h>

static void on_ok_click(ui_widget_t* widget, void* user)
{
    ui_set_text_by_id("titleLabel", "Butona tiklandi");
}

int app_main(void)
{
    ui_window_t* win = ui_load_layout("/apps/hello.json");
    if (!win) return -1;

    ui_widget_t* ok = ui_find(win, "okButton");
    ui_set_on_click(ok, on_ok_click, 0);

    ui_show_window(win);
    return 0;
}

İlk sürüm için hedef basit olmalı: JSON yükle → widget oluştur → event bağla → pencere göster.

Önerilen Proje Yapısı

Her uygulama tek klasörde tutulabilir. Giriş dosyası, manifest, layout ve asset'ler ayrı tutulursa proje daha düzenli büyür.

MyApp/
├── manifest.json
├── main.c
├── ui/
│   └── hello.json
├── assets/
│   └── icon.kbi
└── README.md

Dosya	Açıklama
`manifest.json`	Uygulama adı, sürüm, giriş dosyası, ikon ve layout referansları.
`main.c`	Uygulama mantığı, callback'ler ve sistem API çağrıları.
`ui/*.json`	Pencere ve widget tanımları.
`assets/`	İkon, görsel, font ve diğer kaynak dosyalar.

UI JSON Yapısı

KuvixOS UI JSON dosyası iki ana bölümden oluşur: window ve widgets.

{
  "window": {
    "title": "Hello App",
    "width": 420,
    "height": 240,
    "backgroundColor": "#121212"
  },
  "widgets": [
    {
      "id": "titleLabel",
      "type": "label",
      "text": "Merhaba KuvixOS",
      "x": 12,
      "y": 12,
      "color": "#ffffff"
    }
  ]
}

Alan	Tür	Açıklama
`window.title`	string	Pencere başlığı.
`window.width`	number	Pencere genişliği.
`window.height`	number	Pencere yüksekliği.
`window.backgroundColor`	string	Pencere arka plan rengi. Örnek: `#121212`
`widgets`	array	Widget listesi.

Widget'lar

İlk sürümde desteklenmesi önerilen temel widget'lar aşağıdaki gibidir.

Tür	Zorunlu Alanlar	Ek Alanlar
`label`	`id`, `type`, `text`, `x`, `y`	`color`
`button`	`id`, `type`, `text`, `x`, `y`, `w`, `h`	`color`, `backgroundColor`
`input`	`id`, `type`, `x`, `y`, `w`, `h`	`placeholder`, `color`, `backgroundColor`
`panel`	`id`, `type`, `x`, `y`, `w`, `h`	`backgroundColor`, ileride `children`

Stil Sistemi

CSS mantığına yakın kalmak için önerilen yaklaşım şudur: color her zaman yazı rengini, backgroundColor her zaman arka plan rengini ifade etmelidir.

{
  "id": "okButton",
  "type": "button",
  "text": "Tikla",
  "x": 12,
  "y": 40,
  "w": 96,
  "h": 28,
  "color": "#000000",
  "backgroundColor": "#d6d6d6"
}

Aynı isim aynı anlamı taşımalı. color bazen text, bazen background olmamalı.

C API

İlk sürüm için önerilen temel API fonksiyonları aşağıdaki gibi olabilir.

ui_window_t* ui_load_layout(const char* path);
ui_widget_t* ui_find(ui_window_t* win, const char* id);
void ui_set_on_click(ui_widget_t* widget,
                     void (*callback)(ui_widget_t*, void*),
                     void* user);
void ui_show_window(ui_window_t* win);
void ui_set_text_by_id(const char* id, const char* text);

Event Sistemi

İlk sürümde event bağlama işlemini JSON yerine C kodundan yapmak daha güvenli ve daha basittir.

static void on_ok_click(ui_widget_t* widget, void* user)
{
    ui_set_text_by_id("titleLabel", "Butona tiklandi");
}

ui_widget_t* ok = ui_find(win, "okButton");
ui_set_on_click(ok, on_ok_click, 0);

İleride istenirse JSON içinde onClick gibi alanlar da desteklenebilir.

Örnek Uygulama Akışı

hello.json dosyası yüklenir.
window bilgisine göre pencere oluşturulur.
widgets dizisi dolaşılır.
Her widget için type alanına göre gerçek UI nesnesi üretilir.
id alanlarıyla widget erişimi sağlanır.
C tarafında event callback bağlanır.
Pencere ekranda gösterilir.

Bu yaklaşım, ileride bir UI editor geliştirildiğinde aynı JSON dosyalarını otomatik üretmeyi mümkün kılar.