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

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

<ul><li><a href="#NAME">NAME</a></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="#new">new</a></li>
<li><a href="#type">type</a></li>
<li><a href="#Application_visibility_events">Application visibility events</a>
<ul><li><a href="#active_gain">active_gain</a></li>
<li><a href="#active_state">active_state</a></li>
</ul>
</li>
<li><a href="#Keyboard_events">Keyboard events</a>
<ul><li><a href="#key_state">key_state</a></li>
<li><a href="#key_scancode">key_scancode</a></li>
<li><a href="#key_sym">key_sym</a></li>
<li><a href="#key_mod">key_mod</a></li>
<li><a href="#key_unicode">key_unicode</a></li>
</ul>
</li>
<li><a href="#Mouse_motion_events">Mouse motion events</a>
<ul><li><a href="#motion_state">motion_state</a></li>
<li><a href="#motion_x_motion_y">motion_x, motion_y</a></li>
<li><a href="#motion_xrel_motion_yrel">motion_xrel, motion_yrel</a></li>
</ul>
</li>
<li><a href="#Mouse_button_events">Mouse button events</a>
<ul><li><a href="#button_which">button_which</a></li>
<li><a href="#button_button">button_button</a></li>
<li><a href="#button_state">button_state</a></li>
<li><a href="#button_x_button_y">button_x, button_y</a></li>
</ul>
</li>
<li><a href="#Joystick_axis_events">Joystick axis events</a>
<ul><li><a href="#jaxis_which">jaxis_which</a></li>
<li><a href="#jaxis_axis">jaxis_axis</a></li>
<li><a href="#jaxis_value">jaxis_value</a></li>
</ul>
</li>
<li><a href="#Joystick_button_events">Joystick button events</a>
<ul><li><a href="#jbutton_which">jbutton_which</a></li>
<li><a href="#jbutton_button">jbutton_button</a></li>
<li><a href="#jbutton_state">jbutton_state</a></li>
</ul>
</li>
<li><a href="#Joystick_hat_events">Joystick hat events</a>
<ul><li><a href="#jhat_which">jhat_which</a></li>
<li><a href="#jhat_hat">jhat_hat</a></li>
<li><a href="#jhat_value">jhat_value</a></li>
</ul>
</li>
<li><a href="#Joystrick_trackball_events">Joystrick trackball events</a>
<ul><li><a href="#jball_which">jball_which</a></li>
<li><a href="#jball_ball">jball_ball</a></li>
<li><a href="#jball_xrel_jball_yrel">jball_xrel, jball_yrel</a></li>
</ul>
</li>
<li><a href="#Window_resize_events">Window resize events</a>
<ul><li><a href="#resize_x_resize_y">resize_x, resize_y</a></li>
</ul>
</li>
<li><a href="#Window_expose_events">Window expose events</a></li>
<li><a href="#System_window_manager_events">System window manager events</a>
<ul><li><a href="#syswm_msg">syswm_msg</a></li>
</ul>
</li>
<li><a href="#User_defined_events">User defined events</a>
<ul><li><a href="#user_code">user_code</a></li>
<li><a href="#user_data1_user_data2">user_data1, user_data2</a></li>
</ul>
</li>
<li><a href="#Quit_event">Quit event</a></li>
</ul>
</li>
<li><a href="#AUTHOR">AUTHOR</a></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::Event - General event structure</p>

</div>
<h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="SYNOPSIS_CONTENT">
<pre> use SDL::Event;                             # for the event object itself
 use SDL::Events qw(pump_events poll_event); # functions for event queue handling

 SDL::init(SDL_INIT_VIDEO);
 my $event = SDL::Event-&gt;new();

 while(1)
 {
     pump_events();

     if(poll_event($event))
     {
        if($event-&gt;type == SDL_MOUSEBUTTONDOWN)
        {
            # now you can handle the details
            $event-&gt;button_which;
            $event-&gt;button_button;
            $event-&gt;button_x;
            $event-&gt;button_y;
        }

        last if $event-&gt;type == SDL_QUIT;
     }

     # your screen drawing code will be here
 }

</pre>

</div>
<h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="DESCRIPTION_CONTENT">
<p>Event handling allows your application to receive input from the user. 
Event handling is initalised (along with video) with a call to:</p>
<p><code>SDL::init(SDL_INIT_VIDEO);</code></p>
<p>Internally, SDL stores all the events waiting to be handled in an event queue. 
Using functions like <code>SDL::Events::poll_event()</code>, <code>SDL::Events::peep_events</code> 
and <code>SDL::Events::wait_event()</code> you can observe and handle waiting input events.</p>
<p>The key to event handling in SDL is the <code>SDL::Event</code> union. 
The event queue itself is composed of a series of <code>SDL::Event</code> unions, one for each waiting event. 
<code>SDL::Event</code> unions are read from the queue with the <code>SDL::Events::poll_event()</code> function 
and it is then up to the application to process the information stored with them. </p>

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

</div>
<h2 id="new">new</h2>
<div id="new_CONTENT">
<p><code>new</code> creates an empty event-object, which can be used store information. 
Either by calling <code>poll_event($event)</code> that transferes 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.</p>
<pre> use SDL::Event;

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

</pre>

</div>
<h2 id="type">type</h2>
<div id="type_CONTENT">
<p>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 <code>type</code>.</p>
<pre> print 'heureka' if $event-&gt;type == SDL_MOUSEBUTTONDOWN;

