OSX: number of buttons on attached mouse

Question

I would like to offer tutorial text that changes depending on the number of mouse buttons available. For example, if there are two mouse buttons the text would say "Right click" whereas if there's only 1 button the text would say "Ctrl+click". Is there any API in Cocoa or Carbon that can identify the number of available buttons on the attached mouse?

Answer 1

I would look at the Quartz event services. That's the only place I can think of off the top of my head that will tell you something about the hardware.

However, I don't think you should bother. In general you should adopt a terminology that assumes a standardized hardware or hardware equivalent. For example, the actual command is 'ctrl-click'. That command might be implemented by a right mouse button but it might come from the keyboard or some custom setup for some other hardware. For example, I have a Wacom tablet that lets me custom map five different buttons. Your software could not puzzle out my mapping.

You interface should just say 'ctrl-click' and leave it to the user to define what that means for their own hardware.

Answer 2

Use “secondary click”. This is true of right-click, ctrl-click, left-click on a button-swapped mouse, 18th-click on a highly configurable mouse, a tablet or joystick configured to work as a mouse, etc.

Answer 3

I’m with Peter Hosey here: “secondary click” is correct, and “right-click” is definitively wrong, since you can change which is which in the Mouse preference pane. Also, there’s a secondary-click trackpad gesture.

In the interest of actually answering the question, if you really want to count the buttons on the connected mice (do not assume there’s only one; laptops in particular will often have two and there’s no inherent limit), I believe you’ll need to talk to IOKit (specifically, IOKit/hid/IOHIDDevice.h.)

You’ll then want to find devices whose kIOHIDPrimaryUsagePageKey is kHIDPage_GenericDesktop and whose kIOHIDPrimaryUsageKey is kHIDUsage_GD_Pointer or kHIDUsage_GD_Mouse, and search for the element on the kHIDPage_Button usage page with the highest usage value. This is all fiddly but not very hard, unless you feel the need to support pre-Leopard systems in which case it’s an insane mess.

But! This won’t actually tell you how many buttons the user has on each mouse, it will only give you an upper bound, because USB devices tend to have generic hardware which lies. For instance, all Logitech mice I’ve tested – apart from the Logitech-made Apple Puck Mouse™ – claim to have 16 buttons. For reference, keyboards lie even worse than that.