SDL_HINT_WINRT_HANDLE_BACK_BUTTON(3)

NAME
SDL_HINT_WINRT_HANDLE_BACK_BUTTON - A variable controlling whether back-button-press events on Windows Phone to be marked as handled.

HEADER FILE
Defined in SDL3/SDL_hints.h

SYNOPSIS
#include "SDL3/SDL.h"

#define SDL_HINT_WINRT_HANDLE_BACK_BUTTON SDL_WINRT_HANDLE_BACK_BUTTON"

DESCRIPTION
Windows Phone devices typically feature a Back button. When pressed, the OS will emit back-button-press events, which apps are expected to handle in an appropriate manner. If apps do not explicitly mark these events as 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_EVENT_KEY_DOWN
 and SDL_EVENT_KEY_UP ), 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_EVENT_KEY_DOWN
 events that have a scancode of SDL_SCANCODE_AC_BACK . (Alternatively, SDL_EVENT_KEY_UP
 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

AVAILABILITY
This hint is available since SDL 3.0.0.