include/SDL_video.h
changeset 8937 e5caf226926d
parent 8935 9d2f0236322b
child 8946 c9592936dffc
     1.1 --- a/include/SDL_video.h	Wed May 28 01:27:27 2014 -0400
     1.2 +++ b/include/SDL_video.h	Thu May 29 13:38:39 2014 -0400
     1.3 @@ -791,6 +791,11 @@
     1.4                                                     Uint16 * green,
     1.5                                                     Uint16 * blue);
     1.6  
     1.7 +/**
     1.8 + *  \brief Possible return values from the SDL_HitTest callback.
     1.9 + *
    1.10 + *  \sa SDL_HitTest
    1.11 + */
    1.12  typedef enum
    1.13  {
    1.14      SDL_HITTEST_NORMAL,  /**< Region is normal. No special properties. */
    1.15 @@ -798,6 +803,11 @@
    1.16      /* !!! FIXME: resize enums here. */
    1.17  } SDL_HitTestResult;
    1.18  
    1.19 +/**
    1.20 + *  \brief Callback used for hit-testing.
    1.21 + *
    1.22 + *  \sa SDL_SetWindowHitTest
    1.23 + */
    1.24  typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win,
    1.25                                                   const SDL_Point *area,
    1.26                                                   void *data);
    1.27 @@ -826,7 +836,13 @@
    1.28   *  Platforms that don't support this functionality will return -1
    1.29   *  unconditionally, even if you're attempting to disable hit-testing.
    1.30   *
    1.31 - *  Your callback may fire at any time.
    1.32 + *  Your callback may fire at any time, and its firing does not indicate any
    1.33 + *  specific behavior (for example, on Windows, this certainly might fire
    1.34 + *  when the OS is deciding whether to drag your window, but it fires for lots
    1.35 + *  of other reasons, too, some unrelated to anything you probably care about
    1.36 + *  _and when the mouse isn't actually at the location it is testing_).
    1.37 + *  Since this can fire at any time, you should try to keep your callback
    1.38 + *  efficient, devoid of allocations, etc.
    1.39   *
    1.40   *  \param window The window to set hit-testing on.
    1.41   *  \param callback The callback to call when doing a hit-test.