[sdlgit/SDL-Site.git] / pages / SDL-Events.html-inc

<div class="pod">
<!-- INDEX START -->
<h3 id="TOP">Index</h3>

<ul><li><a href="#NAME">NAME</a>
<ul><li><a href="#CATEGORY">CATEGORY</a></li>
</ul>
</li>
<li><a href="#SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#DESCRIPTION">DESCRIPTION</a></li>
<li><a href="#METHODS">METHODS</a>
<ul><li><a href="#pump_events">pump_events</a></li>
<li><a href="#peep_events_event_num_events_action_">peep_events (event, num_events, action, mask) </a>
<ul><li><a href="#RETURN">RETURN</a></li>
</ul>
</li>
<li><a href="#poll_event_event">poll_event($event)</a>
<ul><li><a href="#RETURN-2">RETURN</a></li>
</ul>
</li>
<li><a href="#push_event_event">push_event($event)</a>
<ul><li><a href="#RETURN-3">RETURN</a></li>
</ul>
</li>
<li><a href="#wait_event_event">wait_event($event)</a>
<ul><li><a href="#RETURN-4">RETURN</a></li>
</ul>
</li>
<li><a href="#set_event_filter">set_event_filter</a>
<ul><li><a href="#PARAMETER">PARAMETER</a></li>
</ul>
</li>
<li><a href="#get_key_state">get_key_state</a></li>
<li><a href="#get_mod_state">get_mod_state</a>
<ul><li><a href="#MOD_VALUES">MOD VALUES</a></li>
</ul>
</li>
<li><a href="#set_mod_state">set_mod_state</a></li>
<li><a href="#event_state">event_state </a>
<ul><li><a href="#STATES">STATES</a></li>
</ul>
</li>
<li><a href="#get_key_name">get_key_name</a></li>
<li><a href="#enable_unicode">enable_unicode </a></li>
<li><a href="#enable_key_repeat">enable_key_repeat </a></li>
<li><a href="#get_mouse_state">get_mouse_state </a></li>
<li><a href="#get_relative_mouse_state">get_relative_mouse_state </a></li>
<li><a href="#get_app_state">get_app_state </a></li>
<li><a href="#joystick_event_state">joystick_event_state </a></li>
</ul>
</li>
<li><a href="#SEE_ALSO">SEE ALSO</a>
</li>
</ul><hr />
<!-- INDEX END -->

<h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="NAME_CONTENT">
<p>SDL::Events - Bindings to the Events Category in SDL API</p>

</div>
<h2 id="CATEGORY">CATEGORY</h2>
<div id="CATEGORY_CONTENT">
<p>Core, Events</p>

</div>
<h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="SYNOPSIS_CONTENT">
<p>Most likely you just want to know how to get events for you app.</p>
<pre>  use SDL;
  use SDL::Event;
  use SDL::Events;

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

  ...

  my $event = SDL::Event-&gt;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-&gt;type == SDL_ACTIVEEVENT; 
		...
	 }
	}

</pre>

</div>
<h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="DESCRIPTION_CONTENT">


</div>
<h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="METHODS_CONTENT">

</div>
<h2 id="pump_events">pump_events</h2>
<div id="pump_events_CONTENT">
<p>Pumps the event loop, gathering events from the input devices.</p>
<pre>	pump_events();

</pre>
<p>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 <a href="http://search.cpan.org/perldoc?poll_event">poll_event</a> and <a href="http://search.cpan.org/perldoc?wait_event">wait_event</a> 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.</p>


</div>
<h2 id="peep_events_event_num_events_action_">peep_events (event, num_events, action, mask) </h2>
<div id="peep_events_event_num_events_action_-2">
<p>Checks the event queue for messages and optionally returns them.  </p>
<pre>	my $num_peep_events = SDL::Events::peep_events($event, 127, SDL_PEEKEVENT, SDL_ALLEVENTS);

</pre>
<p>If action is SDL_ADDEVENT, up to numevents events will be added to the back of the event queue.</p>
<p>If action is SDL_PEEKEVENT, up to numevents events at the front of the event queue, matching mask, will be returned and will not be removed from the queue.</p>
<p>If action is SDL_GETEVENT, up to numevents events at the front of the event queue, matching mask, will be returned and will be removed from the queue.</p>
<p>The mask parameter is a bitwise OR of SDL::Events::SDL_EVENTMASK(event_type), for all event types you are interested in</p>
<p>This function is thread-safe.</p>
<p>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.</p>
<p>Examples of mask:</p>
<dl>
	<dt>SDL_EVENTMASK (SDL_KEYUP)</dt>
	<dt>(SDL_EVENTMASK (SDL_MOUSEBUTTONDOWN) | SDL_EVENTMASK (SDL_MOUSEBUTTONUP))</dt>
	<dt>SDL_ALLEVENTS</dt>
	<dt>SDL_KEYUPMASK</dt>
	<dt>SDL_ALLEVENTS ^ SDL_QUITMASK</dt>
