Event Classes
=======================

PySpin provides an event-driven interface for responding to camera and system
notifications asynchronously.  Rather than polling for state changes, you
register a handler subclass with the relevant camera or system object and
override the appropriate callback method.  The SDK will invoke your handler on
a dedicated internal thread whenever the corresponding event fires.

The available handler categories are:

- **Device events** – camera-level hardware notifications (arrival, removal,
  and device-specific GenICam events).
- **Image events** – called each time a new image or image list is ready for
  processing without calling :py:meth:`~PySpin.Camera.GetNextImage`.
- **Interface events** – fired when a network or USB interface appears or
  disappears on the host.
- **Logging events** – route Spinnaker's internal log messages to your own
  handler for diagnostics or structured logging.
- **System events** – top-level notifications dispatched by the
  :py:class:`~PySpin.System` singleton.

Usage pattern::

    import PySpin

    class MyImageHandler(PySpin.ImageEventHandler):
        def OnImageEvent(self, image):
            print(f"Received image {image.GetFrameID()}")

    system = PySpin.System.GetInstance()
    cam_list = system.GetCameras()
    cam = cam_list[0]
    cam.Init()

    handler = MyImageHandler()
    cam.RegisterEventHandler(handler)

    cam.BeginAcquisition()
    # ... handler fires automatically for each new image ...
    cam.EndAcquisition()

    cam.UnregisterEventHandler(handler)
    cam.DeInit()
    cam_list.Clear()
    system.ReleaseInstance()

.. note::
   Always call :py:meth:`~PySpin.Camera.UnregisterEventHandler` before
   :py:meth:`~PySpin.Camera.DeInit` to avoid callbacks firing on a partially
   torn-down camera object.

PySpin.DeviceArrivalEventHandler
---------------------------------
.. autoclass:: PySpin.DeviceArrivalEventHandler
   :members:
   :undoc-members:
   
PySpin.DeviceEventHandler
--------------------------
.. autoclass:: PySpin.DeviceEventHandler
   :members:
   :undoc-members:
   
PySpin.DeviceRemovalEventHandler
---------------------------------
.. autoclass:: PySpin.DeviceRemovalEventHandler
   :members:
   :undoc-members:

PySpin.EventHandler
--------------------
.. autoclass:: PySpin.EventHandler
   :members:
   :undoc-members:
   
PySpin.ImageEventHandler
-------------------------
.. autoclass:: PySpin.ImageEventHandler
   :members:
   :undoc-members:

PySpin.ImageListEventHandler
----------------------------
.. autoclass:: PySpin.ImageListEventHandler
   :members:
   :undoc-members:

PySpin.InterfaceArrivalEventHandler
------------------------------------
.. autoclass:: PySpin.InterfaceArrivalEventHandler
   :members:
   :undoc-members:
   
PySpin.InterfaceEventHandler
------------------------------
.. autoclass:: PySpin.InterfaceEventHandler
   :members:
   :undoc-members:
   
PySpin.InterfaceRemovalEventHandler
------------------------------------
.. autoclass:: PySpin.InterfaceRemovalEventHandler
   :members:
   :undoc-members:
   
PySpin.LoggingEventHandler
---------------------------
.. autoclass:: PySpin.LoggingEventHandler
   :members:
   :undoc-members:
   
PySpin.LoggingEventDataPtr
---------------------------
.. autoclass:: PySpin.LoggingEventDataPtr
   :members:
   :undoc-members:
   
PySpin.SystemEventHandler
------------------------------
.. autoclass:: PySpin.SystemEventHandler
   :members:
   :undoc-members: