عناصر تحكم المستخدم

تأخذ عناصر تحكم المستخدم في الإضافة شكل متغير عام يمكن للمستخدم النهائي تعديله. وتُصدَّر جميعها من الإضافة عبر ControllableParameters() التي تُرجع مصفوفة من كائنات الإعدادات كما هو موضح أدناه.

export function ControllableParameters(){
    return [
        {"property":"LightingMode", "label":"Lighting Mode", "type":"combobox", "values":["Canvas","Forced"], "default":"Canvas"},
        {"property":"forcedColor", "label":"Forced Color","min":"0","max":"360","type":"color","default":"#009bde"},
        {"property":"SettingControl", "label":"Enable Setting Control","type":"boolean","default":"false"},
        {"property":"dpi1", "label":"DPI","step":"50", "type":"number","min":"200", "max":"18000","default":"800"}
    ];
}

تحتوي كائنات الإعدادات هذه دائمًا على بعض المعاملات الأساسية. وهي صالحة لجميع عناصر تحكم المستخدم في الإضافات.

المعامل	القيمة	النوع
property	اسم المتغير الذي ترغب في تعيينه لعنصر التحكم.	String
label	التسمية التي ستُعرض للمستخدم.	String
type	نوع عنصر التحكم. حاليًا، الخيارات التالية صالحة: boolean, number, hue, color, combobox, and textfield	String
default	القيمة الافتراضية لعنصر التحكم.	متغيّر

منزلق الأرقام

يتيح عنصر التحكم number للمستخدم تحديد قيمة رقمية باستخدام منزلق.

{"property":"dpi1", "label":"DPI","step":"50", "type":"number","min":"200", "max":"18000","default":"800"},

يدعم عنصر التحكم هذا السمات التالية:

المعامل	القيمة	النوع
property	اسم المتغير الذي ترغب في تعيينه لعنصر التحكم.	String
label	التسمية التي ستُعرض للمستخدم.	String
type	”number”	String
default	القيمة الافتراضية لعنصر التحكم.	String, Int
min	أدنى قيمة قابلة للتحديد في المنزلق. تدعم هذه السمة القيم السالبة.	String, Int
max	أعلى قيمة قابلة للتحديد في المنزلق.	String, Int
step	قيمة الخطوة التي يزيد بها المنزلق أو ينقص	String, Int

مفتاح التبديل المنطقي

يتيح عنصر التحكم boolean للمستخدم تحديد قيمة متغير منطقي باستخدام مفتاح تبديل.

{"property":"AngleSnap", "label":"Angle Snapping", "type":"boolean", "default":"0"},

يدعم عنصر التحكم هذا السمات التالية:

المعامل	القيمة	النوع
property	اسم المتغير الذي ترغب في تعيينه لعنصر التحكم.	String
label	التسمية التي ستُعرض للمستخدم.	String
type	”boolean”	String
default	القيمة الافتراضية لمفتاح التبديل. اضبطها على 1 لجعل حالة “التشغيل” هي الافتراضية.	String, Int

منزلق درجة اللون

يتيح عنصر التحكم لاختيار درجة اللون للمستخدم تحديد مكوّن درجة اللون (hue) باستخدام منزلق

يدعم عنصر التحكم هذا السمات التالية:

المعامل	القيمة	النوع
property	اسم المتغير الذي ترغب في تعيينه لعنصر التحكم.	String
label	التسمية التي ستُعرض للمستخدم.	String
type	”hue”	String, Int
default	القيمة الافتراضية لمنزلق درجة اللون.	String
min	أدنى قيمة قابلة للتحديد لدرجة اللون. يجب أن تكون هذه القيمة بين 0 و359.	String, Int
max	أعلى قيمة قابلة للتحديد لدرجة اللون. يجب أن تكون هذه القيمة بين 1 و360.	String, Int

منتقي الألوان

يتيح عنصر التحكم color للمستخدم تحديد لون باستخدام عجلة درجات الألوان ومنزلق التشبّع ومنزلق الإضاءة. تفتح أيقونة المفتاح لوحة ألوان أكثر تقدمًا للاختيار.

{"property":"forcedColor", "label":"Forced Color","min":"0","max":"360","type":"color","default":"#009bde"},

يدعم عنصر التحكم هذا السمات التالية:

المعامل	القيمة	النوع
property	اسم المتغير الذي ترغب في تعيينه لعنصر التحكم.	String
label	التسمية التي ستُعرض للمستخدم.	String
type	”color”	String
default	القيمة الافتراضية لمنتقي الألوان. يجب تحديدها كقيمة سداسية عشرية بالصيغة #RRGGBB	String
min	أدنى قيمة قابلة للتحديد لدرجة اللون. يجب أن تكون هذه القيمة بين 0 و359.	Int
max	أعلى قيمة قابلة للتحديد لدرجة اللون. يجب أن تكون هذه القيمة بين 1 و360.	Int

القائمة المنسدلة

يتيح عنصر التحكم combobox للمستخدم الاختيار من قائمة منسدلة من القيم المُعدّة مسبقًا.

{"property":"SleepModeTime", "label":"Sleep After x Minutes", "type":"combobox", "values":[5,10,15,30,60], "default":10},

يدعم عنصر التحكم هذا السمات التالية:

المعامل	القيمة	النوع
property	اسم المتغير الذي ترغب في تعيينه لعنصر التحكم.	String
label	التسمية التي ستُعرض للمستخدم.	String
type	”combobox”	String
default	القيمة الافتراضية للقائمة المنسدلة. يجب أن تكون هذه القيمة ضمن مصفوفة values	String, Int
values	مصفوفة من القيم للقائمة المنسدلة. الأنواع الصالحة هي السلاسل النصية والأعداد الصحيحة.	[String, Int]

حقل النص

يتيح عنصر التحكم textfield للمستخدم إدخال نص بحرية مع عامل تصفية RegEx اختياري.

{"property":"textBox", "label":"Text Field", "type":"textfield", "default":"3"},

يدعم عنصر التحكم هذا السمات التالية:

المعامل	القيمة	النوع
property	اسم المتغير الذي ترغب في تعيينه لعنصر التحكم.	String
label	التسمية التي ستُعرض للمستخدم.	String
type	”textfield”	String
default	القيمة الافتراضية لحقل النص.	String, Int
filter	عامل تصفية RegEx اختياري لتقييد إدخال المستخدم	RegEx String

استدعاءات on*Changed

كلما غيّر المستخدم عنصر تحكم، يستدعي SignalRGB الدالة on[property]Changed() المقابلة قبل استدعاء Render() التالي. يجب أن يتطابق اسم الدالة تمامًا مع اسم الخاصية من ControllableParameters()، مسبوقًا بـ on ومتبوعًا بـ Changed. مع مراعاة حالة الأحرف.

// ControllableParameters entry:
{"property":"dpi1", "label":"DPI", "step":"50", "type":"number", "min":"200", "max":"18000", "default":"800"},

// Corresponding callback:
export function ondpi1Changed() {
    setDpi(dpi1);
}

الاستدعاءات المدمجة

هذه الاستدعاءات متاحة دون الحاجة إلى إدخال مقابل في ControllableParameters:

الدالة	الوصف
onBrightnessChanged()	تُستدعى عندما يحرّك المستخدم منزلق السطوع الرئيسي للجهاز.