</pre>
<p>Available type constants:</p>
<ul>
		<li><a href="#active">SDL_ACTIVEEVENT</a> - Application visibility event structure 	</li>
		<li><a href="#active">SDL_KEYDOWN</a> - Keyboard event structure 	</li>
		<li><a href="#active">SDL_KEYUP</a> - Keyboard event structure 	</li>
		<li><a href="#active">SDL_MOUSEMOTION</a> - Mouse motion event structure 	</li>
		<li><a href="#active">SDL_MOUSEBUTTONDOWN</a> - Mouse button event structure 	</li>
		<li><a href="#button">SDL_MOUSEBUTTONUP</a> - Mouse button event structure 	</li>
		<li><a href="#active">SDL_JOYAXISMOTION</a> - Joystick axis motion event structure 	</li>
		<li><a href="#active">SDL_JOYBALLMOTION</a> - Joystick trackball motion event structure 	</li>
		<li><a href="#active">SDL_JOYHATMOTION</a> - Joystick hat position change event structure 	</li>
		<li><a href="#active">SDL_JOYBUTTONDOWN</a> - Joystick button event structure 	</li>
		<li><a href="#active">SDL_JOYBUTTONUP</a> - Joystick button event structure 	</li>
		<li><a href="#active">SDL_VIDEORESIZE</a> - Window resize event structure 	</li>
		<li><a href="#active">SDL_VIDEOEXPOSE</a> - Window expose event 	</li>
		<li><a href="#active">SDL_QUIT</a> - Quit requested event 	</li>
		<li><a href="#active">SDL_USEREVENT</a> - A user-defined event type 	</li>
		<li><a href="#active">SDL_SYSWMEVENT</a> - Platform-dependent window manager event. </li>
</ul>

<p>Event types are grouped by masks. <code>SDL_EVENTMASK($type)</code> will return the proper mask for the given <code>type</code>.</p>
<p>Available event mask constants:</p>
<ul>
		<li>SDL_ACTIVEEVENTMASK	</li>
		<li>SDL_KEYDOWNMASK	</li>
		<li>SDL_KEYUPMASK	</li>
		<li>SDL_KEYEVENTMASK	</li>
		<li>SDL_MOUSEMOTIONMASK	</li>
		<li>SDL_MOUSEBUTTONDOWNMASK	</li>
		<li>SDL_MOUSEBUTTONUPMASK	</li>
		<li>SDL_MOUSEEVENTMASK	</li>
		<li>SDL_JOYAXISMOTIONMASK	</li>
		<li>SDL_JOYBALLMOTIONMASK	</li>
		<li>SDL_JOYHATMOTIONMASK	</li>
		<li>SDL_JOYBUTTONDOWNMASK	</li>
		<li>SDL_JOYBUTTONUPMASK	</li>
		<li>SDL_JOYEVENTMASK	</li>
		<li>SDL_VIDEORESIZEMASK	</li>
		<li>SDL_VIDEOEXPOSEMASK	</li>
		<li>SDL_QUITMASK	</li>
		<li>SDL_SYSWMEVENTMASK</li>
</ul>

<p>This way you can check if a given <code>type</code> matches a mask:</p>
<pre> (SDL_JOYBUTTONDOWN   &amp; SDL_MOUSEEVENTMASK) # is false
 (SDL_MOUSEBUTTONDOWN &amp; SDL_MOUSEEVENTMASK) # is true
 (SDL_MOUSEBUTTONUP   &amp; SDL_MOUSEEVENTMASK) # is true
 (SDL_MOUSEMOTION     &amp; SDL_MOUSEEVENTMASK) # is true

 # and also true is:

 (SDL_MOUSEEVENTMASK == SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN) 
                      | SDL_EVENTMASK(SDL_MOUSEBUTTONUP) 
                      | SDL_EVENTMASK(SDL_MOUSEMOTION))

</pre>

</div>
<h2 id="Application_visibility_events">Application visibility events</h2>
<div id="Application_visibility_events_CONTEN">
<p><code>active</code> is used when an event of type <code>SDL_ACTIVEEVENT</code> is reported.</p>
<p>When the mouse leaves or enters the window area a <code>SDL_APPMOUSEFOCUS</code> type activation event occurs, 
if the mouse entered the window then <strong>gain</strong> will be 1, otherwise <strong>gain</strong> will be 0. </p>
<p>A <code>SDL_APPINPUTFOCUS</code> type activation event occurs when the application loses or gains keyboard focus. 
This usually occurs when another application is made active. </p>
<p>Finally, a <code>SDL_APPACTIVE</code> type event occurs when the application is either minimised/iconified (<strong>gain</strong>=0) or restored. </p>
<p>A single event can have multiple values set in <strong>state</strong>.</p>
<p><strong>Note:</strong> This event does not occur when an application window is first created. </p>
<p>A new ActiveEvent (to fake focus loss) will be created like this:</p>
<pre> my $event = SDL::Event-&gt;new();
    $event-&gt;type(SDL_ACTIVEEVENT);
    $event-&gt;active_gain(0);
    $event-&gt;active_state(SDL_APPMOUSEFOCUS);

 # I think this is wrong, -&gt;active_type() should get SDL_APPMOUSEFOCUS, but what state gets?

</pre>

</div>
<h3 id="active_gain">active_gain</h3>
<div id="active_gain_CONTENT">
<p>See <code>active</code>. 0 if the event is a loss or 1 if it is a gain.</p>

</div>
<h3 id="active_state">active_state</h3>
<div id="active_state_CONTENT">
<p>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).</p>

</div>
<h2 id="Keyboard_events">Keyboard events</h2>
<div id="Keyboard_events_CONTENT">
<p><code>key</code> is used when an event of type <code>SDL_KEYDOWN</code> or <code>SDL_KEYUP</code> is reported.</p>
<p>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 (<code>type=SDL_KEYUP</code> or <code>key_state=SDL_RELEASED</code>) 
and when a key is pressed (<code>type=SDL_KEYDOWN</code> or <code>key_state=SDL_PRESSED</code>). </p>
<p>The <code>SDLK_CAPSLOCK</code> and <code>SDLK_NUMLOCK</code> keys are special cases and report an <code>SDL_KEYDOWN</code> when first pressed, 
then an <code>SDL_RELEASED</code> when released and pressed again. For these keys <code>KEYUP</code> and <code>KEYDOWN</code> 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.</p>
<p><strong>Note:</strong> Repeating <code>SDL_KEYDOWN</code> events will occur if key repeat is enabled (see <code>SDL_EnableKeyRepeat</code>). </p>

