Video Events Audio CD-ROM Threads

Event Function Reference

Introduction Function Reference Examples

extern void SDL_PumpEvents(void);

Pumps the event loop, gathering events from the input devices. This function updates the event queue and internal input device state. This should only be run in the thread that sets the video mode.

extern int SDL_PeepEvents(SDL_Event *events, int numevents, SDL_eventaction action, Uint32 mask)

Checks the event queue for messages and optionally returns them.
If 'action' is SDL_ADDEVENT, up to 'numevents' events will be added to the back of the event queue.
If 'action' is SDL_PEEKEVENT, up to 'numevents' events at the front of the event queue, matching 'mask', will be returned and will not be removed from the queue.
If 'action' is SDL_GETEVENT, up to 'numevents' events at the front of the event queue, matching 'mask', will be returned and will be removed from the queue.
This function returns the number of events actually stored, or -1 if there was an error. This function is thread-safe.

extern int SDL_PollEvent(SDL_Event *event);

Polls for currently pending events, and returns 1 if there are any pending events, or 0 if there are none available. If 'event' is not NULL, the next event is removed from the queue and stored in that area.

extern int SDL_WaitEvent(SDL_Event *event);

Waits indefinitely for the next available event, returning 1, or 0 if there was an error while waiting for events. If 'event' is not NULL, the next event is removed from the queue and stored in that area.

extern Uint8 SDL_EventState(Uint8 type, int state);

This function allows you to set the state of processing certain events.
If 'state' is set to SDL_IGNORE, that event will be automatically dropped from the event queue and will not event be filtered.
If 'state' is set to SDL_ENABLE, that event will be processed normally.
If 'state' is set to SDL_QUERY, SDL_EventState() will return the current processing state of the specified event.

extern void SDL_SetEventFilter(SDL_EventFilter filter);

This function sets up a filter to process all events before they are posted to the event queue. This is a very powerful and flexible feature. The filter is protypted as:

typedef int (*SDL_EventFilter)(const SDL_Event *event);

If the filter returns 1, then the event will be added to the internal queue. If it returns 0, then the event will be dropped from the queue. This allows selective filtering of dynamically arriving events.

Structures: (Declared in SDL_events.h) 


/* Predefined event masks */
#define SDL_EVENTMASK(X)       (1<<(X))
enum {
        SDL_ACTIVEEVENTMASK     = SDL_EVENTMASK(SDL_ACTIVEEVENT),
        SDL_KEYDOWNMASK         = SDL_EVENTMASK(SDL_KEYDOWN),
        SDL_KEYUPMASK           = SDL_EVENTMASK(SDL_KEYUP),
        SDL_MOUSEMOTIONMASK     = SDL_EVENTMASK(SDL_MOUSEMOTION),
        SDL_MOUSEBUTTONDOWNMASK = SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN),
        SDL_MOUSEBUTTONUPMASK   = SDL_EVENTMASK(SDL_MOUSEBUTTONUP),
        SDL_QUITMASK            = SDL_EVENTMASK(SDL_QUIT),
        SDL_SYSWMEVENTMASK      = SDL_EVENTMASK(SDL_SYSWMEVENT)
};
#define SDL_ALLEVENTS          0xFFFFFFFF

/* General event structure */
typedef union {
        Uint8 type;
        SDL_ActiveEvent active;
        SDL_KeyboardEvent key;
        SDL_MouseMotionEvent motion;
        SDL_MouseButtonEvent button;
        SDL_QuitEvent quit;
        SDL_SysWMEvent syswm;
} SDL_Event;

Activation Events:

The activation event contains a bitmask of the state change, along with a flag telling whether that state was gained or lost. This event is generated when the application gains or loses focus. It does not occur when the application first becomes visible, but if the application loses focus, it will receive this event. 


/* Application visibility event structure */
typedef struct {
        Uint8 type;
        Uint8 gain;
        Uint8 state;
} SDL_ActiveEvent;

/* The available application states */
#define SDL_APPMOUSEFOCUS       0x01            /* The app has mouse coverage */
#define SDL_APPINPUTFOCUS       0x02            /* The app has input focus */
#define SDL_APPACTIVE           0x04            /* The application is active */

