Documentation is unclear on several issues

[theRealProHacker]

1. For me, the biggest problem are the event attributes. While most are relatively obvious, there are many that are not really. For example
   • Keyboard events: What is the difference between key, mod, unicode and scancode and how can I use them?
   • ACTIVEEVENT attributes and meaning?
   • MOUSEWHEEL: which, flipped, precise_x, precise_y?
   • TEXTEDITING: When is this triggered?
   • AUDIODEVICE*: What is which? What can I do with it? Why is it there?
   • FINGER* and MULTIGESTURE?
   • DROP*: When (and in which order) are these events emitted?
   • MIDI: What is the difference to AUDIODEVICE?
   • Many (if not all) events also have a "window" attribute. What does that mean? What should I do with it?
2. Fonts
   • How are height, ascent, descent, line height (aka linesize), max-/min-x, max-/min-y, advance of a character and the size of a text (size(text) = render(text).get_size()) related and how does setting strikethrough, underline, bold or italic change this?

I don't think "These questions are answered in tutorials and examples" is neither totally factual (afaik) nor a good response. In my opinion, this information should be contained in the reference.

• [ ] Unrelated: "The following is a list event types with their specific attributes." in https://www.pygame.org/docs/ref/event.html misses an "of" before "event"
• [ ] Add the above-mentioned unclear things to the documentation

[illume]

Some good points. Thanks.

[theRealProHacker]

I would like to make a PR. But honestly, a lot of this I don't know or would have to experiment with. Maybe you could help me a bit on that.

For fonts, I found a good source for understanding some of the things mentioned above: https://fonts.google.com/knowledge/choosing_type/exploring_x_height_the_em_square

[jack5790]

I'm going to try to answer everything at once here, if there's any confusion, just leave a reply and I'll look into it.

1. A: pygame.key is a module that holds all functions related to the keyboard, not keyboard events themselves. All pygame events are queued in the pygame.event module. B: A "key mod" is any key that is used to "modify" other keys. CTRL and Shift keys are obvious examples of modifying keys. C: The unicode and scancode attributes are gathered with the event KEYDOWN. The unicode attribute will hold the unicode value of whichever key was pressed, (this may be useful for getting letters pressed with the shift key, but will include letters pressed with caps lock on.) Scan code will return the platform specific key. Here's how a StackOverflow user describes it.

When you press a key on your keyboard, the OS first translates the button press into a key code. The key code specifies the physical location of the key on the keyboard. For example code 4 might correspond to the key labeled A on US keyboards (even if that key has a different label in France or Russia). Each platform has a different set of key codes, or possibly multiple sets. You may know them by a different name, such as scan codes or virtual key codes.

2. Active event refers to the state of the window. From my experience using Win32, there are tons of events being handled in the background of Windows applications, (is the window minimized, is there a portion of the window covered by another window, is the mouse in the window area.) I'll link another StackOverflow that covers this better than I can. (Note. ActiveEvent is now legacy, and WindowEvent is recommended instead.) Ative State StackOverflow

3. After digging through the documentation I found a link that covers all of the attributes, (x values are for horizontal mouse wheels.) The difference between preciseY and y is just the data type. The attribute y is a Sint32 (signed integer 32 bit), while the preciseY is a float, meaning it is more precise. If I had to take a guess as to the flipped attribute, I would assume it is a bool, True if the user is using an inverted mouse wheel, and False if the mouse wheel is standard. Mouse Wheel Event

4. pygame.key.start_text_input() will replace most keydown events with textinput events, allowing the user to input text. For some Asian languages, (think Chinese,) they won't input text, instead they will edit text with what is called an IME. Sending a textediting event as opposed to a textinput event.

5. I couldn't find an answer for you on this one.

6. Finger events refer to touch screens, and MultiGesture events are used to capture common touch screen patterns, like pinching to zoom in/out. It seems to be pretty similar to how unity captures touch inputs, using fingerID to refer to the same finger being down across several frames.

7. I also can't find any documentation referencing a DROP event or function, or any events with a window attribute. Falling back on my win32 experience, I would assume the window attribute returns a handle to the window the event is taking place on. This may be useful if your program creates several windows. Edit: I would also assume the DROP would be performed on an individual event, removing it from the queue.

I've been using pygame for several months now, but I haven't come across much of what you're asking about in my applications. Most of the information I got was from StackOverflow and the documentation itself so if there is anything wrong let me know.