</div>
<h3 id="key_state">key_state</h3>
<div id="key_state_CONTENT">
<p><code>SDL_PRESSED</code> or <code>SDL_RELEASED</code></p>

</div>
<h3 id="key_scancode">key_scancode</h3>
<div id="key_scancode_CONTENT">
<p>The <code>scancode</code> field should generally be left alone, it is the hardware-dependent scancode returned by the keyboard.</p>

</div>
<h3 id="key_sym">key_sym</h3>
<div id="key_sym_CONTENT">
<p>The <code>sym</code> 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: </p>
<pre> while(poll_event($event))
 {
     switch($event-&gt;type)
     {
         case SDL_KEYDOWN:
             move_left() if($event-&gt;key_sym == SDLK_LEFT);
             break;
         .
         .
         .
     }
 }

</pre>

</div>
<h3 id="key_mod">key_mod</h3>
<div id="key_mod_CONTENT">
<p><code>mod</code> stores the current state of the keyboard modifiers as explained in SDL_GetModState.</p>

</div>
<h3 id="key_unicode">key_unicode</h3>
<div id="key_unicode_CONTENT">
<p>The <code>unicode</code> field is only used when UNICODE translation is enabled with SDL_EnableUNICODE. 
If <code>unicode</code> 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:</p>
<pre> my $char;
 if(($event-&gt;key_unicode &amp; 0xFF80) == 0)
 {
     $char = $event-&gt;key_unicode &amp; 0x7F;
 }
 else
 {
     print(&quot;An International Character.\n&quot;);
 }

</pre>
<p>UNICODE translation does create a slight overhead so don't enable it unless its needed.</p>
<p>NOTE: Key release events (SDL_KEYUP) won't necessarily (ever?) contain unicode information. 
See <a href="http://lists.libsdl.org/pipermail/sdl-libsdl.org/2005-January/048355.html">http://lists.libsdl.org/pipermail/sdl-libsdl.org/2005-January/048355.html</a></p>

</div>
<h2 id="Mouse_motion_events">Mouse motion events</h2>
<div id="Mouse_motion_events_CONTENT">
<p>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 (<code>motion_x</code> and <code>motion_y</code>) 
and relative (<code>motion_xrel</code> and <code>motion_yrel</code>) coordinates are reported along with the current 
button states (<code>motion_state</code>).</p>

</div>
<h3 id="motion_state">motion_state</h3>
<div id="motion_state_CONTENT">
<p>The button state can be interpreted using the <code>SDL_BUTTON</code> macro (see SDL_GetMouseState). </p>

</div>
<h3 id="motion_x_motion_y">motion_x, motion_y</h3>
<div id="motion_x_motion_y_CONTENT">
<p>The X/Y coordinates of the mouse</p>

</div>
<h3 id="motion_xrel_motion_yrel">motion_xrel, motion_yrel</h3>
<div id="motion_xrel_motion_yrel_CONTENT">
<p>Relative motion in the X/Y direction.</p>
<p>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.</p>

</div>
<h2 id="Mouse_button_events">Mouse button events</h2>
<div id="Mouse_button_events_CONTENT">
<p>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 <code>button_button</code>, the position of the mouse 
when this event occured is stored in the <code>button_x</code> and the <code>button_y</code> fields. Like SDL_KeyboardEvent, 
information on whether the event was a press or a release event is stored in both the <code>button_type</code> 
and <code>button_state</code> fields, but this should be obvious.</p>
<p>Mouse wheel events are reported as buttons 4 (up) and 5 (down). Two events are generated i.e. you get 
a <code>SDL_MOUSEBUTTONDOWN</code> followed by a <code>SDL_MOUSEBUTTONUP</code> event.</p>

</div>
<h3 id="button_which">button_which</h3>
<div id="button_which_CONTENT">
<p>The input device index</p>

</div>
<h3 id="button_button">button_button</h3>
<div id="button_button_CONTENT">
<p>The mouse button index (<code>SDL_BUTTON_LEFT</code>, <code>SDL_BUTTON_MIDDLE</code>, <code>SDL_BUTTON_RIGHT</code>, <code>SDL_BUTTON_WHEELUP</code>, 
<code>SDL_BUTTON_WHEELDOWN</code>)</p>

</div>
<h3 id="button_state">button_state</h3>
<div id="button_state_CONTENT">
<p><code>SDL_PRESSED</code> or <code>SDL_RELEASED</code></p>

</div>
<h3 id="button_x_button_y">button_x, button_y</h3>
<div id="button_x_button_y_CONTENT">
<p>The X/Y coordinates of the mouse at press/release time</p>

</div>
<h2 id="Joystick_axis_events">Joystick axis events</h2>
<div id="Joystick_axis_events_CONTENT">

</div>
<h3 id="jaxis_which">jaxis_which</h3>
<div id="jaxis_which_CONTENT">

</div>
<h3 id="jaxis_axis">jaxis_axis</h3>
<div id="jaxis_axis_CONTENT">

</div>
<h3 id="jaxis_value">jaxis_value</h3>
<div id="jaxis_value_CONTENT">

</div>
<h2 id="Joystick_button_events">Joystick button events</h2>
<div id="Joystick_button_events_CONTENT">

</div>
<h3 id="jbutton_which">jbutton_which</h3>
<div id="jbutton_which_CONTENT">

</div>
<h3 id="jbutton_button">jbutton_button</h3>
<div id="jbutton_button_CONTENT">

