> ## 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-TW/reference/input/gameinput/enums/gameinputsystembuttons.md)\*

接收在此讀數中按下的系統按鈕集合。

### 傳回值

類型：bool

如果讀數包含系統按鈕狀態，則傳回 `true`。如果不包含，則傳回 `false`，在此情況下 *buttons* 會設定為 `GameInputSystemButtonNone`。

## 備註

在 GameInput v4 中，系統按鈕是一般的輸入類型 `GameInputKindSystemButton`。來自具有系統按鈕之裝置的每個讀數，都會在 [IGameInputReading::GetInputKind](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_getinputkind.md) 中包含 `GameInputKindSystemButton`，而 `GetSystemButtonState` 會以 [IGameInputReading::GetGamepadState](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_getgamepadstate.md) 傳回遊戲台按鈕狀態的相同方式，傳回這些按鈕的目前狀態。若要找出裝置具有哪些系統按鈕，請呼叫 [IGameInputDevice::GetSupportedSystemButtons](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getsupportedsystembuttons.md)。

讀數會回報哪些按鈕處於按下狀態，而不是按下或放開事件。若要偵測按下或放開，請將狀態與前一個讀數的狀態進行比較。

此方法取代了舊版 GameInput 中的 [IGameInput::RegisterSystemButtonCallback](https://docs.xbox.com/zh-TW/reference/input/gameinput/deprecated/interfaces/igameinput/methods/igameinput_registersystembuttoncallback.md) 方法。若要接收系統按鈕輸入，請搭配 `GameInputKindSystemButton` 使用 [IGameInput::RegisterReadingCallback](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinput/methods/igameinput_registerreadingcallback.md)，或使用 [IGameInput::GetCurrentReading](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinput/methods/igameinput_getcurrentreading.md) 進行輪詢。

只有在應用程式處於焦點時才會傳遞系統按鈕輸入，除非已使用 [IGameInput::EnableBackgroundInput](https://docs.xbox.com/zh-TW/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-TW/build/core-features/common/input/overviews/input-overview.md)\
[IGameInputReading](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputreading/igameinputreading.md)\
[GameInputSystemButtons](https://docs.xbox.com/zh-TW/reference/input/gameinput/enums/gameinputsystembuttons.md)\
[GameInputKind](https://docs.xbox.com/zh-TW/reference/input/gameinput/enums/gameinputkind.md)\
[IGameInput::EnableBackgroundInput](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinput/methods/igameinput_enablebackgroundinput.md)\
[IGameInputDevice::GetSupportedSystemButtons](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getsupportedsystembuttons.md)

## 版本歷程記錄

| 版本 | 變更 |
| - | - |
| **v4** | 已推出。 |


## Related topics

- [GameInputSystemButtons](https://docs.xbox.com/zh-TW/reference/input/gameinput/enums/gameinputsystembuttons.md)
- [IGameInputDevice::GetSupportedSystemButtons](https://docs.xbox.com/zh-TW/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getsupportedsystembuttons.md)
- [RegisterSystemButtonCallback (已淘汰)](https://docs.xbox.com/zh-TW/reference/input/gameinput/deprecated/interfaces/igameinput/methods/igameinput_registersystembuttoncallback.md)
- [GameInput API 成員](https://docs.xbox.com/zh-TW/reference/input/gameinput/gameinput_members.md)
- [已淘汰的 GameInput API 成員](https://docs.xbox.com/zh-TW/reference/input/gameinput/deprecated/gameinput_deprecated_members.md)