Vystem 0.2

docs/blastproof/kbdlayout.md

@@ -0,0 +1,71 @@
+# 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:
+
+``` C
+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.
+
+``` C
+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:
+
+``` C
+// 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