</dl>

</div>
<h3 id="RETURN">RETURN</h3>
<div id="RETURN_CONTENT">
<p>Number of Events actually stored or -1 if there was an error</p>

</div>
<h2 id="poll_event_event">poll_event($event)</h2>
<div id="poll_event_event_CONTENT">
<p>Polls for currently pending events. </p>
<p>If $event is not NULL, the next event is removed from the queue and stored in the <a href="SDL-Event.html">SDL::Event</a> structure pointed to by $event.</p>
<p>As this function implicitly calls pump_events, you can only call this function in the thread that set the video mode with <a href="/SDL-Video.html#set_video_mode">SDL::Video::set_video_mode</a>. </p>

</div>
<h3 id="RETURN-2">RETURN</h3>
<div id="RETURN_CONTENT-2">
<p>Returns 1 if there are any pending events, or 0 if there are none available. </p>

</div>
<h2 id="push_event_event">push_event($event)</h2>
<div id="push_event_event_CONTENT">
<p>Pushes an event onto the event queue </p>
<p>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.</p>
<p>Note: Pushing device input events onto the queue doesn't modify the state of the device within SDL. </p>
<p>This function is thread safe, and can be called from other threads safely.</p>

</div>
<h3 id="RETURN-3">RETURN</h3>
<div id="RETURN_CONTENT-3">
<p>Returns 0 on success or -1 if the event couldn't be pushed.</p>

</div>
<h2 id="wait_event_event">wait_event($event)</h2>
<div id="wait_event_event_CONTENT">
<p>Waits indefinitely for the next available $event, returning 0 if there was an error while waiting for events, 1 otherwise.</p>
<p>If $event is not NULL, the next event is removed from the queue and stored in $event.</p>
<p>As this function implicitly calls SDL_PumpEvents, you can only call this function in the thread that  <a href="/SDL-Video.html#set_video_mode">SDL::Video::set_video_mode</a>.  </p>

</div>
<h3 id="RETURN-4">RETURN</h3>
<div id="RETURN_CONTENT-4">
<p>0 if there was an error while waiting for events, 1 otherwise</p>

</div>
<h2 id="set_event_filter">set_event_filter</h2>
<div id="set_event_filter_CONTENT">
<p>Sets up a filter to process all events </p>
<pre>	my $filter = sub { if($_[0]-&gt;type == SDL_ACTIVEEVENT){ return 0} else{ return 1; }};

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

</pre>

</div>
<h3 id="PARAMETER">PARAMETER</h3>
<div id="PARAMETER_CONTENT">
<p>set_event_filter takes a coderef that it checks all events again. The callback gets a event in the stack</p>
<pre>	sub { my $event_to_test = shift; ...}

</pre>
<p>to filter the event return a 0, to pass the filter return a 1. </p>
<p>One <strong>Caveat</strong> is if you are filterign SDL_QUITEVENT the event will be filtered if it is non-intterupt call ( Window closes normally ). If it is a interrupt SDL_QUITEVENT it will be process on the next event poll. </p>
<p>Events pushed onto to the queue with <a href="/SDL-Events.html#push_events">SDL::Events::push_events</a> or <a href="/SDL-Events.html#peep_events">SDL::Events::peep_events</a> do not get filtered.</p>
<p>This callback may run in a different thread. </p>

</div>
<h2 id="get_key_state">get_key_state</h2>
<div id="get_key_state_CONTENT">
<p>Get a snapshot of the current keyboard state</p>
<pre>	my $keys_ref = SDL::Events::get_key_state();

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

</pre>
<p>Use <a href="/SDL-Events.html#pump_events">SDL::Events::pump_events</a> to update the state array.</p>
<p>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.</p>
<p>This function doesn't take into account whether shift has been pressed or not.</p>

</div>
<h2 id="get_mod_state">get_mod_state</h2>
<div id="get_mod_state_CONTENT">
<p>Get the state of the modifier keys</p>
<p>Returns the current state of modifier keys</p>
<p>Return value is an OR'd combination of  KMOD_*</p>
<pre> 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 &amp; KMOD_NONE );

 # CTRL or ALT 

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

</pre>

</div>
<h3 id="MOD_VALUES">MOD VALUES</h3>
<div id="MOD_VALUES_CONTENT">
<dl>
	<dt>KMOD_NONE</dt>
	<dt>KMOD_LSHIFT</dt>
	<dt>KMOD_RSHIFT</dt>
	<dt>KMOD_LCTRL</dt>
	<dt>KMOD_RCTRL</dt>
	<dt>KMOD_LALT</dt>
	<dt>KMOD_RALT</dt>
	<dt>KMOD_LMETA</dt>
	<dt>KMOD_RMETA</dt>
	<dt>KMOD_NUM</dt>
	<dt>KMOD_CAPS</dt>
	<dt>KMOD_MODE</dt>
	<dt>KMOD_CTRL </dt>
	<dd>
		<p>same as KMOD_LCTRL|KMOD_RCTRL</p>
	</dd>
	<dt>KMOD_SHIFT</dt>
	<dd>
		<p>same as KMOD_LSHIFT|KMOD_RSHIFT</p>
	</dd>
	<dt>KMOD_ALT</dt>
	<dd>
		<p>same as KMOD_LALT|KMOD_RALT</p>
	</dd>
	<dt>KMOD_META</dt>
	<dd>
		<p>same as KMOD_LMETA|KMOD_RMETA</p>
	</dd>
