目录

@ohos.multimodalInput.pointer (Mouse Pointer)

The mouse cursor management module, used to query and set mouse cursor related properties.

  • The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import { pointer } from '@kit.InputKit';
import { BusinessError } from '@kit.BasicServicesKit';

pointer.setPointerVisible

setPointerVisible(visible: boolean, callback: AsyncCallback<void>): void

Sets the cursor visibility state, which applies to all windows of the current process. The actual display/hidden effect of the cursor on the screen is also affected by the rendering service process. This API uses an asynchronous callback.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Parameters

Name Type Mandatory Description
visible boolean Yes Whether the mouse pointer is visible in the current window. The value true indicates that the mouse pointer is visible, and the value false indicates the opposite.
callback AsyncCallback<void> Yes Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801

Capability not supported.

Applicable version: 18+

Example

import { pointer } from '@kit.InputKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          try {
            // Setting Mouse Pointer Visibility
            pointer.setPointerVisible(true, (error: BusinessError) => {
              if (error) {
                console.error(`Failed to set pointer cursor visible, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
                return;
              }
              console.info(`Succeeded in setting pointer cursor visible.`);
            });
          } catch (error) {
            console.error(`Failed to set pointer cursor visible, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
          }
        });
    }
  }
}

pointer.setPointerVisible

setPointerVisible(visible: boolean): Promise<void>

Sets the cursor visibility state, which applies to all windows of the current process. The actual display/hidden effect of the cursor on the screen is also affected by the rendering service process. This API uses a promise to return the result asynchronously.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Parameters

Name Type Mandatory Description
visible boolean Yes Whether the mouse pointer is visible in the current window. The value true indicates that the mouse pointer is visible, and the value false indicates the opposite.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
801

Capability not supported.

Applicable version: 18+

Example

import { pointer } from '@kit.InputKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          try {
            // Setting Mouse Pointer Visibility
            pointer.setPointerVisible(false).then(() => {
              console.info(`Succeeded in setting pointer cursor visible.`);
            }).catch((error: BusinessError) => {
              console.error(`Failed to set pointer cursor, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
            })
          } catch (error) {
            console.error(`Failed to set pointer cursor, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
          }
        })
    }
  }
}

pointer.setPointerVisibleSync10+

setPointerVisibleSync(visible: boolean): void

Sets the cursor visibility state, which applies to all windows of the current process. The actual display/hidden effect of the cursor on the screen is also affected by the rendering service process. This API is called synchronously.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Parameters

