Simple, cross-platform library to handle multiple mice.
License
icculus/manymouse
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Folders and files
Name | Name | Last commit message | Last commit date | |
---|---|---|---|---|
Repository files navigation
ManyMouse's website is http://icculus.org/manymouse/ This is a simple library to abstract away the reading of multiple input devices. It is designed to work cross-platform. Just copy all of the C files and headers in this directory into your project and build them; unless explicitly noted, you shouldn't have to #define anything, and each file is wrapped in #ifdefs to avoid compiling on the wrong platforms, so it is safe to build everything without close examination. You don't have to build this as a shared library; we encourage you to just compile the source and statically link them into your application...this makes integrating ManyMouse much less complex. The "example" directory contains complete programs to demostrate the use of the ManyMouse API in action. These files don't need to be copied into your project, but you can cut-and-paste their contents as needed. Basic usage: - Copy *.c and *.h from the base of the manymouse folder to your project. - Add the new files to your project's build system. - #include "manymouse.h" in your source code - Call ManyMouse_Init(); if it returns > 0, it found mice it can use. - Call ManyMouse_DeviceName() if you want to know the human-readable name of each device ("Logitech USB mouse", etc). - Read input from the mice with ManyMouse_PollEvent() in a loop until the function returns 0. Each time through the loop, examine the event that was returned and react appropriately. Do this with regular frequency: generally, a good rule is to poll for ManyMouse events at the same time you poll for other system GUI events...once per iteration of your program's main loop. - When you are done processing mice, call ManyMouse_Quit(). There are examples of complete usage in the "example" directory. The test apps on Linux and MacOS X can be built by running "make" from a terminal. The SDL test app will fail if Simple Directmedia Layer (http://libsdl.org/) isn't installed. The stdio apps will still work. Windows isn't integrated into the Makefile, since most people will want to put it in a VS.NET project anyhow, but here's the command line used to build some of the standalone test apps: cl /I. *.c example\test_manymouse_stdio.c /Fetest_manymouse_stdio.exe cl /I. *.c example\detect_mice.c /Fedetect_mice.exe (yes, that's simple, that's the point)...getting the SDL test app to work on Windows can be done, but takes too much effort unrelated to ManyMouse itself for this document to explain. Some notes: - If a mouse is disconnected, it will not return future events, even if you plug it right back in. You will be alerted of disconnects programmatically through the MANYMOUSE_EVENT_DISCONNECT event, which will be the last event sent for the disconnected device. You can safely redetect all mice by calling ManyMouse_Quit() followed by ManyMouse_Init(), but be warned that this may cause mice (even ones that weren't unplugged) to suddenly have a different device index, since on most systems, the replug will cause the mouse to show up elsewhere in the system's USB device tree. It is recommended that you make redetection an explicit user-requested function for this reason. - In most systems, all mice will control the same system cursor. It's recommended that you ask your window system to grab the mouse input to your application and hide the system cursor, and then do all mouse input processing through ManyMouse. Most GUI systems will continue to deliver mouse events through the system cursor even when ManyMouse is working; in these cases, you should continue to read the usual GUI system event queue, for the usual reasons, and just throw away the mouse events, which you instead grab via ManyMouse_PollEvent(). Hiding the system cursor will mean that you may need to draw your own cursor in an app-specific way, but chances are you need to do that anyhow if you plan to support multiple mice. Grabbing the input means preventing other apps from getting mouse events, too, so you'll probably need to build in a means to ungrab the mouse if the user wants to, say, respond to an instant message window or email...again, you will probably need to do this anyhow. - On Windows, ManyMouse requires Windows XP or later to function, since it relies on APIs that are new to XP...it uses LoadLibrary() on User32.dll and GetProcAddress() to get all the Windows entry points it uses, so on pre-XP systems, it will run, but fail to find any mice in ManyMouse_Init(). ManyMouse does not require a window to run, and can even be used by console (stdio) applications. Please note that using DirectInput at the same time as ManyMouse can cause problems; ManyMouse does not use DirectInput, due to DI8's limitations, but its parallel use seems to prevent ManyMouse from getting mouse input anyhow. This is mostly not an issue, but users of Simple Directmedia Layer (SDL, http://libsdl.org/) may find that it uses DirectInput behind the scenes. We are still researching the issue, but we recommend using SDL's "windib" target in the meantime to avoid this problem. - (XInput code isn't finished yet, but in the future this note will be true.) On X11 systems, we try to use the XInput extension if possible...currently most users (XFree86/x.org X server) will not find this useful, since XInput is either not included or not configured properly. In the short term, most Linux users should favor the evdev target, below. For now, the XInput target will refuse to work unless it sees more than one mouse, since in those cases, the system is possibly misconfigured. XInput currently doesn't support hotplugging, although the x.org people are planning to extend the spec to support this. If you want to use the XInput target, make sure you define SUPPORT_XINPUT at compile time and link against Xlib (on most Unixes, that's "-L/usr/X11R6/lib -lX11 -lXi). Since this requires a big external dependency, and isn't wanted on most platforms with an X server (Cygwin/X, XDarwin), you have to explicitly ask for it, even on Linux/Unix/GNU. - On Linux, we first try to use the /dev/input/event* devices; this means that ManyMouse can function with or without an X server. Please note that the next major release of x.org's X server will grab the devices at the kernel level, and will make this interface useless...eventually, their XInput implementation will implement hotplugging and such, making it the favorable ManyMouse target for most Linux users. - On MacOS X, we use IOKit's HID Manager API, which means you can use this C-callable library from Cocoa, Carbon, and generic Unix applications, with or without a GUI. We'll accept contributed Java bindings, but have no plans to implement those ourselves. This code may or may not work on Darwin (we're not sure if IOKit is available to that platform); reports of success are welcome. If you aren't already, you will need to make sure you link against the "Carbon" and "IOKit" frameworks once you add ManyMouse to your project. - Support for other platforms than MacOS X, Linux, and Windows is not planned, but contributions of implementations for other platforms are welcome. Please see the file LICENSE in the source's root directory. This library was written by Ryan C. Gordon <icculus@icculus.org>. --ryan.
About
Simple, cross-platform library to handle multiple mice.