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

@@ -192,3 +192,82 @@ are not implemented:
 
 ## Writing an IAL Engine to Support Extra Input Messages
 
+On Linux, it is better to use `libinput` to support all input devices including
+multi-touch panel and table tool. However, for an embedded or IoT device,
+it may be too heavy to use `libinput` or there is no way to run `libinput` (e.g.,
+when you run MiniGUI on a real-time operating system).
+
+For this situation, you need to implement your own IAL engine to support
+the extra input messages. The steps are as follow:
+
+1. Use `--enable-customial` option to configure MiniGUI to include
+   `custom` IAL engine.
+1. Implement the following external stubs outside MiniGUI to initialize
+   and terminate your `custom` IAL engine:
+
+```
+BOOL InitCustomInput (INPUT* input, const char* mdev, const char* mtype);
+void TermCustomInput (void);
+```
+1. Change MiniGUI run-time configuration to specify the key `system.ial_engine`
+as `custom`.
+
+In `InitCustomInput` function, you should fill the operators (the callbacks)
+of `input` argument, the pointer to a INPUT structure:
+
+```
+typedef struct tagINPUT {
+    char*   id;
+
+    // Initialization and termination
+    BOOL (*init_input) (struct tagINPUT *input, const char* mdev, const char* mtype);
+    void (*term_input) (void);
+
+    // Mouse operations
+    int  (*update_mouse) (void);
+    void (*get_mouse_xy) (int* x, int* y);
+    void (*set_mouse_xy) (int x, int y);
+    int  (*get_mouse_button) (void);
+    void (*set_mouse_range) (int minx, int miny, int maxx, int maxy);
+    void (*suspend_mouse) (void);
+    int (*resume_mouse) (void);
+
+    // Keyboard operations
+    int  (*update_keyboard) (void);
+    const char* (*get_keyboard_state) (void);
+    void (*suspend_keyboard) (void);
+    int (*resume_keyboard) (void);
+    void (*set_leds) (unsigned int leds);
+
+    // Event loop
+    int (*wait_event) (int which, int maxfd, fd_set *in, fd_set *out,
+            fd_set *except, struct timeval *timeout);
+
+    // New wait event method for getting extra input events; since 4.0.0
+    int (*wait_event_ex) (int maxfd, fd_set *in, fd_set *out,
+            fd_set *except, struct timeval *timeout, EXTRA_INPUT_EVENT* extra);
+} INPUT;
+```
+
+The key to support extra input messages is the new operator: `wait_event_ex`.
+If you implement `wait_event_ex`, you can set `wait_event` to be NULL.
+
+In the implementation of `wait_event_ex`, when there is an extra input message,
+you should:
+
+1. Fill the fields of `extra` structure, e.g.:
+
+    extra->event = IAL_EVENT_AXIS;
+    extra->wparam = MAKELONG(AXIS_SCROLL_VERTICAL, AXIS_SOURCE_WHEEL);
+    extra->wparam = MAKELONG(AXIS_SCROLL_HORIZONTAL, AXIS_SOURCE_WHEEL);
+    extra->lparam = MAKELONG(mouse_event->sv, mouse_event->dsv);
+
+1. Make sure the return value of this operator have the bit of `IAL_EVENT_EXTRA` set:
+
+    retval |= IAL_EVENT_EXTRA;
+
+For more information, please refer to the `libinput` and/or `random` IAL engines:
+
+<https://github.com/VincentWei/minigui/blob/master/src/ial/linux-libinput.c>
+<https://github.com/VincentWei/minigui/blob/master/src/ial/random.c>
+