Name Type Mandatory Description
visible boolean Yes Whether the mouse pointer is visible in the current window. The value true indicates that the mouse pointer is visible, and the value false indicates the opposite.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { pointer } from '@kit.InputKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          try {
            // Synchronously sets the visibility of the mouse pointer
            pointer.setPointerVisibleSync(false);
            console.info(`Succeeded in setting pointer cursor visible.`);
          } catch (error) {
            console.error(`Failed to set pointer cursor visible, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
          }
        })
    }
  }
}

pointer.isPointerVisible

isPointerVisible(callback: AsyncCallback<boolean>): void

Obtains the display/hidden state of the current window. This state reflects the cursor display/hidden state set by the multimodal process for the process where this window resides, rather than the real cursor display/hidden situation. Whether the cursor is correctly displayed or hidden is also affected by the rendering service process. This API uses an asynchronous callback.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Parameters

Name Type Mandatory Description
callback AsyncCallback<boolean> Yes Callback used to return the result. If the operation is successful, err is undefined, and data is the visible status of the mouse pointer (true if visible and false if invisible). Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { pointer } from '@kit.InputKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          try {
            // Checks whether the mouse pointer is visible
            pointer.isPointerVisible((error: BusinessError, visible: boolean) => {
              if (error) {
                console.error(`Failed to get pointer visible, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
                return;
              }
              console.info(`Succeeded in getting pointer visible, visible: ${JSON.stringify(visible)}.`);
            });
          } catch (error) {
            console.error(`Failed to get pointer visible, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
          }
        })
    }
  }
}

pointer.isPointerVisible

isPointerVisible(): Promise<boolean>

Obtains the display/hidden state of the current window. This state reflects the cursor display/hidden state set by the multimodal process for the process where this window resides, rather than the real cursor display/hidden situation. Whether the cursor is correctly displayed or hidden is also affected by the rendering service process. This API uses a promise to return the result asynchronously.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Return value

Type Description
Promise<boolean> Promise used to return the result. true is returned if the mouse pointer is visible; false is returned if the mouse pointer is hidden.

Example

import { pointer } from '@kit.InputKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          try {
            // Checks whether the mouse pointer is visible
            pointer.isPointerVisible().then((visible: boolean) => {
              console.info(`Succeeded in getting pointer visible, visible: ${JSON.stringify(visible)}.`);
            }).catch((error: BusinessError) => {
              console.error(`Failed to get pointer, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
            })
          } catch (error) {
            console.error(`Failed to get pointer visible, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
          }
        })
    }
  }
}

pointer.isPointerVisibleSync10+

isPointerVisibleSync(): boolean

Obtains the display/hidden state of the current window. This state reflects the cursor display/hidden state set by the multimodal process for the process where this window resides, rather than the real cursor display/hidden situation. Whether the cursor is correctly displayed or hidden is also affected by the rendering service process. This API is called synchronously.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Return value

Type Description
boolean Visible status of the mouse pointer. The value true indicates that the mouse pointer is visible, and the value false indicates the opposite.

Example

import { pointer } from '@kit.InputKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          try {
            let visible: boolean = pointer.isPointerVisibleSync();
            console.info(`Succeeded in getting pointer visible, visible: ${JSON.stringify(visible)}.`);
          } catch (error) {
            console.error(`Failed to get pointer visible, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
          }
        })
    }
  }
}

pointer.getPointerStyle

getPointerStyle(windowId: number, callback: AsyncCallback<PointerStyle>): void

Obtains the mouse pointer style type of a specified window. This API can obtain only the mouse pointer style type of windows within the current application process. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Parameters

Name Type Mandatory Description
windowId number Yes

Window ID. The value is an integer greater than or equal to -1. The value -1 indicates the global window.

If the window ID is valid and the corresponding window exists, the mouse pointer style of the window is returned.

If the window ID is valid but the window does not exist, the global mouse pointer style is returned by default.

If the mouse pointer style is set for a non-existent window through setPointerStyle, this API can obtain the mouse pointer style properly.
callback AsyncCallback<PointerStyle> Yes Callback used to return the result. If the operation is successful, err is undefined, and data is the mouse pointer style type. Otherwise, err is an error object. In specific scenarios (obtaining the style on a window with a custom pointer style), DEVELOPER_DEFINED_ICON is returned.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { pointer } from '@kit.InputKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          // Obtains the most recent window in the application.
          window.getLastWindow(this.getUIContext().getHostContext(), (error: BusinessError, win: window.Window) => {
            if (error) {
              console.error(`Failed to obtain the top window, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
              return;
            }
            let windowId = win.getWindowProperties().id;
            if (windowId < 0) {
              console.info(`Invalid windowId.`);
              return;
            }
            try {
              // Obtains the mouse pointer style.
              pointer.getPointerStyle(windowId, (error: BusinessError, style: pointer.PointerStyle) => {
                if (error) {
                  console.error(`Failed to get pointer style, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
                  return;
                }
                console.info(`Succeeded in getting pointer style, style: ${JSON.stringify(style)}.`);
              });
            } catch (error) {
              console.error(`Failed to get pointer style, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
            }
          });
        })
    }
  }
}

pointer.getPointerStyle

getPointerStyle(windowId: number): Promise<PointerStyle>

Obtains the mouse pointer style type. This API can obtain only the mouse pointer style type of windows within the current application process. This API uses a promise to return the result.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Parameters

Name Type Mandatory Description
windowId number Yes

Window ID. The value is an integer greater than or equal to -1. The value -1 indicates the global window.

If the window ID is valid and the corresponding window exists, the mouse pointer style of the window is returned.

If the window ID is valid but the window does not exist, the global mouse pointer style is returned by default.

If the mouse pointer style is set for a non-existent window through setPointerStyle, this API can obtain the mouse pointer style properly.

Return value

Type Description
Promise<PointerStyle> Promise object, which is used to return the mouse pointer style.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { pointer } from '@kit.InputKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          // Obtains the most recent window in the application.
          window.getLastWindow(this.getUIContext().getHostContext(), (error: BusinessError, win: window.Window) => {
            if (error.code) {
              console.error(`Failed to obtain the top window, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
              return;
            }
            let windowId = win.getWindowProperties().id;
            if (windowId < 0) {
              console.info(`Invalid windowId.`);
              return;
            }
            try {
              // Obtains the mouse pointer style.
              pointer.getPointerStyle(windowId).then((style: pointer.PointerStyle) => {
                console.info(`Succeeded in getting pointer style, style: ${JSON.stringify(style)}.`);
              }).catch((error: BusinessError) => {
                console.error(`Failed to get pointer style, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
              });
            } catch (error) {
              console.error(`Failed to get pointer style, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
            }
          });
        })
    }
  }
}

