1# Event Listening Development (C/C++)
2
3## Introduction
4
5The multimodal module provides applications with the ability to listen for key and input events (mouse, touch, and axis events). Currently, event listening is available only for screen recording applications. For example, when a user starts screen recording, your application can listen for key, mouse, touch, and axis events of the device.
6
7## Available APIs
8
9The following table lists the APIs for event listening. For details, see [Input](../../reference/apis-input-kit/input.md).
10
11| API | Description|
12| ------------------------------------------------------------ | -------------------------- |
13| Input_Result OH_Input_AddKeyEventMonitor(Input_KeyEventCallback callback) |Creates a key event listener. |
14| Input_Result OH_Input_AddMouseEventMonitor(Input_MouseEventCallback callback) |Creates a mouse event listener. |
15| Input_Result OH_Input_AddTouchEventMonitor(Input_TouchEventCallback callback) |Creates a touch event listener. |
16| Input_Result OH_Input_AddAxisEventMonitorForAll(Input_AxisEventCallback callback) |Creates a listener for all axis events. |
17| Input_Result OH_Input_AddAxisEventMonitor(InputEvent_AxisEventType axisEventType, Input_AxisEventCallback callback) |Creates a listener for the specified type of axis events. |
18| Input_Result OH_Input_RemoveKeyEventMonitor(Input_KeyEventCallback callback) |Removes a key event listener. |
19| Input_Result OH_Input_RemoveMouseEventMonitor(Input_MouseEventCallback callback) |Removes a mouse event listener. |
20| Input_Result OH_Input_RemoveTouchEventMonitor(Input_TouchEventCallback callback) |Removes a touch event listener. |
21| Input_Result OH_Input_RemoveAxisEventMonitorForAll(Input_AxisEventCallback callback) |Removes a listener for all axis events. |
22| Input_Result OH_Input_RemoveAxisEventMonitor(InputEvent_AxisEventType axisEventType, Input_AxisEventCallback callback) |Removes a listener for the specified type of axis events. |
23
24## How to Develop
25
26### Linking a Dynamic Library
27
28Before calling interception-related APIs, you need to link the related dynamic library. You can do this by editing the **CMakeList.txt** file as follows:
29
30```txt
31   target_link_libraries(entry PUBLIC libohinput.so)
32```
33
34### Applying for Required Permissions
35
36Declare the required permission in the **module.json5** file. For details, see [Declaring Permissions in the Configuration File](../../security/AccessToken/declare-permissions.md).
37
38```json
39"requestPermissions": [
40    {
41        "name": "ohos.permission.INTERCEPT_INPUT_EVENT"
42    }
43]
44```
45
46### Creating an Event Listener
47
48#### Key Events
49
50```c++
51#include "multimodalinput/oh_input_manager.h"
52
53struct KeyEvent {
54    int32_t action;
55    int32_t keyCode;
56    int64_t actionTime { -1 };
57};
58
59// Define the key event callback function.
60void OnKeyEventCallback(const Input_KeyEvent* keyEvent)
61{
62    KeyEvent event;
63    // The lifecycle of Input_KeyEvent is limited to the callback function. Input_KeyEvent will be destroyed if it is called outside of the callback function.
64    event.action = OH_Input_GetKeyEventAction(keyEvent);
65    event.keyCode = OH_Input_GetKeyEventKeyCode(keyEvent);
66    event.actionTime = OH_Input_GetKeyEventActionTime(keyEvent);
67}
68
69void TestMonitor()
70{
71    // Add a key event listener.
72    Input_Result ret = OH_Input_AddKeyEventMonitor(OnKeyEventCallback);
73    // Remove the key event listener.
74    ret = OH_Input_RemoveKeyEventMonitor(OnKeyEventCallback);
75}
76```
77
78#### Mouse Events
79
80```c++
81#include "multimodalinput/oh_input_manager.h"
82
83struct MouseEvent {
84    int32_t action;
85    int32_t displayX;
86    int32_t displayY;
87    int32_t button { -1 };
88    int32_t axisType { -1 };
89    float axisValue { 0.0f };
90    int64_t actionTime { -1 };
91};
92
93// Define the mouse event callback function.
94void OnMouseEventCallback(const Input_MouseEvent* mouseEvent)
95{
96    MouseEvent event;
97    // The lifecycle of Input_MouseEvent is limited to the callback function. Input_MouseEvent will be destroyed if it is called outside of the callback function.
98    event.action = OH_Input_GetMouseEventAction(mouseEvent);
99    event.displayX = OH_Input_GetMouseEventDisplayX(mouseEvent);
100    event.displayY = OH_Input_GetMouseEventDisplayY(mouseEvent);
101    event.button = OH_Input_GetMouseEventButton(mouseEvent);
102    event.axisType = OH_Input_GetMouseEventAxisType(mouseEvent);
103    event.axisValue = OH_Input_GetMouseEventAxisValue(mouseEvent);
104    event.actionTime = OH_Input_GetMouseEventActionTime(mouseEvent);
105}
106
107void TestMonitor()
108{
109    // Add a mouse event listener.
110    Input_Result ret = OH_Input_AddMouseEventMonitor(OnMouseEventCallback);
111    // Remove the mouse event listener.
112    ret = OH_Input_RemoveMouseEventMonitor(OnMouseEventCallback);
113}
114```
115
116#### Touch Events
117
118```c++
119#include "multimodalinput/oh_input_manager.h"
120
121struct TouchEvent {
122    int32_t action;
123    int32_t id;
124    int32_t displayX;
125    int32_t displayY;
126    int64_t actionTime { -1 };
127};
128
129// Define the touch event callback function.
130void OnTouchEventCallback(const Input_TouchEvent* touchEvent)
131{
132    TouchEvent event;
133    // The lifecycle of Input_TouchEvent is limited to the callback function. Input_TouchEvent will be destroyed if it is called outside of the callback function.
134    event.action = OH_Input_GetTouchEventAction(touchEvent);
135    event.id = OH_Input_GetTouchEventFingerId(touchEvent);
136    event.displayX = OH_Input_GetTouchEventDisplayX(touchEvent);
137    event.displayY = OH_Input_GetTouchEventDisplayY(touchEvent);
138    event.actionTime = OH_Input_GetTouchEventActionTime(touchEvent);
139}
140
141void TestMonitor()
142{
143    // Add a touch event listener.
144    Input_Result ret = OH_Input_AddTouchEventMonitor(OnTouchEventCallback);
145    // Remove the touch event listener.
146    ret = OH_Input_RemoveTouchEventMonitor(OnTouchEventCallback);
147}
148```
149
150#### Axis Events
151
152```c++
153#include "multimodalinput/oh_input_manager.h"
154#include <map>
155
156struct AxisEvent {
157    int32_t axisAction;
158    float displayX;
159    float displayY;
160    std::map<int32_t, double> axisValues;
161    int64_t actionTime { -1 };
162    int32_t sourceType;
163    int32_t axisEventType { -1 };
164};
165
166// Define the callback function for all axis events.
167void OnAllAxisEventCallback(const Input_AxisEvent* axisEvent)
168{
169    AxisEvent event;
170
171    // The lifecycle of Input_AxisEvent is limited to the callback function. Input_AxisEvent will be destroyed if it is called outside of the callback function.
172    InputEvent_AxisAction action;
173    Input_Result ret = OH_Input_GetAxisEventAction(axisEvent, &action);
174    event.axisAction = action;
175    ret = OH_Input_GetAxisEventDisplayX(axisEvent, &event.displayX);
176    ret = OH_Input_GetAxisEventDisplayY(axisEvent, &event.displayY);
177    ret = OH_Input_GetAxisEventActionTime(axisEvent, &event.actionTime);
178    InputEvent_SourceType sourceType;
179    ret = OH_Input_GetAxisEventSourceType(axisEvent, &sourceType);
180    event.sourceType = sourceType;
181    InputEvent_AxisEventType axisEventType;
182    ret = OH_Input_GetAxisEventType(axisEvent, &axisEventType);
183    event.axisEventType = axisEventType;
184    if (event.axisEventType == AXIS_EVENT_TYPE_PINCH) {
185        double value = 0;
186        ret = OH_Input_GetAxisEventAxisValue(axisEvent, AXIS_TYPE_PINCH, &value);
187        event.axisValues.insert(std::make_pair(AXIS_TYPE_PINCH, value));
188        ret = OH_Input_GetAxisEventAxisValue(axisEvent, AXIS_TYPE_ROTATE, &value);
189        event.axisValues.insert(std::make_pair(AXIS_TYPE_ROTATE, value));
190    } else if (event.axisEventType == AXIS_EVENT_TYPE_SCROLL) {
191        double value = 0;
192        ret = OH_Input_GetAxisEventAxisValue(axisEvent, AXIS_TYPE_SCROLL_VERTICAL, &value);
193        event.axisValues.insert(std::make_pair(AXIS_TYPE_SCROLL_VERTICAL, value));
194        ret = OH_Input_GetAxisEventAxisValue(axisEvent, AXIS_TYPE_SCROLL_HORIZONTAL, &value);
195        event.axisValues.insert(std::make_pair(AXIS_TYPE_SCROLL_HORIZONTAL, value));
196    }
197}
198
199// Define the callback function for pinch-type axis events.
200void OnPinchAxisEventCallback(const Input_AxisEvent* axisEvent)
201{
202    AxisEvent event;
203
204    // The lifecycle of Input_AxisEvent is limited to the callback function. Input_AxisEvent will be destroyed if it is called outside of the callback function.
205    InputEvent_AxisAction action;
206    Input_Result ret = OH_Input_GetAxisEventAction(axisEvent, &action);
207    event.axisAction = action;
208    ret = OH_Input_GetAxisEventDisplayX(axisEvent, &event.displayX);
209    ret = OH_Input_GetAxisEventDisplayY(axisEvent, &event.displayY);
210    ret = OH_Input_GetAxisEventActionTime(axisEvent, &event.actionTime);
211    InputEvent_SourceType sourceType;
212    ret = OH_Input_GetAxisEventSourceType(axisEvent, &sourceType);
213    event.sourceType = sourceType;
214    InputEvent_AxisEventType axisEventType;
215    ret = OH_Input_GetAxisEventType(axisEvent, &axisEventType);
216    event.axisEventType = axisEventType;
217    double value = 0;
218    ret = OH_Input_GetAxisEventAxisValue(axisEvent, AXIS_TYPE_PINCH, &value);
219    event.axisValues.insert(std::make_pair(AXIS_TYPE_PINCH, value));
220    ret = OH_Input_GetAxisEventAxisValue(axisEvent, AXIS_TYPE_ROTATE, &value);
221    event.axisValues.insert(std::make_pair(AXIS_TYPE_ROTATE, value));
222}
223
224// Define the callback function for scroll wheel-type axis events.
225void OnScrollAxisEventCallback(const Input_AxisEvent* axisEvent)
226{
227    AxisEvent event;
228
229    // The lifecycle of Input_AxisEvent is limited to the callback function. Input_AxisEvent will be destroyed if it is called outside of the callback function.
230    InputEvent_AxisAction action;
231    Input_Result ret = OH_Input_GetAxisEventAction(axisEvent, &action);
232    event.axisAction = action;
233    ret = OH_Input_GetAxisEventDisplayX(axisEvent, &event.displayX);
234    ret = OH_Input_GetAxisEventDisplayY(axisEvent, &event.displayY);
235    ret = OH_Input_GetAxisEventActionTime(axisEvent, &event.actionTime);
236    InputEvent_SourceType sourceType;
237    ret = OH_Input_GetAxisEventSourceType(axisEvent, &sourceType);
238    event.sourceType = sourceType;
239    InputEvent_AxisEventType axisEventType;
240    ret = OH_Input_GetAxisEventType(axisEvent, &axisEventType);
241    event.axisEventType = axisEventType;
242    double value = 0;
243    ret = OH_Input_GetAxisEventAxisValue(axisEvent, AXIS_TYPE_SCROLL_VERTICAL, &value);
244    event.axisValues.insert(std::make_pair(AXIS_TYPE_SCROLL_VERTICAL, value));
245    ret = OH_Input_GetAxisEventAxisValue(axisEvent, AXIS_TYPE_SCROLL_HORIZONTAL, &value);
246    event.axisValues.insert(std::make_pair(AXIS_TYPE_SCROLL_HORIZONTAL, value));
247}
248
249void TestMonitor()
250{
251    // Add a listener for all axis events.
252    Input_Result ret = OH_Input_AddAxisEventMonitorForAll(OnAllAxisEventCallback);
253    // Remove the listener for all axis events.
254    ret = OH_Input_RemoveAxisEventMonitorForAll(OnAllAxisEventCallback);
255
256    // Add a listener for pinch-type axis events.
257    ret = OH_Input_AddAxisEventMonitor(AXIS_EVENT_TYPE_PINCH, OnPinchAxisEventCallback);
258    // Remove the listener for pinch-type axis events.
259    ret = OH_Input_RemoveAxisEventMonitor(AXIS_EVENT_TYPE_PINCH, OnPinchAxisEventCallback);
260
261    // Add a listener for scroll wheel-type axis events.
262    ret = OH_Input_AddAxisEventMonitor(AXIS_EVENT_TYPE_SCROLL, OnScrollAxisEventCallback);
263    // Remove the listener for scroll wheel-type axis events.
264    ret = OH_Input_RemoveAxisEventMonitor(AXIS_EVENT_TYPE_SCROLL, OnScrollAxisEventCallback);
265}
266```
267