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

NAME

       SDL::Events - Bindings to the Events Category in SDL API

   CATEGORY
       Core, Events

SYNOPSIS

       Most likely you just want to know how to get events for you app.

         use SDL ':init';
         use SDL::Event;
         use SDL::Events ':all';

         SDL::init(SDL_INIT_VIDEO); # Event can only be grabbed in the same thread as this

         ...

         my $event = SDL::Event->new(); # notices 'Event' ne 'Events'

         while( 1 )
         {
             SDL::Events::pump_events();
             while(  SDL::Events::poll_event($event) )
             {
                 #check by event type
                 on_active() if $event->type == SDL_ACTIVEEVENT;
                 ...
             }
         }

CONSTANTS

       The constants are exported by default. You can avoid this by doing:

        use SDL::Events ();

       and access them directly:

        SDL::Events::SDL_ACTIVEEVENT;

       or by choosing the export tags below:

       Export tag: ':type'

        SDL_ACTIVEEVENT
        SDL_KEYDOWN
        SDL_KEYUP
        SDL_MOUSEMOTION
        SDL_MOUSEBUTTONDOWN
        SDL_MOUSEBUTTONUP
        SDL_JOYAXISMOTION
        SDL_JOYBALLMOTION
        SDL_JOYHATMOTION
        SDL_JOYBUTTONDOWN
        SDL_JOYBUTTONUP
        SDL_QUIT
        SDL_SYSWMEVENT
        SDL_VIDEORESIZE
        SDL_VIDEOEXPOSE
        SDL_USEREVENT
        SDL_NUMEVENTS

       Export tag: ':mask'

        SDL_EVENTMASK
        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
        SDL_ALLEVENTS

       Export tag: ':action'

        SDL_ADDEVENT
        SDL_PEEKEVENT
        SDL_GETEVENT

       Export tag: ':state'

        SDL_QUERY
        SDL_IGNORE
        SDL_DISABLE / SDL_ENABLE
        SDL_RELEASED / SDL_PRESSED

       Export tag: ':hat'

        SDL_HAT_CENTERED
        SDL_HAT_UP / SDL_HAT_RIGHT / SDL_HAT_DOWN / SDL_HAT_LEFT
        SDL_HAT_RIGHTUP / SDL_HAT_RIGHTDOWN / SDL_HAT_LEFTUP / SDL_HAT_LEFTDOWN

       Export tag: ':app'

        SDL_APPMOUSEFOCUS
        SDL_APPINPUTFOCUS
        SDL_APPACTIVE

       Export tag: ':button'

        SDL_BUTTON
        SDL_BUTTON_LEFT / SDL_BUTTON_MIDDLE / SDL_BUTTON_RIGHT
        SDL_BUTTON_WHEELUP / SDL_BUTTON_WHEELDOWN
        SDL_BUTTON_X1 / SDL_BUTTON_X2
        SDL_BUTTON_LMASK / SDL_BUTTON_MMASK / SDL_BUTTON_RMASK
        SDL_BUTTON_X1MASK / SDL_BUTTON_X2MASK

       Export tag: ':keysym'

        SDLK_UNKNOWN
        SDLK_FIRST
        SDLK_BACKSPACE
        SDLK_TAB
        SDLK_CLEAR
        SDLK_RETURN
        SDLK_PAUSE
        SDLK_ESCAPE
        SDLK_SPACE
        SDLK_EXCLAIM
        SDLK_QUOTEDBL
        SDLK_HASH
        SDLK_DOLLAR
        SDLK_AMPERSAND
        SDLK_QUOTE
        SDLK_LEFTPAREN / SDLK_RIGHTPAREN
        SDLK_ASTERISK
        SDLK_PLUS / SDLK_MINUS
        SDLK_COMMA
        SDLK_PERIOD
        SDLK_0 .. SDLK_9
        SDLK_COLON
        SDLK_SEMICOLON
        SDLK_LESS / SDLK_GREATER
        SDLK_EQUALS
        SDLK_QUESTION
        SDLK_AT
        SDLK_LEFTBRACKET / SDLK_RIGHTBRACKET
        SDLK_SLASH / SDLK_BACKSLASH
        SDLK_CARET
        SDLK_UNDERSCORE
        SDLK_BACKQUOTE
        SDLK_a .. SDLK_z
        SDLK_DELETE
        SDLK_WORLD_0 .. SDLK_WORLD_95
        SDLK_KP0 .. SDLK_KP9
        SDLK_KP_PERIOD
        SDLK_KP_DIVIDE / SDLK_KP_MULTIPLY
        SDLK_KP_MINUS / SDLK_KP_PLUS
        SDLK_KP_ENTER
        SDLK_KP_EQUALS
        SDLK_UP / SDLK_DOWN / SDLK_RIGHT / SDLK_LEFT
        SDLK_INSERT
        SDLK_HOME / SDLK_END
        SDLK_PAGEUP / SDLK_PAGEDOWN
        SDLK_F1 .. SDLK_F15
        SDLK_NUMLOCK / SDLK_CAPSLOCK / SDLK_SCROLLOCK
        SDLK_RSHIFT / SDLK_LSHIFT
        SDLK_RCTRL  / SDLK_LCTRL
        SDLK_RALT   / SDLK_LALT
        SDLK_RMETA  / SDLK_LMETA
        SDLK_LSUPER / SDLK_RSUPER
        SDLK_MODE
        SDLK_COMPOSE
        SDLK_HELP
        SDLK_PRINT
        SDLK_SYSREQ
        SDLK_BREAK
        SDLK_MENU
        SDLK_POWER
        SDLK_EURO
        SDLK_UNDO

       Export tag ':keymod'

        KMOD_NONE
        KMOD_LSHIFT / KMOD_RSHIFT / KMOD_SHIFT
        KMOD_LCTRL  / KMOD_RCTRL  / KMOD_CTRL
        KMOD_LALT   / KMOD_RALT   / KMOD_ALT
        KMOD_LMETA  / KMOD_RMETA  / KMOD_META
        KMOD_NUM
        KMOD_CAPS
        KMOD_MODE
        KMOD_RESERVED

