1# Mouse Event 2 3If a mouse action triggers multiple events, the order of these events is fixed. By default, mouse events are transmitted transparently. 4 5> **NOTE** 6> 7> - The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. 8> - For the time being, a mouse event can be triggered only by an external mouse device. 9 10## onMouse 11 12onMouse(event: (event: MouseEvent) => void) 13 14Triggered when the component is clicked by a mouse button or the mouse pointer moves on the component. 15 16**Atomic service API**: This API can be used in atomic services since API version 11. 17 18**System capability**: SystemCapability.ArkUI.ArkUI.Full 19 20**Parameters** 21 22| Name | Type | Mandatory| Description | 23| ------- | --------------------------------- | ---- | ------------------------------------------------------------ | 24| event | [MouseEvent](#mouseevent) | Yes | Timestamp, mouse button, action, coordinates of the clicked point on the entire screen, and coordinates of the clicked point relative to the component when the event is triggered.| 25 26 27## MouseEvent 28 29Inherits from [BaseEvent](ts-gesture-customize-judge.md#baseevent8). 30 31**System capability**: SystemCapability.ArkUI.ArkUI.Full 32 33| Name | Type | Description | 34| ---------------------- | ---------------------------------------- | ---------------------------- | 35| x | number | X coordinate of the mouse pointer relative to the upper left corner of the component being clicked.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 36| y | number | Y coordinate of the mouse pointer relative to the upper left corner of the component being clicked.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 37| button | [MouseButton](ts-appendix-enums.md#mousebutton8) | Mouse button.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 38| action | [MouseAction](ts-appendix-enums.md#mouseaction8) | Mouse action.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 39| stopPropagation | () => void | Stops the event from bubbling upwards or downwards.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 40| windowX<sup>10+</sup> | number | X coordinate of the mouse pointer relative to the upper left corner of the application window.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 41| windowY<sup>10+</sup> | number | Y coordinate of the mouse pointer relative to the upper left corner of the application window.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 42| displayX<sup>10+</sup> | number | X coordinate of the mouse pointer relative to the upper left corner of the application screen.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 43| displayY<sup>10+</sup> | number | Y coordinate of the mouse pointer relative to the upper left corner of the application screen.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 44| screenX<sup>(deprecated)</sup> | number | X coordinate of the mouse pointer relative to the upper left corner of the application window.<br>This API is deprecated since API version 10. You are advised to use **windowX** instead.| 45| screenY<sup>(deprecated)</sup> | number | Y coordinate of the mouse pointer relative to the upper left corner of the application window.<br>This API is deprecated since API version 10. You are advised to use **windowY** instead.| 46| rawDeltaX<sup>15+</sup> | number | X-axis offset relative to the previously reported mouse pointer position. This value may be less than the difference between the two reported X coordinates when the mouse pointer is near the screen edge.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 47| rawDeltaY<sup>15+</sup> | number | Y-axis offset relative to the previously reported mouse pointer position.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 48| pressedButtons<sup>15+</sup> | MouseButton[] | Array of all mouse buttons that are currently pressed.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 49 50## Example 51 52This example demonstrates how to set a mouse event on a button. When the button is clicked using a mouse device, the **onMouse** event is triggered to obtain relevant mouse event parameters. 53 54```ts 55// xxx.ets 56@Entry 57@Component 58struct MouseEventExample { 59 @State hoverText: string = 'no hover'; 60 @State mouseText: string = ''; 61 @State action: string = ''; 62 @State mouseBtn: string = ''; 63 @State color: Color = Color.Blue; 64 65 build() { 66 Column({ space: 20 }) { 67 Button(this.hoverText) 68 .width(180).height(80) 69 .backgroundColor(this.color) 70 .onHover((isHover: boolean, event: HoverEvent) => { 71 // Use the onHover event to dynamically change the text content and background color of a button when the mouse pointer is hovered on it. 72 if (isHover) { 73 this.hoverText = 'hover'; 74 this.color = Color.Pink; 75 } else { 76 this.hoverText = 'no hover'; 77 this.color = Color.Blue; 78 } 79 }) 80 Button('onMouse') 81 .width(180).height(80) 82 .onMouse((event: MouseEvent):void => { 83 if(event){ 84 switch (event.button) { 85 case MouseButton.None: 86 this.mouseBtn = 'None'; 87 break; 88 case MouseButton.Left: 89 this.mouseBtn = 'Left'; 90 break; 91 case MouseButton.Right: 92 this.mouseBtn = 'Right'; 93 break; 94 case MouseButton.Back: 95 this.mouseBtn = 'Back'; 96 break; 97 case MouseButton.Forward: 98 this.mouseBtn = 'Forward'; 99 break; 100 case MouseButton.Middle: 101 this.mouseBtn = 'Middle'; 102 break; 103 } 104 switch (event.action) { 105 case MouseAction.Hover: 106 this.action = 'Hover'; 107 break; 108 case MouseAction.Press: 109 this.action = 'Press'; 110 break; 111 case MouseAction.Move: 112 this.action = 'Move'; 113 break; 114 case MouseAction.Release: 115 this.action = 'Release'; 116 break; 117 } 118 this.mouseText = 'onMouse:\nButton = ' + this.mouseBtn + 119 '\nAction = ' + this.action + '\nXY=(' + event.x + ',' + event.y + ')' + 120 '\nwindowXY=(' + event.windowX + ',' + event.windowY + ')' + 121 '\ntargetDisplayId = ' + event.targetDisplayId + 122 '\nrawDeltaX = ' + event.rawDeltaX + 123 '\nrawDeltaY = ' + event.rawDeltaY + 124 '\nlength = ' + event.pressedButtons?.length; 125 } 126 }) 127 Text(this.mouseText) 128 }.padding({ top: 30 }).width('100%') 129 } 130} 131``` 132 133 134 135The figure below shows how the button looks like when clicked. 136 137 138