</div>
<h3 id="jbutton_state">jbutton_state</h3>
<div id="jbutton_state_CONTENT">

</div>
<h2 id="Joystick_hat_events">Joystick hat events</h2>
<div id="Joystick_hat_events_CONTENT">

</div>
<h3 id="jhat_which">jhat_which</h3>
<div id="jhat_which_CONTENT">

</div>
<h3 id="jhat_hat">jhat_hat</h3>
<div id="jhat_hat_CONTENT">

</div>
<h3 id="jhat_value">jhat_value</h3>
<div id="jhat_value_CONTENT">

</div>
<h2 id="Joystrick_trackball_events">Joystrick trackball events</h2>
<div id="Joystrick_trackball_events_CONTENT">

</div>
<h3 id="jball_which">jball_which</h3>
<div id="jball_which_CONTENT">

</div>
<h3 id="jball_ball">jball_ball</h3>
<div id="jball_ball_CONTENT">

</div>
<h3 id="jball_xrel_jball_yrel">jball_xrel, jball_yrel</h3>
<div id="jball_xrel_jball_yrel_CONTENT">

</div>
<h2 id="Window_resize_events">Window resize events</h2>
<div id="Window_resize_events_CONTENT">

</div>
<h3 id="resize_x_resize_y">resize_x, resize_y</h3>
<div id="resize_x_resize_y_CONTENT">

</div>
<h2 id="Window_expose_events">Window expose events</h2>
<div id="Window_expose_events_CONTENT">

</div>
<h2 id="System_window_manager_events">System window manager events</h2>
<div id="System_window_manager_events_CONTENT">

</div>
<h3 id="syswm_msg">syswm_msg</h3>
<div id="syswm_msg_CONTENT">

</div>
<h2 id="User_defined_events">User defined events</h2>
<div id="User_defined_events_CONTENT">

</div>
<h3 id="user_code">user_code</h3>
<div id="user_code_CONTENT">

</div>
<h3 id="user_data1_user_data2">user_data1, user_data2</h3>
<div id="user_data1_user_data2_CONTENT">

</div>
<h2 id="Quit_event">Quit event</h2>
<div id="Quit_event_CONTENT">
<p>Create a new SDL::Event object.</p>

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

</div>
<h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="SEE_ALSO_CONTENT">
<p><cite>perl</cite></p>

</div>
</div>
Commit	Line	Data
162a0989	1	<div class="pod">
	2	<!-- INDEX START -->
	3	<h3 id="TOP">Index</h3>
	4
	5	<ul><li><a href="#NAME">NAME</a></li>
	6	<li><a href="#SYNOPSIS">SYNOPSIS</a></li>
	7	<li><a href="#DESCRIPTION">DESCRIPTION</a></li>
	8	<li><a href="#METHODS">METHODS</a>
	9	<ul><li><a href="#new">new</a></li>
	10	<li><a href="#type">type</a></li>
767fbad8	11	<li><a href="#Application_visibility_events">Application visibility events</a>
6e0d970b	12	<ul><li><a href="#active_gain">active_gain</a></li>
162a0989	13	<li><a href="#active_state">active_state</a></li>
	14	</ul>
	15	</li>
767fbad8	16	<li><a href="#Keyboard_events">Keyboard events</a>
6e0d970b	17	<ul><li><a href="#key_state">key_state</a></li>
162a0989	18	<li><a href="#key_scancode">key_scancode</a></li>
	19	<li><a href="#key_sym">key_sym</a></li>
	20	<li><a href="#key_mod">key_mod</a></li>
	21	<li><a href="#key_unicode">key_unicode</a></li>
	22	</ul>
	23	</li>
767fbad8	24	<li><a href="#Mouse_motion_events">Mouse motion events</a>
6e0d970b	25	<ul><li><a href="#motion_state">motion_state</a></li>
162a0989	26	<li><a href="#motion_x_motion_y">motion_x, motion_y</a></li>
	27	<li><a href="#motion_xrel_motion_yrel">motion_xrel, motion_yrel</a></li>
	28	</ul>
	29	</li>
767fbad8	30	<li><a href="#Mouse_button_events">Mouse button events</a>
6e0d970b	31	<ul><li><a href="#button_which">button_which</a></li>
162a0989	32	<li><a href="#button_button">button_button</a></li>
	33	<li><a href="#button_state">button_state</a></li>
	34	<li><a href="#button_x_button_y">button_x, button_y</a></li>
	35	</ul>
	36	</li>
767fbad8	37	<li><a href="#Joystick_axis_events">Joystick axis events</a>
6e0d970b	38	<ul><li><a href="#jaxis_which">jaxis_which</a></li>
162a0989	39	<li><a href="#jaxis_axis">jaxis_axis</a></li>
	40	<li><a href="#jaxis_value">jaxis_value</a></li>
	41	</ul>
	42	</li>
767fbad8	43	<li><a href="#Joystick_button_events">Joystick button events</a>
6e0d970b	44	<ul><li><a href="#jbutton_which">jbutton_which</a></li>
162a0989	45	<li><a href="#jbutton_button">jbutton_button</a></li>
	46	<li><a href="#jbutton_state">jbutton_state</a></li>
	47	</ul>
	48	</li>
767fbad8	49	<li><a href="#Joystick_hat_events">Joystick hat events</a>
6e0d970b	50	<ul><li><a href="#jhat_which">jhat_which</a></li>
162a0989	51	<li><a href="#jhat_hat">jhat_hat</a></li>
	52	<li><a href="#jhat_value">jhat_value</a></li>
	53	</ul>
	54	</li>
