Notes

This class represents an input subsystem in AROS.
Additionally, it serves as a "hub" for collecting input from the subsystems
devices in the system. Events from all subsystem input devices are merged
into a single stream and propagated to all clients.

In order to get an access to input subsystem you need to create an object of
CLID_HW_Input class. The actual returned object is a singletone, you do
not have to dispose it, and every call will return the same object pointer.

After getting this object, you can, for example, enumerate drivers
using moHW_EnumDrivers.

Hardware drivers should register with the subsystems HW Driver, using
moHW_AddDriver method.

If you wish to receive input events, use objects of CLID_Hidd_Input
class.

This class implements the same interface as driver class, but
represents receiver's side and is responsible for registering user's
interrupt handler in the listeners chain. These objects are not real
drivers and do not need to be registered within the subsystem.

Notes

A hardware driver should be a subclass of CLID_Hidd_Input, and implement IID_Hidd_Input
interface according to the following rules:

1. A single object of driver class represents a single hardware unit.
2. A single driver object maintains a single callback address (passed to it
   using aoHidd_Input_IrqHandler). Under normal conditions this callback is supplied
   by CLID_Hidd_Input class.

Notes

This class is the abstract base for all input subsystem classes.
It provides the common interface and event distribution mechanism
used by subsystem-specific input classes (e.g., keyboard, mouse,
controller).

The Input class itself is not intended for direct use. Instead,
you create an object of a subsystem-specific subclass and supply
a callback via the aoHidd_Input_IrqHandler attribute. Your
callback will then be invoked whenever an event arrives until
you dispose of the object.

All clients receive events from all subsystems input devices merged
into a single stream.

Synopsis

[I..], APTR

Function

Specifies an input event handler callback. The handler will be called every time
an input event occurs.

This attribute is used both by input event consumers (e.g., applications or higher-
level input clients) and input event providers (e.g., device drivers or subsystems)
to pass the necessary hooks for interacting with the input subsystem.

Handlers should be declared using 'C' calling conventions, for example:

    void DeviceInputIRQ(APTR data, InputIrqData_t inputData)

Handler parameters are:
    data      - The handler will be called with this set to the value
                defined using the aoHidd_Input_IrqHandlerData attribute.
    inputData - This is an opaque pointer containing subsystem-specific
                input data. Pointing devices will use struct pHidd_Mouse_Event,
                while keyboards will provide struct pHidd_Kbd_Event. See the
                subsystem-specific documentation for more details.

The handler is called inside interrupt context, so normal interrupt restrictions
apply (e.g., avoid blocking operations).

Notes

Every registered handler receives the merged event stream from all input devices.

Bugs

Not all hosted drivers provide this attribute.

See also

aoHidd_Input_IrqHandlerData

Synopsis

[I..], APTR

Function

Specifies a user-defined value that will be passed to the IRQ handler as its
first parameter. This allows both input consumers and providers to associate
static context or private data with the callback. The system will not assume
anything about this value.

Defaults to NULL if not specified.

See also

aoHidd_Input_IrqHandler

Synopsis

OOP_Object *OOP_DoMethod(OOP_Object *obj, struct pHidd_Input_AddHardwareDriver *Msg);

OOP_Object *HIDD_Input_AddHardwareDriver(OOP_Object *obj, OOP_Class *driverClass,
                                       struct TagItem *tags);

Function

Creates a hardware driver object and registers it in the system.

It does not matter on which instance of CLID_Hidd_Input class this method is
used. Hardware driver objects are shared between all of them.

Since V2 this interface is obsolete and deprecated. Use moHW_AddDriver
method on CLID_HW_Input class in order to install the driver.

Inputs

obj         - Any object of CLID_Hidd_Input class.
driverClass - A pointer to OOP class of the driver. In order to create an object
              of some previously registered public class, use
              oop.library/OOP_FindClass().
tags        - An optional taglist which will be passed to driver class' New() method.

Result

A pointer to driver object.

Notes

Do not dispose the returned object yourself, use HIDD_Input_RemHardwareDriver() for it.

See also

moHidd_Input_RemHardwareDriver

Synopsis

void OOP_DoMethod(OOP_Object *obj, struct pHidd_Input_RemHardwareDriver *Msg);

void HIDD_Input_RemHardwareDriver(OOP_Object *obj, OOP_Object *driver);

Function

Unregisters and disposes input hardware driver object.

It does not matter on which instance of CLID_Hidd_Input class this method is
used. Hardware driver objects are shared between all of them.

Since V2 this interface is obsolete and deprecated. Use moHW_RemoveDriver
method on CLID_HW_Input class in order to remove the driver.

Inputs

obj    - Any object of CLID_Hidd_Input class.
driver - A pointer to a driver object, returned by HIDD_Input_AddHardwareDriver().

Result

None

See also

moHidd_Input_AddHardwareDriver