pages/SDL-Events.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="#pump_events">pump_events</a></li>
  13 <li><a href="#peep_events_event_num_events_action_">peep_events (event, num_events, action, mask) </a>
  14 <ul><li><a href="#RETURN">RETURN</a></li>
  15 </ul>
  16 </li>
  17 <li><a href="#poll_event_event">poll_event($event)</a>
  18 <ul><li><a href="#RETURN-2">RETURN</a></li>
  19 </ul>
  20 </li>
  21 <li><a href="#push_event_event">push_event($event)</a>
  22 <ul><li><a href="#RETURN-3">RETURN</a></li>
  23 </ul>
  24 </li>
  25 <li><a href="#wait_event_event">wait_event($event)</a>
  26 <ul><li><a href="#RETURN-4">RETURN</a></li>
  27 </ul>
  28 </li>
  29 <li><a href="#set_event_filter">set_event_filter</a></li>
  30 <li><a href="#get_key_state">get_key_state</a></li>
  31 <li><a href="#get_mod_state">get_mod_state</a></li>
  32 <li><a href="#set_mod_state">set_mod_state</a></li>
  33 <li><a href="#event_state">event_state </a></li>
  34 <li><a href="#get_key_name">get_key_name</a></li>
  35 <li><a href="#enable_unicode">enable_unicode </a></li>
  36 <li><a href="#enable_key_repeat">enable_key_repeat </a></li>
  37 <li><a href="#get_mouse_state">get_mouse_state </a></li>
  38 <li><a href="#get_relative_mouse_state">get_relative_mouse_state </a></li>
  39 <li><a href="#get_app_state">get_app_state </a></li>
  40 <li><a href="#joystick_event_state">joystick_event_state </a></li>
  41 </ul>
  42 </li>
  43 <li><a href="#SEE_ALSO">SEE ALSO</a>
  44 </li>
  45 </ul><hr />
  46 <!-- INDEX END -->
  47
  48 <h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
  49 <div id="NAME_CONTENT">
  50 <p>SDL::Events - Bindings to the Events Category in SDL API</p>
  51
  52 </div>
  53 <h2 id="CATEGORY">CATEGORY</h2>
  54 <div id="CATEGORY_CONTENT">
  55 <p>Core, Events</p>
  56
  57 </div>
  58 <h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p>
  59 <div id="SYNOPSIS_CONTENT">
  60 <p>Most likely you just want to know how to get events for you app.
  61   use SDL;
  62   use SDL::Event;
  63   use SDL::Events;</p>
  64 <pre>  SDL::init(SDL_INIT_VIDEO); # Event can only be grabbed in the same thread as this
  65
  66   ...
  67
  68   my $event = SDL::Event-&gt;new(); # notices 'Event' ne 'Events'
  69
  70   while( 1 )
  71         {
  72           SDL::Events::pump_events();
  73          while(  SDL::Events::poll_event($event) )
  74          {
  75                 #check by event type
  76                 on_active() if $event-&gt;type == SDL_ACTIVEEVENT;
  77                 ...
  78          }
  79         }
  80
  81 </pre>
  82
  83 </div>
  84 <h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p>
  85 <div id="DESCRIPTION_CONTENT">
  86
  87
  88
  89
  90
  91 </div>
  92 <h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
  93 <div id="METHODS_CONTENT">
  94
  95 </div>
  96 <h2 id="pump_events">pump_events</h2>
  97 <div id="pump_events_CONTENT">
  98 <p>Pumps the event loop, gathering events from the input devices.</p>
  99 <pre>   pump_events();
 100
 101 </pre>
 102 <p>pump_events gathers all the pending input information from devices and places it on the event queue. Without calls to pump_events no events would ever be placed on the queue.
 103 Often the need for calls to pump_events is hidden from the user since <a href="http://search.cpan.org/perldoc?poll_event">poll_event</a> and <a href="http://search.cpan.org/perldoc?wait_event">wait_event</a> implicitly call pump_events.
 104 However, if you are not polling or waiting for events (e.g. you are filtering them), then you must call pump_events to force an event queue update.</p>
 105
 106
 107
 108
 109
 110 </div>
 111 <h2 id="peep_events_event_num_events_action_">peep_events (event, num_events, action, mask) </h2>
 112 <div id="peep_events_event_num_events_action_-2">
 113 <p>Checks the event queue for messages and optionally returns them.  </p>
 114 <pre>   my $num_peep_events = SDL::Events::peep_events($event, 127, SDL_PEEKEVENT, SDL_ALLEVENTS);
 115
 116 </pre>
 117 <p>If action is SDL_ADDEVENT, up to numevents events will be added to the back of the event queue.</p>
 118 <p>If action is SDL_PEEKEVENT, up to numevents events at the front of the event queue, matching mask, will be returned and will not be removed from the queue.</p>
 119 <p>If action is SDL_GETEVENT, up to numevents events at the front of the event queue, matching mask, will be returned and will be removed from the queue.</p>
 120 <p>The mask parameter is a bitwise OR of SDL::Events::SDL_EVENTMASK(event_type), for all event types you are interested in</p>
 121 <p>This function is thread-safe.</p>
 122 <p>You may have to call pump_events before calling this function. Otherwise, the events may not be ready to be filtered when you call peep_events.</p>
 123 <p>Examples of mask:</p>
 124 <dl>
 125         <dt>SDL_EVENTMASK (SDL_KEYUP)</dt>
 126         <dt>(SDL_EVENTMASK (SDL_MOUSEBUTTONDOWN) | SDL_EVENTMASK (SDL_MOUSEBUTTONUP))</dt>
 127         <dt>SDL_ALLEVENTS</dt>
 128         <dt>SDL_KEYUPMASK</dt>
 129         <dt>SDL_ALLEVENTS ^ SDL_QUITMASK</dt>
 130 </dl>
 131
 132 </div>
 133 <h3 id="RETURN">RETURN</h3>
 134 <div id="RETURN_CONTENT">
 135 <p>Number of Events actually stored or -1 if there was an error</p>
 136
 137 </div>
 138 <h2 id="poll_event_event">poll_event($event)</h2>
 139 <div id="poll_event_event_CONTENT">
 140 <p>Polls for currently pending events. </p>
 141 <p>If $event is not NULL, the next event is removed from the queue and stored in the <a href="SDL-Event">SDL::Event</a> structure pointed to by $event.</p>
 142 <p>As this function implicitly calls pump_events, you can only call this function in the thread that set the video mode with <a href="/SDL-Video.html#set_video_mode">SDL::Video::set_video_mode</a>. </p>
 143
 144 </div>
 145 <h3 id="RETURN-2">RETURN</h3>
 146 <div id="RETURN_CONTENT-2">
 147 <p>Returns 1 if there are any pending events, or 0 if there are none available. </p>
 148
 149 </div>
 150 <h2 id="push_event_event">push_event($event)</h2>
 151 <div id="push_event_event_CONTENT">
 152 <p>Pushes an event onto the event queue </p>
 153 <p>The event queue can actually be used as a two way communication channel. Not only can events be read from the queue, but the user can also push their own events onto it. event is a pointer to the event structure you wish to push onto the queue.
 154 The event is copied into the queue, and the caller may dispose of the memory pointed to after push_event returns.</p>
 155 <p>Note: Pushing device input events onto the queue doesn't modify the state of the device within SDL. </p>
 156 <p>This function is thread safe, and can be called from other threads safely.</p>
 157
 158 </div>
 159 <h3 id="RETURN-3">RETURN</h3>
 160 <div id="RETURN_CONTENT-3">
 161 <p>Returns 0 on success or -1 if the event couldn't be pushed.</p>
 162
 163 </div>
 164 <h2 id="wait_event_event">wait_event($event)</h2>
 165 <div id="wait_event_event_CONTENT">
 166 <p>Waits indefinitely for the next available $event, returning 0 if there was an error while waiting for events, 1 otherwise.</p>
 167 <p>If $event is not NULL, the next event is removed from the queue and stored in $event.</p>
 168 <p>As this function implicitly calls SDL_PumpEvents, you can only call this function in the thread that  <a href="/SDL-Video.html#set_video_mode">SDL::Video::set_video_mode</a>.  </p>
 169
 170 </div>
 171 <h3 id="RETURN-4">RETURN</h3>
 172 <div id="RETURN_CONTENT-4">
 173 <p>0 if there was an error while waiting for events, 1 otherwise</p>
 174
 175 </div>
 176 <h2 id="set_event_filter">set_event_filter</h2>
 177 <div id="set_event_filter_CONTENT">
 178
 179 </div>
 180 <h2 id="get_key_state">get_key_state</h2>
 181 <div id="get_key_state_CONTENT">
 182
 183 </div>
 184 <h2 id="get_mod_state">get_mod_state</h2>
 185 <div id="get_mod_state_CONTENT">
 186
 187 </div>
 188 <h2 id="set_mod_state">set_mod_state</h2>
 189 <div id="set_mod_state_CONTENT">
 190
 191 </div>
 192 <h2 id="event_state">event_state </h2>
 193 <div id="event_state_CONTENT">
 194
 195 </div>
 196 <h2 id="get_key_name">get_key_name</h2>
 197 <div id="get_key_name_CONTENT">
 198
 199 </div>
 200 <h2 id="enable_unicode">enable_unicode </h2>
 201 <div id="enable_unicode_CONTENT">
 202
 203 </div>
 204 <h2 id="enable_key_repeat">enable_key_repeat </h2>
 205 <div id="enable_key_repeat_CONTENT">
 206
 207 </div>
 208 <h2 id="get_mouse_state">get_mouse_state </h2>
 209 <div id="get_mouse_state_CONTENT">
 210
 211 </div>
 212 <h2 id="get_relative_mouse_state">get_relative_mouse_state </h2>
 213 <div id="get_relative_mouse_state_CONTENT">
 214
 215 </div>
 216 <h2 id="get_app_state">get_app_state </h2>
 217 <div id="get_app_state_CONTENT">
 218
 219 </div>
 220 <h2 id="joystick_event_state">joystick_event_state </h2>
 221 <div id="joystick_event_state_CONTENT">
 222
 223
 224
 225
 226
 227 </div>
 228 <h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
 229 <div id="SEE_ALSO_CONTENT">
 230 <p><a href="SDL-Event">SDL::Event</a>, <a href="SDL-Video">SDL::Video</a>
 231 </p>
 232
 233 </div>
 234 </div>