Hhutingting_02040205翻译回稿：mdm audio input等等kit

@ohos.multimodalInput.pointer (Mouse Pointer)

The pointer module provides APIs related to pointer attribute management, such as querying and setting pointer attributes.

NOTE

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';

pointer.setPointerVisible

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

Sets whether the mouse pointer is visible in the current window. This API uses an asynchronous callback to return the result.

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.

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.

Example

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

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          try {
            pointer.setPointerVisible(true, (error: BusinessError) => {
              if (error) {
                console.error(`Set pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
                return;
              }
              console.info(`Set pointer visible success`);
            });
          } catch (error) {
            console.error(`Set pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
          }
        })
    }
  }
}

pointer.setPointerVisible

setPointerVisible(visible: boolean): Promise<void>

Sets whether the mouse pointer is visible in the current window. This API uses a promise to return the result.

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.

Example

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

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          try {
            pointer.setPointerVisible(false).then(() => {
              console.info(`Set pointer visible success`);
            }).catch((error: BusinessError) => {
              console.error(`Set pointer failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
            })
          } catch (error) {
            console.error(`Set pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
          }
        })
    }
  }
}

pointer.setPointerVisibleSync¹⁰⁺

setPointerVisibleSync(visible: boolean): void

Sets whether the mouse pointer is visible in the current window. This API returns the result 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';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          try {
            pointer.setPointerVisibleSync(false);
            console.info(`Set pointer visible success`);
          } catch (error) {
            console.error(`Set pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
          }
        })
    }
  }
}

pointer.isPointerVisible

isPointerVisible(callback: AsyncCallback<boolean>): void

Obtains the visible status of the mouse pointer. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<boolean>	Yes	Callback used to return the result. 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 {
            pointer.isPointerVisible((error: BusinessError, visible: boolean) => {
              if (error) {
                console.error(`Get pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
                return;
              }
              console.info(`Get pointer visible success, visible: ${JSON.stringify(visible)}`);
            });
          } catch (error) {
            console.error(`Get pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
          }
        })
    }
  }
}

pointer.isPointerVisible

isPointerVisible(): Promise<boolean>

Obtains the visible status of the mouse pointer. This API uses a promise to return the result.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Return value

Type	Description
Promise<boolean>	Promise used to return the 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 {
            pointer.isPointerVisible().then((visible: boolean) => {
              console.info(`Get pointer visible success, visible: ${JSON.stringify(visible)}`);
            }).catch((error: BusinessError) => {
              console.error(`Get pointer failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
            })
          } catch (error) {
            console.error(`Get pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
          }
        })
    }
  }
}

pointer.isPointerVisibleSync¹⁰⁺

isPointerVisibleSync(): boolean

Checks whether the mouse pointer is visible in the current window. This API returns the result 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';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          try {
            let visible: boolean = pointer.isPointerVisibleSync();
            console.info(`Get pointer visible success, visible: ${JSON.stringify(visible)}`);
          } catch (error) {
            console.error(`Get pointer visible failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
          }
        })
    }
  }
}

pointer.getPointerStyle

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

Obtains the mouse pointer style of the specified window. 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 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(() => {
          window.getLastWindow(this.getUIContext().getHostContext(), (error: BusinessError, win: window.Window) => {
            if (error.code) {
              console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(error));
              return;
            }
            let windowId = win.getWindowProperties().id;
            if (windowId < 0) {
              console.info(`Invalid windowId`);
              return;
            }
            try {
              pointer.getPointerStyle(windowId, (error: BusinessError, style: pointer.PointerStyle) => {
                console.info(`Get pointer style success, style: ${JSON.stringify(style)}`);
              });
            } catch (error) {
              console.error(`Get pointer style failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
            }
          });
        })
    }
  }
}

pointer.getPointerStyle

getPointerStyle(windowId: number): Promise<PointerStyle>

Obtains the mouse pointer style. 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(() => {
          window.getLastWindow(this.getUIContext().getHostContext(), (error: BusinessError, win: window.Window) => {
            if (error.code) {
              console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(error));
              return;
            }
            let windowId = win.getWindowProperties().id;
            if (windowId < 0) {
              console.info(`Invalid windowId`);
              return;
            }
            try {
              pointer.getPointerStyle(windowId).then((style: pointer.PointerStyle) => {
                console.info(`Get pointer style success, style: ${JSON.stringify(style)}`);
              }).catch((error: BusinessError) => {
                console.error(`Get pointer style failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
              });
            } catch (error) {
              console.error(`Get pointer style failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
            }
          });
        })
    }
  }
}

pointer.getPointerStyleSync¹⁰⁺

getPointerStyleSync(windowId: number): PointerStyle

Obtains the mouse pointer style, such as the east arrow, west arrow, south arrow, and north arrow, of the specified window. This API returns the result synchronously.

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';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Text()
        .onClick(() => {
          let windowId = -1;
          try {
            let style: pointer.PointerStyle = pointer.getPointerStyleSync(windowId);
            console.info(`Get pointer style success, style: ${JSON.stringify(style)}`);
          } catch (error) {
            console.error(`Get pointer style failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
          }
        })
    }
  }
}

