إتاحة استخدام أجهزة الماوس

استخدِم الدوال التالية لإضافة إمكانية استخدام الماوس في لعبتك من خلال مكتبة Game Controller. نستخدم هنا مصطلح "أجهزة الماوس" لوصف أجهزة الماوس التقليدية، بالإضافة إلى لوحات اللمس أو كرات التتبع.

إضافة دالة ردّ الاتصال الخاصة بحالة الماوس

تستخدِم مكتبة Game Controller دالة رد نداء لحالة الماوس لإرسال إشعار إلى إحدى الألعاب عند توصيل ماوس أو فصله. يمكن استخدام دالة معاودة الاتصال واحدة فقط لحالة الماوس في كل مرة.

• لتسجيل دالة رد نداء خاصة بحالة الماوس أو استبدال أي دالة رد نداء مسجّلة سابقًا بدالة رد نداء جديدة، استدعِ الدالة Paddleboat_setMouseStatusCallback.
• لإزالة أيّ دالة ردّ حالية مسجَّلة، مرِّر NULL أو nullptr في المَعلمة statusCallback.
• المَعلمة userData هي مؤشر اختياري إلى البيانات المحدّدة من قِبل المستخدِم. سيتم تمرير المَعلمة userData إلى دالة رد الاتصال. يتم الاحتفاظ بهذا المؤشر داخليًا إلى أن يتم تغييره من خلال طلب آخر إلى Paddleboat_setMouseStatusCallback.

void Paddleboat_setMouseStatusCallback(Paddleboat_MouseStatusCallback
  statusCallback, void *userData)

توقيع دالة رد الاتصال الخاصة بحالة الماوس هو:

typedef void (*Paddleboat_MouseStatusCallback)(const Paddleboat_MouseStatus
  mouseStatus, void *userData)

تتضمّن المَعلمة mouseStatus enum ثلاث قيم محتملة:

• PADDLEBOAT_MOUSE_NONE: ما مِن جهاز فأرة متصل حاليًا.
• PADDLEBOAT_MOUSE_CONTROLLER_EMULATED: جهاز تحكّم متصل يحاكي الماوس.
• ‫PADDLEBOAT_MOUSE_PHYSICAL: يشير إلى أنّه تم توصيل جهاز واحد أو أكثر من أجهزة الماوس المادية. (تشمل هذه الأجهزة الماوس أو لوحة اللمس أو كرة التتبّع أو غيرها من الأجهزة المشابهة).

تحتوي المَعلمة userData على مؤشر userData المحدّد في آخر استدعاء للدالة Paddleboat_setMouseStatusCallback. يمكن أن تكون قيمة userData فارغة (NULL) أو nullptr.

لا تحاكي بعض وحدات التحكّم وظيفة الماوس. ويمكن أن تحاكي وحدات التحكّم الماوس باستخدام أحد عصا التحكم التناظرية أو لوحة اللمس المدمجة.

لا تعرض مكتبة Game Controller إلا البيانات من جهاز فأرة واحد. تحظى أجهزة الماوس الخارجية بالأولوية على أجهزة الماوس التي تعمل كوحدة تحكّم افتراضية. في حال توصيل ماوس خارجي، سيحلّ محلّ أي ماوس افتراضي نشط سابقًا.

قراءة بيانات الماوس

استدعِ الدالة Paddleboat_getMouseStatus للحصول على حالة جهاز الماوس.

Paddleboat_MouseStatus Paddleboat_getMouseStatus()

استخدِم الدالة Paddleboat_getMouseData للحصول على بيانات الماوس الحالية. تعرض هذه الدالة PADDLEBOAT_NO_ERROR إذا تمت قراءة البيانات بنجاح، وإلا سيتم عرض رمز خطأ مناسب.

bool Paddleboat_getMouseData(Paddleboat_Mouse_Data *mouseData)

يحتوي هيكل Paddleboat_Mouse_Data على معلومات حول:

• الطابع الزمني لآخر حدث إدخال باستخدام الماوس
• موضع المؤشر الحالي
• حالة أزرار الماوس
• حالة عجلات الماوس

struct Paddleboat_Mouse_Data {
    uint64_t timestamp;
    uint32_t buttonsDown;
    int32_t mouseScrollDeltaH;
    int32_t mouseScrollDeltaV;
    float mouseX;
    float mouseY;
}

تحدّد مكتبة Game Controller ثوابت قناع البت لأزرار الماوس في ملف عنوان واجهة paddleboat.h:

enum Paddleboat_Mouse_Buttons {
    PADDLEBOAT_MOUSE_BUTTON_LEFT = (1U << 0),
    PADDLEBOAT_MOUSE_BUTTON_RIGHT = (1U << 1),
    PADDLEBOAT_MOUSE_BUTTON_MIDDLE = (1U << 2),
    PADDLEBOAT_MOUSE_BUTTON_BACK = (1U << 3),
    PADDLEBOAT_MOUSE_BUTTON_FORWARD = (1U << 4),
    PADDLEBOAT_MOUSE_BUTTON_6 = (1U << 5),
    PADDLEBOAT_MOUSE_BUTTON_7 = (1U << 6),
    PADDLEBOAT_MOUSE_BUTTON_8 = (1U << 7)
};

أجهزة الماوس الفعلية مقابل أجهزة الماوس الافتراضية

يشير Paddleboat_MouseStatus من PADDLEBOAT_MOUSE_CONTROLLER_EMULATED إلى عدم توفّر جهاز ماوس خارجي وأنّ مكتبة Game Controller تحاكي ماوسًا افتراضيًا باستخدام ذراع تحكّم متصل. يتم استخدام أدنى فهرس لوحدة تحكّم متصلة مع ضبط العلامة PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE كفأرة افتراضية. لا يمكن ضمان أن تعرض أجهزة الماوس الافتراضية سوى الإحداثيات mouseX وmouseY. قد تتيح أجهزة الماوس الافتراضية تسجيل النقرات من زر ماوس واحد (أيسر)، ولكن هذا ليس مضمونًا.