Keyboard and mouse event

Mouse and Key Events in ArkUI

Mouse Events

Supported mouse events include those triggered by an external mouse or touchpad.

Mouse Event Callbacks

Name	Description
onHover(event: (isHover: boolean) => void)	Triggered when the mouse enters or exits a component. isHover: Indicates whether the mouse is hovering over the component, true when entering, false when exiting.
onMouse(event: (event?: MouseEvent) => void)	Triggered when the component is clicked by a mouse button or when the mouse hovers and moves over the component. The event return value includes the timestamp, mouse button, action, screen coordinates, and component-relative coordinates at the time of the event.

When a component binds the onHover callback, you can set the hover effect of the component using the hoverEffect property.

Mouse Event Data Flow

After mouse events are passed to ArkUI, they are first checked to see if they are left-click down/up/move events. Different responses are made accordingly:

• Yes: The mouse event is first converted into a touch event at the same position, and the touch event's collision test, gesture judgment, and callback response are executed. Then, the mouse event's collision test and callback response are executed.
• No: The event is only used to perform the mouse event's collision test and callback response.

Notes

• All single-finger touch events/gesture events can be operated and responded to using the mouse left button. For example, to develop a function that jumps to a page when clicking a Button and supports both finger clicks and mouse left-button clicks, binding a single click event (onClick) is sufficient. If you need to implement different effects for finger and mouse left-button clicks, you can use the source field in the callback parameters to determine whether the event source is a finger or a mouse.
• The onHover callback is triggered when the mouse pointer enters or leaves the component. This event does not support custom bubble settings and defaults to parent-child bubbling.

Example: Using onHover

@Entry
@Component
struct MouseExample {
  @State hoverText: string = 'Not Hover';
  @State Color: Color = Color.Gray;

  build() {
    Column() {
      Button(this.hoverText)
        .width(200).height(100)
        .backgroundColor(this.Color)
        .onHover((isHover?: boolean) => { // Use onHover to listen for mouse hover on the Button component
          if (isHover) {
            this.hoverText = 'Hovered!';
            this.Color = Color.Green;
          }
          else {
            this.hoverText = 'Not Hover';
            this.Color = Color.Gray;
          }
        })
    }.width('100%').height('100%').justifyContent(FlexAlign.Center)
  }
}

Explanation

• Button Component: The button's onHover event changes the button's text and background color when the mouse hovers over or leaves the button.
• State Variables: hoverText and Color store the current hover state and button color.

Key Events

Example: Using onKeyEvent

@Entry
@Component
struct KeyEventExample {
  @State buttonText: string = '';
  @State buttonType: string = '';
  @State columnText: string = '';
  @State columnType: string = '';


  build() {
    Column() {
      Button('onKeyEvent')
        .defaultFocus(true)
        .width(140).height(70)
        .onKeyEvent((event?: KeyEvent) => { // Set onKeyEvent for Button
          if(event){
            if (event.type === KeyType.Down) {
              this.buttonType = 'Down';
            }
            if (event.type === KeyType.Up) {
              this.buttonType = 'Up';
            }
            this.buttonText = 'Button: \n' +
            'KeyType:' + this.buttonType + '\n' +
            'KeyCode:' + event.keyCode + '\n' +
            'KeyText:' + event.keyText;
          }
        })


      Divider()
      Text(this.buttonText).fontColor(Color.Green)


      Divider()
      Text(this.columnText).fontColor(Color.Red)
    }.width('100%').height('100%').justifyContent(FlexAlign.Center)
    .onKeyEvent((event?: KeyEvent) => { // Set onKeyEvent for the parent Column component
      if(event){
        if (event.type === KeyType.Down) {
          this.columnType = 'Down';
        }
        if (event.type === KeyType.Up) {
          this.columnType = 'Up';
        }
        this.columnText = 'Column: \n' +
        'KeyType:' + this.buttonType + '\n' +
        'KeyCode:' + event.keyCode + '\n' +
        'KeyText:' + event.keyText;
      }
    })
  }
}