> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# IGameInputReading::GetSystemButtonState

> 从输入读数中检索系统按钮（例如 Guide 按钮和 Share 按钮）的状态。

从输入读数中检索系统按钮（例如 Guide 按钮和 Share 按钮）的状态。

## 语法

```cpp theme={null}
bool GetSystemButtonState(
    GameInputSystemButtons* buttons
);
```

### 参数

*buttons*   \_Out\_\
类型：[GameInputSystemButtons](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputsystembuttons.md)\*

接收在此读数中处于按下状态的系统按钮集合。

### 返回值

类型：bool

如果读数包含系统按钮状态，则返回 `true`。如果不包含，则返回 `false`，在这种情况下，*buttons* 设置为 `GameInputSystemButtonNone`。

## 备注

在 GameInput v4 中，系统按钮是一种普通的输入类型，即 `GameInputKindSystemButton`。来自具有系统按钮的设备的每个读数都会在 [IGameInputReading::GetInputKind](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_getinputkind.md) 中包含 `GameInputKindSystemButton`，并且 `GetSystemButtonState` 返回这些按钮当前状态的方式，与 [IGameInputReading::GetGamepadState](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_getgamepadstate.md) 返回游戏手柄按钮状态的方式相同。若要了解设备具有哪些系统按钮，请调用 [IGameInputDevice::GetSupportedSystemButtons](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getsupportedsystembuttons.md)。

读数报告的是哪些按钮处于按下状态，而不是按下或释放事件。若要检测按下或释放，请将该状态与上一个读数的状态进行比较。

此方法取代了早期 GameInput 版本中的 [IGameInput::RegisterSystemButtonCallback](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/interfaces/igameinput/methods/igameinput_registersystembuttoncallback.md) 方法。若要接收系统按钮输入，请将 [IGameInput::RegisterReadingCallback](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinput/methods/igameinput_registerreadingcallback.md) 与 `GameInputKindSystemButton` 一起使用，或者使用 [IGameInput::GetCurrentReading](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinput/methods/igameinput_getcurrentreading.md) 进行轮询。

只有在应用程序具有焦点时才会传送系统按钮输入，除非已使用 [IGameInput::EnableBackgroundInput](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinput/methods/igameinput_enablebackgroundinput.md) 启用后台输入。

以下示例演示如何检测 Guide 按钮的新按下操作。

```cpp theme={null}
Microsoft::WRL::ComPtr<IGameInput> gameInput;
GameInputSystemButtons previousButtons = GameInputSystemButtonNone;

void PollGuideButton() noexcept
{
    Microsoft::WRL::ComPtr<IGameInputReading> reading;
    if (SUCCEEDED(gameInput->GetCurrentReading(GameInputKindSystemButton, nullptr, &reading)))
    {
        GameInputSystemButtons buttons = GameInputSystemButtonNone;
        if (reading->GetSystemButtonState(&buttons))
        {
            const bool guidePressed = (buttons & GameInputSystemButtonGuide) != 0;
            const bool guidePreviouslyPressed = (previousButtons & GameInputSystemButtonGuide) != 0;
            if (guidePressed && !guidePreviouslyPressed)
            {
                // Handle new Guide button press
            }

            previousButtons = buttons;
        }
    }
}
```

## 要求

**头文件：** GameInput.h

**库：** gameinput.lib

**支持的平台：** Windows、XBOX One 系列主机和 XBOX Series 主机

## 另请参阅

[GameInput 概述](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-overview.md)\
[IGameInputReading](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputreading/igameinputreading.md)\
[GameInputSystemButtons](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputsystembuttons.md)\
[GameInputKind](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputkind.md)\
[IGameInput::EnableBackgroundInput](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinput/methods/igameinput_enablebackgroundinput.md)\
[IGameInputDevice::GetSupportedSystemButtons](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getsupportedsystembuttons.md)

## 版本历史

| 版本 | 变更 |
| - | - |
| **v4** | 引入。 |


## Related topics

- [GameInputSystemButtons](https://docs.xbox.com/zh-CN/reference/input/gameinput/enums/gameinputsystembuttons.md)
- [IGameInputDevice::GetSupportedSystemButtons](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getsupportedsystembuttons.md)
- [RegisterSystemButtonCallback（已弃用）](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/interfaces/igameinput/methods/igameinput_registersystembuttoncallback.md)
- [GameInput API 成员](https://docs.xbox.com/zh-CN/reference/input/gameinput/gameinput_members.md)
- [已弃用的 GameInput API 成员](https://docs.xbox.com/zh-CN/reference/input/gameinput/deprecated/gameinput_deprecated_members.md)