pointer.getPointerStyleSync10+

getPointerStyleSync(windowId: number): PointerStyle

Queries the mouse pointer style type of a specified window, such as east arrow, west arrow, south arrow, and north arrow. This API can obtain only the mouse pointer style type of windows within the current application process.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Parameters

Name Type Mandatory Description
windowId number Yes

Window ID. The value is an integer greater than or equal to -1. The value -1 indicates the global window.

If the window ID is valid and the corresponding window exists, the mouse pointer style of the window is returned.

If the window ID is valid but the window does not exist, the global mouse pointer style is returned by default.

If the mouse pointer style is set for a non-existent window through setPointerStyleSync, this API can obtain the mouse pointer style properly.

Return value

Type Description
PointerStyle Mouse pointer style.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { pointer } from '@kit.InputKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          let windowId = -1;
          try {
            let style: pointer.PointerStyle = pointer.getPointerStyleSync(windowId);
            console.info(`Succeeded in getting pointer style, style: ${JSON.stringify(style)}.`);
          } catch (error) {
            console.error(`Failed to get pointer style, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
          }
        })
    }
  }
}

pointer.setPointerStyle

setPointerStyle(windowId: number, pointerStyle: PointerStyle, callback: AsyncCallback<void>): void

Sets the mouse pointer style type for a specified window. This API can set only the mouse pointer style type of windows within the current application process. For details about how to set the mouse pointer style type of the host window through the UIExtensionAbility process, see setCursor. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Parameters

Name Type Mandatory Description
windowId number Yes

Window ID. The value is an integer greater than or equal to 0.

If the window ID is valid and the corresponding window exists, the mouse pointer style of the window can be set properly.

If the window ID is valid but the window does not exist, the mouse pointer style can also be set properly.

The result can be obtained through getPointerStyle.
pointerStyle PointerStyle Yes Pointer style. Do not pass DEVELOPER_DEFINED_ICON.
callback AsyncCallback<void> Yes Callback used to return the result. If the operation is successful, err is undefined. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { pointer } from '@kit.InputKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          // Obtains the most recent window in the application.
          window.getLastWindow(this.getUIContext().getHostContext(), (error: BusinessError, win: window.Window) => {
            if (error.code) {
              console.error(`Failed to obtain the top window, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
              return;
            }
            let windowId = win.getWindowProperties().id;
            if (windowId < 0) {
              console.info(`Invalid windowId.`);
              return;
            }
            try {
              // Sets the mouse pointer style.
              pointer.setPointerStyle(windowId, pointer.PointerStyle.CROSS, error => {
                console.info(`Succeeded in setting pointer style.`);
              });
            } catch (error) {
              console.error(`Failed to set pointer style, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
            }
          });
        })
    }
  }
}

pointer.setPointerStyle

setPointerStyle(windowId: number, pointerStyle: PointerStyle): Promise<void>

Sets the mouse pointer style type for a specified window. This API can set only the mouse pointer style type of windows within the current application process. For details about how to set the mouse pointer style type of the host window through the UIExtensionAbility process, see setCursor. This uses a promise to return the result.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Parameters

Name Type Mandatory Description
windowId number Yes

Window ID. The value is an integer greater than or equal to 0.

If the window ID is valid and the corresponding window exists, the mouse pointer style of the window can be set properly.

If the window ID is valid but the window does not exist, the mouse pointer style can also be set properly.

The result can be obtained through getPointerStyle.
pointerStyle PointerStyle Yes Pointer style. DEVELOPER_DEFINED_ICON cannot be passed as a parameter.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { pointer } from '@kit.InputKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          // Obtains the most recent window in the application.
          window.getLastWindow(this.getUIContext().getHostContext(), (error: BusinessError, win: window.Window) => {
            if (error.code) {
              console.error(`Failed to obtain the top window, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
              return;
            }
            let windowId = win.getWindowProperties().id;
            if (windowId < 0) {
              console.info(`Invalid windowId.`);
              return;
            }
            try {
              // Sets the mouse pointer style.
              pointer.setPointerStyle(windowId, pointer.PointerStyle.CROSS).then(() => {
                console.info(`Succeeded in setting pointer style.`);
              }).catch((error: BusinessError) => {
                console.error(`Failed to set pointer style, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
              });
            } catch (error) {
              console.error(`Failed to set pointer style, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
            }
          });
        })
    }
  }
}

