docs/html/sdlseteventfilter.html

   1 <HTML
   2 ><HEAD
   3 ><TITLE
   4 >SDL_SetEventFilter</TITLE
   5 ><META
   6 NAME="GENERATOR"
   7 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
   8 "><LINK
   9 REL="HOME"
  10 TITLE="SDL Library Documentation"
  11 HREF="index.html"><LINK
  12 REL="UP"
  13 TITLE="Event Functions."
  14 HREF="eventfunctions.html"><LINK
  15 REL="PREVIOUS"
  16 TITLE="SDL_PushEvent"
  17 HREF="sdlpushevent.html"><LINK
  18 REL="NEXT"
  19 TITLE="SDL_GetEventFilter"
  20 HREF="sdlgeteventfilter.html"></HEAD
  21 ><BODY
  22 CLASS="REFENTRY"
  23 BGCOLOR="#FFF8DC"
  24 TEXT="#000000"
  25 LINK="#0000ee"
  26 VLINK="#551a8b"
  27 ALINK="#ff0000"
  28 ><DIV
  29 CLASS="NAVHEADER"
  30 ><TABLE
  31 SUMMARY="Header navigation table"
  32 WIDTH="100%"
  33 BORDER="0"
  34 CELLPADDING="0"
  35 CELLSPACING="0"
  36 ><TR
  37 ><TH
  38 COLSPAN="3"
  39 ALIGN="center"
  40 >SDL Library Documentation</TH
  41 ></TR
  42 ><TR
  43 ><TD
  44 WIDTH="10%"
  45 ALIGN="left"
  46 VALIGN="bottom"
  47 ><A
  48 HREF="sdlpushevent.html"
  49 ACCESSKEY="P"
  50 >Prev</A
  51 ></TD
  52 ><TD
  53 WIDTH="80%"
  54 ALIGN="center"
  55 VALIGN="bottom"
  56 ></TD
  57 ><TD
  58 WIDTH="10%"
  59 ALIGN="right"
  60 VALIGN="bottom"
  61 ><A
  62 HREF="sdlgeteventfilter.html"
  63 ACCESSKEY="N"
  64 >Next</A
  65 ></TD
  66 ></TR
  67 ></TABLE
  68 ><HR
  69 ALIGN="LEFT"
  70 WIDTH="100%"></DIV
  71 ><H1
  72 ><A
  73 NAME="SDLSETEVENTFILTER"
  74 ></A
  75 >SDL_SetEventFilter</H1
  76 ><DIV
  77 CLASS="REFNAMEDIV"
  78 ><A
  79 NAME="AEN5575"
  80 ></A
  81 ><H2
  82 >Name</H2
  83 >SDL_SetEventFilter&nbsp;--&nbsp;Sets up a filter to process all events before they are posted
  84 to the event queue.</DIV
  85 ><DIV
  86 CLASS="REFSYNOPSISDIV"
  87 ><A
  88 NAME="AEN5578"
  89 ></A
  90 ><H2
  91 >Synopsis</H2
  92 ><DIV
  93 CLASS="FUNCSYNOPSIS"
  94 ><A
  95 NAME="AEN5579"
  96 ></A
  97 ><P
  98 ></P
  99 ><PRE
 100 CLASS="FUNCSYNOPSISINFO"
 101 >#include "SDL.h"</PRE
 102 ><P
 103 ><CODE
 104 ><CODE
 105 CLASS="FUNCDEF"
 106 >void <B
 107 CLASS="FSFUNC"
 108 >SDL_SetEventFilter</B
 109 ></CODE
 110 >(SDL_EventFilter filter);</CODE
 111 ></P
 112 ><P
 113 ></P
 114 ></DIV
 115 ></DIV
 116 ><DIV
 117 CLASS="REFSECT1"
 118 ><A
 119 NAME="AEN5585"
 120 ></A
 121 ><H2
 122 >Description</H2
 123 ><P
 124 >This function sets up a filter to process all events before they are posted
 125 to the event queue.  This is a very powerful and flexible feature.  The filter
 126 is prototyped as:
 127 <PRE
 128 CLASS="PROGRAMLISTING"
 129 >typedef int (*SDL_EventFilter)(const SDL_Event *event);</PRE
 130 >
 131 If the filter returns <SPAN
 132 CLASS="RETURNVALUE"
 133 >1</SPAN
 134 >, then the event will be
 135 added to the internal queue.  If it returns <SPAN
 136 CLASS="RETURNVALUE"
 137 >0</SPAN
 138 >,
 139 then the event will be dropped from the queue.  This allows selective
 140 filtering of dynamically.</P
 141 ><P
 142 >There is one caveat when dealing with the <TT
 143 CLASS="LITERAL"
 144 >SDL_QUITEVENT</TT
 145 > event type.  The
 146 event filter is only called when the window manager desires to close the
 147 application window.  If the event filter returns 1, then the window will
 148 be closed, otherwise the window will remain open if possible.
 149 If the quit event is generated by an interrupt signal, it will bypass the
 150 internal queue and be delivered to the application at the next event poll.</P
 151 ><DIV
 152 CLASS="NOTE"
 153 ><BLOCKQUOTE
 154 CLASS="NOTE"
 155 ><P
 156 ><B
 157 >Note: </B
 158 >Events pushed onto the queue with <A
 159 HREF="sdlpushevent.html"
 160 ><TT
 161 CLASS="FUNCTION"
 162 >SDL_PushEvent</TT
 163 ></A
 164 > or <A
 165 HREF="sdlpeepevents.html"
 166 ><TT
 167 CLASS="FUNCTION"
 168 >SDL_PeepEvents</TT
 169 ></A
 170 > do not get passed through the event filter.</P
 171 ></BLOCKQUOTE
 172 ></DIV
 173 ><DIV
 174 CLASS="NOTE"
 175 ><BLOCKQUOTE
 176 CLASS="NOTE"
 177 ><P
 178 ><B
 179 >Note: </B
 180 ><SPAN
 181 CLASS="emphasis"
 182 ><I
 183 CLASS="EMPHASIS"
 184 >Be Careful!</I
 185 ></SPAN
 186 > The event filter function may run in a different thread so be careful what you do within it.</P
 187 ></BLOCKQUOTE
 188 ></DIV
 189 ></DIV
 190 ><DIV
 191 CLASS="REFSECT1"
 192 ><A
 193 NAME="AEN5602"
 194 ></A
 195 ><H2
 196 >See Also</H2
 197 ><P
 198 ><A
 199 HREF="sdlevent.html"
 200 ><SPAN
 201 CLASS="STRUCTNAME"
 202 >SDL_Event</SPAN
 203 ></A
 204 >,
 205 <A
 206 HREF="sdlgeteventfilter.html"
 207 ><TT
 208 CLASS="FUNCTION"
 209 >SDL_GetEventFilter</TT
 210 ></A
 211 >,
 212 <A
 213 HREF="sdlpushevent.html"
 214 ><TT
 215 CLASS="FUNCTION"
 216 >SDL_PushEvent</TT
 217 ></A
 218 ></P
 219 ></DIV
 220 ><DIV
 221 CLASS="NAVFOOTER"
 222 ><HR
 223 ALIGN="LEFT"
 224 WIDTH="100%"><TABLE
 225 SUMMARY="Footer navigation table"
 226 WIDTH="100%"
 227 BORDER="0"
 228 CELLPADDING="0"
 229 CELLSPACING="0"
 230 ><TR
 231 ><TD
 232 WIDTH="33%"
 233 ALIGN="left"
 234 VALIGN="top"
 235 ><A
 236 HREF="sdlpushevent.html"
 237 ACCESSKEY="P"
 238 >Prev</A
 239 ></TD
 240 ><TD
 241 WIDTH="34%"
 242 ALIGN="center"
 243 VALIGN="top"
 244 ><A
 245 HREF="index.html"
 246 ACCESSKEY="H"
 247 >Home</A
 248 ></TD
 249 ><TD
 250 WIDTH="33%"
 251 ALIGN="right"
 252 VALIGN="top"
 253 ><A
 254 HREF="sdlgeteventfilter.html"
 255 ACCESSKEY="N"
 256 >Next</A
 257 ></TD
 258 ></TR
 259 ><TR
 260 ><TD
 261 WIDTH="33%"
 262 ALIGN="left"
 263 VALIGN="top"
 264 >SDL_PushEvent</TD
 265 ><TD
 266 WIDTH="34%"
 267 ALIGN="center"
 268 VALIGN="top"
 269 ><A
 270 HREF="eventfunctions.html"
 271 ACCESSKEY="U"
 272 >Up</A
 273 ></TD
 274 ><TD
 275 WIDTH="33%"
 276 ALIGN="right"
 277 VALIGN="top"
 278 >SDL_GetEventFilter</TD
 279 ></TR
 280 ></TABLE
 281 ></DIV
 282 ></BODY
 283 ></HTML
 284 >