</dl>

</div>
<h2 id="set_mod_state">set_mod_state</h2>
<div id="set_mod_state_CONTENT">
<p>Get the state of the modifier keys</p>
<p>The inverse of <a href="/SDL-Events.html#get_mod_state">SDL::Events::get_mod_state</a> allows you to impose modifier key states on your application.</p>
<p>Simply pass your desired modifier states into $modstate. This value can be a OR'd combination of any KMOD* constant.</p>
<pre> my $modstate = KMOD_LMETA | KMOD_LSHIFT;

</pre>
<p>Any KMOD_* constant see <a href="/SDL-Events.html#get_mod_state">SDL::Events::get_mod_state</a> for constants.
 SDL::Events::set_mod_state( $modstate );</p>

</div>
<h2 id="event_state">event_state </h2>
<div id="event_state_CONTENT">
<p>Allows you to set the state of processing certain events</p>
<pre> SDL::Events::event_state( $type, $state );

</pre>
<p>A list of $type(s) can be found in <a href="SDL-Event.html">SDL::Event</a></p>

</div>
<h3 id="STATES">STATES</h3>
<div id="STATES_CONTENT">
<dl>
	<dt>SDL_IGNORE</dt>
	<dd>
		<p>The event of $type will be automatically dropper from the event queue and will not be filtered.</p>
	</dd>
	<dt>SDL_ENABLE</dt>
	<dd>
		<p>The event of $type will be processed normally. This is default.</p>
	</dd>
	<dt>SDL_QUERY</dt>
	<dd>
		<p>The current processing state of the $type will be returned</p>
	</dd>
</dl>

</div>
<h2 id="get_key_name">get_key_name</h2>
<div id="get_key_name_CONTENT">
<p>Gets the name of the a SDL virtual keysym</p>
<pre> my $event = SDL::Event-&gt;new();

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

</pre>
<p>Returns a string with the name of the key sym.</p>

</div>
<h2 id="enable_unicode">enable_unicode </h2>
<div id="enable_unicode_CONTENT">
<p>Enable/Disable UNICODE translation</p>
<pre>  my $previous_translation_mode = SDL::Events::enable_unicode( 1 ); #enable
     $previous_translation_mode = SDL::Events::enable_unicode( 0 ); #disables

</pre>
<p>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 recieved key down event, the unicode member of the <a href="/SDL-Event.html#key_sym">SDL::Event::key_sym</a> provided structure will be then contain the corresponding character code, or otherwise zero.</p>
<p>A value of 1 for enabling, 0 for disabling and -1 for unchanged. -1 is usefull for querying the current translation mode.</p>
<p>Only key press events will be translated not release events.</p>
<p>Returns the previous translation mode as (1,0).</p>

</div>
<h2 id="enable_key_repeat">enable_key_repeat </h2>
<div id="enable_key_repeat_CONTENT">
<p>Sets keyboard repeat rate</p>
<pre> my $success = SDL::Events::enable_key_repeat( $delay, $interval );

</pre>
<p>Enables or disables the keyboard repeat rate. $delay specifies how long the key must be pressed before it begins repeating, it then repleats at the speed specified by $interval. Both $delay and $interval are expressed in milliseconds.</p>
<p>Setting $delay to 0 disables key repeating completely. Good default values are SDL_DEFAULT_REPEAT_DELAY and SDL_DEFAULT_REPEAT_INTERVAL.</p>
<p>Return 0 on success and -1 on fail.</p>

</div>
<h2 id="get_mouse_state">get_mouse_state </h2>
<div id="get_mouse_state_CONTENT">
<p>Retrives the current state of the mouse</p>
<pre>	my ($mask,$x,$y) = @{ SDL::Events::get_mouse_state( ) };

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

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

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

        print $x.','.$y;

</pre>
<p>The current button state is returned as a button $bitmask, which can be tested using the the above constants </p>

</div>
<h2 id="get_relative_mouse_state">get_relative_mouse_state </h2>
<div id="get_relative_mouse_state_CONTENT">
<p>Retrives the current relative state of the mouse</p>
<pre>	my ($mask,$x,$y) = @{ SDL::Events::get_mouse_state( ) };

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

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

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

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

</pre>
<p>The current button state is returned as a button $bitmask, which can be tested using the the above constants </p>


