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.