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

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

إضافة معاودة الاتصال بحالة الماوس

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

• لتسجيل استدعاء حالة الماوس أو استبدال أي معاودة اتصال تم تسجيلها سابقًا بدالة استدعاء جديدة، استدعِ دالة 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 ثلاث قيم محتمَلة:

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

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

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

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

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

استدعِ وظيفة 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;
}

عضو في البنية	الوصف
timestamp	الطابع الزمني لأحدث حدث تم إدخاله عن طريق الماوس قيمة الطابع الزمني هي بالميكرو ثانية منذ حقبة الساعة.
buttonsDown	بتفيلد، يشير كل بت تبدأ من البت 0 إلى حالة زر لأسفل إذا تم تعيينها.
mouseX mouseY	موضع الماوس في إحداثيات البكسل. يكون لإحداثيات الموضع نطاق من 0.0 إلى عرض الشاشة وارتفاعها.
mouseScrollDeltaH mouseScrollDeltaV	عدد الأحداث التراكمية لعجلة تمرير الماوس : منذ الاستدعاء السابق إلى Paddleboat_getMouseData. هذه القيم غير مضمونة لتكون دقيقة، ولكن لإعطاء مؤشر عن نشاط عجلة التمرير في اتجاه معين. تمتلك معظم الفئران عجلة تمرير واحدة، ويتم رصدها في mouseScrollDeltaV. إذا كان الماوس يحتوي على عجلة تمرير جانبية، يتم الإبلاغ عنها في mouseScrollDeltaH. تتم إعادة ضبط هذه القيم على 0 داخليًا بعد استدعاء Paddleboat_getMouseData.

تحدّد مكتبة وحدة التحكّم في الألعاب ثوابت قناع البت لأزرار الماوس في ملف العنوان الخاص بواجهة 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 إلى عدم توفّر جهاز ماوس فعلي وأنّ مكتبة وحدة التحكّم في الألعاب تحاكي ماوس افتراضي باستخدام وحدة تحكُّم متصلة. يتم استخدام أدنى فهرس وحدة تحكّم متصلة مع مجموعة علامات PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE باعتباره ماوس افتراضي. تضمن أجهزة الماوس الافتراضية فقط الإبلاغ عن إحداثي mouseX وmouseY. قد تُبلِغ أجهزة الماوس الافتراضية عن ضغطات من زر ماوس واحد (أيسر)، لكن ذلك ليس مضمونًا.