</div>
<h2 id="get_app_state">get_app_state </h2>
<div id="get_app_state_CONTENT">
<p>Gets the state of the application</p>
<pre>	my $app_state = SDL::Events::get_app_state();

</pre>
<p>The $app_state is a bitwise combination of:</p>
<dl>
	<dt>SDL_APPMOUSEFOCUS</dt>
	<dd>
		<p>Application has mouse focus</p>
<pre>	warn 'mouse focus' if $app_state &amp; SDL_APPMOUSEFOCUS

</pre>
	</dd>
	<dt>SDL_APPINPUTFOCUS</dt>
	<dd>
		<p>Application has keyboard focus</p>
<pre>	warn 'keyboard focus' if $app_state &amp; SDL_APPINPUTFOCUS


</pre>
	</dd>
	<dt>SDL_APPACTIVE</dt>
	<dd>
		<p>Application is visible</p>
<pre>	warn 'Application Visible' if $app_state &amp; SDL_APPACTIVE


</pre>

</div>
<h2 id="joystick_event_state">joystick_event_state </h2>
<div id="joystick_event_state_CONTENT">
		<p>Enable/disable joystick event polling</p>
<pre>	my $status = SDL::Events::joystick_event_state( $state );

</pre>
		<p>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_JoystickUpdate and read the joystick information manually. $state can be:</p>
	</dd>
	<dt>SDL_QUERY</dt>
	<dt>SDL_ENABLE </dt>
	<dt>SDL_IGNORE</dt>
	<dd>
		<p>Joystick event handling is default. Even if joystick event processing is enabled, individual joysticks must be opened before they generate events</p>
	</dd>
</dl>
<p><strong>Warning:</strong> Calling this function may delete all events currently in SDL's event queue.</p>
<p>If $state is SDL_QUERY then the current state is returned, otherwise the new processing state is returned.</p>

</div>
<h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="SEE_ALSO_CONTENT">
<p><a href="SDL-Event.html">SDL::Event</a>, <a href="SDL-Video.html">SDL::Video</a>
</p>

</div>
</div>
Commit	Line	Data
162a0989	1	<div class="pod">
	2	<!-- INDEX START -->
	3	<h3 id="TOP">Index</h3>
	4
60f74f6f	5	<ul><li><a href="#NAME">NAME</a>
	6	<ul><li><a href="#CATEGORY">CATEGORY</a></li>
	7	</ul>
	8	</li>
162a0989	9	<li><a href="#SYNOPSIS">SYNOPSIS</a></li>
	10	<li><a href="#DESCRIPTION">DESCRIPTION</a></li>
	11	<li><a href="#METHODS">METHODS</a>
	12	<ul><li><a href="#pump_events">pump_events</a></li>
	13	<li><a href="#peep_events_event_num_events_action_">peep_events (event, num_events, action, mask) </a>
	14	<ul><li><a href="#RETURN">RETURN</a></li>
	15	</ul>
	16	</li>
	17	<li><a href="#poll_event_event">poll_event($event)</a>
	18	<ul><li><a href="#RETURN-2">RETURN</a></li>
	19	</ul>
	20	</li>
	21	<li><a href="#push_event_event">push_event($event)</a>
	22	<ul><li><a href="#RETURN-3">RETURN</a></li>
	23	</ul>
	24	</li>
	25	<li><a href="#wait_event_event">wait_event($event)</a>
	26	<ul><li><a href="#RETURN-4">RETURN</a></li>
	27	</ul>
	28	</li>
55bbf7a2	29	<li><a href="#set_event_filter">set_event_filter</a>
	30	<ul><li><a href="#PARAMETER">PARAMETER</a></li>
	31	</ul>
	32	</li>
cf23a5da	33	<li><a href="#get_key_state">get_key_state</a></li>
55bbf7a2	34	<li><a href="#get_mod_state">get_mod_state</a>
	35	<ul><li><a href="#MOD_VALUES">MOD VALUES</a></li>
	36	</ul>
	37	</li>
cf23a5da	38	<li><a href="#set_mod_state">set_mod_state</a></li>
55bbf7a2	39	<li><a href="#event_state">event_state </a>
	40	<ul><li><a href="#STATES">STATES</a></li>
	41	</ul>
	42	</li>
cf23a5da	43	<li><a href="#get_key_name">get_key_name</a></li>
	44	<li><a href="#enable_unicode">enable_unicode </a></li>
	45	<li><a href="#enable_key_repeat">enable_key_repeat </a></li>
	46	<li><a href="#get_mouse_state">get_mouse_state </a></li>
	47	<li><a href="#get_relative_mouse_state">get_relative_mouse_state </a></li>
	48	<li><a href="#get_app_state">get_app_state </a></li>
	49	<li><a href="#joystick_event_state">joystick_event_state </a></li>
