IGameInput::RegisterSystemButtonCallback

Article
03/05/2024

Registers a callback function that is called when the Guide or Share button is pressed or released.

Syntax

HRESULT RegisterSystemButtonCallback(  
         IGameInputDevice* device,
         GameInputSystemButtons buttonFilter,
         void* context,
         GameInputSystemButtonCallback callbackFunc,  
         GameInputCallbackToken* callbackToken  
)

Parameters

device _In_opt_
Type: IGameInputDevice*

Optionally limits registered callback to trigger a specific device.

buttonFilter In The set of buttons to receive callbacks for, logical ORed together. context _In_opt_
Type: void*

An object that provides relevant information for the callback function. Typically, it is the calling object.

callbackFunc _In_
Type: GameInputSystemButtonCallback

Title-defined callback function that is called when the system buttons are pressed or released.

callbackToken _Out_opt_
Type: GameInputCallbackToken*

Token identifying the registered callback function. This token is used to identify the registered function if you need to cancel or unregister the callback function.

Return value

Type: HRESULT

Returns S_OK on success.

Remarks

This method registers a callback function call when the Guide or System button is pressed or released. Whether callbacks are dispensed depends on the GameInputFocusPolicy set by IGameInput::SetFocusPolicy in your process and other processes. See GameInputFocusPolicy for details. On the Xbox, the shell always consumes the guide button, so these callbacks are never dispatched on Xbox.

To stop receiving callbacks, see the IGameInput::UnregisterCallback and IGameInput::StopCallback methods.

This was added in the Windows SDK 10.0.26031 preview GameInput.h and will be added to a future release of the GDK.

The following code example demonstrates how to listen for presses of the Guide button.

Microsoft::WRL::ComPtr<IGameInput> gameInput; 
 
void CALLBACK OnGuideButton( 
    _In_ GameInputCallbackToken callbackToken, 
    _In_ void * context,
    _In_ IGameInputDevice * device,
    _In_ uint64_t timestamp,
    _In_ GameInputSystemButtons currentButtons,
    _In_ GameInputSystemButtons previousButtons) 
{
    bool guidePressed = currentButtons & GameInputSystemButtons::GameInputSystemButtonGuide;
    bool guidePreviouslyPressed = previousButtons & GameInputSystemButtons::GameInputSystemButtonGuide;
    if (guidePressed && !guidePreviouslyPressed)
    {
        // Handle new Guide button press
    }
    else if (!guidePressed && guidePreviouslyPressed)
    {    
        // Handle new Guide button release
    }
} 
 
void RegisterForGuideButton() noexcept 
{ 
    GameInputCallbackToken token; 
    if (SUCCEEDED(gameInput->RegisterSystemButtonCallback( 
        nullptr, // All devices 
        GameInputSystemButtons::GameInputSystemButtonGuide, // Filter to the Guide button
        nullptr, // No context
        OnGuideButton, // Callback
        &token))) // token
    { 
        // Success!
    } 
}

Requirements

Header: GameInput.h

Library: gameinput.lib

Supported platforms: Windows, Xbox One family consoles and Xbox Series consoles

Share via