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>
   6 <ul><li><a href="#CATEGORY">CATEGORY</a></li>
   7 </ul>
   8 </li>
   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="#new">new</a></li>
  13 <li><a href="#type">type</a></li>
  14 <li><a href="#Application_visibility_events">Application visibility events</a>
  15 <ul><li><a href="#active_gain">active_gain</a></li>
  16 <li><a href="#active_state">active_state</a></li>
  17 </ul>
  18 </li>
  19 <li><a href="#Keyboard_events">Keyboard events</a>
  20 <ul><li><a href="#key_state">key_state</a></li>
  21 <li><a href="#key_scancode">key_scancode</a></li>
  22 <li><a href="#key_sym">key_sym</a></li>
  23 <li><a href="#key_mod">key_mod</a></li>
  24 <li><a href="#key_unicode">key_unicode</a></li>
  25 </ul>
  26 </li>
  27 <li><a href="#Mouse_motion_events">Mouse motion events</a>
  28 <ul><li><a href="#motion_state">motion_state</a></li>
  29 <li><a href="#motion_x_motion_y">motion_x, motion_y</a></li>
  30 <li><a href="#motion_xrel_motion_yrel">motion_xrel, motion_yrel</a></li>
  31 </ul>
  32 </li>
  33 <li><a href="#Mouse_button_events">Mouse button events</a>
  34 <ul><li><a href="#button_which">button_which</a></li>
  35 <li><a href="#button_button">button_button</a></li>
  36 <li><a href="#button_state">button_state</a></li>
  37 <li><a href="#button_x_button_y">button_x, button_y</a></li>
  38 </ul>
  39 </li>
  40 <li><a href="#Joystick_axis_events">Joystick axis events</a>
  41 <ul><li><a href="#jaxis_which">jaxis_which</a></li>
  42 <li><a href="#jaxis_axis">jaxis_axis</a></li>
  43 <li><a href="#jaxis_value">jaxis_value</a></li>
  44 </ul>
  45 </li>
  46 <li><a href="#Joystick_button_events">Joystick button events</a>
  47 <ul><li><a href="#jbutton_which">jbutton_which</a></li>
  48 <li><a href="#jbutton_button">jbutton_button</a></li>
  49 <li><a href="#jbutton_state">jbutton_state</a></li>
  50 </ul>
  51 </li>
  52 <li><a href="#Joystick_hat_events">Joystick hat events</a>
  53 <ul><li><a href="#jhat_which">jhat_which</a></li>
  54 <li><a href="#jhat_hat">jhat_hat</a></li>
  55 <li><a href="#jhat_value">jhat_value</a></li>
  56 </ul>
  57 </li>
  58 <li><a href="#Joystrick_trackball_events">Joystrick trackball events</a>
  59 <ul><li><a href="#jball_which">jball_which</a></li>
  60 <li><a href="#jball_ball">jball_ball</a></li>
  61 <li><a href="#jball_xrel_jball_yrel">jball_xrel, jball_yrel</a></li>
  62 </ul>
  63 </li>
  64 <li><a href="#Window_resize_events">Window resize events</a>
  65 <ul><li><a href="#resize_w_resize_h">resize_w, resize_h</a></li>
  66 </ul>
  67 </li>
  68 <li><a href="#Window_expose_events">Window expose events</a></li>
  69 <li><a href="#System_window_manager_events">System window manager events</a>
  70 <ul><li><a href="#syswm_msg">syswm_msg</a></li>
  71 </ul>
  72 </li>
  73 <li><a href="#User_defined_events">User defined events</a>
  74 <ul><li><a href="#user_code">user_code</a></li>
  75 <li><a href="#user_data1_user_data2">user_data1, user_data2</a></li>
  76 </ul>
  77 </li>
  78 <li><a href="#Quit_event">Quit event</a></li>
  79 </ul>
  80 </li>
  81 <li><a href="#AUTHORS">AUTHORS</a></li>
  82 <li><a href="#SEE_ALSO">SEE ALSO</a>
  83 </li>
  84 </ul><hr />
  85 <!-- INDEX END -->
  86
  87 <h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
  88 <div id="NAME_CONTENT">
  89 <p>SDL::Event - General event structure</p>
  90
  91 </div>
  92 <h2 id="CATEGORY">CATEGORY</h2>
  93 <div id="CATEGORY_CONTENT">
  94 <p>Core, Events, Structure</p>
  95
  96 </div>
  97 <h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p>
  98 <div id="SYNOPSIS_CONTENT">
  99 <pre> use SDL::Event;  # for the event object itself
 100  use SDL::Events; # functions for event queue handling
 101
 102  SDL::init(SDL_INIT_VIDEO);
 103  my $event = SDL::Event-&gt;new();
 104
 105  while(1)
 106  {
 107      SDL::Events::pump_events();
 108
 109      if(SDL::Events::poll_event($event))
 110      {
 111         if($event-&gt;type == SDL_MOUSEBUTTONDOWN)
 112         {
 113             # now you can handle the details
 114             $event-&gt;button_which;
 115             $event-&gt;button_button;
 116             $event-&gt;button_x;
 117             $event-&gt;button_y;
 118         }
 119
 120         last if $event-&gt;type == SDL_QUIT;
 121      }
 122
 123      # your screen drawing code will be here
 124  }
 125
 126 </pre>
 127
 128 </div>
 129 <h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p>
 130 <div id="DESCRIPTION_CONTENT">
 131 <p>Event handling allows your application to receive input from the user.
 132 Event handling is initalised (along with video) with a call to:</p>
 133 <p><code>SDL::init(SDL_INIT_VIDEO);</code></p>
 134 <p>Internally, SDL stores all the events waiting to be handled in an event queue.
 135 Using functions like <code>SDL::Events::poll_event()</code>, <code>SDL::Events::peep_events</code>
 136 and <code>SDL::Events::wait_event()</code> you can observe and handle waiting input events.</p>
 137 <p>The key to event handling in SDL is the <code>SDL::Event</code> union.
 138 The event queue itself is composed of a series of <code>SDL::Event</code> unions, one for each waiting event.
 139 <code>SDL::Event</code> unions are read from the queue with the <code>SDL::Events::poll_event()</code> function
 140 and it is then up to the application to process the information stored with them. </p>
 141
 142 </div>
 143 <h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
 144 <div id="METHODS_CONTENT">
 145
 146 </div>
 147 <h2 id="new">new</h2>
 148 <div id="new_CONTENT">
 149 <p><code>new</code> creates an empty event-object, which can be used store information.
 150 Either by calling <code>poll_event($event)</code> that transferes one event from the queue into our object
 151 or by setting all the needed data manually in order to push the event to the queue.</p>
 152 <pre> use SDL::Event;
 153
 154  my $event = SDL::Event-&gt;new();
 155
 156 </pre>
 157
 158 </div>
 159 <h2 id="type">type</h2>
 160 <div id="type_CONTENT">
 161 <p>SDL::Event is a union of all event structures used in SDL, using it is a simple matter of knowing
 162 which union member relates to which event <code>type</code>.</p>
 163 <pre> print 'heureka' if $event-&gt;type == SDL_MOUSEBUTTONDOWN;
 164
 165 </pre>
 166 <p>Available type constants:</p>
 167 <ul>
 168                 <li><a href="#active">SDL_ACTIVEEVENT</a> - Application visibility event structure      </li>
 169                 <li><a href="#active">SDL_KEYDOWN</a> - Keyboard event structure        </li>
 170                 <li><a href="#active">SDL_KEYUP</a> - Keyboard event structure  </li>
 171                 <li><a href="#active">SDL_MOUSEMOTION</a> - Mouse motion event structure        </li>
 172                 <li><a href="#active">SDL_MOUSEBUTTONDOWN</a> - Mouse button event structure    </li>
 173                 <li><a href="#button">SDL_MOUSEBUTTONUP</a> - Mouse button event structure      </li>
 174                 <li><a href="#active">SDL_JOYAXISMOTION</a> - Joystick axis motion event structure      </li>
 175                 <li><a href="#active">SDL_JOYBALLMOTION</a> - Joystick trackball motion event structure         </li>
 176                 <li><a href="#active">SDL_JOYHATMOTION</a> - Joystick hat position change event structure       </li>
 177                 <li><a href="#active">SDL_JOYBUTTONDOWN</a> - Joystick button event structure   </li>
 178                 <li><a href="#active">SDL_JOYBUTTONUP</a> - Joystick button event structure     </li>
 179                 <li><a href="#active">SDL_VIDEORESIZE</a> - Window resize event structure       </li>
 180                 <li><a href="#active">SDL_VIDEOEXPOSE</a> - Window expose event         </li>
 181                 <li><a href="#active">SDL_QUIT</a> - Quit requested event       </li>
 182                 <li><a href="#active">SDL_USEREVENT</a> - A user-defined event type     </li>
 183                 <li><a href="#active">SDL_SYSWMEVENT</a> - Platform-dependent window manager event. </li>
 184 </ul>
 185
 186 <p>Event types are grouped by masks. <code>SDL_EVENTMASK($type)</code> will return the proper mask for the given <code>type</code>.</p>
 187 <p>Available event mask constants:</p>
 188 <ul>
 189                 <li>SDL_ACTIVEEVENTMASK </li>
 190                 <li>SDL_KEYDOWNMASK     </li>
 191                 <li>SDL_KEYUPMASK       </li>
 192                 <li>SDL_KEYEVENTMASK    </li>
 193                 <li>SDL_MOUSEMOTIONMASK </li>
 194                 <li>SDL_MOUSEBUTTONDOWNMASK     </li>
 195                 <li>SDL_MOUSEBUTTONUPMASK       </li>
 196                 <li>SDL_MOUSEEVENTMASK  </li>
 197                 <li>SDL_JOYAXISMOTIONMASK       </li>
 198                 <li>SDL_JOYBALLMOTIONMASK       </li>
 199                 <li>SDL_JOYHATMOTIONMASK        </li>
 200                 <li>SDL_JOYBUTTONDOWNMASK       </li>
 201                 <li>SDL_JOYBUTTONUPMASK </li>
 202                 <li>SDL_JOYEVENTMASK    </li>
 203                 <li>SDL_VIDEORESIZEMASK </li>
 204                 <li>SDL_VIDEOEXPOSEMASK </li>
 205                 <li>SDL_QUITMASK        </li>
 206                 <li>SDL_SYSWMEVENTMASK</li>
 207 </ul>
 208
 209 <p>This way you can check if a given <code>type</code> matches a mask:</p>
 210 <pre> (SDL_JOYBUTTONDOWN   &amp; SDL_MOUSEEVENTMASK) # is false
 211  (SDL_MOUSEBUTTONDOWN &amp; SDL_MOUSEEVENTMASK) # is true
 212  (SDL_MOUSEBUTTONUP   &amp; SDL_MOUSEEVENTMASK) # is true
 213  (SDL_MOUSEMOTION     &amp; SDL_MOUSEEVENTMASK) # is true
 214
 215  # and also true is:
 216
 217  (SDL_MOUSEEVENTMASK == SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN)
 218                       | SDL_EVENTMASK(SDL_MOUSEBUTTONUP)
 219                       | SDL_EVENTMASK(SDL_MOUSEMOTION))
 220
 221 </pre>
 222
 223 </div>
 224 <h2 id="Application_visibility_events">Application visibility events</h2>
 225 <div id="Application_visibility_events_CONTEN">
 226 <p><code>active</code> is used when an event of type <code>SDL_ACTIVEEVENT</code> is reported.</p>
 227 <p>When the mouse leaves or enters the window area a <code>SDL_APPMOUSEFOCUS</code> type activation event occurs,
 228 if the mouse entered the window then <strong>gain</strong> will be 1, otherwise <strong>gain</strong> will be 0. </p>
 229 <p>A <code>SDL_APPINPUTFOCUS</code> type activation event occurs when the application loses or gains keyboard focus.
 230 This usually occurs when another application is made active. </p>
 231 <p>Finally, a <code>SDL_APPACTIVE</code> type event occurs when the application is either minimised/iconified (<strong>gain</strong>=0) or restored. </p>
 232 <p>A single event can have multiple values set in <strong>state</strong>.</p>
 233 <p><strong>Note:</strong> This event does not occur when an application window is first created. </p>
 234 <p>A new ActiveEvent (to fake focus loss) will be created like this:</p>
 235 <pre> my $event = SDL::Event-&gt;new();
 236     $event-&gt;type(SDL_ACTIVEEVENT);
 237     $event-&gt;active_gain(0);
 238     $event-&gt;active_state(SDL_APPMOUSEFOCUS);
 239
 240  # I think this is wrong, -&gt;active_type() should get SDL_APPMOUSEFOCUS, but what state gets?
 241
 242 </pre>
 243
 244 </div>
 245 <h3 id="active_gain">active_gain</h3>
 246 <div id="active_gain_CONTENT">
 247 <p>See <code>active</code>. 0 if the event is a loss or 1 if it is a gain.</p>
 248
 249 </div>
 250 <h3 id="active_state">active_state</h3>
 251 <div id="active_state_CONTENT">
 252 <p>A bitmask of the following values: SDL_APPMOUSEFOCUS if mouse focus was gained or lost,
 253 SDL_APPINPUTFOCUS if input focus was gained or lost, and SDL_APPACTIVE if the application was iconified (gain=0) or restored(gain=1).</p>
 254
 255 </div>
 256 <h2 id="Keyboard_events">Keyboard events</h2>
 257 <div id="Keyboard_events_CONTENT">
 258 <p><code>key</code> is used when an event of type <code>SDL_KEYDOWN</code> or <code>SDL_KEYUP</code> is reported.</p>
 259 <p>The type and state actually report the same information, they just use different values to do it.
 260 A keyboard event generally occurs when a key is released (<code>type=SDL_KEYUP</code> or <code>key_state=SDL_RELEASED</code>)
 261 and when a key is pressed (<code>type=SDL_KEYDOWN</code> or <code>key_state=SDL_PRESSED</code>). </p>
 262 <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,
 263 then an <code>SDL_RELEASED</code> when released and pressed again. For these keys <code>KEYUP</code> and <code>KEYDOWN</code> events are therefore
 264 analogous to the state of the caps lock and num lock LEDs rather than the keys themselves.
 265 These special cases are required for compatibility with Sun workstations.</p>
 266 <p><strong>Note:</strong> Repeating <code>SDL_KEYDOWN</code> events will occur if key repeat is enabled (see <code>SDL_EnableKeyRepeat</code>). </p>
 267
 268 </div>
 269 <h3 id="key_state">key_state</h3>
 270 <div id="key_state_CONTENT">
 271 <p><code>SDL_PRESSED</code> or <code>SDL_RELEASED</code></p>
 272
 273 </div>
 274 <h3 id="key_scancode">key_scancode</h3>
 275 <div id="key_scancode_CONTENT">
 276 <p>The <code>scancode</code> field should generally be left alone, it is the hardware-dependent scancode returned by the keyboard.</p>
 277
 278 </div>
 279 <h3 id="key_sym">key_sym</h3>
 280 <div id="key_sym_CONTENT">
 281 <p>The <code>sym</code> field is extremely useful. It is the SDL-defined value of the key (see the keysym definitions in SDLKey).
 282 This field is very useful when you are checking for certain key presses, like so: </p>
 283 <pre> while(poll_event($event))
 284  {
 285      switch($event-&gt;type)
 286      {
 287          case SDL_KEYDOWN:
 288              move_left() if($event-&gt;key_sym == SDLK_LEFT);
 289              break;
 290          .
 291          .
 292          .
 293      }
 294  }
 295
 296 </pre>
 297
 298 </div>
 299 <h3 id="key_mod">key_mod</h3>
 300 <div id="key_mod_CONTENT">
 301 <p><code>mod</code> stores the current state of the keyboard modifiers as explained in SDL_GetModState.</p>
 302
 303 </div>
 304 <h3 id="key_unicode">key_unicode</h3>
 305 <div id="key_unicode_CONTENT">
 306 <p>The <code>unicode</code> field is only used when UNICODE translation is enabled with SDL_EnableUNICODE.
 307 If <code>unicode</code> is non-zero then this is the UNICODE character corresponding to the keypress.
 308 If the high 9 bits of the character are 0, then this maps to the equivalent ASCII character:</p>
 309 <pre> my $char;
 310  if(($event-&gt;key_unicode &amp; 0xFF80) == 0)
 311  {
 312      $char = $event-&gt;key_unicode &amp; 0x7F;
 313  }
 314  else
 315  {
 316      print(&quot;An International Character.\n&quot;);
 317  }
 318
 319 </pre>
 320 <p>UNICODE translation does create a slight overhead so don't enable it unless its needed.</p>
 321 <p>NOTE: Key release events (SDL_KEYUP) won't necessarily (ever?) contain unicode information.
 322 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>
 323
 324 </div>
 325 <h2 id="Mouse_motion_events">Mouse motion events</h2>
 326 <div id="Mouse_motion_events_CONTENT">
 327 <p>Simply put, a SDL_MOUSEMOTION type event occurs when a user moves the mouse within the
 328 application window or when SDL_WarpMouse is called. Both the absolute (<code>motion_x</code> and <code>motion_y</code>)
 329 and relative (<code>motion_xrel</code> and <code>motion_yrel</code>) coordinates are reported along with the current
 330 button states (<code>motion_state</code>).</p>
 331
 332 </div>
 333 <h3 id="motion_state">motion_state</h3>
 334 <div id="motion_state_CONTENT">
 335 <p>The button state can be interpreted using the <code>SDL_BUTTON</code> macro (see SDL_GetMouseState). </p>
 336
 337 </div>
 338 <h3 id="motion_x_motion_y">motion_x, motion_y</h3>
 339 <div id="motion_x_motion_y_CONTENT">
 340 <p>The X/Y coordinates of the mouse</p>
 341
 342 </div>
 343 <h3 id="motion_xrel_motion_yrel">motion_xrel, motion_yrel</h3>
 344 <div id="motion_xrel_motion_yrel_CONTENT">
 345 <p>Relative motion in the X/Y direction.</p>
 346 <p>If the cursor is hidden (SDL_ShowCursor(0)) and the input is grabbed (SDL_WM_GrabInput(SDL_GRAB_ON)),
 347 then the mouse will give relative motion events even when the cursor reaches the edge of the screen.
 348 This is currently only implemented on Windows and Linux/Unix-alikes.</p>
 349
 350 </div>
 351 <h2 id="Mouse_button_events">Mouse button events</h2>
 352 <div id="Mouse_button_events_CONTENT">
 353 <p>When a mouse button press or release is detected the number of the button pressed (from 1 to 255,
 354 with 1 usually being the left button and 2 the right) is placed into <code>button_button</code>, the position of the mouse
 355 when this event occured is stored in the <code>button_x</code> and the <code>button_y</code> fields. Like SDL_KeyboardEvent,
 356 information on whether the event was a press or a release event is stored in both the <code>button_type</code>
 357 and <code>button_state</code> fields, but this should be obvious.</p>
 358 <p>Mouse wheel events are reported as buttons 4 (up) and 5 (down). Two events are generated i.e. you get
 359 a <code>SDL_MOUSEBUTTONDOWN</code> followed by a <code>SDL_MOUSEBUTTONUP</code> event.</p>
 360
 361 </div>
 362 <h3 id="button_which">button_which</h3>
 363 <div id="button_which_CONTENT">
 364 <p>The input device index</p>
 365
 366 </div>
 367 <h3 id="button_button">button_button</h3>
 368 <div id="button_button_CONTENT">
 369 <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>,
 370 <code>SDL_BUTTON_WHEELDOWN</code>)</p>
 371
 372 </div>
 373 <h3 id="button_state">button_state</h3>
 374 <div id="button_state_CONTENT">
 375 <p><code>SDL_PRESSED</code> or <code>SDL_RELEASED</code></p>
 376
 377 </div>
 378 <h3 id="button_x_button_y">button_x, button_y</h3>
 379 <div id="button_x_button_y_CONTENT">
 380 <p>The X/Y coordinates of the mouse at press/release time</p>
 381
 382 </div>
 383 <h2 id="Joystick_axis_events">Joystick axis events</h2>
 384 <div id="Joystick_axis_events_CONTENT">
 385 <p>A <code>SDL_JOYAXISMOTION</code> event occurs whenever a user moves an axis on the joystick.</p>
 386
 387 </div>
 388 <h3 id="jaxis_which">jaxis_which</h3>
 389 <div id="jaxis_which_CONTENT">
 390 <p>The field <code>jaxis_which</code> is the index of the joystick that reported the event.</p>
 391
 392 </div>
 393 <h3 id="jaxis_axis">jaxis_axis</h3>
 394 <div id="jaxis_axis_CONTENT">
 395 <p>The <code>jaxis_axis</code> is the index of the axis (for a more detailed explaination see the Joystick section).</p>
 396
 397 </div>
 398 <h3 id="jaxis_value">jaxis_value</h3>
 399 <div id="jaxis_value_CONTENT">
 400 <p><code>jaxis_value</code> is the current position of the axis (range: -32768 to 32767).</p>
 401
 402 </div>
 403 <h2 id="Joystick_button_events">Joystick button events</h2>
 404 <div id="Joystick_button_events_CONTENT">
 405 <p>A <code>SDL_JOYBUTTONDOWN</code> or <code>SDL_JOYBUTTONUP</code> event occurs when ever a user presses
 406 or releases a button on a joystick.</p>
 407
 408 </div>
 409 <h3 id="jbutton_which">jbutton_which</h3>
 410 <div id="jbutton_which_CONTENT">
 411 <p>The field <code>jbutton_which</code> is the index of the joystick that reported the event.</p>
 412
 413 </div>
 414 <h3 id="jbutton_button">jbutton_button</h3>
 415 <div id="jbutton_button_CONTENT">
 416 <p>The <code>jbutton_button</code> is the index of the button (for a more detailed explanation see the Joystick section).</p>
 417
 418 </div>
 419 <h3 id="jbutton_state">jbutton_state</h3>
 420 <div id="jbutton_state_CONTENT">
 421 <p><code>jbutton_state</code> is the current state of the button which is either <code>jbutton_SDL_PRESSED</code>
 422 or <code>jbutton_SDL_RELEASED</code>. </p>
 423
 424 </div>
 425 <h2 id="Joystick_hat_events">Joystick hat events</h2>
 426 <div id="Joystick_hat_events_CONTENT">
 427 <p>A <code>SDL_JOYHATMOTION</code> event occurs when ever a user moves a hat on the joystick. </p>
 428
 429 </div>
 430 <h3 id="jhat_which">jhat_which</h3>
 431 <div id="jhat_which_CONTENT">
 432 <p>The field <code>jhat_which</code> is the index of the joystick that reported the event.</p>
 433
 434 </div>
 435 <h3 id="jhat_hat">jhat_hat</h3>
 436 <div id="jhat_hat_CONTENT">
 437 <p><code>jhat_hat</code> is the index of the hat (for a more detailed explanation see the Joystick section).</p>
 438
 439 </div>
 440 <h3 id="jhat_value">jhat_value</h3>
 441 <div id="jhat_value_CONTENT">
 442 <p><code>jhat_value</code> is the current position of the hat. It is a bitwise OR'd combination of the following
 443 values (whose meanings should be pretty obvious):</p>
 444 <ul>
 445                 <li><code>SDL_HAT_CENTERED</code>       </li>
 446                 <li><code>SDL_HAT_UP</code>     </li>
 447                 <li><code>SDL_HAT_RIGHT</code>  </li>
 448                 <li><code>SDL_HAT_DOWN</code>   </li>
 449                 <li><code>SDL_HAT_LEFT</code></li>
 450 </ul>
 451
 452 <p>The following defines are also provided:</p>
 453 <ul>
 454                 <li><code>SDL_HAT_RIGHTUP</code>        </li>
 455                 <li><code>SDL_HAT_RIGHTDOWN</code>      </li>
 456                 <li><code>SDL_HAT_LEFTUP</code> </li>
 457                 <li><code>SDL_HAT_LEFTDOWN</code></li>
 458 </ul>
 459
 460
 461 </div>
 462 <h2 id="Joystrick_trackball_events">Joystrick trackball events</h2>
 463 <div id="Joystrick_trackball_events_CONTENT">
 464 <p>A <code>SDL_JOYBALLMOTION</code> event occurs when a user moves a trackball on the joystick.</p>
 465
 466 </div>
 467 <h3 id="jball_which">jball_which</h3>
 468 <div id="jball_which_CONTENT">
 469 <p>The field <code>jball_which</code> is the index of the joystick that reported the event.</p>
 470
 471 </div>
 472 <h3 id="jball_ball">jball_ball</h3>
 473 <div id="jball_ball_CONTENT">
 474 <p><code>jball_ball</code> is the index of the trackball (for a more detailed explanation see the Joystick section).</p>
 475
 476 </div>
 477 <h3 id="jball_xrel_jball_yrel">jball_xrel, jball_yrel</h3>
 478 <div id="jball_xrel_jball_yrel_CONTENT">
 479 <p>Trackballs only return relative motion, this is the change in position on the ball since it was last
 480 polled (last cycle of the event loop) and it is stored in <code>jball_xrel</code> and <code>jball_yrel</code>.</p>
 481
 482 </div>
 483 <h2 id="Window_resize_events">Window resize events</h2>
 484 <div id="Window_resize_events_CONTENT">
 485
 486 </div>
 487 <h3 id="resize_w_resize_h">resize_w, resize_h</h3>
 488 <div id="resize_w_resize_h_CONTENT">
 489 <p>When <code>SDL_RESIZABLE</code> is passed as a flag to <code>SDL_SetVideoMode</code> the user is allowed to resize the
 490 applications window. When the window is resized an <code>SDL_VIDEORESIZE</code> is reported, with the new
 491 window width and height values stored in the resize structure's <code>resize_w</code> and <code>resize_h</code>.
 492 When an <code>SDL_VIDEORESIZE</code> is received the window should be resized to the new dimensions using
 493 SDL_SetVideoMode. </p>
 494
 495 </div>
 496 <h2 id="Window_expose_events">Window expose events</h2>
 497 <div id="Window_expose_events_CONTENT">
 498 <p>A <code>VIDEOEXPOSE</code> event is triggered when the screen has been modified outside of the application,
 499 usually by the window manager and needs to be redrawn.</p>
 500
 501 </div>
 502 <h2 id="System_window_manager_events">System window manager events</h2>
 503 <div id="System_window_manager_events_CONTENT">
 504 <p>The system window manager event contains a system-specific information about unknown window manager
 505 events. If you enable this event using <code>SDL_EventState</code>, it will be generated whenever unhandled
 506 events are received from the window manager. This can be used, for example, to implement cut-and-paste
 507 in your application.</p>
 508 <p>If you want to obtain system-specific information about the window manager, you can fill in the
 509 version member of a SDL_SysWMinfo structure (details can be found in SDL_syswm.h, which must be included)
 510 using the SDL_VERSION() macro found in SDL_version.h, and pass it to the function:</p>
 511 <pre> int SDL_GetWMInfo(SDL_SysWMinfo *info);
 512
 513 </pre>
 514 <p>See <a href="http://www.libsdl.org/cgi/docwiki.cgi/SDL_SysWMEvent">http://www.libsdl.org/cgi/docwiki.cgi/SDL_SysWMEvent</a></p>
 515
 516 </div>
 517 <h3 id="syswm_msg">syswm_msg</h3>
 518 <div id="syswm_msg_CONTENT">
 519
 520 </div>
 521 <h2 id="User_defined_events">User defined events</h2>
 522 <div id="User_defined_events_CONTENT">
 523 <p>This event is unique, it is never created by SDL but only by the user. The event can be pushed onto
 524 the event queue using <code>SDL::Events::push_event</code>. The contents of the structure members are completely up to the
 525 programmer, the only requirement is that type is a value from <code>SDL_USEREVENT</code> to <code>SDL_NUMEVENTS-1</code> (inclusive)</p>
 526 <pre> my $event = SDL::Event-&gt;new();
 527     $event-&gt;type ( SDL_USEREVENT + 3 );
 528     $event-&gt;event_code(10);
 529     $event-&gt;data1('hello event');
 530
 531  SDL::Events::push_event($event);
 532
 533 </pre>
 534
 535 </div>
 536 <h3 id="user_code">user_code</h3>
 537 <div id="user_code_CONTENT">
 538 <p>User defined event code (integer).</p>
 539
 540 </div>
 541 <h3 id="user_data1_user_data2">user_data1, user_data2</h3>
 542 <div id="user_data1_user_data2_CONTENT">
 543 <p>User defined data.</p>
 544
 545 </div>
 546 <h2 id="Quit_event">Quit event</h2>
 547 <div id="Quit_event_CONTENT">
 548 <p>As can be seen, the <code>SDL_QuitEvent</code> structure serves no useful purpose. The event itself, on the other hand,
 549 is very important. If you filter out or ignore a quit event then it is impossible for the user to close the
 550 window. On the other hand, if you do accept a quit event then the application window will be closed, and
 551 screen updates will still report success even though the application will no longer be visible.</p>
 552 <p><strong>Note</strong>: The macro SDL_QuitRequested will return non-zero if a quit event is pending </p>
 553
 554 </div>
 555 <h1 id="AUTHORS">AUTHORS</h1><p><a href="#TOP" class="toplink">Top</a></p>
 556 <div id="AUTHORS_CONTENT">
 557 <p>See <b>AUTHORS</b> in <cite>SDL</cite>.</p>
 558
 559 </div>
 560 <h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
 561 <div id="SEE_ALSO_CONTENT">
 562 <p><a href="http://search.cpan.org/perldoc?perl">perl</a>
 563 </p>
 564
 565 </div>
 566 </div>