Video | Events | Audio | CD-ROM | Threads |
Introduction | Function Reference | Examples |
Polls for currently pending events, and returns
Waits indefinitely for the next available event, returning
This function allows you to set the state of processing certain events.
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:
If the filter returns
Structures: (Declared in SDL_events.h)
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.
If you want to get the current state of the application, use the function
Keyboard Events:
A keyboard event is generated every time a key on the keyboard is pressed
or released.
If you wish to translate a keysym to it's ASCII representation,
use the function
At any time the current of the keyboard can be obtained as an array
of keystates using:
At any time the current key modifier state can be obtained using:
Mouse Motion Events:
The mouse motion event contains a bitmask of which buttons are down,
which can be tested using the
At any time, the current mouse state can be retrieved using the function:
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.
Quit Events:
An
There are no functions directly affecting the quit event.
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
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
extern int SDL_PollEvent(SDL_Event *event);
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);
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);
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);
typedef int (*SDL_EventFilter)(const SDL_Event *event);
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.
/* 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;
/* 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 */
extern Uint8 SDL_GetAppState(void);
/* Keysym structure */
typedef struct {
SDLKey sym; /* The SDL keysym */
SDLMod mod; /* Any key modifications */
} 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;
extern Uint8 SDL_SymToASCII(SDL_keysym *keysym, char **symname);
If 'symname
' is not NULL
, it is set to
the name of the keysym, and the function returns the ASCII representation
of the keysym if it has one, 0 otherwise.
extern Uint8 *SDL_GetKeyState(int *numkeys);
This array is indexed using the SDL keysym names.
extern SDLMod SDL_GetModState(void);
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;
} SDL_MouseMotionEvent;
extern Uint8 SDL_GetMouseState(Uint16 *x, Uint16 *y);
The current x and y coordinates are saved in 'x
' and
'y
', and the current button state is returned.
/* 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;
typedef struct {
Uint8 type; /* Always SDL_QUIT */
} SDL_QuitEvent;
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.
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;
SDL_VERSION()
macro found in SDL_version.h, and pass it to
the function:
extern int SDL_GetWMInfo(SDL_SysWMinfo *info);