Mercurial > sdl-ios-xcode
diff docs/html/sdlevent.html @ 0:74212992fb08
Initial revision
| author | Sam Lantinga <slouken@lokigames.com> |
|---|---|
| date | Thu, 26 Apr 2001 16:45:43 +0000 |
| parents | |
| children | 55f1f1b3e27d |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/html/sdlevent.html Thu Apr 26 16:45:43 2001 +0000 @@ -0,0 +1,942 @@ +<HTML +><HEAD +><TITLE +>SDL_Event</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.61 +"><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 +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" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +></TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="sdlactiveevent.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><H1 +><A +NAME="SDLEVENT" +>SDL_Event</A +></H1 +><DIV +CLASS="REFNAMEDIV" +><A +NAME="AEN3214" +></A +><H2 +>Name</H2 +>SDL_Event -- General event structure</DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN3217" +></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_QuitEvent quit; + SDL_UserEvent user; + SDL_SywWMEvent syswm; +} SDL_Event;</PRE +></DIV +><DIV +CLASS="REFSECT1" +><A +NAME="AEN3220" +></A +><H2 +>Structure Data</H2 +><DIV +CLASS="INFORMALTABLE" +><A +NAME="AEN3222" +></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 +>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="AEN3289" +></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="AEN3297" +></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_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="AEN3377" +></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 <I +CLASS="EMPHASIS" +>type</I +> 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 <I +CLASS="EMPHASIS" +>and</I +> 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="AEN3434" +></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 +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="eventstructures.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="index.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="sdlactiveevent.html" +>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" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>SDL_ActiveEvent</TD +></TR +></TABLE +></DIV +></BODY +></HTML +> \ No newline at end of file