Saat Yüzü
RehberiClock Face
Guide

Dosya YapısıFile Structure

Bir saat yüzü, cihazda /clock_faces/<id>/ klasöründe yaşar. Market paketin şu dosyaları içerir: A clock face lives in /clock_faces/<id>/ on the device. A market package contains:

• clockface.json — zorunlu. Yüzün tanımı (arka plan + elementler).required. The face definition (background + elements).
• preview.jpg — 240×240 önizleme. bgImage kullanırsan tam-ekran arka plan olarak da çizilir.240×240 preview. If you use bgImage, it is also drawn as the full-screen background.
• manifest.json — market kataloğu için meta (id, ad, sürüm, min firmware...).catalog metadata for the market (id, name, version, min firmware...).
• settings.json — cihazın ürettiği tema kaplaması (opsiyonel, bkz. Tema).device-generated theme override (optional, see Theme).

Market kataloğu manifest.json örneği:Market catalog manifest.json example:

{
  "id": "arda_neon_orbit",
  "name": "Arda Neon Orbit",
  "author": "Arda",
  "version": "1.0.0",
  "category": "digital",
  "tags": ["digital", "animated", "neon", "weather"],
  "target_resolution": "240x240",
  "preview_image": "preview.png",
  "min_firmware_build": 3379561,
  "requires": { "custom_clock_schema": 2, "supports_weather": true }
}

Kök AlanlarRoot Fields

clockface.json kökünde arka plan ve elements dizisi tanımlanır. Tuval her zaman 240×240, merkez 120,120.The clockface.json root defines the background and an elements array. The canvas is always 240×240, center 120,120.

AlanField	VarsayılanDefault	AçıklamaDescription
bgColor	#000000	Arka plan rengi (hex).Background color (hex).
bgImage	false	true ise aynı klasördeki preview.jpg tam ekran çizilir (gradyan/font içeren zengin yüzler için).If true, the folder's preview.jpg is drawn full-screen (for rich faces with gradients/fonts).
bgPattern	SOLID	SOLID, GRID, DOTS, STRIPES_H, STRIPES_V, DIAGONAL, CHECKERBOARD
bgPatternColor	#333333	Desen çizgi/nokta rengi.Pattern line/dot color.
elements	[ ]	Çizilecek eleman nesneleri dizisi (sırayla, üst üste).Array of element objects (drawn in order, layered).

Ortak Eleman AlanlarıCommon Element Fields

Her eleman bir type ve aşağıdaki ortak alanlardan bazılarını taşır:Every element has a type plus some of these common fields:

AlanField	VarsayılanDefault	AçıklamaDescription
type	—	Eleman tipi (zorunlu).Element type (required).
x, y	120	Konum (px). 0,0 = sol üst.Position (px). 0,0 = top-left.
color	#FFFFFF	Renk; #RRGGBB veya RRGGBB.Color; #RRGGBB or RRGGBB.
size	2	Metin boyut çarpanı (textSize).Text size multiplier (textSize).
font	2	Yerleşik font no: 1,2,4,6,7,8 (7 = 7-segment dijital).Built-in font no: 1,2,4,6,7,8 (7 = 7-segment digital).
align	CENTER	LEFT, CENTER, RIGHT
width, height	50	Şekiller ve ANALOG/ARC için boyut/yarıçap.Size/radius for shapes and ANALOG/ARC.
opacity	100	0–100; arka planla harmanlanır.0–100; alpha-blended with background.
format	—	TIME/DATE/şekil biçimini belirler (aşağıda).Sets TIME/DATE/shape format (below).

TIME & DATE

TIME, format alanına göre saat çizer. Özel anahtarlar: HH:MM, HH:MM:SS, HH, MM, SS ve ANALOG. Bunların dışında herhangi bir strftime deseni de verilebilir.TIME renders the clock per format. Special keys: HH:MM, HH:MM:SS, HH, MM, SS and ANALOG. Any other strftime pattern also works.

{ "type": "TIME", "format": "HH:MM",  "x": 120, "y": 100, "font": 7, "size": 1, "color": "#00FF00" }
{ "type": "TIME", "format": "ANALOG", "x": 120, "y": 120, "width": 180, "color": "#FFFFFF" }

ANALOG modunda yarıçap = width / 2; akrep/yelkovan otomatik, saniye ibresi kırmızı çizilir. DATE ise tam strftime kullanır (varsayılan %d.%m.%Y). Cihaz dili Türkçe ise gün/ay adları otomatik olarak Türkçeye çevrilir.In ANALOG mode radius = width / 2; hour/minute hands are automatic and the second hand is drawn red. DATE uses raw strftime (default %d.%m.%Y). When the device language is Turkish, day/month names are auto-localized.

{ "type": "DATE", "format": "%a %d %b", "x": 120, "y": 160, "font": 2, "color": "#AAAAAA" }

WEATHER_ICON & WEATHER_TEMP

WEATHER_ICON hava ikonu çizer. format: SIMPLE (sembol) veya ANIMATED (animasyonlu güneş/bulut/yağmur/kar). WEATHER_TEMP anlık sıcaklığı derece ile yazar.WEATHER_ICON draws a weather icon. format: SIMPLE (glyph) or ANIMATED (animated sun/cloud/rain/snow). WEATHER_TEMP prints the current temperature with a degree sign.

{ "type": "WEATHER_ICON", "format": "ANIMATED", "x": 180, "y": 60 }
{ "type": "WEATHER_TEMP", "x": 120, "y": 200, "font": 4, "color": "#FFD27F" }

