From 661548c8f34ae5d3c2c37c657fe7c1a6c44efd34 Mon Sep 17 00:00:00 2001 From: "Ryan C. Gordon" Date: Thu, 29 May 2014 13:38:39 -0400 Subject: [PATCH] Tweaked hit-testing documentation. --- include/SDL_video.h | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/include/SDL_video.h b/include/SDL_video.h index 6ccb115b33cf8..7d52e6a512bbc 100644 --- a/include/SDL_video.h +++ b/include/SDL_video.h @@ -791,6 +791,11 @@ extern DECLSPEC int SDLCALL SDL_GetWindowGammaRamp(SDL_Window * window, 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 @@ typedef enum /* !!! 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 @@ typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win, * 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.