767fbad8	55	<li><a href="#Joystrick_trackball_events">Joystrick trackball events</a>
6e0d970b	56	<ul><li><a href="#jball_which">jball_which</a></li>
162a0989	57	<li><a href="#jball_ball">jball_ball</a></li>
	58	<li><a href="#jball_xrel_jball_yrel">jball_xrel, jball_yrel</a></li>
	59	</ul>
	60	</li>
767fbad8	61	<li><a href="#Window_resize_events">Window resize events</a>
6e0d970b	62	<ul><li><a href="#resize_x_resize_y">resize_x, resize_y</a></li>
162a0989	63	</ul>
162a0989	64	</li>
767fbad8	65	<li><a href="#Window_expose_events">Window expose events</a></li>
767fbad8	66	<li><a href="#System_window_manager_events">System window manager events</a>
6e0d970b	67	<ul><li><a href="#syswm_msg">syswm_msg</a></li>
162a0989	68	</ul>
162a0989	69	</li>
767fbad8	70	<li><a href="#User_defined_events">User defined events</a>
6e0d970b	71	<ul><li><a href="#user_code">user_code</a></li>
162a0989	72	<li><a href="#user_data1_user_data2">user_data1, user_data2</a></li>
	73	</ul>
	74	</li>
767fbad8	75	<li><a href="#Quit_event">Quit event</a></li>
162a0989	76	</ul>
	77	</li>
	78	<li><a href="#AUTHOR">AUTHOR</a></li>
	79	<li><a href="#SEE_ALSO">SEE ALSO</a>
	80	</li>
	81	</ul><hr />
	82	<!-- INDEX END -->
	83
	84	<h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
	85	<div id="NAME_CONTENT">
	86	<p>SDL::Event - General event structure</p>
	87
	88	</div>
	89	<h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p>
	90	<div id="SYNOPSIS_CONTENT">
	91	<pre> use SDL::Event; # for the event object itself
	92	use SDL::Events qw(pump_events poll_event); # functions for event queue handling
	93
	94	SDL::init(SDL_INIT_VIDEO);
	95	my $event = SDL::Event->new();
	96
	97	while(1)
	98	{
	99	pump_events();
	100
	101	if(poll_event($event))
	102	{
	103	if($event->type == SDL_MOUSEBUTTONDOWN)
	104	{
	105	# now you can handle the details
	106	$event->button_which;
	107	$event->button_button;
	108	$event->button_x;
	109	$event->button_y;
	110	}
	111
	112	last if $event->type == SDL_QUIT;
	113	}
	114
	115	# your screen drawing code will be here
	116	}
	117
	118	</pre>
	119
	120	</div>
	121	<h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p>
	122	<div id="DESCRIPTION_CONTENT">
	123	<p>Event handling allows your application to receive input from the user.
	124	Event handling is initalised (along with video) with a call to:</p>
	125	<p><code>SDL::init(SDL_INIT_VIDEO);</code></p>
	126	<p>Internally, SDL stores all the events waiting to be handled in an event queue.
	127	Using functions like <code>SDL::Events::poll_event()</code>, <code>SDL::Events::peep_events</code>
	128	and <code>SDL::Events::wait_event()</code> you can observe and handle waiting input events.</p>
	129	<p>The key to event handling in SDL is the <code>SDL::Event</code> union.
	130	The event queue itself is composed of a series of <code>SDL::Event</code> unions, one for each waiting event.
	131	<code>SDL::Event</code> unions are read from the queue with the <code>SDL::Events::poll_event()</code> function
	132	and it is then up to the application to process the information stored with them. </p>
	133
	134	</div>
	135	<h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
	136	<div id="METHODS_CONTENT">
	137
	138	</div>
	139	<h2 id="new">new</h2>
140	<div id="new_CONTENT">
141	<p><code>new</code> creates an empty event-object, which can be used store information.
142	Either by calling <code>poll_event($event)</code> that transferes one event from the queue into our object
143	or by setting all the needed data manually in order to push the event to the queue.</p>
144	<pre> use SDL::Event;
145
146	my $event = SDL::Event->new();
147
148	</pre>
149
150	</div>
151	<h2 id="type">type</h2>
152	<div id="type_CONTENT">
153	<p>SDL::Event is a union of all event structures used in SDL, using it is a simple matter of knowing
154	which union member relates to which event <code>type</code>.</p>
6e0d970b	155	<pre> print 'heureka' if $event->type == SDL_MOUSEBUTTONDOWN;
162a0989	156
	157	</pre>
	158	<p>Available type constants:</p>
	159	<ul>
	160	<li><a href="#active">SDL_ACTIVEEVENT</a> - Application visibility event structure </li>
	161	<li><a href="#active">SDL_KEYDOWN</a> - Keyboard event structure </li>
	162	<li><a href="#active">SDL_KEYUP</a> - Keyboard event structure </li>
	163	<li><a href="#active">SDL_MOUSEMOTION</a> - Mouse motion event structure </li>
	164	<li><a href="#active">SDL_MOUSEBUTTONDOWN</a> - Mouse button event structure </li>
	165	<li><a href="#button">SDL_MOUSEBUTTONUP</a> - Mouse button event structure </li>
	166	<li><a href="#active">SDL_JOYAXISMOTION</a> - Joystick axis motion event structure </li>
	167	<li><a href="#active">SDL_JOYBALLMOTION</a> - Joystick trackball motion event structure </li>
	168	<li><a href="#active">SDL_JOYHATMOTION</a> - Joystick hat position change event structure </li>
	169	<li><a href="#active">SDL_JOYBUTTONDOWN</a> - Joystick button event structure </li>
	170	<li><a href="#active">SDL_JOYBUTTONUP</a> - Joystick button event structure </li>
	171	<li><a href="#active">SDL_VIDEORESIZE</a> - Window resize event structure </li>
	172	<li><a href="#active">SDL_VIDEOEXPOSE</a> - Window expose event </li>
	173	<li><a href="#active">SDL_QUIT</a> - Quit requested event </li>
	174	<li><a href="#active">SDL_USEREVENT</a> - A user-defined event type </li>
	175	<li><a href="#active">SDL_SYSWMEVENT</a> - Platform-dependent window manager event. </li>
	176	</ul>
	177