TEXT

Statik metin. İki dilli yüzler için text_tr ve text_en kullan; cihaz diline göre otomatik seçilir. Geriye uyumluluk için tek text de çalışır. (Yerleşik fontlar Türkçe özel karakter içermez → ASCII kullan.)Static text. For bilingual faces use text_tr and text_en; the device picks by its language. A single text also works (backward-compatible). Built-in fonts have no Turkish special glyphs → use ASCII.

{ "type": "TEXT", "text_tr": "GUNAYDIN", "text_en": "GOOD MORNING",
  "x": 120, "y": 40, "font": 2, "size": 1, "color": "#FFFFFF", "align": "CENTER" }

ŞekillerShapes

Tüm şekiller format: "HOLLOW" ile içi boş çizilebilir (varsayılan dolu). Konum x,y şeklin merkezi/çapasıdır.All shapes can be drawn outlined with format: "HOLLOW" (default filled). x,y is the shape's center/anchor.

type	Kullanılan alanlarFields used	NotNote
SHAPE_RECT	x,y,width,height	Dikdörtgen. HOLLOW = çerçeve.Rectangle. HOLLOW = outline.
SHAPE_CIRCLE	x,y,width	width = yarıçap.width = radius.
SHAPE_LINE	x,y,width,height	Çizgi/çubuk. format:"DASHED" kesik. Yön: width>height ise yatay.Line/bar. format:"DASHED" for dashes. Direction: horizontal if width>height.
SHAPE_TRIANGLE	x,y,width,height	Tepe (x, y−height), taban ±width.Apex (x, y−height), base ±width.
SHAPE_STAR	x,y,width	5 köşeli yıldız; width = dış yarıçap.5-point star; width = outer radius.
SHAPE_HEART	x,y,width	Kalp; width = ölçek.Heart; width = scale.
SHAPE_DIAMOND	x,y,width	Eşkenar dörtgen; width = yarı köşegen.Diamond; width = half-diagonal.

{ "type": "SHAPE_CIRCLE", "x": 120, "y": 120, "width": 90, "format": "HOLLOW", "color": "#1E4A7A" }
{ "type": "SHAPE_RECT",   "x": 40, "y": 200, "width": 160, "height": 6, "color": "#E8281E" }

SHAPE_ARC — halka / gösterge— ring / gauge

Yay/halka çizer; gösterge ve ilerleme efektleri için idealdir. 0° tepededir, saat yönünde artar.Draws an arc/ring; ideal for gauges and progress effects. 0° is at the top, increasing clockwise.

AlanField	AçıklamaDescription
width	Dış yarıçap.Outer radius.
height	İç yarıçap (0 = dolu pasta dilimi).Inner radius (0 = filled pie).
start, end	Başlangıç/bitiş açısı (derece).Start/end angle (degrees).
bind	seconds / minutes / hours → bitiş açısı canlı saate göre hareket eder.seconds / minutes / hours → end angle animates with the live clock.

{ "type": "SHAPE_ARC", "x": 120, "y": 120, "width": 110, "height": 100,
  "start": 0, "bind": "seconds", "color": "#E8281E" }

Tema KaplamasıTheme Override

Aynı klasördeki settings.json bir tema taşıyabilir. Varsa bg arka planı, color ise tüm eleman renklerini ezer (uygulamadaki "Hazır Temalar" bunu kullanır). bgImage kullanan yüzlerde tema uygulanmaz.A settings.json in the same folder may carry a theme. If present, bg overrides the background and color overrides every element color (the app's "Preset Themes" use this). Theme is not applied to faces using bgImage.

{ "bg": "#101010", "color": "#00E5FF" }

Tam ÖrnekFull Example

{
  "bgColor": "#000000",
  "bgPattern": "STRIPES_H",
  "bgPatternColor": "#002200",
  "elements": [
    { "type": "TEXT", "text_tr": "SISTEM", "text_en": "SYSTEM",
      "x": 120, "y": 40, "font": 2, "size": 1, "color": "#005500" },
    { "type": "TIME", "format": "%H:%M:%S",
      "x": 120, "y": 100, "font": 7, "size": 1, "color": "#00FF00" },
    { "type": "DATE", "format": "%Y-%m-%d",
      "x": 120, "y": 160, "font": 2, "color": "#00CC00" },
    { "type": "WEATHER_TEMP", "x": 120, "y": 200, "font": 2, "color": "#00FF88" }
  ]
}

Sınırlar & İpuçlarıLimits & Tips

• Schema: 2. Market manifestinde requires.custom_clock_schema: 2 belirt.Schema: 2. Declare requires.custom_clock_schema: 2 in the market manifest.
• Boyut: clockface.json ≈ 64 KB, preview.jpg ≈ 160 KB sınırı.Size: clockface.json ≈ 64 KB, preview.jpg ≈ 160 KB limit.
• Tuval: her zaman 240×240. ~8–12 px güvenli kenar boşluğu bırak, taşma yapma.Canvas: always 240×240. Keep ~8–12 px safe margin; avoid overflow.
• Performans: resim-tabanlı (bgImage) yüzler ~250 ms'de bir yeniden çizilir; animasyon için JSON elementlerini tercih et.Performance: image-based (bgImage) faces redraw ~every 250 ms; prefer JSON elements for animation.
• Renkler RGB565'e dönüştürülür; ince ton farkları kaybolabilir.Colors are converted to RGB565; subtle shades may be lost.