162a0989	50	</ul>
	51	</li>
	52	<li><a href="#SEE_ALSO">SEE ALSO</a>
	53	</li>
	54	</ul><hr />
	55	<!-- INDEX END -->
	56
	57	<h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
	58	<div id="NAME_CONTENT">
	59	<p>SDL::Events - Bindings to the Events Category in SDL API</p>
	60
	61	</div>
60f74f6f	62	<h2 id="CATEGORY">CATEGORY</h2>
	63	<div id="CATEGORY_CONTENT">
	64	<p>Core, Events</p>
	65
	66	</div>
162a0989	67	<h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p>
162a0989	68	<div id="SYNOPSIS_CONTENT">
55bbf7a2	69	<p>Most likely you just want to know how to get events for you app.</p>
55bbf7a2	70	<pre> use SDL;
162a0989	71	use SDL::Event;
55bbf7a2	72	use SDL::Events;
	73
	74	SDL::init(SDL_INIT_VIDEO); # Event can only be grabbed in the same thread as this
162a0989	75
	76	...
	77
	78	my $event = SDL::Event->new(); # notices 'Event' ne 'Events'
	79
	80	while( 1 )
	81	{
	82	SDL::Events::pump_events();
	83	while( SDL::Events::poll_event($event) )
	84	{
	85	#check by event type
	86	on_active() if $event->type == SDL_ACTIVEEVENT;
	87	...
	88	}
	89	}
	90
	91	</pre>
	92
	93	</div>
	94	<h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p>
	95	<div id="DESCRIPTION_CONTENT">
	96
	97
	98
	99
	100
	101	</div>
	102	<h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
	103	<div id="METHODS_CONTENT">
	104
	105	</div>
	106	<h2 id="pump_events">pump_events</h2>
	107	<div id="pump_events_CONTENT">
	108	<p>Pumps the event loop, gathering events from the input devices.</p>
	109	<pre> pump_events();
	110
	111	</pre>
	112	<p>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.
46beffd8	113	Often the need for calls to pump_events is hidden from the user since <a href="http://search.cpan.org/perldoc?poll_event">poll_event</a> and <a href="http://search.cpan.org/perldoc?wait_event">wait_event</a> implicitly call pump_events.
162a0989	114	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.</p>
	115
	116
	117
	118
	119
	120	</div>
	121	<h2 id="peep_events_event_num_events_action_">peep_events (event, num_events, action, mask) </h2>
	122	<div id="peep_events_event_num_events_action_-2">
	123	<p>Checks the event queue for messages and optionally returns them. </p>
	124	<pre> my $num_peep_events = SDL::Events::peep_events($event, 127, SDL_PEEKEVENT, SDL_ALLEVENTS);
	125
	126	</pre>
	127	<p>If action is SDL_ADDEVENT, up to numevents events will be added to the back of the event queue.</p>
	128	<p>If action is SDL_PEEKEVENT, up to numevents events at the front of the event queue, matching mask, will be returned and will not be removed from the queue.</p>
	129	<p>If action is SDL_GETEVENT, up to numevents events at the front of the event queue, matching mask, will be returned and will be removed from the queue.</p>
	130	<p>The mask parameter is a bitwise OR of SDL::Events::SDL_EVENTMASK(event_type), for all event types you are interested in</p>
	131	<p>This function is thread-safe.</p>
	132	<p>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.</p>
	133	<p>Examples of mask:</p>
	134	<dl>
	135	<dt>SDL_EVENTMASK (SDL_KEYUP)</dt>
	136	<dt>(SDL_EVENTMASK (SDL_MOUSEBUTTONDOWN) \| SDL_EVENTMASK (SDL_MOUSEBUTTONUP))</dt>
	137	<dt>SDL_ALLEVENTS</dt>
	138	<dt>SDL_KEYUPMASK</dt>
	139	<dt>SDL_ALLEVENTS ^ SDL_QUITMASK</dt>
	140	</dl>
	141
	142	</div>
	143	<h3 id="RETURN">RETURN</h3>
	144	<div id="RETURN_CONTENT">
	145	<p>Number of Events actually stored or -1 if there was an error</p>
	146
	147	</div>
	148	<h2 id="poll_event_event">poll_event($event)</h2>
	149	<div id="poll_event_event_CONTENT">
	150	<p>Polls for currently pending events. </p>
