الأدوات المساعدة

أدوات الجهاز المساعدة

device.color()

هذه الدالة هي وسيلتك لجلب بيانات الألوان من اللوحة. تأخذ موضع X,Y نسبيًا إلى مخزن البكسلات المؤقت للجهاز على اللوحة وضمنه، وتُرجع مصفوفة [R,G,B] بلون ذلك البكسل.

المعامل	النوع	الوصف	مثال
X	Int	قيمة عددية صحيحة تمثل الإحداثي X داخل مخزن البكسلات المؤقت للجهاز	5
Y	Int	قيمة عددية صحيحة تمثل الإحداثي Y داخل مخزن البكسلات المؤقت للجهاز	3

• ملاحظة: يجب أن تقع إحداثيات X,Y المرسلة ضمن مخزن البكسلات المؤقت الذي يحدده التصدير Size()

القيمة المُرجعة	النوع	الوصف	مثال
ColorArray	مصفوفة أحادية البعد	مصفوفة بطول 3 تحتوي على قيم [R, G, B] المقابلة، وتتراوح من 0 إلى 255 (HEX 00-FF)	[128,158,255]

فيما يلي مثال مختصر على استخدام الدالة في موقف نموذجي.

for(var iIdx = 0; iIdx < vLedPositions.length; iIdx++) //For each Led on the device
        {
            var iPxX = vLedPositions[iIdx][0]; //Get the X and Y values from the [X,Y] array
            var iPxY = vLedPositions[iIdx][1];
            var col; // create a variable to contain the [R.G.B] array data
            if(shutdown){       // Check for some settings that can override the Device.color() call
                col = hexToRgb(shutdownColor)
            }else if (LightingMode == "Forced") {
                col = hexToRgb(forcedColor)
            }else{
                col = device.color(iPxX, iPxY);  //Calling Device.color with the X and Y values
            }
            //Saving the Color data in order into a larger Array of all the LED's data
            RGBdata[iIdx*3] = col[0]; // Red Channel
            RGBdata[iIdx*3+1] = col[1]; //Green Channel
            RGBdata[iIdx*3+2] = col[2]; //Blue Channel
            TotalLedCount += 1;
        }

device.getBrightness()

تُرجع مستوى السطوع الحالي للجهاز داخل SignalRGB. هذه القيمة مطبّقة بالفعل على أي ألوان تُرجعها device.color() أو ما يشابهها.

القيمة المُرجعة	النوع	الوصف	مثال
Brightness	int	السطوع الحالي في النطاق 0-100	42

device.getMotherboardName()

تُرجع اسم WMI للوحة الأم في النظام الحالي.

القيمة المُرجعة	النوع	الوصف	مثال
MotherboardName	string	اسم اللوحة الأم للنظام	B550 Aorus Elite

device.pause()

تحاول هذه الدالة إيقاف خيط الجهاز مؤقتًا للمدة المحددة. ليس مضمونًا أن تكون فترات الإيقاف هذه دقيقة تمامًا بسبب طريقة تعامل نظام التشغيل مع سكون الخيوط.

المعامل	النوع	الوصف	مثال
Duration	Int	مدة الإيقاف المطلوبة بالمللي ثانية	1

• ملاحظة: يفرض Windows حدًا أدنى لوقت السكون يتراوح بين 1 و2ms، وتبدأ الدقة في التراجع كلما طال وقت السكون، لذا لا تستخدمها للتوقيتات الدقيقة.

packet[89] = CalculateCrc(packet);
    device.send_report(packet, 91);
    device.pause(1); // We need a pause here (between packets), otherwise the ornata can't keep up.

device.set_endpoint()

تغيّر هذه الدالة نقطة النهاية النشطة لجميع أوامر القراءة والكتابة. وهي مفيدة للأجهزة التي تحتوي على عدة نقاط نهاية مفتوحة لأوامر مختلفة. من الأمثلة الشائعة على ذلك أجهزة Logitech التي تحتوي على نقطة نهاية لبيانات RGB ونقطة نهاية لأوامر النظام لأشياء مثل إعدادات DPI.

المعامل	النوع	الوصف	مثال
interface	HEX	قيمة سداسية عشرية بصيغة 0x تمثل واجهة (interface) نقطة النهاية المراد فتحها	0x0002
usage	HEX	قيمة سداسية عشرية بصيغة 0x تمثل قيمة usage لنقطة النهاية المراد فتحها	0x0006
usage_page	HEX	قيمة سداسية عشرية بصيغة 0x تمثل قيمة usage_page لنقطة النهاية المراد فتحها	0x0080
collection	HEX	قيمة سداسية عشرية بصيغة 0x تمثل قيمة collection لنقطة النهاية المراد فتحها	0x0001

