include/SDL_events.h
author Sam Lantinga <slouken@libsdl.org>
Fri, 20 Jan 2006 13:07:25 +0000
changeset 1258 b2283b0ded26
parent 930 02759105b989
child 1294 1760ceb23bc6
permissions -rw-r--r--
Date: Thu, 19 Jan 2006 20:02:29 +0200
From: Vassilis Virvilis <vasvir@iit.demokritos.gr>
Subject: [SDL] Request: Please reconsider adding tag in SDL_Event

Hi,

Patch in question:

--- include/SDL_events.h 20 Aug 2004 18:57:01 -0000 1.11
+++ include/SDL_events.h 19 Jan 2006 17:35:09 -0000
@@ -214,7 +214,7 @@
} SDL_SysWMEvent;

/* General event structure */
-typedef union {
+typedef union SDL_Event {
Uint8 type;
SDL_ActiveEvent active;
SDL_KeyboardEvent key;

Reasoning:
----------
1) Allows forward declaration of the SDL_Event union in C++. Please
note that in plain C it is possible to forward declare it.

2) Forward declaration is good because it allows encapsulation. It hides
the specific implementation and does not necessarily exposes SDL staff
to my appication's namespace

3) It can't harm plain C because tags are living in a different namespace
than typenames

4) It is already done like this in other places in SDL. Check for example
SDL_KeySym, and SDL_.*Event structures.

5) Right now I have to include SDL/event.h from a C++ header file. See 2)
slouken@0
     1
/*
slouken@0
     2
    SDL - Simple DirectMedia Layer
slouken@769
     3
    Copyright (C) 1997-2004 Sam Lantinga
slouken@0
     4
slouken@0
     5
    This library is free software; you can redistribute it and/or
slouken@0
     6
    modify it under the terms of the GNU Library General Public
slouken@0
     7
    License as published by the Free Software Foundation; either
slouken@0
     8
    version 2 of the License, or (at your option) any later version.
slouken@0
     9
slouken@0
    10
    This library is distributed in the hope that it will be useful,
slouken@0
    11
    but WITHOUT ANY WARRANTY; without even the implied warranty of
slouken@0
    12
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
slouken@0
    13
    Library General Public License for more details.
slouken@0
    14
slouken@0
    15
    You should have received a copy of the GNU Library General Public
slouken@0
    16
    License along with this library; if not, write to the Free
slouken@0
    17
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
slouken@0
    18
slouken@0
    19
    Sam Lantinga
slouken@251
    20
    slouken@libsdl.org
slouken@0
    21
*/
slouken@0
    22
slouken@0
    23
#ifdef SAVE_RCSID
slouken@0
    24
static char rcsid =
slouken@0
    25
 "@(#) $Id$";
slouken@0
    26
#endif
slouken@0
    27
slouken@0
    28
/* Include file for SDL event handling */
slouken@0
    29
slouken@0
    30
#ifndef _SDL_events_h
slouken@0
    31
#define _SDL_events_h
slouken@0
    32
slouken@0
    33
#include "SDL_types.h"
slouken@0
    34
#include "SDL_active.h"
slouken@0
    35
#include "SDL_keyboard.h"
slouken@0
    36
#include "SDL_mouse.h"
slouken@0
    37
#include "SDL_joystick.h"
slouken@0
    38
#include "SDL_quit.h"
slouken@0
    39
slouken@0
    40
#include "begin_code.h"
slouken@0
    41
/* Set up for C function definitions, even when using C++ */
slouken@0
    42
#ifdef __cplusplus
slouken@0
    43
