| 1 | .TH "SDL_Event" "3" "Tue 11 Sep 2001, 22:59" "SDL" "SDL API Reference" |
| 2 | .SH "NAME" |
| 3 | SDL_Event \- General event structure |
| 4 | .SH "STRUCTURE DEFINITION" |
| 5 | .PP |
| 6 | .nf |
| 7 | \f(CWtypedef union{ |
| 8 | Uint8 type; |
| 9 | SDL_ActiveEvent active; |
| 10 | SDL_KeyboardEvent key; |
| 11 | SDL_MouseMotionEvent motion; |
| 12 | SDL_MouseButtonEvent button; |
| 13 | SDL_JoyAxisEvent jaxis; |
| 14 | SDL_JoyBallEvent jball; |
| 15 | SDL_JoyHatEvent jhat; |
| 16 | SDL_JoyButtonEvent jbutton; |
| 17 | SDL_ResizeEvent resize; |
| 18 | SDL_ExposeEvent expose; |
| 19 | SDL_QuitEvent quit; |
| 20 | SDL_UserEvent user; |
| 21 | SDL_SysWMEvent syswm; |
| 22 | } SDL_Event;\fR |
| 23 | .fi |
| 24 | .PP |
| 25 | .SH "STRUCTURE DATA" |
| 26 | .TP 20 |
| 27 | \fBtype\fR |
| 28 | The type of event |
| 29 | .TP 20 |
| 30 | \fBactive\fR |
| 31 | \fIActivation event\fR |
| 32 | .TP 20 |
| 33 | \fBkey\fR |
| 34 | \fIKeyboard event\fR |
| 35 | .TP 20 |
| 36 | \fBmotion\fR |
| 37 | \fIMouse motion event\fR |
| 38 | .TP 20 |
| 39 | \fBbutton\fR |
| 40 | \fIMouse button event\fR |
| 41 | .TP 20 |
| 42 | \fBjaxis\fR |
| 43 | \fIJoystick axis motion event\fR |
| 44 | .TP 20 |
| 45 | \fBjball\fR |
| 46 | \fIJoystick trackball motion event\fR |
| 47 | .TP 20 |
| 48 | \fBjhat\fR |
| 49 | \fIJoystick hat motion event\fR |
| 50 | .TP 20 |
| 51 | \fBjbutton\fR |
| 52 | \fIJoystick button event\fR |
| 53 | .TP 20 |
| 54 | \fBresize\fR |
| 55 | \fIApplication window resize event\fR |
| 56 | .TP 20 |
| 57 | \fBexpose\fR |
| 58 | \fIApplication window expose event\fR |
| 59 | .TP 20 |
| 60 | \fBquit\fR |
| 61 | \fIApplication quit request event\fR |
| 62 | .TP 20 |
| 63 | \fBuser\fR |
| 64 | \fIUser defined event\fR |
| 65 | .TP 20 |
| 66 | \fBsyswm\fR |
| 67 | \fIUndefined window manager event\fR |
| 68 | .SH "DESCRIPTION" |
| 69 | .PP |
| 70 | 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\&. |
| 71 | .PP |
| 72 | .TP 20 |
| 73 | \fBEvent \fBtype\fR\fR |
| 74 | \fBEvent Structure\fR |
| 75 | .TP 20 |
| 76 | \fBSDL_ACTIVEEVENT\fP |
| 77 | \fI\fBSDL_ActiveEvent\fR\fR |
| 78 | .TP 20 |
| 79 | \fBSDL_KEYDOWN/UP\fP |
| 80 | \fI\fBSDL_KeyboardEvent\fR\fR |
| 81 | .TP 20 |
| 82 | \fBSDL_MOUSEMOTION\fP |
| 83 | \fI\fBSDL_MouseMotionEvent\fR\fR |
| 84 | .TP 20 |
| 85 | \fBSDL_MOUSEBUTTONDOWN/UP\fP |
| 86 | \fI\fBSDL_MouseButtonEvent\fR\fR |
| 87 | .TP 20 |
| 88 | \fBSDL_JOYAXISMOTION\fP |
| 89 | \fI\fBSDL_JoyAxisEvent\fR\fR |
| 90 | .TP 20 |
| 91 | \fBSDL_JOYBALLMOTION\fP |
| 92 | \fI\fBSDL_JoyBallEvent\fR\fR |
| 93 | .TP 20 |
| 94 | \fBSDL_JOYHATMOTION\fP |
| 95 | \fI\fBSDL_JoyHatEvent\fR\fR |
| 96 | .TP 20 |
| 97 | \fBSDL_JOYBUTTONDOWN/UP\fP |
| 98 | \fI\fBSDL_JoyButtonEvent\fR\fR |
| 99 | .TP 20 |
| 100 | \fBSDL_QUIT\fP |
| 101 | \fI\fBSDL_QuitEvent\fR\fR |
| 102 | .TP 20 |
| 103 | \fBSDL_SYSWMEVENT\fP |
| 104 | \fI\fBSDL_SysWMEvent\fR\fR |
| 105 | .TP 20 |
| 106 | \fBSDL_VIDEORESIZE\fP |
| 107 | \fI\fBSDL_ResizeEvent\fR\fR |
| 108 | .TP 20 |
| 109 | \fBSDL_VIDEOEXPOSE\fP |
| 110 | \fI\fBSDL_ExposeEvent\fR\fR |
| 111 | .TP 20 |
| 112 | \fBSDL_USEREVENT\fP |
| 113 | \fI\fBSDL_UserEvent\fR\fR |
| 114 | .SH "USE" |
| 115 | .PP |
| 116 | The \fBSDL_Event\fR structure has two uses |
| 117 | .IP " \(bu" 6 |
| 118 | Reading events on the event queue |
| 119 | .IP " \(bu" 6 |
| 120 | Placing events on the event queue |
| 121 | .PP |
| 122 | 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\&. |
| 123 | .PP |
| 124 | First off, we create an empty \fBSDL_Event\fR structure\&. |
| 125 | .PP |
| 126 | .nf |
| 127 | \f(CWSDL_Event test_event;\fR |
| 128 | .fi |
| 129 | .PP |
| 130 | \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\&. |
| 131 | .PP |
| 132 | .nf |
| 133 | \f(CWwhile(SDL_PollEvent(&test_event)) {\fR |
| 134 | .fi |
| 135 | .PP |
| 136 | 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\&. |
| 137 | .PP |
| 138 | .nf |
| 139 | \f(CW switch(test_event\&.type) {\fR |
| 140 | .fi |
| 141 | .PP |
| 142 | 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: |
| 143 | .PP |
| 144 | .nf |
| 145 | \f(CW case SDL_MOUSEMOTION:\fR |
| 146 | .fi |
| 147 | .PP |
| 148 | All we need do now is read the information out of the \fBmotion\fR member of \fBtest_event\fR\&. |
| 149 | .PP |
| 150 | .nf |
| 151 | \f(CW printf("We got a motion event\&. |
| 152 | "); |
| 153 | printf("Current mouse position is: (%d, %d) |
| 154 | ", test_event\&.motion\&.x, test_event\&.motion\&.y); |
| 155 | break; |
| 156 | default: |
| 157 | printf("Unhandled Event! |
| 158 | "); |
| 159 | break; |
| 160 | } |
| 161 | } |
| 162 | printf("Event queue empty\&. |
| 163 | ");\fR |
| 164 | .fi |
| 165 | .PP |
| 166 | .PP |
| 167 | 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\&. |
| 168 | .PP |
| 169 | .nf |
| 170 | \f(CWSDL_Event user_event; |
| 171 | |
| 172 | user_event\&.type=SDL_USEREVENT; |
| 173 | user_event\&.user\&.code=2; |
| 174 | user_event\&.user\&.data1=NULL; |
| 175 | user_event\&.user\&.data2=NULL; |
| 176 | SDL_PushEvent(&user_event);\fR |
| 177 | .fi |
| 178 | .PP |
| 179 | .SH "SEE ALSO" |
| 180 | .PP |
| 181 | \fI\fBSDL_PollEvent\fP\fR, \fI\fBSDL_PushEvent\fP\fR, \fI\fBSDL_PeepEvents\fP\fR |
| 182 | .\" created by instant / docbook-to-man, Tue 11 Sep 2001, 22:59 |