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

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

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

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

• لتسجيل معاودة الاتصال بحالة الماوس أو استبدال أي معاودة اتصال سبق تسجيلها بدالة جديدة لمعاودة الاتصال، عليك استدعاء الدالة 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 فارغة أو 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. قد تقوم أجهزة الماوس الافتراضية بالإبلاغ عن الضغطات من زر ماوس واحد (يسار)، ولكن هذا ليس مضمونًا.