Events as types

docs/reST/c_api/event.rst

@@ -59,10 +59,10 @@ Header file: src_c/include/pygame.h
    Return an array of bools (using char) of length 5
    with the most recent button releases.
 
-.. c:function:: int pg_post_event(Uint32 type, PyObject *dict)
+.. c:function:: int pg_post_event(Uint32 type, PyObject *obj)
 
    Posts a pygame event that is an ``SDL_USEREVENT`` on the SDL side. This
-   function takes a python dict, which can be NULL too.
+   function takes a python dict/event object, which can be NULL too.
    This function does not need GIL to be held if dict is NULL, but needs GIL
    otherwise. Just like the SDL ``SDL_PushEvent`` function, returns 1 on
    success, 0 if the event was not posted due to it being blocked, and -1 on
@@ -79,3 +79,9 @@ Header file: src_c/include/pygame.h
    creation of the dictproxy instance, and when it is freed.
    Just like the SDL ``SDL_PushEvent`` function, returns 1 on success, 0 if the
    event was not posted due to it being blocked, and -1 on failure.
+
+.. c:function:: PyObject* pgEvent_GetClass(Uint32 type)
+
+   Returns a python class object correlated with the given event type - object is returned
+   as a new reference. On error returns NULL and sets python exception.
+   Same as calling ``pygame.event.event_class(type)`` in python.

docs/reST/ref/event.rst

@@ -463,6 +463,19 @@ On Android, the following events can be generated
 
    .. ## pygame.event.custom_type ##
 
+.. function:: event_class
+
+   | :sl:`returns related event class to event type`
+   | :sg:`event_class(type: int, /) -> type[Event]`
+
+   Returns an event class that is correlated with the given event type. If the class to a given event type is not found,
+   but the type is within the range of valid values for the event type, instead of ``pygame.event.Event`` sublclass returned,
+   ``pygame.event.Event`` itself will be returned, so don't rely on the retuned class having ``type`` attribute equal to a number.
+   This happens for example, with user event types that weren't created by subclassing ``pygame.event.Event``.
+
+   .. versionadded:: 2.5.0
+   .. ## pygame.event.event_class ##
+
 .. class:: Event
 
    | :sl:`pygame object for representing events`
@@ -477,6 +490,8 @@ On Android, the following events can be generated
 
    .. versionchanged:: 2.1.4 This class is also available through the ``pygame.Event``
       alias.
+
+   .. versionchanged:: 2.5.0 This class can be subclassed to create user-defined event types.
 
    .. note::
       From version 2.1.3 ``EventType`` is an alias for ``Event``. Beforehand,
@@ -515,4 +530,84 @@ On Android, the following events can be generated
 
    .. ## pygame.event.Event ##
 
