DRAFT |
SDL_HINT_WINRT_HANDLE_BACK_BUTTON
A hint that specifies a variable to allow back-button-press events on Windows Phone to be marked as handled.
Values
1 |
mark the button as handled |
Default
By default this hint is not set and the application will be terminated.
Code Examples
You can add your code example here
Remarks
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 '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
Version
This hint is available since SDL 2.0.3.
