include/SDL_syswm.h
changeset 3407 d3baf5ac4e37
parent 3274 08574b033f37
child 3685 64ce267332c6
     1.1 --- a/include/SDL_syswm.h	Sun Oct 18 23:21:15 2009 +0000
     1.2 +++ b/include/SDL_syswm.h	Mon Oct 19 13:31:58 2009 +0000
     1.3 @@ -21,9 +21,9 @@
     1.4  */
     1.5  
     1.6  /**
     1.7 - * \file SDL_syswm.h
     1.8 - *
     1.9 - * Include file for SDL custom system window manager hooks
    1.10 + *  \file SDL_syswm.h
    1.11 + *  
    1.12 + *  Include file for SDL custom system window manager hooks.
    1.13   */
    1.14  
    1.15  #ifndef _SDL_syswm_h
    1.16 @@ -42,11 +42,14 @@
    1.17  /* *INDENT-ON* */
    1.18  #endif
    1.19  
    1.20 -/* Your application has access to a special type of event 'SDL_SYSWMEVENT',
    1.21 -   which contains window-manager specific information and arrives whenever
    1.22 -   an unhandled window event occurs.  This event is ignored by default, but
    1.23 -   you can enable it with SDL_EventState()
    1.24 -*/
    1.25 +/**
    1.26 + *  \file SDL_syswm.h
    1.27 + *  
    1.28 + *  Your application has access to a special type of event ::SDL_SYSWMEVENT,
    1.29 + *  which contains window-manager specific information and arrives whenever
    1.30 + *  an unhandled window event occurs.  This event is ignored by default, but
    1.31 + *  you can enable it with SDL_EventState().
    1.32 + */
    1.33  #ifdef SDL_PROTOTYPES_ONLY
    1.34  struct SDL_SysWMinfo;
    1.35  #else
    1.36 @@ -66,13 +69,17 @@
    1.37  #undef Cursor
    1.38  #endif
    1.39  
    1.40 -/* These are the various supported subsystems under UNIX */
    1.41 +/** 
    1.42 + *  These are the various supported subsystems under UNIX.
    1.43 + */
    1.44  typedef enum
    1.45  {
    1.46      SDL_SYSWM_X11
    1.47  } SDL_SYSWM_TYPE;
    1.48  
    1.49 -/* The UNIX custom event structure */
    1.50 +/**
    1.51 + *  The UNIX custom event structure.
    1.52 + */
    1.53  struct SDL_SysWMmsg
    1.54  {
    1.55      SDL_version version;
    1.56 @@ -83,9 +90,11 @@
    1.57      } event;
    1.58  };
    1.59  
    1.60 -/* The UNIX custom window manager information structure.
    1.61 -   When this structure is returned, it holds information about which
    1.62 -   low level system it is using, and will be one of SDL_SYSWM_TYPE.
    1.63 +/**
    1.64 + *  The UNIX custom window manager information structure.
    1.65 + *
    1.66 + *  When this structure is returned, it holds information about which
    1.67 + *  low level system it is using, and will be one of SDL_SYSWM_TYPE.
    1.68   */
    1.69  struct SDL_SysWMinfo
    1.70  {
    1.71 @@ -95,19 +104,26 @@
    1.72      {
    1.73          struct
    1.74          {
    1.75 -            Display *display;   /* The X11 display */
    1.76 -            Window window;      /* The X11 display window */
    1.77 -            /* These locking functions should be called around
    1.78 -               any X11 functions using the display variable.
    1.79 -               They lock the event thread, so should not be
    1.80 -               called around event functions or from event filters.
    1.81 +            Display *display;   /**< The X11 display */
    1.82 +            Window window;      /**< The X11 display window */
    1.83 +            /**
    1.84 +             *  These locking functions should be called around
    1.85 +             *  any X11 functions using the display variable.
    1.86 +             *  They lock the event thread, so should not be
    1.87 +             *  called around event functions or from event filters.
    1.88               */
    1.89 +            /*@{*/
    1.90              void (*lock_func) (void);
    1.91              void (*unlock_func) (void);
    1.92 +            /*@}*/
    1.93  
    1.94 -            /* Introduced in SDL 1.0.2 */
    1.95 -            Window fswindow;    /* The X11 fullscreen window */
    1.96 -            Window wmwindow;    /* The X11 managed input window */
    1.97 +            /**
    1.98 +             *  Introduced in SDL 1.0.2.
    1.99 +             */
   1.100 +            /*@{*/
   1.101 +            Window fswindow;    /**< The X11 fullscreen window */
   1.102 +            Window wmwindow;    /**< The X11 managed input window */
   1.103 +            /*@}*/
   1.104          } x11;
   1.105      } info;
   1.106  };
   1.107 @@ -116,40 +132,48 @@
   1.108  #define WIN32_LEAN_AND_MEAN
   1.109  #include <windows.h>
   1.110  
   1.111 -/* The windows custom event structure */
   1.112 +/**
   1.113 + *  The windows custom event structure.
   1.114 + */
   1.115  struct SDL_SysWMmsg
   1.116  {
   1.117      SDL_version version;
   1.118 -    HWND hwnd;                  /* The window for the message */
   1.119 -    UINT msg;                   /* The type of message */
   1.120 -    WPARAM wParam;              /* WORD message parameter */
   1.121 -    LPARAM lParam;              /* LONG message parameter */
   1.122 +    HWND hwnd;                  /**< The window for the message */
   1.123 +    UINT msg;                   /**< The type of message */
   1.124 +    WPARAM wParam;              /**< WORD message parameter */
   1.125 +    LPARAM lParam;              /**< LONG message parameter */
   1.126  };
   1.127  
   1.128 -/* The windows custom window manager information structure */
   1.129 +/**
   1.130 + *  The windows custom window manager information structure.
   1.131 + */
   1.132  struct SDL_SysWMinfo
   1.133  {
   1.134      SDL_version version;
   1.135 -    HWND window;                /* The Win32 display window */
   1.136 +    HWND window;                /**< The Win32 display window */
   1.137  };
   1.138  
   1.139  #elif defined(SDL_VIDEO_DRIVER_RISCOS)
   1.140  
   1.141 -/* RISC OS custom event structure */
   1.142 +/**
   1.143 + *  RISC OS custom event structure.
   1.144 + */
   1.145  struct SDL_SysWMmsg
   1.146  {
   1.147      SDL_version version;
   1.148 -    int eventCode;              /* The window for the message */
   1.149 +    int eventCode;              /**< The window for the message */
   1.150      int pollBlock[64];
   1.151  };
   1.152  
   1.153 -/* The RISC OS custom window manager information structure */
   1.154 +/**
   1.155 + *  The RISC OS custom window manager information structure.
   1.156 + */
   1.157  struct SDL_SysWMinfo
   1.158  {
   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  };
   1.167  
   1.168  #elif defined(SDL_VIDEO_DRIVER_PHOTON) || defined(SDL_VIDEO_DRIVER_QNXGF)
   1.169 @@ -159,14 +183,18 @@
   1.170  #endif /* SDL_VIDEO_OPENGL_ES */
   1.171  #include <Ph.h>
   1.172  
   1.173 -/* The QNX custom event structure */
   1.174 +/**
   1.175 + * The QNX custom event structure.
   1.176 + */
   1.177  struct SDL_SysWMmsg
   1.178  {
   1.179      SDL_version version;
   1.180      int data;
   1.181  };
   1.182  
   1.183 -/* The QNX Photon custom window manager information structure */
   1.184 +/**
   1.185 + *  The QNX Photon custom window manager information structure.
   1.186 + */
   1.187  struct SDL_SysWMinfo
   1.188  {
   1.189      SDL_version version;
   1.190 @@ -175,14 +203,18 @@
   1.191  
   1.192  #else
   1.193  
   1.194 -/* The generic custom event structure */
   1.195 +/**
   1.196 + *  The generic custom event structure.
   1.197 + */
   1.198  struct SDL_SysWMmsg
   1.199  {
   1.200      SDL_version version;
   1.201      int data;
   1.202  };
   1.203  
   1.204 -/* The generic custom window manager information structure */
   1.205 +/**
   1.206 + *  The generic custom window manager information structure.
   1.207 + */
   1.208  struct SDL_SysWMinfo
   1.209  {
   1.210      SDL_version version;
   1.211 @@ -197,21 +229,21 @@
   1.212  
   1.213  /* Function prototypes */
   1.214  /**
   1.215 - * \fn SDL_bool SDL_GetWindowWMInfo (SDL_WindowID windowID, SDL_SysWMinfo * info)
   1.216 - *
   1.217 - * \brief This function allows access to driver-dependent window information.
   1.218 - *
   1.219 - * \param windowID The window about which information is being requested
   1.220 - * \param info This structure must be initialized with the SDL version, and is then filled in with information about the given window.
   1.221 - *
   1.222 - * \return SDL_TRUE if the function is implemented and the version member of the 'info' struct is valid, SDL_FALSE otherwise.
   1.223 - *
   1.224 - * You typically use this function like this:
   1.225 - * \code
   1.226 - * SDL_SysWMInfo info;
   1.227 - * SDL_VERSION(&info.version);
   1.228 - * if ( SDL_GetWindowWMInfo(&info) ) { ... }
   1.229 - * \endcode
   1.230 + *  \brief This function allows access to driver-dependent window information.
   1.231 + *  
   1.232 + *  \param windowID The window about which information is being requested
   1.233 + *  \param info This structure must be initialized with the SDL version, and is 
   1.234 + *              then filled in with information about the given window.
   1.235 + *  
   1.236 + *  \return SDL_TRUE if the function is implemented and the version member of 
   1.237 + *          the \c info struct is valid, SDL_FALSE otherwise.
   1.238 + *  
   1.239 + *  You typically use this function like this:
   1.240 + *  \code
   1.241 + *  SDL_SysWMInfo info;
   1.242 + *  SDL_VERSION(&info.version);
   1.243 + *  if ( SDL_GetWindowWMInfo(&info) ) { ... }
   1.244 + *  \endcode
   1.245   */
   1.246  extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowWMInfo(SDL_WindowID windowID,
   1.247                                                       SDL_SysWMinfo * info);