+.. table:: List of Event subclasses available as aliases for event types importable as ``pygame.event.{Class name}``.
+   :widths: auto
+
+   =============================  =============================  ==========================
+   Class name                     Alias to                       Notes
+   =============================  =============================  ==========================
+   ``ActiveEvent``                ``ACTIVEEVENT``                
+   ``AppTerminating``             ``APP_TERMINATING``            
+   ``AppLowMemory``               ``APP_LOWMEMORY``              
+   ``AppWillEnterBackground``     ``APP_WILLENTERBACKGROUND``    
+   ``AppDidEnterBackground``      ``APP_DIDENTERBACKGROUND``     
+   ``AppWillEnterForeground``     ``APP_WILLENTERFOREGROUND``    
+   ``AppDidEnterForeground``      ``APP_DIDENTERFOREGROUND``     
+   ``ClipboardUpdate``            ``CLIPBOARDUPDATE``            
+   ``KeyDown``                    ``KEYDOWN``                    
+   ``KeyUp``                      ``KEYUP``                      
+   ``KeyMapChanged``              ``KEYMAPCHANGED``              
+   ``LocaleChanged``              ``LOCALECHANGED``              Only for SDL 2.0.14+
+   ``MouseMotion``                ``MOUSEMOTION``                
+   ``MouseButtonDown``            ``MOUSEBUTTONDOWN``            
+   ``MouseButtonUp``              ``MOUSEBUTTONUP``              
+   ``JoyAxisMotion``              ``JOYAXISMOTION``              
+   ``JoyBallMotion``              ``JOYBALLMOTION``              
+   ``JoyHatMotion``               ``JOYHATMOTION``               
+   ``JoyButtonUp``                ``JOYBUTTONUP``                
+   ``JoyButtonDown``              ``JOYBUTTONDOWN``              
+   ``Quit``                       ``QUIT``                       
+   ``SysWMEvent``                 ``SYSWMEVENT``                 
+   ``VideoResize``                ``VIDEORESIZE``                
+   ``VideoExpose``                ``VIDEOEXPOSE``                
+   ``MidiIn``                     ``MIDIIN``                     
+   ``MidiOut``                    ``MIDIOUT``                    
+   ``NoEvent``                    ``NOEVENT``                    
+   ``FingerMotion``               ``FINGERMOTION``               
+   ``FingerDown``                 ``FINGERDOWN``                 
+   ``FingerUp``                   ``FINGERUP``                   
+   ``MultiGesture``               ``MULTIGESTURE``               
+   ``MouseWheel``                 ``MOUSEWHEEL``                 
+   ``TextInput``                  ``TEXTINPUT``                  
+   ``TextEditing``                ``TEXTEDITING``                
+   ``DropFile``                   ``DROPFILE``                   
+   ``DropText``                   ``DROPTEXT``                   
+   ``DropBegin``                  ``DROPBEGIN``                  
+   ``DropComplete``               ``DROPCOMPLETE``               
+   ``ControllerAxisMotion``       ``CONTROLLERAXISMOTION``       
+   ``ControllerButtonDown``       ``CONTROLLERBUTTONDOWN``       
+   ``ControllerButtonUp``         ``CONTROLLERBUTTONUP``         
+   ``ControllerDeviceAdded``      ``CONTROLLERDEVICEADDED``      
+   ``ControllerDeviceRemoved``    ``CONTROLLERDEVICEREMOVED``    
+   ``ControllerDeviceMapped``     ``CONTROLLERDEVICEREMAPPED``     
+   ``JoyDeviceAdded``             ``JOYDEVICEADDED``             
+   ``JoyDeviceRemoved``           ``JOYDEVICEREMOVED``           
+   ``ControllerTouchpadDown``     ``CONTROLLERTOUCHPADDOWN``     Only for SDL 2.0.14+
+   ``ControllerTouchpadMotion``   ``CONTROLLERTOUCHPADMOTION``   Only for SDL 2.0.14+
+   ``ControllerTouchpadUp``       ``CONTROLLERTOUCHPADUP``       Only for SDL 2.0.14+
+   ``ControllerSensorUpdate``     ``CONTROLLERSENSORUPDATE``     Only for SDL 2.0.14+
+   ``AudioDeviceAdded``           ``AUDIODEVICEADDED``           
+   ``AudioDeviceRemoved``         ``AUDIODEVICEREMOVED``         
+   ``RenderTargetsReset``         ``RENDER_TARGETS_RESET``       
+   ``RenderDeviceReset``          ``RENDER_DEVICE_RESET``        
+   ``WindowShown``                ``WINDOWSHOWN``                
+   ``WindowHidden``               ``WINDOWHIDDEN``               
+   ``WindowExposed``              ``WINDOWEXPOSED``              
+   ``WindowMoved``                ``WINDOWMOVED``                
+   ``WindowResized``              ``WINDOWRESIZED``              
+   ``WindowSizeChanged``          ``WINDOWSIZECHANGED``          
+   ``WindowMinimized``            ``WINDOWMINIMIZED``            
+   ``WindowMaximized``            ``WINDOWMAXIMIZED``            
+   ``WindowRestored``             ``WINDOWRESTORED``             
+   ``WindowEnter``                ``WINDOWENTER``                
+   ``WindowLeave``                ``WINDOWLEAVE``                
+   ``WindowFocusGained``          ``WINDOWFOCUSGAINED``          
+   ``WindowFocusLost``            ``WINDOWFOCUSLOST``            
+   ``WindowClose``                ``WINDOWCLOSE``                
+   ``WindowTakeFocus``            ``WINDOWTAKEFOCUS``            
+   ``WindowHitTest``              ``WINDOWHITTEST``              
+   ``WindowICCProfChanged``       ``WINDOWICCPROFCHANGED``       
+   ``WindowDisplayChanged``       ``WINDOWDISPLAYCHANGED``       
+   =============================  =============================  ==========================
+
 .. ## pygame.event ##

