Mercurial > sdl-ios-xcode
annotate docs/man3/SDL_Event.3 @ 3729:b7590cd5969d gsoc2009_unit_tests
Minor fix.
| author | Edgar Simo <bobbens@gmail.com> |
|---|---|
| date | Sun, 12 Jul 2009 11:18:59 +0000 |
| parents | 546f7c1eb755 |
| children | 1238da4a7112 |
| rev | line source |
|---|---|
|
181
e5bc29de3f0a
Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents:
55
diff
changeset
|
1 .TH "SDL_Event" "3" "Tue 11 Sep 2001, 22:59" "SDL" "SDL API Reference" |
| 0 | 2 .SH "NAME" |
|
2283
546f7c1eb755
Merged revision 3472 from SDL 1.2, fixing bug #493
Sam Lantinga <slouken@libsdl.org>
parents:
2278
diff
changeset
|
3 SDL_Event \- General event structure |
| 0 | 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; | |
|
181
e5bc29de3f0a
Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents:
55
diff
changeset
|
18 SDL_ExposeEvent expose; |
| 0 | 19 SDL_QuitEvent quit; |
| 20 SDL_UserEvent user; | |
|
2278
85cbe9c892f4
Merged revision 3455 from SDL 1.2, fixing documentation typo.
Sam Lantinga <slouken@libsdl.org>
parents:
181
diff
changeset
|
21 SDL_SysWMEvent syswm; |
| 0 | 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 | |
|
181
e5bc29de3f0a
Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents:
55
diff
changeset
|
57 \fBexpose\fR |
|
e5bc29de3f0a
Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents:
55
diff
changeset
|
58 \fIApplication window expose event\fR |
|
e5bc29de3f0a
Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents:
55
diff
changeset
|
59 .TP 20 |
| 0 | 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 | |
|
181
e5bc29de3f0a
Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents:
55
diff
changeset
|
109 \fBSDL_VIDEOEXPOSE\fP |
|
e5bc29de3f0a
Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents:
55
diff
changeset
|
110 \fI\fBSDL_ExposeEvent\fR\fR |
|
e5bc29de3f0a
Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents:
55
diff
changeset
|
111 .TP 20 |
| 0 | 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 | |
|
181
e5bc29de3f0a
Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents:
55
diff
changeset
|
182 ...\" created by instant / docbook-to-man, Tue 11 Sep 2001, 22:59 |