pointer.setPointerStyle

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

Sets the mouse pointer style of the specified window. 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.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

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(() => {
          window.getLastWindow(this.getUIContext().getHostContext(), (error: BusinessError, win: window.Window) => {
            if (error.code) {
              console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(error));
              return;
            }
            let windowId = win.getWindowProperties().id;
            if (windowId < 0) {
              console.info(`Invalid windowId`);
              return;
            }
            try {
              pointer.setPointerStyle(windowId, pointer.PointerStyle.CROSS, error => {
                console.info(`Set pointer style success`);
              });
            } catch (error) {
              console.error(`Set pointer style failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
            }
          });
        })
    }
  }
}

pointer.setPointerStyle

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

Sets the mouse pointer style of the specified window. 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 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.

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(() => {
          window.getLastWindow(this.getUIContext().getHostContext(), (error: BusinessError, win: window.Window) => {
            if (error.code) {
              console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(error));
              return;
            }
            let windowId = win.getWindowProperties().id;
            if (windowId < 0) {
              console.info(`Invalid windowId`);
              return;
            }
            try {
              pointer.setPointerStyle(windowId, pointer.PointerStyle.CROSS).then(() => {
                console.info(`Set pointer style success`);
              }).catch((error: BusinessError) => {
               console.error(`Set pointer style failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
              });
            } catch (error) {
              console.error(`Set pointer style failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
            }
          });
        })
    }
  }
}

pointer.setPointerStyleSync¹⁰⁺

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

Sets the mouse pointer style of the specified window. This API returns the result synchronously.

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.

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(() => {
          window.getLastWindow(this.getUIContext().getHostContext(), (error: BusinessError, win: window.Window) => {
            if (error.code) {
              console.error('Failed to obtain the top window. Cause: ' + JSON.stringify(error));
              return;
            }
            let windowId = win.getWindowProperties().id;
            if (windowId < 0) {
              console.info(`Invalid windowId`);
              return;
            }
            try {
              pointer.setPointerStyleSync(windowId, pointer.PointerStyle.CROSS);
              console.info(`Set pointer style success`);
            } catch (error) {
              console.error(`getPointerSize failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
            }
          });
        })
    }
  }
}

PrimaryButton¹⁰⁺

Type of the primary mouse button.

System capability: SystemCapability.MultimodalInput.Input.Pointer

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

RightClickType¹⁰⁺

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_BUTTON²⁰⁺	4	Tapping or pressing the touchpad with two fingers, or tapping the right-button area of the touchpad.
TOUCHPAD_TWO_FINGER_TAP_OR_LEFT_BUTTON²⁰⁺	5	Tapping or pressing the touchpad with two fingers, or tapping the left-button area of the touchpad.

PointerStyle

Mouse pointer style.

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-shaped 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_CURSOR¹⁰⁺	39	Horizontal text selection
CURSOR_CROSS¹⁰⁺	40	Cross
CURSOR_CIRCLE¹⁰⁺	41	Circle
LOADING¹⁰⁺	42	Animation loading Atomic service API: This API can be used in atomic services since API version 12.
RUNNING¹⁰⁺	43	Animation running in the background Atomic service API: This API can be used in atomic services since API version 12.
MIDDLE_BTN_EAST_WEST¹⁸⁺	44	Scrolling east-west
RUNNING_LEFT²²⁺	45	Running in the background (extension 1)
RUNNING_RIGHT²²⁺	46	Running in the background (extension 2)
AECH_DEVELOPER_DEFINED_ICON²²⁺	47	Custom circular pointer
SCREENRECORDER_CURSOR²⁰⁺	48	Screen recording
LASER_CURSOR²²⁺	49	Floating This pointer can be used only when the stylus enters the air mouse mode and cannot be directly set. In air mouse mode, you can rotate the stylus in the air to control the movement of the virtual pointer on the screen and press the button on the stylus to turn pages up or down. This mode is used PPT presentation and air gesture control.
LASER_CURSOR_DOT²²⁺	50	Click This pointer can be used only when the stylus enters the air mouse mode and cannot be directly set. In air mouse mode, you can rotate the stylus in the air to control the movement of the virtual pointer on the screen and press the button on the stylus to turn pages up or down. This mode is used PPT presentation and air gesture control.
LASER_CURSOR_DOT_RED²²⁺	51	Laser pointer This pointer can be used only when the stylus enters the air mouse mode and cannot be directly set. In air mouse mode, you can rotate the stylus in the air to control the movement of the virtual pointer on the screen and press the button on the stylus to turn pages up or down. This mode is used PPT presentation and air gesture control.
DEVELOPER_DEFINED_ICON²²⁺	-100	Custom pointer. You can use the setCustomCursor to set a custom pointer, but not the setPointerStyle directly.	You can customize pointers as needed via API.

