Fixed bug 2263 - Event timestamp members are undocumented
authorSam Lantinga <slouken@libsdl.org>
Mon, 14 Aug 2017 21:40:40 -0700
changeset 11302657c10a0a705
parent 11301 68c83ddf9096
child 11303 23000b73ce4e
Fixed bug 2263 - Event timestamp members are undocumented

Charles Huber

The event timestamp members should be documented to indicate their meaning and units.

Currently the timestamps are populated using SDL_GetTicks() in SDL_PushEvent() in SDL_events.c.
include/SDL_events.h
     1.1 --- a/include/SDL_events.h	Mon Aug 14 21:35:16 2017 -0700
     1.2 +++ b/include/SDL_events.h	Mon Aug 14 21:40:40 2017 -0700
     1.3 @@ -165,7 +165,7 @@
     1.4  typedef struct SDL_CommonEvent
     1.5  {
     1.6      Uint32 type;
     1.7 -    Uint32 timestamp;
     1.8 +    Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
     1.9  } SDL_CommonEvent;
    1.10  
    1.11  /**
    1.12 @@ -174,7 +174,7 @@
    1.13  typedef struct SDL_WindowEvent
    1.14  {
    1.15      Uint32 type;        /**< ::SDL_WINDOWEVENT */
    1.16 -    Uint32 timestamp;
    1.17 +    Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
    1.18      Uint32 windowID;    /**< The associated window */
    1.19      Uint8 event;        /**< ::SDL_WindowEventID */
    1.20      Uint8 padding1;
    1.21 @@ -190,7 +190,7 @@
    1.22  typedef struct SDL_KeyboardEvent
    1.23  {
    1.24      Uint32 type;        /**< ::SDL_KEYDOWN or ::SDL_KEYUP */
    1.25 -    Uint32 timestamp;
    1.26 +    Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
    1.27      Uint32 windowID;    /**< The window with keyboard focus, if any */
    1.28      Uint8 state;        /**< ::SDL_PRESSED or ::SDL_RELEASED */
    1.29      Uint8 repeat;       /**< Non-zero if this is a key repeat */
    1.30 @@ -206,7 +206,7 @@
    1.31  typedef struct SDL_TextEditingEvent
    1.32  {
    1.33      Uint32 type;                                /**< ::SDL_TEXTEDITING */
    1.34 -    Uint32 timestamp;
    1.35 +    Uint32 timestamp;                           /**< In milliseconds, populated using SDL_GetTicks() */
    1.36      Uint32 windowID;                            /**< The window with keyboard focus, if any */
    1.37      char text[SDL_TEXTEDITINGEVENT_TEXT_SIZE];  /**< The editing text */
    1.38      Sint32 start;                               /**< The start cursor of selected editing text */
    1.39 @@ -221,7 +221,7 @@
    1.40  typedef struct SDL_TextInputEvent
    1.41  {
    1.42      Uint32 type;                              /**< ::SDL_TEXTINPUT */
    1.43 -    Uint32 timestamp;
    1.44 +    Uint32 timestamp;                         /**< In milliseconds, populated using SDL_GetTicks() */
    1.45      Uint32 windowID;                          /**< The window with keyboard focus, if any */
    1.46      char text[SDL_TEXTINPUTEVENT_TEXT_SIZE];  /**< The input text */
    1.47  } SDL_TextInputEvent;
    1.48 @@ -232,7 +232,7 @@
    1.49  typedef struct SDL_MouseMotionEvent
    1.50  {
    1.51      Uint32 type;        /**< ::SDL_MOUSEMOTION */
    1.52 -    Uint32 timestamp;
    1.53 +    Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
    1.54      Uint32 windowID;    /**< The window with mouse focus, if any */
    1.55      Uint32 which;       /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
    1.56      Uint32 state;       /**< The current button state */
    1.57 @@ -248,7 +248,7 @@
    1.58  typedef struct SDL_MouseButtonEvent
    1.59  {
    1.60      Uint32 type;        /**< ::SDL_MOUSEBUTTONDOWN or ::SDL_MOUSEBUTTONUP */
    1.61 -    Uint32 timestamp;
    1.62 +    Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
    1.63      Uint32 windowID;    /**< The window with mouse focus, if any */
    1.64      Uint32 which;       /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
    1.65      Uint8 button;       /**< The mouse button index */
    1.66 @@ -265,7 +265,7 @@
    1.67  typedef struct SDL_MouseWheelEvent
    1.68  {
    1.69      Uint32 type;        /**< ::SDL_MOUSEWHEEL */
    1.70 -    Uint32 timestamp;
    1.71 +    Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
    1.72      Uint32 windowID;    /**< The window with mouse focus, if any */
    1.73      Uint32 which;       /**< The mouse instance id, or SDL_TOUCH_MOUSEID */
    1.74      Sint32 x;           /**< The amount scrolled horizontally, positive to the right and negative to the left */
    1.75 @@ -279,7 +279,7 @@
    1.76  typedef struct SDL_JoyAxisEvent
    1.77  {
    1.78      Uint32 type;        /**< ::SDL_JOYAXISMOTION */
    1.79 -    Uint32 timestamp;
    1.80 +    Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
    1.81      SDL_JoystickID which; /**< The joystick instance id */
    1.82      Uint8 axis;         /**< The joystick axis index */
    1.83      Uint8 padding1;
    1.84 @@ -295,7 +295,7 @@
    1.85  typedef struct SDL_JoyBallEvent
    1.86  {
    1.87      Uint32 type;        /**< ::SDL_JOYBALLMOTION */
    1.88 -    Uint32 timestamp;
    1.89 +    Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
    1.90      SDL_JoystickID which; /**< The joystick instance id */
    1.91      Uint8 ball;         /**< The joystick trackball index */
    1.92      Uint8 padding1;
    1.93 @@ -311,7 +311,7 @@
    1.94  typedef struct SDL_JoyHatEvent
    1.95  {
    1.96      Uint32 type;        /**< ::SDL_JOYHATMOTION */
    1.97 -    Uint32 timestamp;
    1.98 +    Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
    1.99      SDL_JoystickID which; /**< The joystick instance id */
   1.100      Uint8 hat;          /**< The joystick hat index */
   1.101      Uint8 value;        /**< The hat position value.
   1.102 @@ -331,7 +331,7 @@
   1.103  typedef struct SDL_JoyButtonEvent
   1.104  {
   1.105      Uint32 type;        /**< ::SDL_JOYBUTTONDOWN or ::SDL_JOYBUTTONUP */
   1.106 -    Uint32 timestamp;
   1.107 +    Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
   1.108      SDL_JoystickID which; /**< The joystick instance id */
   1.109      Uint8 button;       /**< The joystick button index */
   1.110      Uint8 state;        /**< ::SDL_PRESSED or ::SDL_RELEASED */
   1.111 @@ -345,7 +345,7 @@
   1.112  typedef struct SDL_JoyDeviceEvent
   1.113  {
   1.114      Uint32 type;        /**< ::SDL_JOYDEVICEADDED or ::SDL_JOYDEVICEREMOVED */
   1.115 -    Uint32 timestamp;
   1.116 +    Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
   1.117      Sint32 which;       /**< The joystick device index for the ADDED event, instance id for the REMOVED event */
   1.118  } SDL_JoyDeviceEvent;
   1.119  
   1.120 @@ -356,7 +356,7 @@
   1.121  typedef struct SDL_ControllerAxisEvent
   1.122  {
   1.123      Uint32 type;        /**< ::SDL_CONTROLLERAXISMOTION */
   1.124 -    Uint32 timestamp;
   1.125 +    Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
   1.126      SDL_JoystickID which; /**< The joystick instance id */
   1.127      Uint8 axis;         /**< The controller axis (SDL_GameControllerAxis) */
   1.128      Uint8 padding1;
   1.129 @@ -373,7 +373,7 @@
   1.130  typedef struct SDL_ControllerButtonEvent
   1.131  {
   1.132      Uint32 type;        /**< ::SDL_CONTROLLERBUTTONDOWN or ::SDL_CONTROLLERBUTTONUP */
   1.133 -    Uint32 timestamp;
   1.134 +    Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
   1.135      SDL_JoystickID which; /**< The joystick instance id */
   1.136      Uint8 button;       /**< The controller button (SDL_GameControllerButton) */
   1.137      Uint8 state;        /**< ::SDL_PRESSED or ::SDL_RELEASED */
   1.138 @@ -388,7 +388,7 @@
   1.139  typedef struct SDL_ControllerDeviceEvent
   1.140  {
   1.141      Uint32 type;        /**< ::SDL_CONTROLLERDEVICEADDED, ::SDL_CONTROLLERDEVICEREMOVED, or ::SDL_CONTROLLERDEVICEREMAPPED */
   1.142 -    Uint32 timestamp;
   1.143 +    Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
   1.144      Sint32 which;       /**< The joystick device index for the ADDED event, instance id for the REMOVED or REMAPPED event */
   1.145  } SDL_ControllerDeviceEvent;
   1.146  
   1.147 @@ -398,7 +398,7 @@
   1.148  typedef struct SDL_AudioDeviceEvent
   1.149  {
   1.150      Uint32 type;        /**< ::SDL_AUDIODEVICEADDED, or ::SDL_AUDIODEVICEREMOVED */
   1.151 -    Uint32 timestamp;
   1.152 +    Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
   1.153      Uint32 which;       /**< The audio device index for the ADDED event (valid until next SDL_GetNumAudioDevices() call), SDL_AudioDeviceID for the REMOVED event */
   1.154      Uint8 iscapture;    /**< zero if an output device, non-zero if a capture device. */
   1.155      Uint8 padding1;
   1.156 @@ -413,7 +413,7 @@
   1.157  typedef struct SDL_TouchFingerEvent
   1.158  {
   1.159      Uint32 type;        /**< ::SDL_FINGERMOTION or ::SDL_FINGERDOWN or ::SDL_FINGERUP */
   1.160 -    Uint32 timestamp;
   1.161 +    Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
   1.162      SDL_TouchID touchId; /**< The touch device id */
   1.163      SDL_FingerID fingerId;
   1.164      float x;            /**< Normalized in the range 0...1 */
   1.165 @@ -430,7 +430,7 @@
   1.166  typedef struct SDL_MultiGestureEvent
   1.167  {
   1.168      Uint32 type;        /**< ::SDL_MULTIGESTURE */
   1.169 -    Uint32 timestamp;
   1.170 +    Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
   1.171      SDL_TouchID touchId; /**< The touch device id */
   1.172      float dTheta;
   1.173      float dDist;
   1.174 @@ -447,7 +447,7 @@
   1.175  typedef struct SDL_DollarGestureEvent
   1.176  {
   1.177      Uint32 type;        /**< ::SDL_DOLLARGESTURE or ::SDL_DOLLARRECORD */
   1.178 -    Uint32 timestamp;
   1.179 +    Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
   1.180      SDL_TouchID touchId; /**< The touch device id */
   1.181      SDL_GestureID gestureId;
   1.182      Uint32 numFingers;
   1.183 @@ -465,7 +465,7 @@
   1.184  typedef struct SDL_DropEvent
   1.185  {
   1.186      Uint32 type;        /**< ::SDL_DROPBEGIN or ::SDL_DROPFILE or ::SDL_DROPTEXT or ::SDL_DROPCOMPLETE */
   1.187 -    Uint32 timestamp;
   1.188 +    Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
   1.189      char *file;         /**< The file name, which should be freed with SDL_free(), is NULL on begin/complete */
   1.190      Uint32 windowID;    /**< The window that was dropped on, if any */
   1.191  } SDL_DropEvent;
   1.192 @@ -477,7 +477,7 @@
   1.193  typedef struct SDL_QuitEvent
   1.194  {
   1.195      Uint32 type;        /**< ::SDL_QUIT */
   1.196 -    Uint32 timestamp;
   1.197 +    Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
   1.198  } SDL_QuitEvent;
   1.199  
   1.200  /**
   1.201 @@ -486,7 +486,7 @@
   1.202  typedef struct SDL_OSEvent
   1.203  {
   1.204      Uint32 type;        /**< ::SDL_QUIT */
   1.205 -    Uint32 timestamp;
   1.206 +    Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
   1.207  } SDL_OSEvent;
   1.208  
   1.209  /**
   1.210 @@ -495,7 +495,7 @@
   1.211  typedef struct SDL_UserEvent
   1.212  {
   1.213      Uint32 type;        /**< ::SDL_USEREVENT through ::SDL_LASTEVENT-1 */
   1.214 -    Uint32 timestamp;
   1.215 +    Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
   1.216      Uint32 windowID;    /**< The associated window if any */
   1.217      Sint32 code;        /**< User defined event code */
   1.218      void *data1;        /**< User defined data pointer */
   1.219 @@ -515,7 +515,7 @@
   1.220  typedef struct SDL_SysWMEvent
   1.221  {
   1.222      Uint32 type;        /**< ::SDL_SYSWMEVENT */
   1.223 -    Uint32 timestamp;
   1.224 +    Uint32 timestamp;   /**< In milliseconds, populated using SDL_GetTicks() */
   1.225      SDL_SysWMmsg *msg;  /**< driver dependent data, defined in SDL_syswm.h */
   1.226  } SDL_SysWMEvent;
   1.227