--- name: "SDL::Event" section: "3pm" platform: "linux" package: "libsdl-perl" version: "2.548-5+b1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/SDL::Event" --- # SDL::Event(3pm) General event structure ## NAME SDL::Event - General event structure ### CATEGORY Core, Events, Structure ## SYNOPSIS ``` use SDL::Event; # for the event object itself use SDL::Events; # functions for event queue handling SDL::init(SDL_INIT_VIDEO); my $event = SDL::Event->new(); while(1) { SDL::Events::pump_events(); if(SDL::Events::poll_event($event)) { if($event->type == SDL_MOUSEBUTTONDOWN) { # now you can handle the details $event->button_which; $event->button_button; $event->button_x; $event->button_y; } last if $event->type == SDL_QUIT; } # your screen drawing code will be here } ``` ## DESCRIPTION Event handling allows your application to receive input from the user. Event handling is initalised (along with video) with a call to: `"SDL::init(SDL_INIT_VIDEO);"` Internally, SDL stores all the events waiting to be handled in an event queue. Using functions like `SDL::Events::poll_event()`, `"SDL::Events::peep_events"` and `SDL::Events::wait_event()` you can observe and handle waiting input events. The key to event handling in SDL is the `"SDL::Event"` union. The event queue itself is composed of a series of `"SDL::Event"` unions, one for each waiting event. `"SDL::Event"` unions are read from the queue with the `SDL::Events::poll_event()` function and it is then up to the application to process the information stored with them. ## METHODS ### new `"new"` creates an empty event-object, which can be used store information. Either by calling `poll_event($event)` that transfers one event from the queue into our object or by setting all the needed data manually in order to push the event to the queue. ``` use SDL::Event; my $event = SDL::Event->new(); ``` ### type SDL::Event is a union of all event structures used in SDL, using it is a simple matter of knowing which union member relates to which event `"type"`. ``` print 'heureka' if $event->type == SDL_MOUSEBUTTONDOWN; ``` Available type constants: - • SDL\_ACTIVEEVENT - Application visibility event structure - • SDL\_KEYDOWN - Keyboard event structure - • SDL\_KEYUP - Keyboard event structure - • SDL\_MOUSEMOTION - Mouse motion event structure - • SDL\_MOUSEBUTTONDOWN - Mouse button event structure - • SDL\_MOUSEBUTTONUP - Mouse button event structure - • SDL\_JOYAXISMOTION - Joystick axis motion event structure - • SDL\_JOYBALLMOTION - Joystick trackball motion event structure - • SDL\_JOYHATMOTION - Joystick hat position change event structure - • SDL\_JOYBUTTONDOWN - Joystick button event structure - • SDL\_JOYBUTTONUP - Joystick button event structure - • SDL\_VIDEORESIZE - Window resize event structure - • SDL\_VIDEOEXPOSE - Window expose event - • SDL\_QUIT - Quit requested event - • SDL\_USEREVENT - A user-defined event type - • SDL\_SYSWMEVENT - Platform-dependent window manager event. Event types are grouped by masks. `SDL_EVENTMASK($type)` will return the proper mask for the given `"type"`. Available event mask constants: - • SDL\_ACTIVEEVENTMASK - • SDL\_KEYDOWNMASK - • SDL\_KEYUPMASK - • SDL\_KEYEVENTMASK - • SDL\_MOUSEMOTIONMASK - • SDL\_MOUSEBUTTONDOWNMASK - • SDL\_MOUSEBUTTONUPMASK - • SDL\_MOUSEEVENTMASK - • SDL\_JOYAXISMOTIONMASK - • SDL\_JOYBALLMOTIONMASK - • SDL\_JOYHATMOTIONMASK - • SDL\_JOYBUTTONDOWNMASK - • SDL\_JOYBUTTONUPMASK - • SDL\_JOYEVENTMASK - • SDL\_VIDEORESIZEMASK - • SDL\_VIDEOEXPOSEMASK - • SDL\_QUITMASK - • SDL\_SYSWMEVENTMASK This way you can check if a given `"type"` matches a mask: ``` (SDL_EVENTMASK(SDL_JOYBUTTONDOWN) & SDL_MOUSEEVENTMASK) # is false (SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN) & SDL_MOUSEEVENTMASK) # is true (SDL_EVENTMASK(SDL_MOUSEBUTTONUP) & SDL_MOUSEEVENTMASK) # is true (SDL_EVENTMASK(SDL_MOUSEMOTION) & SDL_MOUSEEVENTMASK) # is true # and also true is: (SDL_MOUSEEVENTMASK == SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN) | SDL_EVENTMASK(SDL_MOUSEBUTTONUP) | SDL_EVENTMASK(SDL_MOUSEMOTION)) ``` ### Application visibility events `"active"` is used when an event of type `"SDL_ACTIVEEVENT"` is reported. When the mouse leaves or enters the window area a `"SDL_APPMOUSEFOCUS"` type activation event occurs, if the mouse entered the window then **gain** will be 1, otherwise **gain** will be 0. A `"SDL_APPINPUTFOCUS"` type activation event occurs when the application loses or gains keyboard focus. This usually occurs when another application is made active. Finally, a `"SDL_APPACTIVE"` type event occurs when the application is either minimised/iconified (**gain**=0) or restored. A single event can have multiple values set in **state**. **Note:** This event does not occur when an application window is first created. A new ActiveEvent (to fake focus loss) will be created like this: ``` my $event = SDL::Event->new(); $event->type(SDL_ACTIVEEVENT); $event->active_gain(0); $event->active_state(SDL_APPMOUSEFOCUS); # I think this is wrong, ->active_type() should get SDL_APPMOUSEFOCUS, but what state gets? ``` *active\_gain* See `"active"`. 0 if the event is a loss or 1 if it is a gain. *active\_state* A bitmask of the following values: SDL\_APPMOUSEFOCUS if mouse focus was gained or lost, SDL\_APPINPUTFOCUS if input focus was gained or lost, and SDL\_APPACTIVE if the application was iconified (gain=0) or restored(gain=1). ### Keyboard events `"key"` is used when an event of type `"SDL_KEYDOWN"` or `"SDL_KEYUP"` is reported. The type and state actually report the same information, they just use different values to do it. A keyboard event generally occurs when a key is released (`"type=SDL_KEYUP"` or `"key_state=SDL_RELEASED"`) and when a key is pressed (`"type=SDL_KEYDOWN"` or `"key_state=SDL_PRESSED"`). The `"SDLK_CAPSLOCK"` and `"SDLK_NUMLOCK"` keys are special cases and report an `"SDL_KEYDOWN"` when first pressed, then an `"SDL_RELEASED"` when released and pressed again. For these keys `"KEYUP"` and `"KEYDOWN"` events are therefore analogous to the state of the caps lock and num lock LEDs rather than the keys themselves. These special cases are required for compatibility with Sun workstations. **Note:** Repeating `"SDL_KEYDOWN"` events will occur if key repeat is enabled (see SDL::Events::enable\_key\_repeat). *key\_state* `"SDL_PRESSED"` or `"SDL_RELEASED"` *key\_scancode* The `"scancode"` field should generally be left alone, it is the hardware-dependent scancode returned by the keyboard. *key\_sym* The `"sym"` field is extremely useful. It is the SDL-defined value of the key (see the keysym definitions in SDLKey). This field is very useful when you are checking for certain key presses, like so: ``` while(poll_event($event)) { switch($event->type) { case SDL_KEYDOWN: move_left() if($event->key_sym == SDLK_LEFT); break; . . . } } ``` *key\_mod* `"mod"` stores the current state of the keyboard modifiers as explained in SDL\_GetModState. *key\_unicode* The `"unicode"` field is only used when UNICODE translation is enabled with SDL::Events::enable\_unicode. If `"unicode"` is non-zero then this is the UNICODE character corresponding to the keypress. If the high 9 bits of the character are 0, then this maps to the equivalent ASCII character: ``` my $char; if(($event->key_unicode & 0xFF80) == 0) { $char = $event->key_unicode & 0x7F; } else { print("An International Character.\n"); } ``` UNICODE translation does create a slight overhead so don't enable it unless its needed. NOTE: Key release events (SDL\_KEYUP) won't necessarily (ever?) contain unicode information. See \ ### Mouse motion events Simply put, a SDL\_MOUSEMOTION type event occurs when a user moves the mouse within the application window or when SDL\_WarpMouse is called. Both the absolute (`"motion_x"` and `"motion_y"`) and relative (`"motion_xrel"` and `"motion_yrel"`) coordinates are reported along with the current button states (`"motion_state"`). *motion\_state* The button state can be interpreted using the `"SDL_BUTTON"` macro (see SDL::Events::get\_mouse\_state). *motion\_x, motion\_y* The X/Y coordinates of the mouse *motion\_xrel, motion\_yrel* Relative motion in the X/Y direction. If the cursor is hidden (**SDL\_ShowCursor**(0)) and the input is grabbed (SDL\_WM\_GrabInput(SDL\_GRAB\_ON)), then the mouse will give relative motion events even when the cursor reaches the edge of the screen. This is currently only implemented on Windows and Linux/Unix-alikes. ### Mouse button events When a mouse button press or release is detected, the number of the button pressed (from 1 to 255, with 1 usually being the left button and 2 the right) is placed into `"button_button"`. The position of the mouse when this event occurred is stored in the `"button_x"` and the `"button_y"` fields. Like a keyboard event, information on whether the event was a press or a release event is stored in both the `"button_type"` and `"button_state"` fields, but this should be obvious. Mouse wheel events are reported as buttons 4 (up) and 5 (down). Two events are generated i.e. you get a `"SDL_MOUSEBUTTONDOWN"` followed by a `"SDL_MOUSEBUTTONUP"` event. *button\_which* The input device index *button\_button* The mouse button index (`"SDL_BUTTON_LEFT"`, `"SDL_BUTTON_MIDDLE"`, `"SDL_BUTTON_RIGHT"`, `"SDL_BUTTON_WHEELUP"`, `"SDL_BUTTON_WHEELDOWN"`) *button\_state* `"SDL_PRESSED"` or `"SDL_RELEASED"` *button\_x, button\_y* The X/Y coordinates of the mouse at press/release time ### Joystick axis events A `"SDL_JOYAXISMOTION"` event occurs whenever a user moves an axis on the joystick. *jaxis\_which* The field `"jaxis_which"` is the index of the joystick that reported the event. *jaxis\_axis* The `"jaxis_axis"` is the index of the axis (for a more detailed explanation see the Joystick section). *jaxis\_value* `"jaxis_value"` is the current position of the axis (range: -32768 to 32767). ### Joystick button events A `"SDL_JOYBUTTONDOWN"` or `"SDL_JOYBUTTONUP"` event occurs when ever a user presses or releases a button on a joystick. *jbutton\_which* The field `"jbutton_which"` is the index of the joystick that reported the event. *jbutton\_button* The `"jbutton_button"` is the index of the button (for a more detailed explanation see the Joystick section). *jbutton\_state* `"jbutton_state"` is the current state of the button which is either `"jbutton_SDL_PRESSED"` or `"jbutton_SDL_RELEASED"`. ### Joystick hat events A `"SDL_JOYHATMOTION"` event occurs when ever a user moves a hat on the joystick. *jhat\_which* The field `"jhat_which"` is the index of the joystick that reported the event. *jhat\_hat* `"jhat_hat"` is the index of the hat (for a more detailed explanation see the Joystick section). *jhat\_value* `"jhat_value"` is the current position of the hat. It is a bitwise OR'd combination of the following values (whose meanings should be pretty obvious): - • `"SDL_HAT_CENTERED"` - • `"SDL_HAT_UP"` - • `"SDL_HAT_RIGHT"` - • `"SDL_HAT_DOWN"` - • `"SDL_HAT_LEFT"` The following defines are also provided: - • `"SDL_HAT_RIGHTUP"` - • `"SDL_HAT_RIGHTDOWN"` - • `"SDL_HAT_LEFTUP"` - • `"SDL_HAT_LEFTDOWN"` ### Joystick trackball events A `"SDL_JOYBALLMOTION"` event occurs when a user moves a trackball on the joystick. *jball\_which* The field `"jball_which"` is the index of the joystick that reported the event. *jball\_ball* `"jball_ball"` is the index of the trackball (for a more detailed explanation see the Joystick section). *jball\_xrel, jball\_yrel* Trackballs only return relative motion, this is the change in position on the ball since it was last polled (last cycle of the event loop) and it is stored in `"jball_xrel"` and `"jball_yrel"`. ### Window resize events *resize\_w, resize\_h* When `"SDL_RESIZABLE"` is passed as a flag to `"SDL_SetVideoMode"` the user is allowed to resize the applications window. When the window is resized an `"SDL_VIDEORESIZE"` is reported, with the new window width and height values stored in the resize structure's `"resize_w"` and `"resize_h"`. When an `"SDL_VIDEORESIZE"` is received the window should be resized to the new dimensions using SDL\_SetVideoMode. ### Window expose events A `"VIDEOEXPOSE"` event is triggered when the screen has been modified outside of the application, usually by the window manager and needs to be redrawn. ### System window manager events The system window manager event contains a system-specific information about unknown window manager events. If you enable this event using `"SDL_EventState"`, it will be generated whenever unhandled events are received from the window manager. This can be used, for example, to implement cut-and-paste in your application. If you want to obtain system-specific information about the window manager, you can fill in the version member of a SDL\_SysWMinfo structure (details can be found in SDL\_syswm.h, which must be included) using the **SDL\_VERSION()** macro found in SDL\_version.h, and pass it to the function: ``` int SDL_GetWMInfo(SDL_SysWMinfo *info); ``` See \ *syswm\_msg* ### User defined events This event is unique, it is never created by SDL but only by the user. The event can be pushed onto the event queue using `"SDL::Events::push_event"`. The contents of the structure members are completely up to the programmer, the only requirement is that type is a value from `"SDL_USEREVENT"` to `"SDL_NUMEVENTS-1"` (inclusive) ``` my $event = SDL::Event->new(); $event->type ( SDL_USEREVENT + 3 ); $event->user_code(10); $event->user_data1('hello event'); SDL::Events::push_event($event); ``` *user\_code* User defined event code (integer). *user\_data1, user\_data2* User defined data. ### Quit event As can be seen, the `"SDL_QuitEvent"` structure serves no useful purpose. The event itself, on the other hand, is very important. If you filter out or ignore a quit event then it is impossible for the user to close the window. On the other hand, if you do accept a quit event then the application window will be closed, and screen updates will still report success even though the application will no longer be visible. **Note**: The macro SDL\_QuitRequested will return non-zero if a quit event is pending ## AUTHORS See "AUTHORS" in SDL. ## SEE ALSO perl