Supporting-and-Using-Extra-Input-Messages.md

 _How to support modern input devices and use the extra input messages in your MiniGUI apps._
+
+
+Table of Contents
+
+- [Overview](#overview)
+- [Using the Extra Input Messages](#using-the-extra-input-messages)
+- [Compile-time configuration](#compile-time-configuration)
+- [Run-time configuration](#run-time-configuration)
+- [Writing an IAL Engine to Support Extra Input Messages](#writing-an-ial-engine-to-support-extra-input-messages)
+
+## Overview
+
+In MiniGUI 4.0.0, we introduce the extra input messages to support modern
+input devices including multiple touch panel, gesture, joystick, tablet tool,
+table pad, and even switch.
+
+The extra input messages have the prefix `MSG_EXIN_`. If a MiniGUI app
+want to handle these extra input events such as gestures, you need
+to handle the `MSG_EXIN_XXX` messages in your window procedure.
+
+Currently, there are two built-in IAL engines which can generates
+the extra input messages:
+
+* The IAL engine of `libinput` to support all modern input devices on a
+Linux box. This engine runs on `libinput` introduced by Free Desktop project.
+
+* The enhanced IAL engine of `random` to generate extra input messages
+  automatically for testing.
+
+You can also write your own IAL engines to generate the extra messages.
+Please see the implementation of `libinput` and `random` engines for
+the details.
+
+This document describes how to handle the extra input messages and
+how to use `libinput` and `random` engines, or how to writing your
+own IAL engine to support a modern input devices, for example, a
+multi-touch panel.
+
+## Using the Extra Input Messages
+
+## Complie-time Configuration
+
+## Run-time Configuration
+
+For `libinput` engine, we introduce a new section in MiniGUI runtime
+configuration:
+
+```
+[libinput]
+seat=seat0
+```
+
+The key `libinput.seat` specifies the seat identifier, the default
+is `seat0`.
+
+For `random` engine, we introduce a new section in MiniGUI runtime
+configuration:
+
+```
+[random]
+logfile=events.out
+eventtypes=mouse-keyboard-button-gesture-stouch
+minkeycode=1
+maxkeycode=128
+minbtncode=0x100
+maxbtncode=0x1ff
+```
+
+The MiniGUI runtime configuration key `random.logfile` specifies
+the log file which will store the input events generated by this engine.
+If MiniGUI failed to open the log file, the log feature will be disabled.
+
+The MiniGUI runtime configuration key `random.eventtypes` specifies
+the input event types which will be generated by this IAL engine,
+in the following pattern:
+
+    <event-type>[-<event-type>]*
+
+The `<event-type>` can be one of the following values:
+
+ - `mouse`: mouse.
+ - `keyboard`: keyboard.
+ - `button`: buttons.
+ - `single_touch`: touch pen or single touch panel.
+ - `multi_touch`: multiple touch panel.
+ - `gesture`: gesture.
+ - `tablet_tool`: tablet tool.
+ - `tablet_pad`: tablet pad.
+ - `switch`: switch.
+
+The MiniGUI ETC key `random.minkeycode` specifies the minimal key code
+which can be generated by the engine if `keyboard` is included.
+
+The MiniGUI ETC key `random.maxkeycode` specifies the maximal key code
+which can be generated by the engine if `keyboard` is included.
+
+The MiniGUI ETC key `random.minbtncode` specifies the minimal button code
+which can be generated by the engine if `button` is included.
+
+The MiniGUI ETC key `random.maxbtncode` specifies the maximal key code
+which can be generated by the engine if `button` is included.
+
+For invalid `random.eventtyps`, the engine uses `mouse` as default.
+
+For invalid `random.minkeycode`, and/or `random.maxkeycode` key values,
+the engine uses `SCANCODE_ESCAPE`, and `SCANCODE_MICMUTE` respectively.
+
+For invalid `random.minbtncode`, and/or `random.maxbtncode` key values, use
+`0x100` (`BTN_MISC` defined by Linux kernel), and `0x2ff` (`KEY_MAX` defined by
+Linux kernel) respectively.
+
+This engine maintains a state machine for each input event type, and
+generates a reasonable event sequence for each type. If and only if
+an event sequence finished or cancelled, the engine switch to another
+event type randomly.
+
+Note that currently, the following event types (in `random` engine)
+are not implemented:
+
+ - `multi_touch`
+ - `tablet_tool`
+ - `tablet_pad`
+ - `switch`
+
+## Writing an IAL Engine to Support Extra Input Messages
+