55bbf7a2	151	<p>If $event is not NULL, the next event is removed from the queue and stored in the <a href="SDL-Event.html">SDL::Event</a> structure pointed to by $event.</p>
92e293d6	152	<p>As this function implicitly calls pump_events, you can only call this function in the thread that set the video mode with <a href="/SDL-Video.html#set_video_mode">SDL::Video::set_video_mode</a>. </p>
162a0989	153
	154	</div>
	155	<h3 id="RETURN-2">RETURN</h3>
	156	<div id="RETURN_CONTENT-2">
	157	<p>Returns 1 if there are any pending events, or 0 if there are none available. </p>
	158
	159	</div>
	160	<h2 id="push_event_event">push_event($event)</h2>
	161	<div id="push_event_event_CONTENT">
	162	<p>Pushes an event onto the event queue </p>
	163	<p>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.
	164	The event is copied into the queue, and the caller may dispose of the memory pointed to after push_event returns.</p>
	165	<p>Note: Pushing device input events onto the queue doesn't modify the state of the device within SDL. </p>
	166	<p>This function is thread safe, and can be called from other threads safely.</p>
	167
	168	</div>
	169	<h3 id="RETURN-3">RETURN</h3>
	170	<div id="RETURN_CONTENT-3">
	171	<p>Returns 0 on success or -1 if the event couldn't be pushed.</p>
	172
	173	</div>
	174	<h2 id="wait_event_event">wait_event($event)</h2>
	175	<div id="wait_event_event_CONTENT">
	176	<p>Waits indefinitely for the next available $event, returning 0 if there was an error while waiting for events, 1 otherwise.</p>
	177	<p>If $event is not NULL, the next event is removed from the queue and stored in $event.</p>
92e293d6	178	<p>As this function implicitly calls SDL_PumpEvents, you can only call this function in the thread that <a href="/SDL-Video.html#set_video_mode">SDL::Video::set_video_mode</a>. </p>
162a0989	179
	180	</div>
	181	<h3 id="RETURN-4">RETURN</h3>
	182	<div id="RETURN_CONTENT-4">
	183	<p>0 if there was an error while waiting for events, 1 otherwise</p>
	184
	185	</div>
cf23a5da	186	<h2 id="set_event_filter">set_event_filter</h2>
cf23a5da	187	<div id="set_event_filter_CONTENT">
55bbf7a2	188	<p>Sets up a filter to process all events </p>
	189	<pre> my $filter = sub { if($_[0]->type == SDL_ACTIVEEVENT){ return 0} else{ return 1; }};
	190
	191	SDL::Events::set_event_filter($filter);
	192
	193	</pre>
	194
	195	</div>
	196	<h3 id="PARAMETER">PARAMETER</h3>
	197	<div id="PARAMETER_CONTENT">
	198	<p>set_event_filter takes a coderef that it checks all events again. The callback gets a event in the stack</p>
	199	<pre> sub { my $event_to_test = shift; ...}
	200
	201	</pre>
	202	<p>to filter the event return a 0, to pass the filter return a 1. </p>
	203	<p>One <strong>Caveat</strong> is if you are filterign SDL_QUITEVENT the event will be filtered if it is non-intterupt call ( Window closes normally ). If it is a interrupt SDL_QUITEVENT it will be process on the next event poll. </p>
	204	<p>Events pushed onto to the queue with <a href="/SDL-Events.html#push_events">SDL::Events::push_events</a> or <a href="/SDL-Events.html#peep_events">SDL::Events::peep_events</a> do not get filtered.</p>
	205	<p>This callback may run in a different thread. </p>
cf23a5da	206
	207	</div>
	208	<h2 id="get_key_state">get_key_state</h2>
	209	<div id="get_key_state_CONTENT">
55bbf7a2	210	<p>Get a snapshot of the current keyboard state</p>
	211	<pre> my $keys_ref = SDL::Events::get_key_state();
	212
	213	print $keys_ref->[SDLK_RETURN]; # 1 if pressed , 0 if not pressed
	214
	215	</pre>
	216	<p>Use <a href="/SDL-Events.html#pump_events">SDL::Events::pump_events</a> to update the state array.</p>
	217	<p>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.</p>
	218	<p>This function doesn't take into account whether shift has been pressed or not.</p>
cf23a5da	219
	220	</div>
	221	<h2 id="get_mod_state">get_mod_state</h2>
	222	<div id="get_mod_state_CONTENT">