pointer.setPointerStyleSync10+

setPointerStyleSync(windowId: number, pointerStyle: PointerStyle): void

Sets the mouse pointer style type for a specified window and returns the result synchronously. This API can set only the mouse pointer style type of windows within the current application process. For details about how to set the mouse pointer style type of the host window through the UIExtensionAbility process, see setCursor.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Parameters

Name Type Mandatory Description
windowId number Yes

Window ID. The value is an integer greater than or equal to 0.

If the window ID is valid and the corresponding window exists, the mouse pointer style of the window can be set properly.

If the window ID is valid but the window does not exist, the mouse pointer style can also be set properly.

The result can be obtained through getPointerStyleSync.
pointerStyle PointerStyle Yes Pointer style. DEVELOPER_DEFINED_ICON cannot be passed in as a parameter.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { pointer } from '@kit.InputKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          // Obtains the most recent window within the application.
          window.getLastWindow(this.getUIContext().getHostContext(), (error: BusinessError, win: window.Window) => {
            if (error.code) {
              console.error(`Failed to obtain the top window, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
              return;
            }
            let windowId = win.getWindowProperties().id;
            if (windowId < 0) {
              console.info(`Invalid windowId.`);
              return;
            }
            try {
              // Synchronously sets the mouse pointer style.
              pointer.setPointerStyleSync(windowId, pointer.PointerStyle.CROSS);
              console.info(`Succeeded in setting pointer style.`);
            } catch (error) {
              console.error(`Failed to set pointer style, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
            }
          });
        })
    }
  }
}

PrimaryButton10+

Type of the primary mouse button.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Name Value Description
LEFT 0 Left button.
RIGHT 1 Right button.

RightClickType10+

Enumerates shortcut menu triggering modes.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Name Value Description
TOUCHPAD_RIGHT_BUTTON 1 Tapping the right-button area of the touchpad.
TOUCHPAD_LEFT_BUTTON 2 Tapping the left-button area of the touchpad.
TOUCHPAD_TWO_FINGER_TAP 3 Tapping or pressing the touchpad with two fingers.
TOUCHPAD_TWO_FINGER_TAP_OR_RIGHT_BUTTON20+ 4 Tapping or pressing the touchpad with two fingers, or tapping the right-button area of the touchpad.
TOUCHPAD_TWO_FINGER_TAP_OR_LEFT_BUTTON20+ 5 Tapping or pressing the touchpad with two fingers, or tapping the left-button area of the touchpad.

PointerStyle