meson_options.txt

@@ -24,12 +24,12 @@ option('midi', type: 'feature', value: 'enabled')
 # Controls whether to make a "stripped" pygame install. Enabling this disables
 # the bundling of docs/examples/tests/stubs in the wheels.
 # The default behaviour is to bundle all of these.
-option('stripped', type: 'boolean', value: 'false')
+option('stripped', type: 'boolean', value: false)
 
 # Controls whether to compile with -Werror (or its msvc equivalent). The default
 # behaviour is to not do this by default
-option('error_on_warns', type: 'boolean', value: 'false')
+option('error_on_warns', type: 'boolean', value: false)
 
 # Controls whether to error on build if generated docs are missing. Defaults to
 # false.
-option('error_docs_missing', type: 'boolean', value: 'false')
+option('error_docs_missing', type: 'boolean', value: false)

src_c/_pygame.h

@@ -196,14 +196,14 @@ PG_SurfaceHasRLE(SDL_Surface *surface);
 
 #endif
 
-/* DictProxy is useful for event posting with an arbitrary dict. Maintains
- * state of number of events on queue and whether the owner of this struct
- * wants this dict freed. This DictProxy is only to be freed when there are no
- * more instances of this DictProxy on the event queue. Access to this is
- * safeguarded with a per-proxy spinlock, which is more optimal than having
- * to hold GIL in case of event timers */
+/* DictProxy is useful for event posting with an arbitrary dict/event object.
+ * Maintains state of number of events on queue and whether the owner of this
+ * struct wants this dict/event instance freed. This DictProxy is only to be
+ * freed when there are no more instances of this DictProxy on the event queue.
+ * Access to this is safeguarded with a per-proxy spinlock, which is more
+ * optimal than having to hold GIL in case of event timers */
 typedef struct _pgEventDictProxy {
-    PyObject *dict;
+    PyObject *obj;  // Either dict or event object.
     SDL_SpinLock lock;
     int num_on_queue;
     Uint8 do_free_at_end;
@@ -533,7 +533,7 @@ typedef enum {
 #define PYGAMEAPI_COLOR_NUMSLOTS 5
 #define PYGAMEAPI_MATH_NUMSLOTS 2
 #define PYGAMEAPI_BASE_NUMSLOTS 29
-#define PYGAMEAPI_EVENT_NUMSLOTS 10
+#define PYGAMEAPI_EVENT_NUMSLOTS 11
 #define PYGAMEAPI_WINDOW_NUMSLOTS 1
 #define PYGAMEAPI_GEOMETRY_NUMSLOTS 1
 

src_c/base.c

@@ -296,6 +296,10 @@ pg_mod_autoquit(const char *modname)
 
     funcobj = PyObject_GetAttrString(module, "_internal_mod_quit");
 
+    /* Silence errors */
+    if (PyErr_Occurred())
+        PyErr_Clear();
+
     /* If we could not load _internal_mod_quit, load quit function */
     if (!funcobj)
         funcobj = PyObject_GetAttrString(module, "quit");

src_c/doc/event_doc.h

@@ -14,6 +14,7 @@
 #define DOC_EVENT_GETGRAB "get_grab() -> bool\ntest if the program is sharing input devices"
 #define DOC_EVENT_POST "post(event, /) -> bool\nplace a new event on the queue"
 #define DOC_EVENT_CUSTOMTYPE "custom_type() -> int\nmake custom user event type"
+#define DOC_EVENT_EVENTCLASS "event_class(type: int, /) -> type[Event]\nreturns related event class to event type"
 #define DOC_EVENT_EVENT "Event(type, dict) -> Event\nEvent(type, **attributes) -> Event\npygame object for representing events"
 #define DOC_EVENT_EVENT_TYPE "type -> int\nevent type identifier."
 #define DOC_EVENT_EVENT_DICT "__dict__ -> dict\nevent attribute dictionary"