55bbf7a2	223	<p>Get the state of the modifier keys</p>
	224	<p>Returns the current state of modifier keys</p>
	225	<p>Return value is an OR'd combination of KMOD_*</p>
	226	<pre> SDL::Events::pump_events; #get latest mod_state in buffers
	227
	228	my $mod_state = SDL::Events::get_mod_state();
	229
	230	# Check which ones are pressed with
	231
	232	# no mod pressed?
	233
	234	print 'no_mod' if ( $mod_state & KMOD_NONE );
	235
	236	# CTRL or ALT
	237
	238	print 'ctrl alt' if ($mod_state & KMOD_CTRL \|\| $mod_state & KMOD_ALT );
	239
	240	</pre>
	241
	242	</div>
	243	<h3 id="MOD_VALUES">MOD VALUES</h3>
	244	<div id="MOD_VALUES_CONTENT">
	245	<dl>
	246	<dt>KMOD_NONE</dt>
	247	<dt>KMOD_LSHIFT</dt>
	248	<dt>KMOD_RSHIFT</dt>
	249	<dt>KMOD_LCTRL</dt>
	250	<dt>KMOD_RCTRL</dt>
	251	<dt>KMOD_LALT</dt>
	252	<dt>KMOD_RALT</dt>
	253	<dt>KMOD_LMETA</dt>
	254	<dt>KMOD_RMETA</dt>
	255	<dt>KMOD_NUM</dt>
	256	<dt>KMOD_CAPS</dt>
	257	<dt>KMOD_MODE</dt>
	258	<dt>KMOD_CTRL </dt>
	259	<dd>
	260	<p>same as KMOD_LCTRL\|KMOD_RCTRL</p>
	261	</dd>
	262	<dt>KMOD_SHIFT</dt>
	263	<dd>
	264	<p>same as KMOD_LSHIFT\|KMOD_RSHIFT</p>
	265	</dd>
	266	<dt>KMOD_ALT</dt>
	267	<dd>
	268	<p>same as KMOD_LALT\|KMOD_RALT</p>
	269	</dd>
	270	<dt>KMOD_META</dt>
	271	<dd>
	272	<p>same as KMOD_LMETA\|KMOD_RMETA</p>
	273	</dd>
	274	</dl>
cf23a5da	275
	276	</div>
	277	<h2 id="set_mod_state">set_mod_state</h2>
	278	<div id="set_mod_state_CONTENT">
55bbf7a2	279	<p>Get the state of the modifier keys</p>
	280	<p>The inverse of <a href="/SDL-Events.html#get_mod_state">SDL::Events::get_mod_state</a> allows you to impose modifier key states on your application.</p>
	281	<p>Simply pass your desired modifier states into $modstate. This value can be a OR'd combination of any KMOD* constant.</p>
	282	<pre> my $modstate = KMOD_LMETA \| KMOD_LSHIFT;
	283
	284	</pre>
	285	<p>Any KMOD_* constant see <a href="/SDL-Events.html#get_mod_state">SDL::Events::get_mod_state</a> for constants.
	286	SDL::Events::set_mod_state( $modstate );</p>
cf23a5da	287
	288	</div>
	289	<h2 id="event_state">event_state </h2>
	290	<div id="event_state_CONTENT">
55bbf7a2	291	<p>Allows you to set the state of processing certain events</p>
	292	<pre> SDL::Events::event_state( $type, $state );
	293
	294	</pre>
	295	<p>A list of $type(s) can be found in <a href="SDL-Event.html">SDL::Event</a></p>
	296
	297	</div>
	298	<h3 id="STATES">STATES</h3>
	299	<div id="STATES_CONTENT">
	300	<dl>
	301	<dt>SDL_IGNORE</dt>
	302	<dd>
	303	<p>The event of $type will be automatically dropper from the event queue and will not be filtered.</p>
	304	</dd>
	305	<dt>SDL_ENABLE</dt>
	306	<dd>
	307	<p>The event of $type will be processed normally. This is default.</p>
	308	</dd>
	309	<dt>SDL_QUERY</dt>
	310	<dd>
	311	<p>The current processing state of the $type will be returned</p>
	312	</dd>
	313	</dl>
cf23a5da	314
	315	</div>
	316	<h2 id="get_key_name">get_key_name</h2>
	317	<div id="get_key_name_CONTENT">
55bbf7a2	318	<p>Gets the name of the a SDL virtual keysym</p>
	319	<pre> my $event = SDL::Event->new();
	320
	321	while( SDL::Events::poll_event($event) )
	322	{
	323	my $key = $event->key_sym;
	324	$key_str = SDL::Events::get_key_name($key);
	325	}
	326
	327	</pre>
	328	<p>Returns a string with the name of the key sym.</p>
cf23a5da	329
	330	</div>
	331	<h2 id="enable_unicode">enable_unicode </h2>
	332	<div id="enable_unicode_CONTENT">
55bbf7a2	333	<p>Enable/Disable UNICODE translation</p>
	334	<pre> my $previous_translation_mode = SDL::Events::enable_unicode( 1 ); #enable
	335	$previous_translation_mode = SDL::Events::enable_unicode( 0 ); #disables
	336
	337	</pre>
	338	<p>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 recieved key down event, the unicode member of the <a href="/SDL-Event.html#key_sym">SDL::Event::key_sym</a> provided structure will be then contain the corresponding character code, or otherwise zero.</p>
	339	<p>A value of 1 for enabling, 0 for disabling and -1 for unchanged. -1 is usefull for querying the current translation mode.</p>
	340	<p>Only key press events will be translated not release events.</p>
	341	<p>Returns the previous translation mode as (1,0).</p>
cf23a5da	342
	343	</div>
	344	<h2 id="enable_key_repeat">enable_key_repeat </h2>
	345	<div id="enable_key_repeat_CONTENT">