extern "C" {
slouken@0
    44
#endif
slouken@0
    45
slouken@0
    46
/* Event enumerations */
slouken@0
    47
enum { SDL_NOEVENT = 0,			/* Unused (do not remove) */
slouken@0
    48
       SDL_ACTIVEEVENT,			/* Application loses/gains visibility */
slouken@0
    49
       SDL_KEYDOWN,			/* Keys pressed */
slouken@0
    50
       SDL_KEYUP,			/* Keys released */
slouken@0
    51
       SDL_MOUSEMOTION,			/* Mouse moved */
slouken@0
    52
       SDL_MOUSEBUTTONDOWN,		/* Mouse button pressed */
slouken@0
    53
       SDL_MOUSEBUTTONUP,		/* Mouse button released */
slouken@0
    54
       SDL_JOYAXISMOTION,		/* Joystick axis motion */
slouken@0
    55
       SDL_JOYBALLMOTION,		/* Joystick trackball motion */
slouken@0
    56
       SDL_JOYHATMOTION,		/* Joystick hat position change */
slouken@0
    57
       SDL_JOYBUTTONDOWN,		/* Joystick button pressed */
slouken@0
    58
       SDL_JOYBUTTONUP,			/* Joystick button released */
slouken@0
    59
       SDL_QUIT,			/* User-requested quit */
slouken@0
    60
       SDL_SYSWMEVENT,			/* System specific event */
slouken@0
    61
       SDL_EVENT_RESERVEDA,		/* Reserved for future use.. */
slouken@0
    62
       SDL_EVENT_RESERVEDB,		/* Reserved for future use.. */
slouken@0
    63
       SDL_VIDEORESIZE,			/* User resized video mode */
slouken@0
    64
       SDL_VIDEOEXPOSE,			/* Screen needs to be redrawn */
slouken@0
    65
       SDL_EVENT_RESERVED2,		/* Reserved for future use.. */
slouken@0
    66
       SDL_EVENT_RESERVED3,		/* Reserved for future use.. */
slouken@0
    67
       SDL_EVENT_RESERVED4,		/* Reserved for future use.. */
slouken@0
    68
       SDL_EVENT_RESERVED5,		/* Reserved for future use.. */
slouken@0
    69
       SDL_EVENT_RESERVED6,		/* Reserved for future use.. */
slouken@0
    70
       SDL_EVENT_RESERVED7,		/* Reserved for future use.. */
slouken@0
    71
       /* Events SDL_USEREVENT through SDL_MAXEVENTS-1 are for your use */
slouken@0
    72
       SDL_USEREVENT = 24,
slouken@0
    73
       /* This last event is only for bounding internal arrays
slouken@0
    74
	  It is the number of bits in the event mask datatype -- Uint32
slouken@0
    75
        */
slouken@0
    76
       SDL_NUMEVENTS = 32
slouken@0
    77
};
slouken@0
    78
slouken@0
    79
/* Predefined event masks */
slouken@0
    80
#define SDL_EVENTMASK(X)	(1<<(X))
slouken@0
    81
enum {
slouken@0
    82
	SDL_ACTIVEEVENTMASK	= SDL_EVENTMASK(SDL_ACTIVEEVENT),
slouken@0
    83
	SDL_KEYDOWNMASK		= SDL_EVENTMASK(SDL_KEYDOWN),
slouken@0
    84
	SDL_KEYUPMASK		= SDL_EVENTMASK(SDL_KEYUP),
slouken@0
    85
	SDL_MOUSEMOTIONMASK	= SDL_EVENTMASK(SDL_MOUSEMOTION),
slouken@0
    86
	SDL_MOUSEBUTTONDOWNMASK	= SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN),
slouken@0
    87
	SDL_MOUSEBUTTONUPMASK	= SDL_EVENTMASK(SDL_MOUSEBUTTONUP),
slouken@0
    88
	SDL_MOUSEEVENTMASK	= SDL_EVENTMASK(SDL_MOUSEMOTION)|
slouken@0
    89
	                          SDL_EVENTMASK(SDL_MOUSEBUTTONDOWN)|
slouken@0
    90
	                          SDL_EVENTMASK(SDL_MOUSEBUTTONUP),
slouken@0
    91
	SDL_JOYAXISMOTIONMASK	= SDL_EVENTMASK(SDL_JOYAXISMOTION),
slouken@0
    92
	SDL_JOYBALLMOTIONMASK	= SDL_EVENTMASK(SDL_JOYBALLMOTION),
slouken@0
    93
	SDL_JOYHATMOTIONMASK	= SDL_EVENTMASK(SDL_JOYHATMOTION),
slouken@0
    94
	SDL_JOYBUTTONDOWNMASK	= SDL_EVENTMASK(SDL_JOYBUTTONDOWN),
slouken@0
    95
	SDL_JOYBUTTONUPMASK	= SDL_EVENTMASK(SDL_JOYBUTTONUP),
slouken@0
    96
	SDL_JOYEVENTMASK	= SDL_EVENTMASK(SDL_JOYAXISMOTION)|
slouken@0
    97
	                          SDL_EVENTMASK(SDL_JOYBALLMOTION)|
slouken@0
    98
	                          SDL_EVENTMASK(SDL_JOYHATMOTION)|
slouken@0
    99
	                          SDL_EVENTMASK(SDL_JOYBUTTONDOWN)|
slouken@0
   100
	                          SDL_EVENTMASK(SDL_JOYBUTTONUP),
slouken@0
   101
	SDL_VIDEORESIZEMASK	= SDL_EVENTMASK(SDL_VIDEORESIZE),
slouken@0
   102
	SDL_VIDEOEXPOSEMASK	= SDL_EVENTMASK(SDL_VIDEOEXPOSE),
slouken@0
   103
	SDL_QUITMASK		= SDL_EVENTMASK(SDL_QUIT),
slouken@0
   104
	SDL_SYSWMEVENTMASK	= SDL_EVENTMASK(SDL_SYSWMEVENT)
slouken@0
   105
};
slouken@0
   106