[theRealProHacker]

Firstly, users should not have to go to the SDL docs all the time

If I may summarize/comment your efforts

1. I actually meant the key attribute on KEY* events. For mod, we could probably just reference key.get_mods() which pretty accurately describes this attribute. The scan code is bound to the physical location and is useful if you want to ignore the local or modifiers. For example, when you want to have a game using the WASD-keys. unicode is a str containing the Unicode character the key press should emit when used as a text input.
2. The comment to the accepted answer actually says

   Thanks, this is just what I was looking for. This should be in the pygame event docs somewhere. – Glenn Mackintosh

3. Thanks for your valuable research. That's exactly what we should put into the documentation. I raised issue #3781 to remove the flipped-attribute, which should also contain all the information to understand what it likely means. I will have to look into the pygame code to really understand what it means.
4. I think the reference to pygame.key.start_text_input() is already good
5. ...
6. I don't know Unity, but that makes sense.
7. DROP means the events: DROPFILE, DROPBEGIN, DROPCOMPLETE and DROPTEXT. Almost every event has a window attribute, but it is only documented on the WINDOW events. My biggest question is how to use the window handle, but it is probably just an OS-specific handle, similar to a file handle, which isn't really useful in the Python world.
8. The difference between MIDI-events and AUDIODEVICE-events is also still not clear, but could maybe be found out from the SDL documentation.

I think, I'll make a PR the next days that will include a lot of these changes to the event documentation and also bring it up-to-date.

[Duyvu1507]

I may not be the most experienced but I'll try my best to answer the questions you have:

Keyboard events: "key" refers to the physical key that was pressed or released. "mod" refers to any modifier keys that were pressed at the same time, such as Shift or Ctrl. "unicode" is the Unicode value of the character that was pressed, if applicable. "scancode" is the physical location of the key on the keyboard. You can use these attributes to determine which key was pressed or released and how it should be handled by your program.

ACTIVEEVENT attributes: The ACTIVEEVENT is triggered when the application gains or loses focus. The "gain" attribute indicates whether the application is gaining or losing focus.

MOUSEWHEEL attributes: "which" indicates which mouse wheel was moved, if there is more than one. "flipped" indicates whether the scroll direction is reversed. "precise_x" and "precise_y" are the precise x and y offsets of the mouse wheel movement, if supported by the hardware. You can use these attributes to determine how the mouse wheel was moved and how it should be handled by your program.

TEXTEDITING: The TEXTEDITING event is triggered when the user types text into a text input field. It includes information about the text that was typed, the cursor position, and the selection range. You can use this event to update the text input field in your program.

AUDIODEVICE: The AUDIODEVICE events are triggered when audio devices are added or removed from the system. The "which" attribute indicates which audio device was added or removed. You can use these events to update your audio settings or device list.

FINGER and MULTIGESTURE: The FINGER and MULTIGESTURE events are triggered when the user touches the screen with one or more fingers. They include information about the touch position, movement, and velocity, as well as any gestures that were detected. You can use these events to create touch-based user interfaces or games.

DROP: The DROP events are triggered when the user drops files onto your application's window. They include information about the files that were dropped and the position of the drop. You can use these events to implement file dragging and dropping in your program.

MIDI: The MIDI events are triggered when MIDI devices are added or removed from the system. They include information about the MIDI device and the type of event. You can use these events to update your MIDI settings or device list.

"window" attribute: The "window" attribute is used to indicate which window the event was triggered on, if your program has multiple windows. You can use this attribute to determine which window to update or respond to in your program.

Fonts: "height" is the total height of the font. "ascent" is the distance from the baseline to the top of the font. "descent" is the distance from the baseline to the bottom of the font. "line height" or "linesize" is the total height of a line of text, including any spacing between lines. "max-/min-x" and "max-/min-y" are the maximum and minimum values for the x and y coordinates of the font glyphs. "advance" is the distance from one glyph to the next in a line of text. "size(text)" returns the size of a rendered text surface in pixels. Setting strikethrough, underline, bold, or italic can affect the size and appearance of the rendered text. For example, bold text may have a larger size than regular text, and italic text may be slanted.

let me know if I made any mistakes!

[ghost]

Modifier keys also include the META key which appears to bethe Windows icon on Windows and the Command key on macOS.