#pragma section-numbers off
#pragma camelcase off
||<tablewidth="100%" style="color: #FF0000;" :> DRAFT||

##*^*^*^*^*See http://wiki.libsdl.org/moin.cgi/SGFunctions for details on editing this page*^*^*^*^*


= SDL_SetWindowHitTest =
Use this function to provide a callback that decides if a window region has special properties.


<<TableOfContents()>>


== Syntax ==
{{{#!highlight cpp
int SDL_SetWindowHitTest(SDL_Window* window,
                         SDL_HitTest callback,
                         void*       callback_data)
}}}


== Function Parameters ==
||'''window'''||the window to set hit-testing on||
||'''callback'''||the function to call when doing a hit-test||
||'''callback_data'''||an app-defined void pointer passed to '''callback'''||


== Return Value ==
Returns 0 on success or -1 on error (including unsupported); call [[SDL_GetError]]() for more information.


== Code Examples ==
{{{#!highlight cpp
You can add your code example here
}}}

##Leave this section as-is unless you have a code example to put in.  In that case, replace You can add your code example here with your code example following the Style Guide instructions.  Leave the rest of the markup alone and delete this comment.


== Remarks ==
The function prototype for '''callback''' is:
 {{{#!highlight cpp
SDL_HitTestResult SDL_HitTest(SDL_Window*      win,
                              const SDL_Point* area,
                              void*            data)
}}}
 . where `SDL_HitTest` is your function name and its parameters are:
 ||`win`||the SDL_Window where hit-testing was set on ||
 ||`area`||an [[SDL_Point]] which should be hit-tested||
 ||`data`||what was passed as '''callback_data''' to SDL_!SetWindowHitTest()||
 . '''callback''' should return an [[SDL_HitTestResult]].

Normally windows are dragged and resized by decorations provided by the system window manager (a title bar, borders, etc), but for some apps, it makes sense to drag them from somewhere else inside the window itself; for example, one might have a borderless window that wants to be draggable from any part, or simulate its own title bar, etc.

This function lets the app provide a callback that designates pieces of a given window as special. This callback is run during event processing if we need to tell the OS to treat a region of the window specially; the use of this callback is known as "hit testing."

Mouse input may not be delivered to your application if it is within a special area; the OS will often apply that input to moving the window or resizing the window and not deliver it to the application.

Specifying NULL for a callback disables hit-testing. Hit-testing is disabled by default.

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, 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.

== Version ==
This function is available since SDL 2.0.4.

----
[[CategoryAPI]], [[CategoryVideo]]
##See the Style Guide for instructions on editing the footer.