Provided by: libsdl-perl_2.546-3build1_amd64 bug

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
       <http://lists.libsdl.org/pipermail/sdl-libsdl.org/2005-January/048355.html>

   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 <http://www.libsdl.org/cgi/docwiki.cgi/SDL_SysWMEvent>

       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