If you want to get the current state of the application, use the function
extern Uint8 SDL_GetAppState(void);

Keyboard Events:

A keyboard event is generated every time a key on the keyboard is pressed or released. 


/* Keysym structure */
typedef struct {
        Uint8 scancode;                 /* hardware specific scancode */
        SDLKey sym;                     /* SDL virtual keysym */
        SDLMod mod;                     /* current key modifiers */
        Uint16 unicode;                 /* translated character */
} SDL_keysym;


/* Keyboard event structure */
typedef struct {
        Uint8 type;                     /* SDL_KEYDOWN or SDL_KEYUP */
        Uint8 state;                    /* SDL_PRESSED or SDL_RELEASED */
        SDL_keysym keysym;
} SDL_KeyboardEvent;

If you wish to translate a keysym to it's printable representation, you need to enable UNICODE translation using the function
extern int SDL_EnableUNICODE(int enable);
and then look in the 'unicode' member of the SDL_keysym structure. This value will be zero for keysyms that do not have a printable representation.

You can get the name of a keysym by using the function
extern char *SDL_GetKeyName(SDLKey key);

At any time the current state of the keyboard can be obtained as an array of keystates using:
extern Uint8 *SDL_GetKeyState(int *numkeys);
This array is indexed using the SDL keysym names.

At any time the current key modifier state can be obtained using:
extern SDLMod SDL_GetModState(void);

Mouse Motion Events:

The mouse motion event contains a bitmask of which buttons are down, which can be tested using the SDL_BUTTON(X) macro, and the current x and y coordinates of the mouse. This event is generated every time a mouse motion event is generated by the underlying window manager. 


/* Mouse motion event structure */
typedef struct {
        Uint8 type;                     /* Always SDL_MOUSEMOTION */
        Uint8 state;
        Uint16 x, y;
        Sint16 xrel;
        Sint16 yrel;
} SDL_MouseMotionEvent;

At any time, the current mouse state can be retrieved using the function:
extern Uint8 SDL_GetMouseState(Uint16 *x, Uint16 *y);
The current button state is returned as a button bitmask, which can be tested using the SDL_BUTTON(X) macros, and the current x and y coordinates are saved in 'x' and 'y'. You can pass NULL for either 'x' or 'y', if you want.

Mouse Button Events:

The mouse button event contains a button number, whether it is being pressed or released, and the x and y coordinates of the mouse at the time of the event. This event is generated when a mouse button is pressed or released. 


/* Mouse button event structure */
typedef struct {
        Uint8 type;             /* SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP */
        Uint8 state;            /* SDL_PRESSED or SDL_RELEASED */
        Uint8 button;
        Uint16 x, y;
} SDL_MouseButtonEvent;

Quit Events: 


typedef struct {
        Uint8 type;                     /* Always SDL_QUIT */
} SDL_QuitEvent;

An SDL_QUIT is generated when the user tries to close the application window. If it is ignored or filtered out, the window will remain open. If it is not ignored or filtered, it is queued normally and the window is allowed to close. When the window is closed, screen updates will complete, but have no effect.

SDL_Init() installs signal handlers for SIGINT (keyboard interrupt) and SIGTERM (system termination request), if handlers do not already exist, that generate SDL_QUIT events as well. There is no way to determine the cause of an SDL_QUIT, but setting a signal handler in your application will override the default generation of quit events for that signal.

There are no functions directly affecting the quit event, but a macro SDL_QuitRequested() will let you know whether or not the user has requested that the application quit (via closing the window or generating a keyboard interrupt.).

Unknown Window Events:

The system window manager event contains a pointer to system-specific information about unknown window manager events. If you enable this event using SDL_EventState(), it will be generated whenever unhandled events are received from the window manager. This can be used, for example, to implement cut-and-paste in your application. 


/* If you want to use this event, you should include SDL_syswm.h */
typedef struct {
        Uint8 type;
        SDL_SysWMmsg *msg;
} SDL_SysWMEvent;

If you want to obtain system-specific information about the window manager, you can fill the version member of a SDL_SysWMinfo structure using the SDL_VERSION() macro found in SDL_version.h, and pass it to the function:
extern int SDL_GetWMInfo(SDL_SysWMinfo *info);