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

# XGameStreamingShowTouchControlLayoutOnClient

> XGameStreamingShowTouchControlLayoutOnClient

# XGameStreamingShowTouchControlLayoutOnClient

在單一用戶端上顯示要求的觸控控制項組合。

## 語法

```cpp theme={null}
void XGameStreamingShowTouchControlLayoutOnClient(  
         XGameStreamingClientId client,  
         const char* layout  
)  
```

### 參數

*client*   \_In\_\
類型：XGameStreamingClientId

要在其上顯示觸控控制項的串流用戶端裝置。

*layout*   \_In\_opt\_z\_\
類型：char\*

要顯示的觸控控制項配置名稱，或使用 nullptr 以顯示預設配置。

應在串流用戶端裝置上顯示的觸控控制項配置識別碼。配置識別碼為遊戲專屬，並對應至作為 [Touch Adaptation Kit](/zh-TW/build/core-features/common/game-streaming/game-streaming-touch-touch-adaptation-kit-overview) 的一部分提供給 XBOX Game Streaming 的配置識別碼。此字串應以 UTF-8 編碼。

如果提供 `nullptr`，將會顯示預設的觸控控制項組合。

任何不對應至該遊戲觸控控制項配置識別碼的字串，都不會變更用戶端裝置上觸控控制項的狀態，使其維持不變。在這些情況下，Content Test Application 可能會提供診斷資訊。

## 傳回值

類型：void

## 備註

此 API 會要求指定的遊戲串流用戶端在玩家的用戶端裝置上顯示特定的觸控控制項配置。如果玩家未串流遊戲，或是串流用戶端未啟用觸控，此函式不會執行任何動作。

如果玩家使用實體控制器而非觸控控制項，此函式不會強制在其裝置上顯示觸控控制項。相反地，用戶端會在玩家下次開始使用觸控控制項時，使用最後要求的配置。

您可以將此函式視為給用戶端裝置的提示，告知其在玩家使用觸控控制項時，哪一個觸控控制項配置最適合目前的遊戲狀態。接著，用戶端裝置會自行管理何時最適合將這些控制項放到玩家的螢幕上。

每次呼叫 `XGameStreamingShowTouchControlLayoutOnClient` 都會透過網路傳送一則訊息，因此不應在每個畫面都呼叫它。相反地，只在遊戲需要在不同的觸控控制項配置之間轉換時才呼叫此 API。

如果您的遊戲想要在**所有**已連線的串流用戶端裝置上顯示觸控控制項配置，請考慮改用 [XGameStreamingShowTouchControlLayout](/zh-TW/reference/system/xgamestreaming/functions/xgamestreamingshowtouchcontrollayout)。

## 範例

```C++ theme={null}
void OnGameStateChanged(GameState newState, XGameStreamingClientId client)
{
    // Toggle to the set of touch overlay controls which best match the new state of the game
    switch (newState)
    {
    case GameState::FirstPersonAction:
        XGameStreamingShowTouchControlLayoutOnClient(client, "FirstPersonAction");
        break;
    case GameState::Driving:
        XGameStreamingShowTouchControlLayoutOnClient(client, "Driving");
        break;
    case GameState::CutScene:
        // Don't show any touch overlay controls while the cut scene is rendering
        XGameStreamingHideTouchControlsOnClient(client);
        break;
    }
}
```

## 需求

**標頭：** xgamestreaming.h

**程式庫：** xgameruntime.lib

**支援的平台：** Windows、XBOX One 系列主機和 XBOX Series 主機

## 另請參閱

[XGameStreamingHideTouchControlsOnClient](/zh-TW/reference/system/xgamestreaming/functions/xgamestreaminghidetouchcontrols)\
[XGameStreamingShowTouchControlLayout](/zh-TW/reference/system/xgamestreaming/functions/xgamestreamingshowtouchcontrollayout)\
[XGameStreaming](/zh-TW/reference/system/xgamestreaming/xgamestreaming_members#TouchAdaptation)


## Related topics

- [XGameStreamingShowTouchControlLayoutOnClient](/reference/system/xgamestreaming/functions/xgamestreamingshowtouchcontrollayoutonclient.md)
- [XGameStreamingShowTouchControlLayout](/reference/system/xgamestreaming/functions/xgamestreamingshowtouchcontrollayout.md)