#define SDL_ALLEVENTS		0xFFFFFFFF
slouken@0
   107
slouken@0
   108
/* Application visibility event structure */
slouken@911
   109
typedef struct SDL_ActiveEvent {
slouken@0
   110
	Uint8 type;	/* SDL_ACTIVEEVENT */
slouken@0
   111
	Uint8 gain;	/* Whether given states were gained or lost (1/0) */
slouken@0
   112
	Uint8 state;	/* A mask of the focus states */
slouken@0
   113
} SDL_ActiveEvent;
slouken@0
   114
slouken@0
   115
/* Keyboard event structure */
slouken@911
   116
typedef struct SDL_KeyboardEvent {
slouken@0
   117
	Uint8 type;	/* SDL_KEYDOWN or SDL_KEYUP */
slouken@0
   118
	Uint8 which;	/* The keyboard device index */
slouken@0
   119
	Uint8 state;	/* SDL_PRESSED or SDL_RELEASED */
slouken@0
   120
	SDL_keysym keysym;
slouken@0
   121
} SDL_KeyboardEvent;
slouken@0
   122
slouken@0
   123
/* Mouse motion event structure */
slouken@911
   124
typedef struct SDL_MouseMotionEvent {
slouken@0
   125
	Uint8 type;	/* SDL_MOUSEMOTION */
slouken@0
   126
	Uint8 which;	/* The mouse device index */
slouken@0
   127
	Uint8 state;	/* The current button state */
slouken@0
   128
	Uint16 x, y;	/* The X/Y coordinates of the mouse */
slouken@0
   129
	Sint16 xrel;	/* The relative motion in the X direction */
slouken@0
   130
	Sint16 yrel;	/* The relative motion in the Y direction */
slouken@0
   131
} SDL_MouseMotionEvent;
slouken@0
   132
slouken@0
   133
/* Mouse button event structure */
slouken@911
   134
typedef struct SDL_MouseButtonEvent {
slouken@0
   135
	Uint8 type;	/* SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP */
slouken@0
   136
	Uint8 which;	/* The mouse device index */
slouken@0
   137
	Uint8 button;	/* The mouse button index */
slouken@0
   138
	Uint8 state;	/* SDL_PRESSED or SDL_RELEASED */
slouken@0
   139
	Uint16 x, y;	/* The X/Y coordinates of the mouse at press time */
slouken@0
   140
} SDL_MouseButtonEvent;
slouken@0
   141
