include/SDL_video.h
changeset 8935 9d2f0236322b
parent 8931 44d8a2f4b431
child 8937 e5caf226926d
     1.1 --- a/include/SDL_video.h	Tue May 27 15:47:25 2014 -0400
     1.2 +++ b/include/SDL_video.h	Wed May 28 01:22:47 2014 -0400
     1.3 @@ -791,43 +791,51 @@
     1.4                                                     Uint16 * green,
     1.5                                                     Uint16 * blue);
     1.6  
     1.7 +typedef enum
     1.8 +{
     1.9 +    SDL_HITTEST_NORMAL,  /**< Region is normal. No special properties. */
    1.10 +    SDL_HITTEST_DRAGGABLE,  /**< Region can drag entire window. */
    1.11 +    /* !!! FIXME: resize enums here. */
    1.12 +} SDL_HitTestResult;
    1.13 +
    1.14 +typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win,
    1.15 +                                                 const SDL_Point *area,
    1.16 +                                                 void *data);
    1.17 +
    1.18  /**
    1.19 - *  \brief Define regions of a window that can be used to drag it.
    1.20 + *  \brief Provide a callback that decides if a window region has special properties.
    1.21   *
    1.22 - *  Normally windows are dragged by decorations provided by the system
    1.23 - *  window manager (usually, a title bar), but for some apps, it makes sense
    1.24 - *  to drag them from somewhere else inside the window itself; for example,
    1.25 - *  one might have a borderless window that wants to be draggable from any
    1.26 - *  part, or simulate its own title bar, etc.
    1.27 + *  Normally windows are dragged and resized by decorations provided by the
    1.28 + *  system window manager (a title bar, borders, etc), but for some apps, it
    1.29 + *  makes sense to drag them from somewhere else inside the window itself; for
    1.30 + *  example, one might have a borderless window that wants to be draggable
    1.31 + *  from any part, or simulate its own title bar, etc.
    1.32   *
    1.33 - *  This method designates pieces of a given window as "drag areas," which
    1.34 - *  will move the window when the user drags with his mouse, as if she had
    1.35 - *  used the titlebar.
    1.36 - *
    1.37 - *  You may specify multiple drag areas, disconnected or overlapping. This
    1.38 - *  function accepts an array of rectangles. Each call to this function will
    1.39 - *  replace any previously-defined drag areas. To disable drag areas on a
    1.40 - *  window, call this function with a NULL array of zero elements.
    1.41 - *
    1.42 - *  Drag areas do not automatically resize. If your window changes dimensions
    1.43 - *  you should plan to re-call this function with new drag areas if
    1.44 - *  appropriate.
    1.45 + *  This function lets the app provide a callback that designates pieces of
    1.46 + *  a given window as special. This callback is run during event processing
    1.47 + *  if we need to tell the OS to treat a region of the window specially; the
    1.48 + *  use of this callback is known as "hit testing."
    1.49   *
    1.50   *  Mouse input may not be delivered to your application if it is within
    1.51 - *  a drag area; the OS will often apply that input to moving the window and
    1.52 - *  not deliver it to the application.
    1.53 + *  a special area; the OS will often apply that input to moving the window or
    1.54 + *  resizing the window and not deliver it to the application.
    1.55 + *
    1.56 + *  Specifying NULL for a callback disables hit-testing. Hit-testing is
    1.57 + *  disabled by default.
    1.58   *
    1.59   *  Platforms that don't support this functionality will return -1
    1.60 - *  unconditionally, even if you're attempting to disable drag areas.
    1.61 + *  unconditionally, even if you're attempting to disable hit-testing.
    1.62   *
    1.63 - *  \param window The window to set drag areas on.
    1.64 - *  \param areas An array of SDL_Rects containing num_areas elements.
    1.65 - *  \param num_areas The number of elements in the areas parameter.
    1.66 + *  Your callback may fire at any time.
    1.67 + *
    1.68 + *  \param window The window to set hit-testing on.
    1.69 + *  \param callback The callback to call when doing a hit-test.
    1.70 + *  \param callback_data An app-defined void pointer passed to the callback.
    1.71   *  \return 0 on success, -1 on error (including unsupported).
    1.72   */
    1.73 -extern DECLSPEC int SDLCALL SDL_SetWindowDragAreas(SDL_Window * window,
    1.74 -                                                   const SDL_Rect *areas,
    1.75 -                                                   int num_areas);
    1.76 +extern DECLSPEC int SDLCALL SDL_SetWindowHitTest(SDL_Window * window,
    1.77 +                                                 SDL_HitTest callback,
    1.78 +                                                 void *callback_data);
    1.79  
    1.80  /**
    1.81   *  \brief Destroy a window.