| Summary: | Unclear documentation for SDL_ActiveEvent, or bad behaviour | ||
|---|---|---|---|
| Product: | SDL | Reporter: | Sebastian Redl <wasti.redl> |
| Component: | website | Assignee: | Ryan C. Gordon <icculus> |
| Status: | RESOLVED FIXED | QA Contact: | Sam Lantinga <slouken> |
| Severity: | normal | ||
| Priority: | P2 | ||
| Version: | 1.2.9 | ||
| Hardware: | x86 | ||
| OS: | Windows (XP) | ||
Where did you see that documentation? The header has the following comment: * 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. Here: http://www.libsdl.org/cgi/docwiki.cgi/SDL_5fActiveEvent I'm not sure how authoritative the DocWiki is, but there seems to be no other online resource. The Wiki has been updated, thanks. BTW, you're welcome to correct the Wiki documentation if you find any errors in it. I would have, but I didn't know whether it was a bug in the docs or the implementation. Will check the header next time. |
The documentation of SDL_ActiveEvent's state member is: "SDL_APPMOUSEFOCUS if mouse focus was gained or lost, SDL_APPINPUTFOCUS if input focus was gained or lost, or SDL_APPACTIVE if the application was iconified (gain=0) or restored(gain=1)." The "or" leads the reader to believe that a == comparison with these constants is appropriate to detect these states, i.e. that one event is generated for each type of state change. At least in the Windows implementation, this is not the case, though: an APPACTIVE state never comes alone, but is instead bit-or'ed together with APPMOUSEFOCUS. Code that looks like this doesn't work: if(event.active.state == SDL_APPACTIVE) { active = event.active.gain != 0; } Either the Windows implementation is in error in that it creates mixed events (in my opinion, that is the case, as I don't think mixing events is a good idea), or the documentation is unclear or even faulty.