slouken@0
   142
/* Joystick axis motion event structure */
slouken@911
   143
typedef struct SDL_JoyAxisEvent {
slouken@0
   144
	Uint8 type;	/* SDL_JOYAXISMOTION */
slouken@0
   145
	Uint8 which;	/* The joystick device index */
slouken@0
   146
	Uint8 axis;	/* The joystick axis index */
slouken@0
   147
	Sint16 value;	/* The axis value (range: -32768 to 32767) */
slouken@0
   148
} SDL_JoyAxisEvent;
slouken@0
   149
slouken@0
   150
/* Joystick trackball motion event structure */
slouken@911
   151
typedef struct SDL_JoyBallEvent {
slouken@0
   152
	Uint8 type;	/* SDL_JOYBALLMOTION */
slouken@0
   153
	Uint8 which;	/* The joystick device index */
slouken@0
   154
	Uint8 ball;	/* The joystick trackball index */
slouken@0
   155
	Sint16 xrel;	/* The relative motion in the X direction */
slouken@0
   156
	Sint16 yrel;	/* The relative motion in the Y direction */
slouken@0
   157
} SDL_JoyBallEvent;
slouken@0
   158
slouken@0
   159
/* Joystick hat position change event structure */
slouken@911
   160
typedef struct SDL_JoyHatEvent {
slouken@0
   161
	Uint8 type;	/* SDL_JOYHATMOTION */
slouken@0
   162
	Uint8 which;	/* The joystick device index */
slouken@0
   163
	Uint8 hat;	/* The joystick hat index */
slouken@0
   164
	Uint8 value;	/* The hat position value:
slouken@577
   165
			    SDL_HAT_LEFTUP   SDL_HAT_UP       SDL_HAT_RIGHTUP
slouken@577
   166
			    SDL_HAT_LEFT     SDL_HAT_CENTERED SDL_HAT_RIGHT
slouken@577
   167
			    SDL_HAT_LEFTDOWN SDL_HAT_DOWN     SDL_HAT_RIGHTDOWN
slouken@0
   168
			   Note that zero means the POV is centered.
slouken@0
   169
			*/
slouken@0
   170
} SDL_JoyHatEvent;
slouken@0
   171
slouken@0
   172
/* Joystick button event structure */
slouken@911
   173
typedef struct SDL_JoyButtonEvent {
slouken@0
   174
	Uint8 type;	/* SDL_JOYBUTTONDOWN or SDL_JOYBUTTONUP */
slouken@0
   175
	Uint8 which;	/* The joystick device index */
slouken@0
   176
	Uint8 button;	/* The joystick button index */
slouken@0
   177
	Uint8 state;	/* SDL_PRESSED or SDL_RELEASED */
slouken@0
   178
} SDL_JoyButtonEvent;
slouken@0
   179
slouken@0
   180
/* The "window resized" event
slouken@0
   181
   When you get this event, you are responsible for setting a new video
slouken@0
   182
   mode with the new width and height.
slouken@0
   183
 */
slouken@911
   184
typedef struct SDL_ResizeEvent {
slouken@0
   185
	Uint8 type;	/* SDL_VIDEORESIZE */
slouken@0
   186
	int w;		/* New width */
slouken@0
   187
	int h;		/* New height */
slouken@0
   188
} SDL_ResizeEvent;
slouken@0
   189
slouken@0
   190
/* The "screen redraw" event */
slouken@911
   191
typedef struct SDL_ExposeEvent {
slouken@0
   192
	Uint8 type;	/* SDL_VIDEOEXPOSE */
slouken@0
   193
} SDL_ExposeEvent;
slouken@0
   194
slouken@0
   195
/* The "quit requested" event */
slouken@911
   196
