[sdl_omap.git] / docs / html / sdlseteventfilter.html

<HTML
><HEAD
><TITLE
>SDL_SetEventFilter</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
"><LINK
REL="HOME"
TITLE="SDL Library Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="Event Functions."
HREF="eventfunctions.html"><LINK
REL="PREVIOUS"
TITLE="SDL_PushEvent"
HREF="sdlpushevent.html"><LINK
REL="NEXT"
TITLE="SDL_GetEventFilter"
HREF="sdlgeteventfilter.html"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFF8DC"
TEXT="#000000"
LINK="#0000ee"
VLINK="#551a8b"
ALINK="#ff0000"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>SDL Library Documentation</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="sdlpushevent.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="sdlgeteventfilter.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="SDLSETEVENTFILTER"
></A
>SDL_SetEventFilter</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN5575"
></A
><H2
>Name</H2
>SDL_SetEventFilter&nbsp;--&nbsp;Sets up a filter to process all events before they are posted 
to the event queue.</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN5578"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN5579"
></A
><P
></P
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include "SDL.h"</PRE
><P
><CODE
><CODE
CLASS="FUNCDEF"
>void <B
CLASS="FSFUNC"
>SDL_SetEventFilter</B
></CODE
>(SDL_EventFilter filter);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN5585"
></A
><H2
>Description</H2
><P
>This function sets up a filter to process all events before they are posted 
to the event queue.  This is a very powerful and flexible feature.  The filter 
is prototyped as:
<PRE
CLASS="PROGRAMLISTING"
>typedef int (*SDL_EventFilter)(const SDL_Event *event);</PRE
>
If the filter returns <SPAN
CLASS="RETURNVALUE"
>1</SPAN
>, then the event will be 
added to the internal queue.  If it returns <SPAN
CLASS="RETURNVALUE"
>0</SPAN
>, 
then the event will be dropped from the queue.  This allows selective
filtering of dynamically.</P
><P
>There is one caveat when dealing with the <TT
CLASS="LITERAL"
>SDL_QUITEVENT</TT
> event type.  The
event filter is only called when the window manager desires to close the
application window.  If the event filter returns 1, then the window will
be closed, otherwise the window will remain open if possible.
If the quit event is generated by an interrupt signal, it will bypass the
internal queue and be delivered to the application at the next event poll.</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>Events pushed onto the queue with <A
HREF="sdlpushevent.html"
><TT
CLASS="FUNCTION"
>SDL_PushEvent</TT
></A
> or <A
HREF="sdlpeepevents.html"
><TT
CLASS="FUNCTION"
>SDL_PeepEvents</TT
></A
> do not get passed through the event filter.</P
></BLOCKQUOTE
></DIV
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
><SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Be Careful!</I
></SPAN
> The event filter function may run in a different thread so be careful what you do within it.</P
></BLOCKQUOTE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN5602"
></A
><H2
>See Also</H2
><P
><A
HREF="sdlevent.html"
><SPAN
CLASS="STRUCTNAME"
>SDL_Event</SPAN
></A
>,
<A
HREF="sdlgeteventfilter.html"
><TT
CLASS="FUNCTION"
>SDL_GetEventFilter</TT
></A
>,
<A
HREF="sdlpushevent.html"
><TT
CLASS="FUNCTION"
>SDL_PushEvent</TT
></A
></P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="sdlpushevent.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="sdlgeteventfilter.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>SDL_PushEvent</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="eventfunctions.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>SDL_GetEventFilter</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
Commit	Line	Data
e14743d1	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 -- 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	>