Skip to content

Latest commit

 

History

History
121 lines (79 loc) · 5.76 KB

Custom_Virtual_Key_Integration_Guide.md

File metadata and controls

121 lines (79 loc) · 5.76 KB

Custom Virtual Key

The custom virtual key is an SDK component enabling you to add virtual keys to your application. After integrating the Real-Time Cloud Rendering SDK, you can integrate the custom virtual key SDK into your project so as to add appropriate key features to your application.

The custom virtual key SDK provides easy-to-use editing features. After integrating the SDK, you can dynamically generate custom virtual keys. Editing features include adding a key (such as mouse or controller button) and adjusting the key position and size.

Feature Overview

Supported keys

Three types of keys are supported: mouse and arrow keys, keyboard, and controller.

Mouse and arrow keys

  1. Mouse buttons: Left button, middle button, right button, scroll-up, and scroll-down

  2. Arrow keys: Up, down, left and right/W, A, S, and D Four common keys W, A, S, and D form arrow keys just like a D-pad on a controller. If the up direction is pressed, a message of the W key will be triggered. If a diagonal direction is pressed, its two adjacent keys will be triggered. Messages of the up, down, left, and right arrow keys are triggered in the same way.

General keyboard keys

  1. 78 commonly used keys on a physical keyboard

Controller

  1. Left and right sticks

  2. D-pad

  3. General pressable buttons: A, B, X, Y, △, ☐, ×, ○, Select, Start, LB, RB, L3, and R3

  4. Triggers: LT and RT (If a trigger is pressed, its message will be sent multiple times in a row instantly, and the message strength decreases gradually over time.)

Supported editing features

  • Dynamically adding/deleting a key.
  • Dynamically adjusting the position and size of a key.
  • Positioning a key by using auxiliary lines.
  • Renaming a pressable key (the name can contain up to six characters).

Note: Resources such as spliced UI images cannot be set dynamically.

API overview

GamepadManager

API Description
setEditListener Sets the listener for virtual key editing events.
setGamePadTouchDelegate Sets the delegate of touch events.
showGamepad Displays the virtual controller.
editGamepad Edits the virtual controller.
needConnected Determines whether the key is a controller button.

Integrating the custom virtual key SDK

  1. The custom virtual key component depends on the Real-Time Cloud Rendering SDK. Therefore, integrate the Real-Time Cloud Rendering SDK into your application first.

  2. Integrate the SDK. Add the following content to the build.gradle file of your application module:

dependencies {
	 ......
    implementation 'com.tencent.tcr:tcr-gamepad:2.2.1'
}
  1. Initialize the virtual key view and read the configuration file during initialization.
mGamePadManager = new GamepadManager(this,Tcrsession);
mCustomGamePadCfg = readConfigFile("lol_5v5.cfg");  // You can implement the reading method on your own.
  1. Initialize virtual keys.
mKeyboardView = new KeyboardView(this,Tcrsession);
  1. Add the custom editing listener.
mGamePadManager.setEditListener((isChanged, newCfg) -> {
            if (isChanged){
                mCustomGamePadCfg = newCfg;
            }
            mGamePadManager.showGamepad(mCustomGamePadCfg); // Update the key view after editing.
        });
  1. Open the virtual key view.
mGamePadManager.showGamepad(mCustomGamePadCfg); // Open the virtual key view.
  1. Open and close the editing view.
mGamePadManager.editGamepad(mCustomGamePadCfg); // Open the custom editing view.

Above are the core steps of integration. For the specific code, see Demo.

Configuration file generation

Generating a layout configuration file

A layout configuration file is a JSON configuration file. The SDK can load it to generate a layout of virtual keys. The demo project provides two common layout configuration files, which can be viewed in the asserts directory of the project. In addition, you can use the following configuration file generation tool to generate virtual key layouts suitable for various applications and save the configuration files for your applications to load and call them.

Configuration file generation tool

A custom virtual key configuration tool is provided to generate key layout configuration files for the SDK. In addition, you can save jsonCfg, which is the edited configuration file content, in the OnEditListener.onFinishEdit(boolean isChanged, String jsonCfg) callback to your local storage in your code.

Note: You only need to save and import the generated configuration file for your application to use it with no need of caring about the content and generation rules in the file.

FAQs

  1. Which is the earliest Android version supported by the virtual key SDK?
    Android 5.0 (API level 21).