typedef struct SDL_QuitEvent {
slouken@0
   197
	Uint8 type;	/* SDL_QUIT */
slouken@0
   198
} SDL_QuitEvent;
slouken@0
   199
slouken@0
   200
/* A user-defined event type */
slouken@911
   201
typedef struct SDL_UserEvent {
slouken@0
   202
	Uint8 type;	/* SDL_USEREVENT through SDL_NUMEVENTS-1 */
slouken@0
   203
	int code;	/* User defined event code */
slouken@0
   204
	void *data1;	/* User defined data pointer */
slouken@0
   205
	void *data2;	/* User defined data pointer */
slouken@0
   206
} SDL_UserEvent;
slouken@0
   207
slouken@0
   208
/* If you want to use this event, you should include SDL_syswm.h */
slouken@0
   209
struct SDL_SysWMmsg;
slouken@0
   210
typedef struct SDL_SysWMmsg SDL_SysWMmsg;
slouken@911
   211
typedef struct SDL_SysWMEvent {
slouken@0
   212
	Uint8 type;
slouken@0
   213
	SDL_SysWMmsg *msg;
slouken@0
   214
} SDL_SysWMEvent;
slouken@0
   215
slouken@0
   216
/* General event structure */
slouken@1258
   217
typedef union SDL_Event {
slouken@0
   218
	Uint8 type;
slouken@0
   219
	SDL_ActiveEvent active;
slouken@0
   220
	SDL_KeyboardEvent key;
slouken@0
   221
	SDL_MouseMotionEvent motion;
slouken@0
   222
	SDL_MouseButtonEvent button;
slouken@0
   223
	SDL_JoyAxisEvent jaxis;
slouken@0
   224
	SDL_JoyBallEvent jball;
slouken@0
   225
	SDL_JoyHatEvent jhat;
slouken@0
   226
	SDL_JoyButtonEvent jbutton;
slouken@0
   227
	SDL_ResizeEvent resize;
slouken@0
   228
	SDL_ExposeEvent expose;
slouken@0
   229
	SDL_QuitEvent quit;
slouken@0
   230
	SDL_UserEvent user;
slouken@0
   231
	SDL_SysWMEvent syswm;
slouken@0
   232
} SDL_Event;
slouken@0
   233
slouken@0
   234
slouken@0
   235
/* Function prototypes */
slouken@0
   236
slouken@0
   237
/* Pumps the event loop, gathering events from the input devices.
slouken@0
   238
   This function updates the event queue and internal input device state.
slouken@0
   239
   This should only be run in the thread that sets the video mode.
slouken@0
   240
*/
slouken@337
   241
extern DECLSPEC void SDLCALL SDL_PumpEvents(void);
slouken@0
   242
slouken@0
   243
/* Checks the event queue for messages and optionally returns them.
slouken@0
   244
   If 'action' is SDL_ADDEVENT, up to 'numevents' events will be added to
slouken@0
   245
   the back of the event queue.
slouken@0
   246
   If 'action' is SDL_PEEKEVENT, up to 'numevents' events at the front
slouken@0
   247
   of the event queue, matching 'mask', will be returned and will not
slouken@0
   248
   be removed from the queue.
slouken@0
   249
   If 'action' is SDL_GETEVENT, up to 'numevents' events at the front 
slouken@0
   250
   of the event queue, matching 'mask', will be returned and will be
slouken@0
   251
   removed from the queue.
slouken@0
   252
   This function returns the number of events actually stored, or -1
slouken@0
   253
   if there was an error.  This function is thread-safe.
slouken@0
   254
*/
slouken@0
   255
typedef enum {
slouken@0
   256
	SDL_ADDEVENT,
slouken@0
   257
	SDL_PEEKEVENT,
slouken@0
   258
	SDL_GETEVENT
slouken@0
   259
} SDL_eventaction;
slouken@0
   260
/* */
slouken@337
   261
extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event *events, int numevents,
slouken@0
   262
				SDL_eventaction action, Uint32 mask);
slouken@0
   263
