Chapter 6: Event handling
If the user is moving the mouse, pressing/releasing a button on the keyboard or pressing/releasing the fire key on the joystick then you speak of events. Further events are resizing a window or switching between several applications. For games though the events described first are much more important. SDL provides a quite easy way to notice and react to such events, which is called event handling.First of all using event handling means to understand the concept of event handling. Events have a special structure you should know about. For example an pressed key is an event or a moved mouse is an event. SDL differs altogether sixteen such events. Every event stores different information depending on its kind. For example the key board event stores the information which key was pressed. The mouse motion event stores the information to which position the mouse got moved. If you got a mouse motion event you can't read out key information and so on. Therefore you have the following general structure to the event data: event.eventstructure.data. The following list will give you an overview of all possible eventstructures in SDL:
| eventstructure | Description |
|---|---|
| SDL_NOEVENT | ? |
| SDL_ACTIVEEVENT | Notices if application is active or inactive (for example when you switch to another application). |
| SDL_KEYDOWN | Both have the same record structure (tSDL_KEYBOARDEVENT) which stores the triggering key with state SDL_PRESSED or SDL_RELEASED |
| SDL_KEYUP | |
| SDL_MOUSEMOTION | Notices the movement of the mouse cursor and stores it position and the relative movement from former origin. |
| SDL_MOUSEBUTTONDOWN | Both have the same record structure (tSDL_MOUSEBUTTONEVENT) which stores the triggering mouse and its key with state SDL_PRESSED or SDL_RELEASED. Futhermore the position is stored. |
| SDL_MOUSEBUTTONUP | |
| SDL_JOYAXISMOTION | Notices the usage of the stick of a joystick. |
| SDL_JOYBALLMOTION | Notices the usage of a joyball and the relative movement from its origin. |
| SDL_JOYHATMOTION | Notices the triggering joystick and its hat. Furthermore one of the nine positions is stored (1=up, 2=right upper corner, 3=right and so on; 0=center). |
| SDL_JOYBUTTONDOWN | Both have the same record structure (tSDL_JOYBUTTONEVENT) which stores the triggering joystick and its key with state SDL_PRESSED or SDL_RELEASED. |
| SDL_JOYBUTTONUP | |
| SDL_VIDEORESIZE | Notices when apllication window gets resized and stores the new height and width. |
| SDL_QUITEV | Notices when user quits the application (by clicking application's X-button at right upper corner) |
| SDL_USEREVENT | Unedfined event which can be definied by user. |
| SDL_SYSWMEVENT | Notices system window manager events. |
To make event handling possible you have to include the unit SDL_EVENTS. The event handling subsystem is automatically initialized along with the video subsystem.
We have to create an event variable which is of pointer type pSDL_EVENT. We will create a second variable of boolean type just to control the while loop.
|
PROGRAM chap6_1; USES SDL; VAR screen:pSDL_SURFACE; loopstop:boolean=FALSE; test_event:pSDL_EVENT; BEGIN SDL_INIT(SDL_INIT_VIDEO); screen:=SDL_SETVIDEOMODE(200,200,32,SDL_SWSURFACE); IF screen=NIL THEN HALT; NEW(test_event); DISPOSE(test_event); SDL_FREESURFACE(screen); SDL_QUIT; END. |
|---|
We want to check the program if any event occured and if so, we want to know which kind of event happened. So we make a while loop which will run until loopstop gets true.
The command SDL_POLLEVENT(parameter) checks if there are pending events and if so it will take the oldest and save it to parameter which is an event record of pSDL_EVENT type. For example if the user presses (then releases) left mouse button, then presses (then releases) space button on keyboard and finally moves the mouse there are altogether five events: 1. left mouse button pressed, 2. left mouse button released, 3. space key pressed, 4. space key released, 5. mouse moved. If you poll for events now you will get the first event (left mouse button pressed) and saved it's properties to the event variable we specified as parameter. The next poll will save the properties of next event (left mouse button released) to event variable and so on. SDL_POLLEVENT(parameter) will return 1 if it has found pending event or 0 if there wasn't any pending event.
Fortunately you don't have to notice any event which is made by the user ;). By event^.eventtype you can easily check which type of event you got. In the case described before it would be 1. SDL_MOUSEBUTTONDOWN, 2. SDL_MOUSEBUTTONUP, 3. SDL_KEYDOWN, 4. SDL_KEYUP, 5. SDL_MOUSEMOTION. It should be senseful to check for the event kind by using the case command.
|
PROGRAM chap6_1; USES SDL; VAR screen:pSDL_SURFACE; loopstop:boolean=FALSE; test_event:pSDL_EVENT; BEGIN SDL_INIT(SDL_INIT_VIDEO); screen:=SDL_SETVIDEOMODE(200,200,32,SDL_SWSURFACE); IF screen=NIL THEN HALT; NEW(test_event); WHILE loopstop=FALSE DO BEGIN IF SDL_POLLEVENT(test_event)=1 THEN BEGIN write('pending event: '); CASE test_event^.type_ OF SDL_ACTIVEEVENT: writeln('Application is/is not active'); SDL_KEYDOWN: writeln('Key pressed '); SDL_KEYUP: writeln('Key released'); SDL_MOUSEMOTION: writeln('Mouse motion'); SDL_MOUSEBUTTONDOWN: writeln('Mouse button down'); SDL_MOUSEBUTTONUP: writeln('Mouse button up'); SDL_JOYAXISMOTION: writeln('Joystick axis motion'); SDL_JOYBALLMOTION: writeln('Joystick's trackball motion'); SDL_JOYHATMOTION: writeln('Joystick's hat position changed'); SDL_JOYBUTTONDOWN: writeln('Joystick button pressed'); SDL_JOYBUTTONUP: writeln('Joystick button released'); SDL_QUITEV: writeln('User-requested quit'); END; END ELSE writeln('no pending events'); DELAY(150); END; DISPOSE(test_event); SDL_FREESURFACE(screen); SDL_QUIT; END. |
|---|
Actually you shouldn't try this source as it is written there because it will end up in an endless loop. The DELAY command is used because otherwise you won't notice any pending events because they are polled too fast and it seems as if there would never be any pending events (just remove DELAY to confirm).
We now want to try the program to read out which key the user pressed on the keyboard. If the key is the escape-key (Esc) the program should stop. We already check the type of the event we polled. So if the event is a keyboard event the further checking should proceed. In our case especially if a key gets pressed. An keyboard event record contains a field called keysym. Keysym is a record of SDL_KEYSYM. SDL_KEYSYM is defined in SDL_KEYBOARD unit. It contains four fields. Scancode which is hardware dependent scancode should be avoided if you want to make hardware independent programs. It is usual integer variable. Next is sym which stores SDLKEY. These SDL keys are independent and it is strongly recommended to use them! In the example we want break up if escape key gets pressed. Its SDL key code is 27. If you want to know what SDL keys are defined look up in the table page. The variable modifier stores modifier keys (like shift, ctrl,...) pressed and stores SDLMod. SDL modifier keys can be found at table page as well. The fourth variable is unicode which may be used to read out unicode characters but to use this you have to enable it what is not described in this tutorial.
To read out or compare the key the user pressed we must use the expression test_event^.key.keysym.sym. Do you remember the general structure of an event (event.eventstructure.data)? - test_event^ is the event, the event structure is defined as an key event by key and the data we want to know is the key pressed contained in keysym.sym.
|
PROGRAM chap6_1; USES SDL; VAR screen:pSDL_SURFACE; loopstop:boolean=FALSE; test_event:pSDL_EVENT; BEGIN SDL_INIT(SDL_INIT_VIDEO); screen:=SDL_SETVIDEOMODE(200,200,32,SDL_SWSURFACE); IF screen=NIL THEN HALT; NEW(test_event); WHILE loopstop=FALSE DO BEGIN IF SDL_POLLEVENT(test_event)=1 THEN BEGIN write('pending event: '); CASE test_event^.type_ OF SDL_ACTIVEEVENT: writeln('Application is/is not active'); SDL_KEYDOWN: BEGIN write('Key pressed '); writeln('(SDLKey=',test_event^.key.keysym.sym,')'); IF test_event^.key.keysym.sym=27 THEN loopstop:=true; END; SDL_KEYUP: writeln('Key released'); SDL_MOUSEMOTION: writeln('Mouse motion'); SDL_MOUSEBUTTONDOWN: writeln('Mouse button down'); SDL_MOUSEBUTTONUP: writeln('Mouse button up'); SDL_JOYAXISMOTION: writeln('Joystick axis motion'); SDL_JOYBALLMOTION: writeln('Joystick's trackball motion'); SDL_JOYHATMOTION: writeln('Joystick's hat position changed'); SDL_JOYBUTTONDOWN: writeln('Joystick button pressed'); SDL_JOYBUTTONUP: writeln('Joystick button released'); SDL_QUITEV: writeln('User-requested quit'); END; END ELSE writeln('no pending events'); DELAY(150); END; DISPOSE(test_event); SDL_FREESURFACE(screen); SDL_QUIT; END. |
|---|
Actually this is easy, isn't it?
Now I will present a command without showing its appliance at any code but since it is easy to understand this is not necessary. Imagine you open any text editor and just hold pressed any letter on the keyboard. What will happen? First the letter will be written to the text editor and after a short break the letter will be written in a loop (without break). - You may want to change this behaviour, especially for action games and such. The command SDL_ENABLEKEYREPEAT(DELAY, INTERVAL) is used for changing this. If delay is set to 0 the key repetition is completly disabled and a held pressed key will just trigger ONCE. If you enable the the delay by setting it to 1 and setting an interval in ms the pressed key will trigger anytime the set interval has passed. E.g. SDL_ENABLEKEYREPEAT(1,1000) will trigger the key any second if pressed. Note: When using this command the certain text edior behaviour is removed and the first triggering will happen immediatly. To get back to the common behaviour use SDL_DEFAULT_REPEAT_DELAY and SDL_DEFAULT_REPEAT_INTERVAL.
Now we will discuss mouse handling. Since it is rather similar to keyboard handling I will just present the code and explain some differences. Here we go:
|
PROGRAM chap6_2; USES SDL; VAR screen:pSDL_SURFACE; loopstop:boolean=FALSE; test_event:pSDL_EVENT; PROCEDURE mouse_check; BEGIN writeln('X: ',test_event^.motion.x,' Y: ',test_event^.motion.y, ' dX: ',test_event^.motion.xrel,' dY: ',test_event^.motion.yrel, ' button state: ',test_event^.motion.state); writeln('button state (pressed/released): ',test_event^.button.state, ' button index: ',test_event^.button.button); END; BEGIN SDL_INIT(SDL_INIT_VIDEO); screen:=SDL_SETVIDEOMODE(200,200,32,SDL_SWSURFACE); IF screen=NIL THEN HALT; NEW(test_event); SDL_EVENTSTATE(SDL_ACTIVEEVENT,SDL_DISABLE); WHILE loopstop=FALSE DO BEGIN IF SDL_POLLEVENT(test_event)=1 THEN BEGIN CASE test_event^.type_ OF SDL_ACTIVEEVENT: writeln('Application is/is not active'); SDL_KEYDOWN: {SDLKey 27 = ESCAPE} IF test_event^.key.keysym.sym=27 THEN loopstop:=TRUE; SDL_MOUSEMOTION: mouse_check; SDL_MOUSEBUTTONDOWN: mouse_check; SDL_MOUSEBUTTONUP: mouse_check; END; END; END; DISPOSE(test_event); SDL_FREESURFACE(screen); SDL_QUIT; END. |
|---|
Anyhow this code looks complicated. I think the structured version in the original source code has a higher readibility. You will notice that you can read out the position of the mouse by test_event^.motion.x and test_event^.motion.y. The relative movement which means the difference from the actual position compared to last polled position you can get by test_event^.motion.xrel and test_event^.motion.yrel. Furthermore it is possbile to return the pressed buttons by test_event^.motion.state. All this data belongs to TSDL_MOUSEMOTIONEVENT record.
Similar to the handling of keyboard events the mouse key events are handled. It of course also provides the feature to return the pressed button but here you get this by test_event^.button.button. It has the very same meaning as test_event^.motion.state! Don't confuse it with test_event^.button.state which here means to check if a button is pressed (SDL_PRESSED) or released (SDL_RELEASED). This data belongs to TSDL_MOUSEBUTTONEVENT record
By the way, you should check what happens if you combine several mouse buttons or use the mouse wheel. Some button combinations lead to the same button index as the usage of the mouse wheel and so on.
If you carefully studied the code you would have noticed the usage of SDL_EVENTSTATE(). This allows you to enable/disable certain event structures. For example in the code SDL_ACTIVEEVENT got disabled by SDL_EVENTSTATE(SDL_ACTIVEEVENT, SDL_DISABLE). That is why you never will receive a note about an active or inactive application even though the status may change when you run the program. The same result you get by using SDL_IGNORE. You can reenable the event structure by SDL_ENABLE.
With this chapter you got introduced into a major concept of game programming.
This file contains the source code: chap6_1.pas (right click and "save as")
This file is the executable: chap6_1.exe (right click and "save as")
This file contains the source code: chap6_2.pas (right click and "save as")
This file is the executable: chap6_2.exe (right click and "save as")
 |
The final result should look and behave like this: While being with the mouse onto the SDL application window any event from the keyboard is recognized and it is said what exactly happened (button down, up, ...) |
 |
The final result should look and behave like this: While being with the mouse onto the SDL application window any event from the mouse is recognized and its (x/y) position, the difference between last recognized position and new position (dX and dY) and if a button is pressed or released and the corresponding button's index is shown. |
to mainpage
Creation/Updates: 12/8/2009; 7/10/2007; 26/7/2007
There is no guarantee that things will work! You do everything described here on your own risk! © M. Molski 2005-2009. All product and company names, brand names, trademarks and logos are the property of their respective owners.