vystem/docs/blastproof/kbdlayout.md

Keyboard layouts

Introduction

Blastproof supports the addition of custom keyboards layout. This file describe how they are structured and how to create one.

Implementation

The layout.h header, located in Blastproof/src/libs/include, contain the utilities needed to create custom keyboards layout. Two main structures are needed:

typedef struct {
  CHAR16 char_source;
  CHAR16 char_dest;
} bp_layout_CHAR_CONV;

The char_source field must be the character that Blastproof will receive from the UEFI firmware. In the immense majority of case, the firmware interprets each pressed key using the QWERTY layout. The char_dest field must be the character that replaced the inputed character.

typedef struct {
  UINTN conv_count;
  bp_layout_CHAR_CONV conv_table[];
} bp_layout_CONV_TABLE;

This structure is defined at compilation time and should indicate the amount of characters conversions as well as all the characters conversions, stored in an array.

Usage

In the immense majority of cases, the firmware uses the QWERTY layout. If this is the case, you should use the keyboard layout of your keyboard. Here are the supported keyboard layout for the moment:

• QWERTY
• AZERTY

In the case where the firmware already use the keyboard layout of your keyboard, please select the QWERTY layout : it doesn't contain any key translation.

Creating your own layout

In order to create your own keyboard layout, you can follow these steps:

Creating the header file

1. Create a header file named <keyboard layout name>.h inside the Blastproof/src/libs/include/layouts folder.

2. Paste it the following template:

// SPDX-License-Identifier: MPL-2.0
#ifndef BP_LIB_LAYOUT_LAYOUTNAME_H
#define BP_LIB_LAYOUT_LAYOUTNAME_H
#include "../layout.h"
bp_layout_CONV_TABLE layoutname_convs={
  .conv_count=0,
  .conv_table={
  }
};
#endif

3. Replace every layoutname and LAYOUTNAME with the name of your layout.

4. Add as many character conversions as you want. A character conversion is set under the form {L'a',L'q'}. In this example, we translate the character a to q.

5. Don't forget to update the conv_count field with the amount of characters conversions.

Registering the layout

Go inside the layout_registry.h file, located inside Blastproof/src/libs/include/layouts and add the following line where indicated:

• #include "<keyboard layout name>.h" : replace <keyboard layout name> with the name of your layout
• add the string that will be displayed (generally the layout name) to the user inside layout_list. Don't forger the L string modifier before the first quote
• &<keyboard layout name>_conv : add this element inside the layout_conversions_table variable. Don't forget the & operator