Tweaked hit-testing documentation.
authorRyan C. Gordon <icculus@icculus.org>
Thu, 29 May 2014 13:38:39 -0400
changeset 8937 e5caf226926d
parent 8936 59cbb9959346
child 8938 c73bac338b90
Tweaked hit-testing documentation.
include/SDL_video.h
--- a/include/SDL_video.h	Wed May 28 01:27:27 2014 -0400
+++ b/include/SDL_video.h	Thu May 29 13:38:39 2014 -0400
@@ -791,6 +791,11 @@
                                                    Uint16 * green,
                                                    Uint16 * blue);
 
+/**
+ *  \brief Possible return values from the SDL_HitTest callback.
+ *
+ *  \sa SDL_HitTest
+ */
 typedef enum
 {
     SDL_HITTEST_NORMAL,  /**< Region is normal. No special properties. */
@@ -798,6 +803,11 @@
     /* !!! FIXME: resize enums here. */
 } SDL_HitTestResult;
 
+/**
+ *  \brief Callback used for hit-testing.
+ *
+ *  \sa SDL_SetWindowHitTest
+ */
 typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win,
                                                  const SDL_Point *area,
                                                  void *data);
@@ -826,7 +836,13 @@
  *  Platforms that don't support this functionality will return -1
  *  unconditionally, even if you're attempting to disable hit-testing.
  *
- *  Your callback may fire at any time.
+ *  Your callback may fire at any time, and its firing does not indicate any
+ *  specific behavior (for example, on Windows, this certainly might fire
+ *  when the OS is deciding whether to drag your window, but it fires for lots
+ *  of other reasons, too, some unrelated to anything you probably care about
+ *  _and when the mouse isn't actually at the location it is testing_).
+ *  Since this can fire at any time, you should try to keep your callback
+ *  efficient, devoid of allocations, etc.
  *
  *  \param window The window to set hit-testing on.
  *  \param callback The callback to call when doing a hit-test.