6e0d970b	178	<p>Event types are grouped by masks. <code>SDL_EVENTMASK($type)</code> will return the proper mask for the given <code>type</code>.</p>
	179	<p>Available event mask constants:</p>
	180	<ul>
	181	<li>SDL_ACTIVEEVENTMASK </li>
	182	<li>SDL_KEYDOWNMASK </li>
	183	<li>SDL_KEYUPMASK </li>
	184	<li>SDL_KEYEVENTMASK </li>
	185	<li>SDL_MOUSEMOTIONMASK </li>
	186	<li>SDL_MOUSEBUTTONDOWNMASK </li>
	187	<li>SDL_MOUSEBUTTONUPMASK </li>
	188	<li>SDL_MOUSEEVENTMASK </li>
	189	<li>SDL_JOYAXISMOTIONMASK </li>
	190	<li>SDL_JOYBALLMOTIONMASK </li>
	191	<li>SDL_JOYHATMOTIONMASK </li>
	192	<li>SDL_JOYBUTTONDOWNMASK </li>
	193	<li>SDL_JOYBUTTONUPMASK </li>
	194	<li>SDL_JOYEVENTMASK </li>
	195	<li>SDL_VIDEORESIZEMASK </li>
	196	<li>SDL_VIDEOEXPOSEMASK </li>
	197	<li>SDL_QUITMASK </li>
	198	<li>SDL_SYSWMEVENTMASK</li>
	199	</ul>
	200
	201	<p>This way you can check if a given <code>type</code> matches a mask:</p>
	202	<pre> (SDL_JOYBUTTONDOWN & SDL_MOUSEEVENTMASK) # is false
	203	(SDL_MOUSEBUTTONDOWN & SDL_MOUSEEVENTMASK) # is true
	204	(SDL_MOUSEBUTTONUP & SDL_MOUSEEVENTMASK) # is true
	205	(SDL_MOUSEMOTION & SDL_MOUSEEVENTMASK) # is true
	206
	207	# and also true is:
	208
	209	(SDL_MOUSEEVENTMASK == SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN)
	210	\| SDL_EVENTMASK(SDL_MOUSEBUTTONUP)
	211	\| SDL_EVENTMASK(SDL_MOUSEMOTION))
	212
	213	</pre>
162a0989	214
162a0989	215	</div>
767fbad8	216	<h2 id="Application_visibility_events">Application visibility events</h2>
767fbad8	217	<div id="Application_visibility_events_CONTEN">
6e0d970b	218	<p><code>active</code> is used when an event of type <code>SDL_ACTIVEEVENT</code> is reported.</p>
162a0989	219	<p>When the mouse leaves or enters the window area a <code>SDL_APPMOUSEFOCUS</code> type activation event occurs,
	220	if the mouse entered the window then <strong>gain</strong> will be 1, otherwise <strong>gain</strong> will be 0. </p>
	221	<p>A <code>SDL_APPINPUTFOCUS</code> type activation event occurs when the application loses or gains keyboard focus.
	222	This usually occurs when another application is made active. </p>
	223	<p>Finally, a <code>SDL_APPACTIVE</code> type event occurs when the application is either minimised/iconified (<strong>gain</strong>=0) or restored. </p>
	224	<p>A single event can have multiple values set in <strong>state</strong>.</p>
	225	<p><strong>Note:</strong> This event does not occur when an application window is first created. </p>
	226	<p>A new ActiveEvent (to fake focus loss) will be created like this:</p>
	227	<pre> my $event = SDL::Event->new();
	228	$event->type(SDL_ACTIVEEVENT);
	229	$event->active_gain(0);
	230	$event->active_state(SDL_APPMOUSEFOCUS);
	231
	232	# I think this is wrong, ->active_type() should get SDL_APPMOUSEFOCUS, but what state gets?
	233
	234	</pre>
	235
	236	</div>
162a0989	237	<h3 id="active_gain">active_gain</h3>
162a0989	238	<div id="active_gain_CONTENT">
6e0d970b	239	<p>See <code>active</code>. 0 if the event is a loss or 1 if it is a gain.</p>
162a0989	240
	241	</div>
	242	<h3 id="active_state">active_state</h3>
	243	<div id="active_state_CONTENT">
6e0d970b	244	<p>A bitmask of the following values: SDL_APPMOUSEFOCUS if mouse focus was gained or lost,
6e0d970b	245	SDL_APPINPUTFOCUS if input focus was gained or lost, and SDL_APPACTIVE if the application was iconified (gain=0) or restored(gain=1).</p>
162a0989	246
162a0989	247	</div>
767fbad8	248	<h2 id="Keyboard_events">Keyboard events</h2>
767fbad8	249	<div id="Keyboard_events_CONTENT">
6e0d970b	250	<p><code>key</code> is used when an event of type <code>SDL_KEYDOWN</code> or <code>SDL_KEYUP</code> is reported.</p>
	251	<p>The type and state actually report the same information, they just use different values to do it.
	252	A keyboard event generally occurs when a key is released (<code>type=SDL_KEYUP</code> or <code>key_state=SDL_RELEASED</code>)
	253	and when a key is pressed (<code>type=SDL_KEYDOWN</code> or <code>key_state=SDL_PRESSED</code>). </p>
	254	<p>The <code>SDLK_CAPSLOCK</code> and <code>SDLK_NUMLOCK</code> keys are special cases and report an <code>SDL_KEYDOWN</code> when first pressed,
	255	then an <code>SDL_RELEASED</code> when released and pressed again. For these keys <code>KEYUP</code> and <code>KEYDOWN</code> events are therefore
	256	analogous to the state of the caps lock and num lock LEDs rather than the keys themselves.
	257	These special cases are required for compatibility with Sun workstations.</p>
	258	<p><strong>Note:</strong> Repeating <code>SDL_KEYDOWN</code> events will occur if key repeat is enabled (see <code>SDL_EnableKeyRepeat</code>). </p>