Mouse pointer style types.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Name Value Description Legend
DEFAULT 0 Default
EAST 1 East arrow
WEST 2 West arrow
SOUTH 3 South arrow
NORTH 4 North arrow
WEST_EAST 5 West-east arrow
NORTH_SOUTH 6 North-south arrow
NORTH_EAST 7 North-east arrow
NORTH_WEST 8 North-west arrow
SOUTH_EAST 9 South-east arrow
SOUTH_WEST 10 South-west arrow
NORTH_EAST_SOUTH_WEST 11 North-east and south-west adjustment
NORTH_WEST_SOUTH_EAST 12 North-west and south-east adjustment
CROSS 13 Cross (accurate selection)
CURSOR_COPY 14 Copy
CURSOR_FORBID 15 Forbid
COLOR_SUCKER 16 Color picker
HAND_GRABBING 17 Grabbing hand
HAND_OPEN 18 Opening hand
HAND_POINTING 19 Hand pointer.
HELP 20 Help
MOVE 21 Move
RESIZE_LEFT_RIGHT 22 Left and right resizing
RESIZE_UP_DOWN 23 Up and down resizing
SCREENSHOT_CHOOSE 24 Screenshot crosshair
SCREENSHOT_CURSOR 25 Screenshot
TEXT_CURSOR 26 Text selection
ZOOM_IN 27 Zoom in
ZOOM_OUT 28 Zoom out
MIDDLE_BTN_EAST 29 Scrolling east
MIDDLE_BTN_WEST 30 Scrolling west
MIDDLE_BTN_SOUTH 31 Scrolling south
MIDDLE_BTN_NORTH 32 Scrolling north
MIDDLE_BTN_NORTH_SOUTH 33 Scrolling north-south
MIDDLE_BTN_NORTH_EAST 34 Scrolling north-east
MIDDLE_BTN_NORTH_WEST 35 Scrolling north-west
MIDDLE_BTN_SOUTH_EAST 36 Scrolling south-east
MIDDLE_BTN_SOUTH_WEST 37 Scrolling south-west
MIDDLE_BTN_NORTH_SOUTH_WEST_EAST 38 Moving as a cone in four directions
HORIZONTAL_TEXT_CURSOR10+ 39 Horizontal text selection.
CURSOR_CROSS10+ 40 Cross
CURSOR_CIRCLE10+ 41 Circle
LOADING10+ 42

Animation loading

Atomic service API: This API can be used in atomic services since API version 12.
RUNNING10+ 43

Animation running in the background

Atomic service API: This API can be used in atomic services since API version 12.
MIDDLE_BTN_EAST_WEST18+ 44 Scrolling east-west
RUNNING_LEFT22+ 45 Animated cursor for background running (extension 1).
RUNNING_RIGHT22+ 46 Animated cursor for background running (extension 2).
AECH_DEVELOPER_DEFINED_ICON22+ 47 Custom circular pointer
SCREENRECORDER_CURSOR20+ 48 Screen recording
LASER_CURSOR22+ 49

Floating cursor. This cursor is used when the stylus enters air mouse mode and cannot be set directly.

In air mouse mode, the stylus can be rotated in the air to control the movement of the virtual cursor on the screen, and the buttons on the stylus body can be used to page up and down. This mode is used in scenarios such as PPT presentations and air operations.
LASER_CURSOR_DOT22+ 50

Click cursor. This cursor is used when the stylus enters air mouse mode and cannot be set directly.

In air mouse mode, the stylus can be rotated in the air to control the movement of the virtual cursor on the screen, and the buttons on the stylus body can be used to page up and down. This mode is used in scenarios such as PPT presentations and air operations.
LASER_CURSOR_DOT_RED22+ 51

Laser pointer cursor. This cursor is used when the stylus enters air mouse mode and cannot be set directly.

In air mouse mode, the stylus can be rotated in the air to control the movement of the virtual cursor on the screen, and the buttons on the stylus body can be used to page up and down. This mode is used in scenarios such as PPT presentations and air operations.
DEVELOPER_DEFINED_ICON22+ -100 Custom pointer. You can use setCustomCursor to set a custom pointer. The custom pointer cannot be directly set using setPointerStyle. Custom pointer style, set via the API. This value is used by getPointerStyle to return data in specific scenarios (obtaining the style on a window where a custom pointer style has been set). It cannot be used as an input parameter of the setCustomCursor or setPointerStyle API.

pointer.setCustomCursor11+

