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&nbsp;--&nbsp;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(&#38;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(&#38;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