Mercurial > sdl-ios-xcode

view docs/html/sdlevent.html @ 172:37e3ca9254c7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Date: Sat, 8 Sep 2001 04:42:23 +0200 From: Max Horn <max@quendi.de> Subject: SDL/OSX: Joystick; Better key handling I just finished implementing improved keyhandling for OS X (in fact the code should be easily ported to the "normal" MacOS part of SDL, I just had no chance yet). Works like this: First init the mapping table statically like before. Them, it queries the OS for the "official" key table, then iterates over all 127 scancode and gets the associates ascii code. It ignores everythng below 32 (has to, as it would lead to many problems if we did not... e.g. both ESC and NUM LOCk produce an ascii code 27 on my keyboard), and all stuff above 127 is mapped to SDLK_WORLD_* simply in the order it is encountered. In addition, caps lock is now working, too. The code work flawless for me, but since I only have one keyboard, I may have not encountered some serious problem... but I am pretty confident that it is better than the old code in most cases. The joystick driver works fine for me, too. I think it can be added to CVS already. It would simply be helpful if more people would test it. Hm, I wonder if Maelstrom or GLTron has Joystick support? That would be a wonderful test application :) I also took the liberty of modifying some text files like BUGS, README.CVS, README.MacOSX (which now contains the OS X docs I long promised)
author Sam Lantinga <slouken@libsdl.org>
date Tue, 11 Sep 2001 19:00:18 +0000
parents 55f1f1b3e27d
children e5bc29de3f0a
line wrap: on
line source

<HTML
><HEAD
><TITLE
>SDL_Event</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.64
"><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="AEN3289"
></A
><H2
>Name</H2
>SDL_Event&nbsp;--&nbsp;General event structure</DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN3292"
></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="AEN3295"
></A
><H2
>Structure Data</H2
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN3297"
></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="AEN3364"
></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="AEN3372"
></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="AEN3452"
></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="AEN3509"
></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
>