Programming with SDL

Tutorial 2 - SDL Events

---

Introduction

In the last tutorial I covered the basics of creating an SDL project in Linux. Looking into the source code, you may have discovered a couple sections I didn't talk about. These sections where left out because I felt they warrented a tutorial of their own, and here it is.

This tutorial will cover Events, and Window management. The next several tutorials will be somewhat shorter than the first one, which covered a significant amount of material. Please note, that any of the functions covered in this tutorial should also be documented in the SDL API Reference as manual pages.

Fun with Events

When programming in GUI enviroments, most of the action takes place on events: the mouse moves, a key is pressed, a mouse click happens, a print job finishes, a CD-ROM is inserted, and so forth.

If you have ever programmed in Windows, the concept of events should be be familiar to you. Most SDL programs will continously check to see if an event has happened, and when one does, handle it. There are two methods of checking for events in SDL: SDL_PollEvent and SDL_WaitEvent. SDL_PollEvent and SDL_WaitEvent both take a parameter of a pointer to type SDL_Event.

SDL_PollEvent checks to see if any events are in the event queue. If there are events in the event que, it will return nonzero to let the programmer know that there are events ready to be handled and place the event data in its parameter.

SDL_WaitEvent waits for an event to happen, and then places the event data inside its parameter. SDL_WaitEvent will always return non zero unless there is an error.

Passing a NULL pointer to either function will allow you to wait for, or check to see, if there are any events. The event data itself however, will remain in the queue.

The event type is stored in the SDL event structure as 'type'. Most SDL programs use a switch statement to determine the type of event and then perform whatever procedure they wish.

Now it is easy to see what the remainder of the main program was doing in the last tutorial.

	SDL_Event event;
...
	while(!exitkey) {
		DrawPicture(screen);
		while(SDL_PollEvent(&event)) {
		switch( event.type ) {
				case SDL_QUIT:
					exitkey = 1;
					printf("Got quit event!\n");
					break;
				case SDL_KEYDOWN:
					printf("Key hit - exiting!\n");
					exitkey = 1;
					break;
			}
		}
	}

		

Here, the program continuosly draws to the software surface using the DrawPictures function. In between draws, the program will check to see if anything interesting has happened. If a key is pressed or there is a quit message, the program will exit. The code below the SDL_PollEvent function will only execute after an event has occured.

Types of Events (Advanced)

There are more types of events than I can cover in depth in a single tutorial. Most of the events that you will want to deal with are user created events(mouse clicks, etc...). Sometimes more important though, are events that are generated indirecty: resize events, status events, and quit events. In order for an application to properly behave: it MUST respond to both types of events. The following are the most used types of events as defined by SDL:

SDL_ACTIVEEVENT: The application visibility status has changed. Information on this event can be found in the "active" structure item of the event structure. "event.active.state" contains information about the type of event that occured. This structure item is documented fully in the SDL documentation. In this tutorial, all I check for is changes in the applications status(iconified or restored). This is done by using a bitwise and with the SDL_APPACTIVE flag and the active.state variable. If the result is nonzero, the application has been minimized or restored. To check whether the event caused a loss or gain in focus(or status), check the active.gain variable. (See code segment bellow.)

SDL_MOUSEBUTTONDOWN/SDL_MOUSEBUTTONUP: These two events are caused when the Mouse button is pressed or released. These must be used to detect mouse clicks or doubleclicks.

SDL_MOUSEMOTION: This event happens whenever the mouse moves.

SDL_KEYDOWN: This even happens whenever a key is pressed.

SDL_VIDEORESIZE: The application window was resized.

SDL_QUIT: The application has recieved a quit request.

SDL_USEREVENT: An event created by the application.

A later tutorial will cover user input events. For the application we are working with, it would be useful to not continue drawing if the application is minimized. To do this, we use the SDL_ACTIVEEVENT event, and create an application flag to see if the application is active or not:

	case SDL_ACTIVEEVENT:
		printf("Activity Change!\n");
			if ( event.active.state & SDL_APPACTIVE ) {
				if( event.active.gain )
					active = 1;
				else 
					active = 0;
							
			}
		break;

Having fun with the window manager

So, now you have your application window, are doing all sorts of things with events, and have a pretty little graphic being drawn. But - your window isn't you!

First things first, let's set the name that appears in the title bar, and the name that appears on the icon when minimized. This is done using SDL_WM_SetCaption. SDL_WM_SetCaption takes parameters of two character arrays: the window title string, and icon text string. A good way to check and see if the proper caption was set is using SDL_WM_GetCaption. SDL_WM_GetCaption is passed the address of two character points: the location of the title string, and the location of the icon string.

The following will get set the name of the window to "Hello World!!!!!!!", and set the icon name to "MAXIMIZE ME". It will then grab the names, and print them out.

	SDL_WM_SetCaption("Hello World!!!!!!", "MAXIMIZE ME");
	SDL_WM_GetCaption(&titlestring, &iconstring);
	if(titlestring) {
		printf("Got title string: %s\n", titlestring);
	}

	if(iconstring) {
		printf("Got icon string: %s\n", iconstring);
	}

	

Finishing Up

The example code included with this tutorial is a modified version of the example program from the first tutorial. I'm not planning on creating another tutorial on strictly events, excepting perhaps a user-interface guide.

I promise the next tutorial will cover more..."interesting"... topics.

Functions Covered in this Tutorial: SDL_PollEvent, SDL_WaitEvent, SDL_WM_SetCaption, SDL_WM_GetCaption

Code: tutorial2.tgz