WinRT: expanded the documentation on SDL_HINT_WINRT_HANDLE_BACK_BUTTON
authorDavid Ludwig <dludwig@pobox.com>
Sat, 04 Oct 2014 14:59:41 -0400
changeset 91543331d2f57704
parent 9153 b0a76d1f4a56
child 9155 dfeb88fc5a9d
WinRT: expanded the documentation on SDL_HINT_WINRT_HANDLE_BACK_BUTTON
include/SDL_hints.h
     1.1 --- a/include/SDL_hints.h	Tue Sep 30 11:20:50 2014 -0700
     1.2 +++ b/include/SDL_hints.h	Sat Oct 04 14:59:41 2014 -0400
     1.3 @@ -439,11 +439,54 @@
     1.4   */
     1.5  #define SDL_HINT_WINRT_PRIVACY_POLICY_LABEL "SDL_WINRT_PRIVACY_POLICY_LABEL"
     1.6  
     1.7 -/** \brief If set to "1", back button press events on Windows Phone 8+ will be marked as handled.
     1.8 +/** \brief Allows back-button-press events on Windows Phone to be marked as handled
     1.9   *
    1.10 - *  TODO, WinRT: document SDL_HINT_WINRT_HANDLE_BACK_BUTTON need and use
    1.11 - *  For now, more details on why this is needed can be found at the
    1.12 - *  beginning of the following web page:
    1.13 + *  Windows Phone devices typically feature a Back button.  When pressed,
    1.14 + *  the OS will emit back-button-press events, which apps are expected to
    1.15 + *  handle in an appropriate manner.  If apps do not explicitly mark these
    1.16 + *  events as 'Handled', then the OS will invoke its default behavior for
    1.17 + *  unhandled back-button-press events, which on Windows Phone 8 and 8.1 is to
    1.18 + *  terminate the app (and attempt to switch to the previous app, or to the
    1.19 + *  device's home screen).
    1.20 + *
    1.21 + *  Setting the SDL_HINT_WINRT_HANDLE_BACK_BUTTON hint to "1" will cause SDL
    1.22 + *  to mark back-button-press events as Handled, if and when one is sent to
    1.23 + *  the app.
    1.24 + *
    1.25 + *  Internally, Windows Phone sends back button events as parameters to
    1.26 + *  special back-button-press callback functions.  Apps that need to respond
    1.27 + *  to back-button-press events are expected to register one or more
    1.28 + *  callback functions for such, shortly after being launched (during the
    1.29 + *  app's initialization phase).  After the back button is pressed, the OS
    1.30 + *  will invoke these callbacks.  If the app's callback(s) do not explicitly
    1.31 + *  mark the event as handled by the time they return, or if the app never
    1.32 + *  registers one of these callback, the OS will consider the event
    1.33 + *  un-handled, and it will apply its default back button behavior (terminate
    1.34 + *  the app).
    1.35 + *
    1.36 + *  SDL registers its own back-button-press callback with the Windows Phone
    1.37 + *  OS.  This callback will emit a pair of SDL key-press events (SDL_KEYDOWN
    1.38 + *  and SDL_KEYUP), each with a scancode of SDL_SCANCODE_AC_BACK, after which
    1.39 + *  it will check the contents of the hint, SDL_HINT_WINRT_HANDLE_BACK_BUTTON.
    1.40 + *  If the hint's value is set to "1", the back button event's Handled
    1.41 + *  property will get set to 'true'.  If the hint's value is set to something
    1.42 + *  else, or if it is unset, SDL will leave the event's Handled property
    1.43 + *  alone.  (By default, the OS sets this property to 'false', to note.)
    1.44 + *
    1.45 + *  SDL apps can either set SDL_HINT_WINRT_HANDLE_BACK_BUTTON well before a
    1.46 + *  back button is pressed, or can set it in direct-response to a back button
    1.47 + *  being pressed.
    1.48 + *
    1.49 + *  In order to get notified when a back button is pressed, SDL apps should
    1.50 + *  register a callback function with SDL_AddEventWatch(), and have it listen
    1.51 + *  for SDL_KEYDOWN events that have a scancode of SDL_SCANCODE_AC_BACK.
    1.52 + *  (Alternatively, SDL_KEYUP events can be listened-for.  Listening for
    1.53 + *  either event type is suitable.)  Any value of SDL_HINT_WINRT_HANDLE_BACK_BUTTON
    1.54 + *  set by such a callback, will be applied to the OS' current
    1.55 + *  back-button-press event.
    1.56 + *
    1.57 + *  More details on back button behavior in Windows Phone apps can be found
    1.58 + *  at the following page, on Microsoft's developer site:
    1.59   *  http://msdn.microsoft.com/en-us/library/windowsphone/develop/jj247550(v=vs.105).aspx
    1.60   */
    1.61  #define SDL_HINT_WINRT_HANDLE_BACK_BUTTON "SDL_WINRT_HANDLE_BACK_BUTTON"