|
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 |