METHODS

   pump_events
       Pumps the event loop, gathering events from the input devices.

               pump_events();

       pump_events gathers all the pending input information from devices and places it on the
       event queue. Without calls to pump_events no events would ever be placed on the queue.
       Often the need for calls to pump_events is hidden from the user since "poll_event" and
       "wait_event" implicitly call pump_events.  However, if you are not polling or waiting for
       events (e.g. you are filtering them), then you must call pump_events to force an event
       queue update.

   peep_events (event, num_events, action, mask)
       Checks the event queue for messages and optionally returns them.

               my $num_peep_events = SDL::Events::peep_events($event, 127, SDL_PEEKEVENT, SDL_ALLEVENTS);

       If action is SDL_ADDEVENT, up to num_events events will be added to the back of the event
       queue.

       If action is SDL_PEEKEVENT, up to num_events events at the front of the event queue,
       matching mask, will be returned and will not be removed from the queue.

       If action is SDL_GETEVENT, up to num_events events at the front of the event queue,
       matching mask, will be returned and will be removed from the queue.

       The mask parameter is a bitwise OR of SDL::Events::SDL_EVENTMASK(event_type), for all
       event types you are interested in

       This function is thread-safe.

       You may have to call pump_events before calling this function. Otherwise, the events may
       not be ready to be filtered when you call peep_events.

       Examples of mask:

       SDL_EVENTMASK (SDL_KEYUP)
       (SDL_EVENTMASK (SDL_MOUSEBUTTONDOWN) | SDL_EVENTMASK (SDL_MOUSEBUTTONUP))
       SDL_ALLEVENTS
       SDL_KEYUPMASK
       SDL_ALLEVENTS ^ SDL_QUITMASK

       RETURN

       Number of Events actually stored or -1 if there was an error

   poll_event($event)
       Polls for currently pending events.

       If $event is not NULL, the next event is removed from the queue and stored in the
       SDL::Event structure pointed to by $event.

       As this function implicitly calls pump_events, you can only call this function in the
       thread that set the video mode with SDL::Video::set_video_mode.

       RETURN

       Returns 1 if there are any pending events, or 0 if there are none available.

   push_event($event)
       Pushes an event onto the event queue

       The event queue can actually be used as a two way communication channel. Not only can
       events be read from the queue, but the user can also push their own events onto it. event
       is a pointer to the event structure you wish to push onto the queue.  The event is copied
       into the queue, and the caller may dispose of the memory pointed to after push_event
       returns.

       Note: Pushing device input events onto the queue doesn't modify the state of the device
       within SDL.

       This function is thread safe, and can be called from other threads safely.

       RETURN

       Returns 0 on success or -1 if the event couldn't be pushed.

   wait_event($event)
       Waits indefinitely for the next available $event, returning 0 if there was an error while
       waiting for events, 1 otherwise.

       If $event is not NULL, the next event is removed from the queue and stored in $event.

       As this function implicitly calls SDL_PumpEvents, you can only call this function in the
       thread that SDL::Video::set_video_mode.

       RETURN

       0 if there was an error while waiting for events, 1 otherwise

   set_event_filter
       Sets up a filter to process all events

               my $filter = sub { if($_[0]->type == SDL_ACTIVEEVENT){ return 0} else{ return 1; }};

               SDL::Events::set_event_filter($filter);

       PARAMETER

       set_event_filter takes a coderef that it checks all events again. The callback gets a
       event in the stack

               sub { my $event_to_test = shift; ...}

       to filter the event return a 0, to pass the filter return a 1.

       One Caveat is if you are filtering SDL_QUIT the event will be filtered if it is non-
       interrupt call ( Window closes normally ). If it is a interrupt SDL_QUIT it will be
       process on the next event poll.

       Events pushed onto to the queue with SDL::Events::push_events or SDL::Events::peep_events
       do not get filtered.

       This callback may run in a different thread.

   get_key_state
       Get a snapshot of the current keyboard state

               my $keys_ref = SDL::Events::get_key_state();

               print $keys_ref->[SDLK_RETURN]; # 1 if pressed , 0 if not pressed

       Use SDL::Events::pump_events to update the state array.

       This function gives you the current state after all events have been processed, so if a
       key or button has been pressed and released before you process events, then the pressed
       state will never show up in the get_key_state call.

       This function doesn't take into account whether shift has been pressed or not.

   get_mod_state
       Get the state of the modifier keys

       Returns the current state of modifier keys

       Return value is an OR'd combination of  KMOD_*

        SDL::Events::pump_events; #get latest mod_state in buffers

        my $mod_state = SDL::Events::get_mod_state();

        # Check which ones are pressed with

        # no mod pressed?

        print 'no_mod' if  ( $mod_state & KMOD_NONE );

        # CTRL or ALT

        print 'ctrl alt' if ($mod_state & KMOD_CTRL || $mod_state & KMOD_ALT );

       MOD VALUES

       KMOD_NONE
       KMOD_LSHIFT
       KMOD_RSHIFT
       KMOD_LCTRL
       KMOD_RCTRL
       KMOD_LALT
       KMOD_RALT
       KMOD_LMETA
       KMOD_RMETA
       KMOD_NUM
       KMOD_CAPS
       KMOD_MODE
       KMOD_CTRL
           same as KMOD_LCTRL|KMOD_RCTRL

       KMOD_SHIFT
           same as KMOD_LSHIFT|KMOD_RSHIFT

       KMOD_ALT
           same as KMOD_LALT|KMOD_RALT

       KMOD_META
           same as KMOD_LMETA|KMOD_RMETA

   set_mod_state
       Get the state of the modifier keys

       The inverse of SDL::Events::get_mod_state allows you to impose modifier key states on your
       application.

       Simply pass your desired modifier states into $modstate. This value can be a OR'd
       combination of any KMOD* constant.

        my $modstate = KMOD_LMETA | KMOD_LSHIFT;

       Any KMOD_* constant see SDL::Events::get_mod_state for constants.
        SDL::Events::set_mod_state( $modstate );

   event_state
       Allows you to set the state of processing certain events

        SDL::Events::event_state( $type, $state );

       A list of $type(s) can be found in SDL::Event

       STATES

       SDL_IGNORE
           The event of $type will be automatically dropper from the event queue and will not be
           filtered.

       SDL_ENABLE
           The event of $type will be processed normally. This is default.

       SDL_QUERY
           The current processing state of the $type will be returned

   get_key_name
       Gets the name of the a SDL virtual keysym

        my $event = SDL::Event->new();

        while( SDL::Events::poll_event($event) )
        {
          my $key = $event->key_sym;
          $key_str = SDL::Events::get_key_name($key);
        }

       Returns a string with the name of the key sym.

   enable_unicode
       Enable/Disable UNICODE translation

         my $previous_translation_mode = SDL::Events::enable_unicode( 1 ); #enable
            $previous_translation_mode = SDL::Events::enable_unicode( 0 ); #disables

       To obtain the character codes corresponding to received keyboard events, Unicode
       translation must first be turned on using this function. The translation incurs a slight
       overhead for each keyboard event and is therefore disabled by default. For each
       subsequently received key down event, the unicode member of the SDL::Event::key_sym
       provided structure will be then contain the corresponding character code, or otherwise
       zero.

       A value of 1 for enabling, 0 for disabling and -1 for unchanged. -1 is useful for querying
       the current translation mode.

       Only key press events will be translated not release events.

       Returns the previous translation mode as (1,0).

   enable_key_repeat
       Sets keyboard repeat rate

        my $success = SDL::Events::enable_key_repeat( $delay, $interval );

       Enables or disables the keyboard repeat rate. $delay specifies how long the key must be
       pressed before it begins repeating, it then repeats at the speed specified by $interval.
       Both $delay and $interval are expressed in milliseconds.

       Setting $delay to 0 disables key repeating completely. Good default values are
       SDL_DEFAULT_REPEAT_DELAY and SDL_DEFAULT_REPEAT_INTERVAL.

       Return 0 on success and -1 on fail.

   get_mouse_state
       Retrieves the current state of the mouse

         my ($mask,$x,$y) = @{ SDL::Events::get_mouse_state( ) };

         print 'Button Left pressed' if ($mask & SDL_BUTTON_LMASK);

         print 'Button Right pressed' if ($mask & SDL_BUTTON_RMASK);

         print 'Button Middle pressed' if ($mask & SDL_BUTTON_MMASK);

         print $x.','.$y;

       The current button state is returned as a button $bitmask, which can be tested using the
       the above constants

   get_relative_mouse_state
       Retrieves the current relative state of the mouse

         my ($mask,$x,$y) = @{ SDL::Events::get_mouse_state( ) };

         print 'Button Left pressed' if ($mask & SDL_BUTTON_LMASK);

         print 'Button Right pressed' if ($mask & SDL_BUTTON_RMASK);

         print 'Button Middle pressed' if ($mask & SDL_BUTTON_MMASK);

         print $x.','.$y; # this is relative to the last position of the mouse

       The current button state is returned as a button $bitmask, which can be tested using the
       the above constants

   get_app_state
       Gets the state of the application

               my $app_state = SDL::Events::get_app_state();

       The $app_state is a bitwise combination of:

       SDL_APPMOUSEFOCUS
           Application has mouse focus

                   warn 'mouse focus' if $app_state & SDL_APPMOUSEFOCUS

       SDL_APPINPUTFOCUS
           Application has keyboard focus

                   warn 'keyboard focus' if $app_state & SDL_APPINPUTFOCUS

       SDL_APPACTIVE
           Application is visible

                   warn 'Application Visible' if $app_state & SDL_APPACTIVE

   joystick_event_state
       Enable/disable joystick event polling

               my $status = SDL::Events::joystick_event_state( $state );

       This function is used to enable or disable joystick event processing. With joystick event
       processing disabled you will have to update joystick states with SDL::Joystick::update and
       read the joystick information manually. $state can be:

       SDL_QUERY
       SDL_ENABLE
       SDL_IGNORE
           Joystick event handling is default. Even if joystick event processing is enabled,
           individual joysticks must be opened before they generate events

       Warning: Calling this function may delete all events currently in SDL's event queue.

       If $state is SDL_QUERY then the current state is returned, otherwise the new processing
       state is returned.

SEE ALSO

       SDL::Event, SDL::Video

AUTHORS

       See "AUTHORS" in SDL.