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="#active">active</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="#key">key</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="#motion">motion</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="#button">button</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="#jaxis">jaxis</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="#jbutton">jbutton</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="#jhat">jhat</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="#jball">jball</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="#resize">resize</a>
  62 <ul><li><a href="#resize_x_resize_y">resize_x, resize_y</a></li>
  63 </ul>
  64 </li>
  65 <li><a href="#expose">expose</a></li>
  66 <li><a href="#syswm">syswm</a>
  67 <ul><li><a href="#syswm_msg">syswm_msg</a></li>
  68 </ul>
  69 </li>
  70 <li><a href="#user">user</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">quit</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="active">active</h2>
 217 <div id="active_CONTENT">
 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="key">key</h2>
 249 <div id="key_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
 269 </div>
 270 <h3 id="key_sym">key_sym</h3>
 271 <div id="key_sym_CONTENT">
 272
 273 </div>
 274 <h3 id="key_mod">key_mod</h3>
 275 <div id="key_mod_CONTENT">
 276
 277 </div>
 278 <h3 id="key_unicode">key_unicode</h3>
 279 <div id="key_unicode_CONTENT">
 280
 281 </div>
 282 <h2 id="motion">motion</h2>
 283 <div id="motion_CONTENT">
 284
 285 </div>
 286 <h3 id="motion_state">motion_state</h3>
 287 <div id="motion_state_CONTENT">
 288
 289 </div>
 290 <h3 id="motion_x_motion_y">motion_x, motion_y</h3>
 291 <div id="motion_x_motion_y_CONTENT">
 292
 293 </div>
 294 <h3 id="motion_xrel_motion_yrel">motion_xrel, motion_yrel</h3>
 295 <div id="motion_xrel_motion_yrel_CONTENT">
 296
 297 </div>
 298 <h2 id="button">button</h2>
 299 <div id="button_CONTENT">
 300
 301 </div>
 302 <h3 id="button_which">button_which</h3>
 303 <div id="button_which_CONTENT">
 304
 305 </div>
 306 <h3 id="button_button">button_button</h3>
 307 <div id="button_button_CONTENT">
 308
 309 </div>
 310 <h3 id="button_state">button_state</h3>
 311 <div id="button_state_CONTENT">
 312
 313 </div>
 314 <h3 id="button_x_button_y">button_x, button_y</h3>
 315 <div id="button_x_button_y_CONTENT">
 316
 317 </div>
 318 <h2 id="jaxis">jaxis</h2>
 319 <div id="jaxis_CONTENT">
 320
 321 </div>
 322 <h3 id="jaxis_which">jaxis_which</h3>
 323 <div id="jaxis_which_CONTENT">
 324
 325 </div>
 326 <h3 id="jaxis_axis">jaxis_axis</h3>
 327 <div id="jaxis_axis_CONTENT">
 328
 329 </div>
 330 <h3 id="jaxis_value">jaxis_value</h3>
 331 <div id="jaxis_value_CONTENT">
 332
 333 </div>
 334 <h2 id="jbutton">jbutton</h2>
 335 <div id="jbutton_CONTENT">
 336
 337 </div>
 338 <h3 id="jbutton_which">jbutton_which</h3>
 339 <div id="jbutton_which_CONTENT">
 340
 341 </div>
 342 <h3 id="jbutton_button">jbutton_button</h3>
 343 <div id="jbutton_button_CONTENT">
 344
 345 </div>
 346 <h3 id="jbutton_state">jbutton_state</h3>
 347 <div id="jbutton_state_CONTENT">
 348
 349 </div>
 350 <h2 id="jhat">jhat</h2>
 351 <div id="jhat_CONTENT">
 352
 353 </div>
 354 <h3 id="jhat_which">jhat_which</h3>
 355 <div id="jhat_which_CONTENT">
 356
 357 </div>
 358 <h3 id="jhat_hat">jhat_hat</h3>
 359 <div id="jhat_hat_CONTENT">
 360
 361 </div>
 362 <h3 id="jhat_value">jhat_value</h3>
 363 <div id="jhat_value_CONTENT">
 364
 365 </div>
 366 <h2 id="jball">jball</h2>
 367 <div id="jball_CONTENT">
 368
 369 </div>
 370 <h3 id="jball_which">jball_which</h3>
 371 <div id="jball_which_CONTENT">
 372
 373 </div>
 374 <h3 id="jball_ball">jball_ball</h3>
 375 <div id="jball_ball_CONTENT">
 376
 377 </div>
 378 <h3 id="jball_xrel_jball_yrel">jball_xrel, jball_yrel</h3>
 379 <div id="jball_xrel_jball_yrel_CONTENT">
 380
 381 </div>
 382 <h2 id="resize">resize</h2>
 383 <div id="resize_CONTENT">
 384
 385 </div>
 386 <h3 id="resize_x_resize_y">resize_x, resize_y</h3>
 387 <div id="resize_x_resize_y_CONTENT">
 388
 389 </div>
 390 <h2 id="expose">expose</h2>
 391 <div id="expose_CONTENT">
 392
 393 </div>
 394 <h2 id="syswm">syswm</h2>
 395 <div id="syswm_CONTENT">
 396
 397 </div>
 398 <h3 id="syswm_msg">syswm_msg</h3>
 399 <div id="syswm_msg_CONTENT">
 400
 401 </div>
 402 <h2 id="user">user</h2>
 403 <div id="user_CONTENT">
 404
 405 </div>
 406 <h3 id="user_code">user_code</h3>
 407 <div id="user_code_CONTENT">
 408
 409 </div>
 410 <h3 id="user_data1_user_data2">user_data1, user_data2</h3>
 411 <div id="user_data1_user_data2_CONTENT">
 412
 413 </div>
 414 <h2 id="quit">quit</h2>
 415 <div id="quit_CONTENT">
 416 <p>Create a new SDL::Event object.</p>
 417
 418 </div>
 419 <h1 id="AUTHOR">AUTHOR</h1><p><a href="#TOP" class="toplink">Top</a></p>
 420 <div id="AUTHOR_CONTENT">
 421
 422 </div>
 423 <h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
 424 <div id="SEE_ALSO_CONTENT">
 425 <p><cite>perl</cite></p>
 426
 427 </div>
 428 </div>