==========
mouse_hidd
==========

.. This document is automatically generated. Don't edit it!

`Index <index>`_

----------

Classes
-------

+ `CLID_Hidd_Mouse`_
+ `CLID_HW_Mouse`_

----------

CLID_Hidd_Mouse
---------------

========================================== ========================================== ========================================== ========================================== 
`--background_mouseclass--`_               `--background_subsystem--`_                `aoHidd_Mouse_Extended`_                   `aoHidd_Mouse_RelativeCoords`_             
`aoHidd_Mouse_State`_                      
========================================== ========================================== ========================================== ========================================== 

-----------

--background_mouseclass--
=========================

Notes
~~~~~
::

     Instances of this class are virtual devices being clients of the
     pointing input subsystem. In order to receive input events, you
     have to create an object of this class and supply a callback using
     aoHidd_Input_IrqHandler attribute. After this your callback will be
     called every time the event arrives until you dispose your object.

     Every client receives events from all pointing devices merged into
     a single stream.

     Mouse event handlers are specified by passing the aHidd_Input_IrqHandler attrib,
     The handler will be called every time a mouse event occurs.  Handlers
     should be declared using 'C' calling conventions,
     e.g.:

     void MouseIRQ(APTR data, struct pHidd_Mouse_ExtEvent *event);

     Handler parameters are:
         data  - Anything you specify using aoHidd_Input_IrqHandlerData
         event - A pointer to a read-only event descriptor structure with the following
                 contents:
             button - button code, or vHidd_Mouse_NoButton of the event describes a simple
                      motion.
             x, y   - event coordinates. Need to be always valid, even if the event describes
                      a button pressed without actual motion.
                      In case of mouse wheel event these fields specify horizontal and vertical
                      wheel delta respectively.
             type   - type of event (button press, button release, wheel or motion).
             flags  - event flags. Currently only one value of vHidd_Mouse_Relative is defined.
                      If this flag is not set, coordinates are assumed to be absolute.
                      This member is actually present in the structure only if the driver
                      supplies TRUE value for aoHidd_Mouse_Extended attribute.

     The handler is called inside interrupts, so usual restrictions apply to it.




See also
~~~~~~~~

`aoHidd_Input_IrqHandler`_ `aoHidd_Input_IrqHandlerData`_ 

----------

--background_subsystem--
========================

Notes
~~~~~
::

     This class represents a "hub" for collecting input from various
     pointing devices (mice, tablets, touchscreens, etc) in the
     system. Events from all pointing devices are merged into a
     single stream and propagated to all clients.

     In order to get an access to pointing input subsystem you need to
     create an object of CLID_HW_Mouse class. The actual returned
     object is a singletone, so disposal is not neccessary.  Every
     call will return the same object pointer. After retrieving the object
     you can, for example, register your driver using moHW_AddDriver
     method, or enumerate drivers using moHW_EnumDrivers.

     If you wish to receive mouse events, use objects of CLID_Hidd_Mouse
     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.



----------

aoHidd_Mouse_Extended
=====================

Synopsis
~~~~~~~~
::

     [..G], BOOL


Function
~~~~~~~~
::

     Asks the driver if it provides extended event descriptor structure
     (struct pHidd_Mouse_ExtEvent).

     If value of this attribute is FALSE, the flags member is actually missing from
     the structure, not just zeroed out! So do not use it at all in this case.

     CLID_Hidd_Mouse class always return TRUE for this attribute.



----------

aoHidd_Mouse_RelativeCoords
===========================

Synopsis
~~~~~~~~
::

     [..G], BOOL


Function
~~~~~~~~
::

     Asks the driver it the device provides relative (like mouse) or absolute (like
     touchscreen or tabled) coordinates.

     Drivers which provide extended event structure may not implement this attribute
     because they may provide mixed set of events. In this case coordinates type
     is determined by flags member of struct pHidd_Mouse_ExtEvent.

     CLID_Hidd_Mouse class does not implement this attribute since it provides mixed
     stream of events.



See also
~~~~~~~~

`aoHidd_Mouse_Extended`_ 

----------

aoHidd_Mouse_State
==================

Synopsis
~~~~~~~~
::

     [..G], struct pHidd_Mouse_Event


Function
~~~~~~~~
::

     Obtains current pointing devices state.

     This attribute was historically implemented only in PS/2 mouse driver, but the
     implementation was broken and incomplete. At the moment this attribute is considered
     reserved. Do not use it, the specification may change in future.


Bugs
~~~~
::

     Not implemented, considered reserved.



CLID_HW_Mouse
-------------

========================================== ========================================== ========================================== ========================================== 
`--hardware_drivers--`_                    
========================================== ========================================== ========================================== ========================================== 

-----------

--hardware_drivers--
====================

Notes
~~~~~
::

     A hardware driver should be a subclass of CLID_Hidd_Mouse, and implement IID_Hidd_Mouse
     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_HW_Mouse class.



