fixed docs

[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_w_resize_h">resize_w, resize_h</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">
<p>A <code>SDL_JOYAXISMOTION</code> event occurs whenever a user moves an axis on the joystick.</p>

</div>
<h3 id="jaxis_which">jaxis_which</h3>
<div id="jaxis_which_CONTENT">
<p>The field <code>jaxis_which</code> is the index of the joystick that reported the event.</p>

</div>
<h3 id="jaxis_axis">jaxis_axis</h3>
<div id="jaxis_axis_CONTENT">
<p>The <code>jaxis_axis</code> is the index of the axis (for a more detailed explaination see the Joystick section).</p>

</div>
<h3 id="jaxis_value">jaxis_value</h3>
<div id="jaxis_value_CONTENT">
<p><code>jaxis_value</code> is the current position of the axis (range: -32768 to 32767).</p>

</div>
<h2 id="Joystick_button_events">Joystick button events</h2>
<div id="Joystick_button_events_CONTENT">
<p>A <code>SDL_JOYBUTTONDOWN</code> or <code>SDL_JOYBUTTONUP</code> event occurs when ever a user presses 
or releases a button on a joystick.</p>

</div>
<h3 id="jbutton_which">jbutton_which</h3>
<div id="jbutton_which_CONTENT">
<p>The field <code>jbutton_which</code> is the index of the joystick that reported the event.</p>

</div>
<h3 id="jbutton_button">jbutton_button</h3>
<div id="jbutton_button_CONTENT">
<p>The <code>jbutton_button</code> is the index of the button (for a more detailed explanation see the Joystick section).</p>

</div>
<h3 id="jbutton_state">jbutton_state</h3>
<div id="jbutton_state_CONTENT">
<p><code>jbutton_state</code> is the current state of the button which is either <code>jbutton_SDL_PRESSED</code> 
or <code>jbutton_SDL_RELEASED</code>. </p>

</div>
<h2 id="Joystick_hat_events">Joystick hat events</h2>
<div id="Joystick_hat_events_CONTENT">
<p>A <code>SDL_JOYHATMOTION</code> event occurs when ever a user moves a hat on the joystick. </p>

</div>
<h3 id="jhat_which">jhat_which</h3>
<div id="jhat_which_CONTENT">
<p>The field <code>jhat_which</code> is the index of the joystick that reported the event.</p>

</div>
<h3 id="jhat_hat">jhat_hat</h3>
<div id="jhat_hat_CONTENT">
<p><code>jhat_hat</code> is the index of the hat (for a more detailed explanation see the Joystick section).</p>

</div>
<h3 id="jhat_value">jhat_value</h3>
<div id="jhat_value_CONTENT">
<p><code>jhat_value</code> is the current position of the hat. It is a bitwise OR'd combination of the following 
values (whose meanings should be pretty obvious):</p>
<ul>
		<li><code>SDL_HAT_CENTERED</code>	</li>
		<li><code>SDL_HAT_UP</code>	</li>
		<li><code>SDL_HAT_RIGHT</code>	</li>
		<li><code>SDL_HAT_DOWN</code>	</li>
		<li><code>SDL_HAT_LEFT</code></li>
</ul>

<p>The following defines are also provided:</p>
<ul>
		<li><code>SDL_HAT_RIGHTUP</code>	</li>
		<li><code>SDL_HAT_RIGHTDOWN</code>	</li>
		<li><code>SDL_HAT_LEFTUP</code>	</li>
		<li><code>SDL_HAT_LEFTDOWN</code></li>
</ul>


</div>
<h2 id="Joystrick_trackball_events">Joystrick trackball events</h2>
<div id="Joystrick_trackball_events_CONTENT">
<p>A <code>SDL_JOYBALLMOTION</code> event occurs when a user moves a trackball on the joystick.</p>

</div>
<h3 id="jball_which">jball_which</h3>
<div id="jball_which_CONTENT">
<p>The field <code>jball_which</code> is the index of the joystick that reported the event.</p>

</div>
<h3 id="jball_ball">jball_ball</h3>
<div id="jball_ball_CONTENT">
<p><code>jball_ball</code> is the index of the trackball (for a more detailed explanation see the Joystick section).</p>

</div>
<h3 id="jball_xrel_jball_yrel">jball_xrel, jball_yrel</h3>
<div id="jball_xrel_jball_yrel_CONTENT">
<p>Trackballs only return relative motion, this is the change in position on the ball since it was last 
polled (last cycle of the event loop) and it is stored in <code>jball_xrel</code> and <code>jball_yrel</code>.</p>

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

</div>
<h3 id="resize_w_resize_h">resize_w, resize_h</h3>
<div id="resize_w_resize_h_CONTENT">
<p>When <code>SDL_RESIZABLE</code> is passed as a flag to <code>SDL_SetVideoMode</code> the user is allowed to resize the 
applications window. When the window is resized an <code>SDL_VIDEORESIZE</code> is reported, with the new 
window width and height values stored in the resize structure's <code>resize_w</code> and <code>resize_h</code>. 
When an <code>SDL_VIDEORESIZE</code> is received the window should be resized to the new dimensions using 
SDL_SetVideoMode. </p>

</div>
<h2 id="Window_expose_events">Window expose events</h2>
<div id="Window_expose_events_CONTENT">
<p>A <code>VIDEOEXPOSE</code> event is triggered when the screen has been modified outside of the application, 
usually by the window manager and needs to be redrawn.</p>

</div>
<h2 id="System_window_manager_events">System window manager events</h2>
<div id="System_window_manager_events_CONTENT">
<p>The system window manager event contains a system-specific information about unknown window manager 
events. If you enable this event using <code>SDL_EventState</code>, it will be generated whenever unhandled 
events are received from the window manager. This can be used, for example, to implement cut-and-paste 
in your application.</p>
<p>If you want to obtain system-specific information about the window manager, you can fill in the 
version member of a SDL_SysWMinfo structure (details can be found in SDL_syswm.h, which must be included) 
using the SDL_VERSION() macro found in SDL_version.h, and pass it to the function:</p>
<pre> int SDL_GetWMInfo(SDL_SysWMinfo *info);

</pre>
<p>See <a href="http://www.libsdl.org/cgi/docwiki.cgi/SDL_SysWMEvent">http://www.libsdl.org/cgi/docwiki.cgi/SDL_SysWMEvent</a></p>

</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">
<p>This event is unique, it is never created by SDL but only by the user. The event can be pushed onto
the event queue using <code>SDL::Events::push_event</code>. The contents of the structure members are completely up to the 
programmer, the only requirement is that type is a value from <code>SDL_USEREVENT</code> to <code>SDL_NUMEVENTS-1</code> (inclusive)</p>
<pre> my $event = SDL::Event-&gt;new();
    $event-&gt;type ( SDL_USEREVENT + 3 );
    $event-&gt;event_code(10);
    $event-&gt;data1('hello event');

 SDL::Events::push_event($event);

</pre>

</div>
<h3 id="user_code">user_code</h3>
<div id="user_code_CONTENT">
<p>User defined event code (integer).</p>

</div>
<h3 id="user_data1_user_data2">user_data1, user_data2</h3>
<div id="user_data1_user_data2_CONTENT">
<p>User defined data.</p>

</div>
<h2 id="Quit_event">Quit event</h2>
<div id="Quit_event_CONTENT">
<p>As can be seen, the <code>SDL_QuitEvent</code> structure serves no useful purpose. The event itself, on the other hand, 
is very important. If you filter out or ignore a quit event then it is impossible for the user to close the 
window. On the other hand, if you do accept a quit event then the application window will be closed, and 
screen updates will still report success even though the application will no longer be visible.</p>
<p><strong>Note</strong>: The macro SDL_QuitRequested will return non-zero if a quit event is pending </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>