162a0989	259
	260	</div>
	261	<h3 id="key_state">key_state</h3>
	262	<div id="key_state_CONTENT">
6e0d970b	263	<p><code>SDL_PRESSED</code> or <code>SDL_RELEASED</code></p>
162a0989	264
	265	</div>
	266	<h3 id="key_scancode">key_scancode</h3>
	267	<div id="key_scancode_CONTENT">
767fbad8	268	<p>The <code>scancode</code> field should generally be left alone, it is the hardware-dependent scancode returned by the keyboard.</p>
162a0989	269
	270	</div>
	271	<h3 id="key_sym">key_sym</h3>
	272	<div id="key_sym_CONTENT">
767fbad8	273	<p>The <code>sym</code> field is extremely useful. It is the SDL-defined value of the key (see the keysym definitions in SDLKey).
	274	This field is very useful when you are checking for certain key presses, like so: </p>
	275	<pre> while(poll_event($event))
	276	{
	277	switch($event->type)
	278	{
	279	case SDL_KEYDOWN:
	280	move_left() if($event->key_sym == SDLK_LEFT);
	281	break;
	282	.
	283	.
	284	.
	285	}
	286	}
	287
	288	</pre>
162a0989	289
	290	</div>
	291	<h3 id="key_mod">key_mod</h3>
	292	<div id="key_mod_CONTENT">
767fbad8	293	<p><code>mod</code> stores the current state of the keyboard modifiers as explained in SDL_GetModState.</p>
162a0989	294
	295	</div>
	296	<h3 id="key_unicode">key_unicode</h3>
	297	<div id="key_unicode_CONTENT">
767fbad8	298	<p>The <code>unicode</code> field is only used when UNICODE translation is enabled with SDL_EnableUNICODE.
	299	If <code>unicode</code> is non-zero then this is the UNICODE character corresponding to the keypress.
	300	If the high 9 bits of the character are 0, then this maps to the equivalent ASCII character:</p>
	301	<pre> my $char;
	302	if(($event->key_unicode & 0xFF80) == 0)
	303	{
	304	$char = $event->key_unicode & 0x7F;
	305	}
	306	else
	307	{
	308	print("An International Character.\n");
	309	}
	310
	311	</pre>
	312	<p>UNICODE translation does create a slight overhead so don't enable it unless its needed.</p>
	313	<p>NOTE: Key release events (SDL_KEYUP) won't necessarily (ever?) contain unicode information.
	314	See <a href="http://lists.libsdl.org/pipermail/sdl-libsdl.org/2005-January/048355.html">http://lists.libsdl.org/pipermail/sdl-libsdl.org/2005-January/048355.html</a></p>
162a0989	315
162a0989	316	</div>
767fbad8	317	<h2 id="Mouse_motion_events">Mouse motion events</h2>
	318	<div id="Mouse_motion_events_CONTENT">
	319	<p>Simply put, a SDL_MOUSEMOTION type event occurs when a user moves the mouse within the
	320	application window or when SDL_WarpMouse is called. Both the absolute (<code>motion_x</code> and <code>motion_y</code>)
	321	and relative (<code>motion_xrel</code> and <code>motion_yrel</code>) coordinates are reported along with the current
	322	button states (<code>motion_state</code>).</p>
162a0989	323
162a0989	324	</div>
162a0989	325	<h3 id="motion_state">motion_state</h3>
162a0989	326	<div id="motion_state_CONTENT">
767fbad8	327	<p>The button state can be interpreted using the <code>SDL_BUTTON</code> macro (see SDL_GetMouseState). </p>
162a0989	328
	329	</div>
	330	<h3 id="motion_x_motion_y">motion_x, motion_y</h3>
	331	<div id="motion_x_motion_y_CONTENT">
767fbad8	332	<p>The X/Y coordinates of the mouse</p>
162a0989	333
	334	</div>
	335	<h3 id="motion_xrel_motion_yrel">motion_xrel, motion_yrel</h3>
	336	<div id="motion_xrel_motion_yrel_CONTENT">
767fbad8	337	<p>Relative motion in the X/Y direction.</p>
	338	<p>If the cursor is hidden (SDL_ShowCursor(0)) and the input is grabbed (SDL_WM_GrabInput(SDL_GRAB_ON)),
	339	then the mouse will give relative motion events even when the cursor reaches the edge of the screen.
	340	This is currently only implemented on Windows and Linux/Unix-alikes.</p>
162a0989	341
162a0989	342	</div>
767fbad8	343	<h2 id="Mouse_button_events">Mouse button events</h2>
	344	<div id="Mouse_button_events_CONTENT">
	345	<p>When a mouse button press or release is detected the number of the button pressed (from 1 to 255,
	346	with 1 usually being the left button and 2 the right) is placed into <code>button_button</code>, the position of the mouse
	347	when this event occured is stored in the <code>button_x</code> and the <code>button_y</code> fields. Like SDL_KeyboardEvent,
	348	information on whether the event was a press or a release event is stored in both the <code>button_type</code>
	349	and <code>button_state</code> fields, but this should be obvious.</p>
	350	<p>Mouse wheel events are reported as buttons 4 (up) and 5 (down). Two events are generated i.e. you get
	351	a <code>SDL_MOUSEBUTTONDOWN</code> followed by a <code>SDL_MOUSEBUTTONUP</code> event.</p>