55bbf7a2	346	<p>Sets keyboard repeat rate</p>
	347	<pre> my $success = SDL::Events::enable_key_repeat( $delay, $interval );
	348
	349	</pre>
	350	<p>Enables or disables the keyboard repeat rate. $delay specifies how long the key must be pressed before it begins repeating, it then repleats at the speed specified by $interval. Both $delay and $interval are expressed in milliseconds.</p>
	351	<p>Setting $delay to 0 disables key repeating completely. Good default values are SDL_DEFAULT_REPEAT_DELAY and SDL_DEFAULT_REPEAT_INTERVAL.</p>
	352	<p>Return 0 on success and -1 on fail.</p>
cf23a5da	353
	354	</div>
	355	<h2 id="get_mouse_state">get_mouse_state </h2>
	356	<div id="get_mouse_state_CONTENT">
55bbf7a2	357	<p>Retrives the current state of the mouse</p>
	358	<pre> my ($mask,$x,$y) = @{ SDL::Events::get_mouse_state( ) };
	359
	360	print 'Button Left pressed' if ($mask & SDL_BUTTON_LMASK);
	361
	362	print 'Button Right pressed' if ($mask & SDL_BUTTON_RMASK);
	363
	364	print 'Button Middle pressed' if ($mask & SDL_BUTTON_MMASK);
	365
	366	print $x.','.$y;
	367
	368	</pre>
	369	<p>The current button state is returned as a button $bitmask, which can be tested using the the above constants </p>
cf23a5da	370
	371	</div>
	372	<h2 id="get_relative_mouse_state">get_relative_mouse_state </h2>
	373	<div id="get_relative_mouse_state_CONTENT">
55bbf7a2	374	<p>Retrives the current relative state of the mouse</p>
	375	<pre> my ($mask,$x,$y) = @{ SDL::Events::get_mouse_state( ) };
	376
	377	print 'Button Left pressed' if ($mask & SDL_BUTTON_LMASK);
	378
	379	print 'Button Right pressed' if ($mask & SDL_BUTTON_RMASK);
	380
	381	print 'Button Middle pressed' if ($mask & SDL_BUTTON_MMASK);
	382
	383	print $x.','.$y; # this is relative to the last postion of the mouse
	384
	385	</pre>
	386	<p>The current button state is returned as a button $bitmask, which can be tested using the the above constants </p>
	387
	388
	389
	390
cf23a5da	391
	392	</div>
	393	<h2 id="get_app_state">get_app_state </h2>
	394	<div id="get_app_state_CONTENT">
55bbf7a2	395	<p>Gets the state of the application</p>
	396	<pre> my $app_state = SDL::Events::get_app_state();
	397
	398	</pre>
	399	<p>The $app_state is a bitwise combination of:</p>
	400	<dl>
	401	<dt>SDL_APPMOUSEFOCUS</dt>
	402	<dd>
	403	<p>Application has mouse focus</p>
	404	<pre> warn 'mouse focus' if $app_state & SDL_APPMOUSEFOCUS
	405
	406	</pre>
	407	</dd>
	408	<dt>SDL_APPINPUTFOCUS</dt>
	409	<dd>
	410	<p>Application has keyboard focus</p>
	411	<pre> warn 'keyboard focus' if $app_state & SDL_APPINPUTFOCUS
	412
	413
	414
	415
	416	</pre>
	417	</dd>
	418	<dt>SDL_APPACTIVE</dt>
	419	<dd>
	420	<p>Application is visible</p>
	421	<pre> warn 'Application Visible' if $app_state & SDL_APPACTIVE
cf23a5da	422
cf23a5da	423
	424
	425
55bbf7a2	426	</pre>
	427
	428	</div>
	429	<h2 id="joystick_event_state">joystick_event_state </h2>
	430	<div id="joystick_event_state_CONTENT">
	431	<p>Enable/disable joystick event polling</p>
	432	<pre> my $status = SDL::Events::joystick_event_state( $state );
cf23a5da	433
55bbf7a2	434	</pre>
	435	<p>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_JoystickUpdate and read the joystick information manually. $state can be:</p>
	436	</dd>
	437	<dt>SDL_QUERY</dt>
	438	<dt>SDL_ENABLE </dt>
	439	<dt>SDL_IGNORE</dt>
	440	<dd>
	441	<p>Joystick event handling is default. Even if joystick event processing is enabled, individual joysticks must be opened before they generate events</p>
	442	</dd>
	443	</dl>
	444	<p><strong>Warning:</strong> Calling this function may delete all events currently in SDL's event queue.</p>
	445	<p>If $state is SDL_QUERY then the current state is returned, otherwise the new processing state is returned.</p>
cf23a5da	446
cf23a5da	447	</div>
162a0989	448	<h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
162a0989	449	<div id="SEE_ALSO_CONTENT">
55bbf7a2	450	<p><a href="SDL-Event.html">SDL::Event</a>, <a href="SDL-Video.html">SDL::Video</a>
60f74f6f	451	</p>
162a0989	452
	453	</div>
	454	</div>