include/SDL_syswm.h
branchSDL-1.2
changeset 4217 4c4113c2162c
parent 4159 a1b03ba2fcd0
child 4544 3f2d351d8274
     1.1 --- a/include/SDL_syswm.h	Mon Sep 21 09:27:08 2009 +0000
     1.2 +++ b/include/SDL_syswm.h	Mon Sep 21 09:38:10 2009 +0000
     1.3 @@ -20,7 +20,9 @@
     1.4      slouken@libsdl.org
     1.5  */
     1.6  
     1.7 -/* Include file for SDL custom system window manager hooks */
     1.8 +/** @file SDL_syswm.h
     1.9 + *  Include file for SDL custom system window manager hooks
    1.10 + */
    1.11  
    1.12  #ifndef _SDL_syswm_h
    1.13  #define _SDL_syswm_h
    1.14 @@ -35,11 +37,12 @@
    1.15  extern "C" {
    1.16  #endif
    1.17  
    1.18 -/* Your application has access to a special type of event 'SDL_SYSWMEVENT',
    1.19 -   which contains window-manager specific information and arrives whenever
    1.20 -   an unhandled window event occurs.  This event is ignored by default, but
    1.21 -   you can enable it with SDL_EventState()
    1.22 -*/
    1.23 +/** @file SDL_syswm.h
    1.24 + *  Your application has access to a special type of event 'SDL_SYSWMEVENT',
    1.25 + *  which contains window-manager specific information and arrives whenever
    1.26 + *  an unhandled window event occurs.  This event is ignored by default, but
    1.27 + *  you can enable it with SDL_EventState()
    1.28 + */
    1.29  #ifdef SDL_PROTOTYPES_ONLY
    1.30  struct SDL_SysWMinfo;
    1.31  typedef struct SDL_SysWMinfo SDL_SysWMinfo;
    1.32 @@ -60,12 +63,12 @@
    1.33  #undef Cursor
    1.34  #endif
    1.35  
    1.36 -/* These are the various supported subsystems under UNIX */
    1.37 +/** These are the various supported subsystems under UNIX */
    1.38  typedef enum {
    1.39  	SDL_SYSWM_X11
    1.40  } SDL_SYSWM_TYPE;
    1.41  
    1.42 -/* The UNIX custom event structure */
    1.43 +/** The UNIX custom event structure */
    1.44  struct SDL_SysWMmsg {
    1.45  	SDL_version version;
    1.46  	SDL_SYSWM_TYPE subsystem;
    1.47 @@ -74,32 +77,38 @@
    1.48  	} event;
    1.49  };
    1.50  
    1.51 -/* The UNIX custom window manager information structure.
    1.52 -   When this structure is returned, it holds information about which
    1.53 -   low level system it is using, and will be one of SDL_SYSWM_TYPE.
    1.54 +/** The UNIX custom window manager information structure.
    1.55 + *  When this structure is returned, it holds information about which
    1.56 + *  low level system it is using, and will be one of SDL_SYSWM_TYPE.
    1.57   */
    1.58  typedef struct SDL_SysWMinfo {
    1.59  	SDL_version version;
    1.60  	SDL_SYSWM_TYPE subsystem;
    1.61  	union {
    1.62  	    struct {
    1.63 -	    	Display *display;	/* The X11 display */
    1.64 -	    	Window window;		/* The X11 display window */
    1.65 -		/* These locking functions should be called around
    1.66 -                   any X11 functions using the display variable, 
    1.67 -                   but not the gfxdisplay variable.
    1.68 -                   They lock the event thread, so should not be
    1.69 -		   called around event functions or from event filters.
    1.70 +	    	Display *display;	/**< The X11 display */
    1.71 +	    	Window window;		/**< The X11 display window */
    1.72 +		/** These locking functions should be called around
    1.73 +                 *  any X11 functions using the display variable, 
    1.74 +                 *  but not the gfxdisplay variable.
    1.75 +                 *  They lock the event thread, so should not be
    1.76 +		 *  called around event functions or from event filters.
    1.77  		 */
    1.78 +                /*@{*/
    1.79  		void (*lock_func)(void);
    1.80  		void (*unlock_func)(void);
    1.81 +                /*@}*/
    1.82  
    1.83 -		/* Introduced in SDL 1.0.2 */
    1.84 -	    	Window fswindow;	/* The X11 fullscreen window */
    1.85 -	    	Window wmwindow;	/* The X11 managed input window */
    1.86 +		/** @name Introduced in SDL 1.0.2 */
    1.87 +                /*@{*/
    1.88 +	    	Window fswindow;	/**< The X11 fullscreen window */
    1.89 +	    	Window wmwindow;	/**< The X11 managed input window */
    1.90 +                /*@}*/
    1.91  
    1.92 -		/* Introduced in SDL 1.2.12 */
    1.93 -		Display *gfxdisplay;	/* The X11 display to which rendering is done */
    1.94 +		/** @name Introduced in SDL 1.2.12 */
    1.95 +                /*@{*/
    1.96 +		Display *gfxdisplay;	/**< The X11 display to which rendering is done */
    1.97 +                /*@}*/
    1.98  	    } x11;
    1.99  	} info;
   1.100  } SDL_SysWMinfo;
   1.101 @@ -107,13 +116,13 @@
   1.102  #elif defined(SDL_VIDEO_DRIVER_NANOX)
   1.103  #include <microwin/nano-X.h>
   1.104  
   1.105 -/* The generic custom event structure */
   1.106 +/** The generic custom event structure */
   1.107  struct SDL_SysWMmsg {
   1.108  	SDL_version version;
   1.109  	int data;
   1.110  };
   1.111  
   1.112 -/* The windows custom window manager information structure */
   1.113 +/** The windows custom window manager information structure */
   1.114  typedef struct SDL_SysWMinfo {
   1.115  	SDL_version version ;
   1.116  	GR_WINDOW_ID window ;	/* The display window */
   1.117 @@ -123,50 +132,50 @@
   1.118  #define WIN32_LEAN_AND_MEAN
   1.119  #include <windows.h>
   1.120  
   1.121 -/* The windows custom event structure */
   1.122 +/** The windows custom event structure */
   1.123  struct SDL_SysWMmsg {
   1.124  	SDL_version version;
   1.125 -	HWND hwnd;			/* The window for the message */
   1.126 -	UINT msg;			/* The type of message */
   1.127 -	WPARAM wParam;			/* WORD message parameter */
   1.128 -	LPARAM lParam;			/* LONG message parameter */
   1.129 +	HWND hwnd;			/**< The window for the message */
   1.130 +	UINT msg;			/**< The type of message */
   1.131 +	WPARAM wParam;			/**< WORD message parameter */
   1.132 +	LPARAM lParam;			/**< LONG message parameter */
   1.133  };
   1.134  
   1.135 -/* The windows custom window manager information structure */
   1.136 +/** The windows custom window manager information structure */
   1.137  typedef struct SDL_SysWMinfo {
   1.138  	SDL_version version;
   1.139 -	HWND window;			/* The Win32 display window */
   1.140 -	HGLRC hglrc;			/* The OpenGL context, if any */
   1.141 +	HWND window;			/**< The Win32 display window */
   1.142 +	HGLRC hglrc;			/**< The OpenGL context, if any */
   1.143  } SDL_SysWMinfo;
   1.144  
   1.145  #elif defined(SDL_VIDEO_DRIVER_RISCOS)
   1.146  
   1.147 -/* RISC OS custom event structure */
   1.148 +/** RISC OS custom event structure */
   1.149  struct SDL_SysWMmsg {
   1.150  	SDL_version version;
   1.151 -	int eventCode;		/* The window for the message */
   1.152 +	int eventCode;		/**< The window for the message */
   1.153  	int pollBlock[64];
   1.154  };
   1.155  
   1.156 -/* The RISC OS custom window manager information structure */
   1.157 +/** The RISC OS custom window manager information structure */
   1.158  typedef struct SDL_SysWMinfo {
   1.159  	SDL_version version;
   1.160 -	int wimpVersion;    /* Wimp version running under */
   1.161 -	int taskHandle;     /* The RISC OS task handle */
   1.162 -	int window;		/* The RISC OS display window */
   1.163 +	int wimpVersion;    /**< Wimp version running under */
   1.164 +	int taskHandle;     /**< The RISC OS task handle */
   1.165 +	int window;		/**< The RISC OS display window */
   1.166  } SDL_SysWMinfo;
   1.167  
   1.168  #elif defined(SDL_VIDEO_DRIVER_PHOTON)
   1.169  #include <sys/neutrino.h>
   1.170  #include <Ph.h>
   1.171  
   1.172 -/* The QNX custom event structure */
   1.173 +/** The QNX custom event structure */
   1.174  struct SDL_SysWMmsg {
   1.175  	SDL_version version;
   1.176  	int data;
   1.177  };
   1.178  
   1.179 -/* The QNX custom window manager information structure */
   1.180 +/** The QNX custom window manager information structure */
   1.181  typedef struct SDL_SysWMinfo {
   1.182  	SDL_version version;
   1.183  	int data;
   1.184 @@ -174,13 +183,13 @@
   1.185  
   1.186  #else
   1.187  
   1.188 -/* The generic custom event structure */
   1.189 +/** The generic custom event structure */
   1.190  struct SDL_SysWMmsg {
   1.191  	SDL_version version;
   1.192  	int data;
   1.193  };
   1.194  
   1.195 -/* The generic custom window manager information structure */
   1.196 +/** The generic custom window manager information structure */
   1.197  typedef struct SDL_SysWMinfo {
   1.198  	SDL_version version;
   1.199  	int data;
   1.200 @@ -191,16 +200,18 @@
   1.201  #endif /* SDL_PROTOTYPES_ONLY */
   1.202  
   1.203  /* Function prototypes */
   1.204 -/*
   1.205 +/**
   1.206   * This function gives you custom hooks into the window manager information.
   1.207   * It fills the structure pointed to by 'info' with custom information and
   1.208   * returns 1 if the function is implemented.  If it's not implemented, or
   1.209   * the version member of the 'info' structure is invalid, it returns 0. 
   1.210   *
   1.211   * You typically use this function like this:
   1.212 + * @code
   1.213   * SDL_SysWMInfo info;
   1.214   * SDL_VERSION(&info.version);
   1.215   * if ( SDL_GetWMInfo(&info) ) { ... }
   1.216 + * @endcode
   1.217   */
   1.218  extern DECLSPEC int SDLCALL SDL_GetWMInfo(SDL_SysWMinfo *info);
   1.219