function Apply()
{
    var packet = [];

    packet[0] = 0x11;
    packet[1] = 0xFF;
    packet[2] = 0x0C;
    packet[3] = 0x5E;

    device.set_endpoint(1, 0x0602, 0xff43); // System Interface
    device.write(packet, 20);
}

device.log()

هذه الدالة هي نسخة الإضافة من console.log. تأخذ قيمة من نوع String أو Number أو Object أو Array وتسجّلها في وحدة تحكم الجهاز لأغراض التصحيح وإعلام المستخدم. يمكن أن تكون مفيدة بشكل خاص لعرض أشياء مثل تغييرات DPI أو الأخطاء، أو أثناء التطوير لعرض تخطيط الحزم أو المدخلات من أوامر القراءة.

• ملاحظة: ستحاول هذه الدالة تحويل متغيرات JavaScript إلى سلاسل نصية حيثما أمكن. يمكن أن يمنحك تسجيل القوالب الحرفية (Template Literals) في JavaScript باستخدام parseInt() أو toString() أو JSON.stringify مزيدًا من التحكم في التحويل والتنسيق.

المعامل	النوع	الوصف	مثال	الافتراضي
Item	Javascript Value	سلسلة نصية أو رقم أو مصفوفة أو قيمة JavaScript أخرى ليتم تسجيلها
Options	JavaScript Object	كائن JavaScript يحتوي على معاملات الإعدادات	{hex: True}	{}

الخيارات	الوصف	النوع	الافتراضي
Hex	يحدد ما إذا كان يجب طباعة الأعداد الصحيحة بالتنسيق العشري أو السداسي عشري	Boolean	False
toFile	يحدد ما إذا كان يجب أن تظهر العناصر المطبوعة في سجلات التصحيح، أو في وحدة تحكم الجهاز فقط	Boolean	False

let ImportantData = "i have really important info here";
    device.log(ImportantData, {toFile: true})

التنبيهات

يمكن استخدام التنبيهات لتنبيه المستخدم بشكل مرئي إذا كانت هناك مشكلة في جهازه. يجب استخدامها باعتدال وتخصيصها للمشكلات الجوهرية التي تمنع العمل، مثل الأجهزة التي لم تُهيّأ بشكل صحيح.

device.notify()

تُنشئ تنبيهًا جديدًا للمستخدم. يمكن استخدام القيمة المُرجعة لإزالة التنبيه بشكل انتقائي، ويجب فعل ذلك إذا أصلح المستخدم المشكلة التي نُبِّه إليها.

ملاحظة

يجب أن يكون نص التنبيه ثابتًا حتى لا تُغرق المستخدم بالتنبيهات.

أولوية التنبيه	الوصف	القيمة
Info	تنبيه عادي	0
Important	تنبيه حرج (مميّز)	1

المعامل	النوع	الوصف	مثال
Title	String	عنوان التنبيه	Firmware Incompatible
Description	String	وصف التنبيه	Firmware Version must be >= 2.0.0
Priority	Int	أولوية التنبيه	0 | 1

القيمة المُرجعة	النوع	الوصف
AlertId	String	سلسلة معرّف التنبيه الذي تم إنشاؤه

let Alertid = device.notify("Really Important Issue", "Please Fix", 1);

device.denotify()

تزيل التنبيه المُعطى إذا كان موجودًا.

المعامل	النوع	الوصف
AlertId	String	معرّف التنبيه AlertId الذي أرجعته device.notify

let Alertid = device.notify("Really Important Issue", "Please Fix", 1);
  // Do stuff and recheck if the alerted issue is fixed
  device.denotify(AlertId);

الرسائل

توفر رسائل الجهاز طريقة لإيصال معلومات مهمة، لكنها لا تمنع العمل، إلى المستخدم. ستظهر هذه الرسائل في صفحة الجهاز فقط

device.addMessage()

تضيف رسالة جهاز جديدة بمعرّف MessageId المُعطى.

المعامل	النوع	الوصف	مثال
messageId	string	معرّف MessageId المرتبط برسالة الجهاز	”mymessage”
message	string	نص الرسالة المراد عرضه	”The message”
tooltip	string	نص إضافي يُعرض عند التمرير	”Some more info”

device.addMessage("message1", "Hey Dude you should know this", "Here's some extra info about it too");

device.removeMessage()

تزيل الرسالة التي أُنشئت بمعرّف MessageId المُعطى إذا كانت موجودة.

المعامل	النوع	الوصف
messageId	string	معرّف MessageId المراد إزالته

device.addMessage("message1", "Hey Dude you should know this", "Here's some extra info about it too");

  // message is no longer relevant
  device.removeMessage("message1");