slouken@0
   264
/* Polls for currently pending events, and returns 1 if there are any pending
slouken@0
   265
   events, or 0 if there are none available.  If 'event' is not NULL, the next
slouken@0
   266
   event is removed from the queue and stored in that area.
slouken@0
   267
 */
slouken@337
   268
extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event *event);
slouken@0
   269
slouken@0
   270
/* Waits indefinitely for the next available event, returning 1, or 0 if there
slouken@0
   271
   was an error while waiting for events.  If 'event' is not NULL, the next
slouken@0
   272
   event is removed from the queue and stored in that area.
slouken@0
   273
 */
slouken@337
   274
extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event *event);
slouken@0
   275
slouken@0
   276
/* Add an event to the event queue.
slouken@844
   277
   This function returns 0 on success, or -1 if the event queue was full
slouken@844
   278
   or there was some other error.
slouken@0
   279
 */
slouken@337
   280
extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event *event);
slouken@0
   281
slouken@0
   282
/*
slouken@0
   283
  This function sets up a filter to process all events before they
slouken@0
   284
  change internal state and are posted to the internal event queue.
slouken@0
   285
slouken@0
   286
  The filter is protypted as:
slouken@0
   287
*/
slouken@930
   288
typedef int (SDLCALL *SDL_EventFilter)(const SDL_Event *event);
slouken@0
   289
/*
slouken@0
   290
  If the filter returns 1, then the event will be added to the internal queue.
slouken@0
   291
  If it returns 0, then the event will be dropped from the queue, but the 
slouken@0
   292
  internal state will still be updated.  This allows selective filtering of
slouken@0
   293
  dynamically arriving events.
slouken@0
   294
slouken@0
   295
  WARNING:  Be very careful of what you do in the event filter function, as 
slouken@0
   296
            it may run in a different thread!
slouken@0
   297
slouken@0
   298
  There is one caveat when dealing with the SDL_QUITEVENT event type.  The
slouken@0
   299
  event filter is only called when the window manager desires to close the
slouken@0
   300
  application window.  If the event filter returns 1, then the window will
slouken@0
   301
  be closed, otherwise the window will remain open if possible.
slouken@0
   302
  If the quit event is generated by an interrupt signal, it will bypass the
slouken@0
   303
  internal queue and be delivered to the application at the next event poll.
slouken@0
   304
*/
slouken@337
   305
extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter);
slouken@0
   306
slouken@0
   307
/*
slouken@0
   308
  Return the current event filter - can be used to "chain" filters.
slouken@0
   309
  If there is no event filter set, this function returns NULL.
slouken@0
   310
*/
slouken@337
   311
extern DECLSPEC SDL_EventFilter SDLCALL SDL_GetEventFilter(void);
slouken@0
   312
slouken@0
   313
/*
slouken@0
   314
  This function allows you to set the state of processing certain events.
slouken@0
   315
  If 'state' is set to SDL_IGNORE, that event will be automatically dropped
slouken@0
   316
  from the event queue and will not event be filtered.
slouken@0
   317
  If 'state' is set to SDL_ENABLE, that event will be processed normally.
slouken@0
   318
  If 'state' is set to SDL_QUERY, SDL_EventState() will return the 
slouken@0
   319
  current processing state of the specified event.
slouken@0
   320
*/
slouken@0
   321
#define SDL_QUERY	-1
slouken@0
   322
#define SDL_IGNORE	 0
slouken@0
   323
#define SDL_DISABLE	 0
slouken@0
   324
#define SDL_ENABLE	 1
slouken@337
   325
extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint8 type, int state);
slouken@0
   326
slouken@0
   327
slouken@0
   328
/* Ends C function definitions when using C++ */
slouken@0
   329
#ifdef __cplusplus
slouken@0
   330
}
slouken@0
   331
#endif
slouken@0
   332
#include "close_code.h"
slouken@0
   333
slouken@0
   334
#endif /* _SDL_events_h */