setCustomCursor(windowId: number, pixelMap: image.PixelMap, focusX?: number, focusY?: number): Promise<void>

Sets a custom pointer style for a specified window. This API can set only the custom pointer style of windows within the current application process. For details about how to set the custom pointer style of the host window through the UIExtensionAbility process, see setCustomCursor. This API uses a promise to return the result.

In the following scenarios, the cursor may switch back to the system style, and developers need to set the cursor style again: the application window layout changes, the hot zone switches, the page navigates, the cursor moves out of and back into the window, or the cursor moves across different areas of the window.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Parameters

Name Type Mandatory Description
windowId number Yes Window ID. The value is an integer greater than 0.
pixelMap image.PixelMap Yes Custom cursor resource.
focusX number No Custom cursor focus X, in px. The value must be greater than or equal to 0. The default value is 0.
focusY number No Custom cursor focus Y, in px. The value must be greater than or equal to 0. The default value is 0.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { pointer } from '@kit.InputKit';
import { image } from '@kit.ImageKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          // app_icon is an example resource. Configure the resource file based on the actual requirements.
          this.getUIContext()?.getHostContext()?.resourceManager.getMediaContent(
            $r('app.media.app_icon').id, (error: BusinessError, svgFileData: Uint8Array) => {
            const svgBuffer: ArrayBuffer = svgFileData.buffer.slice(0);
            let svgImageSource: image.ImageSource = image.createImageSource(svgBuffer);
            let svgDecodingOptions: image.DecodingOptions = { desiredSize: { width: 50, height: 50 } };
            // Create a PixelMap
            svgImageSource.createPixelMap(svgDecodingOptions).then((pixelMap) => {
              window.getLastWindow(this.getUIContext().getHostContext(), (error: BusinessError, win: window.Window) => {
                let windowId = win.getWindowProperties().id;
                try {
                  pointer.setCustomCursor(windowId, pixelMap).then(() => {
                    console.info(`Succeeded in setting custom cursor.`);
                  });
                } catch (error) {
                  console.error(`Failed to set custom cursor, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
                }
              });
            }).catch((error: BusinessError) => {
                console.error(`Failed to create pixel map promise, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
              });
          });
        })
    }
  }
}

CustomCursor15+

Defines custom cursor resources.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Name Type Read-Only Optional Description
pixelMap image.PixelMap No No Pixel map. The minimum size is subject to the minimum limit of the image. The maximum size is 256 x 256 px.
focusX number No Yes Horizontal coordinate of the custom pointer focus, in px. This coordinate is limited by the custom pointer size. The minimum value is 0, and the maximum value is the maximum width of the resource image. The default value is 0 when this parameter is omitted.
focusY number No Yes Vertical coordinate of the custom pointer focus, in px. This coordinate is limited by the custom pointer size. The minimum value is 0, and the maximum value is the maximum width of the resource image. The default value is 0 when this parameter is omitted.

CursorConfig15+

Defines custom cursor configuration.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Name Type Read-Only Optional Description
followSystem boolean No No Whether to adjust the cursor size based on system settings. The value false means to use the custom cursor style size, and true means to adjust the cursor size based on system settings. The adjustable range is [cursor resource image size, 256×256].

pointer.setCustomCursor15+

setCustomCursor(windowId: number, cursor: CustomCursor, config: CursorConfig): Promise<void>

Sets a custom pointer style for a specified window. This API can set only the custom pointer style of windows within the current application process. For details about how to set the custom pointer style of the host window through the UIExtensionAbility process, see setCustomCursor. This API uses a promise to return the result.

The cursor may be switched back to the system style in the following cases: application window layout change, hot zone switching, page redirection, moving of the cursor out of the window and then back to the window, or moving of the cursor in different areas of the window. In this case, you need to reset the cursor style.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Parameters

