In pygame for event.type == ACTIVEEVENT, where is the documentation on what the different event.state and event.gain parameters mean?

Question

I am writing a game in pygame and ran into a situation with needing to discover when the game gains and looses focus. This is indicated with the event.type ACTIVEEVENT, which has two parameters event.state and event.gain. However after looking all over I have been able to find only a little info on what these imply. There are at least 6 different state values that an ACTIVEEVENT can have and each of those states can have multiple gain values

There are snippets here and there, but I could not actually find actual documentation on it anywhere. There is a couple references to the ACTIVEEVENT in https://www.pygame.org/docs/ref/ but no actual information.

I am not looking for people to tell me bits and pieces of what they have discovered about how it works, I have already found it in dribs and drabs, and based on that and some experimenting I figured out what I need. (ACTIVEEVENT state 2, gain 0 seems to mean window lost focus, and ACTIVEEVENT state 6, gain 1 seems to mean window regained focus).

What I want to know is where there is any actual documentation on the ACTIVEEVENT event and/or where I can find it in the pygame documentation if I am missing it somehow?

Answer 1

Since pygame is a thin SDL wrapper, it usually helps to look at libsdl itself:

/** @name The available application states */
/*@{*/
#define SDL_APPMOUSEFOCUS   0x01        /**< The app has mouse coverage */
#define SDL_APPINPUTFOCUS   0x02        /**< The app has input focus */
#define SDL_APPACTIVE       0x04        /**< The application is active */
/*@}*/

/* Function prototypes */
/** 
 * This function returns the current state of the application, which is a
 * bitwise combination of SDL_APPMOUSEFOCUS, SDL_APPINPUTFOCUS, and
 * SDL_APPACTIVE.  If SDL_APPACTIVE is set, then the user is able to
 * see your application, otherwise it has been iconified or disabled.
 */
extern DECLSPEC Uint8 SDLCALL SDL_GetAppState(void);

Here's a little pygame script to see those values in action:

import pygame

pygame.init()

screen = pygame.display.set_mode((200, 200))
clock = pygame.time.Clock()

APPMOUSEFOCUS = 1
APPINPUTFOCUS = 2
APPACTIVE     = 4

def main():
  while True:
    for e in pygame.event.get():
      if e.type == pygame.QUIT: 
          return
      if e.type == pygame.ACTIVEEVENT:
          if e.state & APPMOUSEFOCUS == APPMOUSEFOCUS:
              print ('mouse focus ' + ('gained' if e.gain else 'lost'))
          if e.state & APPINPUTFOCUS == APPINPUTFOCUS:
              print ('input focus ' + ('gained' if e.gain else 'lost'))
          if e.state & APPACTIVE == APPACTIVE:
              print('app is ' + ('visibile' if e.gain else 'iconified'))
    screen.fill((30, 30, 30))
    pygame.display.flip()
    clock.tick(60)

main()

Note that SDL 2 no longer uses these values, but rather events like

SDL_WINDOWEVENT_ENTER
SDL_WINDOWEVENT_LEAVE
SDL_WINDOWEVENT_FOCUS_GAINED
SDL_WINDOWEVENT_FOCUS_LOST
SDL_WINDOWEVENT_MINIMIZED
SDL_WINDOWEVENT_RESTORED

That may be revelant if you want to use pygame 2 in the future.