/lib/pods/SDL/Events.pod
http://github.com/PerlGameDev/SDL · Unknown · 584 lines · 366 code · 218 blank · 0 comment · 0 complexity · 7e08f8541623d8f36dccfb224d51491c MD5 · raw file
- =head1 NAME
- SDL::Events - Bindings to the Events Category in SDL API
- =head2 CATEGORY
- Core, Events
- =head1 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;
- ...
- }
- }
- =head1 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
- =head1 METHODS
- =head2 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 L</poll_event> and L</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.
- =head2 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:
- =over
- =item SDL_EVENTMASK (SDL_KEYUP)
- =item (SDL_EVENTMASK (SDL_MOUSEBUTTONDOWN) | SDL_EVENTMASK (SDL_MOUSEBUTTONUP))
-
- =item SDL_ALLEVENTS
-
- =item SDL_KEYUPMASK
-
- =item SDL_ALLEVENTS ^ SDL_QUITMASK
- =back
- =head3 RETURN
- Number of Events actually stored or -1 if there was an error
- =head2 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 L<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
- L<SDL::Video::set_video_mode|SDL::Video/"set_video_mode">.
- =head3 RETURN
- Returns 1 if there are any pending events, or 0 if there are none available.
- =head2 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.
- =head3 RETURN
- Returns 0 on success or -1 if the event couldn't be pushed.
- =head2 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
- L<SDL::Video::set_video_mode|SDL::Video/"set_video_mode">.
- =head3 RETURN
- 0 if there was an error while waiting for events, 1 otherwise
- =head2 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);
- =head3 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 B<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 L<SDL::Events::push_events|SDL::Events/"push_events"> or L<SDL::Events::peep_events|SDL::Events/"peep_events">
- do not get filtered.
- This callback may run in a different thread.
- =head2 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 L<SDL::Events::pump_events|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.
- =head2 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 );
- =head3 MOD VALUES
- =over
- =item KMOD_NONE
- =item KMOD_LSHIFT
- =item KMOD_RSHIFT
- =item KMOD_LCTRL
- =item KMOD_RCTRL
- =item KMOD_LALT
- =item KMOD_RALT
- =item KMOD_LMETA
- =item KMOD_RMETA
- =item KMOD_NUM
- =item KMOD_CAPS
- =item KMOD_MODE
- =item KMOD_CTRL
- same as KMOD_LCTRL|KMOD_RCTRL
- =item KMOD_SHIFT
- same as KMOD_LSHIFT|KMOD_RSHIFT
- =item KMOD_ALT
- same as KMOD_LALT|KMOD_RALT
- =item KMOD_META
- same as KMOD_LMETA|KMOD_RMETA
- =back
- =head2 set_mod_state
- Get the state of the modifier keys
- The inverse of L<SDL::Events::get_mod_state|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 L<SDL::Events::get_mod_state|SDL::Events/"get_mod_state"> for constants.
- SDL::Events::set_mod_state( $modstate );
- =head2 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 L<SDL::Event>
- =head3 STATES
- =over 4
- =item SDL_IGNORE
- The event of $type will be automatically dropper from the event queue and will not be filtered.
- =item SDL_ENABLE
- The event of $type will be processed normally. This is default.
- =item SDL_QUERY
- The current processing state of the $type will be returned
- =back
- =head2 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.
- =head2 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 L<SDL::Event::key_sym|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).
- =head2 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.
- =head2 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
- =head2 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
- =head2 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:
- =over
- =item SDL_APPMOUSEFOCUS
- Application has mouse focus
- warn 'mouse focus' if $app_state & SDL_APPMOUSEFOCUS
- =item SDL_APPINPUTFOCUS
- Application has keyboard focus
- warn 'keyboard focus' if $app_state & SDL_APPINPUTFOCUS
- =item SDL_APPACTIVE
- Application is visible
- warn 'Application Visible' if $app_state & SDL_APPACTIVE
- =back
- =head2 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 L<SDL::Joystick::update|SDL::Joystick/"update"> and read the joystick information manually. $state can be:
- =over
- =item SDL_QUERY
- =item SDL_ENABLE
- =item SDL_IGNORE
- Joystick event handling is default. Even if joystick event processing is enabled, individual joysticks must be opened before they generate events
- =back
- B<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.
- =head1 SEE ALSO
- L<SDL::Event>, L<SDL::Video>
- =head1 AUTHORS
- See L<SDL/AUTHORS>.