pointer.setCustomCursor¹¹⁺

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

Sets the custom cursor style of the specified window. This API uses a promise to return the result asynchronously.

System capability: SystemCapability.MultimodalInput.Input.Pointer

Parameters

Name	Type	Mandatory	Description
windowId	number	Yes	Window ID.
pixelMap	image.PixelMap	Yes	Custom cursor resource.
focusX	number	No	Focus x of the custom cursor. The value is greater than or equal to 0. The default value is 0.
focusY	number	No	Focus y of the custom cursor. The value is 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 } };
            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(`setCustomCursor success`);
                  });
                } catch (error) {
                  console.error(`setCustomCursor failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
                }
              });
            }).catch((error: BusinessError) => {
                console.error(`createPixelMap promise error: ${JSON.stringify(error, [`code`, `message`])}`);
              });
          });
        })
    }
  }
}

CustomCursor¹⁵⁺

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 cursor focus. The coordinates are restricted by the size of the custom cursor. The minimum value is 0, and the maximum value is the maximum width of the image. The default value is 0 if the parameter is left empty.
focusY	number	No	Yes	Vertical coordinate of the cursor focus. The coordinates are restricted by the size of the custom cursor. The minimum value is 0, and the maximum value is the maximum height of the image. The default value is 0 if the parameter is left empty.

CursorConfig¹⁵⁺

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 true means to adjust the cursor size based on system settings, and the value false means to use the custom cursor size. The adjustment range is [size of the cursor image, 256 x 256].

pointer.setCustomCursor¹⁵⁺

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

Sets the custom cursor style of the specified window. This API uses a promise to return the result asynchronously.

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.
cursor	CustomCursor	Yes	Custom cursor resource.
config	CursorConfig	Yes	Custom cursor configuration, which specifies whether to adjust the cursor size based on system settings. If followSystem in CursorConfig is set to true, the supported adjustment range is [size of the cursor image, 256 x 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 } };
            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: pixelMap, focusX: 25, focusY: 25 },
                    { followSystem: false }).then(() => {
                    console.info(`setCustomCursor success`);
                  });
                } catch (error) {
                  console.error(`setCustomCursor failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
                }
              });
            }).catch((error: BusinessError) => {
                console.error(`createPixelMap promise error: ${JSON.stringify(error, [`code`, `message`])}`);
              });
          });
        })
    }
  }
}

pointer.setCustomCursorSync¹¹⁺

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

Sets the custom mouse pointer style of the specified window. This API returns the result synchronously.

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	Focus x of the custom cursor. The value is greater than or equal to 0. The default value is 0.
focusY	number	No	Focus y of the custom cursor. The value is 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);
            let svgDecodingOptions: image.DecodingOptions = { desiredSize: { width: 50, height: 50 } };
            svgImageSource.createPixelMap(svgDecodingOptions).then((pixelMap) => {
              window.getLastWindow(this.getUIContext().getHostContext(), (error: BusinessError, win: window.Window) => {
                let windowId = win.getWindowProperties().id;
                try {
                  pointer.setCustomCursorSync(windowId, pixelMap, 25, 25);
                  console.info(`setCustomCursorSync success`);
                } catch (error) {
                  console.error(`setCustomCursorSync failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
                }
              });
            }).catch((error: BusinessError) => {
              console.error(`createPixelMap promise error: ${JSON.stringify(error, [`code`, `message`])}`);
            });
          });
        }
      )
    }
  }
}

@ohos.multimodalInput.pointer (Mouse Pointer)

Modules to Import

pointer.setPointerVisible

pointer.setPointerVisible

pointer.setPointerVisibleSync10+

pointer.isPointerVisible

pointer.isPointerVisible

pointer.isPointerVisibleSync10+

pointer.getPointerStyle

pointer.getPointerStyle

pointer.getPointerStyleSync10+

pointer.setPointerStyle

pointer.setPointerStyle

pointer.setPointerStyleSync10+

PrimaryButton10+

RightClickType10+

PointerStyle

pointer.setCustomCursor11+

CustomCursor15+

CursorConfig15+

pointer.setCustomCursor15+

pointer.setCustomCursorSync11+

pointer.setPointerVisibleSync¹⁰⁺

pointer.isPointerVisibleSync¹⁰⁺

pointer.getPointerStyleSync¹⁰⁺

pointer.setPointerStyleSync¹⁰⁺

PrimaryButton¹⁰⁺

RightClickType¹⁰⁺

pointer.setCustomCursor¹¹⁺

CustomCursor¹⁵⁺

CursorConfig¹⁵⁺

pointer.setCustomCursor¹⁵⁺

pointer.setCustomCursorSync¹¹⁺