1 files changed, 182 insertions, 0 deletions
diff --git a/distrib/sdl-1.2.15/docs/man3/SDL_Event.3 b/distrib/sdl-1.2.15/docs/man3/SDL_Event.3
new file mode 100644
index 0000000..b508f19
--- /dev/null
+++ b/distrib/sdl-1.2.15/docs/man3/SDL_Event.3
@@ -0,0 +1,182 @@
+.TH "SDL_Event" "3" "Tue 11 Sep 2001, 22:59" "SDL" "SDL API Reference" 
+.SH "NAME"
+SDL_Event \- General event structure
+.SH "STRUCTURE DEFINITION"
+.PP
+.nf
+\f(CWtypedef 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;\fR
+.fi
+.PP
+.SH "STRUCTURE DATA"
+.TP 20
+\fBtype\fR
+The type of event
+.TP 20
+\fBactive\fR
+\fIActivation event\fR
+.TP 20
+\fBkey\fR
+\fIKeyboard event\fR
+.TP 20
+\fBmotion\fR
+\fIMouse motion event\fR
+.TP 20
+\fBbutton\fR
+\fIMouse button event\fR
+.TP 20
+\fBjaxis\fR
+\fIJoystick axis motion event\fR
+.TP 20
+\fBjball\fR
+\fIJoystick trackball motion event\fR
+.TP 20
+\fBjhat\fR
+\fIJoystick hat motion event\fR
+.TP 20
+\fBjbutton\fR
+\fIJoystick button event\fR
+.TP 20
+\fBresize\fR
+\fIApplication window resize event\fR
+.TP 20
+\fBexpose\fR
+\fIApplication window expose event\fR
+.TP 20
+\fBquit\fR
+\fIApplication quit request event\fR
+.TP 20
+\fBuser\fR
+\fIUser defined event\fR
+.TP 20
+\fBsyswm\fR
+\fIUndefined window manager event\fR
+.SH "DESCRIPTION"
+.PP
+The \fBSDL_Event\fR union is the core to all event handling is SDL, its probably the most important structure after \fBSDL_Surface\fR\&. \fBSDL_Event\fR 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 \fBtype\fR\&.
+.PP
+.TP 20
+\fBEvent \fBtype\fR\fR
+\fBEvent Structure\fR
+.TP 20
+\fBSDL_ACTIVEEVENT\fP
+\fI\fBSDL_ActiveEvent\fR\fR
+.TP 20
+\fBSDL_KEYDOWN/UP\fP
+\fI\fBSDL_KeyboardEvent\fR\fR
+.TP 20
+\fBSDL_MOUSEMOTION\fP
+\fI\fBSDL_MouseMotionEvent\fR\fR
+.TP 20
+\fBSDL_MOUSEBUTTONDOWN/UP\fP
+\fI\fBSDL_MouseButtonEvent\fR\fR
+.TP 20
+\fBSDL_JOYAXISMOTION\fP
+\fI\fBSDL_JoyAxisEvent\fR\fR
+.TP 20
+\fBSDL_JOYBALLMOTION\fP
+\fI\fBSDL_JoyBallEvent\fR\fR
+.TP 20
+\fBSDL_JOYHATMOTION\fP
+\fI\fBSDL_JoyHatEvent\fR\fR
+.TP 20
+\fBSDL_JOYBUTTONDOWN/UP\fP
+\fI\fBSDL_JoyButtonEvent\fR\fR
+.TP 20
+\fBSDL_QUIT\fP
+\fI\fBSDL_QuitEvent\fR\fR
+.TP 20
+\fBSDL_SYSWMEVENT\fP
+\fI\fBSDL_SysWMEvent\fR\fR
+.TP 20
+\fBSDL_VIDEORESIZE\fP
+\fI\fBSDL_ResizeEvent\fR\fR
+.TP 20
+\fBSDL_VIDEOEXPOSE\fP
+\fI\fBSDL_ExposeEvent\fR\fR
+.TP 20
+\fBSDL_USEREVENT\fP
+\fI\fBSDL_UserEvent\fR\fR
+.SH "USE"
+.PP
+The \fBSDL_Event\fR structure has two uses
+.IP "   \(bu" 6
+Reading events on the event queue
+.IP "   \(bu" 6
+Placing events on the event queue
+.PP
+Reading events from the event queue is done with either \fI\fBSDL_PollEvent\fP\fR or \fI\fBSDL_PeepEvents\fP\fR\&. We\&'ll use \fBSDL_PollEvent\fP and step through an example\&.
+.PP
+First off, we create an empty \fBSDL_Event\fR structure\&. 
+.PP
+.nf
+\f(CWSDL_Event test_event;\fR
+.fi
+.PP
+ \fBSDL_PollEvent\fP removes the next event from the event queue, if there are no events on the queue it returns \fB0\fR otherwise it returns \fB1\fR\&. We use a \fBwhile\fP loop to process each event in turn\&. 
+.PP
+.nf
+\f(CWwhile(SDL_PollEvent(&test_event)) {\fR
+.fi
+.PP
+ The \fBSDL_PollEvent\fP function take a pointer to an \fBSDL_Event\fR structure that is to be filled with event information\&. We know that if \fBSDL_PollEvent\fP removes an event from the queue then the event information will be placed in our \fBtest_event\fR structure, but we also know that the \fItype\fP of event will be placed in the \fBtype\fR member of \fBtest_event\fR\&. So to handle each event \fBtype\fR seperately we use a \fBswitch\fP statement\&. 
+.PP
+.nf
+\f(CW  switch(test_event\&.type) {\fR
+.fi
+.PP
+ We need to know what kind of events we\&'re looking for \fIand\fP the event \fBtype\fR\&'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 \fBSDL_MOUSEMOTION\fP is, more than likely, the event we\&'re looking for\&. A little \fImore\fR research tells use that \fBSDL_MOUSEMOTION\fP events are handled within the \fI\fBSDL_MouseMotionEvent\fR\fR structure which is the \fBmotion\fR member of \fBSDL_Event\fR\&. We can check for the \fBSDL_MOUSEMOTION\fP event \fBtype\fR within our \fBswitch\fP statement like so: 
+.PP
+.nf
+\f(CW    case SDL_MOUSEMOTION:\fR
+.fi
+.PP
+ All we need do now is read the information out of the \fBmotion\fR member of \fBtest_event\fR\&. 
+.PP
+.nf
+\f(CW      printf("We got a motion event\&.
+");
+      printf("Current mouse position is: (%d, %d)
+", test_event\&.motion\&.x, test_event\&.motion\&.y);
+      break;
+    default:
+      printf("Unhandled Event!
+");
+      break;
+  }
+}
+printf("Event queue empty\&.
+");\fR
+.fi
+.PP
+.PP
+It is also possible to push events onto the event queue and so use it as a two-way communication path\&. Both \fI\fBSDL_PushEvent\fP\fR and \fI\fBSDL_PeepEvents\fP\fR allow you to place events onto the event queue\&. This is usually used to place a \fBSDL_USEREVENT\fP 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 \fBtype\fR member and filling the appropriate member structure with information\&. 
+.PP
+.nf
+\f(CWSDL_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);\fR
+.fi
+.PP
+.SH "SEE ALSO"
+.PP
+\fI\fBSDL_PollEvent\fP\fR, \fI\fBSDL_PushEvent\fP\fR, \fI\fBSDL_PeepEvents\fP\fR
+.\" created by instant / docbook-to-man, Tue 11 Sep 2001, 22:59