WinRT: expanded the documentation on SDL_HINT_WINRT_HANDLE_BACK_BUTTON

include/SDL_hints.h

@@ -439,11 +439,54 @@ extern "C" {
  */
 #define SDL_HINT_WINRT_PRIVACY_POLICY_LABEL "SDL_WINRT_PRIVACY_POLICY_LABEL"
 
-/** \brief If set to "1", back button press events on Windows Phone 8+ will be marked as handled.
+/** \brief Allows back-button-press events on Windows Phone to be marked as handled
  *
- *  TODO, WinRT: document SDL_HINT_WINRT_HANDLE_BACK_BUTTON need and use
+ *  Windows Phone devices typically feature a Back button.  When pressed,
- *  For now, more details on why this is needed can be found at the
+ *  the OS will emit back-button-press events, which apps are expected to
- *  beginning of the following web page:
+ *  handle in an appropriate manner.  If apps do not explicitly mark these
+ *  events as 'Handled', then the OS will invoke its default behavior for
+ *  unhandled back-button-press events, which on Windows Phone 8 and 8.1 is to
+ *  terminate the app (and attempt to switch to the previous app, or to the
+ *  device's home screen).
+ *
+ *  Setting the SDL_HINT_WINRT_HANDLE_BACK_BUTTON hint to "1" will cause SDL
+ *  to mark back-button-press events as Handled, if and when one is sent to
+ *  the app.
+ *
+ *  Internally, Windows Phone sends back button events as parameters to
+ *  special back-button-press callback functions.  Apps that need to respond
+ *  to back-button-press events are expected to register one or more
+ *  callback functions for such, shortly after being launched (during the
+ *  app's initialization phase).  After the back button is pressed, the OS
+ *  will invoke these callbacks.  If the app's callback(s) do not explicitly
+ *  mark the event as handled by the time they return, or if the app never
+ *  registers one of these callback, the OS will consider the event
+ *  un-handled, and it will apply its default back button behavior (terminate
+ *  the app).
+ *
+ *  SDL registers its own back-button-press callback with the Windows Phone
+ *  OS.  This callback will emit a pair of SDL key-press events (SDL_KEYDOWN
+ *  and SDL_KEYUP), each with a scancode of SDL_SCANCODE_AC_BACK, after which
+ *  it will check the contents of the hint, SDL_HINT_WINRT_HANDLE_BACK_BUTTON.
+ *  If the hint's value is set to "1", the back button event's Handled
+ *  property will get set to 'true'.  If the hint's value is set to something
+ *  else, or if it is unset, SDL will leave the event's Handled property
+ *  alone.  (By default, the OS sets this property to 'false', to note.)
+ *
+ *  SDL apps can either set SDL_HINT_WINRT_HANDLE_BACK_BUTTON well before a
+ *  back button is pressed, or can set it in direct-response to a back button
+ *  being pressed.
+ *
+ *  In order to get notified when a back button is pressed, SDL apps should
+ *  register a callback function with SDL_AddEventWatch(), and have it listen
+ *  for SDL_KEYDOWN events that have a scancode of SDL_SCANCODE_AC_BACK.
+ *  (Alternatively, SDL_KEYUP events can be listened-for.  Listening for
+ *  either event type is suitable.)  Any value of SDL_HINT_WINRT_HANDLE_BACK_BUTTON
+ *  set by such a callback, will be applied to the OS' current
+ *  back-button-press event.
+ *
+ *  More details on back button behavior in Windows Phone apps can be found
+ *  at the following page, on Microsoft's developer site:
  *  http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj247550(v=vs.105).aspx
  */
 #define SDL_HINT_WINRT_HANDLE_BACK_BUTTON "SDL_WINRT_HANDLE_BACK_BUTTON"