Name Type Mandatory Description
windowId number Yes Window ID. The value is an integer greater than 0.
cursor CustomCursor Yes Custom cursor resource.
config CursorConfig Yes Custom cursor configuration, used to configure whether to adjust the cursor size based on system settings. If followSystem in CursorConfig is set to true, the adjustable range of the cursor size is [cursor resource image size, 256×256].

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Mouse Pointer Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Abnormal windowId parameter passed in. 2. Abnormal pixelMap parameter passed in; 3. Abnormal focusX parameter passed in.4. Abnormal focusY parameter passed in.
26500001 Invalid windowId. Possible causes: The window id does not belong to the current process.

Example

import { pointer } from '@kit.InputKit';
import { image } from '@kit.ImageKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          // app_icon is an example resource. Configure the resource file based on the actual requirements.
          this.getUIContext()?.getHostContext()?.resourceManager.getMediaContent(
            $r('app.media.app_icon').id, (error: BusinessError, svgFileData: Uint8Array) => {
            const svgBuffer: ArrayBuffer = svgFileData.buffer.slice(0);
            let svgImageSource: image.ImageSource = image.createImageSource(svgBuffer);
            let svgDecodingOptions: image.DecodingOptions = { desiredSize: { width: 50, height: 50 } };
            // Create a PixelMap
            svgImageSource.createPixelMap(svgDecodingOptions).then((pixelMap) => {
              // Get the most recent window within the application
              window.getLastWindow(this.getUIContext().getHostContext(), (error: BusinessError, win: window.Window) => {
                let windowId = win.getWindowProperties().id;
                try {
                  // Set a custom pointer
                  pointer.setCustomCursor(windowId, { pixelMap: pixelMap, focusX: 25, focusY: 25 },
                    { followSystem: false }).then(() => {
                    console.info(`Succeeded in setting custom cursor.`);
                  });
                } catch (error) {
                  console.error(`Failed to set custom cursor, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
                }
              });
            }).catch((error: BusinessError) => {
                console.error(`Failed to create pixel map promise, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
              });
          });
        })
    }
  }
}

pointer.setCustomCursorSync11+

setCustomCursorSync(windowId: number, pixelMap: image.PixelMap, focusX?: number, focusY?: number): void

Sets a custom pointer style for a specified window synchronously. This API can set only the custom pointer style of windows within the current application process. For details about how to set the custom pointer style of the host window through the UIExtensionAbility process, see setCustomCursor.

In the following scenarios, the cursor may switch back to the system style, and developers need to set the cursor style again: the application window layout changes, the hot zone switches, the page navigates, the cursor moves out of and back into the window, or the cursor moves across different areas of the window.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Parameters

Name Type Mandatory Description
windowId number Yes Window ID. The value must be an integer greater than 0.
pixelMap image.PixelMap Yes Custom cursor resource.
focusX number No Custom pointer focus X, in px. The value must be greater than or equal to 0. The default value is 0.
focusY number No Custom pointer focus Y, in px. The value must be greater than or equal to 0. The default value is 0.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

Example

import { pointer } from '@kit.InputKit';
import { image } from '@kit.ImageKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          // app_icon is an example resource. Configure the resource file based on the actual requirements.
          this.getUIContext()?.getHostContext()?.resourceManager.getMediaContent(
            $r('app.media.app_icon').id, (error: BusinessError, svgFileData: Uint8Array) => {
            const svgBuffer = svgFileData.buffer;
            let svgImageSource: image.ImageSource = image.createImageSource(svgBuffer);
            // Width and height of the pointer image
            let svgDecodingOptions: image.DecodingOptions = { desiredSize: { width: 50, height: 50 } };
            // Create a PixelMap
            svgImageSource.createPixelMap(svgDecodingOptions).then((pixelMap) => {
              // Get the most recent window in the application
              window.getLastWindow(this.getUIContext().getHostContext(), (error: BusinessError, win: window.Window) => {
                let windowId = win.getWindowProperties().id;
                try {
                  // Set a custom pointer synchronously
                  pointer.setCustomCursorSync(windowId, pixelMap, 25, 25);
                  console.info(`Succeeded in setting custom cursor sync.`);
                } catch (error) {
                  console.error(`Failed to set custom cursor sync, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
                }
              });
            }).catch((error: BusinessError) => {
              console.error(`Failed to create pixel map promise, Code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}.`);
            });
          });
        }
      )
    }
  }
}