162a0989	352
162a0989	353	</div>
162a0989	354	<h3 id="button_which">button_which</h3>
162a0989	355	<div id="button_which_CONTENT">
767fbad8	356	<p>The input device index</p>
162a0989	357
	358	</div>
	359	<h3 id="button_button">button_button</h3>
	360	<div id="button_button_CONTENT">
767fbad8	361	<p>The mouse button index (<code>SDL_BUTTON_LEFT</code>, <code>SDL_BUTTON_MIDDLE</code>, <code>SDL_BUTTON_RIGHT</code>, <code>SDL_BUTTON_WHEELUP</code>,
767fbad8	362	<code>SDL_BUTTON_WHEELDOWN</code>)</p>
162a0989	363
	364	</div>
	365	<h3 id="button_state">button_state</h3>
	366	<div id="button_state_CONTENT">
767fbad8	367	<p><code>SDL_PRESSED</code> or <code>SDL_RELEASED</code></p>
162a0989	368
	369	</div>
	370	<h3 id="button_x_button_y">button_x, button_y</h3>
	371	<div id="button_x_button_y_CONTENT">
767fbad8	372	<p>The X/Y coordinates of the mouse at press/release time</p>
162a0989	373
162a0989	374	</div>
767fbad8	375	<h2 id="Joystick_axis_events">Joystick axis events</h2>
767fbad8	376	<div id="Joystick_axis_events_CONTENT">
162a0989	377
162a0989	378	</div>
162a0989	379	<h3 id="jaxis_which">jaxis_which</h3>
	380	<div id="jaxis_which_CONTENT">
	381
	382	</div>
	383	<h3 id="jaxis_axis">jaxis_axis</h3>
	384	<div id="jaxis_axis_CONTENT">
	385
	386	</div>
	387	<h3 id="jaxis_value">jaxis_value</h3>
	388	<div id="jaxis_value_CONTENT">
	389
	390	</div>
767fbad8	391	<h2 id="Joystick_button_events">Joystick button events</h2>
767fbad8	392	<div id="Joystick_button_events_CONTENT">
162a0989	393
162a0989	394	</div>
162a0989	395	<h3 id="jbutton_which">jbutton_which</h3>
	396	<div id="jbutton_which_CONTENT">
	397
	398	</div>
	399	<h3 id="jbutton_button">jbutton_button</h3>
	400	<div id="jbutton_button_CONTENT">
	401
	402	</div>
	403	<h3 id="jbutton_state">jbutton_state</h3>
	404	<div id="jbutton_state_CONTENT">
	405
	406	</div>
767fbad8	407	<h2 id="Joystick_hat_events">Joystick hat events</h2>
767fbad8	408	<div id="Joystick_hat_events_CONTENT">
162a0989	409
162a0989	410	</div>
162a0989	411	<h3 id="jhat_which">jhat_which</h3>
	412	<div id="jhat_which_CONTENT">
	413
	414	</div>
	415	<h3 id="jhat_hat">jhat_hat</h3>
	416	<div id="jhat_hat_CONTENT">
	417
	418	</div>
	419	<h3 id="jhat_value">jhat_value</h3>
	420	<div id="jhat_value_CONTENT">
	421
	422	</div>
767fbad8	423	<h2 id="Joystrick_trackball_events">Joystrick trackball events</h2>
767fbad8	424	<div id="Joystrick_trackball_events_CONTENT">
162a0989	425
162a0989	426	</div>
162a0989	427	<h3 id="jball_which">jball_which</h3>
	428	<div id="jball_which_CONTENT">
	429
	430	</div>
	431	<h3 id="jball_ball">jball_ball</h3>
	432	<div id="jball_ball_CONTENT">
	433
	434	</div>
	435	<h3 id="jball_xrel_jball_yrel">jball_xrel, jball_yrel</h3>
	436	<div id="jball_xrel_jball_yrel_CONTENT">
	437
	438	</div>
767fbad8	439	<h2 id="Window_resize_events">Window resize events</h2>
767fbad8	440	<div id="Window_resize_events_CONTENT">
162a0989	441
162a0989	442	</div>
162a0989	443	<h3 id="resize_x_resize_y">resize_x, resize_y</h3>
	444	<div id="resize_x_resize_y_CONTENT">
	445
	446	</div>
767fbad8	447	<h2 id="Window_expose_events">Window expose events</h2>
767fbad8	448	<div id="Window_expose_events_CONTENT">
162a0989	449
162a0989	450	</div>
767fbad8	451	<h2 id="System_window_manager_events">System window manager events</h2>
767fbad8	452	<div id="System_window_manager_events_CONTENT">
162a0989	453
162a0989	454	</div>
162a0989	455	<h3 id="syswm_msg">syswm_msg</h3>
	456	<div id="syswm_msg_CONTENT">
	457
	458	</div>
767fbad8	459	<h2 id="User_defined_events">User defined events</h2>
767fbad8	460	<div id="User_defined_events_CONTENT">
162a0989	461
162a0989	462	</div>
162a0989	463	<h3 id="user_code">user_code</h3>
	464	<div id="user_code_CONTENT">
	465
	466	</div>
	467	<h3 id="user_data1_user_data2">user_data1, user_data2</h3>
	468	<div id="user_data1_user_data2_CONTENT">
	469
	470	</div>
767fbad8	471	<h2 id="Quit_event">Quit event</h2>
767fbad8	472	<div id="Quit_event_CONTENT">
162a0989	473	<p>Create a new SDL::Event object.</p>
	474
	475	</div>
	476	<h1 id="AUTHOR">AUTHOR</h1><p><a href="#TOP" class="toplink">Top</a></p>
	477	<div id="AUTHOR_CONTENT">
	478
	479	</div>
	480	<h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
	481	<div id="SEE_ALSO_CONTENT">
	482	<p><cite>perl</cite></p>
	483
	484	</div>
	485	</div>