pages/SDL-Event.html-inc

   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>
  11 <li><a href="#Application_visibility_events">Application visibility events</a>
  12 <ul><li><a href="#active_gain">active_gain</a></li>
  13 <li><a href="#active_state">active_state</a></li>
  14 </ul>
  15 </li>
  16 <li><a href="#Keyboard_events">Keyboard events</a>
  17 <ul><li><a href="#key_state">key_state</a></li>
  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>
  24 <li><a href="#Mouse_motion_events">Mouse motion events</a>
  25 <ul><li><a href="#motion_state">motion_state</a></li>
  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>
  30 <li><a href="#Mouse_button_events">Mouse button events</a>
  31 <ul><li><a href="#button_which">button_which</a></li>
  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>
  37 <li><a href="#Joystick_axis_events">Joystick axis events</a>
  38 <ul><li><a href="#jaxis_which">jaxis_which</a></li>
  39 <li><a href="#jaxis_axis">jaxis_axis</a></li>
  40 <li><a href="#jaxis_value">jaxis_value</a></li>
  41 </ul>
  42 </li>
  43 <li><a href="#Joystick_button_events">Joystick button events</a>
  44 <ul><li><a href="#jbutton_which">jbutton_which</a></li>
  45 <li><a href="#jbutton_button">jbutton_button</a></li>
  46 <li><a href="#jbutton_state">jbutton_state</a></li>
  47 </ul>
  48 </li>
  49 <li><a href="#Joystick_hat_events">Joystick hat events</a>
  50 <ul><li><a href="#jhat_which">jhat_which</a></li>
  51 <li><a href="#jhat_hat">jhat_hat</a></li>
  52 <li><a href="#jhat_value">jhat_value</a></li>
  53 </ul>
  54 </li>
  55 <li><a href="#Joystrick_trackball_events">Joystrick trackball events</a>
  56 <ul><li><a href="#jball_which">jball_which</a></li>
  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>
  61 <li><a href="#Window_resize_events">Window resize events</a>
  62 <ul><li><a href="#resize_w_resize_h">resize_w, resize_h</a></li>
  63 </ul>
  64 </li>
  65 <li><a href="#Window_expose_events">Window expose events</a></li>
  66 <li><a href="#System_window_manager_events">System window manager events</a>
  67 <ul><li><a href="#syswm_msg">syswm_msg</a></li>
  68 </ul>
  69 </li>
  70 <li><a href="#User_defined_events">User defined events</a>
  71 <ul><li><a href="#user_code">user_code</a></li>
  72 <li><a href="#user_data1_user_data2">user_data1, user_data2</a></li>
  73 </ul>
  74 </li>
  75 <li><a href="#Quit_event">Quit event</a></li>
  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-&gt;new();
  96
  97  while(1)
  98  {
  99      pump_events();
 100
 101      if(poll_event($event))
 102      {
 103         if($event-&gt;type == SDL_MOUSEBUTTONDOWN)
 104         {
 105             # now you can handle the details
 106             $event-&gt;button_which;
 107             $event-&gt;button_button;
 108             $event-&gt;button_x;
 109             $event-&gt;button_y;
 110         }
 111
 112         last if $event-&gt;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-&gt;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>
 155 <pre> print 'heureka' if $event-&gt;type == SDL_MOUSEBUTTONDOWN;
 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
 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   &amp; SDL_MOUSEEVENTMASK) # is false
 203  (SDL_MOUSEBUTTONDOWN &amp; SDL_MOUSEEVENTMASK) # is true
 204  (SDL_MOUSEBUTTONUP   &amp; SDL_MOUSEEVENTMASK) # is true
 205  (SDL_MOUSEMOTION     &amp; 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>
 214
 215 </div>
 216 <h2 id="Application_visibility_events">Application visibility events</h2>
 217 <div id="Application_visibility_events_CONTEN">
 218 <p><code>active</code> is used when an event of type <code>SDL_ACTIVEEVENT</code> is reported.</p>
 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-&gt;new();
 228     $event-&gt;type(SDL_ACTIVEEVENT);
 229     $event-&gt;active_gain(0);
 230     $event-&gt;active_state(SDL_APPMOUSEFOCUS);
 231
 232  # I think this is wrong, -&gt;active_type() should get SDL_APPMOUSEFOCUS, but what state gets?
 233
 234 </pre>
 235
 236 </div>
 237 <h3 id="active_gain">active_gain</h3>
 238 <div id="active_gain_CONTENT">
 239 <p>See <code>active</code>. 0 if the event is a loss or 1 if it is a gain.</p>
 240
 241 </div>
 242 <h3 id="active_state">active_state</h3>
 243 <div id="active_state_CONTENT">
 244 <p>A bitmask of the following values: SDL_APPMOUSEFOCUS if mouse focus was gained or lost,
 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>
 246
 247 </div>
 248 <h2 id="Keyboard_events">Keyboard events</h2>
 249 <div id="Keyboard_events_CONTENT">
 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>
 259
 260 </div>
 261 <h3 id="key_state">key_state</h3>
 262 <div id="key_state_CONTENT">
 263 <p><code>SDL_PRESSED</code> or <code>SDL_RELEASED</code></p>
 264
 265 </div>
 266 <h3 id="key_scancode">key_scancode</h3>
 267 <div id="key_scancode_CONTENT">
 268 <p>The <code>scancode</code> field should generally be left alone, it is the hardware-dependent scancode returned by the keyboard.</p>
 269
 270 </div>
 271 <h3 id="key_sym">key_sym</h3>
 272 <div id="key_sym_CONTENT">
 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-&gt;type)
 278      {
 279          case SDL_KEYDOWN:
 280              move_left() if($event-&gt;key_sym == SDLK_LEFT);
 281              break;
 282          .
 283          .
 284          .
 285      }
 286  }
 287
 288 </pre>
 289
 290 </div>
 291 <h3 id="key_mod">key_mod</h3>
 292 <div id="key_mod_CONTENT">
 293 <p><code>mod</code> stores the current state of the keyboard modifiers as explained in SDL_GetModState.</p>
 294
 295 </div>
 296 <h3 id="key_unicode">key_unicode</h3>
 297 <div id="key_unicode_CONTENT">
 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-&gt;key_unicode &amp; 0xFF80) == 0)
 303  {
 304      $char = $event-&gt;key_unicode &amp; 0x7F;
 305  }
 306  else
 307  {
 308      print(&quot;An International Character.\n&quot;);
 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>
 315
 316 </div>
 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>
 323
 324 </div>
 325 <h3 id="motion_state">motion_state</h3>
 326 <div id="motion_state_CONTENT">
 327 <p>The button state can be interpreted using the <code>SDL_BUTTON</code> macro (see SDL_GetMouseState). </p>
 328
 329 </div>
 330 <h3 id="motion_x_motion_y">motion_x, motion_y</h3>
 331 <div id="motion_x_motion_y_CONTENT">
 332 <p>The X/Y coordinates of the mouse</p>
 333
 334 </div>
 335 <h3 id="motion_xrel_motion_yrel">motion_xrel, motion_yrel</h3>
 336 <div id="motion_xrel_motion_yrel_CONTENT">
 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>
 341
 342 </div>
 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>
 352
 353 </div>
 354 <h3 id="button_which">button_which</h3>
 355 <div id="button_which_CONTENT">
 356 <p>The input device index</p>
 357
 358 </div>
 359 <h3 id="button_button">button_button</h3>
 360 <div id="button_button_CONTENT">
 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>,
 362 <code>SDL_BUTTON_WHEELDOWN</code>)</p>
 363
 364 </div>
 365 <h3 id="button_state">button_state</h3>
 366 <div id="button_state_CONTENT">
 367 <p><code>SDL_PRESSED</code> or <code>SDL_RELEASED</code></p>
 368
 369 </div>
 370 <h3 id="button_x_button_y">button_x, button_y</h3>
 371 <div id="button_x_button_y_CONTENT">
 372 <p>The X/Y coordinates of the mouse at press/release time</p>
 373
 374 </div>
 375 <h2 id="Joystick_axis_events">Joystick axis events</h2>
 376 <div id="Joystick_axis_events_CONTENT">
 377 <p>A <code>SDL_JOYAXISMOTION</code> event occurs whenever a user moves an axis on the joystick.</p>
 378
 379 </div>
 380 <h3 id="jaxis_which">jaxis_which</h3>
 381 <div id="jaxis_which_CONTENT">
 382 <p>The field <code>jaxis_which</code> is the index of the joystick that reported the event.</p>
 383
 384 </div>
 385 <h3 id="jaxis_axis">jaxis_axis</h3>
 386 <div id="jaxis_axis_CONTENT">
 387 <p>The <code>jaxis_axis</code> is the index of the axis (for a more detailed explaination see the Joystick section).</p>
 388
 389 </div>
 390 <h3 id="jaxis_value">jaxis_value</h3>
 391 <div id="jaxis_value_CONTENT">
 392 <p><code>jaxis_value</code> is the current position of the axis (range: -32768 to 32767).</p>
 393
 394 </div>
 395 <h2 id="Joystick_button_events">Joystick button events</h2>
 396 <div id="Joystick_button_events_CONTENT">
 397 <p>A <code>SDL_JOYBUTTONDOWN</code> or <code>SDL_JOYBUTTONUP</code> event occurs when ever a user presses
 398 or releases a button on a joystick.</p>
 399
 400 </div>
 401 <h3 id="jbutton_which">jbutton_which</h3>
 402 <div id="jbutton_which_CONTENT">
 403 <p>The field <code>jbutton_which</code> is the index of the joystick that reported the event.</p>
 404
 405 </div>
 406 <h3 id="jbutton_button">jbutton_button</h3>
 407 <div id="jbutton_button_CONTENT">
 408 <p>The <code>jbutton_button</code> is the index of the button (for a more detailed explanation see the Joystick section).</p>
 409
 410 </div>
 411 <h3 id="jbutton_state">jbutton_state</h3>
 412 <div id="jbutton_state_CONTENT">
 413 <p><code>jbutton_state</code> is the current state of the button which is either <code>jbutton_SDL_PRESSED</code>
 414 or <code>jbutton_SDL_RELEASED</code>. </p>
 415
 416 </div>
 417 <h2 id="Joystick_hat_events">Joystick hat events</h2>
 418 <div id="Joystick_hat_events_CONTENT">
 419 <p>A <code>SDL_JOYHATMOTION</code> event occurs when ever a user moves a hat on the joystick. </p>
 420
 421 </div>
 422 <h3 id="jhat_which">jhat_which</h3>
 423 <div id="jhat_which_CONTENT">
 424 <p>The field <code>jhat_which</code> is the index of the joystick that reported the event.</p>
 425
 426 </div>
 427 <h3 id="jhat_hat">jhat_hat</h3>
 428 <div id="jhat_hat_CONTENT">
 429 <p><code>jhat_hat</code> is the index of the hat (for a more detailed explanation see the Joystick section).</p>
 430
 431 </div>
 432 <h3 id="jhat_value">jhat_value</h3>
 433 <div id="jhat_value_CONTENT">
 434 <p><code>jhat_value</code> is the current position of the hat. It is a bitwise OR'd combination of the following
 435 values (whose meanings should be pretty obvious):</p>
 436 <ul>
 437                 <li><code>SDL_HAT_CENTERED</code>       </li>
 438                 <li><code>SDL_HAT_UP</code>     </li>
 439                 <li><code>SDL_HAT_RIGHT</code>  </li>
 440                 <li><code>SDL_HAT_DOWN</code>   </li>
 441                 <li><code>SDL_HAT_LEFT</code></li>
 442 </ul>
 443
 444 <p>The following defines are also provided:</p>
 445 <ul>
 446                 <li><code>SDL_HAT_RIGHTUP</code>        </li>
 447                 <li><code>SDL_HAT_RIGHTDOWN</code>      </li>
 448                 <li><code>SDL_HAT_LEFTUP</code> </li>
 449                 <li><code>SDL_HAT_LEFTDOWN</code></li>
 450 </ul>
 451
 452
 453 </div>
 454 <h2 id="Joystrick_trackball_events">Joystrick trackball events</h2>
 455 <div id="Joystrick_trackball_events_CONTENT">
 456 <p>A <code>SDL_JOYBALLMOTION</code> event occurs when a user moves a trackball on the joystick.</p>
 457
 458 </div>
 459 <h3 id="jball_which">jball_which</h3>
 460 <div id="jball_which_CONTENT">
 461 <p>The field <code>jball_which</code> is the index of the joystick that reported the event.</p>
 462
 463 </div>
 464 <h3 id="jball_ball">jball_ball</h3>
 465 <div id="jball_ball_CONTENT">
 466 <p><code>jball_ball</code> is the index of the trackball (for a more detailed explanation see the Joystick section).</p>
 467
 468 </div>
 469 <h3 id="jball_xrel_jball_yrel">jball_xrel, jball_yrel</h3>
 470 <div id="jball_xrel_jball_yrel_CONTENT">
 471 <p>Trackballs only return relative motion, this is the change in position on the ball since it was last
 472 polled (last cycle of the event loop) and it is stored in <code>jball_xrel</code> and <code>jball_yrel</code>.</p>
 473
 474 </div>
 475 <h2 id="Window_resize_events">Window resize events</h2>
 476 <div id="Window_resize_events_CONTENT">
 477
 478 </div>
 479 <h3 id="resize_w_resize_h">resize_w, resize_h</h3>
 480 <div id="resize_w_resize_h_CONTENT">
 481 <p>When <code>SDL_RESIZABLE</code> is passed as a flag to <code>SDL_SetVideoMode</code> the user is allowed to resize the
 482 applications window. When the window is resized an <code>SDL_VIDEORESIZE</code> is reported, with the new
 483 window width and height values stored in the resize structure's <code>resize_w</code> and <code>resize_h</code>.
 484 When an <code>SDL_VIDEORESIZE</code> is received the window should be resized to the new dimensions using
 485 SDL_SetVideoMode. </p>
 486
 487 </div>
 488 <h2 id="Window_expose_events">Window expose events</h2>
 489 <div id="Window_expose_events_CONTENT">
 490 <p>A <code>VIDEOEXPOSE</code> event is triggered when the screen has been modified outside of the application,
 491 usually by the window manager and needs to be redrawn.</p>
 492
 493 </div>
 494 <h2 id="System_window_manager_events">System window manager events</h2>
 495 <div id="System_window_manager_events_CONTENT">
 496 <p>The system window manager event contains a system-specific information about unknown window manager
 497 events. If you enable this event using <code>SDL_EventState</code>, it will be generated whenever unhandled
 498 events are received from the window manager. This can be used, for example, to implement cut-and-paste
 499 in your application.</p>
 500 <p>If you want to obtain system-specific information about the window manager, you can fill in the
 501 version member of a SDL_SysWMinfo structure (details can be found in SDL_syswm.h, which must be included)
 502 using the SDL_VERSION() macro found in SDL_version.h, and pass it to the function:</p>
 503 <pre> int SDL_GetWMInfo(SDL_SysWMinfo *info);
 504
 505 </pre>
 506 <p>See <a href="http://www.libsdl.org/cgi/docwiki.cgi/SDL_SysWMEvent">http://www.libsdl.org/cgi/docwiki.cgi/SDL_SysWMEvent</a></p>
 507
 508 </div>
 509 <h3 id="syswm_msg">syswm_msg</h3>
 510 <div id="syswm_msg_CONTENT">
 511
 512 </div>
 513 <h2 id="User_defined_events">User defined events</h2>
 514 <div id="User_defined_events_CONTENT">
 515 <p>This event is unique, it is never created by SDL but only by the user. The event can be pushed onto
 516 the event queue using <code>SDL::Events::push_event</code>. The contents of the structure members are completely up to the
 517 programmer, the only requirement is that type is a value from <code>SDL_USEREVENT</code> to <code>SDL_NUMEVENTS-1</code> (inclusive)</p>
 518 <pre> my $event = SDL::Event-&gt;new();
 519     $event-&gt;type ( SDL_USEREVENT + 3 );
 520     $event-&gt;event_code(10);
 521     $event-&gt;data1('hello event');
 522
 523  SDL::Events::push_event($event);
 524
 525 </pre>
 526
 527 </div>
 528 <h3 id="user_code">user_code</h3>
 529 <div id="user_code_CONTENT">
 530 <p>User defined event code (integer).</p>
 531
 532 </div>
 533 <h3 id="user_data1_user_data2">user_data1, user_data2</h3>
 534 <div id="user_data1_user_data2_CONTENT">
 535 <p>User defined data.</p>
 536
 537 </div>
 538 <h2 id="Quit_event">Quit event</h2>
 539 <div id="Quit_event_CONTENT">
 540 <p>As can be seen, the <code>SDL_QuitEvent</code> structure serves no useful purpose. The event itself, on the other hand,
 541 is very important. If you filter out or ignore a quit event then it is impossible for the user to close the
 542 window. On the other hand, if you do accept a quit event then the application window will be closed, and
 543 screen updates will still report success even though the application will no longer be visible.</p>
 544 <p><strong>Note</strong>: The macro SDL_QuitRequested will return non-zero if a quit event is pending </p>
 545
 546 </div>
 547 <h1 id="AUTHOR">AUTHOR</h1><p><a href="#TOP" class="toplink">Top</a></p>
 548 <div id="AUTHOR_CONTENT">
 549
 550 </div>
 551 <h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
 552 <div id="SEE_ALSO_CONTENT">
 553 <p><cite>perl</cite></p>
 554
 555 </div>
 556 </div>