Mercurial > sdl-ios-xcode
view docs/html/sdlevent.html @ 4333:55717a755897 SDL-1.2
Switched from setting the period size and count to setting the buffer size directly, based on feedback from the ALSA development list:
http://mailman.alsa-project.org/pipermail/alsa-devel/2009-October/022267.html
This has the nice side effect of reducing latency on my SBLive! card.
author | Sam Lantinga <slouken@libsdl.org> |
---|---|
date | Tue, 13 Oct 2009 09:56:15 +0000 |
parents | 60fa95a89846 |
children |
line wrap: on
line source
<HTML ><HEAD ><TITLE >SDL_Event</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="SDL Event Structures." HREF="eventstructures.html"><LINK REL="PREVIOUS" TITLE="SDL Event Structures." HREF="eventstructures.html"><LINK REL="NEXT" TITLE="SDL_ActiveEvent" HREF="sdlactiveevent.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="eventstructures.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="80%" ALIGN="center" VALIGN="bottom" ></TD ><TD WIDTH="10%" ALIGN="right" VALIGN="bottom" ><A HREF="sdlactiveevent.html" ACCESSKEY="N" >Next</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><H1 ><A NAME="SDLEVENT" ></A >SDL_Event</H1 ><DIV CLASS="REFNAMEDIV" ><A NAME="AEN3711" ></A ><H2 >Name</H2 >SDL_Event -- General event structure</DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN3714" ></A ><H2 >Structure Definition</H2 ><PRE CLASS="PROGRAMLISTING" >typedef union{ Uint8 type; SDL_ActiveEvent active; SDL_KeyboardEvent key; SDL_MouseMotionEvent motion; SDL_MouseButtonEvent button; SDL_JoyAxisEvent jaxis; SDL_JoyBallEvent jball; SDL_JoyHatEvent jhat; SDL_JoyButtonEvent jbutton; SDL_ResizeEvent resize; SDL_ExposeEvent expose; SDL_QuitEvent quit; SDL_UserEvent user; SDL_SysWMEvent syswm; } SDL_Event;</PRE ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN3717" ></A ><H2 >Structure Data</H2 ><DIV CLASS="INFORMALTABLE" ><A NAME="AEN3719" ></A ><P ></P ><TABLE BORDER="0" CLASS="CALSTABLE" ><TBODY ><TR ><TD ALIGN="LEFT" VALIGN="TOP" ><TT CLASS="STRUCTFIELD" ><I >type</I ></TT ></TD ><TD ALIGN="LEFT" VALIGN="TOP" >The type of event</TD ></TR ><TR ><TD ALIGN="LEFT" VALIGN="TOP" ><TT CLASS="STRUCTFIELD" ><I >active</I ></TT ></TD ><TD ALIGN="LEFT" VALIGN="TOP" ><A HREF="sdlactiveevent.html" >Activation event</A ></TD ></TR ><TR ><TD ALIGN="LEFT" VALIGN="TOP" ><TT CLASS="STRUCTFIELD" ><I >key</I ></TT ></TD ><TD ALIGN="LEFT" VALIGN="TOP" ><A HREF="sdlkeyboardevent.html" >Keyboard event</A ></TD ></TR ><TR ><TD ALIGN="LEFT" VALIGN="TOP" ><TT CLASS="STRUCTFIELD" ><I >motion</I ></TT ></TD ><TD ALIGN="LEFT" VALIGN="TOP" ><A HREF="sdlmousemotionevent.html" >Mouse motion event</A ></TD ></TR ><TR ><TD ALIGN="LEFT" VALIGN="TOP" ><TT CLASS="STRUCTFIELD" ><I >button</I ></TT ></TD ><TD ALIGN="LEFT" VALIGN="TOP" ><A HREF="sdlmousebuttonevent.html" >Mouse button event</A ></TD ></TR ><TR ><TD ALIGN="LEFT" VALIGN="TOP" ><TT CLASS="STRUCTFIELD" ><I >jaxis</I ></TT ></TD ><TD ALIGN="LEFT" VALIGN="TOP" ><A HREF="sdljoyaxisevent.html" >Joystick axis motion event</A ></TD ></TR ><TR ><TD ALIGN="LEFT" VALIGN="TOP" ><TT CLASS="STRUCTFIELD" ><I >jball</I ></TT ></TD ><TD ALIGN="LEFT" VALIGN="TOP" ><A HREF="sdljoyballevent.html" >Joystick trackball motion event</A ></TD ></TR ><TR ><TD ALIGN="LEFT" VALIGN="TOP" ><TT CLASS="STRUCTFIELD" ><I >jhat</I ></TT ></TD ><TD ALIGN="LEFT" VALIGN="TOP" ><A HREF="sdljoyhatevent.html" >Joystick hat motion event</A ></TD ></TR ><TR ><TD ALIGN="LEFT" VALIGN="TOP" ><TT CLASS="STRUCTFIELD" ><I >jbutton</I ></TT ></TD ><TD ALIGN="LEFT" VALIGN="TOP" ><A HREF="sdljoybuttonevent.html" >Joystick button event</A ></TD ></TR ><TR ><TD ALIGN="LEFT" VALIGN="TOP" ><TT CLASS="STRUCTFIELD" ><I >resize</I ></TT ></TD ><TD ALIGN="LEFT" VALIGN="TOP" ><A HREF="sdlresizeevent.html" >Application window resize event</A ></TD ></TR ><TR ><TD ALIGN="LEFT" VALIGN="TOP" ><TT CLASS="STRUCTFIELD" ><I >expose</I ></TT ></TD ><TD ALIGN="LEFT" VALIGN="TOP" ><A HREF="sdlexposeevent.html" >Application window expose event</A ></TD ></TR ><TR ><TD ALIGN="LEFT" VALIGN="TOP" ><TT CLASS="STRUCTFIELD" ><I >quit</I ></TT ></TD ><TD ALIGN="LEFT" VALIGN="TOP" ><A HREF="sdlquitevent.html" >Application quit request event</A ></TD ></TR ><TR ><TD ALIGN="LEFT" VALIGN="TOP" ><TT CLASS="STRUCTFIELD" ><I >user</I ></TT ></TD ><TD ALIGN="LEFT" VALIGN="TOP" ><A HREF="sdluserevent.html" >User defined event</A ></TD ></TR ><TR ><TD ALIGN="LEFT" VALIGN="TOP" ><TT CLASS="STRUCTFIELD" ><I >syswm</I ></TT ></TD ><TD ALIGN="LEFT" VALIGN="TOP" ><A HREF="sdlsyswmevent.html" >Undefined window manager event</A ></TD ></TR ></TBODY ></TABLE ><P ></P ></DIV ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN3791" ></A ><H2 >Description</H2 ><P >The <SPAN CLASS="STRUCTNAME" >SDL_Event</SPAN > union is the core to all event handling is SDL, its probably the most important structure after <SPAN CLASS="STRUCTNAME" >SDL_Surface</SPAN >. <SPAN CLASS="STRUCTNAME" >SDL_Event</SPAN > is a union of all event structures used in SDL, using it is a simple matter of knowing which union member relates to which event <TT CLASS="STRUCTFIELD" ><I >type</I ></TT >.</P ><P ><DIV CLASS="INFORMALTABLE" ><A NAME="AEN3799" ></A ><P ></P ><TABLE BORDER="1" CLASS="CALSTABLE" ><THEAD ><TR ><TH ALIGN="LEFT" VALIGN="TOP" >Event <TT CLASS="STRUCTFIELD" ><I >type</I ></TT ></TH ><TH ALIGN="LEFT" VALIGN="TOP" >Event Structure</TH ></TR ></THEAD ><TBODY ><TR ><TD ALIGN="LEFT" VALIGN="MIDDLE" ><TT CLASS="LITERAL" >SDL_ACTIVEEVENT</TT ></TD ><TD ALIGN="LEFT" VALIGN="MIDDLE" ><A HREF="sdlactiveevent.html" ><SPAN CLASS="STRUCTNAME" >SDL_ActiveEvent</SPAN ></A ></TD ></TR ><TR ><TD ALIGN="LEFT" VALIGN="TOP" ><TT CLASS="LITERAL" >SDL_KEYDOWN/UP</TT ></TD ><TD ALIGN="LEFT" VALIGN="TOP" ><A HREF="sdlkeyboardevent.html" ><SPAN CLASS="STRUCTNAME" >SDL_KeyboardEvent</SPAN ></A ></TD ></TR ><TR ><TD ALIGN="LEFT" VALIGN="TOP" ><TT CLASS="LITERAL" >SDL_MOUSEMOTION</TT ></TD ><TD ALIGN="LEFT" VALIGN="TOP" ><A HREF="sdlmousemotionevent.html" ><SPAN CLASS="STRUCTNAME" >SDL_MouseMotionEvent</SPAN ></A ></TD ></TR ><TR ><TD ALIGN="LEFT" VALIGN="TOP" ><TT CLASS="LITERAL" >SDL_MOUSEBUTTONDOWN/UP</TT ></TD ><TD ALIGN="LEFT" VALIGN="TOP" ><A HREF="sdlmousebuttonevent.html" ><SPAN CLASS="STRUCTNAME" >SDL_MouseButtonEvent</SPAN ></A ></TD ></TR ><TR ><TD ALIGN="LEFT" VALIGN="TOP" ><TT CLASS="LITERAL" >SDL_JOYAXISMOTION</TT ></TD ><TD ALIGN="LEFT" VALIGN="TOP" ><A HREF="sdljoyaxisevent.html" ><SPAN CLASS="STRUCTNAME" >SDL_JoyAxisEvent</SPAN ></A ></TD ></TR ><TR ><TD ALIGN="LEFT" VALIGN="TOP" ><TT CLASS="LITERAL" >SDL_JOYBALLMOTION</TT ></TD ><TD ALIGN="LEFT" VALIGN="TOP" ><A HREF="sdljoyballevent.html" ><SPAN CLASS="STRUCTNAME" >SDL_JoyBallEvent</SPAN ></A ></TD ></TR ><TR ><TD ALIGN="LEFT" VALIGN="TOP" ><TT CLASS="LITERAL" >SDL_JOYHATMOTION</TT ></TD ><TD ALIGN="LEFT" VALIGN="TOP" ><A HREF="sdljoyhatevent.html" ><SPAN CLASS="STRUCTNAME" >SDL_JoyHatEvent</SPAN ></A ></TD ></TR ><TR ><TD ALIGN="LEFT" VALIGN="TOP" ><TT CLASS="LITERAL" >SDL_JOYBUTTONDOWN/UP</TT ></TD ><TD ALIGN="LEFT" VALIGN="TOP" ><A HREF="sdljoybuttonevent.html" ><SPAN CLASS="STRUCTNAME" >SDL_JoyButtonEvent</SPAN ></A ></TD ></TR ><TR ><TD ALIGN="LEFT" VALIGN="TOP" ><TT CLASS="LITERAL" >SDL_QUIT</TT ></TD ><TD ALIGN="LEFT" VALIGN="TOP" ><A HREF="sdlquitevent.html" ><SPAN CLASS="STRUCTNAME" >SDL_QuitEvent</SPAN ></A ></TD ></TR ><TR ><TD ALIGN="LEFT" VALIGN="TOP" ><TT CLASS="LITERAL" >SDL_SYSWMEVENT</TT ></TD ><TD ALIGN="LEFT" VALIGN="TOP" ><A HREF="sdlsyswmevent.html" ><SPAN CLASS="STRUCTNAME" >SDL_SysWMEvent</SPAN ></A ></TD ></TR ><TR ><TD ALIGN="LEFT" VALIGN="TOP" ><TT CLASS="LITERAL" >SDL_VIDEORESIZE</TT ></TD ><TD ALIGN="LEFT" VALIGN="TOP" ><A HREF="sdlresizeevent.html" ><SPAN CLASS="STRUCTNAME" >SDL_ResizeEvent</SPAN ></A ></TD ></TR ><TR ><TD ALIGN="LEFT" VALIGN="TOP" ><TT CLASS="LITERAL" >SDL_VIDEOEXPOSE</TT ></TD ><TD ALIGN="LEFT" VALIGN="TOP" ><A HREF="sdlexposeevent.html" ><SPAN CLASS="STRUCTNAME" >SDL_ExposeEvent</SPAN ></A ></TD ></TR ><TR ><TD ALIGN="LEFT" VALIGN="TOP" ><TT CLASS="LITERAL" >SDL_USEREVENT</TT ></TD ><TD ALIGN="LEFT" VALIGN="TOP" ><A HREF="sdluserevent.html" ><SPAN CLASS="STRUCTNAME" >SDL_UserEvent</SPAN ></A ></TD ></TR ></TBODY ></TABLE ><P ></P ></DIV ></P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN3885" ></A ><H2 >Use</H2 ><P >The <SPAN CLASS="STRUCTNAME" >SDL_Event</SPAN > structure has two uses</P ><P ></P ><UL COMPACT="COMPACT" ><LI ><P >Reading events on the event queue</P ></LI ><LI ><P >Placing events on the event queue</P ></LI ></UL ><P >Reading events from the event queue is done with either <A HREF="sdlpollevent.html" ><TT CLASS="FUNCTION" >SDL_PollEvent</TT ></A > or <A HREF="sdlpeepevents.html" ><TT CLASS="FUNCTION" >SDL_PeepEvents</TT ></A >. We'll use <TT CLASS="FUNCTION" >SDL_PollEvent</TT > and step through an example.</P ><P >First off, we create an empty <SPAN CLASS="STRUCTNAME" >SDL_Event</SPAN > structure. <PRE CLASS="PROGRAMLISTING" >SDL_Event test_event;</PRE > <TT CLASS="FUNCTION" >SDL_PollEvent</TT > removes the next event from the event queue, if there are no events on the queue it returns <SPAN CLASS="RETURNVALUE" >0</SPAN > otherwise it returns <SPAN CLASS="RETURNVALUE" >1</SPAN >. We use a <TT CLASS="FUNCTION" >while</TT > loop to process each event in turn. <PRE CLASS="PROGRAMLISTING" >while(SDL_PollEvent(&test_event)) {</PRE > The <TT CLASS="FUNCTION" >SDL_PollEvent</TT > function take a pointer to an <SPAN CLASS="STRUCTNAME" >SDL_Event</SPAN > structure that is to be filled with event information. We know that if <TT CLASS="FUNCTION" >SDL_PollEvent</TT > removes an event from the queue then the event information will be placed in our <SPAN CLASS="STRUCTNAME" >test_event</SPAN > structure, but we also know that the <SPAN CLASS="emphasis" ><I CLASS="EMPHASIS" >type</I ></SPAN > of event will be placed in the <TT CLASS="STRUCTFIELD" ><I >type</I ></TT > member of <SPAN CLASS="STRUCTNAME" >test_event</SPAN >. So to handle each event <TT CLASS="STRUCTFIELD" ><I >type</I ></TT > seperately we use a <TT CLASS="FUNCTION" >switch</TT > statement. <PRE CLASS="PROGRAMLISTING" > switch(test_event.type) {</PRE > We need to know what kind of events we're looking for <SPAN CLASS="emphasis" ><I CLASS="EMPHASIS" >and</I ></SPAN > the event <TT CLASS="STRUCTFIELD" ><I >type</I ></TT >'s of those events. So lets assume we want to detect where the user is moving the mouse pointer within our application. We look through our event types and notice that <TT CLASS="LITERAL" >SDL_MOUSEMOTION</TT > is, more than likely, the event we're looking for. A little <A HREF="sdlmousemotionevent.html" >more</A > research tells use that <TT CLASS="LITERAL" >SDL_MOUSEMOTION</TT > events are handled within the <A HREF="sdlmousemotionevent.html" ><SPAN CLASS="STRUCTNAME" >SDL_MouseMotionEvent</SPAN ></A > structure which is the <TT CLASS="STRUCTFIELD" ><I >motion</I ></TT > member of <SPAN CLASS="STRUCTNAME" >SDL_Event</SPAN >. We can check for the <TT CLASS="LITERAL" >SDL_MOUSEMOTION</TT > event <TT CLASS="STRUCTFIELD" ><I >type</I ></TT > within our <TT CLASS="FUNCTION" >switch</TT > statement like so: <PRE CLASS="PROGRAMLISTING" > case SDL_MOUSEMOTION:</PRE > All we need do now is read the information out of the <TT CLASS="STRUCTFIELD" ><I >motion</I ></TT > member of <SPAN CLASS="STRUCTNAME" >test_event</SPAN >. <PRE CLASS="PROGRAMLISTING" > printf("We got a motion event.\n"); printf("Current mouse position is: (%d, %d)\n", test_event.motion.x, test_event.motion.y); break; default: printf("Unhandled Event!\n"); break; } } printf("Event queue empty.\n");</PRE ></P ><P >It is also possible to push events onto the event queue and so use it as a two-way communication path. Both <A HREF="sdlpushevent.html" ><TT CLASS="FUNCTION" >SDL_PushEvent</TT ></A > and <A HREF="sdlpeepevents.html" ><TT CLASS="FUNCTION" >SDL_PeepEvents</TT ></A > allow you to place events onto the event queue. This is usually used to place a <TT CLASS="LITERAL" >SDL_USEREVENT</TT > on the event queue, however you could use it to post fake input events if you wished. Creating your own events is a simple matter of choosing the event type you want, setting the <TT CLASS="STRUCTFIELD" ><I >type</I ></TT > member and filling the appropriate member structure with information. <PRE CLASS="PROGRAMLISTING" >SDL_Event user_event; user_event.type=SDL_USEREVENT; user_event.user.code=2; user_event.user.data1=NULL; user_event.user.data2=NULL; SDL_PushEvent(&user_event);</PRE ></P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN3942" ></A ><H2 >See Also</H2 ><P ><A HREF="sdlpollevent.html" ><TT CLASS="FUNCTION" >SDL_PollEvent</TT ></A >, <A HREF="sdlpushevent.html" ><TT CLASS="FUNCTION" >SDL_PushEvent</TT ></A >, <A HREF="sdlpeepevents.html" ><TT CLASS="FUNCTION" >SDL_PeepEvents</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="eventstructures.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="sdlactiveevent.html" ACCESSKEY="N" >Next</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >SDL Event Structures.</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="eventstructures.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >SDL_ActiveEvent</TD ></TR ></TABLE ></DIV ></BODY ></HTML >